# FX 数据诊断：Agent 安装与管理

本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261115133614`，需要 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`。技能目录由 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/skills/fx-data-diagnostics` 和 `.workbuddy-ai/skills/fx-data-diagnostics`，不扫描整个用户目录。薄 Skill 也记录了 Node 与稳定脚本的绝对路径。显式目录优先；多个安装无法消歧时说明冲突，不另建副本。
3. **已有安装只执行一次登记命令：**

   ```text
   <已有稳定入口> install --agent <当前 Agent>
   ```

   稳定入口复用原 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>
   ```

5. **按 `install` 返回结果结束安装。** `ok=true` 且 `checks.integrity`、`checks.skills`、`checks.context` 均为 `ok`，即已完成文件登记和检查。直接反馈，不再执行 `status`、`doctor`、`context` 或 `ls` 复查，不读取 CLI 源码、客户端缓存或诊断规则，不准备 Python/MCP，也不运行示例。结果已包含版本、复用情况、内容入口和阶段耗时。

安装完成后用 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 缺失不阻止登记，首次运行包内 Python 脚本时再准备。
- WorkBuddy 的 `.workbuddy/skills` 与 `.workbuddy-ai/skills` 由 CLI 按本机线索选择；无法确认时按 CLI 提示处理，不自行扫描客户端缓存或改成两处同时登记。

## 按需使用

用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`。其输出已包含首轮规则正文（AGENTS.md、公共查询规则全文、系统与环境知识全文）和本次临时目录，Agent 直接开始排查，其余知识仅在当前步骤需要时读取。CLI 在返回前检查并按需更新，再固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。

实时查询通过用户在当前客户端安装的 SigNoZ MCP 或 Skill 进行，凭据只保存在本机，不经过对话。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。

## 更新与回退

用户要求更新时，调用稳定入口的 `update`；要求回退到上次更新前时调用 `rollback`，明确指定版本时调用 `update --version <版本号>`。新调查使用切换后的版本，进行中的调查保持原版本。回退不锁定后续版本，下一次新诊断仍检查最新版；需要持续使用旧版时按配置变量关闭自动更新。新增客户端只登记，不隐式更新。

开始诊断时的自动更新由 CLI 在 `context` 内完成，无需 Agent 设置定时任务或另跑 `update`。更新静默完成，诊断输出不包含更新状态，无需读取或提示；用户询问时通过 `status` 查看。

旧版用户需先手动更新一次才能获得自动更新能力。版本切换后按客户端要求刷新技能或新开聊天。

若旧试用版提示需要迁移，先用当前 npm 包替换全局程序，直接调用新包 CLI 的 `update`，再登记与检查。迁移保留客户端登记、诊断材料和独立 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 残留，确认归属并清理后重试；不凭目录名直接删除，不扫描其他位置，也不宣称已完整卸载。

## 配置变量

| 变量 | 用途 |
|---|---|
| `FX_DATA_DIAGNOSTICS_HOME` | 自定义共享安装目录 |
| `FX_DATA_DIAGNOSTICS_PYTHON` | 自定义 Python 可执行文件 |
| `FX_DATA_DIAGNOSTICS_AGENT_HOME` | 自定义客户端用户目录，通常无需设置 |
| `FX_DATA_DIAGNOSTICS_AUTO_UPDATE` | 默认开启自动更新；设为 `0` 可关闭，适用于受限环境或需要持续使用旧版时 |

显式 CLI 参数优先，其次是环境变量，未指定时使用默认目录或自动发现的运行环境。