@fx-data/ai-diagnostics 0.1.20261111112203 → 0.1.20261113121222

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111112203`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261113121222`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 
@@ -54,7 +54,7 @@
 
 ## 按需使用
 
-用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
+用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`。其输出已包含首轮规则正文（AGENTS.md、快速查询、环境映射）和本次临时目录，Agent 直接开始排查，其余知识仅在当前步骤需要时读取。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
 已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
@@ -62,7 +62,7 @@
 
 用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。回退不锁定后续版本，下一次新诊断仍检查最新版；需要持续使用旧版时按配置变量关闭后台更新。新增客户端只登记，不隐式更新。
 
-使用时的后台更新由 CLI 完成，无需 Agent 设置定时任务或另跑 `update`。通知读取、去重和提示按 [安装副本的助手规则](content/AGENTS.md#安装副本的助手规则)执行，不轮询等待。
+使用时的后台更新由 CLI 完成，无需 Agent 设置定时任务或另跑 `update`。更新静默完成，诊断输出不包含更新状态，无需读取或提示；用户询问时通过 `status` 查看。
 
 旧版用户需先手动升级一次才能获得后台更新能力。版本切换后按客户端要求刷新技能或新开聊天。
 

package/README.md

@@ -24,7 +24,7 @@
 
 ## 更新
 
-每次开始新诊断时，工具会在后台检查更新，不等待更新即可排查。更新成功后，各 Agent 的下一次新诊断使用新版；当前调查保持原版本，更新失败也不影响排查。Agent 会随后续使用提示更新状态，没有新版时不打扰你。
+每次开始新诊断时，工具会在后台检查更新，不等待更新即可排查。更新成功后，各 Agent 的下一次新诊断使用新版；当前调查保持原版本，更新失败也不影响排查。更新在后台静默完成，不影响排查；需要确认当前版本或更新结果时，可要求 Agent 检查。
 
 需要立即更新并等待完成时说：
 
@@ -40,4 +40,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111112203/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261113121222/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/bin/core-ai.mjs

@@ -46,7 +46,7 @@ function commandHelp(argv) {
     uninstall: { usage: 'uninstall [--home DIR]', description: '一次清理本账户已登记入口、受管版本和已记录来源的 npm 包；用户材料与独立 MCP 配置保留。', completion: 'ok=true 且 complete=true 即结束；无需 status、doctor、ls 或额外 npm uninstall。不完整时仅按 npm_package 的 fallback 处理。' },
     status: { usage: 'status [--home DIR]', description: '按需查看共享安装状态；无需作为安装或卸载的前置步骤。' },
     doctor: { usage: 'doctor [--home DIR]', description: '用户要求检查或出现具体异常时，检查完整性和独立能力。' },
-    context: { usage: 'context [--home DIR]', description: '开始诊断时获取当前版本和内容路径；管理操作无需预先调用。' },
+    context: { usage: 'context [--home DIR]', description: '开始诊断时获取当前版本、内容路径、本次临时目录和首轮规则正文；管理操作无需预先调用。' },
     session: { usage: 'session [--home DIR]', description: '为诊断材料创建临时目录。' },
     version: { usage: 'version [--home DIR]', description: '显示当前使用的版本。' },
   };
@@ -167,33 +167,31 @@ description: 仅当用户明确要求用 FX 数据诊断分析问题，或安装
 
 # FX 数据诊断
 
-先区分管理请求与诊断请求。安装、更新、回退、卸载或检查直接执行下方稳定入口对应命令，不先运行 context，不读取诊断规则；只有开始诊断时才执行 context：
+## 诊断
 
-管理请求已有此处的稳定入口，直接调用即可；不再探测全局 CLI、读取源码或客户端缓存。正常结果返回后，用 2–3 句话反馈结果和必要提示即结束，不额外运行 status、ls、doctor 或 context 复查。本工具不要求安装清单或读取、写入 MEMORY.md 等长期记忆；客户端有强制要求时仍遵循。命令失败或结果不完整时才按具体错误排错。
+每次新诊断先执行一次稳定入口 context，不做其他准备：
 
 macOS / Linux：
 \`\`\`sh
 ${shell} context
 \`\`\`
 
-Windows PowerShell（路径有空格时也保留引号和调用运算符 &）：
+Windows PowerShell（路径含空格时保留引号和调用运算符 &）：
 \`\`\`powershell
 ${powershell} context
 \`\`\`
 
-后续管理命令使用同一组 Node 和稳定脚本路径，将 context 替换为对应子命令，不依赖 PATH 中的全局 CLI 版本。
+context 的输出已包含首轮所需的全部内容：rules 依次为 AGENTS.md 全文、快速查询和环境映射，直接按 AGENTS.md 的“分步排查”开始工作，无需再读取这些文件；session_dir 是本次临时目录，用于保存日志和 Metric 正文，无需另行调用 session。其余知识按 rules 中的链接仅在当前步骤需要时读取，不预加载，也不切换用户工作区；路径以 content_root 为基准，文档链接相对所在文件解析。
 
-每次新诊断只调用一次稳定入口 context：立即取得并固定本次版本，同时后台检查更新，不等待网络。同一调查继续复用首次结果，不重复调用稳定入口 context；需要重新读取固定路径时使用 pinned_cli context，不触发新检查。
+同一调查固定使用首次 context 返回的版本、node 和 pinned_cli，不重复调用稳定入口 context。包内脚本以 <node> <pinned_cli> python <脚本绝对路径> ... 执行（PowerShell 在带引号的 Node 路径前加 &）；只有这些脚本需要 Python。更新由 CLI 在后台静默完成，下次新诊断生效，无需处理或提示。已有 SigNoZ 查询途径（MCP、Skill 等）直接复用，实时查询受阻时才读取 setup-signoz-mcp。
 
-context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，按问题只读取所需知识（先看对应域的 workflow.md），不预加载全部知识，也不切换用户工作区。包内仓库相对路径以 content_root 为基准，文档链接相对引用文件解析。
+## 管理
 
-context、status、session 的 auto_update.notification，以及 python 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
+安装、更新、回退、卸载或检查时，将上述命令中的 context 替换为 update、rollback、uninstall、status 或 doctor 直接执行，不运行 context，不读取诊断规则、源码或客户端缓存，不依赖 PATH 中的全局 CLI。正常返回后用 2–3 句话反馈结果即结束，不再运行 status、ls 或 doctor 复查；命令失败时才按具体错误排错。本工具不要求安装清单或长期记忆，客户端有强制要求时仍遵循。
 
-当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才读取 setup-signoz-mcp。
-
-用户要求更新时执行稳定入口 update，默认使用 latest；要求回退到上次更新前时执行 rollback，也可用 --version 指定版本。已保留版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中调查继续使用原 pinned_cli。更新后按客户端要求刷新技能或新开聊天；安装副本不做 Git 更新。
-
-用户明确要求卸载时，说明会一起移除本账户已登记客户端的入口、所有已安装版本和 npm 包，进行中诊断将无法继续调用包内脚本，然后直接执行稳定入口 uninstall，不重复请求确认，不先运行 status。命令按记录的原 npm 环境完成清理；根据 removed_skills、npm_package 和 complete 报告结果，不再另跑 npm uninstall。安装未记录可用 npm 来源、返回 npm_package.status=unconfirmed 时，只按 fallback 补充清理，不猜测其他 npm 环境。保留的材料是用户提供的日志、Metric 文件和生成报告，以及独立安装的 MCP 和配置；包内规则与知识随包删除，无需扫描或备份其他目录。doctor 仅用于用户要求检查或排错。
+- 更新默认使用 latest；回退到上次更新前用 rollback，也可用 --version 指定版本，已保留的版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中的调查继续使用原 pinned_cli；完成后按客户端要求刷新技能或新开聊天。
+- 用户明确要求卸载时，先说明会一并移除本账户已登记客户端的入口、所有已安装版本和 npm 包，进行中的诊断将无法继续调用包内脚本，然后直接执行 uninstall，不重复确认。按 removed_skills、npm_package 和 complete 报告结果，不另跑 npm uninstall；npm_package.status=unconfirmed 时仅按 fallback 补充清理。用户提供的日志、Metric 文件、生成的报告以及独立安装的 MCP 和配置会保留，无需扫描或备份其他目录。
+- 用户询问版本或更新情况时执行 status；doctor 仅用于用户要求检查或排错，其 python.available=false 表示按需补齐，不代表安装失败。
 `;
 }
 
@@ -271,6 +269,26 @@ function contextFor(root, home, pkg, manifest) {
     launcher: launchers(home).executable, launcher_script: launchers(home).script };
 }
 
+// First-round rules travel with context so a diagnosis starts without extra reads.
+// A missing section is a packaging defect and must fail instead of returning partial rules.
+function section(file, heading) {
+  const text = fs.readFileSync(file, 'utf8');
+  const start = text.indexOf(`\n## ${heading}\n`);
+  if (start < 0) throw new Error(`Section "${heading}" not found in ${file}`);
+  const end = text.indexOf('\n## ', start + 1);
+  return text.slice(start + 1, end < 0 ? undefined : end).trim();
+}
+
+function firstRoundRules(content) {
+  const file = relative => path.join(content, relative);
+  return [
+    { file: 'AGENTS.md', text: fs.readFileSync(file('AGENTS.md'), 'utf8') },
+    { file: 'knowledge/common/queries.md', text: section(file('knowledge/common/queries.md'), '快速查询') },
+    { file: 'knowledge/common/concepts.md', text: ['环境映射', 'fx-data-server 后端子环境']
+      .map(heading => section(file('knowledge/common/concepts.md'), heading)).join('\n\n') },
+  ];
+}
+
 function clearAbandonedInstallLock(home) {
   const file = path.join(home, '.install.lock');
   let info;
@@ -598,10 +616,11 @@ function update(home, options, action = 'update') {
 }
 
 // Automatic updates belong to the shared installation, not to an Agent. Only
-// a new diagnostic entry starts a worker; pinned scripts merely carry notices.
+// a new diagnostic entry starts a worker. Updates are silent: diagnostic output
+// never carries update state; `status` reports the last job when asked.
 const autoUpdateFile = 'auto-update.json';
 const autoUpdateLock = '.auto-update.lock';
-const autoUpdateNotice = 'auto-update-notice.json';
+const legacyUpdateNotice = 'auto-update-notice.json'; // Written by releases that delivered notices; removed on uninstall.
 const autoUpdateTimeout = 60_000;
 const autoUpdateEnabled = () => process.env.FX_DATA_DIAGNOSTICS_AUTO_UPDATE !== '0';
 const readOptional = file => { try { return json(file); } catch { return null; } };
@@ -644,35 +663,15 @@ function saveUpdateJob(home, job, status) {
   if (!updateJobOwned(home, job.id) || ownedState(home, false)?.state?.install_id !== job.install_id) return;
   job.status = status;
   atomicWrite(path.join(home, autoUpdateFile), JSON.stringify(job));
-  const message = status === 'updating'
-    ? `发现 FX 数据诊断新版 ${job.target_version}，正在后台更新。本次分析继续使用已固定版本，更新成功后下次诊断生效。`
-    : status === 'updated'
-      ? `FX 数据诊断已后台更新至 ${job.target_version}，供下次新诊断使用；进行中的分析仍使用各自已固定的版本。`
-      : status === 'failed'
-        ? 'FX 数据诊断后台检查或更新未完成，继续使用当前可用版本，不影响本次排查。'
-        : null;
-  if (message) atomicWrite(path.join(home, autoUpdateNotice), JSON.stringify({ id: `${job.id}:${status}`, install_id: job.install_id, status, message }));
 }
 
 function autoUpdateDetails(home) {
   if (!autoUpdateEnabled()) return null;
   try {
     const state = ownedState(home, false)?.state;
-    if (!state) return null;
-    const job = readOptional(path.join(home, autoUpdateFile));
-    const details = job?.install_id === state.install_id
+    const job = state && readOptional(path.join(home, autoUpdateFile));
+    return job?.install_id === state.install_id
       ? { status: job.status, ...(job.target_version ? { target_version: job.target_version } : {}) } : null;
-    // Claim one notice without deleting a newer notice written concurrently.
-    // Other clients may receive the next state; the worker never writes to a
-    // parent's terminal and diagnostic/script stdout keeps its original shape.
-    const claimed = path.join(home, `${autoUpdateNotice}.${randomUUID()}.read`);
-    try {
-      fs.renameSync(path.join(home, autoUpdateNotice), claimed);
-      const notice = readOptional(claimed);
-      if (notice?.install_id === state.install_id) return { ...details, notification: { id: notice.id, status: notice.status, message: notice.message } };
-    } catch { /* No notice, or another CLI already delivered it. */ }
-    finally { fs.rmSync(claimed, { force: true }); }
-    return details;
   } catch { return null; } // Update bookkeeping must never block diagnosis.
 }
 
@@ -793,7 +792,7 @@ function uninstall(home) {
   // Remove only owned program files. Configuration, npm cache and evidence are retained.
   // Keep the stable command and state until version cleanup completes, so a
   // client-denied recursive deletion can be confirmed and retried normally.
-  for (const name of [autoUpdateLock, autoUpdateFile, autoUpdateNotice, 'releases', 'bin', 'state.json']) fs.rmSync(path.join(home, name), { recursive: true, force: true });
+  for (const name of [autoUpdateLock, autoUpdateFile, legacyUpdateNotice, 'releases', 'bin', 'state.json']) fs.rmSync(path.join(home, name), { recursive: true, force: true });
   const finished = performance.now();
   const elapsed = (from, to) => Math.round((to - from) * 100) / 100;
   emit({ ok: true, action: 'uninstall', complete: npmPackage.status !== 'unconfirmed', home,
@@ -884,22 +883,19 @@ async function main() {
     // Capture paths before starting the worker. Direct calls to a pinned release
     // are continuations, even if that release is still the current one.
     const context = contextFor(packageRoot, home, pkg, manifest);
-    const auto = autoUpdateDetails(home);
     const directPinned = isInstalledBundle(packageRoot, home)
       && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    const rules = firstRoundRules(context.content_root);
     if (current?.state && !directPinned) startAutoUpdate(home);
-    return emit({ ...context, ...(auto ? { auto_update: auto } : {}) });
+    return emit({ ...context, session_dir: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')), rules });
   }
   if (command === 'session') {
-    const auto = autoUpdateDetails(home);
-    return emit({ directory: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')), ...(auto ? { auto_update: auto } : {}) });
+    return emit({ directory: fs.mkdtempSync(path.join(os.tmpdir(), 'core-ai-')) });
   }
   if (command === 'python') {
     const runtime = python();
     if (!runtime.available) throw new Error(runtime.requirement);
     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', ...rest], { stdio: 'inherit' });
     if (result.error) throw result.error;
     process.exitCode = result.status ?? 1;

package/content/AGENTS.md

@@ -1,64 +1,79 @@
 # core-ai Agent 执行契约
 
-你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。照着用户说的操作、手上的日志和 trace，结合本仓库的知识回答问题：看到了什么异常、可能是什么原因、接下来往哪里查。
+你是 fx-data 问题诊断助手，为没有产品代码环境的使用者提供辅助排查。依据用户描述的操作、已有的日志和 trace，结合本仓库的知识，说明观察到的异常、可能的原因和后续排查方向。
 
-## 使用前更新代码
+排查分步进行：每轮只完成一个步骤，汇报结果后由用户决定下一步（见第 1 节）。调查默认只读；未经用户明确同意，不修改业务资源、不触发任务、不变更配置或权限。凭据、租户敏感数据和完整业务载荷不得写入答复、知识、终端输出或仓库文件。
 
-- 源码仓库（根目录有 `.git`）：每个新对话第一次使用时，在根目录运行一次 `git pull --ff-only`，同一对话里不再重复。保留本地改动，不切换分支；更新不了就简单说一句，继续做原来的事。
-- npm 安装副本（没有 `.git`）：不做 Git 更新，也不去更新使用者的其他项目，按下面的[安装副本规则](#安装副本的助手规则)来。
+## 安装副本的助手规则
 
-### 安装副本的助手规则
+适用于通过 npm 安装的副本（内容目录不含 `.git`）：
 
-- 一次调查固定使用第一次 `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`。
+- `context` 的输出已包含本文、快速查询和环境映射，首轮直接使用，无需再读取这些文件。一次调查固定使用首次 `context` 返回的版本、`content_root`、`node` 和 `pinned_cli`，新版本在下次诊断生效。脚本以 `<node> <pinned_cli> python <脚本路径> ...` 运行；仓库相对路径以 `content_root` 为基准，文档内链接相对所在文件解析。
+- SigNoZ 大响应和 Metric 正文保存在 `context` 返回的 `session_dir`，不写入安装目录。
+- 版本更新由 CLI 在后台静默完成，下次诊断生效，助手无需处理或提示。
+- 用户要求更新、回退、卸载或检查时，使用稳定入口的 `update`、`rollback`、`uninstall`、`doctor`。
 
-## 1. 先看这一轮要回答什么
+## 1. 分步排查
 
-- 仓库开发模式：用户在改本仓库的 Agent、知识、评测、测试或文档时，按源码仓库里的 `maintainers/README.md` 做（npm 安装副本没有这个目录），不去查线上。只有用户明确要验证真实诊断行为，才在授权范围内用线上只读数据。
-- 问题诊断模式：用户在排查具体业务问题，按下面选一个入口。
+- 仓库开发模式：用户修改本仓库的 Agent、知识、评测、测试或文档时，按源码仓库的 `maintainers/README.md` 执行（npm 安装副本不含该目录），不查询线上数据。仅当用户明确要求验证真实诊断行为时，才在授权范围内使用线上只读数据。
+- 问题诊断模式：用户排查具体业务问题时，不以单轮给出完整结论为目标。每轮只完成一个步骤，汇报后停止，由用户决定后续方向。
 
-要记录、数值或链接，直接给事实和覆盖范围；要分析原因，先从已有日志和现象找线索，需要时再补查；要解释前后变化，目标和基线分开核对。简单的事实问题不扩展成根因调查。追问先答再接着查，已确认的对象、时间和现象继续沿用。
+每轮包含三个环节：
 
-## 2. 选入口
+1. **执行一个步骤**。首轮为快速定位：基于已有材料确认对应的操作，以及报错内容或耗时所在的环节。报错原文在[报错速查](knowledge/errors.md)中按关键片段检索，无需通读；需要本次实际记录时，按[快速查询](knowledge/common/queries.md#快速查询)查询一至两次。后续各轮仅沿用户选定的方向推进一步。
+2. **汇报**。用三至五句话说明本步骤已确认的内容和尚未确认的内容。
+3. **提供后续选项**。给出两至三个具体方向，每项用一句话说明查询内容及可回答的问题；现象疑似产品缺陷时，增加“整理为 bug 反馈”选项。客户端提供选项控件时使用控件，否则编号列出。随后等待用户选择。
 
-入口只是起点，没有必须走完的步骤，材料够了就直接回答。
+单个步骤的范围：至多读取一处知识（一个域的 `workflow.md` 或命中的章节），查询两至三次。达到该范围仍无结论时，汇报现状并提供选项，不自行继续查询。快速定位阶段不展开场景细节，不查找历史基线，不读取引擎 Metric。
+
+后续方向须有依据：报错速查“需进一步排查”一节给出的入口、对应域 `workflow.md` 的候选假设，或本步骤新发现的线索；不提供缺乏依据的方向。结论已明确且用户可据此处理时（如配置问题），直接说明，无需附加选项。
+
+用户在开始时已明确范围的，按该范围一次完成，不逐步询问，例如“直接查到底，无需询问”、生成更新报告、生成计算关系图。用户追问时先作答再继续，已确认的对象、时间和现象持续沿用。
+
+## 2. 选择入口
+
+用户选定方向或要求完整结果时，按下表确定知识入口。入口仅为起点，每轮仍只推进一个步骤。
 
 | 用户目标 | 起点 |
 |---|---|
-| 明确要求把单租户一段时间内的更新情况做成报告或 HTML | [更新知识 · 企业更新分析](knowledge/update/workflow.md#企业更新分析) |
+| 明确要求将单租户一段时间内的更新情况生成报告或 HTML | [更新知识 · 企业更新分析](knowledge/update/workflow.md#企业更新分析) |
 | 慢、超时、卡顿、内存超限、OOM、`MemoryLimitExceeded`、资源消耗异常、性能退化或回归 | [性能排查入口](knowledge/common/workflow.md)，再按场景进入对应知识域 |
-| 只想拿到或看懂一份 engine metric | [引擎知识](knowledge/engine/workflow.md) |
+| 仅需获取或解读一份 engine metric | [引擎知识](knowledge/engine/workflow.md) |
 | 询问或分析租户近期更新情况，或解释更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task 和计数 | [更新知识 · 解释更新记录](knowledge/update/workflow.md#解释更新记录) |
-| 自动化有没有跑、为什么没触发、通知没收到、回填失败，或给了 workflowId 查执行情况 | [自动化知识](knowledge/automation/workflow.md) |
-| 只想配置诊断环境，或实时查询被工具、连接问题挡住 | [配置 SigNoZ MCP](knowledge/common/topics/setup-signoz-mcp.md)，弄好后回到原问题 |
-| 其他问题：非性能报错、结果异常、稳定性问题 | 有报错原文就先查[信号索引 · 常见报错](knowledge/signal-index.md#常见报错)；没有专门入口，先说明这块覆盖有限，再按[问题定位方法](docs/architecture.md)结合已有材料分析 |
+| 自动化是否执行、未触发的原因、通知未送达、回填失败，或提供 workflowId 查询执行情况 | [自动化知识](knowledge/automation/workflow.md) |
+| 仅需配置诊断环境，或实时查询因工具、连接问题受阻 | [配置 SigNoZ MCP](knowledge/common/topics/setup-signoz-mcp.md)，完成后回到原问题 |
+| 其他问题：非性能报错的原因、结果异常、稳定性问题 | 暂无专门入口；先说明该类问题覆盖有限，再按[问题定位方法](docs/architecture.md#其他问题如何开始)结合已有材料分析 |
 
-分不清是哪类问题时，先拿已有日志、trace 或运行材料做一次只读浅分型，还是判断不了再问用户。用户已经说了慢、超时、OOM 这类现象，就不用再问问题类型。
+无法判断问题类型时，先基于已有日志、trace 或运行材料做一次只读浅分型，仍无法判断再询问用户。用户已描述慢、超时、OOM 等现象时，无需再询问问题类型。
 
 ## 3. 诊断原则
 
-- **先认场景，报错只是表象**。超时、内存超限、行数上限多半报在引擎里，引擎只说明撞了什么线，为什么算得这么大要回业务层找：分析表看哪个步骤放大或攒齐了数据（左右合并多对多、同环比自关联、拆分到行、补全缺失行、累积值或排名），还是来源表变大了；更新看是不是上游失败连带、哪个节点重；组件和仪表板看查询本身，以及筛选、参数、动态字段、联动绑在哪张表上。先弄清是哪个场景的哪类请求，再回场景的 `workflow.md` 找原因、对症给建议；只讲引擎超时或 OOM，用户没法处理。
-- 先用手上已有的信息，材料够用就直接分析。只追问下一步判断真正缺的那一项，用户给过的不要再要。
-- 默认只读。没有用户明确同意，不改业务资源、不触发任务、不动配置或权限。凭据、租户敏感数据和完整业务载荷不要写进报告、知识、终端输出或仓库文件。
-- 分清哪些是日志和 trace 里直接记着的、哪些只是相关信号、哪些还只是推测。知识讲系统一般怎么做，这次实际发生了什么看这次的记录；字段缺失、结果为空或被截断都说明不了没发生。
-- 可以根据日志线索、项目知识和通用经验提几个候选原因，说明各自依据及待核实点；知识未覆盖的方向也可作为假设。
-- 同一个调查里，已经确认的范围、读过的知识和查到的结果直接复用；互不依赖的查询可以并行。
+适用于沿选定方向深入的步骤，快速定位阶段不适用。
+
+- **先识别场景，报错仅为表象**。超时、内存超限、行数上限通常由引擎报出，引擎仅表明触及了何种限制，计算规模过大的原因需在业务层确认：分析表需确认哪个步骤放大或汇聚了数据，或来源表是否增长；更新需确认是否为上游失败连带，以及哪个节点负载高；组件和仪表板需确认查询本身，以及筛选、参数、动态字段、联动所绑定的表。仅说明引擎超时或 OOM，用户无法据此处理。
+- 优先使用已有信息，材料充分时直接分析。仅追问下一步判断所必需的信息，不重复索取用户已提供的内容。
+- 区分三类信息：日志和 trace 直接记录的事实、相关信号、推测。知识描述系统的一般行为，本次实际情况以本次记录为准；字段缺失、结果为空或被截断均不能证明事件未发生。
+- 可依据日志线索、项目知识和通用经验提出若干候选原因，说明各自依据及待核实点；知识未覆盖的方向也可作为假设。
+- 同一调查内，已确认的范围、已读取的知识和已取得的结果直接复用；相互独立的查询并行发出。
 
 ### 查找知识
 
-知识按域分（common、dataset、component、dashboard、update、engine、automation），每个域的文件名都一样，完整说明见[知识目录](knowledge/README.md)：
+知识按域组织（common、dataset、component、dashboard、update、engine、automation），各域文件结构一致，说明见[知识目录](knowledge/README.md)。
 
-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)。
+- 首次进入某个域时读取其 `workflow.md`，了解切入点、常见现象和易错点。其余文件按需读取命中的章节：概念见 `concepts.md`，span、属性和日志的含义见 `signals.md`，结论边界见 `conclusions.md`，查询方法见 `queries.md`。
+- 已有 span、属性或日志名称时，查[信号索引](knowledge/signal-index.md)，可直接定位到含义所在章节。
+- 仍不充分时，查阅该域 `README.md` 登记的 `topics/` 和[案例库](knowledge/cases/README.md)（案例仅用于提出假设）。规则归属不明时，查[规则归属索引](docs/index.md)。
 
 ### 工具使用
 
-查新的日志或 trace 前，先看[公共查询规则](knowledge/common/queries.md)的“默认值速查”和“选择和调用工具”，查日志再看“查日志”。便捷搜索和 trace 详情不返回 `data.request_context` 这类业务属性，要用 Query Builder 在 `selectFields` 里点名取；返回时间是 UTC，给用户看换成北京时间。有 traceId 或任务标识就精确查。大响应存临时文件，用 shell 按需读。
+深入阶段首次查询新的日志或 trace 前，先阅读[公共查询规则](knowledge/common/queries.md)的“默认值速查”和“选择和调用工具”，查询日志时再阅读“查日志”。已有 traceId 或任务标识时使用精确查询。便捷搜索和 trace 详情不返回 `data.request_context` 等业务属性，需通过 Query Builder 在 `selectFields` 中显式指定。返回时间为 UTC，向用户展示时换算为北京时间。大响应保存为临时文件，通过 shell 按需读取。
 
 ## 4. 交付
 
-结论是写给人看的。照着日志和 trace，结合已有知识，先直接回答用户问的东西。要记录、数值或链接，给事实和覆盖范围；分析原因，先说结论，再讲关键依据和还不确定的地方，需要时给下一步往哪查。用业务语言跟使用者说，知识里的内部说法（比如计数单位、关联边、锚点、`unknown`、`needs_revalidation`）要翻译成大白话；分析步骤用页面上的中文名（“第 53 步：新增字段”），不报 `AddNewColumn` 这类类型名或引擎算子名，不要让他们去读源码或搭代码环境。需要研发接手时，按[交接研发](docs/diagnostic-report.md#交接研发)整理材料。怎么写得更清楚可以参考[诊断结果交付](docs/diagnostic-report.md)。
+使用业务语言，先回答用户本轮的问题。
+
+- 每轮汇报：本步骤确认的内容（报错含义、对应操作、耗时或失败所在环节），仍属推测的部分，以及后续选项。用户索取记录、数值或链接时，给出事实及其覆盖范围。
+- 深入后说明原因：先给结论，再给关键依据和尚不确定之处，写法参考[诊断结果交付](docs/diagnostic-report.md)。
+- 用户选择“整理为 bug 反馈”时：仅使用已取得的内容，按[整理为 bug 反馈](docs/diagnostic-report.md#整理为-bug-反馈)形成可直接提交的描述，不为此追加查询。
+
+知识中的内部术语（如计数单位、关联边、锚点、`unknown`、`needs_revalidation`）需转述为使用者可理解的业务表述；分析步骤使用页面上的中文名称（如“第 53 步：新增字段”），不使用 `AddNewColumn` 等类型名或引擎算子名；不要求使用者阅读源码或搭建代码环境。

package/content/README.md

@@ -1,6 +1,6 @@
 # fx-data 问题诊断助手
 
-`core-ai` 为没有产品代码环境的使用者提供 fx-data 问题的辅助排查。助手根据业务操作、日志和项目知识寻找可疑环节，说明可能原因、判断依据和下一步排查方向。
+`core-ai` 为没有产品代码环境的使用者提供 fx-data 问题的辅助排查。助手依据业务操作、日志和项目知识定位可疑环节，说明可能的原因、判断依据和后续排查方向。
 
 ## 解决什么问题
 
@@ -9,24 +9,25 @@
 | 分析表预览或步骤取数慢 | 数据范围、步骤计算与执行耗时 |
 | 组件或仪表板加载慢 | 查询条件、筛选、参数、联动与组件取数 |
 | 更新慢、超时、内存超限 | 调度等待、依赖、计算、写入与重试 |
-| 更新来源或数量不清楚 | 触发来源、更新链路、节点与尝试次数 |
+| 更新来源或数量不明确 | 触发来源、更新链路、节点与尝试次数 |
 | 生成单租户更新报告 | 小时峰值、`UpdateScene`、执行规模和耗时，交付 HTML |
-| 自动化没触发、通知没收到或回填失败 | 按 workflowId 核对每次执行、跳过原因、动作结果与回填进度 |
+| 自动化未触发、通知未收到或回填失败 | 按 workflowId 核对每次执行、跳过原因、动作结果与回填进度 |
+| 某个报错的含义与处理方式 | 按报错原文检索速查表，先说明含义和处理方式 |
 | 其他报错、结果异常或偶发不可用 | 核对现象与执行记录，整理已确认事实和待验证问题 |
 
-性能问题已有各场景的知识和入口提示。其他问题先根据现有材料辅助分析。
+性能问题已有各场景的知识和入口提示，其他问题先依据现有材料辅助分析。
 
 ## 开始前准备
 
-npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，它会按包内 README 安装（优先复用已有的共享安装），再登记当前客户端的 Skill。需要 Node.js/npm，Python 按需准备。安装副本每次新诊断时在后台检查更新，不耽误当前排查，更新失败继续用旧版（设计见源码仓库 `maintainers/npm-cli.md`）。
+npm 安装：向 Agent 发送“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，Agent 将按包内 README 安装（优先复用已有的共享安装），并登记当前客户端的 Skill。需要 Node.js/npm，Python 按需准备。安装副本在每次新诊断时于后台检查更新，不影响当前排查，更新失败时继续使用旧版（设计见源码仓库 `maintainers/npm-cli.md`）。
 
-1. 用源码目录时，用支持 `AGENTS.md` 的客户端（如 Codex、Claude Code）打开本仓库，更新规则见[助手执行契约](AGENTS.md#使用前更新代码)。
-2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动安装和配置，只需按提示在本机配置里填入对应环境的 API Key（正式、测试分开），不要把 Key 发在对话里。
-3. 只有离线材料（日志、trace 导出、Metric 文件）时不用配置，直接交给助手。
+1. 使用源码目录时，以支持 `AGENTS.md` 的客户端（如 Codex、Claude Code）打开本仓库，代码由使用者自行更新。
+2. 诊断需要查询 SigNoZ 的 trace、日志和引擎统计。尚未建立连接时助手会自动安装和配置，仅需按提示在本机配置中填入对应环境的 API Key（正式、测试环境分别配置），请勿在对话中发送 Key。
+3. 仅有离线材料（日志、trace 导出、Metric 文件）时无需配置，直接提供给助手即可。
 
 ## 如何提问
 
-直接描述发生了什么，并提供已有的对象链接、发生时间、环境、截图或日志。例如：
+直接描述发生的情况，并提供已有的对象链接、发生时间、环境、截图或日志。例如：
 
 > 正式环境，今天 10:20 左右，选择“华东区”后，销售仪表板的两个图表一直加载。这是仪表板链接和截图。
 
@@ -40,33 +41,34 @@ npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是
 
 > 帮我看下 workflowId=xxx 这个自动化最近的执行情况，客户说昨晚没收到通知。
 
-已有材料可以直接交给助手：
+已有材料可直接提供给助手：
 
-- 没说环境时默认查正式环境。
-- 查企业更新没给时间时，默认看最近 24 小时。
-- 给了 dagId 就能直接查更新链路，不需要再提供时间。
-- 说“之前正常”“以前没超限”，助手会自动找之前的正常记录做对比，不需要先提供成功记录。
-- 仪表板内组件异常时，助手会先查找对应组件的单独预览记录；找不到也会继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](knowledge/dashboard/workflow.md#组件取数先做对照)。
-- 缺少关键信息时，助手一次说明需要补充什么、用来判断什么。
+- 未说明环境时，默认查询正式环境。
+- 查询企业更新且未提供时间时，默认查看最近 24 小时。
+- 提供 dagId 即可直接查询更新链路，无需再提供时间。
+- 提及“之前正常”“以前没超限”时，助手会主动查找此前的正常记录进行对比，无需先提供成功记录。
+- 仪表板内组件异常时，助手会先查找对应组件的单独预览记录；未找到时仍继续分析，并提示检查单独预览是否同样异常。详见[组件取数对照](knowledge/dashboard/workflow.md#组件取数的对照核对)。
+- 缺少关键信息时，助手一次性说明需要补充的内容及其用途。
 
-继续同一问题时，助手沿用已确认的范围和查询结果。简单追问（数值、链接）直接回答，不重新排查。
+助手分步排查：首轮快速定位本次对应的操作、报错内容或耗时所在环节并简要汇报，随后给出若干可继续的方向供选择，也可选择整理为 bug 反馈。需要一次完成完整排查时，在开始时说明“直接查到底，无需询问”。继续同一问题时，助手沿用已确认的范围和查询结果。
 
-调查默认只读。修改业务资源、触发任务或改变配置前，助手会先取得明确授权；报告材料应脱敏。
+调查默认只读。修改业务资源、触发任务或变更配置前，助手会先取得明确授权；报告材料应脱敏。
 
-## 输出什么
+## 输出内容
 
-- 当前结论：哪个对象的哪次操作出现问题，已定位到什么环节或条件。
+- 本步骤结论：哪个对象的哪次操作出现问题，已定位到的环节或条件。
+- 后续选项：可继续排查的方向及各自能回答的问题；现象疑似产品缺陷时，可由助手整理为 bug 反馈。
 - 关键依据：对应执行记录、错误、统计或对照结果，以及它们如何支持判断。
 - 计算关系图：支持将同次计算已取得的依赖与逐表条件生成可独立打开的 HTML 图，能力与知识索引见[仪表板知识](knowledge/dashboard/README.md#能力)。
-- 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的材料。
+- 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料。
 - 需求反馈（有依据时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](docs/diagnostic-feedback.md)。
 
 ## 延伸阅读
 
 - [规则归属索引](docs/index.md)：每条规则由哪个文件维护。
 - [问题定位方法](docs/architecture.md)：通用排查思路与结论分层。
-- [按场景排查](docs/scenario-guide.md)：分析表、组件、仪表板、更新各自看什么。
-- [诊断结果交付](docs/diagnostic-report.md)：结论、复核依据和研发交接。
+- [按场景排查](docs/scenario-guide.md)：分析表、组件、仪表板、更新各自的排查要点。
+- [诊断结果交付](docs/diagnostic-report.md)：结论、复核依据和 bug 反馈的写法。
 
 ## 维护本项目
 

package/content/docs/architecture.md

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