V2EX = way to explore V2EX 是一个关于分享和探索的地方
Sign Up Now For Existing Member Sign In
请不要在回答技术问题时复制粘贴 AI 生成的内容
This topic created in 54 days ago, the information mentioned may be changed or developed.
因为前一阵子被自己参与的 DAG （有向无环图）系统排错折磨得苦不堪言，才有了这个项目。
当时系统涉及几十个节点，排错时需要从 Langfuse 里几十 KB 甚至非常重的 Trace 树中用肉眼找关键节点，经常看花了眼。但在痛苦的过程中，我也意识到：**这种排错其实极度有“套路”。**
尤其是前阵子各种 Agent Skill 爆火，当时我就想，为什么不直接给 AI 接上 DB 、Redis 和 Langfuse 的只读接口，然后写一个特定的 Skill （也就是 Runbook 手册）告诉它：
*“遇到这样的问题你按这个顺序查，第一步查 Redis ，第二步对比 DB ，第三步去对应的几十 KB 的 Trace 里精准捞出特定的那些关键数据进行分析。”*
实际跑通测试下来，效果出奇地好：AI 不再瞎猜，给出的结论极其稳定可信。所以，干脆就把这套方法论抽象了出来，做成了这个独立的框架：`agent-debugger` / `debug-runbook`。
GitHub 项目地址：
[https://github.com/UnCooe/debug-runbook]( https://github.com/UnCooe/debug-runbook)
### 为什么做这个东西？
它想解决的问题其实挺具体的。
现在很多 AI Agent 的“线上排障”方案，本质上还是把数据库只读账号、日志系统、Tracing 、Redis 这些工具接口一股脑暴露给模型，然后期待它自己查明白。
看起来很智能，但实际越做越觉得，这里面有个经常被忽略的关键变量：
> **排障能力里最值钱的部分，绝不是工具访问权限，而是调查顺序与证据链条。**
一个有经验的后端同学排查问题，脑子里通常不是“有什么工具”，而是：
1. 先确认请求到底有没有真的进入主流程
2. 再看关键副作用（ Side Effect ）有没有发生
3. 再对齐持久化状态 (DB)
4. 最后才看 缓存 / 幂等键 / 异步链路 有没有把流程短路
这个顺序本身，就是千锤百炼的**排错经验**。
而很多 Agent 方案，偏偏把这部分丢了，只剩下“模型自由发挥”。结果就会出现几个典型的高血压名场面：
- 工具很多，但调查路径不稳定，每次问法不同，排查步骤也不同；
- 模型极容易被大段的 Trace / SQL 结果 / 日志噪音带偏（ Token 直接爆炸）；
- 它能给出一个“像样的解释”，但证据链根本经不起推敲；
- 真到线上大推业务场景时，你完全不敢 audit 它到底凭什么得出的这个结论。
### 这个项目做了什么？
所以做这个项目时，换了个解法。思路不是“看怎么再封装几个强大的 MCP 调试工具”，而是反向操作：
> **把资深工程师的排障套路写成可执行的 YAML Runbook ，强制约束 Agent 先按顺序收集证据，再下结论。**
项目的架构骨架大概是这样运作的：
- 输入一个事故上下文（比如 `trace_id`、`order_id`、`request_id`）
- **选剧本**：引擎先根据症状（ Symptom ）匹配最对口的 Runbook 。
- **强制按序执行**：再严格按 Runbook 规定的步骤，顺序调用 Trace / DB / Redis 这些 Adapter 。
- **洗数据**：所有 Adapter 返回的原始结果，全部过滤洗干净，归一化成了结构化的 `Evidence`（证据）。
- **推断结论**：再把这些证据扔进决策引擎（ Decision Rules ），产出最终包含根因的结构化 Incident Report 。
不是让模型像无头苍蝇一样直接面对一地鸡毛的真实状态图，而是先把**“可调查路径”**和**“证据形状”**全都死死限定住。
### 核心特性 MVP 验证
现在做出来的早期开源版（ MVP ）跑通了几个硬核节点：
1. **Runbook Selection**：根据 symptom 和 context 选排查剧本，不是所有问题都一把梭地查全套系统。
2. **Ordered Execution**：排查步骤强制有序，不允许 Agent 自己胡乱跳转发散。
3. **Evidence Normalization**：不直接把原始 Payload 喂给大模型，而是转成几十个字的统一 Evidence ，保护上下文长度。
4. **Decision Rules**：最终出什么结论不靠 LLM 的玄学推理，而是基于收集到的“证据组合”来触发（比如 `A 证据 + B 证据 = C 结论` 成立）。
5. **绝对的只读红线**：所有 Adapter 都限制在了只读层。DB 有表名白名单拦截，Redis 限制了 Key 前缀匹配规则，从根本上杜绝大模型在库里“乱挥大刀”。
### 真实的 Demo 案例
在库里塞了一个最常见的业务 Case Demo：**“订单创建成功了，但下游任务没生成”**（`npm run demo:order-task-missing`）。
* **原生 Agent 的瞎排查**：把几百行的 Trace 读一遍发现没报错，又去扫全表 SQL 搜日志，毫无头绪。
* **在这个 Runbook 框架里**：它老老实实地走了一条固定路径。先扫 Trace ，再看丢失的那一环丢在哪里了，转头查 DB 的订单和任务表比对，最后精准定位到 Redis 里的 Idempotency Key 。通过收集齐这几样证据，得出了极其稳定的结论：
**“请求大概率被 cache / idempotency 状态提前拦截短路了，所以订单尽管落库了，但后续副作用未触发”**。
这套逻辑基准的 Benchmark 是全绿通过的。
### 欢迎来交流与碰撞
这套东西刻意没有往“全自动自发修复线上 Bug”那种吸睛（但现阶段不现实）的方向去靠，因为觉得在复杂的业务黑洞里，**可审计性**与**证据链是否收闭**，远比所谓的“AI 显得很聪明”能落地得多。现在项目已经备齐了 MCP 入口，搭好了引擎的基础结构。
V 站的各位老哥/老姐们如果有在这条 AIOps 泥石流里摸爬滚打过的，很想借机探讨几个灵魂拷问：
1. 你们团队线上最频繁、最适合被总结成“八股文排错 Runbook”的事故场景是哪一类？
2. 在平时的排障中（ Trace / DB / MQ / 日志分析等），你们觉得大模型在哪一层最容易犯浑、被噪声带跑偏？
3. 对于生产环境，你是更愿意相信一个“工具自由调用的万能 Agent”，还是“被规范排障手册强约束的 Agent”？
4. 如果要把你们老专家脑子里的“祖传排故套路”沉淀成 YAML 代码交接给 AI ，最大的阻力通常是什么？
如果觉得这里的实现思想有那么点意思，极其欢迎路过指点，或者试着提 PR 用你们最得意的“排障剧本”砸向。相比多添个连接器，这项目现在最缺的反而是真实战场的经验**剧本**，因为从这个架构看，Adapter 只是干活的苦力，**高度浓缩的 Runbook 才是真正的资产层。**
当时系统涉及几十个节点，排错时需要从 Langfuse 里几十 KB 甚至非常重的 Trace 树中用肉眼找关键节点，经常看花了眼。但在痛苦的过程中，我也意识到：**这种排错其实极度有“套路”。**
尤其是前阵子各种 Agent Skill 爆火，当时我就想，为什么不直接给 AI 接上 DB 、Redis 和 Langfuse 的只读接口，然后写一个特定的 Skill （也就是 Runbook 手册）告诉它：
*“遇到这样的问题你按这个顺序查，第一步查 Redis ，第二步对比 DB ，第三步去对应的几十 KB 的 Trace 里精准捞出特定的那些关键数据进行分析。”*
实际跑通测试下来，效果出奇地好：AI 不再瞎猜，给出的结论极其稳定可信。所以，干脆就把这套方法论抽象了出来，做成了这个独立的框架：`agent-debugger` / `debug-runbook`。
GitHub 项目地址：
[https://github.com/UnCooe/debug-runbook]( https://github.com/UnCooe/debug-runbook)
### 为什么做这个东西？
它想解决的问题其实挺具体的。
现在很多 AI Agent 的“线上排障”方案，本质上还是把数据库只读账号、日志系统、Tracing 、Redis 这些工具接口一股脑暴露给模型，然后期待它自己查明白。
看起来很智能，但实际越做越觉得，这里面有个经常被忽略的关键变量：
> **排障能力里最值钱的部分，绝不是工具访问权限，而是调查顺序与证据链条。**
一个有经验的后端同学排查问题，脑子里通常不是“有什么工具”，而是：
1. 先确认请求到底有没有真的进入主流程
2. 再看关键副作用（ Side Effect ）有没有发生
3. 再对齐持久化状态 (DB)
4. 最后才看 缓存 / 幂等键 / 异步链路 有没有把流程短路
这个顺序本身，就是千锤百炼的**排错经验**。
而很多 Agent 方案，偏偏把这部分丢了，只剩下“模型自由发挥”。结果就会出现几个典型的高血压名场面：
- 工具很多，但调查路径不稳定，每次问法不同，排查步骤也不同；
- 模型极容易被大段的 Trace / SQL 结果 / 日志噪音带偏（ Token 直接爆炸）；
- 它能给出一个“像样的解释”，但证据链根本经不起推敲；
- 真到线上大推业务场景时，你完全不敢 audit 它到底凭什么得出的这个结论。
### 这个项目做了什么？
所以做这个项目时，换了个解法。思路不是“看怎么再封装几个强大的 MCP 调试工具”，而是反向操作：
> **把资深工程师的排障套路写成可执行的 YAML Runbook ，强制约束 Agent 先按顺序收集证据，再下结论。**
项目的架构骨架大概是这样运作的：
- 输入一个事故上下文（比如 `trace_id`、`order_id`、`request_id`）
- **选剧本**：引擎先根据症状（ Symptom ）匹配最对口的 Runbook 。
- **强制按序执行**：再严格按 Runbook 规定的步骤，顺序调用 Trace / DB / Redis 这些 Adapter 。
- **洗数据**：所有 Adapter 返回的原始结果，全部过滤洗干净，归一化成了结构化的 `Evidence`（证据）。
- **推断结论**：再把这些证据扔进决策引擎（ Decision Rules ），产出最终包含根因的结构化 Incident Report 。
不是让模型像无头苍蝇一样直接面对一地鸡毛的真实状态图，而是先把**“可调查路径”**和**“证据形状”**全都死死限定住。
### 核心特性 MVP 验证
现在做出来的早期开源版（ MVP ）跑通了几个硬核节点：
1. **Runbook Selection**：根据 symptom 和 context 选排查剧本，不是所有问题都一把梭地查全套系统。
2. **Ordered Execution**：排查步骤强制有序，不允许 Agent 自己胡乱跳转发散。
3. **Evidence Normalization**：不直接把原始 Payload 喂给大模型，而是转成几十个字的统一 Evidence ，保护上下文长度。
4. **Decision Rules**：最终出什么结论不靠 LLM 的玄学推理，而是基于收集到的“证据组合”来触发（比如 `A 证据 + B 证据 = C 结论` 成立）。
5. **绝对的只读红线**：所有 Adapter 都限制在了只读层。DB 有表名白名单拦截，Redis 限制了 Key 前缀匹配规则，从根本上杜绝大模型在库里“乱挥大刀”。
### 真实的 Demo 案例
在库里塞了一个最常见的业务 Case Demo：**“订单创建成功了，但下游任务没生成”**（`npm run demo:order-task-missing`）。
* **原生 Agent 的瞎排查**：把几百行的 Trace 读一遍发现没报错，又去扫全表 SQL 搜日志，毫无头绪。
* **在这个 Runbook 框架里**：它老老实实地走了一条固定路径。先扫 Trace ，再看丢失的那一环丢在哪里了，转头查 DB 的订单和任务表比对，最后精准定位到 Redis 里的 Idempotency Key 。通过收集齐这几样证据，得出了极其稳定的结论：
**“请求大概率被 cache / idempotency 状态提前拦截短路了，所以订单尽管落库了，但后续副作用未触发”**。
这套逻辑基准的 Benchmark 是全绿通过的。
### 欢迎来交流与碰撞
这套东西刻意没有往“全自动自发修复线上 Bug”那种吸睛（但现阶段不现实）的方向去靠，因为觉得在复杂的业务黑洞里，**可审计性**与**证据链是否收闭**，远比所谓的“AI 显得很聪明”能落地得多。现在项目已经备齐了 MCP 入口，搭好了引擎的基础结构。
V 站的各位老哥/老姐们如果有在这条 AIOps 泥石流里摸爬滚打过的，很想借机探讨几个灵魂拷问：
1. 你们团队线上最频繁、最适合被总结成“八股文排错 Runbook”的事故场景是哪一类？
2. 在平时的排障中（ Trace / DB / MQ / 日志分析等），你们觉得大模型在哪一层最容易犯浑、被噪声带跑偏？
3. 对于生产环境，你是更愿意相信一个“工具自由调用的万能 Agent”，还是“被规范排障手册强约束的 Agent”？
4. 如果要把你们老专家脑子里的“祖传排故套路”沉淀成 YAML 代码交接给 AI ，最大的阻力通常是什么？
如果觉得这里的实现思想有那么点意思，极其欢迎路过指点，或者试着提 PR 用你们最得意的“排障剧本”砸向。相比多添个连接器，这项目现在最缺的反而是真实战场的经验**剧本**，因为从这个架构看，Adapter 只是干活的苦力，**高度浓缩的 Runbook 才是真正的资产层。**
 | 1 DonaldY Mar 14 “ 现在很多 AI Agent 的“线上排障”方案，本质上还是把数据库只读账号、日志系统、Tracing 、Redis 这些工具接口一股脑暴露给模型，然后期待它自己查明白。” 看样子类似做了 skill （编写了排查步骤/经验）。 其实数据、系统封闭倒成问题，日志告警在一个平台、线上数据库本地没有权限直连（线上查询又是另一个平台）。 |
 | 2 bimeixishuai OP 为什么发布前 markdown 格式还没问题，发布完就成这样了 |
| &nsp; 3 bimeixishuai OP @DonaldY 你说得对，确实是 skill 这类东西出来以后，我才有了这个想法的。 我真正想做的重点也是把排障经验和步骤固化下来，不是强调 Agent 直接拿线上 DB/Redis 权限。 文里这点我确实写得有点理想化了。真实落地时，更合理的接法应该是走企业内部已经封装好的日志/查询/观测平台，runbook 是上层逻辑，底层不一定是裸连生产系统。 反过来说，我现在也越来越觉得，adapter 层本身未必最难，真正难的是把团队里那些知道先查什么、什么证据算数的经验沉淀下来。 |
| 4 bimeixishuai OP 别收藏了，快来讨论哇 |
Select Language