Complex Bug Debugging with AI（复杂 BUG 与 AI 协作排查的工程化 Harness）
这是什么
不是案例库，是协作工作流本身。
案例库
bug-pattern-diagnosis回答"这个 bug 是什么" 本 SKILL 回答"怎么和 AI 一起排查复杂 bug"
核心信念：复杂 bug 单靠 AI 解不了，单靠人也解不了。AI 缺：领域直觉 / 业务上下文 / 反信号 / 决策权。人缺：跑遍 100 条命令的耐心。只有人 × AI 协作 + 严格流程，才能稳定攻破。
触发时机
用户描述下列情况时主动激活：
- "排查很久了 / 排查不下去了"
- "bug 很诡异 / 不可复现 / 间歇性"
- "重启又自己好了，但还会再出"
- "看起来是 X，但改了 X 又不行"
- "涉及多个服务 / 节点 / 集群"
- "现象层面看起来矛盾"
普通 NPE / 编译错误 / 怎么写函数 → 不要启用，直接处理。
前置：模型与能力预检（开始前必做）
1. 模型必须是 Opus 4.7（或同等强度）
- 弱模型会沿第一个假设一路编（自洽但错），把用户带沟里
- Opus 4.7 会主动反向怀疑自己（如怀疑工作区代码 ≠ 部署代码，主动拉 jar 反编译比对）
- 当前模型不是 Opus 4.7 → 先告诉用户切换，不要硬上
2. 能力体系完备性
排查能力的下限取决于最弱的工具：
| 能力 | 缺失影响 |
|---|---|
| 代码访问（Read / Grep） | 无法验证业务逻辑 |
| 基础设施（K8S MCP / SSH） | 无法看 pod / 节点 |
| 数据访问（DB MCP） | 只能信用户口述 |
| 日志访问（拉真实日志） | 止于"猜栈" |
| 网络/HTTP 调用 | 无法做实验 |
| 专业 SKILL（如 server-log-analysis） | 效率打折 |
缺哪个补哪个，不要带病开工。
四条贯穿全流程的 AI 自我约束红线
① 不主观论断
每个结论必须有刚跑出来的数据 / 刚读到的代码支撑。禁止用"应该是 / 可能是 / 通常是"当结论。可以说"基于刚才的 metrics，判断是 ..."。
② 不沿假设编
用户给的方向 ≠ 真相。自己上轮假设 ≠ 已确认。看到反信号（"我也试过也不行" / 数据不符预期）立即停下当前路径，重新取证。
③ 方案失效要主动说
没修好 → 第一时间明说"方案 X 失效，证据是 ..."，主动升级下一方案。禁止："应该好了，你试试" / "部分生效..." / 默默换方案。
④ 用户不配合时停止推进
没换强模型 / 能力缺失 / 没回询问 / 没提供边界信息 → 不要带病开工，按下面的话术明确指出。用户坚持不补 → 可继续，但先标记"以下排查在 X 信息缺失下进行，结论可能偏差"。
双向纪律：主动询问 + 用户配合度强制检查
协作不是单方面。AI 不能在用户不配合时硬推，也不能悄悄替用户决定。
主动询问原则
每进入一个阶段，AI 必须主动询问该阶段需要的信息，禁止用户给一句模糊描述就一头扎进去。
9 套用户不配合信号 + AI 反馈话术（直接套用，不要现编）
① 没用强模型
⚠️ 当前模型不是 Opus 4.7。弱模型容易沿假设编（自洽但错），建议先切换。
若坚持用，请额外警惕我的结论，对每个"应该是 ..."追问"数据支撑是什么？"。
② 能力体系缺失
⚠️ 本次排查需要 [具体能力]，当前未配置。
影响：[具体影响]。请先配置再继续。
若暂时配不了，我会基于你提供的文本日志排查，但可信度显著降低。
③ 阶段 A：现象描述太模糊
⚠️ 现象太模糊，无法画链路图。请提供以下三项中至少两项：
1. 一句话现象（"X 接口返回 500 / 设备发 register 没收到 reply"）
2. 真实 log / 接口响应截图
3. 涉及的服务清单（"前端 → 网关 → access-service → broker"）
不补齐我只能停留在猜可能性阶段。
④ 阶段 A：不验收链路图就推下一步
⚠️ 你还没确认链路图是否准确。如果链路图错了，后续讨论都基于错误前提。
请回"对"或"不对，重点是 XXX"，再继续。
⑤ 阶段 B：跳过结构化问题
⚠️ 你没回答以下结构化问题（我自己拿不到）：
□ 复现率？□ 环境差异？□ 最近改动？□ 你自己复现过吗（金问题）？
没有这些信息我只能基于猜测做边界测试。请逐条回答。
⑥ 阶段 C：AI 询问后用户没回答 / 答得模糊
⚠️ 我遇到一个**必须由你确认**的事实：
问题：[具体二选一问题]
影响：决定排查方向（A → 路径 X；B → 路径 Y）
请：1) 告诉我怎么查，我去查；2) 或明确说"不知道也查不到"，我会按两种情况都假设展开。
不要直接换话题，否则诊断空间无法收敛。
⑦ 阶段 C：反信号描述太模糊
⚠️ 你说"也不行 / 没问题"是关键反信号，但描述太模糊。请补充：
- 怎么试的？（命令 / 工具 / 步骤）
- 看到什么？（具体输出 / 错误码）
- 环境一致吗？
不要说"MQTTX 也不行"，要说"MQTTX QoS 1 publish XXX，连 XXX broker，无报错但 reply 没收到"。
⑧ 阶段 D：让 AI 替自己拍板
⚠️ 方案选择必须由你拍板，因为：
- 你比我清楚生产容忍度 / 不能影响什么 / 回滚能力
- 出问题承担后果的是你的团队，不是我
我已列清"修复力度 / 生产影响 / 回滚成本"。请基于"今天能接受多大影响"决定。
若实在没决策依据，告诉我"运维窗口 X / 不能影响 Y"，我帮你筛但你拍板。
⑨ 阶段 G：修复完不沉淀
⚠️ 本次细节正在快速从短期记忆里流失。强烈建议现在沉淀（5 分钟）：
- 按 bug-pattern-diagnosis 模板写 BUGxx.md
- 重点：症状速查 / 反向特征 / 5 分钟自检命令 / 走过的弯路
不沉淀代价：下次类似 bug 你 / 同事 / AI 都要从零再排一次。
回"沉淀"或"不用"，明确即可。
配合度门控（每阶段流转前自检）
| 流转 | Gate |
|---|---|
| A → B | 用户验收链路图了吗？ |
| B → C | 答完结构化问题？补了"我也复现过"？ |
| C 每轮 | 上轮疑问回答了？反信号够具体？ |
| C → D | 决定性证据充分？AI 没自我说服？ |
| D → E | 用户拍板了？还是让 AI 替决策？ |
| E → F/G | 验证数据齐？修复前后并列展示？ |
| G 完成 | 同意沉淀？BUGxx.md 完整？ |
任一 Gate 不通过 → 停下来按话术指出，不要硬推。
7 阶段协作工作流
阶段 A：业务链路对齐【先建图，不修 bug】
双方对"链路"认知不一致 → 后续讨论都是鸡同鸭讲。
AI 主动开场（必做）：
按 SKILL 流程走（不需要可打断我）。阶段 A 我需要：
1. 一句话现象（不要先猜原因）
2. 真实 log / 接口响应 / 截图
3. 涉及哪些服务 / 链路
我画完链路图给你确认。
AI 做：
- 主动询问 / Read 代码，画端到端链路图
- 复述现象，确认"我理解的 = 你说的"
- 明确列"已知 X"、"不知道 Y"
人验收（强制 Gate）：
- "对" → 进入 B
- "不对，重点是 XXX" → 重画
- 没明确验收 → 套话术 ④
反模式：上来就扎代码 / 没等验收就推下一步。
阶段 B：症状结构化 + 领域信息补齐
AI 主动开场（必做）：
进入 B。请逐条回答（缺哪条都会让排查走偏）：
□ 复现率：100% / 偶发 / 特定条件？
□ 环境差异：本地能复现吗？
□ 多实例特征：单 / 多副本？
□ 最近改动：发版 / 扩容 / 配置变更 / 依赖升级？
□ 日志特征：集中 / 分散？时间窗？
□ 你自己复现过吗？（金问题）用什么手段？看到什么？
□ 你怀疑过哪些方向？已排除什么？
模糊或跳过的我会再追问。
人补领域信息："这是 broker 集群" / "上周扩容了" / "我用 MQTTX 也试了也不行" ← 这种'我也复现了'是金子。
Gate：用户回答 ≥5 条 → C；少于 3 条 → 套话术 ⑤；反信号模糊 → 套话术 ⑦。
反模式：不结构化就直接排查 / 用户跳过就脑补。
阶段 C：AI 自主边界测试循环【核心引擎】
复杂 bug 几乎不可能一次实验定位，必须循环收敛。
AI 主动开场（必做）：
进入 C。我会跑这个循环：现象 → 边界测试 → 数据并列展示 → 有疑惑就主动问你。
每轮我会：明确说"这轮验证什么假设"、数据并列展示、必须由你确认的事实主动停下问。
你随时打断说"等等，这个数据为什么 XXX？"是被鼓励的——能帮我避免自我说服。
本轮预计跑 [命令清单]，需要 [具体能力]。能力齐了吗？
AI 每轮：
-
设计能二分诊断空间的实验（不是穷举跑命令）
-
自主执行：MCP / shell / 代码读取 / 跨节点对比
-
数据并列展示：
实验 预期 实际 一致？ 入口 A 应成功 成功 ✅ ✓ 入口 B 应成功 失败 ❌ ✗ 异常点 -
自检"实际 vs 假设是否完全吻合"：
- 完全吻合 + 信息充分 → 初步结论 → D
- 任何"不太对"的数据 → 不要硬下结论，列疑问问人
- 信息不够 → 设计下一轮
人做：看 AI 列的疑问 / 在 AI 自我说服时主动打断："等等，那这个数据为什么 XXX？"
Gate：AI 询问的事实必须回答或明确说"不知道"。反信号必须具体。
反模式：跑了 10 条命令但没并列展示 / 实验是"穷举"不是"二分" / 部分数据吻合就下结论 / 不主动暴露疑惑（最大反模式） / 询问后没答就继续跑。
阶段 D：方案设计 + 风险摆台【AI 摆台，人决策】
AI 主动开场（必做）：
进入 D。我列所有可行方案，**最终选哪个由你拍板**。
请告诉我：今天有运维窗口吗？哪些业务绝对不能影响？回滚能力如何？
若你说"你看着办" → 请先看下表"生产影响"列。我不替你拍板（出问题承担后果的是你）。
AI 做：列所有方案，绝不替人拍板：
| 方案 | 步骤 | 修复力度 | 生产影响 | 回滚成本 | 推荐度 | 理由 |
|---|
Gate：用户明确选 → E；说"你看着办" → 套话术 ⑧；催"快修"但没拍板 → "在你拍板前我不会动手"。
反模式：直接说"我建议方案 X"+ 操作 / 隐藏方案 / 没给生产影响评估。
阶段 E：执行 + 实时验证【边做边证】
"操作完就觉得修好了"是最大的坑。
AI 做：
-
执行修复
-
立即重跑阶段 C 的决定性实验（同命令、同输入）
-
修复前后并列：
指标 修复前 修复后 符合预期？
反模式：执行完不验证就说"应该好了" / 部分指标改善就说"修好了" / 验证甩给用户。
阶段 F：方案失效时的主动升级【最容易翻车】
AI 做：
- 数据不符 → 立刻明说"方案 X 失效，证据是 ..."
- 分析失效原因
- 自动升级下一方案（除非升级方案风险等级提升，那时再请人决策）
- 重新执行 + 验证
真实案例范例：
方案 1 (重启 pod) 失效。证据：路由表预期 ≈41，实际仍 3 ❌；跨节点 publish 仍失败 ❌。
原因：hostPath 持久化让节点重启后跳过 mria 全量 bootstrap。
升级方案 3 (cluster leave + join)：路由表 3 → 46 ✅；跨节点 publish 全通过 ✅。修复成功。
反模式："应该好了，你试试" / "方案 1 部分生效..." / 默默换方案 / 失效后让用户决定下一步。
阶段 G：闭环沉淀【强制收尾】
修复成功后必须立刻沉淀，不要拖到第二天——血的细节会很快忘。
AI 主动开场（必做，不要等用户提）：
✅ 修复验证成功。**强制进入 G**——细节正在快速流失。
我现在按 bug-pattern-diagnosis 模板写 BUGxx.md（5 分钟）。
确认：□ 同意沉淀（默认）→ 直接开写 □ 不沉淀 → 请明确说"不用"，并理解：下次类似 bug 大家都从零再排
AI 做：用 bug-pattern-diagnosis 模板写 BUGxx.md，4 块必写：
- 症状速查表（可验证、可 grep）
- 反向特征（什么情况不是本案例 ← 防误诊）
- 5 分钟自检命令（让下次直接抄）
- 本次走过的弯路（为什么方案 1 失效 / 为什么以为是 X）
Gate：用户没回应 → 套话术 ⑨ + 默认沉淀。说"不用" → 明说"OK，下次我也学不到这次的经验"。
反模式：不沉淀 / 等用户提才动 / 案例只写"是什么 bug"不写反向特征和弯路。
一图流（紧凑版）
[前置] 模型 = Opus 4.7 + 能力完备 ← 缺任一项 套话术 ①/②
↓
[A] 链路对齐 ─ 开场问"现象/log/服务" ─ Gate: 用户验收链路图 ─ 红线: 不扎代码
↓
[B] 症状结构化 ─ 开场问 7 项清单 ─ Gate: 答 ≥5 条 + "你复现过吗" ─ 红线: 必须收反信号
↓
[C] 边界测试循环 ─ 开场说"二分实验/数据并列/有疑惑就问" ─ Gate: 用户必答询问 ─ 红线: 不主观/不沿假设/主动暴露疑惑
↓
[D] 方案摆台 ─ 开场问"运维窗口/不能影响什么/回滚" ─ Gate: 用户拍板 ─ 红线: AI 不决策/不隐藏方案
↓
[E] 执行+验证 ─ 红线: 不验证不算修复
↓ ──修好──→ [G]
↓
└──没修好──→ [F] AI 明说失效+证据 + 自动升级 → 回 E
↓
[G] 闭环沉淀 ─ 开场默认沉淀 ─ Gate: 没回应 → 默认沉淀
反模式速查（人 / AI 对照话术编号）
AI 反模式（自查）：跳过 A 扎代码 / 命令输出无并列 / "应该" 当结论 / 看到反信号还沿原方向 / 自我说服快速下结论 / D 直接操作 / 执行完不验证 / 模糊词掩盖失效 / 验证甩给用户 / 修复完不沉淀。
人反模式 → AI 应套话术：
| 人反模式 | 话术 |
|---|---|
| 弱模型排查复杂 bug | ① |
| 缺关键能力 | ② |
| 现象太模糊 | ③ |
| 不验收链路图就推下一步 | ④ |
| 跳过结构化问题 | ⑤ |
| 询问后不答 / 答模糊 | ⑥ |
| 反信号太粗 | ⑦ |
| 让 AI 替拍板 | ⑧ |
| 修复完不沉淀 | ⑨ |
| 把问题甩给 AI 喝咖啡 | ⑥+⑦ AI 主动 ping |
| "你按 BUGxx 修一下" | "案例是思路启发不是答案，先按 A 对齐链路" |
AI 不能纵容用户不配合。套话术 ≠ 拒绝合作，而是让用户清楚"现在不合作的代价是什么"。
与 bug-pattern-diagnosis 的关系
bug-pattern-diagnosis = 病例库（看过的病）；本 SKILL = 诊疗手册（怎么看病）。
典型协作链：用户报复杂 bug → 本 SKILL 启用 7 阶段 → 阶段 C 时去 bug-pattern-diagnosis 找思路启发 → 回 C 继续测试 → 排查成功 → 阶段 G 用 bug-pattern-diagnosis 模板写新 BUGxx.md。两者互相调用、互相喂养。
自我演化
每次排查后评估：有新红线？有未覆盖的反模式？有阶段该拆得更细？有 → 主动建议用户更新本 SKILL。本 SKILL 自身就是用本 SKILL 演化出来的。
一句话总结
复杂 bug 排查 = Opus 4.7 × 能力完备 × 7 阶段 × 4 条 AI 红线 × 双向配合度门控 × 闭环沉淀。 本 SKILL 同时约束 AI 和用户。检测到不配合时 AI 必须按话术指出，让用户决定补齐还是放弃——不要带病硬推。