@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/dsh-preflight.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * dsh 升级前变更审查（preflight）——2026-08-21 事故固化
+ *
+ * 用法:
+ *   node scripts/dsh-preflight.mjs <新版本> [--snapshot <快照文件>] [--from-dir <已装目录>]
+ *
+ * 做什么:
+ *   1. 本地安装目标版本（tarball + 快照 overrides，绝不触碰全局）
+ *   2. 依赖结构 diff：与当前全局 @deepseek-ai scope 对比子包清单
+ *      - 新增子包 → 检查主包 dsh-web-app / dsh 是否声明（漏声明 = rc.8 primitives 断链前科）
+ *      - 消失子包 → 引用方是否已迁移
+ *      - 版本变化分布
+ *   3. 关键探针包存在性（profiles 断链检查清单）
+ *   4. 输出 markdown 报告 → /tmp/dsh-preflight-<版本>.md
+ *
+ * 注意: 本脚本只做「本地 + 对比」审查；隔离试跑 + CDP boot 验证 + 品牌补丁
+ *       特征回归见 docs/dsh-version-management.md「升级前变更审查清单」第 2/3 步
+ *       （必须带完整品牌补丁在独立 profile 试跑，不能只跑裸版本）。
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifySubpackages, readScope } from "./lib/dep-declaration.mjs";
+import { requireDshScope } from "./lib/dsh-scope.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = join(__dirname, "..");
+const LOCK_DIR = join(REPO, "dsh-version-lock");
+// 2026-09-28：scope 解析收敛到 scripts/lib/dsh-scope.mjs（客户机 dsh 不在 homebrew 下）。
+// 0.6.0 F1 修复批（2026-10-14）：预检**整篇**都在读这棵树的版本/断链 ⇒ 拿不到 scope 必须**响亮失败**
+// （⛔ 不许拿一个可能不存在的路径继续，那会输出一份"树里什么都没有"的假报告）。
+let SCOPE_DIR;
+try { SCOPE_DIR = requireDshScope({ what: "宿主预检（dsh-preflight）" }); }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1); }
+// profiles 断链探针（rc.8 事故清单；0.1.1 无 primitives 属正常，见报告）
+const LINK_PROBES = ["dsh-client-ui-primitives", "dsh-client-ui-sidebar", "dsh-client-ui-conversation"];
+// 主包（声明依赖关系的关键包，漏声明检测对象）
+const DECLARER_PKGS = ["dsh", "dsh-web-app", "dsh-client-ui-sidebar", "dsh-client-ui-conversation"];
+
+const target = process.argv[2];
+if (!target) {
+  console.error("用法: node scripts/dsh-preflight.mjs <新版本> [--snapshot <快照>] [--from-dir <已装目录>]");
+  process.exit(1);
+}
+const snapArgIdx = process.argv.indexOf("--snapshot");
+const snapshotFile = snapArgIdx > -1 ? process.argv[snapArgIdx + 1] : null;
+const fromDirIdx = process.argv.indexOf("--from-dir");
+const fromDir = fromDirIdx > -1 ? process.argv[fromDirIdx + 1] : null;
+
+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); };
+
+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;
+}
+
+console.log(`\n═══ dsh 升级前审查: ${target} ═══\n`);
+
+// ── 1. 快照 ──────────────────────────────────────────────
+let snapshot = null;
+if (snapshotFile) snapshot = JSON.parse(readFileSync(snapshotFile, "utf8"));
+else {
+  const locked = join(LOCK_DIR, `${target}.json`);
+  if (existsSync(locked)) snapshot = JSON.parse(readFileSync(locked, "utf8"));
+}
+if (snapshot) ok(`快照: ${snapshotFile || join(LOCK_DIR, target + ".json")}（${Object.keys(snapshot.resolved || {}).length} 个子包）`);
+else warn("无快照——若目标版本无快照文件，先按 docs 生成候选快照再审查");
+
+// ── 2. 本地安装 ──────────────────────────────────────────
+console.log("\n[1/4] 本地安装目标版本 ...");
+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}`);
+} else {
+  const tarball = join("/tmp", `deepseek-ai-dsh-${target}.tgz`);
+  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 });
+  }
+  work = join("/tmp", `dsh-preflight-${target}`);
+  rmSync(work, { recursive: true, force: true });
+  mkdirSync(work, { recursive: true });
+  const pkgJson = { name: "dsh-preflight-work", private: true, dependencies: { "@deepseek-ai/dsh": `file:${tarball}` } };
+  if (snapshot) {
+    pkgJson.overrides = {};
+    for (const [name, ver] of Object.entries(snapshot.resolved)) pkgJson.overrides[name] = ver;
+  }
+  writeFileSync(join(work, "package.json"), JSON.stringify(pkgJson, null, 2));
+  warn("npm install 进行中（file:+overrides 组合可能较慢）...");
+  run(`cd "${work}" && npm install --no-audit --no-fund --loglevel=error`);
+  ok("依赖已安装（本地目录）");
+  depRoot = join(work, "node_modules", "@deepseek-ai");
+}
+const newVers = collectVersions(depRoot);
+if (!newVers) fail("本地安装缺少 @deepseek-ai 目录");
+
+// ── 3. 依赖结构 diff ─────────────────────────────────────
+console.log("\n[2/4] 依赖结构 diff（vs 当前全局）...");
+const curVers = collectVersions(SCOPE_DIR);
+if (!curVers) warn("当前全局 scope 不存在，跳过 diff");
+let report = `# dsh 升级前审查报告: ${target}（${new Date().toISOString().slice(0, 16)}）\n\n`;
+if (curVers) {
+  const added = Object.keys(newVers).filter((n) => !curVers[n]);
+  const removed = Object.keys(curVers).filter((n) => !newVers[n]);
+  const changed = Object.keys(newVers).filter((n) => curVers[n] && curVers[n] !== newVers[n]);
+  report += `## 依赖结构 diff\n\n`;
+  if (added.length) report += `**新增子包（${added.length}）**：${added.join(", ")}\n\n`;
+  if (removed.length) report += `**消失子包（${removed.length}）**：${removed.join(", ")}\n\n`;
+  if (changed.length) {
+    report += `**版本变化（${changed.length}）**：\n\n`;
+    for (const n of changed) report += `- ${n}: ${curVers[n]} → ${newVers[n]}\n`;
+    report += "\n";
+  }
+  if (!added.length && !removed.length && !changed.length) report += "子包清单无变化。\n\n";
+  console.log(`  新增: ${added.length} | 消失: ${removed.length} | 版本变化: ${changed.length}`);
+  if (added.length) warn(`⚠️ 新增子包需检查主包是否声明（漏声明 → 断链卡屏，rc.8 primitives 前科）`);
+}
+
+// ── 4. 漏声明检测 + 探针包 ───────────────────────────────
+console.log("\n[3/4] 关键包漏声明检测（断链风险）...");
+// 2026-09-28 修：原实现用**目录名**比**包名**（缺 @deepseek-ai/ scope）⇒ 0.1.7 上把 52 个 UI
+// 子包全报成漏声明。全是噪音的告警等于没有告警（真孤儿会被淹）。分类逻辑见
+// scripts/lib/dep-declaration.mjs：declared（声明方声明）/ transitive（别人依赖）/ orphan（真可疑）。
+const packages = readScope(depRoot);
+const cls = classifySubpackages({
+  packages,
+  declarers: DECLARER_PKGS.map((p) => (p.includes("/") ? p : `@deepseek-ai/${p}`)),
+  interest: (n) => n.startsWith("@deepseek-ai/dsh-client-ui"),
+});
+report += `## 关键包漏声明检测（UI 子包三级分类）\n\n`;
+report += `- 声明方声明：${cls.declared.length} 个\n`;
+report += `- 传递依赖（别的包依赖它，正常）：${cls.transitive.length} 个${cls.transitive.length ? "：" + cls.transitive.map((n) => n.replace("@deepseek-ai/", "")).join(", ") : ""}\n`;
+report += `- **既无声明也无人依赖（真可疑）**：${cls.orphan.length} 个${cls.orphan.length ? "：" + cls.orphan.map((n) => n.replace("@deepseek-ai/", "")).join(", ") : ""}\n`;
+if (cls.orphan.length) {
+  warn(`⚠️ ${cls.orphan.length} 个 UI 子包既未被声明也无人依赖（磁盘上有、没人引用）—— 逐个确认是否需要增量接线`);
+  for (const n of cls.orphan) console.log(`     · ${n}`);
+} else {
+  ok(`UI 子包全部有归属（声明 ${cls.declared.length} / 传递 ${cls.transitive.length} / 孤儿 0）`);
+}
+
+
+console.log("\n[4/4] 探针包存在性（profiles 断链清单）...");
+report += `\n## 探针包存在性（profiles 断链清单）\n\n`;
+for (const p of LINK_PROBES) {
+  const present = existsSync(join(depRoot, p));
+  report += `- ${p}: ${present ? "✅ 存在" : "❌ 不存在"}\n`;
+  console.log(`  ${present ? "✅" : "❌"} ${p}`);
+}
+
+const reportPath = `/tmp/dsh-preflight-${target}.md`;
+writeFileSync(reportPath, report);
+console.log(`\n报告已写入: ${reportPath}`);
+console.log(`
+── 剩余人工步骤（docs/dsh-version-management.md「升级前变更审查清单」）──
+  2. 隔离试跑 + CDP boot 验证（带完整品牌补丁，独立 profile + 独立端口）
+  3. 品牌补丁特征回归（data-slot / wordmark / 类名前缀对照补丁 ①②③④⑤⑥）
+  4. CLI 行为 diff（dsh --help；--profile/--port/--no-open 等）
+  5. 凭据格式探测（隔离试跑后检查 ~/.dsh/.credentials.yaml 写入格式）
+  6. profiles 链接重建行为确认（嵌套 vs 顶层 flat）
+全部通过后再执行 scripts/dsh-upgrade.mjs ${target}`);

package/engine/scripts/dsh-release-watch-daily.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# 每日只读巡检：官方 dsh 是否发新版（窗口外 ⇒ 列入待适配）。
+#
+# 为什么：客户会先按 **dsh 官方**方式装宿主（官方 README 首选 `npx @deepseek-ai/dsh web`，
+# npm `latest` 现在就是 0.2.0-rc.2），如果我们的支持窗口跟不上，客户会在门禁处被挡。
+# 本巡检把"官方发版 → 我方待办"的发现动作自动化（发现延迟从"人想起来"降到 ≤1 天）。
+#
+# 判据全部在 `scripts/dsh-release-watch.mjs`（只读、cwd 无关、退出码 0/1/2）：
+#   0 = 窗口内；1 = 有更新未适配（需按脚本打印的 7 步链适配）；2 = 取不到元数据（⛔ 不等于没更新）
+# ⛔ 本脚本只读：不写仓库、不写 ~/.dsh（日志由 launchd 的 StandardOutPath 落盘）、不装/不升级任何 dsh。
+set -u
+REPO="/Users/chester/Code/argent-dsh"
+NODE="/opt/homebrew/bin/node"
+cd "$REPO" 2>/dev/null || { echo "[$(date '+%F %T')] 仓库不存在：$REPO"; exit 2; }
+echo "──────── $(date '+%F %T') dsh 发版巡检 ────────"
+"$NODE" scripts/dsh-release-watch.mjs 2>&1
+rc=$?
+echo "[$(date '+%F %T')] exit=${rc}（0=窗口内 / 1=有更新未适配 / 2=取不到元数据）"
+exit "${rc}"

package/engine/scripts/dsh-release-watch.mjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+/**
+ * dsh **官方发版监听**（只读）—— 2026-10-11「宿主发版监听批」
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、为什么需要它（用户提出的现实问题）
+ * ══════════════════════════════════════════════════════════════════════════
+ * dsh 官方 npm 的 `dist-tags.latest` **现在就已经是 `0.2.0-rc.2`**，而 Argent 的支持窗口
+ * （`dsh-version-lock/` 里**已晋级**的最高快照）还停在 `0.1.7-rc.2`。客户装机的第一件事是
+ * 按官方命令装 dsh ⇒ **装到的就是窗口外版本**。若只在"人发现"之后才去适配，就会长期挡客户。
+ *
+ * 所以缺的**不是**能力（我们已有 preflight → snapshot → 审计 三段式），缺的是**触发**：
+ * 一条只读命令，一跑就知道"官方发了什么、离我们的窗口有多远、下一步抄哪几条命令"。
+ * ⛔ 本脚本**只报告**：不写任何文件、不改 registry、不 npm login、不发布、不投递；
+ * 除了取元数据本身，没有任何副作用（`--registry` 指本地文件时连网络都不碰 ⇒ 回归可做到零网络）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、判据（**只有一个真源**，⛔ 不新增第二份版本字面量）
+ * ══════════════════════════════════════════════════════════════════════════
+ * · **窗口真源** = `dsh-version-lock/*.json`（顶层 = 已晋级/已验证；`candidate/` **不参与**）
+ *   ＋ `scripts/lib/dsh-versions.mjs` 的 `listVerifiedVersions()` / `pickLatestVerified()` /
+ *   `cmpVer()`（**rc 排序也归它**，本文件不自己实现版本比较）。
+ * · `verifiedListGaps()` 顺带做一次**基线漂移自检**：内置基线必须覆盖 lock 里已晋级的全集
+ *   （缺项 = 装机时会把现役版本报成"未验证"；与 `scripts/tests/dsh-verified-list.test.mjs` 同源判据）。
+ * · 差集：官方 `versions` 里**比窗口最高版本更新**的全部版本 = `outOfWindow`；
+ *   其中 `candidate/` 里还没有的 = `pendingCandidate`（= 真正待办的版本），已有的 = `candidateReady`
+ *   （已审查未验收 ⇒ 下一步是**验收+晋级**，不是重新 preflight）。
+ *
+ * ## 结论与退出码（⚠️ 的语义是**适配关系**，不是"新版本更好"）
+ * | 退出码 | 结论行 | 含义 |
+ * |---|---|---|
+ * | 0 | `状态：✅ 窗口内` | 官方**任何通道**都没有窗口外版本 |
+ * | 1 | `状态：⚠️ 有更新未适配` | 官方有窗口外版本（`latest` 出窗 = **直接挡客户**，最高优先） |
+ * | 2 | `状态：❌ 取不到元数据` | 拉不到/解析不了官方元数据 —— **⛔ 绝不当成"没有更新"** |
+ *
+ * 退出码 2 刻意与"没更新"分开：把网络失败读成"今天没发版"，正是这类监听器最危险的假绿。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 三、用法
+ * ══════════════════════════════════════════════════════════════════════════
+ * ```bash
+ * node scripts/dsh-release-watch.mjs                 # 人读（默认 registry = npmmirror 镜像）
+ * node scripts/dsh-release-watch.mjs --json          # 机器读（字段形状稳定）
+ * node scripts/dsh-release-watch.mjs --registry https://registry.npmjs.org/@deepseek-ai/dsh
+ * node scripts/dsh-release-watch.mjs --registry /tmp/meta.json   # 本地元数据（离线/夹具；也认 file://）
+ * node scripts/dsh-release-watch.mjs --lock-dir <目录>            # 换窗口真源（回归夹具用）
+ * ```
+ *
+ * ## 环境开关
+ * · `ARGENT_TESTS_OFFLINE=1` —— 由 `scripts/run-tests.sh` 导出：**拒绝真发网络请求**（直接抛错 ⇒
+ *   走"取不到元数据"分支）。目的是让"夹具回归零网络"这条性质**可执行**，而不是靠自觉
+ *   （同类先例：`ARGENT_TELEMETRY_OFF`）。⛔ 只影响本脚本的 http(s) 取数，不影响本地文件模式；
+ *   且只拦**默认**取数路径（`globalThis.fetch`）—— 显式注入 `fetchImpl` 的调用方走的是**测试 seam**，
+ *   由它自己保证零网络（见 `loadMetadata` 里的说明）。
+ *
+ * ## 纯度
+ * 只 import `node:` 内建 ＋ 同层 `scripts/lib/*`（`is-direct-run.mjs` / `dsh-versions.mjs`），
+ * **零宿主模块**（不 import `@deepseek-ai/*` / `cordis` / `plugins/*`）——
+ * 虽然 `kernel-purity` 的层标注把 `scripts/dsh-*.mjs` 归在 L2（宿主运维档、不扫内容），
+ * 本文件仍按 L1 的纯度自律；回归里有一条**静态断言**钉住这件事。
+ *
+ * 回归：`node scripts/tests/dsh-release-watch.test.mjs`（纯夹具、零网络、含只读性指纹）
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import {
+  DSH_VERIFIED_FALLBACK,
+  cmpVer,
+  listCandidateVersions,
+  listVerifiedVersions,
+  pickLatestVerified,
+  verifiedListGaps,
+} from './lib/dsh-versions.mjs'
+
+export const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+/** 官方 registry（默认走镜像：本机/客户机都在国内网络；`--registry` 可覆盖成 npmjs 官方源）。 */
+export const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/@deepseek-ai/dsh'
+export const DEFAULT_LOCK_DIR = join(REPO, 'dsh-version-lock')
+/** 0.2.x 适配审计清单（另一个只读审计批在写；**不存在时**只提示、不编造）。 */
+export const AUDIT_DOC = 'docs/dsh-0.2.x-适配审计.md'
+/** 结论三态（JSON 的 `status` 用机器值，人读行恒为 `状态：<emoji> <文案>`）。 */
+export const STATUS = {
+  ok: '✅ 窗口内',
+  stale: '⚠️ 有更新未适配',
+  unavailable: '❌ 取不到元数据',
+}
+/** 默认 IO（可注入：回归用临时目录/文件夹具，⛔ 不碰真仓库）。 */
+export const DEFAULT_IO = {
+  exists: existsSync,
+  readdir: readdirSync,
+  read: (p) => readFileSync(p, 'utf8'),
+}
+
+// ── 版本比较：**一律**走 lib 的 cmpVer（rc 排序归它，⛔ 本文件不自己实现）──────────
+const sortAsc = (list) => [...list].sort(cmpVer)
+const sortDesc = (list) => [...list].sort((a, b) => cmpVer(b, a))
+const uniq = (list) => [...new Set(list.filter(Boolean))]
+const fmtList = (list, sep = '、') => (list.length ? list.join(sep) : '（无）')
+
+/**
+ * 差距的**人读描述**（只描述，不参与任何排序/判据 —— 排序恒用 `cmpVer`）。
+ * @returns {string|null} `to` 不比 `from` 新 ⇒ null
+ */
+export function describeGap(from, to) {
+  if (!from || !to || cmpVer(to, from) <= 0) return null
+  const core = (v) => String(v).split('-')[0].split('.').map((n) => Number(n) || 0)
+  const [a1, a2, a3] = core(from)
+  const [b1, b2, b3] = core(to)
+  if (b1 !== a1) return `大版本 +${b1 - a1}（${from} → ${to}）`
+  if (b2 !== a2) return `小版本 +${b2 - a2}（${from} → ${to}）`
+  if (b3 !== a3) return `补丁 +${b3 - a3}（${from} → ${to}）`
+  return `同为 ${b1}.${b2}.${b3}，预发布号更靠后（${from} → ${to}）`
+}
+
+/** 把 registry 文档（或本地同一形状的 JSON）收敛成我们唯一用得到的两个字段。 */
+export function normalizeMetadata(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('元数据不是对象（不是 npm registry 的包文档）')
+  }
+  const distTags = (raw['dist-tags'] && typeof raw['dist-tags'] === 'object' && !Array.isArray(raw['dist-tags']))
+    ? raw['dist-tags'] : {}
+  const versions = (raw.versions && typeof raw.versions === 'object' && !Array.isArray(raw.versions))
+    ? Object.keys(raw.versions) : []
+  if (!versions.length) {
+    throw new Error('元数据里没有 versions（拿到的不是包文档 ⇒ 不能据此判"没更新"）')
+  }
+  // ⚠️ `latest` 缺失同样按"取不到"处理：客户装的正是 `latest`，没有它就无法回答
+  // "官方命令会装到哪一版" ⇒ 此时报"窗口内"就是假绿（宁可响亮地失败）。
+  if (!distTags.latest) {
+    throw new Error('元数据里没有 dist-tags.latest（无法判定"客户按官方命令会装到哪一版" ⇒ 不能判"窗口内"）')
+  }
+  return { distTags, versions }
+}
+
+/**
+ * 取元数据。`registry` 是 http(s) ⇒ 真拉；`file://` 或本地路径 ⇒ 读文件（离线/夹具）。
+ * 三种失败（网络 / HTTP 状态 / JSON 形状）**一律抛错**，由调用方转成 exit 2。
+ */
+export async function loadMetadata({ registry = DEFAULT_REGISTRY, fetchImpl = globalThis.fetch, io = DEFAULT_IO, timeoutMs = 20000 } = {}) {
+  const src = String(registry || DEFAULT_REGISTRY)
+  if (/^https?:\/\//i.test(src)) {
+    // ⚠️ 离线开关只拦**默认**取数路径（`globalThis.fetch` = 真发请求）；显式注入 `fetchImpl` 的调用方
+    //    是在走**测试 seam**（注入的假 fetch 自己保证零网络），不能被一刀切拦掉 ——
+    //    2026-10-11 实测踩到：一刀切时 run-tests.sh 导出的 ARGENT_TESTS_OFFLINE=1 会把回归里
+    //    "假 fetch 抛/假 404" 两条用例变成"离线模式"，等于把 seam 本身变得不可测。
+    if (fetchImpl === globalThis.fetch && String(process.env.ARGENT_TESTS_OFFLINE || '') === '1') {
+      throw new Error('离线模式（ARGENT_TESTS_OFFLINE=1）：拒绝真发网络请求（测试期的零网络声明）')
+    }
+    if (typeof fetchImpl !== 'function') throw new Error('本 Node 没有全局 fetch（需要 Node ≥ 18）')
+    let res
+    try {
+      const signal = (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) ? AbortSignal.timeout(timeoutMs) : undefined
+      res = await fetchImpl(src, { headers: { accept: 'application/json' }, signal })
+    } catch (e) {
+      throw new Error(`请求失败：${e && e.message ? e.message : e}`)
+    }
+    if (!res || typeof res.ok !== 'boolean') throw new Error('请求返回了非法响应对象')
+    if (!res.ok) throw new Error(`HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`)
+    const text = await res.text()
+    try {
+      return JSON.parse(text)
+    } catch (e) {
+      throw new Error(`响应不是 JSON：${e && e.message ? e.message : e}`)
+    }
+  }
+  const file = src.startsWith('file:') ? fileURLToPath(src) : src
+  let text
+  try {
+    text = io.read(file)
+  } catch (e) {
+    throw new Error(`读不到本地元数据 ${file}：${e && e.message ? e.message : e}`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (e) {
+    throw new Error(`本地元数据不是 JSON（${file}）：${e && e.message ? e.message : e}`)
+  }
+}
+
+/**
+ * **窗口真源**（纯读）：lock 顶层晋级快照 ＋ 基线漂移自检 ＋ 候选清单。
+ * 抽成独立函数是为了让"取不到元数据"时**照样**能把窗口打出来（那只读本机文件，与网络无关）。
+ */
+export function readWindow({ lockDir = DEFAULT_LOCK_DIR, io = DEFAULT_IO } = {}) {
+  const promoted = sortAsc(uniq(listVerifiedVersions(lockDir, io)))
+  const lockReadable = promoted.length > 0
+  const windowVersions = lockReadable ? promoted : sortAsc(uniq(DSH_VERIFIED_FALLBACK))
+  const highestVerified = pickLatestVerified(lockDir, io)
+  const windowHighest = lockReadable ? highestVerified : windowVersions[windowVersions.length - 1]
+  const baseline = verifiedListGaps(DSH_VERIFIED_FALLBACK, lockDir, io)
+  return {
+    verifiedWindow: windowVersions,
+    verifiedHighest: windowHighest,
+    windowReadable: lockReadable,
+    windowSource: lockReadable
+      ? `dsh-version-lock/ 顶层晋级快照（${promoted.length} 个）`
+      : '⚠️ lock 目录读不到 ⇒ 退回 scripts/lib/dsh-versions.mjs 的内置基线',
+    baselineDrift: { ok: baseline.ok, missing: baseline.missing },
+    candidateVersions: sortAsc(uniq(listCandidateVersions(lockDir, io))),
+  }
+}
+
+/**
+ * **纯判据**：元数据 ＋ 窗口真源 ⇒ 结论对象（无网络；IO 只读窗口真源；回归直接调它）。
+ *
+ * @param {{metadata: object, lockDir?: string, io?: object, repoDocExists?: (rel: string) => boolean}} args
+ */
+export function evaluate({ metadata, lockDir = DEFAULT_LOCK_DIR, io = DEFAULT_IO, repoDocExists } = {}) {
+  const { distTags, versions } = normalizeMetadata(metadata)
+  const official = uniq(versions)
+  const win = readWindow({ lockDir, io })
+  const { verifiedHighest: windowHighest, candidateVersions } = win
+
+  const tagOf = (k) => (distTags[k] ? String(distTags[k]) : null)
+  const latest = tagOf('latest')
+  const next = tagOf('next')
+  const alpha = tagOf('alpha')
+
+  // ── 差集：官方有、窗口内没有的版本（含各通道）──
+  const outOfWindow = sortDesc(official.filter((v) => cmpVer(v, windowHighest) > 0))
+  const pendingCandidate = outOfWindow.filter((v) => !candidateVersions.includes(v))
+  const candidateReady = outOfWindow.filter((v) => candidateVersions.includes(v))
+  const tagVersions = uniq([latest, next, alpha])
+  const tagsOutOfWindow = sortDesc(tagVersions.filter((v) => cmpVer(v, windowHighest) > 0))
+  const latestInWindow = latest ? cmpVer(latest, windowHighest) <= 0 : null
+  // 待办顺序：dist-tags 指向的（latest 最优先）在前，其余按版本倒序 —— 清单要能"从上往下抄"。
+  const stepOrder = uniq([...([latest, next, alpha]), ...sortDesc(outOfWindow)])
+    .filter((v) => outOfWindow.includes(v))
+
+  // ── 结论：**任何通道**有窗口外版本 ⇒ ⚠️（宁多报不漏报）；拿不到元数据根本走不到这里 ──
+  const status = outOfWindow.length === 0 ? 'ok' : 'stale'
+  const auditDocExists = typeof repoDocExists === 'function' ? repoDocExists(AUDIT_DOC) : io.exists(join(REPO, AUDIT_DOC))
+
+  return {
+    status,
+    conclusion: STATUS[status],
+    registry: null, // 由 run() 填（evaluate 不关心来源）
+    latest,
+    next,
+    alpha,
+    distTags: { ...distTags },
+    versionCount: official.length,
+    ...win,
+    inWindow: latestInWindow === null ? false : latestInWindow,
+    latestInWindow,
+    outOfWindow,
+    tagsOutOfWindow,
+    pendingCandidate,
+    candidateReady,
+    gap: latest ? describeGap(windowHighest, latest) : null,
+    auditDoc: auditDocExists ? AUDIT_DOC : null,
+    nextSteps: buildNextSteps(stepOrder, candidateVersions, auditDocExists),
+    error: null,
+  }
+}
+
+/** 逐版本给出**照抄可跑**的下一步（已进候选 ⇒ 走验收+晋级；未进候选 ⇒ 走 preflight+快照）。 */
+export function buildNextSteps(stepOrder, candidateVersions, auditDocExists) {
+  return stepOrder.map((ver) => {
+    const inCandidate = candidateVersions.includes(ver)
+    const steps = inCandidate
+      ? [
+        'node scripts/plugin-bootcheck.mjs            # 隔离试跑：要求全 preset OK（真实 profile，不重启服务）',
+        'node scripts/dsh-upgrade.mjs --patches-only   # 五项复核（补丁重打 + 加固 + 旧 session 迁移 + preset 门禁 + 冒烟）',
+        `git mv dsh-version-lock/candidate/${ver}.json dsh-version-lock/${ver}.json   # 真机重启验收通过后晋级`,
+      ]
+      : [
+        `node scripts/dsh-preflight.mjs ${ver}`,
+        `node scripts/dsh-snapshot.mjs --from-dir /tmp/dsh-preflight-${ver} --target ${ver} --write`,
+        `# ↑ <staged> 缺省 = preflight 建的 /tmp/dsh-preflight-${ver}；快照落 dsh-version-lock/candidate/${ver}.json（候选，不参与自动挑选）`,
+      ]
+    if (auditDocExists) steps.push(`# 审计清单：${AUDIT_DOC}`)
+    return { version: ver, inCandidate, steps }
+  })
+}
+
+const bar = (s = '') => `  ${s}`
+
+/** 人读渲染：结论行恒为**最后一行**，且恒以 `状态：` 开头（可 grep / 可断言）。 */
+export function renderHuman(r) {
+  const L = []
+  L.push('═══ dsh 官方发版监听（只读）═══')
+  L.push(bar(`registry     : ${r.registry}`))
+  if (r.error) {
+    L.push(bar(`取数失败     : ${r.error}`))
+    L.push(bar('⛔ 这是"取不到"，不是"没有更新" —— 别据此判窗口内；可换 --registry 或稍后重试'))
+  }
+  const tags = Object.entries(r.distTags || {}).sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `${k}=${v}`)
+  L.push(bar(`官方 dist-tags: ${tags.length ? tags.join('  ') : '（无）'}`))
+  L.push(bar(`版本总数     : ${r.versionCount == null ? '—' : r.versionCount}`))
+  L.push(bar(`支持窗口     : ${fmtList(r.verifiedWindow, ' / ')}（最高 ${r.verifiedHighest || '—'}；来源 ${r.windowSource}）`))
+  if (!r.baselineDrift.ok) {
+    L.push(bar(`⚠️ 基线漂移   : 内置基线缺 ${fmtList(r.baselineDrift.missing)}`
+      + '（装机时会把已晋级版本报成"未验证"；修 scripts/lib/dsh-versions.mjs 的 DSH_VERIFIED_FALLBACK）'))
+  }
+  L.push(bar(`latest       : ${r.latest || '—'}`
+    + (r.gap ? ` —— ⛔ 窗口外：比窗口最高 ${r.verifiedHighest} ${r.gap}` : (r.latestInWindow ? ' —— ✅ 在窗口内' : ''))))
+  L.push(bar(`其他通道     : next=${r.next || '—'}  alpha=${r.alpha || '—'}`))
+  if (r.error) {
+    // ⛔ 取不到元数据时**不许**出现"都在窗口内"这类结论（那正是最危险的假绿）。
+    L.push(bar('待适配       : 未知 —— 官方侧一个字段都没拿到，⛔ 不得读成"没有更新"'))
+  } else if (r.outOfWindow.length) {
+    L.push(bar(`待适配（官方已发、窗口内没有，共 ${r.outOfWindow.length} 个）: ${fmtList(r.outOfWindow)}`))
+    L.push(bar(`dist-tags 指向的窗口外版本: ${fmtList(r.tagsOutOfWindow)}`
+      + (r.latestInWindow === false ? '（latest 出窗 = 直接挡客户，最高优先）' : '（latest 未出窗）')))
+    L.push(bar(`候选缺口（官方有、candidate/ 里没有）: ${fmtList(r.pendingCandidate)}`))
+    L.push(bar(`已在候选（已审查未验收 ⇒ 下一步是验收+晋级）: ${fmtList(r.candidateReady)}`))
+    L.push('')
+    L.push('下一步（按优先级从上往下抄；latest 最先）:')
+    for (const s of r.nextSteps) {
+      L.push(bar(`· ${s.version}${s.inCandidate ? '（已在 candidate/ ⇒ 走验收+晋级）' : '（未进 candidate/ ⇒ 走 preflight+快照）'}`))
+      for (const c of s.steps) L.push(bar(`    ${c}`))
+    }
+  } else {
+    L.push(bar('待适配       : （无）官方所有已发版本都在窗口内'))
+  }
+  L.push('')
+  L.push(`状态：${r.conclusion}`)
+  return L.join('\n')
+}
+
+/** 机器读渲染：字段形状**稳定**（回归 §5 逐字段断言）。 */
+export function renderJson(r) {
+  return {
+    registry: r.registry,
+    latest: r.latest,
+    next: r.next,
+    alpha: r.alpha,
+    versionCount: r.versionCount,
+    verifiedWindow: r.verifiedWindow,
+    verifiedHighest: r.verifiedHighest,
+    inWindow: r.inWindow,
+    outOfWindow: r.outOfWindow,
+    pendingCandidate: r.pendingCandidate,
+    candidateReady: r.candidateReady,
+    candidateVersions: r.candidateVersions,
+    tagsOutOfWindow: r.tagsOutOfWindow,
+    status: r.status,
+    conclusion: r.conclusion,
+    gap: r.gap,
+    windowSource: r.windowSource,
+    windowReadable: r.windowReadable,
+    baselineDrift: r.baselineDrift,
+    distTags: r.distTags,
+    auditDoc: r.auditDoc,
+    nextSteps: r.nextSteps,
+    error: r.error || null,
+  }
+}
+
+export const USAGE = `用法: node scripts/dsh-release-watch.mjs [选项]
+
+  --registry <url|文件>  官方 registry 元数据来源；http(s) = 真拉，本地路径 / file:// = 读文件（离线夹具）
+                         默认 ${DEFAULT_REGISTRY}
+  --lock-dir <目录>      窗口真源（默认 dsh-version-lock/；回归夹具用临时目录）
+  --json                 输出机器可读 JSON（字段形状稳定）
+  --timeout <毫秒>       单次请求超时（默认 20000）
+  -h, --help             本帮助
+
+退出码: 0 = 窗口内 ／ 1 = 有更新未适配 ／ 2 = 取不到元数据（**不是**"没有更新"）
+只读: 不写任何文件、不改 registry、不 npm login；ARGENT_TESTS_OFFLINE=1 时**拒绝**真发网络请求`
+
+/** 参数解析（不认识的参数/缺值 ⇒ 收进 errors，由 run() 转成 exit 2）。 */
+export function parseArgs(argv) {
+  const out = { registry: DEFAULT_REGISTRY, lockDir: DEFAULT_LOCK_DIR, json: false, help: false, timeoutMs: 20000, errors: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    const val = (name) => {
+      const v = argv[i + 1]
+      if (v === undefined || v.startsWith('--')) { out.errors.push(`${name} 缺参数值`); return null }
+      i += 1
+      return v
+    }
+    if (a === '--registry') { const v = val(a); if (v) out.registry = v; continue }
+    if (a === '--lock-dir') { const v = val(a); if (v) out.lockDir = v; continue }
+    if (a === '--timeout') {
+      const v = val(a)
+      const n = Number(v)
+      if (v && (!Number.isFinite(n) || n <= 0)) out.errors.push(`--timeout 需要正整数毫秒（得到 ${v}）`)
+      else if (v) out.timeoutMs = n
+      continue
+    }
+    if (a === '--json') { out.json = true; continue }
+    if (a === '-h' || a === '--help') { out.help = true; continue }
+    out.errors.push(`未知参数 ${a}`)
+  }
+  return out
+}
+
+/**
+ * 主流程（可注入 fetch/io ⇒ 回归能在**零网络**下走同一条代码路径）。
+ * @returns {Promise<number>} 退出码（0/1/2）
+ */
+export async function run(argv, {
+  fetchImpl = globalThis.fetch,
+  io = DEFAULT_IO,
+  out = (s) => process.stdout.write(`${s}\n`),
+  err = (s) => process.stderr.write(`${s}\n`),
+  repoDocExists,
+} = {}) {
+  const args = parseArgs(argv)
+  if (args.help) { out(USAGE); return 0 }
+  if (args.errors.length) {
+    for (const e of args.errors) err(`✗ ${e}`)
+    err(USAGE)
+    return 2
+  }
+
+  let result
+  try {
+    const raw = await loadMetadata({ registry: args.registry, fetchImpl, io, timeoutMs: args.timeoutMs })
+    result = evaluate({ metadata: raw, lockDir: args.lockDir, io, repoDocExists })
+  } catch (e) {
+    // ★ 关键判据：**取不到元数据 ≠ 没有更新** —— 窗口照常算（那部分只读本机文件），结论恒 ❌ / exit 2。
+    result = {
+      ...evaluateUnavailable({ lockDir: args.lockDir, io }),
+      registry: args.registry,
+      error: e && e.message ? e.message : String(e),
+    }
+  }
+  result.registry = args.registry
+  if (args.json) out(JSON.stringify(renderJson(result), null, 2))
+  else out(renderHuman(result))
+  return result.status === 'ok' ? 0 : (result.status === 'stale' ? 1 : 2)
+}
+
+/** "取不到元数据"时的结论对象（窗口部分照常给出；官方侧字段一律 null/空 —— ⛔ 不猜）。 */
+export function evaluateUnavailable({ lockDir = DEFAULT_LOCK_DIR, io = DEFAULT_IO } = {}) {
+  const win = readWindow({ lockDir, io })
+  return {
+    status: 'unavailable',
+    conclusion: STATUS.unavailable,
+    registry: null,
+    latest: null,
+    next: null,
+    alpha: null,
+    distTags: {},
+    versionCount: null,
+    ...win,
+    inWindow: false,
+    latestInWindow: null,
+    outOfWindow: [],
+    tagsOutOfWindow: [],
+    pendingCandidate: [],
+    candidateReady: [],
+    gap: null,
+    auditDoc: null,
+    nextSteps: [],
+    error: null,
+  }
+}
+
+/** 入口守卫：只在**直接执行**时跑主逻辑（软链安全，判据见 lib/is-direct-run.mjs）。 */
+if (isDirectRun(import.meta.url)) {
+  run(process.argv.slice(2)).then((code) => { process.exitCode = code })
+}