Skip to content
Barney0809Public

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rca-agent

ci Python license

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 动手,得先有"谁批准、怎么留痕"的流程

这一栏是刻意留在首页的。一个把"没做的部分"写在首页的项目, 比一个只在角落里标一句"未接线"的项目可信得多 —— 而可信是这个仓库要证明的唯一一件事。


四、自己核对(零成本,不需要 API key)

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, 再加一个会变成 -qq,pytest 会把结果行一起吞掉。

要花钱的部分(真跑评测):需要 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。

⚠️ 但它需要两样东西同时在场:录制文件 + 同一批场景目录。 因为录制 key 是 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 都被重新证明一遍。

⚠️ 两条如实写在这里、不写"已实现"的边界: ① 完整 7 场景包(4.4 MB)仍未入库,只有演示包入库; ② 回放复现的是"录制内部自洽的那条轨迹",不等于某一次归档运行 (同一批响应下归档判 19/21、回放判 21/21,21 次里 13 次步骤数不同)—— 想复现某一次运行,用 --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 就是这么被发现的)

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages