@fx-data/ai-diagnostics 0.1.20261027064707 → 0.1.20261107142011

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261027064707`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261107142011`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 
@@ -49,14 +49,14 @@
 - 独立 Node 环境下，用其绝对路径运行配套 `npm-cli.js`（Unix：`lib/node_modules/npm/bin/npm-cli.js`；Windows：`node_modules/npm/bin/npm-cli.js`）。通过同一环境的 `npm root -g` 找到包，沿用自定义 prefix，再用同一 Node 调用包内 `bin/core-ai.mjs` 登记。路径含空格时保留引号；Windows PowerShell 调用带引号的可执行路径需要 `&`。不依赖用户项目目录。
 - 全局目录不可写时仅为本次安装指定用户目录的 `--prefix`；现有源找不到本包时仅为本次命令指定 `--registry=https://registry.npmjs.org`，不改全局 npm 配置。
 - 安装失败时同时读取 stderr 中的错误和分项检查。Node 路径失效时修复原运行环境；内容损坏、所有权冲突或权限错误应处理具体错误，不通过第二份安装绕过。需要进一步排错时再运行 `doctor`。
-- 复用旧版时，若 `install` 尚未返回 `checks` 和 `context`，仅此分支补跑稳定入口的 `doctor`、`context` 验证，不因此升级或重新下载。Python 缺失不阻止登记，首次解析材料时再准备。
+- 复用旧版时，若 `install` 尚未返回 `checks` 和 `context`，仅此分支补跑稳定入口的 `doctor`、`context` 验证，不因此升级或重新下载。Python 缺失不阻止登记，首次运行包内 Python 脚本时再准备。
 - WorkBuddy 的 `.workbuddy/skills` 与 `.workbuddy-ai/skills` 由 CLI 按本机线索选择；无法确认时按 CLI 提示处理，不自行扫描客户端缓存或改成两处同时登记。
 
 ## 按需使用
 
 用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
-已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 解析按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
+已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
 ## 更新与回退
 

package/README.md

@@ -38,4 +38,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261027064707/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261107142011/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/bin/core-ai.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Distribution only: diagnostic rules and parsers live in the unchanged content bundle.
+// Distribution only: diagnostic rules and scripts live in the unchanged content bundle.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -53,11 +53,11 @@ function commandHelp(argv) {
   let target;
   if (['help', '--help', '-h'].includes(command)) target = Object.hasOwn(commands, args[0]) ? args[0] : 'help';
   else if (Object.hasOwn(commands, command) && args.some(arg => arg === '--help' || arg === '-h')) target = command;
-  else return null; // metric/python keep their parser or script help arguments.
+  else return null; // python keeps the script's own help arguments.
   const note = '帮助只显示说明，不执行命令。安装和管理成功以命令返回结果为准，简短反馈后停止，无需额外 status 或 doctor。';
   if (target !== 'help') return { ok: true, action: 'help', command: target, ...commands[target], note };
   return { ok: true, action: 'help', name: commandName, display_name: 'FX 数据诊断',
-    commands: [...Object.values(commands).map(value => value.usage), 'metric <parser options>', 'python <script> [args...]'],
+    commands: [...Object.values(commands).map(value => value.usage), 'python <script> [args...]'],
     registry: defaultRegistry, note };
 }
 
@@ -185,11 +185,11 @@ ${powershell} context
 
 每次新诊断只调用一次稳定入口 context：立即取得并固定本次版本，同时后台检查更新，不等待网络。同一调查继续复用首次结果，不重复调用稳定入口 context；需要重新读取固定路径时使用 pinned_cli context，不触发新检查。
 
-context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，按问题只读取所需 Skill 和引用，不预加载全部知识，也不切换用户工作区。包内仓库相对路径以 content_root 为基准，文档链接相对引用文件解析。
+context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，按问题只读取所需知识（先看对应域的 workflow.md），不预加载全部知识，也不切换用户工作区。包内仓库相对路径以 content_root 为基准，文档链接相对引用文件解析。
 
-context、status、session 的 auto_update.notification，以及 python/metric 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
+context、status、session 的 auto_update.notification，以及 python 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
 
-当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。Metric 调用先读取 analyze-engine-metric 的输入表：纯文本用 metric --metric；SigNoZ JSON 用 metric --metric-log-json <文件> --task-name <选定 task>。通过 session 获取临时目录，日志和产物不写入安装内容。只有解析脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
+当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
 
 用户要求更新时执行稳定入口 update，默认使用 latest；要求回退到上次更新前时执行 rollback，也可用 --version 指定版本。已保留版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中调查继续使用原 pinned_cli。更新后按客户端要求刷新技能或新开聊天；安装副本不做 Git 更新。
 
@@ -266,7 +266,7 @@ function skillChecks(targets, home, installId) {
 function contextFor(root, home, pkg, manifest) {
   const content = path.join(root, 'content');
   return { version: pkg.version, source_commit: manifest.source_commit, content_root: content,
-    agent_rules: path.join(content, 'AGENTS.md'), skills_root: path.join(content, '.agents', 'skills'),
+    agent_rules: path.join(content, 'AGENTS.md'),
     pinned_cli: path.join(root, 'bin', 'core-ai.mjs'), node: process.execPath,
     launcher: launchers(home).executable, launcher_script: launchers(home).script };
 }
@@ -433,8 +433,9 @@ function install(home, options, { sourceRoot = packageRoot, action = 'install' }
     if (checks.skills.status !== 'ok') throw new Error(checks.skills.entries.filter(entry => entry.status === 'error').map(entry => entry.error).join('; '));
     const context = contextFor(release, home, pkg, manifest);
     fs.accessSync(context.agent_rules, fs.constants.R_OK);
-    if (!fs.statSync(context.skills_root).isDirectory()) throw new Error('Diagnostic skills directory is unavailable');
-    fs.accessSync(context.skills_root, fs.constants.R_OK);
+    const knowledgeRoot = path.join(context.content_root, 'knowledge');
+    if (!fs.statSync(knowledgeRoot).isDirectory()) throw new Error('Diagnostic knowledge directory is unavailable');
+    fs.accessSync(knowledgeRoot, fs.constants.R_OK);
     if (!registrationOnly) atomicWrite(path.join(home, homeMarker), JSON.stringify(ownership));
     const releaseProtocols = { ...prior?.state?.release_protocols };
     if (prior?.state?.lifecycle_protocol === lifecycleProtocol) releaseProtocols[prior.state.version] = lifecycleProtocol;
@@ -774,7 +775,7 @@ function python() {
     const probe = spawnSync(args[0], [...args.slice(1), '-I', '-B', '-c', 'import sys; print(sys.executable); sys.exit(0 if sys.version_info >= (3,9) else 1)'], { encoding: 'utf8' });
     if (probe.status === 0) return { executable: probe.stdout.trim(), available: true };
   }
-  return { available: false, requirement: 'Python 3.9+ is required for offline Metric parsing.' };
+  return { available: false, requirement: 'Python 3.9+ is required to run bundled scripts.' };
 }
 
 function uninstall(home) {
@@ -822,7 +823,7 @@ function doctor(home) {
   checks.python = { status: runtime.available ? 'ok' : 'unavailable', ...runtime };
   const errors = [integrityError, ...(checks.skills.entries || []).filter(entry => entry.status === 'error').map(entry => entry.error)].filter(Boolean);
   const result = { ok: errors.length === 0, version: installed?.state?.version ?? null, integrity: checks.integrity.status,
-    python: runtime, capabilities: { metric: checks.integrity.status === 'ok' && runtime.available }, skills: installed?.state?.skills || [], checks };
+    python: runtime, skills: installed?.state?.skills || [], checks };
   if (result.ok) emit(result);
   else { process.stderr.write(`${JSON.stringify({ ...result, error: errors.join('; ') })}\n`); process.exitCode = 1; }
 }
@@ -840,7 +841,7 @@ async function main() {
   try { current = ownedState(home, false); }
   catch (error) { if (command === 'doctor') return doctor(home); throw error; }
   const activeRoot = current?.state ? path.join(home, 'releases', current.state.version) : null;
-  const pinned = isInstalledBundle(packageRoot, home) && ['context', 'python', 'metric'].includes(command);
+  const pinned = isInstalledBundle(packageRoot, home) && ['context', 'python'].includes(command);
   const migrationRequired = Boolean(current?.state && current.state.lifecycle_protocol !== lifecycleProtocol);
   if (command === 'doctor') {
     if (!activeRoot || packageRoot === activeRoot || migrationRequired) return doctor(home);
@@ -848,7 +849,7 @@ async function main() {
     // diagnostic content is damaged. Fall back here only if the CLI is unsafe.
     try { bundleMetadata(activeRoot); } catch { return doctor(home); }
   }
-  if (migrationRequired && (command === 'install' || (!pinned && ['context', 'python', 'metric', 'version', '--version'].includes(command)))) {
+  if (migrationRequired && (command === 'install' || (!pinned && ['context', 'python', 'version', '--version'].includes(command)))) {
     throw new Error('Existing installation requires migration: run npm install -g @fx-data/ai-diagnostics, then use the new global fx-data-diagnostics update command');
   }
   // npm installation is a bootstrap. Re-running it must not switch an existing
@@ -873,7 +874,7 @@ async function main() {
   if (command === 'update') return update(home, options);
   if (command === 'rollback') return update(home, options, 'rollback');
   if (command === 'uninstall') return uninstall(home);
-  const { pkg, manifest, content } = verifyBundle(packageRoot, { allowMacMetadata: isInstalledBundle(packageRoot, home) });
+  const { pkg, manifest } = verifyBundle(packageRoot, { allowMacMetadata: isInstalledBundle(packageRoot, home) });
   if (command === '--version' || command === 'version') return emit({ version: pkg.version, package: pkg.name });
   if (command === 'status') {
     const auto = autoUpdateDetails(home);
@@ -893,14 +894,13 @@ async function main() {
     const auto = autoUpdateDetails(home);
     return emit({ directory: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')), ...(auto ? { auto_update: auto } : {}) });
   }
-  if (command === 'metric' || command === 'python') {
+  if (command === 'python') {
     const runtime = python();
     if (!runtime.available) throw new Error(runtime.requirement);
-    const args = command === 'metric' ? [path.join(content, '.agents/skills/analyze-engine-metric/scripts/analyze_engine_metric.py'), ...rest] : rest;
-    if (!args.length) throw new Error('A script or Python option is required');
+    if (!rest.length) throw new Error('A script or Python option is required');
     const auto = autoUpdateDetails(home);
     if (auto?.notification) process.stderr.write(`${JSON.stringify({ fx_data_diagnostics: { auto_update: auto } })}\n`);
-    const result = spawnSync(runtime.executable, ['-I', '-B', ...args], { stdio: 'inherit' });
+    const result = spawnSync(runtime.executable, ['-I', '-B', ...rest], { stdio: 'inherit' });
     if (result.error) throw result.error;
     process.exitCode = result.status ?? 1;
     return;

package/content/AGENTS.md

@@ -1,84 +1,62 @@
 # core-ai Agent 执行契约
 
-你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。结合业务操作、日志和项目知识，说明观察到的异常、可能原因和排查方向；需要确认具体对象或执行时，再补充对应证据。
+你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。照着用户说的操作、手上的日志和 trace，结合本仓库的知识回答问题：看到了什么异常、可能是什么原因、接下来往哪里查。
 
 ## 使用前更新代码
 
-只有本项目根目录存在 `.git` 文件或目录时，才按源码仓库方式更新：每次新对话首次使用时，在该根目录运行 `git pull --ff-only`；同一对话不重复更新。保留本地改动，不切换分支。无法安全更新或联网失败时，简短说明并继续原任务。
-
-通过 CLI 安装的目录没有 `.git`，不得在它或使用者的其他项目执行 Git 更新。全局 Skill 通过 `context` 返回内容目录时，遵循 [npm 安装副本规则](#安装副本的助手规则)。首次使用时读取对应说明，本轮已读则复用。新诊断由 CLI 后台检查更新，当前调查始终使用首次返回的版本。
+- 源码仓库（根目录有 `.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` 为基准，文档链接相对引用文件解析。
-- 每次新诊断只调用一次稳定入口的 `context`；CLI 在后台检查更新，不等待网络或下载，同一调查继续复用已返回的版本。
-- 更新通知由 CLI 返回：`context`、`status`、`session` 的 JSON 中查看可选的 `auto_update.notification`；`python`、`metric` 的 stderr 可带独立 JSON，其中为 `fx_data_diagnostics.auto_update.notification`，stdout 仍是原脚本结果。通知包含 `id`、`status`、`message`，按 `message` 简短告知，按 `id` 避免重复提示；当前调查保持固定版本，新版供下次新诊断使用。没有通知不提示，不为获取更新结果额外轮询；本轮没有后续 CLI 调用时，下次使用再补报。
-- 用 `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,17 +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`）。
 
-npm 安装副本在每次新诊断时后台检查更新，当前排查不等待；更新成功后下次新诊断生效，失败继续使用旧版，见[版本管理](docs/npm-cli.md#34-版本管理)。
-
-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 文件）时不用配置，直接交给助手。
 
 ## 如何提问
 
@@ -42,7 +40,7 @@ npm 安装副本在每次新诊断时后台检查更新，当前排查不等待
 - 查企业更新没给时间时，默认看最近 24 小时。
 - 给了 dagId 就能直接查更新链路，不需要再提供时间。
 - 说“之前正常”“以前没超限”，助手会自动找之前的正常记录做对比，不需要先提供成功记录。
-- 仪表板内组件异常时，助手会先查找对应组件的单独计算记录；找不到也会继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照)。
+- 仪表板内组件异常时，助手会先查找对应组件的单独预览记录；找不到也会继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](knowledge/dashboard/workflow.md#组件取数先做对照)。
 - 缺少关键信息时，助手一次说明需要补充什么、用来判断什么。
 
 继续同一问题时，助手沿用已确认的范围和查询结果。简单追问（数值、链接）直接回答，不重新排查。
@@ -53,47 +51,16 @@ npm 安装副本在每次新诊断时后台检查更新，当前排查不等待
 
 - 当前结论：哪个对象的哪次操作出现问题，已定位到什么环节或条件。
 - 关键依据：对应执行记录、错误、统计或对照结果，以及它们如何支持判断。
-- 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的证据。
-- 需求反馈（有证据支持时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](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，查不到是哪个企业就直说，请用户提供或让研发核对，不去猜。
+- 结果异常：用脱敏的最小例子说明预期和实际的差别，核对筛选条件、时间范围、权限和数据是否已更新。
+- 偶发不可用：确认影响对象、持续多久、怎么恢复的，同时间有没有别的异常记录。
 
-解析器输出事实，诊断层结合本次证据解释，不把数值排名当作原因。
+能证明的事实先交付；要进一步验证产品行为时按上面的方法交接，不承诺没依据的根因。