@fx-data/ai-diagnostics 0.1.20261027064707 → 0.1.20261107142011

package/content/docs/diagnostic-feedback.md

@@ -1,63 +1,45 @@
 # 诊断后的需求反馈
 
-反馈用于持续优化 `core-ai` 的诊断能力、工具、知识和文档。助手根据本轮已有材料整理反馈，不依赖使用者具备产品代码环境，也不要求使用者定位产品代码、设计技术方案、制定验收条件或跟踪处理状态。
-
-交付诊断结果时，检查本轮是否发现知识缺口、项目改进机会，或文档与运行记录的差异。有证据支持时，在结果后附上简短的“需求反馈”；没有则省略。诊断的完成条件不变，也不为补齐反馈扩大查询。
+反馈用来持续改进 `core-ai` 的诊断能力、工具、知识和文档。助手根据本轮已有材料整理，不要求使用者定位代码、设计方案、写验收条件或跟踪进度。诊断中确实发现知识缺口、改进机会或文档与记录不符、且有依据时，在结果后附一段简短的“需求反馈”；没有就省略，不为反馈拉长回答或扩大查询。
 
 ## 什么情况需要反馈
 
-- 场景补充：本轮遇到现有知识未覆盖的普通报错、结果异常、偶发问题、指标、计算机制或性能现象，且已有材料能说明缺少哪种判断方法。例如错误已记录，但知识没有说明如何区分请求条件问题与依赖失败；或现有方法无法区分两种等待。本次问题已经定位，知识却缺少相应条件与反证时，也可反馈。写清已确认事实、尚不能判断的部分，以及希望补充的能力；单次猜测不写成通用规律。
-- 优化项：本次诊断中实际遇到的重复取证、信息遗漏、不必要追问、工具或解析限制、说明难以理解等项目改进机会。说明遇到的问题和期望改善；有明确方向时可附建议，不要求使用者提供解决方案，不承诺收益。
-- 文档差异：给出实际使用的文档章节或链接、文档描述及本次不同的观测。先按[知识适用性](../knowledge/common/knowledge-applicability.md)核对操作、版本、配置、字段口径和覆盖范围；确认在适用范围内矛盾时标为“已确认不一致”，范围尚未核实时标为“待核实的文档差异”。
-
-反馈限于当前问题中已遇到、能用已有记录复核的事项。空结果、字段缺失、截断和未完成分页不能单独证明文档错误。采集、工具或解析限制确实影响定位时，可以提出优化项；尚未确认的根因仍列在诊断缺口中，不自动转成需求。
-
-已核实的解析口径问题、规则冲突或工具限制，即使本轮已绕过、没有影响业务结论，也应随答复反馈，不能只留在内部调查记录中。说明本轮如何避免误判，以及后续使用时仍可能造成的影响。
+- **场景补充**：遇到现有知识没覆盖的报错、结果异常、偶发问题、指标、计算机制或性能现象，且材料能说明缺了哪种判断方法（比如知识没说怎么区分请求条件问题和依赖失败）。问题已定位、知识却缺相应条件和反证时也算。写清已确认的、还判断不了的、希望补什么；单次猜测不写成通用规律。
+- **优化项**：本次实际遇到的重复取证、信息遗漏、不必要的追问、工具或解析限制、说明难懂。说清问题和期望改善，有方向可附建议，不承诺收益。
+- **文档差异**：给出文档位置、原描述和本次不同的观测，先按[知识适用性](../knowledge/common/conclusions.md#知识适用性)核对版本、配置、字段口径和范围。确认在适用范围内矛盾标“已确认不一致”，范围没核实标“待核实的文档差异”。
 
-观测已被文档中的兼容或回退规则解释，且没有额外判断缺口时，不列为“待核实的文档差异”。版本未知本身不能证明需要补充文档。
+只反馈本次遇到、能用已有记录复核的事。空结果、字段缺失、截断、分页没读完都不能单独证明文档错了；没确认的根因留在诊断缺口里，不转成需求。已经核实的解析口径、规则冲突或工具限制，即使本轮绕过去了也要反馈，说明怎么避免误判、以后还会有什么影响。已被文档里的兼容或回退规则解释的观测，不算文档差异；版本未知本身也不证明要补文档。
 
 ## 怎样写成可转交的反馈
 
-每项用少量文字说明：
-
-1. 问题：反馈类型、触发现象，以及当前知识或工具在哪项判断上不足。
-2. 复核依据：对应操作、环境、时间和已取得的执行或产物位置；文档差异附文档位置、原描述和实际观测。
-3. 影响与期望：本次造成的影响、希望怎样改善，以及仍需核实的点。有明确改进或验证方向时可附建议，没有时只反馈问题。
-
-依据复用本次诊断材料并脱敏，不复制原始大日志、凭据或完整业务载荷。只引用已取得的链接；没有链接时保留已确认的 trace/task 等标识。预期收益与已测量结果分别表述，物理算子差异不能直接推导业务配置变化或唯一根因。
+每项几句话：
 
-补充场景时，保留复核所需的最少字段、原值、单位、统计对象和关联关系，以及已确认条件、反证和未知项。临时产物路径只供本轮复核，转交材料不能只引用当前机器可读的路径；无需为反馈获取新的业务载荷。
+1. **问题**：反馈类型、触发现象，知识或工具在哪项判断上不足。
+2. **复核依据**：对应操作、环境、时间和已取得的执行或产物位置；文档差异附文档位置、原描述和实际观测。
+3. **影响与期望**：本次造成的影响、希望怎么改善、还要核实什么。
 
-例如，统计中已有内存信息，但本轮需要反复读取完整报告才能提取，可反馈“已取得统计后仍多次读取才能回答内存问题，期望首次解析直接展示内存及来源，并保留完整报告入口”。如果文档描述的字段位置与本次记录不同，但版本适用范围未知，应反馈“待核实的文档差异”，附文档描述和实际观测，不直接判定文档过期；适用信息从已有材料核对，不要求使用者寻找内部发布标识。
+依据复用本次材料并脱敏，不贴原始大日志、凭据或完整业务载荷；只引用已取得的链接，没有链接就留 trace/task 标识。保留复核所需的最少字段、原值、单位、统计对象和关联，以及已确认条件、反证和未知项；临时文件路径只在本机有效，不能当作转交依据。预期收益和已测结果分开说。
 
-场景补充示例：“本次聚合节点已有 main/secondary arena 的内存记录，但知识未解释这些状态，定位仍需额外确认。现有材料显示两类状态分别占用内存；具体值、单位及任务见上述依据。期望补充字段含义、适用聚合方式和判断方法，两者是否同时驻留仍待核实。”
-
-业务结论尚未成立时，将待确认原因留在诊断缺口中，另行反馈已有证据证明的知识或工具限制。仅缺少材料、没有项目能力问题依据时，省略反馈；已覆盖的常规案例也无需重复反馈。
+示例：“已取得 Metric 后仍多次读取正文才找到内存字段，期望文档指明内存字段的位置和读法。”文档写的字段位置和本次不同、但版本适用范围未知时，反馈“待核实的文档差异”，附原描述和实际观测，不直接判定文档过期。
 
 ## 非性能案例怎样保留
 
-普通报错、结果异常和偶发问题，按已有材料保留能帮助下次判断的信息。未知项说明未知，不为填写反馈追加查询或追问。
+按已有材料保留能帮下次判断的信息，未知的写未知，不为填反馈追加查询：
 
-| 问题 | 优先保留的案例信息 |
+| 问题 | 优先保留 |
 |---|---|
-| 普通报错 | 触发操作、错误签名、错误前后的关键记录、已有定位线索，以及每次必现还是偶发 |
-| 结果异常 | 预期与实际的脱敏最小差异、筛选条件、时间范围、权限和数据更新状态，以及已发现的条件差异 |
-| 偶发问题 | 已知发生时间与频率、影响范围、持续时间、恢复方式，以及已有正常样本与异常记录的区别 |
-
-同时说明提出过哪些候选原因、哪些记录帮助区分它们，以及哪些方向已排除或仍待核实。未确认的原因继续保留为假设；已有证据证明缺少判断方法时，可据此提出场景补充，不必等完整根因确认后才反馈。
+| 普通报错 | 触发操作、错误签名、前后的关键记录、定位线索，必现还是偶发 |
+| 结果异常 | 预期和实际的脱敏最小差异、筛选条件、时间范围、权限和数据更新状态 |
+| 偶发问题 | 发生时间和频率、影响范围、持续时间、恢复方式，正常和异常记录的区别 |
 
-后续取得复核结果或用户纠正时，更新原项反馈中的判断和依据，保留反证与适用范围，避免把同一案例重复整理成多项需求。只使用本次调查及后续已提供的材料，不为完善案例额外取证。
+同时写清提过哪些候选原因、哪些记录帮着区分、哪些已排除或待核实。确认缺判断方法时就可以提场景补充，不必等根因确认。之后有复核结果或用户纠正时，更新原来那项，不重复成多项需求。
 
 ## 谁汇总与反馈
 
-专项分析把相关反馈线索、依据和适用限制交给当前调查负责人，复用已有调查与证据。最终交付方合并重复事项，保留相互矛盾的证据，随结果反馈一次。直接解读 Metric、解释更新记录和非性能辅助诊断也按此处理。
-
-默认反馈到当前对话，作为可转交的需求草案；不自动向外部平台发消息或创建工单，不自动把本次观测写成 Knowledge、Experience 或记忆。用户指定提交渠道或要求修改文档时，再按该请求处理。
+排查中的反馈线索合并成一次，随结果给出；重复的合并，矛盾的都保留。默认反馈到当前对话，作为可转交的需求草案，不自动发消息、建工单，也不自动写进知识或记忆；用户指定渠道或要求改文档时再按要求做。
 
 ## 收到改进请求后怎样使用
 
-先核对反馈缺少哪种判断方法、已有依据和期望改善，再按[文档目录](index.md)选择归属文件：系统行为和字段含义写入知识；排查步骤和工具用法补入对应方法；案例中可复用的候选与反证写入对应 Skill 的场景经验。证据仍不足的原因保留在案例反馈中，不写成系统事实。
-
-普通报错、结果异常和偶发问题尚无对应专项时，先将经过核实的排查方法补入[通用方法](architecture.md#其他问题如何开始)，案例中的未确认原因仍保留在反馈中。多个案例显示操作方式或判断方法需要单独处理时，再考虑增加专项。
+先核对缺的是哪种判断方法、已有依据和期望，再按[规则归属索引](index.md)选归属文件：系统行为和字段含义写进知识，排查步骤和工具用法补进对应方法，核实过的完整案例按[案例库](../knowledge/cases/README.md)收录，多个案例归纳出的方向写进对应域 `workflow.md` 的“常见现象与候选假设”。依据不够的原因留在案例反馈里，不写成系统事实。没有专项的非性能问题，核实过的方法先补进[其他问题如何开始](architecture.md#其他问题如何开始)，多个案例证明需要单独处理时再加专项。
 
-改动后用该案例及相近反例复核实际判断，检查是否更容易找到线索、区分候选原因并减少无用追问。输出反馈或脚本通过，都不能证明场景能力已经提升。
+改完用这个案例和相近反例复核实际判断：是不是更容易找到线索、区分原因、少问无用的问题。反馈或脚本通过，不能证明能力已经提升。

package/content/docs/diagnostic-report.md

@@ -1,56 +1,29 @@
 # 诊断结果交付
 
-性能诊断、直接 Metric 解读、更新记录解释和非性能辅助分析都使用本说明。最终交付方首次答复前读取，本轮已读则复用；专项只返回自身职责内的证据和判断，不因此承担最终业务根因。
+给使用者写答复时的参考，用得上再读。用业务对象和这次的运行记录讲清楚问题，使用者不需要有产品代码环境。必须提到技术字段时，保留原名，顺便说一下是什么意思。
 
-面向使用者交付，用业务对象和本次运行记录解释问题。使用者无需具备产品代码环境。解释或复核需要技术字段时，保留原名并说明含义；需要研发验证时，整理问题和对应证据。
+## 怎么答
 
-先直接回答本轮问题。查看记录、询问数值或索要链接时，用短段落或列表给出所需事实与范围，不套完整诊断报告。需要展开原因和依据的报告，已经闭环时使用以下两个一级章节：
-
-```markdown
-## 当前结论
-## 关键依据
-```
-
-尚有实质缺口时再增加 `## 待确认信息`，写清剩余判断及排查方向。不要为了格式完整输出“下一步”，也不要因此省略尚未解释问题的必要排查方向。问题已经解释时不为格式制造任务；原因尚未解释时，必须说明如何继续区分候选原因。建议存在适用前提或业务取舍时，在结论旁说明；未经验证的配置改动不写成已确认解决方案。
-
-“看一下这个 trace 的问题”“分析为什么失败”等请求属于原因分析，不能按查数值或链接的简单事实请求压缩交付。先给清楚的结论，再展开支撑判断所需的计算过程、证据和未解决问题；篇幅由问题复杂度决定，不限制为几条摘要。某项信息无需补查，只缩小该项取证范围，不降低其他分析和交付要求。
-
-每次交付时，检查本轮发现的场景知识缺口、优化项和文档差异。有证据支持时，按[诊断后的需求反馈](diagnostic-feedback.md)在报告后附上 `## 需求反馈`；没有则省略。合并专项返回的重复反馈，保留依据和适用限制。业务结论仍需单独交付，不为反馈额外取证。
-
-## 内容与证据
-
-- 当前结论：先说明已观察到的异常和可疑环节，结合已知业务对象、操作或执行解释；对象或执行尚未确认时说明范围。需要解释具体业务计算或步骤及触发条件时再展开，步骤只引用已验证的业务映射。保留已有环境、时间、资源和选中执行形态，区分已确认事实与候选原因；假设的依据和核对方法见[问题定位方法](architecture.md#每一步都用来区分原因)。不把最慢 span、OOM 或“数据量大”单独命名为完整根因。
-- 单次失败：连接本次输入与数据形成、局部膨胀、下游资源压力和直接失败条件。没有历史基线只限制“相对以前变化”的判断，不阻断本次执行解释。成对调查再补充相对基线的变化与可比范围。
-- 关键依据：保留锚定本次执行、支持或反驳判断、量化本次数据范围的必要证据，并解释每项证据对判断的作用。已经取得 trace 时给出完整 traceId；只有用户或工具返回完整链接时才引用，不按域名和 ID 拼接地址。只有 task/chain 时明确未取得 trace，不把执行 ID 冒充 trace 闭环。
-- 行数、列数、字节、输入输出、放大倍数、峰值/上限等已取得且影响判断的数据应进入依据。Metric 规模关系逐项使用完整 `metric_report.json` 的 `data_scale_transitions` 和可比较的 `input_output` 机械计算，不由报告作者重新手算跨节点关系。
-- 其他执行类型只有错误签名相同而未分别取得 Metric 时，只作为重复现象旁证；不得并入同一条算子原因链。保留反证、替代解释、字段缺失和对比范围。
-- 待确认信息：只列影响当前原因判断或处置选择的缺口。按证据强弱和区分原因的作用安排排查顺序，不固定动作数量；每项说明检查哪个业务对象或执行环节、依据什么线索、具体核对什么，以及不同结果分别支持或削弱哪个解释。助手仍能在已授权范围内完成的只读取证应先完成，不能作为建议转交用户。确需用户操作或研发验证时，给出其能执行的动作和需要返回的最小结果，不让使用者选择 Skill、内部 schema 或知识包。
-
-原因分析至少把已取得材料串成可阅读的过程：本次业务计算 → 实际输入及处理路径 → 中间结果或状态 → 资源压力 → 直接失败条件。每一段只写已有依据；无法连接的地方明确是哪条关系尚未证明，并保留有依据的候选解释。不能仅并列“大量中间结果”“存在覆盖”“达到上限”，就把这些事实当成完整原因链；也不能因为尚不能确认唯一原因，省略已经能够成立的贡献因素和局部判断。
-
-排查建议必须能改变判断。例如“临时结果为数千万行且保留数十列”时，应结合已有计划定位对应的汇总前结果及其使用分支，核对这些分支需要的明细和列，再判断是否有可减少的中间状态。尚未定位业务步骤时，说明需要建立哪项对应关系，不能只写“检查是否保留过多明细和字段”。优化方向同时保留业务等价前提，不把待验证方向写成确定解决方案。
-
-复杂筛选树等场景专项要求继续保留；节点名称未知时使用已有 ID 并说明名称缺口。未取得真实步骤映射时，不把物理 Operator 命名为具体业务步骤。附件保存完整明细，正文仍须展示影响判断的路径、覆盖位置及相关数量，解释其与执行的关系；不能以“已整理到附件”代替正文分析。
-
-内部调查摘要保留查询范围、已执行动作、选中/排除候选、来源版本、临时产物位置、证据缺口和未完成动作。最终答复不默认展示调用了哪个 Skill、Pod、无关执行 ID、源码行号和只用于搜索的字段。
-
-技术术语应能解释具体问题，例如哪里失败、消耗多少、哪个阶段承接数据。指标只列与判断有关的部分，并保留单位、统计口径、反证和实质缺口。复用已取得的链接和事实，不为补充排版重新取证。
-
-## 输出前核对
-
-确认结论回答了原始现象、执行没有串线、量化证据未丢失、置信层次没有提升、仍需执行的 Metric/专项分析已完成。原因分析还须核对：读者能否从正文看懂计算怎样形成压力；候选原因是否有依据且保留反证；尚未解释的关系是否对应具体的区分动作；必要解释是否被挪进附件而在正文消失。任一项证据不足时明确阶段性判断；不能用索要成功样本替代尚未完成的失败 Metric 分析。
-
-给使用者的说明不得出现产品代码路径、类名、方法位置或要求查代码的动作。日志字段确有必要时保留原名并解释含义；需要研发接手时按下方要求整理材料。
+- 先直接回答用户这一轮问的东西。只是查记录、问数值或要链接，给出事实和范围就行，不用套完整的诊断报告。
+- 分析原因时先说结论，再给撑得住这个判断的关键依据。还有没弄清的地方，就说还剩哪些判断、接下来怎么区分。问题已经解释清楚了，不用为了格式硬凑一个“下一步”。
+- 把拿到的材料串成一段读得懂的过程：这次算的是什么业务 → 实际的输入和处理路径 → 中间结果或状态 → 资源压力 → 直接失败条件。每一段只写有依据的内容，连不上的地方说清楚是哪层关系还没证实。
+- 分开写已经确认的事实和候选原因，反证、单位和统计口径都留着。没有历史基线，只是说不了“比以前变了多少”，不影响解释这一次。
+- 最慢的 span、OOM、超时阈值或者“数据量大”，单拎出来都不算完整的根因。要讲清楚是哪段计算、多大的输入、怎么放大，才走到了这条线。
+- 给的排查建议要能帮着做判断，并说明适用前提。没验证过的配置改动，不要写成已经确认的解决办法。
+- 拿到了 trace 就给完整的 traceId。链接只引用用户或工具给出的完整地址，不要自己拿域名和 ID 拼。只有 task 或 chain 时，说明还没拿到 trace。
+- 没拿到真实的步骤映射时，不要把物理 Operator 说成某个具体的业务步骤。
+- 用使用者听得懂的话写。知识里的内部说法要翻成大白话：`unknown` 说成“版本对不上，这部分没法确认”，计数单位说成“按什么数的”，关联边、锚点、候选这类词换成“哪条记录对上了哪条”“这次是哪一次执行”。
+- 不要贴产品代码路径、类名或方法位置，也不要让使用者去查代码。
 
 ## 交接研发
 
-现有记录无法区分原因、运行结果相互矛盾，或问题涉及尚未覆盖的产品行为时，整理以下材料：
+现有记录分不清原因、几次运行结果互相矛盾，或者问题涉及还没覆盖的产品行为时，整理下面这些材料：
 
-1. 客户的操作、预期、实际结果和影响范围。
-2. 环境、发生时间、可取得的产品版本信息及相关对象链接。
-3. 问题执行的链接、错误原文和必要脱敏材料；没有取得的明确说明。
-4. 已确认事实、已排除方向，以及各自依据。
+1. 客户做了什么操作，预期是什么，实际怎样，影响多大。
+2. 环境、发生时间、能拿到的产品版本信息，以及相关对象的链接。
+3. 出问题那次执行的链接、错误原文和必要的脱敏材料；没拿到的写明没拿到。
+4. 已经确认的事实、已经排除的方向，以及各自的依据。
 5. 需要研发回答的具体问题，例如“这次等待期间，上游是否已完成且可供读取？”
-6. 能稳定复现时提供最短操作步骤；不能复现时注明发生频率与已知条件。
+6. 能稳定复现就给最短的操作步骤；复现不了就写清发生频率和已知条件。
 
-不要把“请研发看一下”作为唯一交接内容，也不要用未经确认的原因给工单定性。原始大日志与业务数据使用受控附件，不复制到指南中。
+别只写一句“请研发看一下”就交出去，也别用没确认的原因给工单定性。原始的大日志和业务数据用受控附件传。

package/content/docs/index.md

@@ -1,30 +1,6 @@
-# 文档目录
+# 规则归属索引
 
-查找、修改规则或新增文件前，先用本目录确认规则归属。仓库文档统一在这里登记，每个主题只在一个归属文件中维护，其他文件写一句结论并链接到该文件。
-
-## 使用规则
-
-- 查找规则时，先看“按主题查找”，再读归属文件的对应章节，不从多个文件拼凑同一条规则。
-- 修改规则时，只改归属文件；其他位置写一句结论加链接。两处说法冲突时，以归属文件为准，将另一处改为引用。
-- 新增、删除或改名文件时，同步更新“全部文件”；新增跨文件规则时，同步登记“按主题查找”。离线检查会核对目录是否覆盖全部文档。
-
-## 分层结构
-
-```text
-入口层   AGENTS.md（助手契约与问题路由）    README.md（使用者入门）
-  │
-流程层   .agents/skills/*/SKILL.md（怎么查：步骤、触发条件、交接）
-  │        └─ references/（只属于该 Skill 的参考与经验）
-  │
-知识层   knowledge/（查什么、怎么判断：系统事实、字段、查询规则）
-  │
-交付层   docs/diagnostic-report.md、docs/diagnostic-feedback.md（怎么答复）
-  │
-说明层   docs/architecture.md、docs/scenario-guide.md（给使用者读的方法说明）
-维护层   docs/skill-writing-guide.md、docs/roadmap.md、本目录（给维护者）
-```
-
-上层只通过链接引用下层细节。Skill 写步骤和触发条件，知识层写判断依据，不在知识层编排 Skill 调用流程。
+找某条规则时先看本页：每个主题只在一个归属文件中维护，其他文件写一句结论并链接到它。先读归属文件的对应章节，不从多个文件拼凑同一条规则；两处说法冲突时以归属文件为准。按文件找知识（何时读哪个）见[知识目录](../knowledge/README.md)。
 
 ## 按主题查找
 
@@ -34,115 +10,50 @@
 | npm 安装副本的版本固定、脚本调用与临时产物规则 | [安装副本的助手规则](../AGENTS.md#安装副本的助手规则) |
 | 助手判断与脚本使用范围 | [助手执行契约 · 工具使用](../AGENTS.md#工具使用) |
 | 从日志提出候选原因、选择核对方向 | [问题定位方法 · 每一步都用来区分原因](architecture.md#每一步都用来区分原因) |
-| 环境、时间窗、dagId、历史对比等入口默认值 | [公共查询规则 · 默认值速查](../knowledge/common/signoz-query-policy.md#默认值速查) |
-| 查询时间格式、时区和已有边界复用 | [公共查询规则 · 查询约束](../knowledge/common/signoz-query-policy.md#查询约束) |
-| 首次查询怎么开始、截图 ID 可信度、按现象选证据源 | [公共查询规则](../knowledge/common/signoz-query-policy.md#调查起点) |
-| 查询预算、空结果回退、大结果传递 | [公共查询规则 · 查询预算与结果复用](../knowledge/common/signoz-query-policy.md#查询预算与结果复用) |
-| 历史对比的基线选择 | [公共查询规则 · 主动对比](../knowledge/common/signoz-query-policy.md#主动对比) |
-| 后台独立 trace 的显式链接（`linked`） | [公共查询规则 · 独立 Trace 的显式链接](../knowledge/common/signoz-query-policy.md#独立-trace-的显式链接) |
-| 环境名称、URL 与后端服务映射 | [环境识别](../knowledge/common/signoz-environments.md) |
-| 从 trace 判断属于哪个场景 | [场景识别](../knowledge/common/trace-routing.md) |
-| 共享外部组件入口属于组件还是仪表板 | [场景识别 · 外部组件取数入口](../knowledge/common/trace-routing.md#外部组件取数入口) |
-| 仪表板组件异常时先查单独计算、无对照时如何继续 | [仪表板专项 · 组件取数先做对照](../.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照) |
-| 仪表板内外组件对照的时间窗与查询预算 | [公共查询规则 · 仪表板内外组件对照](../knowledge/common/signoz-query-policy.md#仪表板内外组件对照) |
-| 单独组件与仪表板请求的可比性、成功判定 | [仪表板 · 组件计算对照的证据](../knowledge/dashboard/observability.md#组件计算对照的证据) |
-| 动态字段类型、覆盖确认与取证边界、上游重算 | [仪表板 · 动态字段覆盖与上游展开](../knowledge/dashboard/observability.md#动态字段覆盖与上游展开) |
-| 从控件关系请求日志补字段名称与绑定 | [仪表板 · 名称与请求上下文的关联取证](../knowledge/dashboard/observability.md#名称与请求上下文的关联取证) |
-| 知识是否适用于本次版本和记录 | [知识适用性](../knowledge/common/knowledge-applicability.md) |
-| 何时必须取 Metric、何时可跳过；失败分析何时算完成 | [性能诊断 · 失败分析的完成条件](../.agents/skills/diagnose-performance/SKILL.md#失败分析的完成条件) |
-| 引擎任务定位、MetricOuts 正文获取与复用 | [Metric 获取](../knowledge/engine/metric-retrieval.md) |
-| Metric 字段含义 | [Metric 解读](../knowledge/engine/metric-semantics.md) |
-| 解析产物格式、版本与复用 | [Metric 事实产物](../knowledge/engine/metric-artifacts.md) |
-| 常见引擎性能问题的判断方法 | [常见引擎性能问题](../knowledge/engine/performance-patterns.md) |
-| 分析表 / 组件 / 仪表板的业务实体、入口 span 与 attribute | [分析表](../knowledge/dataset/observability.md)、[组件](../knowledge/component/observability.md)、[仪表板](../knowledge/dashboard/observability.md) |
-| 仪表板筛选树的完整性、名称补齐与展示 | [仪表板 · 筛选树还原与交付](../knowledge/dashboard/observability.md#筛选树还原与交付) |
-| 仪表板配置影响范围与“绑定下移”核对 | [仪表板 · 核对配置影响范围](../knowledge/dashboard/observability.md#核对配置影响范围) |
-| 企业更新与 dagId 的检索窗口、降级和时间扩展 | [更新发现指引 · 检索时间](../.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md#检索时间) |
-| 按输入选择更新场景与 recipe | [更新运行证据](../knowledge/update/runtime-evidence.md#选当前需要的知识) |
-| 更新的身份术语、关联边、计数单位与停止规则 | [更新证据摘要边界](../.agents/skills/analyze-analysis-table-update-runtime/references/update-diagnostic-contract.md) |
+| 环境、时间窗、dagId、历史对比等入口默认值 | [公共查询规则 · 默认值速查](../knowledge/common/queries.md#默认值速查) |
+| 查询时间格式、时区和已有边界复用 | [公共查询规则 · 查询约束](../knowledge/common/queries.md#查询约束) |
+| 首次查询怎么开始、截图 ID 可信度、按现象决定先查什么 | [公共查询规则](../knowledge/common/queries.md#调查起点) |
+| 查询预算、空结果回退、大结果传递 | [公共查询规则 · 查询预算与结果复用](../knowledge/common/topics/query-budget.md#查询预算与结果复用) |
+| 历史对比的基线选择 | [公共查询规则 · 主动对比](../knowledge/common/topics/baseline-comparison.md#主动对比) |
+| 后台独立 trace 的显式链接（`linked`） | [公共查询规则 · 独立 Trace 的显式链接](../knowledge/common/topics/linked-traces.md#独立-trace-的显式链接) |
+| 环境名称、URL 与后端服务映射 | [环境识别](../knowledge/common/concepts.md) |
+| 从 trace 判断属于哪个场景 | [场景识别](../knowledge/common/signals.md) |
+| 看到某个 span、属性或日志名，想知道含义在哪 | [信号索引](../knowledge/signal-index.md) |
+| 仪表板组件预览入口里怎么分出仪表板以外的图表预览 | [场景识别 · 仪表板组件预览入口](../knowledge/common/signals.md#仪表板组件预览入口) |
+| 仪表板组件异常时先查单独预览、无对照时如何继续 | [仪表板 · 组件取数先做对照](../knowledge/dashboard/workflow.md#组件取数先做对照) |
+| 仪表板内外组件对照的时间窗与查询预算 | [公共查询规则 · 仪表板内外组件对照](../knowledge/common/topics/baseline-comparison.md#仪表板内外组件对照) |
+| 单独组件与仪表板请求的可比性、成功判定 | [仪表板 · 组件计算对照怎么判断](../knowledge/dashboard/topics/component-comparison.md#组件计算对照怎么判断) |
+| 动态字段类型、覆盖确认与取证边界、上游重算 | [仪表板 · 动态字段覆盖与上游展开](../knowledge/dashboard/topics/dynamic-fields.md#动态字段覆盖与上游展开) |
+| 从筛选器关系请求日志补字段名称与绑定 | [仪表板 · 名称与请求上下文的关联取证](../knowledge/dashboard/topics/name-binding.md#名称与请求上下文的关联取证) |
+| 知识是否适用于本次版本和记录 | [知识适用性](../knowledge/common/conclusions.md#知识适用性) |
+| 性能问题从哪里入手、怎样选场景域 | [性能排查入口](../knowledge/common/workflow.md) |
+| 某个场景域的入手提示、候选假设与易错点 | 各域 `workflow.md`，见[知识目录](../knowledge/README.md) |
+| 安装、配置或恢复 SigNoZ MCP | [配置 SigNoZ MCP](../knowledge/common/topics/setup-signoz-mcp.md) |
+| 引擎任务定位、MetricOuts 正文获取与复用 | [Metric 获取](../knowledge/engine/queries.md) |
+| Metric 字段含义 | [Metric 解读](../knowledge/engine/conclusions.md) |
+| 常见引擎性能问题的判断方法 | [常见引擎性能问题](../knowledge/engine/topics/patterns.md) |
+| 分析表 / 组件 / 仪表板的业务概念、入口 span 与 attribute | [分析表](../knowledge/dataset/README.md)、[组件](../knowledge/component/README.md)、[仪表板](../knowledge/dashboard/README.md) |
+| 仪表板筛选树的完整性、名称补齐与展示 | [仪表板 · 筛选树还原与交付](../knowledge/dashboard/topics/filter-tree.md#筛选树还原与交付) |
+| 仪表板配置影响范围与“绑定下移”核对 | [仪表板 · 核对配置影响范围](../knowledge/dashboard/conclusions.md#核对配置影响范围) |
+| 企业更新与 dagId 的检索窗口、降级和时间扩展 | [更新发现指引 · 检索时间](../knowledge/update/topics/discover-executions.md#检索时间) |
+| 按输入选择更新取证配方 | [更新 · 选哪个配方](../knowledge/update/queries.md#选哪个配方) |
+| 更新的计数单位 / 允许的关联边 | [更新 · 计数单位与身份](../knowledge/update/concepts.md#计数单位与身份)、[关联边](../knowledge/update/topics/correlations.md#关联边) |
+| 更新记录的计数对账、判断矩阵与停止规则 | [更新 · 能下什么结论](../knowledge/update/conclusions.md) |
 | 答复格式、原因链展开、正文与附件分工、可执行排查方向 | [诊断结果交付](diagnostic-report.md) |
 | 交接研发的材料 | [诊断结果交付 · 交接研发](diagnostic-report.md#交接研发) |
 | 诊断后的需求反馈 | [需求反馈](diagnostic-feedback.md) |
+| 已核实案例的收录门槛与格式 | [诊断案例库](../knowledge/cases/README.md) |
 | 非性能案例保留什么、反馈后怎样改进 | [非性能案例](diagnostic-feedback.md#非性能案例怎样保留)、[收到改进请求后](diagnostic-feedback.md#收到改进请求后怎样使用) |
-| Skill 与说明的写法 | [Skill 编写建议](skill-writing-guide.md) |
-| 交付方案选型、用户安装使用、版本更新与发布 | [FX 数据诊断交付方案](npm-cli.md) |
-| 新诊断后台检查更新、失败保留旧版与更新状态提示 | [版本管理](npm-cli.md#34-版本管理)、[安装副本的助手规则](../AGENTS.md#安装副本的助手规则) |
-| npm 交付模块目录、构建与发布职责 | [构建打包](npm-cli.md#32-构建打包)、[发布分发](npm-cli.md#33-发布分发) |
-| npm 包内的用户使用说明 | 包内 README，由 `packages/ai-diagnostics/templates/README.md` 模板生成 |
-| npm 包的 Agent 安装与管理步骤、配置变量 | 包内 `AGENT_SETUP.md`，由 `packages/ai-diagnostics/templates/AGENT_SETUP.md` 模板生成 |
-| 发布 Token 的本机配置与 CI 注入 | [发布 npm 包](../README.md#发布-npm-包) |
+| 新诊断后台检查更新、失败保留旧版与更新状态提示 | [安装副本的助手规则](../AGENTS.md#安装副本的助手规则) |
 
-## 性能诊断的调用关系
+## 性能诊断的流转
 
 ```text
-AGENTS.md ──性能问题──▶ diagnose-performance（范围、路由、跨场景、交付）
-                           ├─▶ diagnose-dataset / component / dashboard-performance
-                           │       └─▶ analyze-engine-metric（专项直接调用）
-                           └─▶ diagnose-update-performance
-                                   ├─▶ analyze-analysis-table-update-runtime
-                                   └─▶ analyze-engine-metric（专项直接调用）
+AGENTS.md ──性能问题──▶ common/workflow（范围、选场景域、跨场景、交付）
+                           ├─▶ dataset / component / dashboard 的 workflow
+                           │       └─▶ engine/workflow（域内直接进入）
+                           └─▶ update/workflow（更新性能排查）
+                                   └─▶ engine/workflow（域内直接进入）
 ```
 
-专项在本场景内完成取证，包括直接调用引擎统计分析；只有进入其他场景或交付时才回到 `diagnose-performance`。只解释更新记录时，根 Agent 直接调用 `analyze-analysis-table-update-runtime`；只解读 Metric 时直接调用 `analyze-engine-metric`。
-
-## 全部文件
-
-读者分为使用者（排查问题的人）、助手（诊断 Agent）和维护者（修改本仓库的人）。
-
-### 入口
-
-| 文件 | 读者 | 负责 |
-|---|---|---|
-| [AGENTS.md](../AGENTS.md) | 助手 | 执行契约、问题路由、证据边界、交付原则 |
-| [README.md](../README.md) | 使用者 | 能解决什么问题、如何提问、输出什么 |
-| npm 包 README（源模板 `packages/ai-diagnostics/templates/README.md`） | 使用者 | 安装、使用、更新与卸载；提供 Agent 文档入口 |
-| npm 包 AGENT_SETUP.md（源模板 `packages/ai-diagnostics/templates/AGENT_SETUP.md`） | 安装 Agent | 复用检测、环境准备、薄 Skill 登记与管理；随包生成，不作为诊断前置知识 |
-
-### 诊断能力（Skill）
-
-| Skill | 何时使用 | 自有参考 |
-|---|---|---|
-| [diagnose-performance](../.agents/skills/diagnose-performance/SKILL.md) | 慢、超时、内存超限、性能回归的总入口 | 无 |
-| [diagnose-dataset-performance](../.agents/skills/diagnose-dataset-performance/SKILL.md) | 分析表预览、步骤计算 | [经验](../.agents/skills/diagnose-dataset-performance/references/experience.md) |
-| [diagnose-component-performance](../.agents/skills/diagnose-component-performance/SKILL.md) | 组件取数 | [经验](../.agents/skills/diagnose-component-performance/references/experience.md) |
-| [diagnose-dashboard-performance](../.agents/skills/diagnose-dashboard-performance/SKILL.md) | 仪表板控件候选值与组件取数 | [经验](../.agents/skills/diagnose-dashboard-performance/references/experience.md) |
-| [diagnose-update-performance](../.agents/skills/diagnose-update-performance/SKILL.md) | 更新慢、失败、内存超限 | [经验](../.agents/skills/diagnose-update-performance/references/experience.md) |
-| [analyze-analysis-table-update-runtime](../.agents/skills/analyze-analysis-table-update-runtime/SKILL.md) | 解释更新来源、链路、节点、重试与计数 | [更新发现指引](../.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md)、[证据摘要边界](../.agents/skills/analyze-analysis-table-update-runtime/references/update-diagnostic-contract.md) |
-| [analyze-engine-metric](../.agents/skills/analyze-engine-metric/SKILL.md) | 获取并解读引擎 Metric | 无 |
-| [setup-signoz-mcp](../.agents/skills/setup-signoz-mcp/SKILL.md) | 安装、配置或恢复 SigNoZ 连接 | [安装参考](../.agents/skills/setup-signoz-mcp/references/installation.md)、[Windows 构建](../.agents/skills/setup-signoz-mcp/references/windows-artifact.md) |
-
-经验文件只用于提出和排序假设，取证门槛和判断依据以本目录登记的归属文件为准。
-
-### 知识（knowledge/）
-
-| 文件 | 何时读取 | 负责 |
-|---|---|---|
-| [common/signoz-query-policy.md](../knowledge/common/signoz-query-policy.md) | 需要新增线上证据时 | 入口默认值、查询约束、预算、对比基线、独立 trace 链接 |
-| [common/signoz-environments.md](../knowledge/common/signoz-environments.md) | 首次查询或配置连接时 | 环境映射与选择顺序 |
-| [common/signoz-query-example.md](../knowledge/common/signoz-query-example.md) | 工具说明不可读、需要 Query Builder 结构时 | 原始查询结构例子 |
-| [common/trace-routing.md](../knowledge/common/trace-routing.md) | 只有 trace 或场景不明时 | 场景识别、外部组件入口判定 |
-| [common/knowledge-applicability.md](../knowledge/common/knowledge-applicability.md) | 首次使用场景知识时 | 知识与本次记录的适用核对 |
-| [dataset/observability.md](../knowledge/dataset/observability.md) | 进入分析表场景时 | 分析表实体、入口与信号 |
-| [component/observability.md](../knowledge/component/observability.md) | 进入组件场景时 | 组件实体、入口与信号 |
-| [dashboard/observability.md](../knowledge/dashboard/observability.md) | 进入仪表板场景时 | 仪表板实体、入口与信号、筛选树、配置核对 |
-| [dashboard/query-examples.md](../knowledge/dashboard/query-examples.md) | 仪表板需要定向补取字段时 | 仪表板查询意图与例子 |
-| [engine/metric-retrieval.md](../knowledge/engine/metric-retrieval.md) | 需要定位引擎任务或取 Metric 时 | 任务字段、关联、正文获取 |
-| [engine/metric-semantics.md](../knowledge/engine/metric-semantics.md) | 首次解读 Metric 字段时 | 字段含义与分析顺序 |
-| [engine/metric-artifacts.md](../knowledge/engine/metric-artifacts.md) | 复用或展开解析产物时 | 产物格式、版本与复用 |
-| [engine/performance-patterns.md](../knowledge/engine/performance-patterns.md) | 按现象判断引擎机制时 | 常见性能问题与反证 |
-| [update/observability.md](../knowledge/update/observability.md) | trace 路由识别更新场景时 | 更新场景识别线索（入口页） |
-| [update/runtime-evidence.md](../knowledge/update/runtime-evidence.md) | 解释更新运行记录时 | 选择更新知识分片 |
-| [update/diagnostic/](../knowledge/update/diagnostic/) | 由更新分析按需读取 | 更新场景、recipe 与观测分片（JSON，入口为 `manifest.json` 和各 `*-index.json`） |
-
-### 说明与维护（docs/）
-
-| 文件 | 读者 | 负责 |
-|---|---|---|
-| [architecture.md](architecture.md) | 使用者、助手 | 通用问题定位方法；非性能问题的辅助分析方法 |
-| [scenario-guide.md](scenario-guide.md) | 使用者 | 各场景先看什么、怎样判断 |
-| [diagnostic-report.md](diagnostic-report.md) | 助手 | 答复格式、证据展示、研发交接 |
-| [diagnostic-feedback.md](diagnostic-feedback.md) | 助手 | 需求反馈的触发条件与写法 |
-| [skill-writing-guide.md](skill-writing-guide.md) | 维护者 | Skill 与说明的写法 |
-| [roadmap.md](roadmap.md) | 维护者 | 覆盖范围与待补齐方向 |
-| [npm-cli.md](npm-cli.md) | 使用者、维护者 | FX 数据诊断的选型决策、能力包与发布设计、用户安装使用和更新 |
-| [index.md](index.md) | 全部 | 本目录 |
+各域在本场景内完成取证，包括直接进入引擎排查；只有进入其他场景或交付时才回到 `common/workflow`。只解释更新记录时，直接按 `update/workflow` 的“解释更新记录”处理；只解读 Metric 时，直接按 `engine/workflow` 处理。

package/content/docs/scenario-guide.md

@@ -1,86 +1,68 @@
 # 按场景排查
 
-先确定客户慢的是哪一次操作，再阅读对应部分。对象名称相同，不代表操作相同；每个判断都需要对应到本次记录。通用调查顺序见[问题定位方法](architecture.md)。
+先确定慢的是哪一次操作，再读对应部分。对象名字相同不代表操作相同，每个判断都要对上这次的记录。通用顺序见[问题定位方法](architecture.md)，各场景的细节在对应知识域的 `workflow.md`。
 
 ## 分析表
 
-先区分预览数据慢、某一步骤取数慢，还是后台更新慢。后台更新按[更新](#更新)调查，不能用成功预览代替失败更新。
+先分清是预览慢、某一步取数慢，还是后台更新慢；后台更新按[更新](#更新)查，成功的预览代替不了失败的更新。
 
-先看什么：分析表链接、当时选中的步骤、筛选与参数、请求的数据范围，以及本次执行的耗时或错误。
-
-怎样判断：先说明选中步骤在处理哪些数据、是否引入关联、聚合或范围变化。某个步骤之后变慢时，对照相邻步骤的实际输入输出和耗时，不能仅凭步骤名称认定原因。页面步骤位置不一定是稳定的步骤标识。
-
-何时继续深入：已选定慢或失败引擎执行时，默认获取对应 Metric 核对执行事实；只有明确未提交、用户限定不读取或实际取证受阻时才跳过。遇到内存或行数限制，解释数据在本次计算中如何形成，不能只重复错误名称。明确取消或资源等待超时且尚未提交时，先解释取消链或等待条件，不用其他任务的统计补成本次计算原因。
-
-交付重点：说明本次预览范围、已确认的慢点或失败条件，区分执行层判断与已经验证的业务步骤原因。
+- 先看：分析表链接、当时选中的步骤、筛选和参数、数据范围、这次执行的耗时或错误。
+- 怎样判断：先说清选中的步骤在处理哪些数据、有没有引入合并、汇总或范围变化。某一步之后变慢，对照相邻步骤的实际输入输出和耗时，不凭步骤名字下结论；页面上的步骤位置也不一定是稳定标识。
+- 深入：选定了慢或失败的引擎执行就看对应的 Metric，只有明确没提交、用户不让读或取不到时才跳过。内存或行数超限要解释数据怎么变大的，不只重复错误名；取消或等资源超时还没提交的，解释取消链或等待条件。
+- 交付：这次预览的范围、确认的慢点或失败条件，执行层判断和已验证的步骤原因分开说。
 
 ## 组件
 
-先确认是编辑或单独预览组件慢，还是仪表板中的组件慢。来自仪表板的请求，需要连同触发它的筛选、参数或联动一起调查。
-
-先看什么：组件链接或标识、绑定表、查询字段、聚合与排序、筛选条件、参数和本次请求。
+先确认是图表编辑、仪表板以外的图表预览慢，还是仪表板里的组件慢；来自仪表板的连同触发它的筛选、参数、联动一起查。
 
-怎样判断：区分组件自身计算复杂、读取范围扩大、等待数据就绪和结果返回慢。不能因为底层分析表也有更新，就认定更新拖慢了这次组件请求；需要有对应等待、状态或读取关系。
-
-交付重点：说明这个组件这次计算了什么，哪个条件或环节与现象有关。不要把共享底层表的所有组件都列为受影响，影响范围以本次记录或配置为依据。
+- 先看：组件标识、绑定表、查询字段、聚合和排序、筛选、参数和这次请求。
+- 怎样判断：分清是组件自身计算重、读取范围变大、在等数据就绪，还是结果返回慢。底层分析表也在更新，不能就说是更新拖慢了，要有等待、状态或读取关系的记录。
+- 交付：这个组件这次算了什么，哪个条件或环节和现象有关；影响范围以记录或配置为准，不把共享底层表的组件都列为受影响。
 
 ## 仪表板
 
-优先区分两种操作：
+先分清是哪种操作：
 
-| 慢的操作 | 调查对象 |
+| 慢的操作 | 查什么 |
 |---|---|
-| 打开筛选器，下拉候选值迟迟不出现 | 筛选器自身取数 |
-| 选择筛选值后，图表迟迟不刷新 | 受该动作影响的组件取数 |
-
-首次打开、参数改变和组件联动也可能触发组件取数。用户动作决定本次要观察哪些请求，并不自动说明原因。
-
-筛选器自身取数：查看候选值来源表和字段、实际候选值数量，以及其他控件带入的条件。绑定多个字段并不必然导致慢，必须看实际读取范围与执行结果。
+| 打开筛选器，下拉选项迟迟不出来 | 筛选器自身取候选值 |
+| 选了筛选值，图表迟迟不刷新 | 受这个动作影响的组件取数 |
 
-组件取数：先按[组件取数对照](../.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照)核对单独计算，再还原组件查询，检查动态字段、筛选、参数、权限和联动条件。涉及多层关联表时，画出从组件绑定表到筛选字段所在表的完整关系，标注筛选落在哪一层；记录不完整时只展示能确认的部分。
+首次打开、参数变化和联动也会触发组件取数；用户动作只决定看哪些请求，不说明原因。
 
-字段只显示 ID 时，按[名称关联取证](../knowledge/dashboard/observability.md#名称与请求上下文的关联取证)核对已有请求和控件关系日志，区分字段名称、当时选择值与默认值，不直接从日期表达式猜名称。
-
-共享路径：同一条件对象可能被多条路径访问。分别说明条件对象数和路径数，保留记录中的共享或环标记；不能按表名相同合并对象，也不能仅因路径深或数量多就认定是慢因。
-
-判断影响：同一次动作中没有观察到其他组件请求，只能说明观测范围，不能证明配置上没有其他目标。控件标识、组件资产和画布实例也不能仅因名称相同而混用。
-
-对照时注意：没有控件字段不等于没有控件影响；明确记录为零才可以作为相应证据。同一组件前后耗时不同，也需要核对查询形态和数据范围，才能讨论筛选的贡献。
-
-交付重点：先说明慢的是候选值还是图表，哪些实际条件扩大了计算范围，以及是否还有配置前提待确认。绑定下移、手动候选值等建议必须满足业务需要，不能直接照搬历史案例。
+- 筛选器取候选值：看来源表和字段、实际候选值数量、其他筛选器带进来的条件。绑多个字段不一定慢，要看实际读取范围和执行结果。
+- 组件取数：先按[组件取数对照](../knowledge/dashboard/workflow.md#组件取数先做对照)看单独预览，再还原组件查询，检查动态字段、筛选、参数、权限和联动。涉及多层关联表时，画出从组件绑定表到筛选字段所在表的完整关系，标出筛选落在哪层；记录不全只画能确认的部分。
+- 字段只有 ID 时，按[名称关联取证](../knowledge/dashboard/topics/name-binding.md#名称与请求上下文的关联取证)从已有请求和筛选器关系日志补名称，分清字段名、当时选的值和默认值。
+- 同一条件对象可能被多条路径访问，分别说对象数和路径数，不按表名合并，也不因路径深、数量多就认定是慢因。
+- 同一次动作里没看到其他组件请求，只说明观测范围；没有筛选器字段不等于没有影响，明确记为零才算依据。
+- 交付：先说慢的是候选值还是图表、哪些实际条件扩大了计算，还有哪些配置前提待确认。绑定下移、手动候选值等建议要符合业务需要，不照搬历史案例。
 
 ## 更新
 
-先找到客户指的是哪一次更新，以及实际失败、持续等待或耗时较长的对象。相同表可能同时有预览、更新或重试记录，分别保留。
-
-按下面的过程寻找时间或失败位置；记录中没有的阶段不要补造：
+先找到用户说的是哪一次更新，以及实际失败、一直等待或耗时长的对象；同一张表的预览、更新、重试分开记。按下面的过程找时间或失败位置，记录里没有的阶段不补：
 
 ```text
 发起更新 → 等待调度或上游 → 执行节点 → 计算或读取数据 → 写入及后续处理
 ```
 
-- 等待锁后重新派发：锁等待超时说明本次尝试未能取得锁，后续重派不等于整次更新最终失败。结合明确的重派记录区分尝试，不能把相邻队列接收时间加进原尝试。
-- 尚未进入计算：核对上游依赖、排队与开始时间，不用引擎统计解释计算之前的等待。
-- 某个节点耗时集中：区分节点等待、实际计算、数据写入和后续处理，再沿明确关联深入。
-- 失败后重试：每次尝试单独记录，不能用重试成功掩盖前一次失败，也不能把尝试次数当成更新对象数。
-- 内存或行数超限：分析本次计算的输入、放大过程和资源边界。已有对应执行统计时先完成分析，不把正常样本作为前提。
-
-节点成功不必然表示发生了数据加载，也不等于整次更新已完成。判断数据是否成功写入，应使用对应完成记录；仅有触发通知或节点数量不能证明。
+- 等锁后重新派发：这次尝试没拿到锁，不等于整次更新失败；按明确的重派记录分清尝试，不把相邻的队列接收时间加进原尝试。
+- 还没进入计算：看上游依赖、排队和开始时间，不用引擎统计解释计算之前的等待。
+- 某个节点耗时集中：分清等待、计算、写入和后续处理，再沿明确关联往下查。
+- 失败后重试：每次尝试单独记，重试成功掩盖不了前一次失败，尝试次数也不是更新对象数。
+- 内存或行数超限：分析这次的输入、放大过程和资源上限，不以正常样本为前提。
 
-交付重点：说明时间或失败集中在什么阶段、哪些关联已确认，以及结果是否足以回答客户这次问题。缺少必要关联时说明缺哪一段，不根据同表名或时间接近拼接流程。
+节点成功不一定发生了数据加载，也不等于整次更新完成；写没写进去看对应的完成记录。交付时说清时间或失败集中在哪个阶段、哪些关联已确认，缺哪段就说缺哪段，不按同表名或时间接近拼流程。
 
 ## 解释更新记录
 
-客户问“为什么有这么多次更新”时，先确认正在数什么：
+用户问“为什么有这么多次更新”，先确认在数什么：
 
-| 记录对象 | 表示什么 | 不能直接等同于 |
+| 记录对象 | 表示什么 | 不能等同于 |
 |---|---|---|
 | 发起请求 | 一次触发更新的动作 | 更新了多少张表 |
-| 更新链路 | 一次调度组织的更新范围 | 已完成写入次数 |
-| 更新节点 | 链路中处理的具体对象 | 引擎任务数量 |
-| 执行尝试 | 节点的一次实际尝试 | 不同业务对象数量 |
+| 更新链路 | 一次调度组织的更新范围 | 写入完成的次数 |
+| 更新节点 | 链路里处理的具体表 | 引擎任务数 |
+| 执行尝试 | 节点的一次实际尝试 | 不同业务对象数 |
 | 引擎任务 | 一次底层计算任务 | 整次更新请求 |
 
-一次请求可以涉及多个节点，一个节点可以重试；多个请求也可能被合并处理。因此数量不相等本身不是异常。
-
-先固定计数对象，再寻找明确标识和关联记录，说明哪些数量可以比较、哪些无法换算。若目标转为“为什么这次更新慢或失败”，应继续进入更新性能排查，不能只交付计数说明。
+一次请求可以涉及多个节点，节点可以重试，多个请求也可能合并，所以数量不相等本身不是异常。先固定计数对象，再找明确的标识和关联，说明哪些数能比、哪些换算不了。目标变成“为什么这次慢或失败”时，接着做更新性能排查。

package/content/knowledge/README.md

@@ -0,0 +1,49 @@
+# 知识目录
+
+诊断要用的东西都在 `knowledge/` 里：业务概念、入口 span 和 attribute、字段含义、日志和 trace 能说明什么、怎么写查询，再加上每个域一份很短的 `workflow.md`，写着从哪下手和容易踩的坑。助手靠这些知识自己判断，没有另外一层流程。
+
+每个知识域的结构都一样，在一个域里学会怎么找，换到别的域也一样找。
+
+## 目录
+
+- 怎样找知识
+- 槽位
+- 知识域
+
+## 怎样找知识
+
+1. **选域**：按问题属于哪个场景，在下面的“知识域”里挑一个。拿不准时先看[通用 · 入口与信号](common/signals.md)。
+2. **看入口提示**：第一次进某个域，可以先扫一眼它的 `workflow.md`，里面有这类问题从哪下手、常见现象和容易踩的坑。
+3. **选槽位**：看这会儿要做什么，读该域对应的槽位（见下表）。每个域的槽位名字都一样。
+4. **只读用得上的章节**：槽位文件有目录，按章节读；同一轮读过、范围也没变，就直接复用。要展开某个主题，看该域 `README.md` 的“展开明细”。
+
+不知道该读哪个槽位，就先看该域的 `README.md`，里面列了每个槽位和展开明细各放了什么。
+
+手上已经有某个 span、属性或日志名时，先查[信号索引](signal-index.md)，按名字就能找到它的含义在哪一节。
+
+## 槽位
+
+| 要做什么 | 读 | 回答的问题 |
+|---|---|---|
+| 这类问题从哪里入手 | `workflow.md` | 入手提示；常见现象的候选假设；易错点 |
+| 弄清概念是什么、怎么关联 | `concepts.md` | 有哪些业务概念、计数单位、环境或标签；它们之间怎么关联 |
+| 认出入口，看懂 span、attribute、日志和字段 | `signals.md` | 这条 trace / 日志属于哪个场景；每个信号是什么意思、什么时候出现 |
+| 看完日志和 trace，能下什么结论 | `conclusions.md` | 手上的日志、trace 能说明什么、不能说明什么；该停在哪里；怎样核对适用范围 |
+| 写查询、选取证路径 | `queries.md` | 怎样在 SigNoZ 取证；查询约束与预算；按输入选哪个取证配方 |
+| 展开某个专门主题 | `topics/<主题>.md` | 只在该域 README 的“展开明细”登记的主题：大表、长明细、专项方法 |
+
+每个域都要有 `README.md` 和上面五个槽位文件；某个槽位没内容，就在文件里写一句“本域没有此类内容”，文件本身不能少。`topics/` 下的每个文件都要在该域 README 里写明什么时候读。新增知识按槽位放，放置规则见源码仓库的 `maintainers/README.md`。
+
+## 知识域
+
+| 域 | 范围 | 典型入口 |
+|---|---|---|
+| [common](common/README.md) | 跨场景共用：性能排查入口、环境、trace 路由、查询规则、知识适用性、SigNoZ MCP 配置 | 慢、超时、OOM 等性能问题从[性能排查入口](common/workflow.md)开始 |
+| [dataset](dataset/README.md) | 分析表的前台预览与步骤计算 | [排查入口](dataset/workflow.md) |
+| [component](component/README.md) | 组件（图表）取数 | [排查入口](component/workflow.md) |
+| [dashboard](dashboard/README.md) | 仪表板 2.0的筛选器候选值与组件计算 | [排查入口](dashboard/workflow.md) |
+| [update](update/README.md) | 分析表更新（dispatch）：场景标签、逻辑事件、关联边、取证配方 | [解释更新记录与更新性能排查](update/workflow.md) |
+| [engine](engine/README.md) | 引擎执行统计（Metric）的获取与解读 | [排查入口](engine/workflow.md) |
+| [cases](cases/README.md) | 已核实的诊断案例，只用于提出假设 | 提出候选原因前 |
+
+`cases` 是案例集，不按槽位分；其余六个域都按上面的槽位组织。