本规范定义 STAROps 运维 Skill 的 7 要素，用于将 RDS 巡检、告警根因定位、日志模式分析等重复运维操作沉淀为可加载技能。
适用范围：
- 自研 Skill 的设计期评审标准
- 第三方 Skill 引入前的合规审查清单
- 适用类型：巡检类 / 诊断类 / 报告类 L0 只读 Skill
不适用：涉及写操作的 L2+ Skill（变更 / 删除 / 重启），需走风险分级与审批流程，不在本规范覆盖。
前提条件
- 已开通 STAROps 实例，账号有数字员工创建权限。
- 已识别可沉淀的运维场景（具备重复性、可结构化输出、动作只读）。
- 已确认 Skill 所需的数据源（SLS Project / Logstore / MetricStore / 拓扑等）均可访问。
- 已了解 STAROps Skill 与脚本的分工边界，倾向把数值计算交给脚本而非 LLM。
规范要素
合格的 STAROps Skill 必须包含 7 个要素：
| 要素 | 含义 | 是否必须 |
|---|---|---|
| 触发条件 | 用户如何触发这个 Skill，什么情况下不应触发 | 必须 |
| 流程设计 | Skill 的执行步骤序列，每步有输入 / 动作 / 输出 | 必须 |
| 计算与脚本 | 哪些数值计算必须脚本化，不依赖 LLM 推理 | 必须 |
| 输出与复用 | Skill 的最终输出格式和字段定义 | 必须 |
| 风险控制 | Skill 的风险等级和边界约束 | 必须 |
| 失败处理 | 每步失败时的处理方式 | 必须 |
| 推理边界 | LLM 可以做什么、不能做什么 | 必须 |
应用样例
样例 1：触发条件
| 项 | 内容 |
|---|---|
| 正例 | rds-inspection 的 description 段：「使用脚本批量执行阿里云 RDS 健康巡检，覆盖核心指标、性能、安全、关联日志四个维度，输出结构化巡检报告并附带原始采样与上下游影响。」并补充边界约束，明确划清不触发场景。 |
| 反例 | 触发条件只写「当用户需要帮助时」。Agent 无法区分「RDS 巡检」与「RDS 性能优化」「RDS 备份恢复」等相关任务，客户说「帮我查一下 RDS」可能路由到错误的 Skill 链路。 |
| 期望输出 | description 含 3 个要素：动作（巡检 / 诊断 / 报告）+ 对象（RDS / 容器 / 主机）+ 维度（核心 / 性能 / 安全）。边界约束写明「不执行任何变更操作」「不访问数据库执行 SQL」等不触发条件。 |
| 关键差异 | 正例 description 与边界约束共同划定触发与不触发场景，反例语义模糊导致路由错误。 |
样例 2：计算与脚本
| 项 | 内容 |
|---|---|
| 正例 | Python 脚本承载查询 + 阈值评估 + 持续时间累计。InspectionCase 声明： InspectionCase(threshold=80.0, duration=300, compare=CompareOp.GT) 公共引擎 evaluate() 与 calc_sustained_seconds() 算出连续超阈值秒数。 |
| 反例 | 让 LLM 从原始时间序列计算「CPU 使用率超过 80%，持续 5 分钟」。模型每次重新生成 Python 查询脚本，跨次结果可能因采样间隔误读、算法选择不同而不一致，且让 LLM 写脚本本身比执行脚本慢一个数量级，单次会话的延迟与 token 消耗都被显著推高。 |
| 期望输出 | 脚本输出结构化结果： {"case_id": "rds_cpu_high", "status": "find_problem", "duration_seconds": 360, "total_entities": 12, "abnormal_count": 1} |
| 关键差异 | 正例脚本完成数值计算，结果稳定可复现；反例 LLM 推理，跨次结果漂移且耗时高。 |
脚本的架构模式（数据驱动声明 + 公共引擎）、纯函数保证与确定性验证方式见 编写 Skill 确定性脚本。
样例 3：风险控制
| 项 | 内容 |
|---|---|
| 正例 | 声明 L0（只读），边界约束 4 条： ① 不执行任何变更操作（不改 RDS 配置、不执行 SQL、不重启实例） ② 不访问数据库执行 SQL（数据均经 SLS MetricStore / Logstore） ③ 不展示敏感信息（账号 / IP / 密码 / Token 自动脱敏，SQL 超过 100 字符截断） ④ 跨 workspace / region 复用（参数化 --region / --project / --metricstore） |
| 反例 | 声明 L0 但实际执行了 ALTER TABLE 或重启实例。客户基于 L0 声明跳过审批走自动化路径，事后追责无法定位变更动作来源。 |
| 期望输出 | Skill 调用面仅含只读接口（PromQL 查询、SLS 日志查询、拓扑查询），无任何写操作 API。 |
| 关键差异 | 正例风险等级与实际操作一致，反例高操作低声明可能导致生产事故。 |
样例 4：失败处理
| 项 | 内容 |
|---|---|
| 正例 | 单项失败返回 status=error 与可读 error 字段，不阻断其他项。降级规则：审计日志 Logstore 未传入时，日志脚本返回 error 并提示参数缺失；拓扑查询失败时，降级为空数组并记录 error，不阻断主流程。 |
| 正例输出 | {"case_id": "rds_slow_sql_high", "status": "error", "error": "audit-logstore param missing", "abnormal_count": 0}；其他巡检项继续返回 status=pass 或 find_problem。 |
| 反例 | 单步失败时中断整个 Skill，或直接返回 Python traceback 给客户。客户无法判断哪些巡检项成功、哪些失败，无法决定是否重试或人工兜底。 |
| 关键差异 | 正例快速失败与结构化错误，反例黑盒中断流程。 |
样例 5：推理边界
| 项 | 内容 |
|---|---|
| 正例 | 脚本与 LLM 分工： 脚本：PromQL 查询 / 日志查询 / 阈值评估 / 持续时间计算 / JSON 格式化 / 拓扑查询 LLM：解读 JSON 结果 / 把巡检项结果汇总成可读报告 / 给出修复建议 / 必要时与客户对话澄清范围 |
| 反例 | LLM 直接执行 SQL 或调用变更 API（如重启实例）。一旦 LLM 越界，等同于在 L0 声明下做了 L2+ 的操作，破坏分级管控。 |
| 期望输出 | Skill 的 SKILL.md 中明确写出脚本与 LLM 各自的「能做」「不能做」清单，并把不能做的项目列入「边界约束」段。 |
| 关键差异 | 正例分工写进 SKILL.md，反例无明文分工导致 LLM 越界。 |
样例 6：流程设计
| 项 | 内容 |
|---|---|
| 正例 | rds-inspection 的 6 步流程（SKILL.md「执行策略」段）： 1. 巡检前必须先列 todo list（明确维度与巡检项） 2. 优先用 scripts/ 下脚本批量执行（不手动逐条查询） 3. 四个脚本并行执行（核心 / 性能 / 安全 / 关联日志相互独立） 4. 汇总 JSON 输出（巡检项结果统一 schema） 5. 用 references/report-template.md 生成可读报告 6. 单项失败返回 status=error，不阻断其他项 |
| 反例 | Skill 只写「对 RDS 实例做巡检」，未声明步骤顺序与并行边界。每次执行步骤数、顺序、并行度都可能不同，跨次结果不可复现。 |
| 期望输出 | SKILL.md 含步骤编号清单 + 每步输入 / 动作 / 输出三段 + 并行块显式标注（如多脚本的 & 并行示例）。 |
| 关键差异 | 正例依赖关系显式，Agent 可稳定复现；反例隐式依赖导致同一输入跑出不同执行轨迹。 |
样例 7：输出与复用
| 项 | 内容 |
|---|---|
| 正例 | 顶层 schema 固定： {"total_cases": 21, "passed": 18, "find_problem_cases": 2, "no_problem_found": 0, "errors": 1, "has_find_problem": true, "results": [...]} 配套 references/report-template.md Markdown 报告模板；status 枚举 pass / find_problem / no_problem_found / error 跨执行稳定。 |
| 反例 | 同一 Skill 不同次执行有时返回 JSON、有时返回 Markdown、有时返回自然语言，字段名也跨次漂移。下游聚合或解析脚本会因字段缺失或键名变动直接报错，无法支撑跨次趋势对比与自动化分发。 |
| 期望输出 | 字段名与枚举值跨次稳定，下游脚本可直接 `jq '.results[] |
| 关键差异 | 正例下游系统可自动化消费，反例需人工解读且无法做跨次趋势对比。 |
进阶要素（可选）
渐进式加载
巡检项多的 Skill，可以分层执行：
- 第一层：核心指标（CPU、内存、磁盘、实例状态），优先执行
- 第二层：性能指标（慢查询、锁等待、缓冲命中率），并行执行
- 第三层：安全配置（SSL、公网访问、备份、审计日志），并行执行
操作分级
| 操作级别 | 允许行为 | 禁止行为 |
|---|---|---|
| 只读巡检（L0） | 查询指标、评估阈值、生成报告 | 修改配置、执行 SQL、重启实例 |
| 变更操作（L2+） | 需人工审批后执行 | 自动化执行任何写操作 |
附录 A：Skill 编写模板
复制本模板新建 SKILL.md，按 7 个要素逐项填实。所有 （必填） 字段必须替换为实际内容；保留 {xxx} 占位语义但替换为实际值。
查看模板
markdown
# Skill 编写模板
## 基本信息
| 字段 | 值 |
|---|---|
| Skill 名称 | `{skill-name}`（kebab-case，例：`rds-inspection`） |
| 解决的问题 | （必填）一句话说明这个 Skill 解决什么运维场景的什么问题 |
| 触发条件 | （必填）用户在什么情况下会调用这个 Skill（自然语言 + 关键词） |
| 风险等级 | （必填）L0 / L1 / L2 / L3 |
## 触发条件（要素 1）
- 自然语言触发：`{用户可能说的话}`
- 关键词触发：`{关键词列表}`
- 边界条件：`{什么情况下不应触发}`
## 流程设计（要素 2）
步骤 1: {步骤名}
输入: {什么数据}
动作: {做什么}
输出: {产出什么}
失败处理: {失败时怎么办}
步骤 2: {步骤名}
...
## 计算与脚本（要素 3）
| 计算项 | 脚本路径 | 输入 | 输出 | 说明 |
|---|---|---|---|---|
| `{计算项}` | `{script-path}` | `{输入}` | `{输出}` | `{为什么必须脚本化}` |
## 输出与复用（要素 4）
- 输出格式：`{报告 / 配置 / 脚本 / 看板}`
- 输出字段：`{必填字段列表}`
- 复用方式：`{客户如何复用这个输出}`
## 风险控制（要素 5）
| 风险 | 等级 | 控制措施 |
|---|---|---|
| `{风险描述}` | L0-L3 | `{控制措施}` |
风险等级 ≥ L2，必须声明 HIL（Human-in-the-Loop）：
- HIL 触发条件：`{什么情况下必须人确认}`
- HIL 确认方式：`{确认流程}`
风险等级 = L3，必须声明回滚方案：
- 回滚步骤：`{如何回滚}`
- 回滚验证：`{如何确认回滚成功}`
## 失败处理（要素 6）
| 步骤 | 失败场景 | 处理方式 | 是否阻塞 |
|---|---|---|---|
| `{步骤 N}` | `{失败场景}` | `{处理方式}` | 是 / 否 |
## 推理边界（要素 7）
| 可推理 | 不可推理（必须脚本 / 必须人） |
|---|---|
| `{LLM 可以做的判断}` | `{必须脚本化或人介入的判断}` |
## 自检
- [ ] 触发条件明确，无歧义
- [ ] 每步有输入 / 动作 / 输出 / 失败处理
- [ ] 数值计算全部脚本化
- [ ] 输出格式和字段已定义
- [ ] 风险等级已声明，L2+ 有 HIL，L3 有回滚
- [ ] 每步失败处理已定义
- [ ] 推理边界已声明
- [ ] 已在 STAROps 实例真实跑通（附调用请求 ID）
附录 B：Skill 质量自检 Checklist
在 Skill 提交评审前逐项打勾。未通过的项必须修复或显式声明豁免理由。
查看 Checklist
markdown
# Skill 质量 Checklist
## Skill 名称：`{skill-name}`
## 自检人：`{姓名}` / 日期：`{YYYY-MM-DD}`
## 1. 触发条件
- [ ] 触发条件已用自然语言写明，无歧义
- [ ] 关键词列表已列出
- [ ] 边界条件已声明（什么情况下不应触发）
- [ ] 触发条件与已有 Skill 无冲突（不会误触发其他 Skill）
## 2. 流程设计
- [ ] 每步有明确的输入 / 动作 / 输出
- [ ] 每步有失败处理
- [ ] 步骤间依赖关系清晰（无隐式状态传递）
- [ ] 步骤数合理（不过多也不过少）
## 3. 计算与脚本
- [ ] 所有数值计算已脚本化（不依赖 LLM 推理）
- [ ] 脚本路径已声明
- [ ] 脚本输入 / 输出格式已定义
- [ ] 脚本已独立可运行（不依赖 Skill 上下文）
## 4. 输出与复用
- [ ] 输出格式已定义（报告 / 配置 / 脚本 / 看板）
- [ ] 必填字段已列出
- [ ] 客户复用方式已说明
- [ ] 输出样例已给出（至少 1 个正例）
## 5. 风险控制
- [ ] 风险等级已声明（L0-L3）
- [ ] L2+ 已声明 HIL 触发条件和确认方式
- [ ] L3 已声明回滚步骤和回滚验证
- [ ] 风险等级与实际操作一致（不是高操作低声明）
## 6. 失败处理
- [ ] 每步失败场景已枚举
- [ ] 每步处理方式已定义（重试 / 跳过 / 阻塞 / 降级）
- [ ] 阻塞性失败已标明
- [ ] 失败信息对客户可读（不是裸异常）
## 7. 推理边界
- [ ] 可推理事已列出
- [ ] 不可推理事已列出（必须脚本 / 必须人）
- [ ] 边界声明与实际操作一致（没有把不可推理的交给 LLM）
## 8. 真实跑通
- [ ] 已在 STAROps 实例真实跑通
- [ ] 调用请求 ID 已记录
- [ ] 跑通结果与预期输出一致
- [ ] 失败场景至少跑通 1 个
## 总结
- 通过项：`{N}` / 总计：`{M}`
- 未通过项及豁免理由：
- `{项}`: `{理由}`
- 是否可提交评审：是 / 否
常见问题
一个 Skill 应该包含多少步骤？
步骤数按真实需要，不强制 3 条或 5 条。判定标准：每步有明确的输入 / 动作 / 输出，步骤间依赖关系清晰，无隐式状态传递。
触发条件与已有 Skill 冲突怎么办？
调整触发条件的关键词和边界条件，消除歧义。若两个 Skill 触发条件天然重叠，在边界条件里显式声明分工。
一次性临时查询是否需要沉淀为 Skill？
不需要。Skill 沉淀的是可重复执行的运维场景；一次性查询直接在数字员工对话里完成即可。
涉及写操作的 Skill 如何评审？
本规范覆盖 L0 只读 Skill。涉及变更 / 删除 / 重启等写操作的 L2+ Skill 需走风险分级与审批流程，由平台团队单独评审。
