@fx-data/ai-diagnostics 0.1.20261016035151 → 0.1.20261027064707

package/AGENT_SETUP.md

@@ -1,64 +1,82 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261016035151`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261027064707`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+
+用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
+
+正常路径只完成下列步骤，成功即结束；仅当命令失败或结果不完整时进入异常处理。本工具不要求创建安装清单、读取或写入 `MEMORY.md` 等长期记忆；客户端另有强制要求时仍遵循其规则。
+
+用户提供本地 `.tgz` 时，优先只读取其中的 `package/AGENT_SETUP.md`，并将该包作为安装来源；无需联网查找另一份指引、完整解包或研究 CLI 源码。
 
 ## 安装与复用
 
-1. 识别当前客户端：WorkBuddy、Codex、Pi 分别使用 `workbuddy`、`codex`、`pi`。只登记当前客户端，明确传入 `--agent`，不使用 `all`，无需安装 `find-skills`。其他客户端尚无内置登记支持时说明限制，不冒充已完成安装。
-2. **先查找已有共享安装，再决定是否下载。** 设置了 `FX_DATA_DIAGNOSTICS_HOME` 时优先采用该目录，否则检查下表。
+1. 识别当前客户端：WorkBuddy、Codex、Pi 分别使用 `workbuddy`、`codex`、`pi`。只登记当前客户端，明确传入 `--agent`，不使用 `all`，无需安装 `find-skills`。技能目录由 CLI 识别，Agent 不自行研究客户端缓存或包内代码。其他客户端尚无内置登记支持时说明限制。
+2. **合并为一次必要探测：先找共享入口，缺失时再检查现有 Node/npm 和全局包。** 在同一次 shell 调用中按顺序判断；命中已有入口即可停止探测，不逐项调用工具或重复核对。设置了 `FX_DATA_DIAGNOSTICS_HOME` 时优先采用该目录，否则检查下表。
 
    | 平台 | 默认共享目录 | 稳定入口（相对共享目录） |
    |---|---|---|
    | macOS / Linux | `$XDG_DATA_HOME/fx-data-diagnostics`，未设置时为 `~/.local/share/fx-data-diagnostics` | `bin/fx-data-diagnostics` |
    | Windows | `%LOCALAPPDATA%\fx-data-diagnostics`，未设置时为 `%USERPROFILE%\AppData\Local\fx-data-diagnostics` | `bin\fx-data-diagnostics.cmd` |
 
-   自定义目录还可从已有薄 Skill 的 `.core-ai-owner.json` 中读取 `home`；只检查用户目录下 `.agents/skills/fx-data-diagnostics` 和 `.workbuddy-ai/skills/fx-data-diagnostics`，不扫描整个用户目录。薄 Skill 也记录了 Node 与稳定脚本的绝对路径。显式目录优先；多个安装无法消歧时说明冲突，不另建副本。
-3. **已有安装直接登记当前 Agent。** 使用其稳定入口运行 `status`，确认 `installed=true`、`package=@fx-data/ai-diagnostics`，再依次执行：
+   自定义目录还可从已有薄 Skill 的 `.core-ai-owner.json` 中读取 `home`；只检查用户目录下 `.agents/skills/fx-data-diagnostics`、`.workbuddy/skills/fx-data-diagnostics` 和 `.workbuddy-ai/skills/fx-data-diagnostics`，不扫描整个用户目录。薄 Skill 也记录了 Node 与稳定脚本的绝对路径。显式目录优先；多个安装无法消歧时说明冲突，不另建副本。
+3. **已有安装只执行一次登记命令：**
 
    ```text
    <已有稳定入口> install --agent <当前 Agent>
-   <已有稳定入口> doctor
-   <已有稳定入口> context
    ```
 
-   稳定入口复用原 Node，此分支不调用 `npm install`、`npx` 或 `update`。当前 shell 找不到 Node/npm、npm 全局目录没有本包，都不能证明共享安装不存在。Node 路径失效时先修复原运行环境；内容损坏、所有权冲突或权限错误应处理具体错误，不通过第二份安装绕过。
-4. **没有共享安装时才准备首次安装。** 先检查 PATH 中的 `fx-data-diagnostics` 或当前 npm 的全局包目录；已有完整包可直接调用 CLI 登记。确需下载时，优先复用符合 `engines` 要求的已有 Node/npm，不满足时使用客户端托管环境，或从 [Node.js 官方下载](https://nodejs.org/en/download) 获取匹配平台的独立发行包、校验官方校验和后放到用户目录。使用其绝对路径，不替换用户项目的环境，不要求用户手动设置 PATH。
-5. 首次下载和登记如下，`<当前 Agent>` 替换为第 1 步确认的名称：
+   稳定入口复用原 Node，此分支不调用 `npm install`、`npx` 或 `update`，也不需要先运行 `status`。当前 shell 找不到 Node/npm、npm 全局目录没有本包，都不能证明共享安装不存在。
+4. **没有共享安装时才准备首次安装。** 使用第 2 步的探测结果：PATH 中的 `fx-data-diagnostics` 或当前 npm 全局目录已有完整包时，直接调用 CLI 登记。否则复用符合要求的 Node/npm 安装包；环境不满足才进入下方「环境或安装异常」。下面两步可在同一次 shell 调用中顺序执行，npm 安装成功后才登记；用户提供本地 `.tgz` 时将包名替换为该文件路径：
 
    ```text
    npm install -g @fx-data/ai-diagnostics
    fx-data-diagnostics install --agent <当前 Agent>
-   fx-data-diagnostics doctor
-   fx-data-diagnostics context
    ```
 
-   全局目录不可写时仅为本次安装指定用户目录的 `--prefix`；现有源找不到本包时仅为本次命令指定 `--registry=https://registry.npmjs.org`，不改全局 npm 配置。已有安装不重复执行 npm 安装命令。
-6. 独立 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 调用带引号的可执行路径需要 `&`。不依赖用户项目目录。
-7. 核对 `doctor` 的完整性、当前客户端登记和 `context` 返回的规则文件可读。失败时同时读取 stderr 中的检查结果。Python 缺失不阻止安装，解析脚本首次需要时再补齐。需要刷新技能时完成客户端支持的刷新（如 Pi 的 `/reload`）；无法自动刷新则说明下一步，不把磁盘登记当成已经验证客户端发现。
+5. **按 `install` 返回结果结束安装。** `ok=true` 且 `checks.integrity`、`checks.skills`、`checks.context` 均为 `ok`，即已完成文件登记和检查。直接反馈，不再执行 `status`、`doctor`、`context` 或 `ls` 复查，不读取 CLI 源码、客户端缓存或诊断规则，不准备 Python/MCP，也不运行示例。结果已包含版本、复用情况、内容入口和阶段耗时。
 
-安装完成后简短反馈“已启用 FX 数据诊断”、版本、复用或首次下载的结果，以及需要用户执行的刷新动作。将 CLI 返回的 `next_step` 作为默认使用提示：
+安装完成后用 2–3 句话反馈：版本和首次安装/复用结果；需要的刷新动作；`next_step` 的用法。不附安装过程、目录清单或后续计划。文件登记成功不代表客户端已发现技能；`checks.skills.client_discovery=not_verified` 时只提示刷新或新开聊天，不宣称“已启用”，也不为证明发现而读取客户端缓存。可使用客户端支持的刷新方式（如 Pi 的 `/reload`），无需重新检查安装。默认使用提示为：
 
 > 用 FX 数据诊断分析这条 trace 为什么内存超限。
 
 提示用户附上实际发生问题的 traceId 或链接。不要自动发起诊断，也不要用虚构 corpId 或整租户时间窗查询作为安装后的默认演示。
 
+## 环境或安装异常
+
+仅在命令失败、缺少必要运行环境或返回结果不完整时查看本节；成功结果无需额外检查。
+
+- Node/npm 不满足包要求时，使用客户端托管环境，或从 [Node.js 官方下载](https://nodejs.org/en/download) 获取匹配平台的独立发行包，校验官方校验和后放到用户目录。使用绝对路径，不替换用户项目环境，不要求用户手动配置 PATH。
+- 独立 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 缺失不阻止登记，首次解析材料时再准备。
+- WorkBuddy 的 `.workbuddy/skills` 与 `.workbuddy-ai/skills` 由 CLI 按本机线索选择；无法确认时按 CLI 提示处理，不自行扫描客户端缓存或改成两处同时登记。
+
 ## 按需使用
 
-明确调用 FX 数据诊断后，按薄 Skill 执行 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。固定本次调查的版本与 `pinned_cli`；普通聊天无需预加载诊断内容。
+用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
 已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 解析按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
 ## 更新与回退
 
-用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。新增客户端只登记，不隐式更新。
+用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。回退不锁定后续版本，下一次新诊断仍检查最新版；需要持续使用旧版时按配置变量关闭后台更新。新增客户端只登记，不隐式更新。
+
+使用时的后台更新由 CLI 完成，无需 Agent 设置定时任务或另跑 `update`。通知读取、去重和提示按 [安装副本的助手规则](content/AGENTS.md#安装副本的助手规则)执行，不轮询等待。
 
-用户要求自动更新时，通过当前客户端或系统调度同一稳定入口的 `update`，告知是否设置成功；普通诊断不自动检查或更新。版本切换后按客户端要求刷新技能或新开聊天。
+旧版用户需先手动升级一次才能获得后台更新能力。版本切换后按客户端要求刷新技能或新开聊天。
 
 若旧试用版提示需要迁移，先用当前 npm 包替换全局程序，直接调用新包 CLI 的 `update`，再登记与检查。迁移保留客户端登记、诊断材料和独立 MCP 配置；旧试用版不作为回退目标。
 
 ## 卸载
 
-先运行 `status`，说明将一起移除哪些已登记客户端的入口和已安装版本，以及进行中的诊断将无法继续使用包内脚本。用户已明确要求卸载时，说明影响后执行 `uninstall`，不重复请求确认；成功后在原安装环境执行 `npm uninstall -g @fx-data/ai-diagnostics`，沿用自定义 prefix。保留诊断材料和独立 MCP 配置。
+用户已明确要求卸载时，先说明会一起移除本账户已登记客户端的入口、所有已安装版本和 npm 包，进行中的诊断将无法继续调用包内脚本；随后直接执行稳定入口的 `uninstall`，不重复请求确认，不先运行 `status`、`context` 或读取诊断规则。
+
+CLI 使用首次安装记录的 Node/npm 和 prefix，在无网络模式下清理 npm 包，再移除受管副本及薄 Skill。`ok=true`、`complete=true` 即完整卸载成功：用 2–3 句话报告 `removed_skills`、`npm_package` 对应的结果和保留内容后结束，不再运行 `status`、`ls`、`npm uninstall` 或写安装清单/长期记忆。本工具保留的是用户提供的日志、Metric 文件和生成报告，以及独立 MCP 配置；包内规则与知识随包删除，无需扫描或备份其他目录。
+
+若安装未记录可用 npm 来源、返回 `npm_package.status=unconfirmed`，只按返回的 `fallback` 补充清理，不猜测其他 npm 环境或宣称已完整卸载。npm 清理失败时受管状态和入口会保留，按错误修复原环境后重试同一 `uninstall`；需要进一步排错时才运行 `doctor`。
+
+若返回 `npm_package.status=partial`，仅核对 `residual_paths` 列出的疑似 npm 残留，确认归属并清理后重试；不凭目录名直接删除，不扫描其他位置，也不宣称已完整卸载。
 
 ## 配置变量
 
@@ -67,5 +85,6 @@
 | `FX_DATA_DIAGNOSTICS_HOME` | 自定义共享安装目录 |
 | `FX_DATA_DIAGNOSTICS_PYTHON` | 自定义 Python 可执行文件 |
 | `FX_DATA_DIAGNOSTICS_AGENT_HOME` | 自定义客户端用户目录，通常无需设置 |
+| `FX_DATA_DIAGNOSTICS_AUTO_UPDATE` | 默认开启后台更新；设为 `0` 可关闭，适用于受限环境或需要持续使用旧版时 |
 
 显式 CLI 参数优先，其次是环境变量，未指定时使用默认目录或自动发现的运行环境。

package/README.md

@@ -22,20 +22,20 @@
 
 ## 更新
 
-> 更新 FX 数据诊断。
+每次开始新诊断时，工具会在后台检查更新，不等待更新即可排查。更新成功后，各 Agent 的下一次新诊断使用新版；当前调查保持原版本，更新失败也不影响排查。Agent 会随后续使用提示更新状态，没有新版时不打扰你。
 
-已启用的 Agent 共用更新后的版本。需要自动更新时，可以说：
+需要立即更新并等待完成时说：
 
-> 帮我设置每天上午 9 点（北京时间）检查并更新 FX 数据诊断的任务，失败时通知我。
+> 更新 FX 数据诊断。
 
-能否设置定时任务取决于当前Agent。若新版有问题，可以说“把 FX 数据诊断回退到这次更新前的版本”。
+旧版用户先手动更新一次，即可获得后台更新能力。若新版有问题，可以说“把 FX 数据诊断回退到这次更新前的版本”；需要持续使用旧版时，同时让 Agent 关闭后台更新。
 
 ## 卸载
 
 > 卸载 FX 数据诊断。
 
-卸载会删除 npm 包、本机当前账户下的诊断能力包及已登记的各 Agent 入口。诊断材料和独立配置的 SigNoZ 连接会保留。
+卸载会删除 npm 包、本机当前账户下的诊断能力包（含规则和知识）及已登记的各 Agent 入口。用户提供的日志、Metric 文件和生成报告，以及独立配置的 SigNoZ 连接会保留。
 
 ---
 
-**给 Agent：** 安装与管理前读取[Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261016035151/AGENT_SETUP.md)；已下载的包中也有同名文件。在线链接不可用时，可从 npm 官方仓库的对应版本包中读取该文件。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261027064707/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。