@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/dsh-upgrade.mjs

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+/**
+ * dsh 版本快照锁定升级器（支持 rc.6 嵌套布局与 0.1.1+ flat-scope 布局）
+ *
+ * 用法:
+ *   node scripts/dsh-upgrade.mjs <目标版本> [--snapshot <快照文件>]
+ *        [--scope-dir <@deepseek-ai 目录>] [--global-bin <dsh 软链路径>]
+ *        （不传则自动探测：npm root -g → homebrew → ~/node；客户机务必确认探测结果）
+ *
+ * 只读自检:
+ *   node scripts/dsh-upgrade.mjs <目标版本> --print-snapshot
+ *        打印快照的**真实落点**与档位（根 / candidate）后立即退出，不改任何状态、不联网。
+ *
+ * 流程:
+ *   1. 预下载 tarball（离线安装）
+ *   2. 备份当前全局 @deepseek-ai scope → /tmp/dsh-backup-<日期>
+ *   3. 临时目录本地 npm install（file: tarball + overrides 快照，绝不 npm install -g）
+ *   4. 校验 @deepseek-ai 子包版本分布 == 快照
+ *   5. 替换全局（flat-scope: 整个 /opt/homebrew/lib/node_modules/@deepseek-ai/；
+ *      nested: 仅主包 dsh/）+ 重建 bin 符号链接
+ *   6. 验证 dsh --version / 断链 / 页面 200
+ *   7. 失败自动回滚备份
+ *
+ * 注意: 本脚本不重启 dsh web 服务（重启需用户手动 launchctl kickstart）。
+ */
+import { execSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, cpSync, readdirSync, symlinkSync, unlinkSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveDshScopeDir, resolveDshBin } from "./lib/dsh-scope.mjs";
+import { locateSnapshot } from "./lib/dsh-snapshot-path.mjs";
+import { relocatePatchTarget } from "./lib/patch-target.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = join(__dirname, "..");
+const LOCK_DIR = join(REPO, "dsh-version-lock");
+// 2026-09-18：scope/bin 路径**不再写死 homebrew** —— 客户机的 dsh 装在
+// `~/node/lib/node_modules`（node 官方包，无 homebrew）⇒ 写死会让升级脚本在客户机直接失效。
+// 取值优先级：命令行 --scope-dir/--global-bin → 环境变量 DSH_SCOPE/DSH_BIN → 自动探测 → homebrew 兜底。
+// 2026-09-28：解析逻辑收敛到 scripts/lib/dsh-scope.mjs（唯一真源，含命令行/环境变量/
+// npm root -g 自动探测三级优先级）——此前 4 个脚本各写一份，客户机上各自失效。
+// ── --scope-dir / --global-bin：把命令行覆盖**落到环境变量**再解析 ─────────────
+// 脚本头部与《客户机部署与上线.md》一直宣称支持这两个旗标（且客户机升级那一步就靠它们
+// 指定"装到哪棵树、重建哪个 bin 链接"），但此前**并未解析** ⇒ 传了会被静默忽略，
+// 实际作用到自动探测出的全局 scope 上。这是最危险的一类偏差（意图与落点不一致），故在
+// 解析 SCOPE_DIR/GLOBAL_BIN **之前**先落地。（DSH_SCOPE/DSH_BIN 仍可用，优先级：命令行 > 环境变量 > 探测）
+{
+  const _scopeArg = process.argv.indexOf("--scope-dir");
+  const _binArg = process.argv.indexOf("--global-bin");
+  if (_scopeArg > -1 && process.argv[_scopeArg + 1]) process.env.DSH_SCOPE = process.argv[_scopeArg + 1];
+  if (_binArg > -1 && process.argv[_binArg + 1]) process.env.DSH_BIN = process.argv[_binArg + 1];
+}
+
+const PROFILES = join(process.env.HOME || "", ".dsh", "profiles");
+
+const target = process.argv[2];
+const snapArgIdx = process.argv.indexOf("--snapshot");
+const snapshotFile = snapArgIdx > -1 ? process.argv[snapArgIdx + 1] : null;
+const fromDirIdx = process.argv.indexOf("--from-dir");
+const patchesOnly = process.argv.includes("--patches-only");
+// ── P5（2026-09-29）：三段式升级（用户批准的 D6/D7）────────────────
+//   --stage <root>    ：装到**旁路树**（`<root>/lib/node_modules/@deepseek-ai`）+ 在那棵树上跑门禁，
+//                       **不碰全局 scope、不重建全局 bin、不重启**；
+//   --activate <root> ：只改**指针**（可选同时重指全局 bin 以兼容尚未切包装脚本的 plist）+ 打印重启指引；
+//   --rollback        ：指针回到审计里的上一棵 known-good 树（同样只改链接，不重启）。
+// 升级/回滚**永远不自己重启服务**（AGENTS.md「严禁自杀式重启」），重启交给人或熔断。
+const stageIdx = process.argv.indexOf("--stage");
+const STAGE_ROOT = stageIdx > -1 ? process.argv[stageIdx + 1] : null;
+const activateIdx = process.argv.indexOf("--activate");
+const ACTIVATE_ROOT = activateIdx > -1 ? process.argv[activateIdx + 1] : null;
+const ROLLBACK = process.argv.includes("--rollback");
+const verifyIdx = process.argv.indexOf("--verify");
+const VERIFY_ROOT = verifyIdx > -1 ? process.argv[verifyIdx + 1] : null;
+const NO_BIN_LINK = process.argv.includes("--no-bin-link");
+
+const fromDir = fromDirIdx > -1 ? process.argv[fromDirIdx + 1] : null;
+
+if (!target) {
+  console.error("用法: node scripts/dsh-upgrade.mjs <目标版本> [--snapshot <快照文件>] [--from-dir <已装目录>]");
+  console.error("  --from-dir: 复用现成安装目录（含 node_modules），跳过 npm install（推荐——file:+overrides 组合在 npm 下可能极慢/卡死，2026-08-21 实测）");
+  process.exit(1);
+}
+
+const run = (cmd, opts = {}) =>
+  execSync(cmd, { stdio: opts.silent ? "pipe" : "inherit", encoding: "utf8", ...opts });
+
+const ok = (m) => console.log("  ✅ " + m);
+const warn = (m) => console.log("  ⚠️  " + m);
+const fail = (m) => { console.error("  ❌ " + m); process.exit(1); };
+
+// ── 目标 scope / 被测 dsh 解析（P1-3b 2026-10-12）───────────────────────────────
+// **真源** = `lib/dsh-scope.mjs#resolveDshScopeDir()`（**npx 感知**：`npm root -g` → PATH 上的 dsh →
+// HOME 相对（邻居→标准）→ 当前 node 前缀 → **npx 缓存**（`~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）
+// → homebrew / Intel 绝对兜底；⛔ 探不到 ⇒ **null**）。
+// **显式入参路径**（本脚本原有，语义未变）：`--scope-dir` / `--global-bin` 在上面的块里先落到
+// `DSH_SCOPE`/`DSH_BIN`，真源按「命令行 > 环境变量 > 自动探测」取值 ⇒ 显式仍然最高优先。
+// 为什么必须换掉遗留 `resolveDshScope()`（同一缺陷的第二个入口，2026-10-12 用户 MBP 实测）：
+// 它在"纯 npx 机器"上**静默返回一个不存在的路径**（`/usr/local/lib/node_modules/@deepseek-ai`）
+// ⇒ 本脚本要么在 `[2/7]` 报"全局 scope 不存在"（误导：机器上明明有 dsh）、要么在
+// `--patches-only` 上拿这棵不存在的树去 `relocatePatchTarget`（错误更难读）。
+// ⛔ 放在 `if (!target)` 的用法提示**之后**：`node scripts/dsh-upgrade.mjs`（不带参数）仍只打印用法。
+// 例外：`--print-snapshot` 是**只读自检**（⛔ 不碰 scope、不联网、不改状态）⇒ 它允许 scope 缺席。
+const _scopeResolved = resolveDshScopeDir();
+const SCOPE_OPTIONAL = process.argv.includes("--print-snapshot");
+if (!_scopeResolved && !SCOPE_OPTIONAL) {
+  console.error("  ❌ 解析不到 dsh 的全局 scope：这台机器上找不到任何 @deepseek-ai 农场");
+  console.error("     已按序试过：`--scope-dir`/`DSH_SCOPE` → `--global-bin`/`DSH_BIN` 反推 → `npm root -g` → " +
+    "PATH 上的 dsh → HOME 相对布局 → 当前 node 前缀 → **npx 缓存（~/.npm/_npx/<hash>/…）** → homebrew / Intel 绝对路径。");
+  console.error("     ⛔ 旧实现会在这里**静默回一个不存在的路径**（实测 `/usr/local/lib/node_modules/@deepseek-ai`）—— 故不静默。");
+  console.error("     出路：① `--scope-dir <…/@deepseek-ai>`；② `DSH_SCOPE=<…>`；③ `--global-bin <该 scope 自带的 dsh>`（由它反推）。");
+  process.exit(1);
+}
+const SCOPE_DIR = _scopeResolved ? _scopeResolved.dir : "";
+const SCOPE_FROM = _scopeResolved ? _scopeResolved.from : "（--print-snapshot 不需要 scope）";
+const GLOBAL_BIN = _scopeResolved ? resolveDshBin({ scopeDir: SCOPE_DIR }) : "";
+if (_scopeResolved) {
+  console.log(`  [scope] ${SCOPE_DIR}（来源：${SCOPE_FROM}）`);
+  if (/_npx[\\/]/.test(SCOPE_DIR)) {
+    warn("目标 scope 在 **npx 缓存**里（npm 自己管的树）：这就是 `npx @deepseek-ai/dsh` 实际在跑的那棵树。");
+    console.log("      · 打补丁（--patches-only）改的就是它 —— 合理；");
+    console.log("      · 整树替换会改动 npm 的缓存条目 —— 官方改法仍是 `npx @deepseek-ai/dsh@<版本>`。");
+  }
+}
+
+/**
+ * 补丁自检清单（**声明式**，2026-10-02）。
+ *
+ * 每个补丁的"真打上了吗 / 上游改动把语义改坏了吗"由同目录的 `verify-*.mjs` 回答；
+ * 这里只登记"跑哪个脚本、通过/失败时说什么"。新增补丁自检 ⇒ 加一行，**不要再改判定逻辑**
+ * （此前两处硬编码 + 三处汇总文案，加一个补丁容易漏改，漏了就是"门禁绿着但补丁没生效"）。
+ * ⚠️ 必须在下面的 `patchesOnly` 块**之前**声明（那块会同步调用 applyHotfixPatches）。
+ */
+const SELF_CHECKS = [
+  {
+    file: "verify-hardening.mjs",
+    label: "加固",
+    pass: "dsh 加固补丁校验通过（render 形状 + append 边界）",
+    fail: "dsh 加固补丁校验**失败** —— 补丁未生效或上游已改动，先别重启！见 AGENTS.md「会话毒化事故」",
+  },
+  {
+    // 打包副本门禁（2026-09-29 worker 事故）：迁移器/校验器在
+    // dsh-session-persistence-jsonl 的 **worker.cjs 打包件**里还有一份内联副本，
+    // 只打 lib/index.js = 离线校验假绿、真实 resume 照旧失败（session-06732069）。
+    file: "verify-bundled-migrators.mjs",
+    label: "打包副本",
+    pass: "打包副本迁移器 hotfix 校验通过（worker.cjs 与模块一致）",
+    fail: "打包副本迁移器 hotfix **失守** —— worker.cjs 未同步，旧会话 resume 会报 stored log is corrupt，先别重启！见 AGENTS.md",
+  },
+  {
+    // TRANSPORT 可诊断性（2026-10-02）：问述代理复用官方 dsh-llm-deepseek 适配器，
+    // 其 TRANSPORT 分支此前只留 message+code ⇒ 事后分不清 ECONNRESET/提前关闭/5xx 断流。
+    file: "verify-transport-diagnostics.mjs",
+    label: "TRANSPORT 可诊断性",
+    pass: "TRANSPORT 诊断补丁校验通过（cause / streamId / 已产出长度可观测，判定语义未变）",
+    fail: "TRANSPORT 诊断补丁**失败** —— 补丁未生效或上游已改动，先别重启！见 scripts/patches/dsh-llm-deepseek--transport-diagnostics.patch 头部说明",
+  },
+];
+
+// --patches-only：只重打补丁 + 加固校验 + 校验旧 session 迁移 + preset 门禁，**不动全局 scope**（升级后/排查时可单独跑）
+if (patchesOnly) {
+  console.log("[patches-only] 仅重打 scripts/patches/*.patch + 加固校验 + 旧 session 迁移校验 + preset 门禁（不替换 scope、不重启）");
+  const r = applyHotfixPatches();
+  const g = runPresetGates();
+  // 自检项由 applyHotfixPatches 内的 SELF_CHECKS 声明（新增一个 verify-*.mjs 只需在那里加一行）
+  const bad = r.migration === false || r.selfChecks.some((c) => c.state === false) || g.schema === false || g.boot === false;
+  const selfText = r.selfChecks.map((c) => `${c.label}=${c.state === undefined ? "跳过" : c.state ? "通过" : "失败"}`).join("、");
+  console.log(`\n[patches-only] 完成：补丁 ok=${r.ok} warn=${r.warn}、${selfText}`
+    + `、迁移校验=${r.migration === null ? "跳过" : r.migration ? "通过" : "失败"}`
+    + `、preset schema=${g.schema === null ? "跳过" : g.schema ? "通过" : "失败"}、启动冒烟=${g.boot === null ? "跳过" : g.boot ? "通过" : "失败"}`);
+  if (bad) console.log("  ⛔ 有门禁未通过 —— 先别重启服务！");
+  process.exit(bad ? 1 : 0);
+}
+
+// ── verify：在**隔离 home** 里对旁路树做真实启动冒烟 + preset 挂载探针 ──────
+// 三段式的中间那一步（评审稿 §6）：stage 装好、activate 之前，先证明"这棵树真能起来"。
+// 复用既有 `plugin-bootcheck.mjs`（隔离 DSH_HOME + 临时端口 + 把真实 .agent-presets 链进去
+// 逐个 preset 真实 mount）——不另造一套判据。
+if (VERIFY_ROOT) {
+  const { looksLikeScope } = await import("./lib/scope-pointer.mjs");
+  const vScope = join(VERIFY_ROOT, "lib", "node_modules", "@deepseek-ai");
+  if (!looksLikeScope(vScope)) fail(`--verify 的目标不是可运行的 dsh 树（需要 <root>/lib/node_modules/@deepseek-ai 布局）：${vScope}`);
+  const vBin = join(VERIFY_ROOT, "bin", "dsh");
+  console.log(`\n[verify] 旁路树：${vScope}`);
+  console.log(`[verify] 版本：${(() => { try { return run(`${JSON.stringify(vBin)} --version`, { silent: true }).trim() || "(无输出)"; } catch (e) { return `取版本失败（${e.status || "?"}）`; } })()}`);
+  console.log("[verify] 隔离启动冒烟 + preset 挂载探针（不碰默认入口、不占线上端口）...");
+  let vCode = 0;
+  try {
+    run(`node ${JSON.stringify(join(REPO, "scripts", "plugin-bootcheck.mjs"))}`, {
+      env: { ...process.env, DSH_SCOPE: vScope, DSH_BIN: existsSync(vBin) ? vBin : undefined },
+    });
+  } catch (e) { vCode = e.status || 1; }
+  if (vCode !== 0) {
+    console.error("\n  ⛔ 旁路树冒烟未通过 ⇒ **不要激活**（默认入口未动；修好或弃用这棵树）");
+    process.exit(1);
+  }
+  ok("旁路树冒烟通过（隔离 home + preset 逐个挂载 OK）");
+  console.log("\n下一步：node scripts/dsh-upgrade.mjs --activate " + VERIFY_ROOT);
+  process.exit(0);
+}
+
+// ── activate / rollback：只改指针与（可选的）全局 bin 链接 ──────
+if (ACTIVATE_ROOT || ROLLBACK) {
+  const { readPointer, writePointer, previousScope, looksLikeScope } = await import("./lib/scope-pointer.mjs");
+  const scopeOf = (root) => join(root, "lib", "node_modules", "@deepseek-ai");
+  let dest;
+  if (ROLLBACK) {
+    const cur = readPointer();
+    dest = previousScope(process.env, cur);
+    if (!dest) fail("审计里找不到可回退的树（用 --activate <root> 显式指定，或 dsh-restore.sh --list 看候选）");
+    console.log(`回退：${cur || "(未设置)"} → ${dest}`);
+  } else {
+    dest = scopeOf(ACTIVATE_ROOT);
+    if (!looksLikeScope(dest)) fail(`目标不是可运行的 dsh 树（需要 <root>/lib/node_modules/@deepseek-ai 布局）：${dest}`);
+    console.log(`激活：${readPointer() || "(未设置)"} → ${dest}`);
+  }
+  const before = readPointer();
+  writePointer(dest, { reason: ROLLBACK ? "dsh-upgrade --rollback" : "dsh-upgrade --activate", previous: before });
+  ok(`指针已写入（审计可查：dsh-restore.sh --list）`);
+  if (!NO_BIN_LINK) {
+    // 兼容期：plist 仍指向全局 bin 时，指针还不够 ⇒ 同时重指 bin（激活包装脚本后可用 --no-bin-link 关掉）
+    const bin = resolveDshBin({ scopeDir: dest });
+    const binEntry = (() => {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dest, "dsh", "package.json"), "utf8"));
+        return pkg.bin ? (typeof pkg.bin === "string" ? pkg.bin : pkg.bin.dsh || Object.values(pkg.bin)[0]) : null;
+      } catch { return null; }
+    })();
+    if (binEntry && existsSync(join(dest, "dsh", binEntry))) {
+      try { unlinkSync(bin); } catch {}
+      symlinkSync(join(dest, "dsh", binEntry), bin);
+      ok(`全局 bin 已重指：${bin} → ${dest}/dsh/${binEntry}（加 --no-bin-link 可跳过）`);
+    } else warn(`未能重指全局 bin（主包无 bin 字段或目标不存在）：${bin}`);
+  }
+  console.log("\n下一步（**不自动重启**）：");
+  console.log("  bash scripts/dsh-restart.sh    # 由你手动重启服务（或让熔断那一次自动重启生效）");
+  console.log("  验收：新/旧会话可开、角色挂载、唤醒链路；不合格 ⇒ node scripts/dsh-upgrade.mjs --rollback");
+  process.exit(0);
+}
+
+// ── 0. 快照与布局 ────────────────────────────────────────────
+// 快照**真实落点**解析（唯一真源在 scripts/lib/dsh-snapshot-path.mjs）：加载与打印共用，
+// 杜绝"打印根目录、实际读 candidate"这种误导排障的偏差（2026-10-12 P1-0 / 审计 §C.1 #8）。
+const snapInfo = locateSnapshot(LOCK_DIR, target, snapshotFile);
+let snapshot = null;
+if (snapInfo.path) { try { snapshot = JSON.parse(readFileSync(snapInfo.path, "utf8")); } catch (e) { fail(`快照解析失败（${snapInfo.path}）: ${e.message}`); } }
+const layout = snapshot?.layout || "nested"; // flat-scope: 0.1.1+（顶层 197 包）；nested: rc.6（主包内嵌）
+/** 快照落点的那一行输出（**加载与打印同一判据**；`--print-snapshot` 复用它）。 */
+function printSnapshotLine() {
+  if (snapshot) ok(`快照: ${snapInfo.path}（${snapInfo.tier}；${Object.keys(snapshot.resolved || {}).length} 个子包）`);
+  else if (target) warn(`快照: 未找到（已找过 ${snapInfo.searched.join(" → ")}）⇒ 本次不做版本分布锁定`);
+}
+// `--print-snapshot`：**只读**自检 —— 打印快照真实落点后立即退出（P1-0 验收用；不改任何状态、不联网）。
+if (process.argv.includes("--print-snapshot")) { printSnapshotLine(); process.exit(0); }
+
+// ── 1. 预下载 tarball ────────────────────────────────────────
+console.log(`\n[1/7] 预下载 @deepseek-ai/dsh@${target} tarball ...`);
+const tarball = join("/tmp", `deepseek-ai-dsh-${target}.tgz`);
+  // `--from-dir` 表示产物已在本地（离线/内网/演练）⇒ 不该也不需联网下载；
+  // 2026-09-29 实测：npm 不可达时这一步会把整条升级卡死在开头。
+  if (fromDir) {
+    ok(`--from-dir 已给（${fromDir}）⇒ 跳过下载`);
+  } else if (!existsSync(tarball)) {
+  run(`cd /tmp && npm pack @deepseek-ai/dsh@${target} --silent`, { silent: true });
+  const found = readdirSync("/tmp").filter((f) => f.startsWith("deepseek-ai-dsh-") && f.endsWith(".tgz"));
+  if (!found.length) fail("tarball 下载失败");
+  const real = join("/tmp", found[found.length - 1]);
+  if (real !== tarball) run(`mv "${real}" "${tarball}"`, { silent: true });
+}
+ok(`tarball: ${tarball}（布局: ${layout}）`);
+if (snapshot || target) printSnapshotLine();
+
+// ── 2. 备份当前全局 scope ────────────────────────────────────
+// 暂存模式（--stage）不动全局 ⇒ 不需要先备份它（dsh-backup-scope.sh 已提供持久备份）。
+if (STAGE_ROOT) {
+  console.log("\n[2/7] --stage：跳过全局备份（本模式不替换全局）");
+} else {
+console.log("\n[2/7] 备份当前全局 @deepseek-ai scope ...");
+if (!existsSync(SCOPE_DIR)) fail(`全局 scope 不存在: ${SCOPE_DIR}`);
+const backupDir = join("/tmp", `dsh-backup-${new Date().toISOString().slice(0, 10)}`);
+mkdirSync(backupDir, { recursive: true });
+const backupScope = join(backupDir, "scope");
+if (existsSync(backupScope)) rmSync(backupScope, { recursive: true, force: true });
+cpSync(SCOPE_DIR, backupScope, { recursive: true, dereference: true });
+ok(`备份: ${backupScope}（含当前 dsh 全树）`);
+}
+
+// ── 3. 本地安装（from-dir 直接复用 / npm install + overrides）──
+console.log("\n[3/7] 本地安装 ...");
+let work;
+let depRoot;
+if (fromDir) {
+  work = fromDir;
+  depRoot = join(work, "node_modules", "@deepseek-ai");
+  if (!existsSync(depRoot)) fail(`--from-dir 缺少 node_modules/@deepseek-ai: ${depRoot}`);
+  ok(`复用已装目录: ${work}（跳过 npm install）`);
+} else {
+  work = join("/tmp", `dsh-install-${target}`);
+  rmSync(work, { recursive: true, force: true });
+  mkdirSync(work, { recursive: true });
+  let pkgJson = { name: "dsh-upgrade-work", private: true, dependencies: { "@deepseek-ai/dsh": `file:${tarball}` } };
+  if (snapshot) {
+    pkgJson.overrides = {};
+    for (const [name, ver] of Object.entries(snapshot.resolved)) {
+      // ⚠️ 主包不能进 overrides：它是 `file:<tgz>` 直接依赖，同时 override 会让 npm 报
+      // `EOVERRIDE ... conflicts with direct dependency`（2026-09-29 实测，升级在替换全局前失败）。
+      if (name === "@deepseek-ai/dsh") { warn("快照里含主包 @deepseek-ai/dsh —— 已跳过其 override（应为生成器 bug）"); continue; }
+      pkgJson.overrides[name] = ver;
+    }
+  }
+  writeFileSync(join(work, "package.json"), JSON.stringify(pkgJson, null, 2));
+  warn("npm install 进行中（file:+overrides 组合可能极慢，2026-08-21 实测卡死过一次；建议改用 --from-dir）...");
+  run(`cd "${work}" && npm install --no-audit --no-fund --loglevel=error`);
+  ok("依赖已安装（本地目录，未触碰全局）");
+}
+
+// ── 4. 校验版本分布 ──────────────────────────────────────────
+console.log("\n[4/7] 校验版本一致性 ...");
+if (!depRoot) {
+  depRoot = layout === "flat-scope"
+    ? join(work, "node_modules", "@deepseek-ai")
+    : join(work, "node_modules", "@deepseek-ai", "dsh", "node_modules", "@deepseek-ai");
+}
+const installed = collectVersions(depRoot);
+if (!installed) fail(`本地安装缺少依赖目录: ${depRoot}`);
+const dist = {};
+for (const ver of Object.values(installed)) dist[ver] = (dist[ver] || 0) + 1;
+console.log("  版本分布:", JSON.stringify(dist));
+if (snapshot) {
+  const mismatches = [];
+  for (const [name, ver] of Object.entries(snapshot.resolved)) {
+    if (installed[name] && installed[name] !== ver) mismatches.push(`${name}: 期望 ${ver} 实际 ${installed[name]}`);
+  }
+  const missing = Object.keys(snapshot.resolved).filter((n) => !installed[n]);
+  if (mismatches.length || missing.length) {
+    warn("快照不匹配:");
+    [...mismatches, ...missing.map((n) => `${n}: 缺失`)].slice(0, 10).forEach((m) => warn("  " + m));
+  } else {
+    ok(`子包版本与快照 ${target} 完全一致（${Object.keys(installed).length} 个）`);
+  }
+} else {
+  warn("未提供快照：安装为 npm 当前解析结果，建议装后生成快照存档");
+}
+
+// ── 5s. 暂存模式：装到旁路树 + 在那棵树上跑门禁（**不动全局、不重启**）──
+if (STAGE_ROOT) {
+  const stageScope = join(STAGE_ROOT, "lib", "node_modules", "@deepseek-ai");
+  console.log(`\n[5s/7] --stage：装到旁路树 ${stageScope}`);
+  if (existsSync(stageScope)) rmSync(stageScope, { recursive: true, force: true });
+  mkdirSync(stageScope, { recursive: true });
+  cpSync(depRoot, stageScope, { recursive: true });
+  // flat-scope 布局下顶层还有非 @deepseek-ai 依赖（js-yaml 等）⇒ 一并放进旁路树
+  // 顶层依赖（flat-scope 布局下 js-yaml 等在 scope 之外）。注意：
+  //  · 源目录可能混着**别的**全局包与**断链**（实测 `/opt/homebrew/lib/node_modules/dsh-rc6-global-install`
+  //    就是断链）—— 直接 cpSync 会 ENOENT 崩掉整条升级 ⇒ 逐个 try/catch，跳过并点名；
+  //  · nested 布局没有顶层依赖可补 ⇒ 不做这一步。
+  if (layout === "flat-scope") {
+    const srcTop = join(work, "node_modules");
+    const destTop = dirname(stageScope);
+    const skipped = [];
+    if (existsSync(srcTop)) {
+      for (const item of readdirSync(srcTop)) {
+        if (item === "@deepseek-ai") continue;
+        const dest = join(destTop, item);
+        if (existsSync(dest)) continue;
+        try { cpSync(join(srcTop, item), dest, { recursive: true }); }
+        catch (e) { skipped.push(`${item}（${(e && e.code) || "ERR"}）`); }
+      }
+    }
+    if (skipped.length) warn(`顶层依赖跳过 ${skipped.length} 项（断链/不可读，不影响 dsh 本体）：${skipped.join("、")}`);
+    else ok("顶层依赖已补齐");
+  }
+  // 自包含入口：<root>/bin/dsh（不需要 sudo、不动全局 bin）
+  const stageBin = join(STAGE_ROOT, "bin", "dsh");
+  mkdirSync(dirname(stageBin), { recursive: true });
+  const stagePkg = JSON.parse(readFileSync(join(stageScope, "dsh", "package.json"), "utf8"));
+  const stageEntry = stagePkg.bin
+    ? (typeof stagePkg.bin === "string" ? stagePkg.bin : stagePkg.bin.dsh || Object.values(stagePkg.bin)[0])
+    : "lib/bin.js";
+  try { unlinkSync(stageBin); } catch {}
+  symlinkSync(join(stageScope, "dsh", stageEntry), stageBin);
+  ok(`旁路树就绪（入口 ${stageBin}）`);
+
+  // 门禁**在那棵树上**跑：共享解析器认 DSH_SCOPE/DSH_BIN（复用 --patches-only 的全部判据）
+  console.log("\n[6s/7] 在旁路树上重打 hotfix 补丁 + 跑六项门禁（隔离，不碰全局）...");
+  let gateCode = 0;
+  try {
+    run(`node ${JSON.stringify(join(REPO, "scripts", "dsh-upgrade.mjs"))} --patches-only`, {
+      env: { ...process.env, DSH_SCOPE: stageScope, DSH_BIN: stageBin },
+    });
+  } catch (e) { gateCode = e.status || 1; }
+  if (gateCode !== 0) {
+    console.error("\n  ⛔ 旁路树门禁未通过 ⇒ **不要激活**（默认入口完全没动，删掉旁路树即可）");
+    console.error(`     看详情：node scripts/dsh-upgrade.mjs --patches-only   # 带 DSH_SCOPE=${stageScope}`);
+    process.exit(1);
+  }
+  ok("旁路树门禁全绿");
+  console.log("\n下一步（三段式的后两步，**都不自动重启**）：");
+  console.log(`  ① 真实形态冒烟（可选）：用克隆的 home 在旁路树上起一次隔离实例`);
+  console.log(`  ② 激活：node scripts/dsh-upgrade.mjs --activate ${STAGE_ROOT}`);
+  console.log(`     回退：node scripts/dsh-upgrade.mjs --rollback`);
+  process.exit(0);
+}
+
+// ── 5. 替换全局 scope ────────────────────────────────────────
+console.log("\n[5/7] 替换全局 scope ...");
+rmSync(SCOPE_DIR, { recursive: true, force: true });
+mkdirSync(SCOPE_DIR, { recursive: true });
+if (layout === "flat-scope") {
+  // 0.1.1+：顶层扁平 → 整个 scope 全部替换（197 包）
+  cpSync(depRoot, SCOPE_DIR, { recursive: true });
+  // 顶层非 scope 依赖（js-yaml 等）→ 补到全局顶层，跳过已存在（保护用户其他全局包）
+  const srcTop = join(work, "node_modules");
+  const destTop = dirname(SCOPE_DIR);
+  for (const item of readdirSync(srcTop)) {
+    const src = join(srcTop, item);
+    const dest = join(destTop, item);
+    if (item === "@deepseek-ai") continue;
+    if (!existsSync(dest)) cpSync(src, dest, { recursive: true });
+  }
+  ok("顶层依赖已补齐（跳过已存在的用户全局包）");
+} else {
+  // rc.6：只主包，嵌套子包随主包带入
+  cpSync(join(work, "node_modules", "@deepseek-ai", "dsh"), join(SCOPE_DIR, "dsh"), { recursive: true });
+}
+// 重建 bin 链接（从主包 package.json 的 bin 字段解析）
+try { unlinkSync(GLOBAL_BIN); } catch {}
+const mainPkg = JSON.parse(readFileSync(join(SCOPE_DIR, "dsh", "package.json"), "utf8"));
+const binEntry = mainPkg.bin && (typeof mainPkg.bin === "string" ? mainPkg.bin : mainPkg.bin.dsh || Object.values(mainPkg.bin)[0]);
+if (binEntry) {
+  const binTarget = join(SCOPE_DIR, "dsh", binEntry);
+  if (existsSync(binTarget)) {
+    symlinkSync(binTarget, GLOBAL_BIN);
+    ok(`bin 链接: ${GLOBAL_BIN} → ${binTarget}`);
+  } else warn(`bin 目标不存在: ${binTarget}`);
+} else warn("主包无 bin 字段，跳过 bin 链接");
+ok("已替换全局，备份保留在 " + backupScope);
+
+// ── 5.5 hotfix 补丁重打 + 旧 session 迁移校验 ────────────────
+// 2026-09-10 教训：升级整树替换 scope ⇒ 打在包内的 hotfix 会被**静默冲掉**（0.1.5 的
+// session-format v0→v1 漏认 `permission/preset.origin` 曾导致重启后旧 session 无法加载）。
+// 故每次升级后必须重打 patches/ 下的补丁，并对**最旧真实 session** 跑完整迁移链校验。
+console.log("\n[5.5/7] 重打 hotfix 补丁 + 旧 session 迁移校验 + preset 门禁 ...");
+const hotfix = applyHotfixPatches();
+const gates = runPresetGates();
+// ── 6. 验证 ──────────────────────────────────────────────────
+console.log("\n[6/7] 验证 ...");
+try {
+  const v = run("dsh --version", { silent: true }).trim().split("\n")[0];
+  ok(`dsh --version = ${v}`);
+} catch { fail("dsh --version 失败（已回滚，见下）"); }
+const probes = ["dsh-client-ui-primitives", "dsh-client-ui-sidebar", "dsh-client-ui-conversation"];
+for (const p of probes) {
+  if (!existsSync(join(SCOPE_DIR, p))) warn(`全局 scope 缺 ${p}`);
+}
+for (const p of probes) {
+  let found = false;
+  for (const profile of safeProfiles()) {
+    const link = join(PROFILES, profile, "node_modules", "@deepseek-ai", p);
+    if (existsSync(link)) { found = true; break; }
+  }
+  if (!found) warn(`profiles 中未发现 ${p}（重启后如卡加载屏，按 docs 恢复 profiles 依赖）`);
+}
+try {
+  const code = run("curl -s -o /dev/null -w %{http_code} --max-time 10 http://127.0.0.1:3080/", { silent: true }).trim();
+  if (code === "200") ok("页面 200（旧进程仍在跑，属正常）"); else warn(`页面状态码 ${code}`);
+} catch { warn("页面检查失败"); }
+
+// ── 7. 收尾 ──────────────────────────────────────────────────
+console.log("\n[7/7] 完成。");
+console.log("  ✅ 升级成功（未重启服务，旧进程仍用旧代码）");
+const failedSelfChecks = hotfix.selfChecks.filter((c) => c.state === false);
+if (hotfix.migration === false || failedSelfChecks.length > 0 || gates.schema === false || gates.boot === false) {
+  console.log("  ⛔ 门禁未全部通过 —— 先别重启服务！修好下面这些再重启：");
+  for (const c of failedSelfChecks) console.log(`       · 补丁自检失败：${c.label}（node scripts/patches/${c.file} 看详情）`);
+  if (hotfix.migration === false) console.log("       · 旧 session 迁移校验失败（见 AGENTS.md「session 迁移 hotfix」）");
+  if (gates.schema === false) console.log("       · preset schema 门禁失败（node scripts/validate-preset-schema.mjs --runtime）");
+  if (gates.boot === false) console.log("       · 启动冒烟失败（node scripts/plugin-bootcheck.mjs，含 preset 挂载）");
+  console.log("       或回滚（见下方回滚步骤）后再重启");
+}
+console.log("  ⏭  生效：用户手动执行  bash ~/Code/argent-dsh/scripts/dsh-restart.sh");
+console.log("  ⏭  回滚：");
+console.log(`       sudo rm -rf ${SCOPE_DIR}`);
+console.log(`       sudo cp -R ${backupScope} ${SCOPE_DIR}`);
+console.log(`       sudo ln -sfn ${join(SCOPE_DIR, "dsh", binEntry || "lib/bin.js")} ${GLOBAL_BIN}`);
+console.log("       然后重启服务（同上 kickstart 命令）");
+
+// ── helpers ──────────────────────────────────────────────────
+function collectVersions(dir) {
+  if (!existsSync(dir)) return null;
+  const out = {};
+  for (const name of readdirSync(dir)) {
+    const pj = join(dir, name, "package.json");
+    if (existsSync(pj)) {
+      try { out[name] = JSON.parse(readFileSync(pj, "utf8")).version; } catch {}
+    }
+  }
+  return out;
+}
+function safeProfiles() {
+  try {
+    return readdirSync(PROFILES).filter((d) => {
+      try { return statSync(join(PROFILES, d)).isDirectory(); } catch { return false; }
+    });
+  } catch { return []; }
+}
+
+/**
+ * 重打 scripts/patches/*.patch 到全局 scope，并跑各补丁的**自检脚本**（`verify-*.mjs`）
+ * + 最旧真实 session 的迁移链校验。
+ * 返回值：{ ok, warn, selfChecks: [{ file, label, state }], migration }
+ *   selfChecks[].state: true 通过 / false 失败 / undefined 无该脚本
+ *   migration:          true 通过 / false 失败 / null 跳过
+ *
+ * 2026-10-02：自检项从"两处硬编码"改成**声明式清单**（SELF_CHECKS）—— 新增一个补丁自检
+ * 只需在清单里加一行，不必再动这里的判定逻辑（此前每加一个补丁都要改三处汇总文案，
+ * 容易漏、漏了就是"门禁绿着但补丁没生效"）。
+ */
+function applyHotfixPatches() {
+  const out = { ok: 0, warn: 0, selfChecks: [], migration: null };
+  const patchDir = join(REPO, "scripts", "patches");
+  if (!existsSync(patchDir)) { warn(`无补丁目录：${patchDir}`); return out; }
+  for (const pf of readdirSync(patchDir).filter((f) => f.endsWith(".patch"))) {
+    const text = readFileSync(join(patchDir, pf), "utf8");
+    // 版本门（2026-09-29）：补丁可声明 `# requires-dsh: >=0.1.7`。上游在不同版本里
+    // 结构不同——同一个补丁不可能适配两版；不适用的**静默跳过**（不是失败），
+    // 否则门禁常红、训练人忽略真红。
+    const req = /^#\s*requires-dsh:\s*(>=|>)?\s*([0-9][\w.-]*)\s*$/m.exec(text);
+    if (req) {
+      const instVer = JSON.parse(readFileSync(join(SCOPE_DIR, "dsh", "package.json"), "utf8")).version;
+      const okVer = req[1] === ">" ? cmpVerText(instVer, req[2]) > 0 : cmpVerText(instVer, req[2]) >= 0;
+      if (!okVer) { console.log(`  ⏭  跳过补丁 ${pf}（要求 dsh ${req[1] || ">="}${req[2]}，当前 ${instVer}）`); continue; }
+    }
+    const header = ((/^\+\+\+\s+(\S+)/m.exec(text) || [])[1] || "").trim();
+    // 2026-09-28 客户机教训：补丁头里写的是**打补丁那台机器**的绝对路径
+    // （/opt/homebrew/lib/node_modules/@deepseek-ai/...），客户机 dsh 装在
+    // ~/node/lib/node_modules/ ⇒ 直接 existsSync 必然 false，补丁静默跳过。
+    // 正解：按 @deepseek-ai/ 之后的包内相对路径重定位到**当前 scope**（lib/patch-target.mjs）。
+    const target = relocatePatchTarget(header, SCOPE_DIR);
+    if (!target || !existsSync(target)) {
+      warn(`补丁 ${pf}: 目标文件不存在（上游可能已改动）→ ${header || "无法解析"}`);
+      out.warn++;
+      continue;
+    }
+    const r = spawnSync("patch", ["--forward", "--batch", "-i", join(patchDir, pf), target], { encoding: "utf8" });
+    const log = `${r.stdout || ""}${r.stderr || ""}`;
+    if (r.status === 0) { ok(`补丁已重打: ${pf} → ${target.replace(SCOPE_DIR + "/", "")}`); out.ok++; }
+    else if (/previously applied|Reversed \(or previously applied\)|Skipping patch/i.test(log)) { ok(`补丁已是最新（无需重打）: ${pf}`); out.ok++; }
+    else { warn(`补丁应用失败（需人工核对，可能上游已修复）: ${pf} :: ${log.trim().split("\n").pop() || ""}`); out.warn++; }
+  }
+  // 补丁自检（声明式清单）：每个补丁的 `verify-*.mjs` 在这里登记一行即可。
+  // 放在迁移校验**之前**，这样它们不依赖"本机存在 session 文件"这个前提。
+  for (const check of SELF_CHECKS) {
+    const script = join(patchDir, check.file);
+    out.selfChecks.push({ file: check.file, label: check.label, state: undefined });
+    const slot = out.selfChecks[out.selfChecks.length - 1];
+    if (!existsSync(script)) { warn(`缺补丁自检脚本 ${check.file}，跳过「${check.label}」`); continue; }
+    try {
+      run(`node ${script}`, { silent: true });
+      ok(check.pass);
+      slot.state = true;
+    } catch {
+      warn(check.fail);
+      slot.state = false;
+    }
+  }
+  const verify = join(patchDir, "verify-session-migration.mjs");
+  if (existsSync(verify)) {
+    const sessRoot = join(process.env.DSH_HOME || join(process.env.HOME || "", ".dsh"), "sessions");
+    // 抽样本（2026-09-29 修正）：原来只取 `session.jsonl.zstd`（**未版本化=v0**）里最旧的一个
+    // ⇒ v3/v4 一个都没覆盖，而当天真正炸的正是 v3→v4 迁移（门禁全绿、会话照样打不开）。
+    // 现在按"未版本化 / 版本化"两组各取**最新+最旧**，钉住 v0 与 v3/v4 两条迁移链。
+    const samples = [];
+    for (const pattern of ["session.jsonl.zstd", "session.v*.jsonl.zstd"]) {
+      let list = "";
+      try { list = run(`ls -t ${sessRoot}/*/*/${pattern} 2>/dev/null`, { silent: true }).trim(); } catch { /* 无该形态 */ }
+      if (!list) continue;
+      const arr = list.split("\n").map((s) => s.trim()).filter(Boolean);
+      for (const f of [arr[0], arr[arr.length - 1]]) if (f && !samples.includes(f)) samples.push(f);
+    }
+    if (samples.length === 0) { warn("未找到 session 文件，跳过旧 session 迁移校验"); return out; }
+    try {
+      run(`node ${verify} ${samples.join(" ")}`, { silent: true });
+      ok(`旧 session 迁移校验通过（${samples.length} 个样本：v0 与 v3/v4 各最新/最旧）`);
+      out.migration = true;
+    } catch {
+      warn("旧 session 迁移校验**失败** —— 升级后旧会话可能无法加载，先别重启！见 AGENTS.md「0.1.5/0.1.7 session 迁移 hotfix」");
+      out.migration = false;
+    }
+  }
+  return out;
+}
+
+/**
+ * 升级后 preset 门禁：0.1.5 起 preset 挂载失败是**致命**的（旧 session resume 直接报错，
+ * 2026-09-10 事故：persona 行 `text:` 应为 `prefix:`，0.1.1 容忍、0.1.5 拒绝）。
+ * 两项均为**非致命警告**：是否回滚/是否重启由人决定，但必须显式告知"先别重启"。
+ * 返回值：{ schema: true/false/null(跳过), boot: true/false/null }
+ */
+function runPresetGates() {
+  const out = { schema: null, boot: null };
+  const schema = join(REPO, "scripts", "validate-preset-schema.mjs");
+  const boot = join(REPO, "scripts", "plugin-bootcheck.mjs");
+  if (existsSync(schema)) {
+    try { run(`node ${schema} --runtime`, { silent: true }); ok("preset schema 门禁通过（preset 行 config 全部合法）"); out.schema = true; }
+    catch { warn("preset schema 门禁**失败** —— 行 config 不合法，0.1.5 上该 preset 会挂载失败，先别重启！"); out.schema = false; }
+  } else warn("缺 scripts/validate-preset-schema.mjs，跳过 preset schema 门禁");
+  if (existsSync(boot)) {
+    try { run(`node ${boot}`, { silent: true }); ok("启动冒烟通过（隔离 home；含 preset 真实挂载）"); out.boot = true; }
+    catch { warn("启动冒烟**失败** —— 隔离 home 下 dsh 起不来或 preset 挂载失败，先别重启！（node scripts/plugin-bootcheck.mjs 看详情）"); out.boot = false; }
+  } else warn("缺 scripts/plugin-bootcheck.mjs，跳过启动冒烟");
+  return out;
+}