# 2026-05-25 Multi-Agent 分层诊断提交记录

这份文档记录 `multi-agent` 分支今天围绕分层诊断 evaluation 做过的提交。由于其中一部分 commit 是从其他分支 cherry-pick 过来的，本文不按提交时间判断范围，而是从 `强化分层诊断关键证据交接` 开始按 commit 顺序整理。

## 提交范围

| 顺序 | Commit | 标题 | 说明 |
| ---: | --- | --- | --- |
| 1 | `487317e` | 强化分层诊断关键证据交接 | 分层诊断第一轮 evidence handoff 强化。 |
| 2 | `705dacb` | 稳定分层诊断证据与容量分类 | 补强容量类、worker 类信号，稳定 evidence 输出。 |
| 3 | `9f2cd98` | 稳定分层诊断证据采集并同步分支环境配置 | 继续补强 collector，并同步 `dev-multi-agent` 环境配置。 |
| 4 | 本次提交 | 记录分层诊断评测结果 | 上传 2026-05-25 evaluation artifacts，并记录 10 case 对比报告。 |

## 1. `487317e` 强化分层诊断关键证据交接

这个提交的目标是让 evidence-agent 和 diagnosis-analyst 的交接更结构化，减少诊断阶段重新解释原始数据时的漂移。

主要改动：

- 在 `evidence-agent.md` 中强化 evidence handoff 要求，让 evidence 输出包含更明确的 critical evidence、routing hints 和诊断约束。
- 在 `diagnosis-analyst.md` 中要求诊断阶段基于 evidence-agent 的结构化输出进行判断，而不是重新从零散证据中自由推断。
- 新增或扩展 `evidence-agent-output.schema.json` 与 `diagnosis-analyst-output.schema.json`，让两个 sub-agent 的输出边界更清晰。
- 在 `collect_evidence.py` 中补充 critical evidence hints，让 collector 直接沉淀一些后续诊断需要消费的关键信号。
- 增加对应测试，覆盖 collector 输出和 orchestration 配置。

涉及文件：

- `agentkit/config/investibook/agents/evidence-agent.md`
- `agentkit/config/investibook/agents/diagnosis-analyst.md`
- `agentkit/config/investibook/schemas/evidence-agent-output.schema.json`
- `agentkit/config/investibook/schemas/diagnosis-analyst-output.schema.json`
- `agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py`
- `backend/tests/test_collect_evidence_tikv_thread_cpu.py`
- `backend/tests/test_diagnosis_orchestration_config.py`

## 2. `705dacb` 稳定分层诊断证据与容量分类

这个提交进一步补强 capacity / worker 相关 evidence，主要服务于 `cpu-spike`、`sustained-cpu-pressure`、`system-unavailability` 这类 case。

主要改动：

- 增加容量变化、worker 异常、component health 等信号在 evidence 输出中的显式表达。
- 强化 diagnosis-analyst 对 capacity classification 的使用要求，避免把容量类问题误收敛成普通 query bottleneck。
- 补充 collector 测试，确保新增信号稳定生成。

涉及文件：

- `agentkit/config/investibook/agents/evidence-agent.md`
- `agentkit/config/investibook/agents/diagnosis-analyst.md`
- `agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py`
- `backend/tests/test_collect_evidence_tikv_thread_cpu.py`
- `backend/tests/test_diagnosis_orchestration_config.py`

## 3. `9f2cd98` 稳定分层诊断证据采集并同步分支环境配置

这个提交把前面分层诊断的本地修复同步到 `multi-agent` 分支，并补齐独立 dev 环境配置。

主要改动：

- 继续增强 `collect_evidence.py`，让 evidence collector 在 component health、容量变化、关键日志和查询证据之间形成更稳定的诊断交接信息。
- 补充 `test_collect_evidence_tikv_thread_cpu.py` 中的 evidence collector 单测。
- 新增 `deployment/kustomize/envs/dev-multi-agent/agent-config.yaml`，让 `multi-agent` 分支可以使用独立的 agent config，避免和 main dev 环境互相影响。

涉及文件：

- `agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py`
- `backend/tests/test_collect_evidence_tikv_thread_cpu.py`
- `deployment/kustomize/envs/dev-multi-agent/agent-config.yaml`

## 4. 本次提交：记录分层诊断评测结果

这个提交不包含新的诊断代码，只上传 evaluation 结果和分析文档。原因是本轮 focused log context window 试验对 `component-restart` 有小幅帮助，但对 `panic` 没有证明有效，因此先不进入 `multi-agent` 分支。

主要内容：

- 新增 2026-05-25 的完整 evaluation 报告。
- 上传 3 个关键 eval artifact，方便 reviewer 不用重新跑即可查看细节。
- 明确记录当前 evidence 进展：10 个 case 中 7 个达到 critical evidence 30/30。
- 明确记录剩余 evidence 缺口：`component-restart`、`panic-in-recoverable-goroutine`、`sql-tail-latency-spike`。

涉及文件：

- `docs/plans/2026-05-25-multi-agent-layered-evaluation-results.zh.md`
- `backend/data/eval_audits/evalrun-50ca4bf7efdd41b4b1fc13100cb63698/`
- `backend/data/eval_audits/evalrun-948065d0468b41adadded97137d05142/`
- `backend/data/eval_audits/evalrun-ad7c959992214f67b1e3fe910e26dae8/`

## 今天代码改动的实际含义

今天这组代码改动，不是把某几个 case 的缺失点按 case id 硬编码进去，而是把之前解析比较薄弱、容易被 agent 忽略的证据源，做成更结构化、更容易消费的 evidence，并通过 sub-agent 的 prompt、schema、collector 和测试一起约束下来。

最核心的是几块：

1. Loki log 增强

   以前更多是按组件和 level 做聚合计数，比如 TiDB 有多少 ERROR、WARN。现在额外加了 focused raw log samples，专门抓 panic、query interrupted、kill query、OOM、restart、timeout、backlog、unavailable、coprocessor 这些诊断关键字。

   这样 agent 不只是看到“ERROR 很多”，而是能看到“日志里有没有具体 panic / interrupted / OOM / timeout 信号”。

2. component health 增强

   以前 component count 更像粗粒度变化统计。现在会记录 `first / last / min / max / net_delta / max_to_last_delta / change_count`，对 Premium 的 coprocessor-worker capacity loss、节点数变化、restart 这类 case 更友好。

3. evidence-agent / diagnosis-analyst 交接增强

   以前 evidence 和 diagnosis 的边界比较松，diagnosis 阶段容易重新从零散原始数据里自由发挥。现在 prompt 和 schema 都要求 evidence-agent 把关键证据、缺失证据、critical evidence hints、下一步推荐 skill 明确写出来，再交给 diagnosis-analyst 消费。

   这部分的目标不是让 evidence-agent 判断根因，而是让它把“我看到了什么、没看到什么、哪些信号值得后续诊断关注”说清楚。

4. schema 和测试固化

   新增或扩展了 evidence-agent / diagnosis-analyst 的输出 schema，并补充测试覆盖 collector 输出、agent 配置和 orchestration 约束。这样这些结构化信号不是只写在 prompt 里的建议，而是能被测试和 evaluation artifact 稳定检查。

5. 独立 multi-agent 环境配置

   `dev-multi-agent` 的 agent config 也同步进来了，目的是让分层诊断分支可以在独立环境里跑，不和 main dev 环境互相影响。

总体来说，今天的代码不是在给 agent 演示怎么诊断，而是在把薄弱数据源解析成 agent 更容易消费的证据形态，并把 evidence-agent 到 diagnosis-analyst 的交接协议收紧。后面的 diagnosis sub-agent 不需要自己从一堆 raw metrics/logs 里猜，至少能先拿到稳定、结构化、可回归的信号。

## Evaluation 结果摘要

只看 critical evidence，本轮结果是正收益：

| 指标 | Baseline | 当前 |
| --- | ---: | ---: |
| critical evidence 平均分 | 21.6 / 30 | 25.0 / 30 |
| evidence 满分 case 数 | 5 / 10 | 7 / 10 |
| evidence 提升 case 数 | 4 / 10 | 4 / 10 |
| evidence 持平 case 数 | 5 / 10 | 5 / 10 |
| evidence 回退 case 数 | 1 / 10 | 1 / 10 |

三个未满分 case：

| Case | Baseline | 当前 | 变化 | 缺口 |
| --- | ---: | ---: | ---: | --- |
| `component-restart-during-incident-window` | 0/30 | 10/30 | +10 | 仍缺 direct panic 和 query interruption 日志信号。 |
| `panic-in-recoverable-goroutine` | 30/30 | 10/30 | -20 | 缺 recoverable panic 直接证据和 query timeout interruption 信号。 |
| `sql-tail-latency-spike-during-incident-window` | 20/30 | 20/30 | 0 | 缺 heap path 与 upstream known issue / fixed release 的关联证据。 |

## 当前判断

今天这组提交已经把 evidence 采集和交接从“散落在主诊断流程里”推进到“sub-agent 可消费的结构化 evidence”。从 evaluation 看，证据层确实变稳了；下一步应该继续优先补齐剩余 3 个 evidence case，再进入 diagnosis 阶段优化。

本轮暂不提交 focused log context window 试验代码。它对 `component-restart` 有一点帮助，但不是 restart/panic 类问题的根治方案。更好的方向是补充日志不可用时的 fallback evidence，例如 Prometheus panic counter、component restart、Activity Hub、known bug / fixed release 关联等结构化信号。