@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/AGENTS.md

@@ -1,82 +1,62 @@
 # core-ai Agent 执行契约
 
-你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。结合业务操作、日志和项目知识，说明观察到的异常、可能原因和排查方向；需要确认具体对象或执行时，再补充对应证据。
+你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。照着用户说的操作、手上的日志和 trace，结合本仓库的知识回答问题：看到了什么异常、可能是什么原因、接下来往哪里查。
 
 ## 使用前更新代码
 
-只有本项目根目录存在 `.git` 文件或目录时，才按源码仓库方式更新：每次新对话首次使用时，在该根目录运行 `git pull --ff-only`；同一对话不重复更新。保留本地改动，不切换分支。无法安全更新或联网失败时，简短说明并继续原任务。
-
-通过 CLI 安装的目录没有 `.git`，不得在它或使用者的其他项目执行 Git 更新。全局 Skill 通过 `context` 返回内容目录时，遵循 [npm 安装副本规则](#安装副本的助手规则)。首次使用时读取对应说明，本轮已读则复用。升级由使用者明确发起，不在诊断中途更换版本。
+- 源码仓库（根目录有 `.git`）：每个新对话第一次使用时，在根目录运行一次 `git pull --ff-only`，同一对话里不再重复。保留本地改动，不切换分支；更新不了就简单说一句，继续做原来的事。
+- npm 安装副本（没有 `.git`）：不做 Git 更新，也不去更新使用者的其他项目，按下面的[安装副本规则](#安装副本的助手规则)来。
 
 ### 安装副本的助手规则
 
-以下约定仅适用于 npm CLI 安装副本，由执行诊断的 Agent 读取并遵循；源码仓库不适用：
-
-- 安装副本没有 `.git`，跳过 Git 更新检查，不更新用户的其他项目。只读取当前问题需要的 Skill 及引用，不将交付方案全文作为诊断前置知识。
-- 本次调查固定使用首次 `context` 返回的版本、`content_root`、`agent_rules`、`skills_root`、`node` 和 `pinned_cli`；脚本通过 `<node> <pinned_cli> python <脚本路径> ...` 执行。仓库相对路径以 `content_root` 为基准，文档链接相对引用文件解析。
-- 用 `session` 获取临时目录。Metric 纯正文使用 `metric --metric`；SigNoZ JSON 响应使用 `metric --metric-log-json ... --task-name ...`，不可混用。
-- 已有可用 MCP 直接复用；实时查询受阻时读取 [MCP 配置 Skill](.agents/skills/setup-signoz-mcp/SKILL.md)，适配当前客户端。凭据保存在本机配置，不写入能力包或诊断报告。
-- 用户要求更新、回退、卸载或检查时使用稳定入口的 `update`、`rollback`、`uninstall`、`doctor`。版本切换后按客户端要求刷新技能或新开聊天；当前调查不切换版本。
+- 一次调查固定使用第一次 `context` 返回的版本、`content_root`、`node` 和 `pinned_cli`，新版本留给下次诊断。脚本用 `<node> <pinned_cli> python <脚本路径> ...` 运行；仓库相对路径以 `content_root` 为基准，文档里的链接相对所在文件解析。
+- 用 `session` 拿临时目录，SigNoZ 大响应和 Metric 正文都存在那里，不写进安装目录。
+- `context`、`status`、`session` 的 JSON 里，或 `python` 命令的 stderr 里出现 `auto_update.notification`（stderr 里的字段是 `fx_data_diagnostics.auto_update.notification`）时，用其中的 `message` 简短告诉用户，按 `id` 避免重复提醒。没有通知就不提，也不为了等更新去轮询。
+- 用户要更新、回退、卸载或检查时，用稳定入口的 `update`、`rollback`、`uninstall`、`doctor`。
 
-## 1. 先识别任务模式
+## 1. 先看这一轮要回答什么
 
-- 仓库开发模式：修改本仓库的 Agent、Skill、Knowledge、Experience、测试或文档，直接按第 5 节执行，不进入线上诊断。只有用户明确要求验证真实诊断行为时，才在授权范围内使用线上只读证据。
-- 问题诊断模式：排查具体业务问题，按下方规则选择一个入口。
+- 仓库开发模式：用户在改本仓库的 Agent、知识、评测、测试或文档时，按源码仓库里的 `maintainers/README.md` 做（npm 安装副本没有这个目录），不去查线上。只有用户明确要验证真实诊断行为，才在授权范围内用线上只读数据。
+- 问题诊断模式：用户在排查具体业务问题，按下面选一个入口。
 
-先明确本轮要回答什么。查记录、数值或链接时，直接给出事实和覆盖范围；分析原因时，先从已有日志和现象寻找线索，再按需要定位执行、补充证据；解释前后变化时，分别核对目标和基线。简单事实请求不自动扩展为根因调查。原诊断尚未完成时，先回答追问，再继续排查，沿用已确认的对象、时间和现象。
+要记录、数值或链接，直接给事实和覆盖范围；要分析原因，先从已有日志和现象找线索，需要时再补查；要解释前后变化，目标和基线分开核对。简单的事实问题不扩展成根因调查。追问先答再接着查，已确认的对象、时间和现象继续沿用。
 
-## 2. 按问题类型路由
+## 2. 选入口
 
-根据用户目标选择 Skill，不要求使用者选择内部能力。选定后只读取对应 Skill 及当前步骤需要的参考资料，不预加载全部场景。查找规则时，先看[文档目录](docs/index.md)的“按主题查找”，以登记的归属文件为准。
+入口只是起点，没有必须走完的步骤，材料够了就直接回答。
 
-| 用户目标 | 入口与边界 |
+| 用户目标 | 起点 |
 |---|---|
-| 慢、超时、卡顿、内存超限、OOM、`MemoryLimitExceeded`、资源消耗异常、性能退化或回归 | `$diagnose-performance` 维护调查、选择场景并汇总结果。只有资源、时间、trace 或跨场景线索也可进入；内存超限属于性能失败模式。 |
-| 明确只要求获取或解读 engine metric | `$analyze-engine-metric` 自行获取、解析并解释执行层证据，不负责 DSL 或业务步骤映射。端到端性能问题仍走性能入口。 |
-| 只解释更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task 或核对更新计数 | `$analyze-analysis-table-update-runtime` 返回证据摘要，不维护多轮调查、不协调跨场景、不宣称最终根因或处置优先级。性能目标须经性能入口和更新场景调用。 |
-| 明确只要求配置诊断环境，或必要的实时查询被工具/连接问题阻断 | `$setup-signoz-mcp`；恢复后继续原调查。已有材料足够时继续离线分析。 |
-| 其他问题：非性能报错、结果异常、稳定性问题 | 目前没有成熟的问题型主 Skill。开始时简短说明覆盖限制，依据已有材料按[问题定位方法](docs/architecture.md)辅助分析，不机械并入性能流程。非性能更新异常可用更新 analyzer 解释运行证据，持续根因调查或处置排序仍缺少专项负责能力。 |
-
-问题类型不明确时，先用已有日志、精确 trace 或运行材料做只读浅分型，判断更接近性能、报错/结果异常，还是更新链路解释。仍无法判断或缺少材料时，再向用户或客户确认；浅分型不扩大查询范围、不同时启动多个专项流程。已明确慢、超时、OOM 等性能现象时，不重复询问问题类型。
+| 慢、超时、卡顿、内存超限、OOM、`MemoryLimitExceeded`、资源消耗异常、性能退化或回归 | [性能排查入口](knowledge/common/workflow.md)，再按场景进入对应知识域 |
+| 只想拿到或看懂一份 engine metric | [引擎知识](knowledge/engine/workflow.md) |
+| 只想弄清更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task，或核对更新计数 | [更新知识 · 解释更新记录](knowledge/update/workflow.md#解释更新记录) |
+| 只想配置诊断环境，或实时查询被工具、连接问题挡住 | [配置 SigNoZ MCP](knowledge/common/topics/setup-signoz-mcp.md)，弄好后回到原问题 |
+| 其他问题：非性能报错、结果异常、稳定性问题 | 有报错原文就先查[信号索引 · 常见报错](knowledge/signal-index.md#常见报错)；没有专门入口，先说明这块覆盖有限，再按[问题定位方法](docs/architecture.md)结合已有材料分析 |
 
-用户已明确只要更新记录、Metric 数值或执行链接时，先按该事实目标处理，不为选择问题型入口追问故障类型。
+分不清是哪类问题时，先拿已有日志、trace 或运行材料做一次只读浅分型，还是判断不了再问用户。用户已经说了慢、超时、OOM 这类现象，就不用再问问题类型。
 
-## 3. 诊断执行与证据边界
+## 3. 诊断原则
 
-- 先使用已有信息；脱敏材料足够时离线分析。只追问下一步判断所缺的关键信息，能一起确认的合并询问；不重新索要已提供的信息。
-- 默认只读调查。未经用户明确同意，不修改业务资源、不触发任务、不改变配置或权限。不在报告、fixture、Knowledge、终端输出或仓库文件中保存凭据、租户敏感数据和完整业务载荷。
-- 本次事实须由对应资源和运行记录证明。区分直接证据、相关信号和待验证推断；指南说明可能的行为，Experience 只用于提出假设。字段缺失、结果为空或截断，都不能证明行为没有发生。
-- 可以根据日志线索、项目知识和通用经验提出多个候选原因，说明各自依据及待核实点。知识未覆盖的方向也可作为假设；分析方法见[问题定位方法](docs/architecture.md#每一步都用来区分原因)。
-- 首次使用场景知识时按[知识适用性](knowledge/common/knowledge-applicability.md)核对来源范围。已知产品版本可辅助核对，未知时保留依赖版本的判断，不要求使用者查找内部发布标识。更新 analyzer 负责其专用校验；缺少版本、关联键或候选消歧证据时保留未知，不用引擎统计补造更新关系。
-- 同一调查复用已确认范围、已读规则、查询结果和临时产物，只核对变化部分。切换 Skill 后继续当前调查，无需重新开始或创建子代理。交接时带上当前问题、所选执行与范围、证据/产物位置及覆盖边界、缺口、下一步和已有反馈线索；接收方继续剩余动作，不重复发现或解析。
-- 相互独立且都能改变当前判断的取证或分析可以并行；环境解析、执行选择、依赖前次结果的查询和最终归因顺序推进。不能为并行而扩大调查范围。
-
-### 工具使用
+- **先认场景，报错只是表象**。超时、内存超限、行数上限多半报在引擎里，引擎只说明撞了什么线，为什么算得这么大要回业务层找：分析表看哪个步骤放大或攒齐了数据（左右合并多对多、同环比自关联、拆分到行、补全缺失行、累积值或排名），还是来源表变大了；更新看是不是上游失败连带、哪个节点重；组件和仪表板看查询本身，以及筛选、参数、动态字段、联动绑在哪张表上。先弄清是哪个场景的哪类请求，再回场景的 `workflow.md` 找原因、对症给建议；只讲引擎超时或 OOM，用户没法处理。
+- 先用手上已有的信息，材料够用就直接分析。只追问下一步判断真正缺的那一项，用户给过的不要再要。
+- 默认只读。没有用户明确同意，不改业务资源、不触发任务、不动配置或权限。凭据、租户敏感数据和完整业务载荷不要写进报告、知识、终端输出或仓库文件。
+- 分清哪些是日志和 trace 里直接记着的、哪些只是相关信号、哪些还只是推测。知识讲系统一般怎么做，这次实际发生了什么看这次的记录；字段缺失、结果为空或被截断都说明不了没发生。
+- 可以根据日志线索、项目知识和通用经验提几个候选原因，说明各自依据及待核实点；知识未覆盖的方向也可作为假设。
+- 同一个调查里，已经确认的范围、读过的知识和查到的结果直接复用；互不依赖的查询可以并行。
 
-需要新增运行证据时读取[公共查询规则](knowledge/common/signoz-query-policy.md)，同轮已读则复用。环境、时间窗、dagId、历史对比基线等入口默认值，以及工具发现、查询预算、空结果回退和大结果传递只在该文件维护，这里和各 Skill 不重复。
+### 查找知识
 
-- 已有 traceId 或任务标识时精确查询，不重做资源发现。每次查询前确认已有结果是否足够，只补一个尚未确认的判断缺口。
-- 用户已表达历史对比（如“之前没超限”）或企业入口只缺时间时，按默认值直接查询；没有实际工具或证据阻断时，不把下一项可执行查询留给用户。企业入口本轮只覆盖更新。
-- 助手依据知识和当前工具声明选择执行、构造查询、核对结构、判断关联并解释证据。Metric 正文等大材料由解析脚本处理；查询时间按[公共查询规则](knowledge/common/signoz-query-policy.md#查询约束)直接使用当前工具支持的格式。工具原始响应直接保存或交给解析器，上下文只保留必要事实、完整性状态和产物路径。
+知识按域分（common、dataset、component、dashboard、update、engine），每个域的文件名都一样，完整说明见[知识目录](knowledge/README.md)：
 
-## 4. 交付与停止
+1. **先认场景**：场景明确就直接进；不明确先看[场景识别](knowledge/common/signals.md)。第一次进某个域，先扫一眼它的 `workflow.md`，里面是从哪下手、常见现象和容易踩的坑。
+2. **按名称查**：手上有 span、属性、日志名或报错原文，查[信号索引](knowledge/signal-index.md)，它直接指到含义所在的章节；查完回到场景接着找原因。
+3. **按要做的事读文件**：概念和关联读 `concepts.md`；认入口、看懂 span、attribute、日志读 `signals.md`；拿不准手上的日志和 trace 能下什么结论读 `conclusions.md`；要写查询读 `queries.md`。只读命中的章节。
+4. **还不够再展开**：看该域 `README.md` 登记的 `topics/`。相近的已核实案例在 [cases](knowledge/cases/README.md)，只用来提假设。不知道某条规则写在哪，查[规则归属索引](docs/index.md)。
 
-根 Agent 选择问题型主 Skill 并交付其结果，不替代专项重新分析。交付时保留证据、反证、缺口和结论的可靠程度；阶段性结果不能直接当作根因，专项未给出方案时也不能自行编造。
-
-证据已解释现象和关键触发条件时，交付结果。还有必要且可执行的分析时，继续推进，专项返回或 MCP 配置完成后也一样。缺少关键证据、候选无法区分或需要研发验证产品行为时，可交付已确认事实、可信假设、具体缺口和下一步所需的最小动作。某项关联缺失只限制依赖它的判断，在当前调查范围内仍可沿其他日志线索继续分析，不用扩大查询代替缺口说明。
-
-最终交付方首次答复前读取[诊断结果交付](docs/diagnostic-report.md)，本轮已读则复用。简单事实请求仍直接回答，保留专项结论及其限制。
-
-每次诊断交付时，按[诊断后的需求反馈](docs/diagnostic-feedback.md)检查本轮发现的场景知识缺口、本项目优化项和文档差异。有证据支持时，整理可转交的“需求反馈”，写清问题、已有依据、影响与期望；没有则省略。反馈用于改进 `core-ai`，使用者无需定位产品代码、设计方案或跟踪处理。复用已有证据，说明适用范围和待核实项，保留专项结论，不为反馈扩大调查；默认只反馈到当前对话。
+### 工具使用
 
-通用方法见[问题定位方法](docs/architecture.md)，场景说明见[按场景排查](docs/scenario-guide.md)。面向使用者说明业务结论和复核依据，不要求读取产品源码或搭建代码环境，不暴露内部 Skill 选择或知识校验协议。
+查新的日志或 trace 前，先看[公共查询规则](knowledge/common/queries.md)的“默认值速查”和“选择和调用工具”，查日志再看“查日志”。便捷搜索和 trace 详情不返回 `data.request_context` 这类业务属性，要用 Query Builder 在 `selectFields` 里点名取；返回时间是 UTC，给用户看换成北京时间。有 traceId 或任务标识就精确查。大响应存临时文件，用 shell 按需读。
 
-## 5. 仓库开发模式
+## 4. 交付
 
-- 修改前阅读[问题定位方法](docs/architecture.md)；新增或修改 Skill 时继续阅读[Skill 编写建议](docs/skill-writing-guide.md)，本轮已读则复用。
-- 修改前在[文档目录](docs/index.md)找到规则的归属文件，只改归属文件，其他位置写一句结论加链接；发现冲突时以归属文件为准，把另一处改成链接。新增、删除或改名文件，或新增跨文件规则时，同步更新目录。
-- 修改 Agent、Skill 或能力边界时，同步检查 README、architecture、roadmap、相关 Knowledge 和测试，只更新受影响的描述。
-- `.agents/skills/` 保持平铺，只创建确有内容的 `scripts/`、`references/`、`assets/`。系统事实写入 `knowledge/`，场景经验写入对应 Skill 的 `references/experience.md`。
-- 优先复用当前 Tool。将环境、字段、关联与调查选择的规则写入知识，供助手判断；只有大模型难以可靠完成的大材料解析和精确计算才保留脚本。
-- 仓库交付内容不得包含产品源码路径、类/方法索引、代码审计台账或要求读取产品代码的排查步骤。将核实过的行为改写为业务含义、可观察记录、判断方法和适用限制。
-- 使用 `scripts/validate.py` 执行适用的结构、链接、Skill 和行为验证；失败时修正实现，不放宽验证标准。
+结论是写给人看的。照着日志和 trace，结合已有知识，先直接回答用户问的东西。要记录、数值或链接，给事实和覆盖范围；分析原因，先说结论，再讲关键依据和还不确定的地方，需要时给下一步往哪查。用业务语言跟使用者说，知识里的内部说法（比如计数单位、关联边、锚点、`unknown`、`needs_revalidation`）要翻译成大白话；分析步骤用页面上的中文名（“第 53 步：新增字段”），不报 `AddNewColumn` 这类类型名或引擎算子名，不要让他们去读源码或搭代码环境。需要研发接手时，按[交接研发](docs/diagnostic-report.md#交接研发)整理材料。怎么写得更清楚可以参考[诊断结果交付](docs/diagnostic-report.md)。

package/content/README.md

@@ -12,15 +12,15 @@
 | 更新来源或数量不清楚 | 触发来源、更新链路、节点与尝试次数 |
 | 其他报错、结果异常或偶发不可用 | 核对现象与执行记录，整理已确认事实和待验证问题 |
 
-性能问题已有专项排查流程。其他问题先根据现有材料辅助分析。
+性能问题已有各场景的知识和入口提示。其他问题先根据现有材料辅助分析。
 
 ## 开始前准备
 
-交付方式见 [FX 数据诊断交付方案](docs/npm-cli.md)：用户说“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，Agent 从包内 README 的 Agent 入口读取安装说明，优先复用已有共享安装，再登记当前客户端的薄 Skill。CLI 使用 Node.js/npm，Python 解析环境按需准备。
+npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，它会按包内 README 安装（优先复用已有的共享安装），再登记当前客户端的 Skill。需要 Node.js/npm，Python 按需准备。安装副本每次新诊断时在后台检查更新，不耽误当前排查，更新失败继续用旧版（设计见源码仓库 `maintainers/npm-cli.md`）。
 
-1. 使用源码目录时，用支持 `AGENTS.md` 的 Agent 客户端（如 Codex、Claude Code）打开本仓库，更新规则见 [助手执行契约](AGENTS.md#使用前更新代码)；npm 安装副本按交付方案管理版本。
-2. 诊断需要查询 SigNoZ 的 trace、日志和引擎统计。当前客户端还没有 SigNoZ 连接时，助手会自动安装并配置，只需提供对应环境的 API Key。正式环境和测试环境的 Key 分别维护。
-3. 只有离线材料（日志、trace 导出、Metric 文件）时，无需配置连接，直接交给助手分析。
+1. 用源码目录时，用支持 `AGENTS.md` 的客户端（如 Codex、Claude Code）打开本仓库，更新规则见[助手执行契约](AGENTS.md#使用前更新代码)。
+2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动配置，只需提供对应环境的 API Key（正式、测试分开）。
+3. 只有离线材料（日志、trace 导出、Metric 文件）时不用配置，直接交给助手。
 
 ## 如何提问
 
@@ -40,7 +40,7 @@
 - 查企业更新没给时间时，默认看最近 24 小时。
 - 给了 dagId 就能直接查更新链路，不需要再提供时间。
 - 说“之前正常”“以前没超限”，助手会自动找之前的正常记录做对比，不需要先提供成功记录。
-- 仪表板内组件异常时，助手会先查找对应组件的单独计算记录；找不到也会继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照)。
+- 仪表板内组件异常时，助手会先查找对应组件的单独预览记录；找不到也会继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](knowledge/dashboard/workflow.md#组件取数先做对照)。
 - 缺少关键信息时，助手一次说明需要补充什么、用来判断什么。
 
 继续同一问题时，助手沿用已确认的范围和查询结果。简单追问（数值、链接）直接回答，不重新排查。
@@ -51,47 +51,16 @@
 
 - 当前结论：哪个对象的哪次操作出现问题，已定位到什么环节或条件。
 - 关键依据：对应执行记录、错误、统计或对照结果，以及它们如何支持判断。
-- 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的证据。
-- 需求反馈（有证据支持时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](docs/diagnostic-feedback.md)。
+- 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的材料。
+- 需求反馈（有依据时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](docs/diagnostic-feedback.md)。
 
 ## 延伸阅读
 
-- [文档目录](docs/index.md)：全部文档的分层、归属和按主题查找。
+- [规则归属索引](docs/index.md)：每条规则由哪个文件维护。
 - [问题定位方法](docs/architecture.md)：通用排查思路与结论分层。
 - [按场景排查](docs/scenario-guide.md)：分析表、组件、仪表板、更新各自看什么。
 - [诊断结果交付](docs/diagnostic-report.md)：结论、复核依据和研发交接。
-- [指南完善方向](docs/roadmap.md)：已覆盖范围与待补齐能力。
 
 ## 维护本项目
 
-查找或修改规则前，先看[文档目录](docs/index.md)，确认规则归属、文档分层和 Skill 调用关系。每条规则只在归属文件中维护，其他位置通过链接引用；新增、删除或改名文件时同步更新目录。编写约定见 [Skill 编写建议](docs/skill-writing-guide.md)。
-
-诊断脚本放在所属 Skill 的 `.agents/skills/<skill>/scripts/` 中。修改后在仓库根目录运行 `python3 scripts/validate.py`，检查结构、链接、脚本处理和文档目录是否完整。
-
-交付代码使用 `node --test packages/ai-diagnostics/tests/test_npm*.mjs` 验证安装与版本管理。整体设计见 [构建与发布](docs/npm-cli.md#32-构建打包)。
-
-### 发布 npm 包
-
-发布机器需要 Bash、Git 和可访问本机目录的 Docker，适用于 macOS 或 Linux；构建所需的 Node/npm/Python 由 Docker 提供。提交代码后，在干净工作区执行发布。
-
-**本地和 CI 都通过环境变量 `NPM_TOKEN` 注入发布凭据。** 按 [npm 官方说明](https://docs.npmjs.com/creating-and-viewing-access-tokens/) 创建仅授权 `@fx-data/ai-diagnostics` 读写、启用 Bypass 2FA 并设置有效期的细粒度 Token。本地可在 Bash 或 zsh 中隐藏输入，再导出变量：
-
-```sh
-read -rs NPM_TOKEN
-export NPM_TOKEN
-bash scripts/npm-publish.sh
-```
-
-执行第一行后粘贴 Token 并回车，输入不会显示，也不会写入命令历史。变量在当前终端会话内有效；若终端已注入 `NPM_TOKEN`，直接执行发布命令即可，无需配置本地文件。
-
-**希望本机保存 Token 时，可选用一次性配置：**
-
-```sh
-bash scripts/npm-publish.sh --configure-token
-```
-
-脚本隐藏输入并保存到 `~/.config/fx-data-diagnostics/npm-token`（遵循 `XDG_CONFIG_HOME`），仅当前用户可读写。以后无环境变量时自动读取；Token 过期或更换时重新配置。环境变量始终优先，缺少 Token 会在构建前提示获取和配置方式。
-
-只构建验证使用 `bash scripts/npm-publish.sh --dry-run`，不需要 Token；重试已保存的产物使用 `bash scripts/npm-publish.sh --resume <产物目录>`，沿用原版本与包。完整流程见[发布分发](docs/npm-cli.md#33-发布分发)。
-
-CI 复用同一命令：设置 `CI=true`，从流水线 Secret 注入 `NPM_TOKEN`，发布容器需能访问 npm 官方仓库。CI 不读取个人配置、不交互输入；Token 仅注入发布阶段，不进入构建镜像、npm 包或日志。
+修改本仓库、运行验证或发布 npm 包，见源码仓库中的 `maintainers/README.md`；该目录不随 npm 包发布。

package/content/docs/architecture.md

@@ -1,118 +1,89 @@
 # 问题定位方法
 
-从使用者的一次具体操作开始，依据运行记录和项目知识确认问题发生的环节、条件和原因。使用者无需准备产品代码环境；证据不足时，列出需要补充的材料或交给研发验证的问题。
+从使用者的一次具体操作开始，用运行记录和项目知识确认问题出在哪个环节、什么条件下、为什么。使用者不需要产品代码环境；材料不够时，列出要补什么，或交给研发验证。源码目录和 npm 安装副本的判断方法相同，推理都由当前 Agent 完成。
 
-诊断内容可以通过源码目录或 [npm CLI 与全局 Skill](npm-cli.md) 提供；安装方式不改变判断方法，CLI 负责版本与脚本入口，推理仍由当前 Agent 完成。
+## 目录
 
-## 先把问题说清楚
-
-环境、时间窗、dagId 和历史对比的默认值见[公共查询规则](../knowledge/common/signoz-query-policy.md)的“默认值速查”，已有信息不重复索要。企业入口当前只覆盖更新。
+- [先把问题说清楚](#先把问题说清楚)
+- [找到对应的这次操作](#找到对应的这次操作)
+- [沿实际操作还原过程](#沿实际操作还原过程)
+- [每一步都用来区分原因](#每一步都用来区分原因)
+- [区分发现与原因](#区分发现与原因)
+- [单次分析与前后对照](#单次分析与前后对照)
+- [什么时候结束排查](#什么时候结束排查)
+- [什么时候交接给研发](#什么时候交接给研发)
+- [其他问题如何开始](#其他问题如何开始)
 
-从客户的一次具体操作开始，先确认预期和实际结果。以下信息已有的直接使用，缺少时再确认：
+## 先把问题说清楚
 
-- 操作：客户点击、修改或执行了什么？
-- 对象：涉及哪个分析表、组件、仪表板或更新任务？
-- 时间和环境：什么时候发生，在哪个环境？时间是否包含时区？
-- 现象和影响：慢、失败、结果异常，还是暂时不可用？影响一个对象还是多个对象？
+先确认预期和实际结果。下面几项已有的直接用，缺的再问（默认值见[默认值速查](../knowledge/common/queries.md#默认值速查)）：
 
-查看更新记录时，给出状态和时间范围；询问内存时，给出对应执行的数值、单位和来源；索要链接时，直接给已取得的链接。分析原因或前后变化时，再完成对应执行和对照的必要分析。排查期间的简单追问先回答，随后继续定位。
+- 操作：点了、改了或执行了什么；
+- 对象：哪个分析表、组件、仪表板或更新；
+- 时间和环境：什么时候、哪个环境、时间带不带时区；
+- 现象和影响：慢、失败、结果不对还是暂时不可用，影响一个还是多个对象。
 
-“一直很慢”与“今天某次操作慢”的调查范围不同；“以前正常”也不意味着任意一次历史操作都能作为对照。先用已有信息缩小范围，不要求客户一次准备完整清单。
+“一直很慢”和“今天某次慢”调查范围不同；“以前正常”也不是随便哪次历史都能当对照。用已有信息先缩小范围，不要求用户一次准备完整清单。
 
 ## 找到对应的这次操作
 
-已有执行链接时直接查看；只有对象链接时，在确认的环境和发生时间内寻找记录。只有截图时先核对其中的对象和标识，字符看不清或首次查询没有结果时先确认，不按猜测扩大搜索。
+有执行链接就直接看；只有对象链接，在确认的环境和时间里找记录；只有截图，先核对上面的对象和标识，看不清或首查没结果时先确认，不按猜测扩大搜索。
 
-明确失败或内存超限时，先找对应错误和失败记录；明确只是慢时，先找对应操作的耗时记录。不要因为另一条记录更慢或错误更严重，就把它当成客户这次的问题。
-
-把每次执行的时间、对象、结果和链接放在一起。有多个可信候选且必须选定执行才能回答时，说明它们的区别，再确认要分析哪次。企业更新概况可直接列观察结果并突出异常，不要求用户选一条正常记录深入。前台预览、后台更新、失败重试和正常对照分别保留，不能拼成一次执行。
+失败或内存超限先找对应的错误记录，只是慢就找这次的耗时记录，不因别的记录更慢、错误更严重就换成它。前台预览、后台更新、失败重试、正常对照分开记，不拼成一次执行。多个候选都可信、又必须选一个才能回答时，说明区别再请用户确认；企业更新概况直接列观察结果、突出异常即可。
 
 ## 沿实际操作还原过程
 
-先说明本次算了什么，再解释哪里慢或为什么失败。按[场景排查](scenario-guide.md)选择需要核对的内容：
-
-- 输入读取了哪些表、时间范围或数据？
-- 哪些筛选、参数、聚合、联动或权限条件参与了计算？
-- 慢点发生在等待、计算、写入，还是结果返回？
-- 是否存在失败后重试？重试增加了多少工作？
+先说清这次算了什么，再解释哪里慢、为什么失败。按[场景排查](scenario-guide.md)核对：读了哪些表和数据范围；哪些筛选、参数、聚合、联动、权限参与了计算；慢在等待、计算、写入还是返回；有没有失败重试，多了多少工作。
 
-页面配置说明可能怎样计算，本次请求和执行记录说明实际怎样计算。配置、日志与统计需要能对应同一对象和同一次操作，才能合在一起解释。
-
-组件取数慢和分析表更新慢同时出现时，需要确认这次组件请求是否在等待或读取该次更新的结果。共享底层计算只能提供关联线索，还不足以确认原因相同。
-
-仪表板内组件异常优先按[组件取数对照](../.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照)核对单独预览，再分析实际条件与计算路径；对照缺失不阻断本次异常分析。
+页面配置说明可能怎么算，请求和执行记录说明实际怎么算，两者对得上同一对象、同一次操作才能合起来解释。组件取数慢和更新慢同时出现时，要确认这次组件请求是不是在等或读这次更新的结果，共享底层计算只是线索。仪表板内组件异常先按[组件取数对照](../knowledge/dashboard/workflow.md#组件取数先做对照)看单独预览，没有对照也继续分析。
 
 ## 每一步都用来区分原因
 
-先看错误前后的时间线、重复出现的异常、耗时变化和上下游记录，从中提出少量候选原因，并按线索强弱安排核对顺序。每个方向说明哪条日志支持它、有什么其他解释，以及再看什么能区分；暂时缺少字段或关联时，将该方向保留为待验证假设，再看其他可用线索。
-
-把当前猜测写成可验证的问题。例如：
+看错误前后的时间线、重复出现的异常、耗时变化和上下游记录，提出少量候选原因，按线索强弱排序。每个方向写清哪条记录支持它、还有什么别的解释、再看什么能区分；缺字段或关联时保留为待验证假设，先看别的线索。相近的已核实案例见[案例库](../knowledge/cases/README.md)，只用来提方向。
 
 | 当前猜测 | 需要核对什么 | 能得出什么 |
 |---|---|---|
-| 筛选条件扩大了计算范围 | 本次筛选值、绑定字段、关联表路径和实际计算范围 | 说明哪些额外数据处理与该条件有关 |
-| 更新在等待上游 | 对应节点的开始时间、依赖状态和等待记录 | 区分等待耗时与计算耗时 |
-| 内存超限来自中间数据增多 | 本次输入量、计算阶段的输入输出、内存和失败记录 | 说明数据怎样形成并触发资源边界 |
-| 多条日志表示重复更新 | 各记录的更新、节点与尝试标识，以及明确关联 | 区分正常展开、重试与可能重复执行 |
-
-补材料或查询前，先说明哪项判断缺少证据，以及查询结果能区分哪些原因。查询条件没有变化时复用已有记录；没有结果时先核对环境、时间与对象，不同时扩大多个搜索条件。
+| 筛选条件扩大了计算范围 | 筛选值、绑定字段、关联表路径和实际计算范围 | 哪些额外的数据处理和这个条件有关 |
+| 更新在等上游 | 节点开始时间、依赖状态和等待记录 | 等待和计算各占多少 |
+| 内存超限来自中间数据变多 | 输入量、各阶段输入输出、内存和失败记录 | 数据怎么变大、怎么撞上上限 |
+| 多条日志是重复更新 | 各条记录的更新、节点和尝试标识及明确关联 | 正常展开、重试还是重复执行 |
 
-一次查询已经返回所需的完整记录时，直接整理数量或状态，不再为同一事实重复查询。结果达到上限、尚有分页或需要总体统计时，才补聚合或继续读取；零结果不能直接当作没有执行。
-
-继续调查或转入另一场景时，沿用已确认的操作、执行范围和证据，只补下一项判断所缺的内容。已有直接证据能解释现象时，核对反证和适用范围即可，无需重新生成假设。相互独立且必要的分析可以并行；依赖执行选择或前次结果的动作顺序完成。
-
-助手依据知识选择执行、构造查询、核对结构与知识适用范围，并判断原因；脚本使用范围见[助手执行契约](../AGENTS.md#工具使用)。摘要中的总数与返回数不同表示展示不全，不能据摘要缺项判断记录不存在。
-
-已有证据解释现象时，先核对本次必要取证是否完成：已选定的慢或失败引擎执行需要对应的引擎统计。必要分析完成后交付，不为走流程重复查询。
+查之前先说清缺的是哪项判断、结果能区分什么；查询方式、复用和空结果的处理见[公共查询规则](../knowledge/common/queries.md)。已有记录能直接解释现象时，核对反证和适用范围即可。已选定的慢或失败引擎执行要看对应的 Metric；必要的都查完就交付，不为走流程重复查。
 
 ## 区分发现与原因
 
-结论的力度应与证据一致：
+结论说得多肯定，要和依据相称：
 
-| 层次 | 可以怎样表述 | 还不能说明什么 |
+| 层次 | 可以怎样说 | 还不能说明 |
 |---|---|---|
-| 已确认现象 | 这次更新失败，错误为内存超限 | 数据为什么消耗了这些内存 |
-| 已确认过程 | 某个计算阶段产生了大量中间结果，下游阶段承受了这些数据 | 为什么业务配置或输入变成这样 |
-| 已确认原因 | 本次具体条件导致计算范围扩大，记录显示它如何形成压力并触发失败 | 未验证的修改一定能解决问题 |
-| 待验证推测 | 当前现象与上游等待相符，但缺少依赖完成时间 | 上游等待已经是根因 |
+| 已确认现象 | 这次更新失败，错误是内存超限 | 为什么用了这么多内存 |
+| 已确认过程 | 某个阶段产生了大量中间结果，下游承受了这些数据 | 为什么业务配置或输入变成这样 |
+| 已确认原因 | 这次的具体条件扩大了计算范围，记录显示它怎样形成压力、触发失败 | 没验证的修改一定能解决 |
+| 待验证推测 | 现象和等上游相符，但缺依赖完成时间 | 等上游就是根因 |
 
-只有总行数，不能推断数据倾斜或某种计算导致放大；只看到两个事件时间接近，不能断言它们存在因果关系；字段缺失也不等于相应业务行为没有发生。
-
-涉及行数、字节、内存或放大比例时，写明统计对象、单位和来源。不同任务、不同阶段的数值不能随意相除或相加。引擎的物理计算阶段也不能直接命名为页面上的业务步骤。
+只有总行数不推断倾斜或放大；两个事件时间接近不说明因果；字段缺失不等于没发生。涉及行数、字节、内存、倍数时写明对象、单位和来源，不同任务、阶段的数不随便相除相加。引擎的物理阶段不能直接叫成页面上的步骤。
 
 ## 单次分析与前后对照
 
-“之前没超限”“以前正常”“最近变慢”已经表达对比目标。先定位本次执行，再按[公共查询规则](../knowledge/common/signoz-query-policy.md)主动查找基线，不要求用户先找成功 trace。基线不足时仍交付本次事实及覆盖缺口。
-
-只有本次失败材料时，先解释本次输入、数据处理过程和失败条件。正常样本不是开始或继续单次分析的必要材料。
+“之前没超限”“以前正常”“最近变慢”已经是要对比：先定位这次执行，再按[主动对比](../knowledge/common/topics/baseline-comparison.md#主动对比)主动找基线，不要求用户先找成功 trace。只有失败材料时，先解释这次的输入、处理过程和失败条件，正常样本不是必需的。
 
-要回答“为什么以前正常、这次不正常”，再核对正常对照。至少确认操作对象、查询条件、参数、数据范围和执行结果是否可比。两份材料使用各自的发生时间和执行记录，不能套用同一时间窗。
-
-对照中有多项条件同时变化时，分别说明变化；只有耗时不同，不能把差异全部归因于某个筛选器或配置。没有可比样本时，把“相对以前的变化”作为缺口，不影响交付已经确认的本次事实。
+要回答“为什么以前好、这次不好”，确认对象、查询条件、参数、数据范围和结果可比，两边用各自的时间和执行记录。多项条件同时变了就分别说明；只有耗时不同时，不全归到某个筛选器或配置上。没有可比样本时，把“相对以前的变化”记为缺口，照样交付这次的事实。
 
 ## 什么时候结束排查
 
-满足以下任一种情况，就应给出当前结果：
-
-- 已有证据解释了客户的现象和关键触发条件；
-- 缺少一项关键材料，继续查看现有记录不能区分原因；
-- 多个候选仍然可信，需要客户确认具体操作；
-- 后续判断需要研发验证产品行为。
-
-结束前按[诊断结果交付](diagnostic-report.md)核对结论、证据和建议前提。该说明统一维护报告格式、需求反馈入口与研发交接材料；简单事实或链接直接回答，已有证据不足时说明具体缺口。
+满足任一条就给出当前结果：已经解释了现象和关键触发条件；缺一项关键材料，继续看现有记录也分不出原因；多个候选都可信，需要用户确认具体操作；后面的判断要研发验证产品行为。交付前按[诊断结果交付](diagnostic-report.md)核对结论、依据和建议前提。
 
 ## 什么时候交接给研发
 
-当问题涉及未覆盖的产品行为、相互矛盾的执行结果，或现有记录无法区分原因时，按[研发交接要求](diagnostic-report.md#交接研发)整理已经确认的问题、证据和需要验证的判断。
+涉及没覆盖的产品行为、执行结果互相矛盾，或现有记录分不出原因时，按[交接研发](diagnostic-report.md#交接研发)整理已确认的问题、依据和待验证的判断。
 
 ## 其他问题如何开始
 
-非性能报错、结果异常和偶发不可用，目前没有与性能问题同样完整的专项方法。先使用通用步骤整理材料，不强行套用性能解释。
-
-- 报错：保留完整错误、触发操作、发生时间和对应执行，区分每次必现与偶发。
-- 结果异常：用脱敏的最小例子说明预期与实际差异，核对筛选条件、时间范围、权限以及数据是否已更新。
-- 偶发不可用：确认影响对象、持续时间、恢复方式与是否有同时发生的异常记录。
+非性能报错、结果异常、偶发不可用目前没有完整的专项方法，先按通用步骤整理材料，不硬套性能解释。
 
-已有材料能证明的事实先交付；需要进一步验证产品行为时，按上面的交接方法整理，不承诺尚无证据支持的根因。
+- 报错：看入口 span 的 `has_error` 和 `status_message`，HTTP 200 也可能是业务失败。`status_message` 是给用户看的业务提示（功能未开通、权限不足、请求太频繁、表不存在、表正在更新等）时，是业务规则拒绝了请求，不是系统故障；按同一 route、同一提示统计一段时间的次数，看是普遍现象还是只有这次。其他报错保留完整错误、触发操作、时间和对应执行，区分必现和偶发。
+- 前台请求的 trace 上通常没有企业 ID，查不到是哪个企业就直说，请用户提供或让研发核对，不去猜。
+- 结果异常：用脱敏的最小例子说明预期和实际的差别，核对筛选条件、时间范围、权限和数据是否已更新。
+- 偶发不可用：确认影响对象、持续多久、怎么恢复的，同时间有没有别的异常记录。
 
-解析器输出事实，诊断层结合本次证据解释，不把数值排名当作原因。
+能证明的事实先交付；要进一步验证产品行为时按上面的方法交接，不承诺没依据的根因。

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. 能稳定复现就给最短的操作步骤；复现不了就写清发生频率和已知条件。
 
-不要把“请研发看一下”作为唯一交接内容，也不要用未经确认的原因给工单定性。原始大日志与业务数据使用受控附件，不复制到指南中。
+别只写一句“请研发看一下”就交出去，也别用没确认的原因给工单定性。原始的大日志和业务数据用受控附件传。