这套 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 诞生记」系列导读。后续章节会逐篇展开:四维证据源怎么接、代码图谱怎么建、只读门禁怎么实现、以及一次真实事故的完整排查回放。
评论