# Diagnosis Knowledge Orchestration 设计 **Date:** 2026-05-06 **Status:** Design draft **Input:** `docs/research/2026-04-21-diagnosis-knowledge-orchestration.zh.md` + 当前 Skills / ACP runtime 现状 --- ## 1. 设计目标 把 TiDB 诊断能力从“大入口 prompt + 大 SKILL + 重复 KB 规则”的模式，收敛为一个开放、可扩展、低上下文成本的诊断编排系统。 核心目标： 1. **避免上下文膨胀**：不把所有 SOP、guard、KB、tool 协议一次性注入 context。 2. **避免规则遗漏**：每个具体诊断动作都声明前置条件、证据需求、guard 选择器和成功/失败输出。 3. **避免固定 pipeline 劣化**：诊断不是线性流水线，而是开放 action graph。 4. **保留 agent 推理能力**：系统提供结构、边界和确定性兜底，不替 agent 做完整诊断推理。 5. **让知识增长可治理**：新增 SOP / guard / fact 有单一事实来源，可生成、校验、回归。 --- ## 2. 核心模型 最终心智模型是： ```text Diagnosis Skill -> Orchestration Manifest -> Frames -> Actions -> Guards -> Evidence Protocol -> KB Assets -> Runtime State -> Validation ``` 这不是 `Stage + Guard`，也不是 `Stage + Action Type`。更准确的设计是： ```text Frame = 大的分析形态和状态边界 Action = 具体可进入、可完成、可验证的诊断动作 Guard = 对 action / claim 的约束，按 selector 注入 Evidence = action 需要时调用的数据协议 KB = 事实资产，不控制流程 Runtime State = 记录进度和缺口 Validation = 确定性后验证 ``` --- ## 3. 实体职责 ### 3.1 Diagnosis Skill `tidb-clinic-diagnosis` 是唯一诊断入口。 它负责： - 判断用户请求是否进入诊断。 - 引导 agent 读取 orchestration manifest。 - 保留少量全局硬规则，例如 ticket-only 不触发诊断。 - 路由到外部专项 skill，例如慢 SQL / query tuning。 它不负责： - 承载完整诊断 SOP。 - 承载所有 guard 正文。 - 承载 KB 事实正文。 - 写死诊断 pipeline。 ### 3.2 Orchestration Manifest Orchestration Manifest 是诊断编排索引，不是固定 pipeline。 它负责描述： - 有哪些 Frame。 - 有哪些 Action。 - Frame 下可以选择哪些 Action。 - Action 的前置条件、输入、证据需求、guard selector、输出和转移。 - Guard / Evidence / KB 的索引入口。 它不负责： - 写具体诊断正文。 - 写工具命令细节。 - 写长篇 guard 解释。 - 替 agent 决定唯一流程。 ### 3.3 Frame Frame 是粗粒度分析形态。 典型 Frame： - `intake`：确认诊断意图、cluster 范围、入口信号。 - `entry-triage`：判断入口类型，例如业务 SQL、panic、DDL、Expensive Query、内部操作。 - `component-investigation`：组件级分析形态，例如 TiDB / TiKV / PD / TiFlash。 - `crosscheck`：多源校验、反例排除、结论组织。 Frame 负责： - 定义当前诊断状态。 - 定义该状态下应该产出的大结果。 - 暴露可进入的 Action selector。 Frame 不负责： - 具体查 CPU。 - 具体分类 panic。 - 具体查 slow query。 - 全量 guard 注入。 ### 3.4 Action Action 是具体诊断动作，是避免遗漏的关键实体。 典型 Action： - `resolve-tier-routing` - `classify-entry-signal` - `check-cpu-saturation` - `correlate-topsql-hot-node` - `classify-panic` - `inspect-expensive-query` - `validate-root-cause` Action 负责声明： - 什么时候可以进入。 - 需要哪些输入。 - 需要哪些 evidence。 - 缺 evidence 时如何处理。 - 需要匹配哪些 guard。 - 成功后说明了什么。 - 失败或不确定说明了什么。 - 下一步可能进入哪个 Frame 或 Action。 Action 的设计原则： - 只有“可独立进入、可独立完成、会改变下一步”的动作才应该成为 Action。 - 不要把每个小判断都拆成 Action。 - Action 应该小而可验证。 ### 3.5 Guard Guard 是对 Action 或 Claim 的约束。 Guard 不跟着 Frame 全量注入，而是通过 selector 触发： ```text frame + action + evidence_intent + component + metric + symptom + claim_type ``` Guard 负责： - 防止错误归因。 - 定义必须检查的反例。 - 定义哪些结论不能说。 - 为后续 deterministic validation 提供规则来源。 CPU 示例： - 在 `entry-triage` 里查 CPU，只能作为 triage signal，不能直接写 root cause。 - 在 `component-investigation` 里查 CPU，需要证明 bottleneck，需要 quota / limit / duration / impact / correlation。 - 在 `crosscheck` 里写 CPU 结论，需要验证多源证据链和反例排除。 所以同一个指标可以出现在多个 Frame；真正决定 guard 强度的是 Action 目的和 Claim 类型。 ### 3.6 Evidence Protocol Evidence Protocol 是数据读取协议，不是 Frame，也不是主流程。 它负责： - 定义证据读取的通用约束。 - 定义时间窗口、工具输出、失败降级、unknown 表达方式。 - 被 Action 按需引用。 它不负责： - 决定诊断下一步。 - 主动注入到每轮 context。 - 承载具体结论规则。 ### 3.7 KB Assets `tidb-knowledge-base` 应该是事实资产目录。 它负责： - tier architecture。 - metric routing facts。 - incorrect conclusions catalog。 - official docs index。 它不负责： - 定义诊断流程。 - 决定进入哪个 Action。 - 复述 diagnosis workflow。 Action / Guard 在需要时引用 KB。 ### 3.8 Runtime State Runtime State 是 Phase 2 的轻量执行保障。 它记录： - 当前 Frame。 - 候选 Actions。 - 已完成 Actions。 - 已选择 Guards。 - 缺失 Evidence。 - 关键中间输出。 它不负责： - 替 agent 完整推理。 - 做强 workflow engine。 - 阻塞所有不符合流程的回答。 ### 3.9 Validation Validation 是后验证，不是主推理。 它负责检查高置信、可程序化的问题： - 结论声称 CPU 是瓶颈，但没有 quota / limit / duration / impact 支撑。 - ANALYZE 被写成主因，但 TopSQL CPU 不占优。 - 结论引用 statement count，但没有 affected rows 支撑。 - 跨 nodegroup 做无效对比。 首版以 warning 为主，不强阻塞用户输出。 --- ## 4. 注入策略 ### 4.1 什么时候注入什么 | 时机 | 注入内容 | 方式 | 防遗漏机制 | | --- | --- | --- | --- | | Session 初始化 | 全局规则、ticket-only gate、安全边界 | 静态 system prompt | 只放稳定规则 | | 命中诊断意图 | Diagnosis Skill + Orchestration Manifest | agent 读取 | 入口强制先读 manifest | | 进入 Frame | 当前 Frame brief | 按需读取 | Frame 声明 outputs 和 action selectors | | 准备执行 Action | Action card | 按 selector 读取 | Action 声明 preconditions / evidence / guards / outputs | | Action 需要数据 | Evidence Protocol 或工具 skill | 按需读取 | Action 声明缺 evidence 的 fallback | | 准备归因或结论 | Guard index + selected guard details | 先索引后正文 | Guard selector 防止全量注入 | | 最终输出前 | Crosscheck + conclusion guards | 按 claim 读取 | 结论必须满足 guard 或声明 unknown | ### 4.2 以什么方式注入 注入方式按粒度分层： - **静态注入**：只放全局稳定规则。 - **入口读取**：诊断触发后读取短入口和 manifest。 - **索引过滤**：先读 action / guard index。 - **按需正文**：只读命中的 Action / Guard / Evidence。 - **运行时提醒**：Phase 2 只注入短 guidance，例如当前 frame、候选 action、selected guard ids。 明确禁止： - 不把所有 guard 正文注入 context。 - 不把 KB JSON 注入 context。 - 不把 Evidence Protocol 当主流程注入。 - 不把所有 Actions 当作固定 pipeline 读完。 --- ## 5. 为什么不是固定 Pipeline 固定 Pipeline 只能表达常见顺序，不能表达诊断的分支、回跳和证据驱动特性。 典型问题： - CPU 可能只是 triage signal，也可能是 bottleneck proof，也可能是 final RCA claim。 - Panic 可能直接进入日志分类，也可能作为组件 crash 证据。 - Expensive Query 可能走 slow query、TopSQL、plan tuning 或 internal operation。 - Evidence 可能一开始完整，也可能某个 Action 才发现需要补采。 因此诊断应该是开放的： ```text Frame 给出整体分析形态 Action 根据前置条件动态进入 Guard 根据 action/claim 动态注入 Evidence 根据 action 需要动态读取 ``` --- ## 6. Phase 规划 ### 6.1 Phase 0：文档形态和编排边界 核心目标： - 把诊断主入口从大文档收敛为短入口。 - 建立 Frame / Action / Guard / Evidence 的概念边界。 - 把 `tidb-knowledge-base` 收敛为 KB 资产目录。 - 精简静态 system prompt，只保留诊断 gate 和全局稳定规则。 - 不改变 backend runtime，不改变工具行为，不改变 UI。 范围内： - 重构诊断 Skill 的文档结构。 - 定义 Orchestration Manifest 的概念和最小字段。 - 定义首批 Seed Frames 和 Seed Actions 的设计边界。 - 定义 Guard Index / Guard Detail 的按需读取原则。 - 明确 Evidence Protocol 是 Action 依赖，不是主流程。 - 明确哪些 open issues 可由规则化 Action / Guard 覆盖。 范围外： - 不引入 Knowledge Unit generator。 - 不实现 backend runtime state。 - 不实现 deterministic guard validation。 - 不改 evidence 采集工具。 - 不改默认 enabled skills。 - 不改 UI。 完成标准： - 入口文档不再承载完整 SOP。 - KB Skill 不再复述诊断流程。 - Guard 不再全量注入。 - Evidence 不再被建模成主流程。 - 后续新增诊断能力优先新增 Action / Guard，而不是扩充大入口文档。 ### 6.2 Phase 1：结构化知识生产 核心目标： - 把手写 Markdown 维护升级为结构化 Knowledge Units。 - 让 Frame / Action / Guard / Fact 有单一事实来源。 - 通过生成器生成运行时可读资产和索引。 - 通过 CI 校验重复、冲突、无效引用和缺失字段。 范围内： - 定义 Knowledge Unit schema。 - 引入 generator / validator。 - 生成 action index、guard index、runtime readable docs。 - 迁移少量高价值 guard / SOP 作为样例。 范围外： - 不做 embedding / RAG。 - 不要求 backend 自动推进 Action graph。 - 不把所有 existing skills 一次性迁入。 - 不让 guard validation 阻塞用户输出。 完成标准： - 新增规则不再直接修改大 Markdown。 - Guard 可按 selector 生成索引。 - Action 可声明 preconditions / evidence / outputs。 - 生成结果 deterministic，可 review。 ### 6.3 Phase 2：运行时执行保障 核心目标： - 在 backend 层做轻量 orchestration guidance 和 deterministic validation。 - 降低 agent 漏 action、漏 guard、漏 evidence 的概率。 - 把可程序化错误变成 warning / report metadata。 范围内： - 记录当前 Frame、候选 Actions、已完成 Actions、selected Guards、missing Evidence。 - 按当前状态注入短 guidance。 - 在结论写入或报告生成前执行高置信 guard validation。 - 把 validation 结果写入 evidence report。 范围外： - 不替 agent 做完整诊断推理。 - 不做强 DB workflow engine。 - 不让每个 Frame / Action 变成独立 OpenCode Skill。 - 首版不强阻塞用户可见输出。 完成标准： - ticket-only 不注入诊断 guidance。 - 诊断上下文可提示当前 Frame / candidate Actions / selected Guards。 - 缺 required guard 或 required evidence 时能产生 warning。 - 至少覆盖少量高价值 deterministic validation。 --- ## 7. 主要风险 ### 7.1 Action 爆炸 风险：每个小判断都变成 Action，导致选择困难。 控制： - Action 必须可独立进入、可独立完成、会改变下一步。 - 组件内部小细节优先留在 Action body 或 Guard，不急着拆新 Action。 - Phase 0 只定义少量 Seed Actions。 ### 7.2 Selector 过度复杂 风险：selector 维度太多，agent 匹配错。 控制： - 首版只使用少量核心维度。 - 可选维度不作为强依赖。 - Phase 2 再做 deterministic selector lint。 ### 7.3 Guard 漏注入 风险：依赖 agent 自己过滤，仍然可能漏。 控制： - Action 必须声明 guard selectors。 - 最终结论前按 claims 再做一次 guard selection。 - Phase 2 检查 claim 和 selected guards 是否匹配。 ### 7.4 Context 继续膨胀 风险：Frame / Action / Guard 都写太长，回到大 prompt。 控制： - 入口短。 - Index 短。 - Action 小。 - Guard detail 按需读。 - KB 大文件不进入 prompt。 ### 7.5 过早变成 Workflow Engine 风险：Phase 0/1 就做复杂 runtime engine。 控制： - Phase 0 只做文档边界。 - Phase 1 只做生成和校验。 - Phase 2 只做 guidance 和 warning，不做强执行。 --- ## 8. 总结 当前设计应收敛为： ```text Frame 少而稳定 Action 小而可验证 Guard 按需过滤 Evidence 只服务 Action KB 只提供事实资产 Runtime State 只做提醒和缺口记录 Validation 只做确定性兜底 ``` 这个模型的重点不是“设计一个更复杂的 pipeline”，而是避免系统再次劣化成一个越来越大的 prompt。