这套 Skill 有 187 行指令、11 个脚本、4 份规范文档。翻遍整个仓库,你不会找到一句话教 AI「怎么排查生产问题」——没有「第一步查日志、第二步看监控」,没有根因树,没有决策表。

它只有三样东西:现场、边界、验收。这篇不谈理念,直接读源码,看这三样东西是怎么长成的。

                 一起事故进来
                      │
        ┌─────────────┴─────────────┐
        │  ① 环境就绪:门禁不通过,不许开查  │
        │  check-environment.sh 状态机     │
        │  源码新鲜度 await-freshness.sh  │
        └─────────────┬─────────────┘
                      ▼
        ┌─────────────────────────┐
        │  ② 过程自由:AI 自己决定怎么查    │
        │  不规定顺序、不规定工具、不规定框架  │
        │  (但所有云端调用必须走只读包装脚本)│
        └─────────────┬───────────┘
                      ▼
        ┌─────────────────────────┐
        │  ③ 输出契约:20 条质量检查      │
        │  incident-analysis-output.md │
        │  结论卡 + 证据链 + 状态分级      │
        └─────────────────────────┘

一、环境就绪:「装了」和「能用」是两回事

AI 排查失败的头号原因不是模型不行,是现场不行:日志没配、源码是旧的、图谱没索引。而模型面对残缺现场时不会说「我查不了」,它会直接开编。所以 Skill 把环境做成强制门禁。

1. 一次检查,全部状态摆出来

scripts/check-environment.sh

这个脚本不是检查「命令存在」,而是真的去读一次:SLS 实际读取、ARMS 实际读取、本地源码同步状态、全部托管仓库的索引状态。最后汇总只有两种结果:

汇总状态 含义
ENVIRONMENT_CHECK_READY 全部必选能力实际可用,且无刷新进行中
ENVIRONMENT_CHECK_PARTIAL 至少一项未就绪,按状态逐项修复后重查

关键在于状态必须分层,因为「部分就绪」最容易被 AI 说成「一切正常」:

状态 真实含义
CODEBASE_MEMORY_LOCAL_READY 只是本地程序装好了。不代表会话里有 MCP 工具,不代表相关仓库有索引
CODEBASE_MEMORY_RESTART_REQUIRED 配置写入了,但当前会话没加载,需要重启 Agent
CODEBASE_MEMORY_READY 全部托管仓库索引存在,且与当前源码 Commit 一致
SOURCE_REFRESH_IN_PROGRESS 源码正在刷新,禁止读源码、禁止调图谱

注意 LOCAL_READY 和 READY 的天壤之别:一个是「装了」,一个是「能用」。所以 SKILL.md 里还有一条硬性规定:

Shell 脚本无法证明当前 Agent 会话已经加载 MCP 工具。脚本返回 ENVIRONMENT_CHECK_READY 后,Agent 必须在当前会话调用一次 list_projects;调用不可用时,将最终环境状态覆盖为 CODEBASE_MEMORY_RESTART_REQUIRED 和 ENVIRONMENT_CHECK_PARTIAL,不得声称代码图谱可用。

环境验证以「真的调了一次」为准,不以「理论上应该有」为准。

2. 源码新鲜度:一个 marker 文件实现的读写锁

生产事故最常见的弯路,是拿最新代码分析旧事故。Skill 的对策是「先刷新,再准入」:

  • 排查开始:refresh-sources.sh 后台全量对齐 70 多个仓库和图谱索引,不阻塞其他证据收集,同时写入 source-refresh-in-progress 标记文件
  • 读取源码前:必须过 await-freshness.sh 这道门禁,拿到 SOURCE_FRESHNESS_READY 才放行

这个门禁脚本不到 100 行,但有一个我很喜欢的细节——它会识别「刷新进程已经死了、但标记还残留」的僵死状态:

while [ -f "$MARKER_FILE" ]; do
    running_pid="$(awk -F '\t' '{print $1; exit}' "$MARKER_FILE")"
    if [ -z "$running_pid" ] || ! kill -0 "$running_pid" 2>/dev/null; then
        rm -f "$MARKER_FILE"
        printf '%s\n' 'SOURCE_REFRESH_STALE: refresh process is gone; rerun scripts/refresh-sources.sh' >&2
        exit 1
    fi
    sleep 2
done

标记文件里存着刷新进程的 PID,门禁用 kill -0 探活:进程还在就等,进程死了清掉残留标记、报 SOURCE_REFRESH_STALE 要求重跑。没有数据库、没有消息队列,一个文件加一个 PID,就是一套可读写的状态机。

刷新完成后,各仓库当时的 HEAD Commit 就是本次排查的源码基线,排查期间不再二次刷新。报告里每个仓库都要记录精确 Commit;对齐不了事故版本时,必须写:

当前源码已检查,事故版本尚未确认。

「我查过源码」和「我查过那个版本的源码」,是两份完全不同的证据。

二、只读:不靠「嘱咐」,靠「结构」

让 AI 碰生产,我最担心的不是它查得慢,是它顺手做点什么。提示词里写「请不要修改生产数据」是一句废话,只读必须长在结构里。

1. 最内层:拒绝一切环境覆盖

所有云端调用最后都汇聚到 aliyun-prod.sh,它只有 35 行,但每一行都在挡人:

for argument in "$@"; do
  case "$argument" in
    --profile|--profile=*|--mode|--mode=*|--region|--region=* \
    |--access-key-id|--access-key-id=*|--access-key-secret|--access-key-secret=*|--sts-token|--sts-token=*)
      printf 'ALIYUN_ENV_INVALID: forbidden production credential override: %s\n' "$argument" >&2
      exit 2
      ;;
  esac
done

export ALIBABA_CLOUD_IGNORE_PROFILE='TRUE'
exec aliyun "$@"

两层防护:参数层面,任何 profile、region、ak/sk、token 的覆盖直接退出;环境层面,ALIBABA_CLOUD_IGNORE_PROFILE='TRUE' 让 CLI 彻底忽略本机其他 profile——这台机器上就算还配着别人的高权限账号,也轮不到它上场。Skill 的阿里云配置是独立目录里单独一份,用的是架构专门开的只读账号,不碰用户日常那把什么都能干的钥匙。

2. 中间层:API 白名单

aliyun-arms.sh 在调用前把 API 名放进 case 里过一遍:

case "$OPERATION" in
  ListTraceApps|SearchTraceAppByName|SearchTraceAppByPage|SearchTraces|SearchTracesByPage|GetTrace|GetMultipleTrace|GetStack|GetTraceApp|GetAppApiByPage|GetAppJVMConfig|QueryAppTopology)
    INJECT_REGION='true'
    ;;
  GetTraceAppConfig|QueryMetricByPage)
    INJECT_REGION='false'
    ;;
  *)
    printf 'ARMS_READ_OPERATION_NOT_ALLOWED: %s\n' "$OPERATION" >&2
    exit 2
    ;;
esac

不在名单里的 API,根本到不了云端。 ARMS 的写操作、管理操作不是「被警告」,是「不存在」。SLS 那边同理,--project、--endpoint 出现在参数里就直接报错——想临时换个环境查一下?参数层面就不允许。

这就是我说的:让「只读」成为默认路径,让「能写」成为不存在的路径。

3. 数据库:fail closed,宁可不查

数据库是可选能力,闸门最严。dbx-readonly-policy.md 立了三道闸:

工具面:只许出现 dbx_list_connections、dbx_list_tables、dbx_describe_table、dbx_get_schema_context、dbx_execute_query 这几个查询工具。只要发现任何连接管理、数据修改、DDL、导入导出工具,立即报 DBX_PERMISSION_SCOPE_INVALID 并停止全部 DBX 调用。

SQL 面:只接受 SELECT / SHOW / DESCRIBE / EXPLAIN 开头的单条语句,其他前缀一律拒绝,禁止 SELECT *,返回最多 100 行,大表先 EXPLAIN,禁止 EXPLAIN ANALYZE(它会真的执行查询,可能造成负载)。

最硬的一条:

Never test permissions by attempting a write, even inside a transaction or rollback.

不许用「试写一下再回滚」来验证权限——验证权限这件事本身就可能造成事故。权限不明,就不查;数据库证据没拿到,报告里就写「未纳入」,其他证据继续,但不许把数据库假设写成根因。这就是 fail closed:任何一环存疑,闸门自动落下。

三、过程自由:为什么不教排查

刚做这套东西时,我也想过把排查流程写细:先查 SLS,再拉 Trace,再定位服务,再翻代码。真写下去就会发现这条路是死的——每起事故都是新的。一次资源耗尽和一次证书失效,证据的位置、查询的顺序完全不同。把流程写死,轻则让 AI 做无用功,重则它在「第一步」找不到证据时,硬编一个答案交差。

所以 SKILL.md 里只有一句原则:

本 Skill 只提供现场、工具和必要的安全约束。Agent 可以根据具体事故自主决定排查思路、工具组合和证据顺序。

甚至「不要因为某项工具可用,就强制 Agent 使用该工具」也写进去了——代码图谱好用,但不许为了形式完整强行拿它下结论。过程自由,契约刚性。

四、输出契约:210 行规范,只干一件事——不许糊弄

最后交出来的报告,必须过 incident-analysis-output.md。这份规范是整套 Skill 里我最得意的部分,它不管你怎么查,只管你怎么说。

1. 结论状态只有四种,没有「80% 确定」

状态 判定标准
已确认 直接证据闭合关键因果链,且无冲突证据
高置信 多个独立证据一致支持,只剩非关键环节未直接验证
待验证 有可检验的假设,关键环节还没证据
证据不足 撑不起可靠判断,或关键数据源不可用

规范明确禁止「缺乏依据的百分比置信度」——「80% 确定」是把证据缺口包装成数字。还有一条很狠的:总体状态不得高于最弱的关键环节。「服务端链路已确认、端到端根因待验证」必须分开写,下游查清不等于整件事查清。

对「死锁、行锁等待、内存溢出」这类机制级判断,只有日志、Trace、监控直接呈现该机制时才能标「已确认」;时间顺序和源码语义都吻合但没直接证据,只能是「高置信」。推测出来的机制,不能享受目击者的待遇。

2. 原因分四层,不许一个「根本原因」包打天下

举个通用例子:用户看到「下单接口大面积超时」。

层级 定义 例子里分别是什么
直接原因 直接导致告警的系统行为 数据库连接池耗尽,请求排队超时
上游触发 让直接原因成立的条件 全量分析任务与高峰期业务查询叠加,打满数据库 CPU
缺陷或放大因素 没拦住异常的缺陷 分析库与业务库没有隔离、没有限流降级
最终根因 异常最初为什么产生 待验证:为什么全量任务被安排在业务高峰期?

保护性校验缺失,不等于异常最初产生的原因。 没有隔离是「放大因素」,不是「最终根因」——把这两层混写,复盘就会停在「加个限流」而不是「改掉调度」。

3. 事故结论卡:第一屏就能独立阅读

所有阶段性结论和最终报告,都必须先给这张卡:

## 事故结论

- 结论状态:已确认 / 高置信 / 待验证 / 证据不足
- 已确认范围:已经闭合的因果链或结论对象
- 未确认范围:尚缺证据的关键环节;无则写「无」
- 故障应用:
- 发生时间:
- 用户现象:
- 影响范围:已确认范围及其查询窗口/数据源边界;未确认范围
- 原因摘要:无法确认时写「未确认」,并给出当前最重要的证据缺口
- 故障位置:仓库 / Commit / 文件 / 符号 / 行号;未定位时写「未定位」
- 处置状态:未执行 / 处理中 / 已执行
- 下一步:只列当前最有价值的验证或处置动作

注意两个细节:「未确认」是合法答案——模板允许空着,不许编;「处置状态」只能依据用户或外部系统的明确反馈填写——AI 不许把「我建议修复」写成「已修复」。

4. 证据表:事实和判断分开放

完整报告里的关键证据表长这样:

编号 类型 来源与定位 客观事实 支持的判断
E1 SLS Project / Logstore / 时间窗 / traceId 14:03:21 起连续出现连接超时 异常起始时间不晚于 14:03
E2 源码 仓库 / Commit / 文件 / 行号 该接口未设置查询超时上限 推断:慢查询可无限占用连接

「客观事实」列只写直接观测,「支持的判断」列写能推出什么。时间相关性不能写成因果,源码语义不能写成线上事实,用户描述不能写成系统事实。

还有一条几乎是为 AI 复盘量身定制的:所有否定性、穷尽性判断,都必须带查询边界。「无其他影响」「未发现异常」「全部正常」——必须附上哪个数据源、哪个应用、哪个时间窗口。「查询窗口内未检出」不等于「整个生产不存在」。

5. 质量检查:20 条「不许」

规范最后是一份 checklist,输出前逐条过。随手摘几条:

  • 没有把工具调用成功,等同于根因已经确认
  • 没有把「尚未检查」写成「源码未纳入」
  • 没有使用「已自愈」「无残留」「数据正常」等没有当前状态证据的表述
  • 没有把建议描述为已经执行
  • 本地最新源码无法与事故版本对齐时,没有把当前源码行为直接当作线上事实
  • 没有泄露凭据、私钥、Token 或数据库连接密钥

它约束的不是能力,是诚实。

五、这套 Skill 真正固化的是什么

回到开头:不写排查流程,那这套 Skill 的价值在哪?

它固化的不是方法,是纪律。

方法属于 AI——它比人更会在几十个服务、几千条日志里找关联,固化流程反而是束缚。但纪律必须属于工程:现场不齐不许开查、只读路径不许绕过、没有证据不许下结论、结论不全不许写「已确认」。

过程自由,环境可复现,权限只读,结论可审计。

一个 Agent 聪不聪明,决定它排查的上限;这套纪律在不在,决定它排查的下限。上限给老板看,下限才给生产用。


系列说明:本文是「生产排查 Skill 诞生记」系列导读。后续章节会逐篇展开:四维证据源怎么接、代码图谱怎么建、只读门禁怎么实现、以及一次真实事故的完整排查回放。