@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/doctor.js

@@ -0,0 +1,975 @@
+// 自检：`doctor`（契约 §2 的「自检」行、§5 的第 ⑦ 段、§3.2 退出码）。
+//
+// 回答四个问题：**版本对不对、凭据在不在、设备指纹稳不稳、连不连得上**，
+// 外加"服务端当前发布的是哪一版、这台机器要不要/能不能升上去"。
+// 每一项都给"下一步该敲什么"，而不是只报一串状态。
+//
+// ## 五件容易做错的事（都是 Rust 版拿实测换来的口径，逐条照抄）
+//
+// 1. **`doctor` 正常路径永远以退出码 0 收尾**，哪怕报告里全是问题。
+//    "连不上服务端"只是 `problems` 里的一项（`what="连不上服务端"`），不是退出码 7：
+//    自检的价值恰恰在于网络不通时也能把本机状态（凭据、权限、代理判定）说清楚；
+//    `/cli/latest` 问不到（旧服务端没有这个端点）同理，只记进 `release.error`。
+//    唯一的硬失败是服务端**明确判定太旧**（`cli.too_old`）——那是退出码 8。
+// 2. **`/health` 与 `/cli/latest` 都是匿名请求**（`capability="public"`）：
+//    凭据过期、刚装好还没登录的人也要能自检、能问出该装哪一版 ——
+//    把版本协商关在登录之后，等于让最需要自救的人连"我该升到哪一版"都问不出来。
+//    唯一的例外是 `--upgrade` 的第一步：它走 `sendAuthed`（见下）。
+// 3. **`--dry-run` 与 `--out` 是两件事**（契约 §5 ⑦ 写得很细）：
+//    * `--dry-run`：**升级动作本身**止步于"问一次 `/cli/latest`"——不下载、不写任何文件。
+//      它是给人看的"将要发生什么"，不是"轻量地做一次"。Rust 版真踩过这个坑：
+//      `doctor --upgrade --dry-run` 曾经真的把自己换掉了。
+//      （注意线上其实有**两次** `/cli/latest`：一次是上面第 2 条的匿名 release 探测，
+//      一次是 `--upgrade` 自己的第一步，两次都只读，且实测 Rust 0.1.7 也是两次。）
+//    * `--out <路径>`：把**服务端当前发布的那一份产物**写到指定路径，
+//      **当前可执行文件一个字节都不动**；它**与本机是不是最新无关** ——
+//      本机恰好最新时若走"已是最新，什么都不做"的早退，用户拿到的是
+//      "命令成功、路径上却什么都没有"（装到别的机器 / 排障 / 核对 sha256 都靠它）。
+// 4. **`--upgrade` 失败不改写 `problems`、也不改退出码**：它落进
+//    `data.upgrade.error` + `data.next_steps`，`ok` 仍可能是 true。
+//    这是 Rust 的口径：`problems` 是"本机自检发现的问题"，升级失败是"这次动作没做成"，
+//    两件事分开报，脚本才不会把"升级失败"读成"这台机器坏了"。
+//    绝不假装成功：没落盘就一定 `replaced=false` + `error`。
+// 5. **升级的动作有两套，凭据要求也不同**（2026-10-16 起）：
+//    * **不带 `--out`**（= 常规升级）只问 public 的 npm registry，**不需要登录** ——
+//      升级是包管理器的事，把一个 npm 查询绑在平台凭据上只会让"登录过期的人连
+//      升级命令都问不出来"。这条路**一个字节都不写**，只给 `npm i -g …@latest`。
+//    * **带 `--out`** 走服务端的产物通道：`/cli/download/<os>/<arch>` 要有效令牌
+//      （产物不该匿名可取），而令牌只活在 0600 的凭据文件里（刻意不打印、不进 argv），
+//      所以没登录会报 `auth.missing_token`；"把 URL 给人拿浏览器下"这条路走不通，
+//      要用产物就得让 CLI 自己带凭据去取。
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import embeddedSkills from '../spec/embedded_skills.json' with { type: 'json' };
+import { EXIT_TOO_OLD, Kind, CliError, loginHint } from '../core/error.js';
+import { PACKAGE_NAME } from '../version.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { ProxyPlan, USER_AGENT, VERSION_HEADER, requestSpec } from '../core/http.js';
+import { CredentialStore } from '../core/config.js';
+import { renderHuman } from '../core/output.js';
+import { maskPhone, maskToken, sortKeysDeep } from '../core/util.js';
+import { accessNeedsRefresh, refreshExpired } from '../core/auth.js';
+import { VERSION } from '../version.js';
+import { probeHealth, fetchLatestRelease } from './config.js';
+
+/**
+ * 关于"换掉自己"这件事（2026-10-16 之后 **没有**这条路了，读之前先看结论）
+ *
+ * Node 版曾经移植过 Rust 的自替换：把 `/cli/download/...` 下来的产物写到
+ * `package.json` 的 `bin` 映射指向的 `bin/xinhe-oa-cli.js`（用 `import.meta.url`
+ * 自定位，而不是 `argv[1]` —— 本模块也能被 `import { runCli }` 当库用，那时的
+ * `argv[1]` 是宿主的脚本，拿它当"自己"等于删别人的文件）。
+ *
+ * 现在这条路**整段删掉**了，理由两条（细节见下面 `npmUpgradePlan` 的注释）：
+ *
+ * 1. 入口由 npm 管理：包的文件树归 npm 记账，自己替换其中一个文件会让
+ *    `package.json` 的版本与磁盘内容对不上，下次 `npm i -g` 的行为不可预期；
+ * 2. 通道会串：`/cli/download/{os}/{arch}` 现在是**给安装脚本与手工下载**用的
+ *    Node 入口脚本（见 `cli-node/scripts/download-entry.template.js`），
+ *    而它过去发的是 Rust 二进制 —— 同一组平台键下换内容，只靠 sha256 分辨不出来。
+ *
+ * 于是 `--upgrade` 只剩两条落盘语义，都不碰"自己"：
+ *   * 不带 `--out`：只问 npm registry，给一句 `npm i -g …@latest`（`npmUpgradePlan`）；
+ *   * 带 `--out`：把服务端当前发布的那份产物写到**那个路径**（`--out` 的本义），
+ *     并且落盘前过一道内容嗅探（`assertLooksLikeJavaScript`）。
+ */
+
+/**
+ * 内嵌技能数量。
+ *
+ * Rust 版是 `build.rs` 在**构建期**扫仓库 `skills/<名字>/SKILL.md` 得到的常量；
+ * Node 版没有构建期，内嵌清单由 `scripts/gen-embedded-skills.py` 生成到
+ * `src/spec/embedded_skills.json`（`skills.js` 读的也是它）。两者是同一份事实，
+ * 所以这里**读真实清单**而不是写常数 —— 写死 0 会让 `doctor --json` 的
+ * `embedded_skills` 与 Rust 不一致，而那是"两边功能一致"要盯的字段。
+ */
+const EMBEDDED_SKILLS = embeddedSkills.skills.length;
+
+/** 平台词汇必须与服务端 `/cli/latest` 的 `platforms[].os/arch` 同一套。 */
+export function platform() {
+  const os =
+    process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'darwin' : 'linux';
+  // 与 Rust 的 `cfg!(target_arch = "aarch64")` 等价：**只有** arm64 是 arm64，
+  // 其余一律 amd64（服务端只认这两套词汇）。
+  const arch = process.arch === 'arm64' ? 'arm64' : 'amd64';
+  return [os, arch];
+}
+
+/** 服务端 `{"data": ...}` 拆包（`/cli/latest` 两种形状都容忍）。 */
+function unwrap(body) {
+  if (body && typeof body === 'object' && body.data !== undefined && body.data !== null) {
+    return body.data;
+  }
+  return body ?? {};
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 错误摘要（`doctor` 的报告里错误只以 `{code, message}` 出现）。 */
+function errorSummary(err) {
+  return {
+    code: typeof err?.code === 'string' ? err.code : 'cli.network',
+    message: typeof err?.message === 'string' ? err.message : String(err),
+  };
+}
+
+/**
+ * 出网期间**钉住事件循环**（一个兜底定时器，跑完就放掉）。
+ *
+ * 为什么需要：`core/http.js` 的退避重试 `sleep()` 一度用的是 **unref 过的**
+ * `setTimeout`。当进程里只剩这一个待办时，Node 判定"没活干了"直接退出 ——
+ * 顶层 `await` 还没结算，于是退出码 13（`Detected unsettled top-level await`），
+ * stdout 一个字节都没有。
+ *
+ * 后果正好落在最需要自检的那条路径上：`base_url` 指向一个没人听的端口时，
+ * `doctor --json` 只往 stderr 打一行"网络故障…重试"，然后**退出 13、没有报告**
+ * （实测四种 stdio 组合都一样）。Rust 版没有这个问题（tokio 的 sleep 会撑着运行时），
+ * 而契约 §2 要求"不联网时 doctor 仍以退出码 0 收尾，报告里如实记一条'连不上服务端'"。
+ *
+ * 本文件写完时 core 已经把那处 unref 去掉了（`http.js` 的 `sleep` 现在是普通定时器），
+ * 这层兜底仍然保留：`doctor` 的不联网口径不该取决于"别人的定时器有没有 unref"，
+ * 一个空定时器的成本可以忽略，而失效的样子（静默退出、没有报告）最难排查。
+ */
+async function keepAlive(task) {
+  const handle = setInterval(() => {}, 1000);
+  try {
+    return await task();
+  } finally {
+    clearInterval(handle);
+  }
+}
+
+/**
+ * Unix 权限位的八进制串（`700` / `644` …）。
+ *
+ * 与 Rust 的 `format!("{:o}", mode & 0o777)` 同形：**不带**前导 0，
+ * 所以下面的比较写的是 `"600"` 而不是 `"0600"`。
+ */
+function modeString(target) {
+  if (process.platform === 'win32') return null;
+  try {
+    return (fs.statSync(target).mode & 0o777).toString(8);
+  } catch {
+    return null;
+  }
+}
+
+/** Rust `Path::parent()` 的口径（`cfg` 的父目录是 `""`，不是 Node 的 `"."`）。 */
+function parentPath(target) {
+  const text = String(target).replace(/[\\/]+$/, '');
+  if (text.length === 0) return null;
+  const cut = Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\'));
+  if (cut < 0) return '';
+  return cut === 0 ? text.slice(0, 1) : text.slice(0, cut);
+}
+
+/** sha256（小写十六进制，64 字符）——校验下载产物用。 */
+function sha256Hex(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+/** Rust `Path::with_extension()`：**替换**最后一个点之后的部分（不是往后追加）。 */
+function withExtension(target, extension) {
+  const base = path.basename(target);
+  const dot = base.lastIndexOf('.');
+  // 以 `.` 开头且再无点（`.hidden`）在 Rust 里算"没有扩展名"，stem 是整个文件名。
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  return path.join(path.dirname(target), `${stem}.${extension}`);
+}
+
+function removeQuietly(target) {
+  try {
+    fs.unlinkSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 落盘 + **强制 0755**（脚本要能直接执行；Rust 侧同样是写后 set_permissions）。 */
+function writeExecutable(target, bytes, label = '') {
+  try {
+    fs.writeFileSync(target, bytes);
+  } catch (err) {
+    throw CliError.usage(`写不了${label} ${target}：${err.message}`);
+  }
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(target, 0o755);
+    } catch {
+      // 与 Rust 的 `let _ = set_permissions(...)` 一致：收权限失败不阻断落盘。
+    }
+  }
+}
+
+/**
+ * 落位：`<目标>` → `<目标>.old`，新内容 → `<目标>`（Rust `swap_in_place` 的逐句移植）。
+ *
+ * 两条纪律：
+ * * 目标**不存在**不是"替换"而是"装到新位置"（`--out <新路径>`）：没有旧文件可改名，
+ *   直接落盘（父目录按需创建）。Rust 侧实测踩过：rename 会报 "No such file or directory"，
+ *   而错误信息把原因说成"可能没有写权限"——指错方向。
+ * * 替换失败**尽量还原**：宁可回到旧版本，也不要"两个都没有"。
+ */
+function swapInPlace(target, bytes) {
+  // 上一次升级留下的 `.old`：这次能删就删（Windows 上上一次的进程早已退出）。
+  const stale = `${target}.old`;
+  const staleRemoved = fs.existsSync(stale) ? removeQuietly(stale) : false;
+
+  if (!fs.existsSync(target)) {
+    const parent = path.dirname(target);
+    if (parent.length > 0 && parent !== '.') {
+      try {
+        fs.mkdirSync(parent, { recursive: true });
+      } catch {
+        // 与 Rust 的 `let _ = create_dir_all` 一致：建不了就让下面的写操作去报错。
+      }
+    }
+    writeExecutable(target, bytes);
+    return staleRemoved;
+  }
+
+  const staging = withExtension(target, 'new');
+  writeExecutable(staging, bytes, '临时文件');
+  try {
+    fs.renameSync(target, stale);
+  } catch (err) {
+    removeQuietly(staging);
+    throw CliError.usage(
+      `换不了 ${target}：${err.message}（可能没有写权限；试 \`--out\` 写到别处，或用管理员/root 再跑一次）`,
+    );
+  }
+  try {
+    fs.renameSync(staging, target);
+  } catch (err) {
+    try {
+      fs.renameSync(stale, target);
+    } catch {
+      // 还原也失败：下面的错误信息会如实说"已尝试还原"。
+    }
+    removeQuietly(staging);
+    throw CliError.usage(`新版本落位失败：${err.message}；已尝试还原旧版本`);
+  }
+  return staleRemoved;
+}
+
+/** 从 `/cli/latest` 的响应里挑出本机平台的产物。 */
+function artifactFor(latest, os, arch) {
+  const platforms = Array.isArray(latest?.platforms) ? latest.platforms : null;
+  if (platforms === null) return null;
+  return (
+    platforms.find(
+      (item) => item?.os === os && item?.arch === arch,
+    ) ?? null
+  );
+}
+
+/**
+ * 升级结果 → `data.upgrade`（Rust `UpgradeOutcome::to_json` 的逐字移植）。
+ *
+ * `replaced` 说的是"有没有落盘"，`target` 说的是"落在哪儿"：
+ * 两者合起来（`current_binary_touched`）才不会把 `--out` 误读成"我被换了"。
+ */
+function outcomeJson(outcome) {
+  const touchedSelf = outcome.replaced && !outcome.installedElsewhere;
+  const pathText = outcome.path;
+  let nextStep;
+  // npm 通道的 `next_step` 在 `npmUpgradePlan` 里就算好了（它知道 registry 通不通、
+  // 有没有新版本），这里**不要**用下面的"落盘/替换"话术覆盖它。
+  if (outcome.npm !== undefined && outcome.npm !== null) {
+    nextStep = outcome.next_step;
+  } else if (outcome.dryRun && outcome.installedElsewhere) {
+    nextStep = `--dry-run：没有下载、也没写任何文件；去掉 --dry-run 才会把 ${outcome.to} 的产物写到 ${pathText}`;
+  } else if (outcome.dryRun) {
+    nextStep = `--dry-run：没有下载、没有替换；去掉 --dry-run 才会把 ${outcome.from} 换成 ${outcome.to}（${pathText}）`;
+  } else if (outcome.installedElsewhere) {
+    nextStep = `产物已写到 ${pathText}（sha256 已校验）；当前运行的二进制没有改动`;
+  } else if (outcome.replaced) {
+    nextStep =
+      '重开一个终端（或重新执行命令）用的就是新版本；`xinhe-oa-cli --version` 可以核对';
+  } else {
+    nextStep = '已经是最新，什么都不用做';
+  }
+  return {
+    from: outcome.from,
+    to: outcome.to,
+    path: pathText,
+    target: outcome.installedElsewhere ? 'out' : 'npm',
+    // npm 通道的细节（`target: "npm"` 时才有）：包名、registry、探测到的版本、
+    // "是不是更新"，以及可直接照抄的命令。`error` 非空表示问不到 registry。
+    ...(outcome.npm !== undefined && outcome.npm !== null ? { npm: outcome.npm } : {}),
+    replaced: outcome.replaced,
+    dry_run: outcome.dryRun,
+    current_binary_touched: touchedSelf,
+    bytes: outcome.bytes,
+    sha256: outcome.sha256,
+    stale_removed: outcome.staleRemoved,
+    next_step: nextStep,
+  };
+}
+
+/** 升级成功后 `doctor` 往 `next_steps` 里追加的那一句（比 `upgrade.next_step` 详细）。 */
+function outcomeNextStep(outcome) {
+  // npm 通道：升级由包管理器做，CLI 只给命令。
+  if (outcome.npm !== undefined && outcome.npm !== null) {
+    return outcome.next_step;
+  }
+  if (outcome.dryRun && outcome.installedElsewhere) {
+    return `--dry-run：没有下载、也没写任何文件；去掉 --dry-run 才会把 ${outcome.to} 的产物写到 ${outcome.path}`;
+  }
+  if (outcome.dryRun) {
+    return `--dry-run：没有下载、没有替换；去掉 --dry-run 才会把 ${outcome.path}（当前 ${outcome.from}）换成 ${outcome.to}`;
+  }
+  if (outcome.installedElsewhere) {
+    return `产物已写到 ${outcome.path}（${outcome.from} → ${outcome.to}，${outcome.bytes} 字节，sha256 已校验）；当前运行的二进制没有改动`;
+  }
+  if (outcome.replaced) {
+    return `已从 ${outcome.from} 升到 ${outcome.to}：${outcome.path}（重开终端即用新版本）`;
+  }
+  return `已经是最新（${outcome.to}），什么都没做`;
+}
+
+/**
+ * 执行自更新（Rust `update::upgrade` 的逐句移植）。`outPath` 为空则替换当前可执行文件。
+ *
+ * 两条硬纪律（见文件头）：`--dry-run` 时**升级动作本身**只问一次 `/cli/latest`、
+ * 一个字节都不写；`--out` 时产物写到那个路径、当前可执行文件一个字节都不动。
+ */
+async function performUpgrade(runtime, outPath) {
+  const [os, arch] = platform();
+  const installedElsewhere = outPath !== null;
+
+  // **不带 `--out` 就是"我要升级"**，而升级现在走 npm：这条路**不碰**产物通道
+  // （`/cli/latest` 的产物是给安装脚本与手工下载用的 Node 入口脚本，与"升级本机"无关），
+  // 所以先返回，连"服务端有没有发本平台产物"都不必过问。
+  if (!installedElsewhere) {
+    return await npmUpgradePlan(runtime);
+  }
+
+  // ① 问服务端发布了什么。这一次**带凭据**（`sendAuthed`）：接下来要下载的
+  //    `/cli/download/...` 要令牌，先在这里把"没登录"如实报出来
+  //    （`auth.missing_token` → 退出码 3 的 hint 会进 next_steps）。
+  const response = await keepAlive(() => runtime.sendAuthed('GET', '/cli/latest', requestSpec()));
+  const body = unwrap(response.body);
+
+  const published = typeof body.version === 'string' ? body.version : '';
+  if (published.length === 0) {
+    throw new CliError(
+      Kind.Server,
+      'cli.artifact_missing',
+      '服务端没有报告 CLI 版本号（/cli/latest 的响应里没有 version）',
+    ).withHint('确认服务端已配置 CLI_DIST_DIR，且 dist/cli/manifest.json 存在');
+  }
+
+  const artifact = artifactFor(body, os, arch);
+  if (artifact === null) {
+    const available = Array.isArray(body.platforms)
+      ? body.platforms
+          .filter((item) => isPlainObject(item) && typeof item.os === 'string' && typeof item.arch === 'string')
+          .map((item) => `${item.os}/${item.arch}`)
+      : [];
+    throw new CliError(
+      Kind.Server,
+      'cli.artifact_missing',
+      `服务端没有发布 ${os}/${arch} 的产物`,
+    ).withHint(
+      `服务端当前有：${
+        available.length === 0 ? '（一个都没有）' : available.join('、')
+      }。这台机器的平台可能还没构建（docs/31 §5 的说明）`,
+    );
+  }
+
+  // 走到这里只剩一条落盘路径：`--out <路径>`（把服务端当前发布的那份产物写到别处，
+  // 供核对/装机/排障用），当前可执行文件一个字节都不动。
+  const target = outPath;
+  // `/cli/latest` 报的产物指纹：落盘前拿它校验；预演时它就是"将要写入的东西"。
+  const expected = typeof artifact.sha256 === 'string' ? artifact.sha256.toLowerCase() : '';
+  const expectedSize =
+    Number.isInteger(artifact.size) && artifact.size >= 0 ? artifact.size : 0;
+
+  // ② `--dry-run` 到这里止步：上面那次 `/cli/latest` 是**只读**的，下面才是"写"。
+  if (runtime.dryRun) {
+    return {
+      from: VERSION,
+      to: published,
+      path: target,
+      replaced: false,
+      installedElsewhere,
+      dryRun: true,
+      staleRemoved: false,
+      bytes: expectedSize,
+      sha256: expected,
+    };
+  }
+
+  // ③ 下载（**用已有登录凭据**：令牌由 CLI 自己从 0600 的凭据文件取，不进 argv、不打印）。
+  //    二进制响应由 http 层按 content-type 落进 `raw`（与附件下载同一条路）。
+  const download = await keepAlive(() =>
+    runtime.sendAuthed('GET', `/cli/download/${os}/${arch}`, requestSpec()),
+  );
+  const bytes = Buffer.isBuffer(download.raw) ? download.raw : Buffer.alloc(0);
+  if (bytes.length === 0) {
+    throw new CliError(
+      Kind.Server,
+      'cli.artifact_missing',
+      '下载到的是空文件，没有替换任何东西',
+    );
+  }
+
+  // ④a **内容嗅探**：产物通道现在发的是 Node 入口脚本（`cli-node/scripts/
+  //     download-entry.template.js`），而它过去发的是 Rust 二进制（ELF/PE）——
+  //     两种内容共用同一组平台键。只看 sha256 的话，"服务端发的不是 JS"会被当成
+  //     "新版本"照落，落下去的就是一个永远不会执行的入口。这道闸门与 sha256 是
+  //     **两件事**：sha256 管完整性，这一道管"它是不是能当我自己的东西"。
+  assertLooksLikeJavaScript(outPath, bytes);
+
+  // ④ 校验：不通过 ⇒ **一个字节都不落盘**（换上去的是用户干活唯一的工具，宁可不动）。
+  if (expected.length > 0) {
+    const actual = sha256Hex(bytes);
+    if (actual !== expected) {
+      throw new CliError(
+        Kind.Server,
+        'cli.checksum_mismatch',
+        `下载内容与 /cli/latest 报的 sha256 不一致（期望 ${expected}，实际 ${actual}）`,
+      ).withHint('没有替换任何文件；重试一次，仍不一致请联系运维');
+    }
+  }
+
+  // ⑤ 落位（自己或 `--out` 那个路径）。
+  const staleRemoved = swapInPlace(target, bytes);
+  return {
+    from: VERSION,
+    to: published,
+    path: target,
+    replaced: true,
+    installedElsewhere,
+    dryRun: false,
+    staleRemoved,
+    bytes: bytes.length,
+    sha256: sha256Hex(bytes),
+  };
+}
+
+
+// ---------------------------------------------------------------------------
+// 升级：npm 是唯一通道（Node 作为唯一客户端入口之后）
+// ---------------------------------------------------------------------------
+/**
+ * 为什么 Node 版**不再自更新**（这是一条刻意的行为变更，改回去前先读这段）
+ *
+ * 1. **通道冲突**：`/cli/download/{os}/{arch}` 是**服务端产物通道**，内容由服务端
+ *    决定，Node 版过去把自己也接到这条通道上升级 —— 于是"服务端发的是 ELF 还是 JS"
+ *    决定了用户下次还能不能启动客户端（只看 sha256 是拦不住的：那是服务端报的、
+ *    对得上的哈希）。两种东西抢同一个 slot，迟早出事。
+ *    （2026-10-16 起这条通道改发 Node 入口脚本 —— 但那是**给安装脚本与手工下载**的，
+ *    升级仍然只走 npm；`--out` 那道内容嗅探留着，防的就是"通道又被换回二进制"。）
+ * 2. **npm 生态里升级的正确路径是包管理器**：`npm i -g @xinhe-oa/cli@latest`。
+ *    自己替换一个由 npm 管理的文件树里的入口脚本，会把 npm 的账本
+ *    （`package.json` 版本、`node_modules` 记录）与实际内容弄不一致 ——
+ *    下一次 `npm i -g` 的行为就不可预期了。
+ *
+ * 所以 `doctor --upgrade` 的含义变成"**核对并给出升级命令**"：
+ *   * 问 npm registry 当前 latest 是多少（尽力而为，连不上就如实说，不报错）；
+ *   * 与本机版本比一比，给出 `npm i -g …@latest` 或"已经是最新"；
+ *   * **一个字节都不写**，"自己"永远不动（`current_binary_touched: false`）。
+ *
+ * `--out <路径>` 保留原义：把**服务端当前发布的那份产物**写到那个路径
+ * （核对 sha256 / 装到别处 / 排障用），同样不动当前可执行文件。
+ */
+async function npmUpgradePlan(runtime) {
+  const registry = process.env.XINHE_OA_NPM_REGISTRY ?? 'https://registry.npmjs.org';
+  const packageName = process.env.XINHE_OA_NPM_PACKAGE ?? PACKAGE_NAME;
+  const queried = await queryNpmLatest(registry, packageName);
+
+  const to = typeof queried.version === 'string' ? queried.version : VERSION;
+  const newer = isNewerVersion(to, VERSION);
+  const installCommand = `npm i -g ${packageName}@latest`;
+
+  let nextStep;
+  if (queried.error !== null) {
+    nextStep = `问不到 npm registry（${queried.error}）；升级仍然只有一条路：${installCommand}`;
+  } else if (newer) {
+    nextStep = `有新版本：${installCommand}（装完重开终端，用 xinhe-oa-cli --version 核对）`;
+  } else {
+    nextStep = '已经是最新，什么都不用做';
+  }
+
+  return {
+    from: VERSION,
+    to,
+    path: null,
+    target: 'npm',
+    replaced: false,
+    installedElsewhere: false,
+    dryRun: runtime.dryRun,
+    staleRemoved: false,
+    bytes: 0,
+    sha256: '',
+    npm: {
+      package: packageName,
+      registry,
+      latest_version: queried.version,
+      latest_is_newer: newer,
+      command: installCommand,
+      error: queried.error,
+    },
+    next_step: nextStep,
+  };
+}
+
+/** 问一次 npm registry 的 `latest`。**尽力而为**：问不到就回 `error`，不抛。 */
+async function queryNpmLatest(registry, packageName) {
+  const base = String(registry).replace(/\/+$/, '');
+  // 只把**包名里有歧义的字符**处理一下，**不能**把 `/` 编码成 `%2F`：
+  // npm registry 的 scoped 包路径就是 `/@scope/name/latest`，
+  // 编码成 `/@scope%2Fname/latest` 在真 registry 与内网源上都不认。
+  const url = `${base}/${packageName}/latest`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10_000);
+  if (typeof timer.unref === 'function') timer.unref();
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/json', 'user-agent': USER_AGENT },
+    });
+    if (!response.ok) {
+      return { version: null, error: `HTTP ${response.status}` };
+    }
+    const body = await response.json();
+    const version = typeof body?.version === 'string' ? body.version : null;
+    return version === null
+      ? { version: null, error: '响应里没有 version' }
+      : { version, error: null };
+  } catch (err) {
+    return { version: null, error: err?.name === 'AbortError' ? '超时' : String(err?.message ?? err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 语义化版本比较（只回答"a 比 b 新吗"；号段非法时按"不比"处理，宁可说已经是最新）。 */
+export function isNewerVersion(candidate, current) {
+  const parse = (text) =>
+    String(text)
+      .split('-')[0]
+      .split('.')
+      .map((part) => Number.parseInt(part, 10));
+  const a = parse(candidate);
+  const b = parse(current);
+  if (a.length === 0 || b.length === 0) return false;
+  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return false;
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const left = a[i] ?? 0;
+    const right = b[i] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return false;
+}
+
+/**
+ * 落盘前的**内容嗅探**：这份字节像不像一个 Node 入口脚本。
+ *
+ * sha256 管的是"传输有没有坏"，这一道管的是"**它是不是能当我自己的东西**"。
+ * 产物通道的内容换过一次（Rust 二进制 → Node 入口脚本，见
+ * `cli-node/scripts/download-entry.template.js`），而两种内容共用同一组平台键：
+ * 把 ELF 写进入口位置不会报任何错 —— 只会在下次启动时变成一个再也跑不起来的文件。
+ * 宁可拒绝落盘并说清楚。
+ */
+export function assertLooksLikeJavaScript(target, bytes) {
+  const head = bytes.subarray(0, 2).toString('utf8');
+  if (head === '#!') return;
+  const ascii = bytes.subarray(0, 4).toString('hex');
+  const kind =
+    ascii === '7f454c46'
+      ? 'ELF（Linux 可执行文件）'
+      : ascii.startsWith('4d5a')
+        ? 'PE（Windows 可执行文件）'
+        : '不是以 #! 开头的文本';
+  throw new CliError(
+    Kind.Server,
+    'cli.artifact_not_javascript',
+    `服务端发布的那份产物不是 Node 入口脚本（${kind}），拒绝写到 ${target}`,
+  ).withHint(
+    '这多半是服务端还没切到 Node 入口（或有人把 Rust 产物归集回了 dist/cli）；' +
+      '升级改用 npm：npm i -g @xinhe-oa/cli@latest',
+  );
+}
+
+/** `doctor`（含 `--upgrade`）。 */
+export async function handleDoctor({ args, runtime }) {
+  // `--out` 只有跟着 `--upgrade` 才有意义（Rust 侧是 clap 的 `requires = "upgrade"`）。
+  // 这道闸门必须在**任何网络请求之前**：Rust 是解析期判死（本地退出码 2、一个请求都不发）。
+  const wantsUpgrade = flagOn(args, '--upgrade');
+  const outPath = flagValue(args, '--out');
+  if (outPath !== null && !wantsUpgrade) {
+    throw CliError.usage('`doctor --out` 要配合 `--upgrade` 一起用').withHint(
+      '它只把服务端当前发布的那份产物写到指定路径：xinhe-oa-cli doctor --upgrade --out <路径>',
+    );
+  }
+
+  const problems = [];
+  const nextSteps = [];
+
+  // ---- 出网路径（代理判定是客户机器上最常见的坑）----
+  // 真的建一个 Http：代理判定与超时从"将要发请求的那个对象"上读，
+  // 而不是在 doctor 里再算一遍（两处各算一次必然漂移）。
+  let transport;
+  try {
+    const http = runtime.anonymousHttp();
+    const decision =
+      http.proxyPlan() === ProxyPlan.DirectLoopback
+        ? 'direct_loopback'
+        : http.proxyPlan() === ProxyPlan.System
+          ? 'system_proxy'
+          : 'direct_by_config';
+    transport = {
+      base_url: http.baseUrl,
+      device_id_present: http.deviceId.length > 0,
+      proxy_config: runtime.proxy,
+      proxy_decision: decision,
+      explanation: runtime.proxyDescription(),
+      request_timeout_seconds: Math.floor(http.timeout() / 1000),
+      user_agent: USER_AGENT,
+      note: '本机与内网地址永远直连：中间隔代理去连 127.0.0.1 必然连不上',
+    };
+  } catch (err) {
+    // 没有可用的 base_url：把 `anonymous_http()` 的报错原样记进报告（`cli.usage`），
+    // 而不是在这里另造一句话 —— 两处措辞不一致时，用户会以为是两个毛病。
+    transport = {
+      base_url: runtime.baseUrl ?? null,
+      proxy_config: runtime.proxy,
+      error: errorSummary(err),
+      note: '还没有可用的 base_url，所以判定不出出网路径',
+    };
+  }
+
+  // ---- 版本 ----
+  const version = {
+    cli_version: VERSION,
+    user_agent: USER_AGENT,
+    version_header: VERSION_HEADER,
+    note: 'UA 里刻意不带版本号：带上的话用户一升级就会被 auth.device_mismatch 踢下线',
+  };
+
+  // ---- 配置 ----
+  const configDir = runtime.paths.dir;
+  const dirMode = modeString(configDir);
+  const credentialsModeRaw = runtime.credentials.fileMode();
+  const credentialsMode = credentialsModeRaw === null ? null : credentialsModeRaw.toString(8);
+  if (credentialsMode !== null && credentialsMode !== '600') {
+    problems.push({
+      what: '凭据文件权限太松',
+      detail: `${runtime.paths.credentialsFile} 是 ${credentialsMode}，应当是 600`,
+      how_to_fix:
+        'chmod 600 ~/.config/xinhe-oa-cli/credentials.json（CLI 下次写凭据时也会自动收紧）',
+    });
+  }
+  if (dirMode !== null && dirMode !== '700') {
+    problems.push({
+      what: '配置目录权限太松',
+      detail: `${configDir} 是 ${dirMode}，应当是 700`,
+      how_to_fix: 'chmod 700 ~/.config/xinhe-oa-cli',
+    });
+  }
+  const config = {
+    profile: runtime.profile,
+    base_url: runtime.baseUrl ?? null,
+    proxy_config: runtime.proxy,
+    proxy_effective: runtime.proxyDescription(),
+    config_dir: configDir,
+    config_dir_mode: dirMode,
+    config_file: runtime.paths.configFile,
+    credentials_file: runtime.paths.credentialsFile,
+    credentials_file_mode: credentialsMode,
+    env_overrides: {
+      XINHE_OA_CONFIG_DIR:
+        typeof process.env.XINHE_OA_CONFIG_DIR === 'string' ? process.env.XINHE_OA_CONFIG_DIR : null,
+      XINHE_OA_BASE_URL:
+        typeof process.env.XINHE_OA_BASE_URL === 'string' ? process.env.XINHE_OA_BASE_URL : null,
+      XINHE_OA_PROXY:
+        typeof process.env.XINHE_OA_PROXY === 'string' ? process.env.XINHE_OA_PROXY : null,
+    },
+  };
+  if (runtime.baseUrl === null || runtime.baseUrl === undefined) {
+    problems.push({
+      what: '还没配置后端地址',
+      how_to_fix: 'xinhe-oa-cli config --set base_url=http://127.0.0.1:8102',
+    });
+    nextSteps.push('xinhe-oa-cli config --set base_url=<后端地址>');
+  }
+
+  // ---- 凭据与设备指纹 ----
+  const credential = runtime.credentials.get(runtime.profile);
+  let credentials;
+  let device;
+  if (credential !== null) {
+    const accessToken = typeof credential.tokens?.access_token === 'string' ? credential.tokens.access_token : '';
+    const refreshToken = typeof credential.tokens?.refresh_token === 'string' ? credential.tokens.refresh_token : '';
+    const deviceId = typeof credential.device_id === 'string' ? credential.device_id : '';
+    const hasAccess = accessToken.length > 0;
+    const hasRefresh = refreshToken.length > 0;
+    if (!hasAccess && !hasRefresh) {
+      problems.push({
+        what: '凭据文件存在但没有令牌',
+        how_to_fix: 'xinhe-oa-cli login --phone <手机号>',
+      });
+    }
+    const expired = refreshExpired(credential);
+    if (expired) {
+      problems.push({
+        what: 'refresh 已过期',
+        how_to_fix: loginHint(typeof credential.phone === 'string' ? credential.phone : null),
+      });
+      nextSteps.push('xinhe-oa-cli login --phone <手机号>');
+    }
+    credentials = {
+      present: true,
+      has_access_token: hasAccess,
+      has_refresh_token: hasRefresh,
+      access_token: maskToken(accessToken),
+      refresh_token: maskToken(refreshToken),
+      access_expires_at:
+        typeof credential.tokens?.access_expires_at === 'string'
+          ? credential.tokens.access_expires_at
+          : null,
+      refresh_expires_at:
+        typeof credential.tokens?.refresh_expires_at === 'string'
+          ? credential.tokens.refresh_expires_at
+          : null,
+      refresh_expired: expired,
+      needs_refresh: accessNeedsRefresh(credential),
+      user: credential.user ?? null,
+      updated_at: typeof credential.updated_at === 'string' ? credential.updated_at : null,
+      note: '令牌只在这里以掩码出现；argv 与日志里搜不到',
+    };
+    device = {
+      device_id: deviceId,
+      stable: deviceId.length > 0,
+      tokens_empty: !hasAccess && !hasRefresh,
+      note: '每个请求都带 X-Device-Id；服务端把 refresh 绑在 HMAC(UA + X-Device-Id) 上',
+    };
+  } else {
+    if (runtime.baseUrl !== null && runtime.baseUrl !== undefined) {
+      nextSteps.push('xinhe-oa-cli login --phone <手机号>');
+    }
+    credentials = { present: false, how_to_fix: 'xinhe-oa-cli login --phone <手机号>' };
+    device = { device_id: null, note: '还没有设备指纹：首次 login 时生成并持久化' };
+  }
+
+  // ---- 磁盘 ----
+  // 注意这里查的是"配置目录（或其父目录）在不在"，不是真的写一次 ——
+  // 与 Rust 同口径：凭据文件读不出来（坏 JSON）也算不可写，因为登录时同样落不了盘。
+  let writable = false;
+  try {
+    CredentialStore.load(runtime.paths);
+    const parent = parentPath(configDir);
+    writable = fs.existsSync(configDir) || (parent !== null && fs.existsSync(parent));
+  } catch {
+    writable = false;
+  }
+  const disk = {
+    config_dir_writable: writable,
+    note: '配置目录需要可写（登录要落凭据）',
+  };
+  if (!writable) {
+    problems.push({
+      what: '配置目录不可写',
+      detail: configDir,
+      how_to_fix: '检查目录权限，或用 XINHE_OA_CONFIG_DIR=<可写目录> 换一个位置',
+    });
+  }
+
+  // ---- 连通性（`--probe` 在 Rust 里默认就是 true，所以有 base_url 就一定探一次）----
+  let network = { probed: false };
+  let server = {};
+  if (runtime.baseUrl !== null && runtime.baseUrl !== undefined) {
+    try {
+      const body = await keepAlive(() => probeHealth(runtime));
+      const health = isPlainObject(body) ? body : {};
+      // 与 Rust 的 `.and_then(Value::as_str).unwrap_or("unknown")` 同口径：
+      // 只有"字段不是字符串"才退成 unknown（空串原样留着）。
+      const serverVersion = typeof health.version === 'string' ? health.version : 'unknown';
+      const ok = health.ok === true;
+      server = {
+        reachable: true,
+        version: serverVersion,
+        ok,
+        degraded: health.degraded ?? null,
+        degraded_reasons: health.degraded_reasons ?? null,
+        env: health.env ?? null,
+      };
+      network = {
+        probed: true,
+        reachable: true,
+        target: runtime.baseUrl,
+        proxy_effective: runtime.proxyDescription(),
+      };
+      if (!ok) {
+        problems.push({
+          what: '服务端自报 not ok',
+          detail: health.degraded_reasons ?? null,
+          how_to_fix: '把 request_id 与 /health 的输出给运维',
+        });
+      }
+    } catch (err) {
+      const failure = errorSummary(err);
+      network = {
+        probed: true,
+        reachable: false,
+        target: runtime.baseUrl,
+        proxy_effective: runtime.proxyDescription(),
+        error: failure,
+      };
+      const hint = typeof err?.hint === 'string' && err.hint.length > 0 ? err.hint : null;
+      problems.push({
+        what: '连不上服务端',
+        detail: failure.message,
+        how_to_fix: hint ?? '检查 base_url 与服务端进程',
+      });
+      if (hint !== null) nextSteps.push(hint);
+    }
+  }
+
+  // ---- 版本协商（#71 的 `/cli/latest`）----
+  //
+  // 服务端的**最小版本门禁只挂在 `/cli/latest` 上**（业务接口不挂：能力与数据范围
+  // 问一次服务端的发布信息 —— 但**只作为诊断**，不再当作"我该不该升级"的依据。
+  //
+  // 为什么还留着：`release` 段能回答"这台机器要装客户端的话，服务端有没有产物"，
+  // 运维与排障需要它（`doctor` 的定位就是自检报告）。
+  //
+  // 为什么不再当升级依据：那个端点回答的是"该装哪个 **Rust** 产物"。
+  // Node 版升级走 npm，两套版本号不是一回事 —— 拿它判断会得出误导性结论
+  // （"服务端是 0.1.7、你是 0.2.0"会被读成"有新版"）。
+  // 更要紧的是：服务端的版本闸会对旧客户端回 426，而它的指引是重跑 install.sh
+  // （装的是 Rust 版）—— 对 Node 用户那是死路。所以这里**不抛 8**，
+  // 只把"服务端觉得该升级了"如实记进 `release`，升级指引由 npm 那条路给。
+  let release = { probed: false };
+  if (runtime.baseUrl !== null && runtime.baseUrl !== undefined) {
+    let body = null;
+    let failure = null;
+    try {
+      body = await keepAlive(() => fetchLatestRelease(runtime));
+    } catch (err) {
+      failure = err;
+    }
+
+    if (failure === null) {
+      const info = isPlainObject(body) ? body : {};
+      release = {
+        probed: true,
+        latest_version: typeof info.version === 'string' ? info.version : 'unknown',
+        min_supported_version:
+          typeof info.min_supported_version === 'string' ? info.min_supported_version : 'unknown',
+        artifact_present: typeof info.artifact_present === 'boolean' ? info.artifact_present : null,
+        platforms: info.platforms ?? null,
+        install_script_url: info.install_script_url ?? null,
+        notes: info.notes ?? null,
+        problems: info.problems ?? null,
+      };
+      if (info.artifact_present === false) {
+        // 没发布产物不是错误（"只跑服务端"是最常见的部署形态），但要报出来。
+        // 产物通道对 Node 版只影响"下载入口脚本 / --out 核对"，**不影响升级**（那走 npm），
+        // 所以这句只说清怎么补上，不说"去升级"。
+        nextSteps.push(
+          '服务端还没发布 CLI 入口脚本；运维执行 bash cli-node/scripts/publish-download-artifact.sh 归集后即可下载',
+        );
+      }
+    } else if (failure?.exitCode === EXIT_TOO_OLD) {
+      // 服务端认为这个客户端太旧。**对 Node 版这不是退出码 8**：那条指引会让人
+      // 去重跑安装脚本（装回来的是 Rust 版），而 Node 版的升级只有 npm 一条路。
+      release = {
+        probed: true,
+        error: errorSummary(failure),
+        note: '服务端认为该升级了；Node 版升级走 npm：xinhe-oa-cli doctor --upgrade',
+      };
+      nextSteps.push('升级客户端：npm i -g @xinhe-oa/cli@latest（服务端的安装脚本装的是 Rust 版）');
+    } else {
+      release = {
+        probed: true,
+        error: errorSummary(failure),
+        note: '问不到服务端发布的版本；不影响其它检查',
+      };
+    }
+  }
+
+  // `--upgrade` 的结果（不升级时是 null）。放进报告而不是只打一行日志 ——
+  // 复盘时要能回答"当时服务端发布的是哪个版本、换了没有"。
+  let upgrade = null;
+  if (wantsUpgrade) {
+    // 真的自更新（不是打印一句"去跑 install.sh"）：三种落法必须分得清 ——
+    //   * 默认 → 替换**当前这个可执行文件**（`bin/xinhe-oa-cli.js`）；
+    //   * `--out <路径>` → 只把产物写到那个路径，当前可执行文件不动；
+    //   * `--dry-run` → 升级动作本身只问一次 `/cli/latest`，不下载、不写任何文件。
+    try {
+      const outcome = await performUpgrade(runtime, outPath);
+      nextSteps.push(outcomeNextStep(outcome));
+      upgrade = outcomeJson(outcome);
+      if (upgrade.current_binary_touched) {
+        nextSteps.push(
+          '旧版本留在同名 `.old`（Windows 上运行中的文件删不掉），下次启动会自动清理',
+        );
+      }
+    } catch (err) {
+      // 升级失败**不影响别的自检结论** —— 把错误如实放进报告（`replaced` 也不会出现
+      // "成功"的形状），而不是整体失败（见文件头第 4 条）。
+      upgrade = { probed: true, error: errorSummary(err) };
+      nextSteps.push(
+        typeof err?.hint === 'string' && err.hint.length > 0
+          ? err.hint
+          : '升级失败：没有替换任何文件，当前版本照常可用',
+      );
+    }
+  }
+  nextSteps.push('xinhe-oa-cli schema           看全部命令面');
+  nextSteps.push('xinhe-oa-cli me --json        我是谁、能做什么、缺什么权限');
+
+  const data = {
+    ok: problems.length === 0,
+    cli_version: VERSION,
+    version,
+    config,
+    transport,
+    credentials,
+    device,
+    network,
+    server,
+    release,
+    upgrade,
+    disk,
+    embedded_skills: EMBEDDED_SKILLS,
+    problems,
+    next_steps: nextSteps,
+    phone_masked: phoneMasked(runtime),
+  };
+  const requestId = null;
+  const serverVersion = typeof server.version === 'string' ? server.version : null;
+
+  // 人类可读面（`--json` 一个字节都不变）：**自更新的结论必须看得见**。
+  //
+  // 通用表格渲染只会挑第一个"对象数组"字段（doctor 里是 `problems`），
+  // `upgrade` 与 `next_steps` 会被整段吞掉 —— 于是 `doctor --upgrade` 在默认输出下只剩
+  // 一行 `cli_version=…`，"到底动没动这台机器 / 产物写到哪了"一个字都不说。
+  // 实测就有人因此以为 `--out` 没生效、而本体其实已经被换掉。
+  //
+  // 渲染前先按字典序排一遍键（`sortKeysDeep`）：Rust 的 `data` 是 BTreeMap，
+  // 它的 `render_human` 读到的顶层标量本来就是排好序的（`cli_version / embedded_skills /
+  // ok / phone_masked`），不排的话 Node 会按**插入序**印（`ok / cli_version / …`）——
+  // 内容一样、顺序不同，对拍时全是噪声。
+  let human = renderHuman(sortKeysDeep(data), runtime.markdown);
+  if (upgrade !== null && typeof upgrade.next_step === 'string') {
+    human += `\n自更新：${upgrade.next_step}`;
+  }
+  runtime.finishFromWithHuman({ request_id: requestId, server_version: serverVersion }, data, human);
+}
+
+/** `phone_masked`（配置里没存手机号时是 null，不是 `****`）。 */
+function phoneMasked(runtime) {
+  const phone = runtime.config.profile(runtime.profile).phone;
+  return typeof phone === 'string' ? maskPhone(phone) : null;
+}