# 分类 Specialist 优先的诊断加载设计

## 目标与边界

常规诊断走「公共原则 → 标准分类 family → 对应 specialist」。
`tidb-clinic-diagnosis` 不再是一项默认必须全文读取的诊断手册，而是分类、工具和可选参考资料的容器。

本次不改变 collector 查询、并发、数据源、时间窗口、原始证据文件，也不改变 Copilot 的时间确认和分支选择交互。用户所选分支仍是待验证假设，不是指定答案。没有添加工单号、集群、固定错误签名或 expected RCA 到运行时 prompt。

## 真实运行依据

审计覆盖 2026-09-06 PR1165 的 8 次运行、2026-09-08 training 的 10 次运行、PR1185 定点复测的 2 次运行，共 20 次、18 个不同 case。

17 次进入 diagnosis-analyst，其中 13 次未观察到主 SKILL 正文读取，1 次只读取前 50 行，3 次完整读取历史版本的 576 行。17 次均读到至少一个 family、KB 和 diagnosis-overview，并尝试使用报告写入脚本。14 次由 evidence-agent 调用 collector，未观察到 investigator 或 analyst 调用 collector。

这支持明确已有模块化路径，但不能证明大上下文污染了模型，也不能证明拆分必然提升分数或耗时。读取、遵守规则、最终 RCA 正确是三个不同的验收项。

| Case | 已沉淀的 RCA / 证据要求 | 实际路径及偏差 | 本次处理 |
| --- | --- | --- | --- |
| progressive-resource-growth-during-steady-workload | statistics usage delta-map 保留导致 heap/GC CPU 随进程时间增长，重启暂时清空状态 | 没读主正文，仍从 KB 检查 GC 和机制证据 | 保留公共 KB/GC 要求；fallback 不再默认排除内部操作 |
| transaction-failure-during-concurrent-upsert | FK cascade savepoint 在内部悲观锁重试时丢失 | 全文和 TX handbook 都读了，仍沿 FK/事务机制分析 | 保留 TX 专项链；不把成功归因于是否全文读取 |
| checkpoint-catchup-slow-after-changefeed-resume | storage sink 单批 4096 事件上限与 flush interval 导致 checkpoint 积压 | family 提到 CDC specialist，但 catalog 缺失，analyst 转读大正文 | 补齐 catalog、真实路径、family 加载契约；不向 prompt 注入批量上限答案 |
| latency-surge-with-tikv-cpu-imbalance | 查询回表 seek 放大与 region leader 集中；具体索引需 schema/plan 证据 | AutoX 已加载，但 schema 未收集时仍给具体 DDL | SQL family 持有加载契约，显式服从 AutoX case-contract；不声称此改动已解决推理越界 |
| database-time-spike-with-storage-read-wait | 窗口内 cache miss/read wait；窗口外 kill query 不是触发原因 | 未读正文，主 agent 已把 disk IO 验证维度替换为 gRPC P99，后续拒绝 storage | 不归因于大正文；继续保留原有同维度验证/窗口规则，本次不改该 case 的结论模板 |

RCA 对照来源是仓库已标准化的工单评估材料，本次未重新访问 Jira 验证工单最新状态：

- [资源增长 expected](../../evaluation/regression/cases/progressive-resource-growth-during-steady-workload/expected.md)
- [事务重试 expected](../../evaluation/regression/cases/transaction-failure-during-concurrent-upsert/expected.md)
- [CDC checkpoint expected](../../evaluation/regression/cases/checkpoint-catchup-slow-after-changefeed-resume/expected.md)
- [SQL/TiKV expected](../../evaluation/regression/cases/latency-surge-with-tikv-cpu-imbalance/expected.md)
- [Storage read wait expected](../../evaluation/regression/cases/database-time-spike-with-storage-read-wait/expected.md)

可复查 trace：

- [CDC checkpoint](https://langfuse.dev.investibook.tidbcloud.com/project/investibook-dev/traces/781982e8307544ab8e275b3fb004ba11)：catalog read `tooluseHOaazKreM7dySq4IRJQFUG`；明确认为 specialist 不可用的 generation `e22e593e28274510bbd6a1e6664097f0`。
- [AWS SQL/TiKV](https://langfuse.dev.investibook.tidbcloud.com/project/investibook-dev/traces/2962cbd7dc4343199031ca86658e2f28)：AutoX case-contract read `toolusePImp9uwVtYg5I7IF1W4pYL`；schema 缺失时仍给索引建议的 generation `e96a4ca7bfed4c17bf78d47c4d946012`。
- [GCP Storage](https://langfuse.dev.investibook.tidbcloud.com/project/investibook-dev/traces/44ab82a7d9a54568a28457f4305091f6)：交接维度发生替换的 task `tooluseRddACuFdHbu4m3q3Xc4b6F`。

完整离线审计保存在本地 `outputs/clinic-skill-usage-audit-20260908/`，未把数百 MB 原始对话、凭证或客户产物提交到代码库。

## 加载流程

| 阶段 | Investigator | Evidence Agent | Diagnosis Analyst |
| --- | --- | --- | --- |
| 范围确认 | workspace 背景、必要时间转换；Web Copilot 时间确认 | 不提前采集 | 不启动 |
| 公共上下文 | catalog、tier architecture、pitfall catalog、diagnosis-overview | 按自己的采集模式加载 | 派发后读取相同公共诊断原则 |
| 采集 | 派发 sweep 或 targeted | 原 collector 或定向数据访问 | 不查询数据源 |
| 分类 | handoff + 标准分类表；Copilot 等用户选择，Autopilot 自动选择 | 返回原始证据及线索 | 尚不替用户预设结论 |
| 派发 | 只解析所选 family 的加载契约，传完整 required list | 必要时补采 | 读所有所选 family 及其 required specialist 后综合 |
| 改判 | 不强迫遵循用户假设 | 按具体缺口补采 | 加载最终分类所需知识后改判，记录 override |
| 输出 | 根据 analyst artifact 回复 | 不判断根因 | 使用原报告工具和 schema |

Task 不可用时的单 agent 降级沿用相同知识加载契约。ad-hoc、evidence-only 和 code 模式不因本次调整而进入 specialist 诊断。

## Specialist 与 Fallback

- SQL：详细 candidate/causal gate 从主正文移到 SQL family。任务明确选择 SQL 时必须先加载 AutoX，再接受或否定该假设；分析中额外发现 SQL 候选时，仍按机制证据决定是否加载，不能由 TopSQL 排名直接触发。
- TX：沿用 transaction handbook。多分支中明确选择 TX 时，不得因为已加载另一分支的 specialist 而跳过它。
- CDC：默认加载 ticdc-health-inspection 及其必读规则；只有证据涉及 TiKV/CDC 边界时才追加 tikv-cdc。仅复用诊断知识，不执行其新一轮健康巡检、直接采集或独立报告流程。
- 未部署 TiCDC 只说明健康检查不适用；若用户的问题就是创建未完成，不能用“未部署所以健康”关闭事件。
- 没有外部 specialist 的 family 可以独立完成诊断，不必自动进入 fallback。
- fallback 仅解决 family/specialist 尚未覆盖的明确推理问题，记录原因、实际读取章节。缺证据、低置信度、required specialist 丢失都不应自动触发全文阅读。
- required specialist 找不到时必须暴露 loading gap，不能静默用大正文替代并声称专项链完成。

## 文件拆分与冲突处理

- 根 `SKILL.md` 缩为入口与职责说明。
- `references/general-diagnosis-fallback.md` 保留通用诊断方法，默认不读。
- `references/evidence-collection.md` 保留独立采集示例和证据说明，不能成为 evidence-agent 新的 preflight。
- 分类 subskill、knowledge 文件、collector 和 raw reader 路径不变。
- 保留 analyst 原有 Task 描述中的简单问题直答与复杂问题派发边界，不通过本次 skill 拆分扩大 analyst 调用范围。skill 工具白名单允许已登记的四个 specialist；没有增加数据访问或采集命令权限。
- 报告工具不再根据默认值声明读过大手册。缺省仍填公共契约名称，family/specialist/fallback 必须由 agent 明确记录。这个字段不是读取证明，验收仍看 Langfuse 工具输出与后续 LLM 输入。

通用方法中三类绝对推断改为已有公共规则的口径：内部操作没有默认低于业务 SQL 的优先级；TopSQL top-N 缺失不是排除证据；EBS 信号必须验证时间与作用路径，不能自动等于根因。CPU/profile 深入检查保留为未解释问题的可选方法，不再要求 specialist 已满足证据契约后重复完整循环。没有改成偏向任何 case 的固定答案。

## 同批修复：证据时间范围保真

报告生成器从 collector summary 和 evidence-agent handoff 保留 hint 的
`time_scope`，防止 analyst 重写 hint 时遗漏或无依据改成 `canonical_window`。
hint ID 标识信号类型，不等于具体样本：补采 handoff 可用 `evidence_ref`
（workspace 内原始 JSON 文件 + JSON Pointer）引用新日志项。工具核对 handoff
与 analyst 的 cluster、原始项的实际时间戳及两个时间窗口，确认后允许新样本
作为支持证据，不被同 ID 的旧 summary 降级。只有标签或聚合桶时间不算确认；
未能定位原始项时仍保留限制。该检查验证引用和时间，不判断日志机制或根因。

旧样本继续保留在背景，显式引用旧证据仍被过滤；同 ID 的新样本与旧样本
分别处理。保留 analyst 状态/备注和原始 collector 数据，不改变采集流程。

这个修复与知识加载独立：不论 analyst 走 specialist 还是通用 fallback，
最终都经过报告写入。它只约束 hint 引用的时间语义，不声称验证了所有自然
语言根因陈述，也不证明 agent 已正确理解证据。

Review 补充：nodegroup 内同类比较、跨组说明容量与 workload 差异的基础规则
移到必读 `diagnosis-overview`，不依赖 fallback 是否加载。分析中改判为 CDC
主因同样要求 `ticdc-health-inspection`，报告改判校验同步检查 family 与该
specialist 的声明；`tikv-cdc` 仍按证据需要加载。实际读取仍由 Langfuse 复核。

补采样本校验与报告窗口校验共用边界解析函数，均接受 `start/end` 和 `from/to`。
handoff 与 analyst 使用不同格式，或起止字段使用混合别名，均按同一窗口判断；
格式差异不应降级有效证据，也不能放过窗口外样本。

## 验证与后续复测

两组修改及 review 修复合并后，本地完成 266 项测试：编排/加载契约、catalog 与实体文件/引用路径、skill 权限、SQL/TX/CDC 多分支边界、报告默认与实际 skill 列表、hint 时间限制恢复与支持证据过滤、补采样本引用/窗口核验及时间字段别名、collector/证据存储、报告 hydration 和 workspace 初始化。`git diff --check` 通过。

这些测试验证配置和文件契约，不证明模型遵循，也不是新一轮准确率或耗时结果。本次未发起 dev/prod 诊断、未改评分器或 expected。

已知既有契约差异：main 的 Task 描述允许 investigator 对明确简单问题直接结论，但 investigator 角色正文和 catalog 仍要求完整诊断派发 analyst。此次保留原有 Task 描述，不把撤回描述改动视为已经恢复简单诊断快路径；该边界需单独统一并验证，不能仅凭 hint matched 判断问题简单。

部署后定点复测建议：CDC checkpoint、SQL/TiKV、TX concurrent-upsert、GC/memory growth，再加无 specialist 的 storage case。每例新 workspace；Copilot 选择既定待验证分支，不把 expected RCA 当作用户输入。检查：

1. 选中的所有 family/specialist 都实际读取，且发生在 synthesis 之前；缺项要有具体失败记录。
2. 是否只有需要时才读 general fallback，是否写明原因和章节。
3. analyst 不执行采集；证据字段/窗口/unknown 语义不丢失。
4. 对照真实 RCA 检查机制证据、替代解释和建议边界，不能只看 skill 名字。
5. 单独记录 collector、analyst、报告写入耗时和 token。不要从旧样本加载率推断本次已加速。