# Diagnosis Knowledge Orchestration Phase 0 设计范围 **Date:** 2026-05-06 **Status:** Scope design **Parent design:** `docs/plans/2026-05-06-diagnosis-knowledge-orchestration-code-architecture.zh.md` **Research input:** `docs/research/2026-04-21-diagnosis-knowledge-orchestration.zh.md` --- ## 1. Phase 0 目标 Phase 0 的目标不是实现完整 runtime 编排，而是先把诊断知识的形态从“大入口文档”调整为可治理的开放结构。 Phase 0 只做三件事： 1. **把 `tidb-clinic-diagnosis` 从大文档入口改成短入口 + 开放 orchestration 设计。** 2. **把 `tidb-knowledge-base` 从流程型 skill 收敛为 KB 资产目录。** 3. **精简静态 prompt，避免 system prompt、diagnosis skill、KB skill 重复承载同一套诊断 SOP。** Phase 0 的核心设计原则： - 诊断不是固定 pipeline。 - Frame 只表达大的分析形态。 - Action 才表达具体诊断动作。 - Guard 按 action / claim 选择，不全量注入。 - Evidence 是 action 需要时调用的辅助协议，不是主流程。 - KB 只提供事实资产，不控制诊断流程。 --- ## 2. 为什么先做 Phase 0 当前问题不是缺少更多规则，而是规则和流程被堆在几个大入口里： - 入口 Skill 太大，agent 一读就带入大量无关上下文。 - System prompt、diagnosis skill、KB skill 重复描述 Step A/B、metric routing、pitfall。 - Guard 没有清晰注入条件，容易要么漏掉，要么全量塞入 context。 - Evidence collection 被混入诊断流程，导致工具动作和分析状态边界不清。 Phase 0 先解决“知识应该放在哪里、什么时候读、以什么粒度读”的问题。 --- ## 3. 实体边界 ### 3.1 Diagnosis Skill 负责： - 诊断入口判断。 - 引导读取 orchestration。 - 保留极少量全局硬边界。 - 路由外部专项 skill。 不负责： - 完整 SOP。 - 全量 guard。 - KB 事实正文。 - 固定 pipeline。 ### 3.2 Orchestration 负责： - 描述 Frame / Action / Guard / Evidence 的关系。 - 告诉 agent 如何从当前 Frame 选择候选 Action。 - 告诉 Action 如何选择 Guard 和 Evidence。 不负责： - 写长篇诊断正文。 - 变成 backend workflow engine。 - 强制所有诊断按一个线性顺序走。 ### 3.3 Frame 负责： - 表达当前诊断的大分析形态。 - 定义这个形态下应产出的粗粒度结果。 - 暴露候选 Actions。 Phase 0 推荐保留少量 seed frames： - `intake` - `entry-triage` - `component-investigation` - `crosscheck` 这些只是初始分析形态，不是永久固定 pipeline。 ### 3.4 Action 负责： - 定义具体诊断动作。 - 声明前置条件。 - 声明需要的输入和证据。 - 声明 guard selector。 - 声明成功、失败、不确定分别说明什么。 Phase 0 推荐优先覆盖少量高价值 Actions： - tier / metric scope 解析。 - entry signal 分类。 - CPU saturation 检查。 - TopSQL 与 hot node 相关性检查。 - panic 分类。 - Expensive Query 入口检查。 这些 Action 的目标是证明设计粒度，而不是穷尽所有诊断路径。 ### 3.5 Guard 负责： - 约束 Action 或 Claim。 - 防止错误归因。 - 定义必须检查的反例。 - 为后续 deterministic validation 提供规则来源。 Guard 不应该因为进入某个 Frame 就全量注入。它应该按 selector 过滤： ```text frame + action + evidence_intent + component + metric + symptom + claim_type ``` ### 3.6 Evidence 负责： - 说明 action 如何读取或补充证据。 - 说明工具失败时如何降级。 - 说明证据不足时如何表达 unknown。 Evidence 不负责： - 决定下一步诊断路径。 - 主动进入每轮 context。 ### 3.7 KB 负责： - tier architecture。 - metric routing facts。 - known incorrect conclusions。 - official docs index。 KB 不负责： - 诊断流程编排。 - Action 选择。 - Guard 注入。 --- ## 4. 注入策略 Phase 0 的注入策略是“先索引，后正文；先选择，后读取”。 | 场景 | 应读取什么 | 不应读取什么 | | --- | --- | --- | | 刚命中诊断 | 短入口 + orchestration | 全部 SOP / 全部 guards | | 进入 Frame | 当前 Frame brief | 所有 Frame 正文 | | 选择 Action | 当前 Action card | 所有 Action 正文 | | Action 需要数据 | Evidence protocol 的相关部分 | 全部工具说明 | | 准备归因 | Guard index + 命中 guard detail | 全量 guard catalog | | 需要事实 | KB index 或精确 KB asset | 全量 KB JSON | 避免遗漏的机制不是“全量注入”，而是： - Action 声明 required evidence。 - Action 声明 guard selector。 - Action 声明 success / failure outputs。 - Crosscheck 在最终 claim 前再做 guard selection。 - Phase 2 再由 backend 检查 required evidence / selected guard 是否缺失。 --- ## 5. Issues 覆盖范围 Phase 0 能覆盖“诊断路径和判断规则不稳定”的问题，但不能解决工具脚本、数据源、UI 或第三方集成错误。 Phase 0 可作为验收的方向： | Issue | Phase 0 设计覆盖 | | --- | --- | | `#270` TopSQL multi-hotspot ranking lacks hot-node correlation rule | 通过 TopSQL-hot-node correlation Action + Guard 覆盖 | | `#245` Panic 告警诊断应优先查找和分类 panic 日志 | 通过 panic classification Action 覆盖 | | `#243` 未区分正常 panic 和异常 panic | 通过 panic classification Guard 覆盖 | | `#382` CPU 降噪不足 | 通过 CPU saturation Action + CPU quota/limit Guard 覆盖 | | `#257` Expensive Query 应优先查 slow query | 通过 Expensive Query Action 的 routing 规则部分覆盖 | Phase 0 只能部分缓解： - 首轮诊断耗时过长：入口变短会有帮助，但证据采集和 LLM 链路耗时不在 Phase 0。 - TopSQL 数据不可用：Action 可以要求显式降级，但数据源错误需要工具层修复。 - Clinic / Grafana 深链：Action 可以要求引用 evidence links，但链接生成和 UI 展示不在 Phase 0。 Phase 0 不覆盖： - Loki / Activity Hub 脚本错误。 - `collect_evidence` 与 `clinic-cli` 统一。 - Lark / Jira 集成问题。 - UI 欢迎语 / use case 配置。 - OpenCode 模型成本、循环、上下文底层问题。 --- ## 6. Phase 0 Scope ### 6.1 Scope In - 收敛 `tidb-clinic-diagnosis` 的入口职责。 - 定义 Frame / Action / Guard / Evidence / KB 的边界。 - 建立开放 orchestration 的设计，而不是固定 pipeline。 - 定义首批 seed frames 和 seed actions 的选择原则。 - 定义 guard index + guard detail 的按需读取原则。 - 收敛 `tidb-knowledge-base` 为资产目录。 - 精简静态 prompt 中重复的诊断 SOP。 ### 6.2 Scope Out - 不实现 runtime state。 - 不实现 backend validation。 - 不实现 Knowledge Unit generator。 - 不修改 evidence 工具行为。 - 不修改默认 skills。 - 不修改 UI。 - 不做全量 nutshell skills 迁移。 --- ## 7. Phase 0 完成标准 Phase 0 完成后应该满足： - 诊断入口不再是大 SOP 文档。 - 诊断流程不再被描述为固定 pipeline。 - 具体诊断能力以 Action 形式表达。 - Guard 具备按需选择模型，不要求全量注入。 - Evidence 明确是 Action 依赖，不是主流程。 - KB Skill 不再复述诊断流程。 - Static prompt 不再重复 KB Step A/B 和完整 metric routing。 - 后续新增规则时，优先判断它是 Action、Guard、Evidence 还是 KB Fact，而不是继续塞进入口文档。 --- ## 8. 后续 Phase 边界 ### Phase 1：结构化生产 目标： - 把 Frame / Action / Guard / Fact 从手写文档升级为结构化 Knowledge Units。 - 生成可读文档和索引。 - 用 CI 检查重复、冲突、无效引用和缺字段。 不做： - 不做 runtime 自动推进。 - 不做 RAG。 - 不阻塞用户输出。 ### Phase 2：运行时保障 目标： - 记录当前 Frame、候选 Actions、已完成 Actions、selected Guards、missing Evidence。 - 给 agent 注入短 orchestration guidance。 - 对高置信 guard 做 deterministic warning。 不做： - 不替 agent 做完整诊断推理。 - 不做强 workflow engine。 - 不让 Frame / Action 变成独立 Skill。 --- ## 9. 主要风险 | 风险 | 控制方式 | | --- | --- | | Action 爆炸 | 只有可独立进入、可独立完成、会改变下一步的动作才是 Action | | Selector 过度复杂 | Phase 0 只保留少量核心 selector 维度 | | Guard 漏注入 | Action 声明 guard selector，Crosscheck 再按 claim 复核 | | Context 继续膨胀 | 入口短、索引短、Action 小、Guard detail 按需读 | | 过早做 workflow engine | Phase 0 只做文档边界，Phase 2 也只做 guidance / warning | | 旧规则迁移遗漏 | 每条旧规则必须归类为 Frame、Action、Guard、Evidence、KB 或 discard | --- ## 10. 设计结论 Phase 0 的重点不是“先拆几个 stage”，而是建立长期不会劣化的实体边界： ```text Frame 少而稳定 Action 小而可验证 Guard 按需过滤 Evidence 只服务 Action KB 只提供事实资产 Prompt 只放全局规则 ``` 只有这个边界稳定后，才应该进入具体文件改造。