LLM 的「自觉」不可靠 —— 所以用确定性的工程机制,同时约束它的判断和它的行动。
一个可复现的多 Agent 故障根因分析(RCA)实验: 它诊断一个自建的三服务系统,并把**"测量本身可信"当成第一目标 —— 包括诚实地报告一个否定自己的结论**。
📌 想直接看结论:
demo/rca-demo.html(双击打开,无需服务器)。 那个页面由存档生成、可逐字节重放,不花一分钱就能核对本文里的每个数字。📌 进度 / 计数 / 封堵状态一律看
docs/00-状态.md—— 那是唯一权威,本文不复制。
多 Agent 没有可测的价值增量 —— 而且更贵、更差。
同一个世界、同一套评分、同一个计价时段、同样的步数上限,两侧覆盖同样的 7 个场景:
| 单 Agent(baseline) | 多 Agent(三专员 + 交叉质证 + 裁决) | |
|---|---|---|
| 样本 | 21 次尝试(7 场景 × 3 轮) | 21 次尝试(同样的 7 场景 × 3 轮) |
| 准确率 | 100% | 95.2%(存档判定为 90.5% —— 判据修过一次,见 #48) |
| 步数(LLM 轮次) | 8.3 | 28.8(3.5×) |
| 成本 / 次诊断 | ¥0.0172 | ¥0.0732(4.3×) |
多花 4 倍的钱、3.5 倍的时间,准确率没有任何优势。
⚠️ 幅度必须带上噪声带读:那 4.8 个百分点全部来自 F4 一个场景(multi 1/3、baseline 3/3), 而单场景每轮只有 3 次尝试 —— 同配置重跑 baseline,它在 F4 上自己就从 3/3 变成了 2/3。 所以能站住的是方向(三次配对里 multi 一次都没超过 baseline),不是幅度(见 harness-log #46)。
唯一的失败模式集中在 F4 一个场景(1/3):协调者把真正的根因(一个反向的配置漂移)
降级甚至驳回,同时把一条**没有基线对比的"安静指标"**提升成了根因。
我一度怀疑这是评分口径冤枉了它,于是去读代码、对存档实测、再让第二个尺子逐条复核 ——
两把尺子完全一致:不是尺子问题,它真的更差(见 docs/harness-log.md #44)。
但比这个结论更重要的是:它是被测量出来的,而一路上我八次得到过相反的结论
(第八次是反方向的:我差点替 multi 开脱)。每一次查下去都发现是尺子坏了
(评分把被否定的提及算作命中、场景的标准答案是反的、任务定义从没要求"找全"、
计价模型漏了法定节假日……)。
这八次翻案逐条记在 demo/rca-demo.html 第四节和 docs/harness-log.md 里。
| 不可靠的"自觉" | 本项目用的确定性机制 | |
|---|---|---|
| 判断面 | 单视角确认偏误:先看到 CPU 飙升,就一路去找流量证据 | 信息隔离(三个专员各自只看自己那一路遥测)+ 强制交叉举证(假设必须引用 evidence_id,机械校验)—— 已实现 |
| 行动面 | 模型"自己会小心" | 默认拒绝:ops 动作全部经过策略执行点(路径规范化 / 动词分级 / 隔离区 / 审计),并经 MCP 收口—— 诊断角色拿不到任何 ops 工具(见第三节) |
把软约束做成硬约束:交叉质证不是提示词里的一句话,而是协议层的检查 —— 假设没引用证据直接被驳回;引用的证据全在支持自己、没有一条能证伪他人,也要被驳回。
📊 一页图版本:
docs/架构图.svg(绿色实线 = 已实现,红色虚线 = 未接线,可直接投屏)
┌── Agent 编排(**手写循环**;LangGraph 已接线,见 graph_loop.py)─┐
│ baseline.py(单 Agent) │
│ specialist.py × 3(按角色限定工具面) │
│ coordinator.py(交叉质证 + 裁决) │
└──────────────────────────────────────────────────────┘
│ 经 MCP 收口(ops 工具面;诊断工具是进程内只读调用)
┌─────────────────┴────────────────────────────────────┐
│ 工具面:3 个**只读**工具 │
│ query_logs / query_metrics / get_changes │
│ 角色隔离:RestrictedToolBox ← 已实现且有用例 │
└──────────────────────────────────────────────────────┘
│ 只读遥测(原始遥测永不进入上下文)
┌─────────────────┴────────────────────────────────────┐
│ 遥测:接入 → 降维(压缩到 0.217%,信号全存活) │
└──────────────────────────────────────────────────────┘
│
┌─────────────────┴────────────────────────────────────┐
│ 被诊断世界:order → inventory → payment → 外部风控 │
│ 自建 FastAPI,8 种可注入故障,Redis,一条命令起全栈 │
└──────────────────────────────────────────────────────┘
已实现(每条都能指到文件/用例):
| 能力 | 在哪 |
|---|---|
| 三个 FastAPI 服务 + Redis,可注入 8 种故障 | world/、scripts/inject_fault.py、docs/04-故障目录.md |
| 遥测接入与降维(原始遥测不进上下文) | src/rca/telemetry/ |
| 角色隔离的工具面(3 个只读工具) | src/rca/tools.py(RestrictedToolBox) |
| 单 Agent 与多 Agent 两条诊断路径 | src/rca/agents/baseline.py、specialist.py、coordinator.py |
| 评测 harness(关键词主判 + LLM 裁判交叉校验、噪声带、存档、轨迹) | eval/runner.py、eval/judge.py |
| 策略执行点(路径守卫 / 动词分级 / 隔离区 / 审计) | src/rca/policy/(27 条用例)+ ops 工具的接线 src/rca/tools_ops.py、scripts/ops.py(14 条用例) |
| MCP 工具面收口(ops 三工具经 MCP 暴露,无旁路) | src/rca/mcp_server.py + scripts/ops_mcp_server.py(6 条用例 + 2 个变异体) |
| LangGraph 编排 + 循环级断点续跑(AC-10) | src/rca/agents/graph_loop.py + scripts/demo_resume.py(4 条用例 + 2 个变异体;评测数字仍出自手写循环,见 docs/adr/0001) |
| 错误封堵清单:一条错误只有在回归用例能变红之后才算封堵 | docs/harness-log.md + scripts/mutate_check.py |
未接线(写在 README 里就必须说清,见 docs/harness-log.md #41):
| 没有的东西 | 现状 | 这意味着什么 |
|---|---|---|
| 让诊断 Agent 自己动手 —— 未接线 | 诊断角色只有 3 个只读工具;ops 工具只由人的 CLI(scripts/ops.py)发起 |
这是刻意的:授权只能由人给。要让 Agent 动手,得先有"谁批准、怎么留痕"的流程 |
这一栏是刻意留在首页的。一个把"没做的部分"写在首页的项目, 比一个只在角落里标一句"未接线"的项目可信得多 —— 而可信是这个仓库要证明的唯一一件事。
git clone <repo-url> && cd rca-agent
uv sync # 依赖锁定在 uv.lock然后(Windows 下用 .\.venv\Scripts\python.exe 代替 uv run python):
| 想核对什么 | 命令 | 预期 |
|---|---|---|
| 上面的检查一次跑完 | make ci(= scripts/ci.ps1) |
与 .github/workflows/ci.yml 的离线作业同一条命令,本地实测通过 |
| 页面确实由存档生成 | uv run python scripts/make_demo.py |
git status 依然干净 —— 重放逐字节一致 |
| 文档里的成本构成 | uv run python scripts/cost_breakdown.py runs/_recordings/record-deepseek-flash.ndjson --list |
文件里有 3 次运行;--run 1 得到命中率 79.5% / 输出 72.3% |
| 全部回归用例 | uv run pytest |
全绿(数字见 docs/00-状态.md) |
| 封堵是不是空的 | uv run python scripts/seal_report.py |
每条"已封堵"都有变异组背书,退出码 0 |
⚠️ 跑 pytest 时不要再加-q:pyproject.toml的addopts里已经有-q, 再加一个会变成
要花钱的部分(真跑评测):需要 DEEPSEEK_API_KEY、需要起被测世界(Docker + Redis),
两侧合计约 ¥0.8。命令形如:
uv run python eval/runner.py --agent baseline --rounds 3 # 单 Agent,7 个场景
uv run python eval/runner.py --agent multi --faults F1,F8 --rounds 3 # 多 Agent,2 个场景--mode replay 可以完全从录制回放、不调 API(未命中会直接报错,不会悄悄花钱)。
这条机制已实测可用(2026-09-25,见 harness-log #53):把 API Key 换成假的、
DEEPSEEK_BASE_URL 指向 http://127.0.0.1:9(该端口无人监听)之后,
7 场景 × 3 轮 = 21 次尝试照样跑完(20 秒、exit 0)——
任何一次真实调用都会立刻失败,所以"零 API 调用"是实测的,不是推断的。
证据:runs/_replay_pack/ 里的包 + runs/_evidence/replay-zero-cost.md。
sha256(tag+model+messages),而 tag 里嵌着场景目录名
(specialist/metrics/r-20260925-072345 —— 那是一次故障注入的时间戳),
换一批目录必然第一步就 miss:
# 仓库自带一个演示包(replay_pack/,1.73 MB,F1+F8 两个场景)—— 克隆后直接就能跑:
# bash: export RCA_REPLAY_ROOT=replay_pack
$env:RCA_REPLAY_ROOT = "replay_pack"
uv run python eval/runner.py --agent multi --faults F1,F8 --rounds 1 --mode replay
# 想要完整 7 场景的包,就用你自己的 runs/ 重新打(日志 gzip 24 MB → 2.6 MB):
uv run python scripts/make_replay_pack.py --out runs/_replay_pack演示包随仓库提交(日志 1.03 MB + 裁剪后的录制 0.76 MB,录制从 643 条裁到 253 条)。
tests/test_replay_pack.py 里有一条真的重放一次的用例:它在毒化环境
(假 Key + 127.0.0.1:9)下跑完一次 F1,所以"零 API 调用"每次跑 CI 都被重新证明一遍。
--batch 在录的时候标批次、回放时指定同批
(--mode record --batch run-a / --mode replay --batch run-a);
指定了批次却找不到那条时直接报未命中,绝不串用别批的响应。
| 文档 | 内容 |
|---|---|
docs/00-状态.md |
唯一权威:进度、当前事实、下一步 |
docs/08-项目总览.md |
3 分钟看懂这个项目做了什么 + 导航表(建议先看这份) |
docs/01-需求分析.md |
为什么做、必须满足什么、什么叫做完 |
docs/02-技术方案与排期.md |
技术选型、架构设计、逐日排期 |
docs/03-事件流协议.md |
冻结的接口契约 |
docs/04-故障目录.md |
8 种故障 + 真值是否被对照实验验证过 |
docs/05-单Agent基线结果.md / 06-多Agent结果.md |
结果与证据索引(每个数字 → 存档 → 复现命令) |
docs/harness-log.md |
错误封堵清单:每一个缺陷的现象/根因/封堵/能变红的用例 |
docs/07-面试讲述稿.md |
3 分钟 / 10 分钟讲述 + 40 分钟追问准备 |
docs/09-演示视频分镜.md |
演示视频的分镜 / 命令 / 台词(录制前照这个准备) |
docs/10-护栏设计.md |
护栏:在 Agent 运行时看着它、提醒或拦截 —— 设计与验收形状(判据不许看标准答案,见 docs/adr/0007) |
docs/adr/ |
架构决策记录 |
- 多 Agent 现在也覆盖全部 7 个场景(此前只有 F1/F8),两侧样本对等;但每侧仍只有 3 轮, 轮间波动 14.3 个百分点(按当前判据算;同配置重跑,单场景的准确率差过 20 个百分点), 所以上面那句「95.2% vs 100% ⇒ 低了 4.8 个百分点」要连同噪声带一起读 —— 差落在带内
- 主结论只测了
deepseek-flash;deepseek-v4-pro只做过一次小样本对照 (两臂各 3 次尝试、max_steps=40:3/3 vs 2/3),不足以给幅度结论(#46) - 被诊断系统是自建的:故障是注入的,不是自然发生的;"根因"由我定义的判据裁定
- 评分主判据是关键词/判据式判定,LLM 裁判只做独立交叉校验(不参与正确性计算)
- 一条错误只有在回归用例能变红之后才算封堵;标记为"靠人"的流程缺陷没有自动化证明
- 这里的"安全"是机制,不是保证:任何守卫都可能被绕过
- CI 已在 GitHub Actions 上真跑过,两个作业都绿(2026-09-26 起,仓库公开在
github.com/Barney0809/rca-agent):离线门禁约 25 秒、需要 Docker 的世界集成约 1 分 19 秒; 本地等价门禁make ci(=scripts/ci.ps1)与它跑同一批命令。 第一次真跑就抓到两处"只在本机成立"的缺陷(归档里的trace_path是 Windows 反斜杠 ⇒ Linux 上交付页静默丢掉整段 trace;以及一个/healthz假设)—— 这正是"让它真跑"的价值 (#39/#42/#59 就是这么被发现的)
MIT