@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

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,114 +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 交付模块目录、构建与发布职责 | [构建打包](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` 是案例集，不按槽位分；其余六个域都按上面的槽位组织。

package/content/knowledge/cases/README.md

@@ -0,0 +1,60 @@
+# 诊断案例库
+
+收录经过核实的诊断案例：现象、区分过哪些候选原因、最后的原因和处理，以及适用限制。案例只用于**提出和排序假设**，不是系统事实，也不能代替本次记录确认根因；这与各域 `workflow.md` 中“常见现象与候选假设”只排序假设的定位一致。
+
+## 目录
+
+- 什么时候读
+- 收录门槛
+- 条目格式
+- 案例索引
+
+## 什么时候读
+
+提出候选原因前，按场景在下方索引里找相近现象。命中时把它当作一个候选方向：说明来自哪个案例、其状态和适用限制，再用这次的日志和 trace 验证，不直接套用结论。没有命中不影响正常排查。
+
+## 收录门槛
+
+- 有依据：原因必须有支持它的记录，并写出被排除的候选和反证。只有猜测的原因不收录，留在反馈草稿里。
+- 单个案例先记为 `observed`；被第二个独立案例，或研发复核证实后升为 `confirmed`。单次相似现象不足以形成通用原因。
+- 已收录同类问题时更新原条目的依据和适用范围，不重复新建。
+- 按脱敏要求写：不放 32 位十六进制 ID、`agp` 开头的标识、租户名、企业 ID、完整业务载荷或凭据。
+- 持续被新案例推翻的条目改回 `observed` 或删除，不保留过期的结论。
+
+收录由维护者审核后合入，助手在诊断中不自动写入本目录；诊断后的草稿按[需求反馈](../../docs/diagnostic-feedback.md)提出。
+
+## 条目格式
+
+每个案例一个文件，文件名 `<场景>-<短名>.md`，场景取 `dataset`、`component`、`dashboard`、`update`、`engine`、`other`。
+
+```markdown
+---
+scene: update
+status: observed        # observed | confirmed
+recorded: 2026-11-07
+---
+
+# 一句话标题（现象，不是结论）
+
+## 现象
+用户看到什么、在什么操作后、影响范围；只写可观察的事实。
+
+## 区分过的候选原因
+| 候选 | 支持或反对它的记录 | 结论 |
+|---|---|---|
+
+## 原因
+最终原因，以及它由哪些记录证明。
+
+## 处理与结果
+采取了什么、结果如何；没有处理则写明。
+
+## 适用与限制
+版本、环境、数据条件；哪些情形下这个案例不适用。
+```
+
+## 案例索引
+
+| 场景 | 案例 | 状态 | 一句话 |
+|---|---|---|---|
+| 仪表板 | [仪表板图表报 polars query timeout，引擎优化器超时](dashboard-parameter-deep-binding.md) | confirmed | 只带日期参数、查询语句约 24 万字符：参数绑在很深的上游表，整条上游链被实时展开 |

package/content/knowledge/cases/dashboard-parameter-deep-binding.md

@@ -0,0 +1,32 @@
+---
+scene: dashboard
+status: confirmed
+recorded: 2026-11-07
+---
+
+# 仪表板图表报 polars query timeout，引擎优化器超时
+
+## 现象
+
+仪表板里一个图表取数失败，页面报错。整个请求约 3.4 秒，HTTP 返回 200，但 span 标了错误。引擎 `query` span 上的报错是 `Task execution timeout after 2003 ms (limit: 2000 ms)`，往上被包装成 `QueryTimeOutException` / `polars query timeout`。
+
+## 区分过的候选原因
+
+| 候选 | 支持或反对它的记录 | 结论 |
+|---|---|---|
+| 引擎资源不足或排队 | 引擎排队和计划生成都很快，失败在优化阶段的计时保护上，没有内存超限 | 排除 |
+| 图表自身查询太重 | 组件本身只有一个查询；请求里除了参数没有别的条件 | 不是主因 |
+| 筛选或动态字段扩大了计算 | `previewComponent` 上筛选树为空，动态字段计数为 0 | 排除 |
+| 参数绑在很深的上游表，触发整条上游链实时展开 | 请求只带了两个日期参数（`controls.parameter_names`）；日志 `dax parse too slow, dax length = 239934`，查询语句约 24 万字符；`begin get allParent` / `end get parent` 成对出现约 30 次 | 成立 |
+
+## 原因
+
+两个日期参数绑在离图表很远的上游父表上。参数值一变，上游已经存好的结果都用不了，只能把整条上游链一起实时展开，生成的查询语句膨胀到约 24 万字符，引擎优化器在 2 秒预算内处理不完而超时。引擎超时只是表象，原因在仪表板的参数绑定层级。研发已复核。
+
+## 处理与结果
+
+建议把参数绑定挪到靠近图表的表上，挪之前和用户确认业务口径。调大优化器超时预算只是让它多算一会儿，解决不了查询太大的问题，不作为首选。
+
+## 适用与限制
+
+适用于仪表板内组件取数报引擎超时或内存超限、请求只带参数、查询语句异常长的情况。参数具体绑在哪张表 trace 里看不到，要请用户在仪表板的参数设置里核对。查询语句长度要和同一组件平时或单独预览时比，不能只看绝对值。

package/content/knowledge/common/README.md

@@ -0,0 +1,31 @@
+# 通用知识
+
+跨场景共用的规则：性能排查入口、SigNoZ 环境、trace 场景路由、公共查询规则、知识适用性。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 性能问题从哪里入手 | [workflow.md](workflow.md) | 性能排查入口：选场景域的提示、易错点 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | SigNoZ 环境、URL 与后端 `service.name` 的映射和选择顺序 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 只有 trace 或场景不明时怎样识别入口场景；仪表板组件预览入口的来源判定 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | 知识与本次记录的适用核对 |
+| 写查询、选取证路径 | [queries.md](queries.md) | 公共查询规则的必读部分：默认值速查、工具调用、调查起点、查询约束 |
+
+## 展开明细
+
+| 文件 | 何时读 | 内容 |
+|---|---|---|
+| [topics/query-example.md](topics/query-example.md) | 工具说明不可读、需要 Query Builder 原始结构时 | 原始查询结构例子 |
+| [topics/start-and-anchors.md](topics/start-and-anchors.md) | 从现象、截图或转抄的 ID 开始，还没有可信的执行锚点时 | 锚点可信度；按现象决定先查什么 |
+| [topics/linked-traces.md](topics/linked-traces.md) | 从原 trace 找后台独立执行 trace（`linked`），或反过来时 | 独立 trace 的显式链接 |
+| [topics/query-budget.md](topics/query-budget.md) | 判断还能再查几次、已有结果能否复用时 | 查询预算与结果复用 |
+| [topics/baseline-comparison.md](topics/baseline-comparison.md) | 用户表达“之前正常”“最近变慢”，或仪表板内组件异常需要单独预览对照时 | 主动对比与基线；仪表板内外组件对照 |
+| [topics/large-results.md](topics/large-results.md) | 响应很大、需要落盘读取，或用户要求线上取样评测时 | 大结果、临时文件与取样 |
+| [topics/setup-signoz-mcp.md](topics/setup-signoz-mcp.md) | 需要安装、配置或恢复 SigNoZ MCP，或实时查询因工具、连接、鉴权问题被阻断时 | 配置 SigNoZ MCP：流程、安装、客户端接入、恢复 |
+
+## 关联
+
+- 相关知识域：[案例库](../cases/README.md)：已核实案例，只用于提出假设

package/content/knowledge/common/concepts.md

@@ -0,0 +1,49 @@
+# 通用 · 概念与关联
+
+各域共用的 SigNoZ 环境和后端服务映射，用来确定这次查哪个环境、过滤哪个 `service.name`。这里不放 API Key，也不规定具体客户端怎么配置。按下表直接确认，不用跑脚本。
+
+## 环境映射
+
+| 对用户名称 | 可识别别名 | SigNoZ URL | 推荐 MCP 名称 |
+|---|---|---|---|
+| 测试 | 测试、test | `https://signoz.jsydevelop.com` | `signoz_test` |
+| 正式 | 正式、work | `https://signoz.work.jsydevelop.com` | `signoz_work` |
+
+对用户只有“测试环境”和“正式环境”两个选项。团队口头说的 `work 环境` 就是正式环境，问用户时也只说“正式环境”，不要多出一个“工作环境”。
+
+`prod` 和 `production` 不是正式环境的别名。`prod` 在后端语境里是测试 SigNoZ 实例下的一个服务子环境；`production` 目前没有确认过的含义，不参与自动识别。
+
+有的客户端只连一个 SigNoZ MCP，靠工具的 `env` 参数切环境：正式环境传 `work`，测试环境按下面后端子环境的名字传；`env=prod` 查的是测试实例，不是正式环境。
+
+推荐 MCP 名称只是为了各客户端叫法一致。客户端已有别的稳定名称就保留，以连接信息里的 URL 为准；调用方式和参数以当前客户端实际提供的工具为准。已经确认的环境和本轮成功的查询直接复用，不因为工具前缀不同就重新安装或验证。
+
+## fx-data-server 后端子环境
+
+SigNoZ 实例和后端 `service.name` 是两层信息。查后端请求时两者都要定下来，并把 `service.name` 放进查询过滤。
+
+| 用户或部署表达 | SigNoZ 实例 | 后端 `service.name` |
+|---|---|---|
+| `test` | 测试 | `hihidata-jsy-test` |
+| `dev` | 测试 | `hihidata-jsy-dev` |
+| `prod` | 测试 | `hihidata-jsy-prod` |
+| `perftest` | 测试 | `hihidata-jsy-perftest` |
+| `work` / `default` | 正式 | `hihidata-jsy-default` |
+
+例如“`work` 环境”连正式 URL、过滤 `service.name=hihidata-jsy-default`；“`prod` 环境”连测试 URL、过滤 `service.name=hihidata-jsy-prod`。几个子环境共用一个实例，连上以后仍要按服务过滤。不要凭 `service.environment=prod` 选实例，这个字段两个实例里都可能出现，后端样本也可能不填。
+
+## 选择顺序
+
+1. 用户给了 SigNoZ URL 或链接，以它为准。URL 和口头说的环境对不上时，查询前请用户确认是“测试环境”还是“正式环境”。
+2. 没有 URL，就用用户明确说的环境。
+3. 这次调查已经确认过环境，直接沿用，用户后面没再提也不切换。
+4. 新调查什么都没说，默认使用 work（正式环境），后端查询同时用正式环境的服务过滤。不再让用户选，也不去多个环境里探测。
+5. 从现有 MCP 连接信息核对目标 URL。已有本轮成功查询就不再额外验证。默认的 work 连不上就去恢复这个连接，不改用测试环境。用户给的名称或 URL 认不出来、或者互相矛盾时，只处理这一处歧义，不拿默认值盖过去。
+
+## 使用边界
+
+- 只有用户明确要求跨环境核对某个精确 ID 时，才去多个环境查；平时默认 work，不跨环境扫描。
+- 缺时间时不顺带让用户选环境。时间等入口默认值见[公共查询规则](queries.md)的“默认值速查”。
+- 环境一旦确认，这次诊断的 trace、日志和 metric 都只查这个环境，不混用别的环境的数据。
+- `service.environment` 这类 attribute 只能在当前实例里过滤，代替不了选实例。
+- MCP 能读某个环境的 SigNoZ，不代表业务页面链接也有同样的权限。
+- 测试和正式环境的 API Key 分开维护，不能混用或互相覆盖。

package/content/knowledge/common/{knowledge-applicability.md → conclusions.md}

@@ -1,10 +1,14 @@
-# 怎样使用本指南中的知识
+# 通用 · 能下什么结论
 
-指南中的业务关系和字段说明用于解释实际记录，不能代替本次问题的证据。排查从手上已有材料开始，不要求取得产品代码。
+回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么，结论能下到哪一步”。
 
-同一调查已经读过且适用范围未变化的知识直接复用。操作、版本、配置、字段或来源发生变化时，只重新核对受影响的部分；新的执行仍需自己的运行证据。更新 analyzer 的知识适用性、身份和关联核对继续按其契约执行，不能用“已读过”代替本次证据核对。
+## 知识适用性
 
-## 核对适用条件
+指南中的业务关系和字段说明用于解释实际记录，不能代替这次问题的日志和 trace。排查从手上已有材料开始，不要求取得产品代码。
+
+同一调查已经读过且适用范围未变化的知识直接复用。操作、版本、配置、字段或来源发生变化时，只重新核对受影响的部分；新的执行仍要看它自己的运行记录。更新域的知识适用性、身份和关联核对继续按[更新 · 能下什么结论](../update/conclusions.md)执行，不能用“已读过”代替对这次记录的核对。
+
+### 核对适用条件
 
 1. 先确认实际操作。接口版本号或通用计算记录不能单独说明业务场景。
 2. 核对页面、请求和日志中实际出现的字段及含义。没有某个字段，不代表对应筛选、联动或处理过程不存在。
@@ -12,11 +16,11 @@
 4. 历史记录可以帮助理解当时发生的操作，但历史入口不应成为寻找当前问题的默认条件。
 5. 更新记录之间需要明确关联；无法关联的部分保留未知。已经明确属于某次引擎任务的统计仍可单独分析，但不能用它补造缺失的更新关系。
 
-## 出现不一致时
+### 出现不一致时
 
 记录实际看到的字段、业务现象和与指南不同之处。说明哪些判断受影响，再选择补充对应执行记录、核对可取得的产品版本或交接研发；不要要求使用者查找提交号或产品实现。
 
-本轮交付时，将有依据的差异按[诊断后的需求反馈](../../docs/diagnostic-feedback.md)反馈给使用者。区分适用范围内的已确认不一致与范围未知的待核实差异；空结果、字段缺失或截断不能单独证明文档错误。
+有依据的差异按[诊断后的需求反馈](../../docs/diagnostic-feedback.md)反馈，区分适用范围内的已确认不一致与范围未知的待核实差异；空结果、字段缺失或截断不能单独证明文档错误。
 
 知识校验用于确定结论的适用范围。信息不足时，向使用者说明哪一段还不能确认，无需让客户理解内部文件、校验格式或工具名称。