@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/dsh-scope.mjs

@@ -0,0 +1,500 @@
+/**
+ * dsh 全局安装位置解析（**唯一真源**）。
+ *
+ * 由来（2026-09-28 客户机实测）：本机（开发机）dsh 走 homebrew，
+ * `SCOPE_DIR = /opt/homebrew/lib/node_modules/@deepseek-ai`；客户机是 node 官方包，
+ * `~/node/lib/node_modules/@deepseek-ai`。历史上有 4 个脚本各自写死 homebrew 路径，
+ * 到客户机就"文件不存在/门禁假红"。这里收敛成一处，取值优先级：
+ *   --scope-dir/--global-bin → 环境变量 DSH_SCOPE/DSH_BIN → npm root -g 自动探测 → 候选兜底。
+ *
+ * ⚠️ 本文件必须**零第三方依赖**（升级链路上的脚本要在半坏的机器上也能跑）；
+ *    唯一的本地 import 是 `./dsh-host-resolve.mjs`（同为引擎面文件、同样零第三方依赖），
+ *    只为复用"npx 缓存目录在哪"这一个判据（⛔ 不再写第二份）。
+ *
+ * ── 2026-10-12 P1-3（审计 §C.1 #7）追加两件事 ────────────────────────────────────
+ * ① `scopeBinCandidates()` —— 由目标 scope 推导 `dsh` 可执行入口的候选序列（**唯一实现**）。
+ *    P1-0 曾把其中的「平铺档 `<dir>/node_modules/.bin/dsh`」**暂存**在
+ *    `scripts/lib/bootcheck-wiring.mjs#bootcheckBinCandidates()`（因为本文件在能力包的
+ *    `pack.engine` 清单里：改一个字节就要给三个能力包提版 + 重盖章）。P1-3 本就是"要提版"
+ *    的那一批 ⇒ **上移到真源**，bootcheck 那边的副本已删除（两处不再各自实现）。
+ * ② `resolveDshScopeDir()` —— **找得到 / 找不到都要说清楚**的 scope 定位器，
+ *    给 `install-argent.mjs#scopeDirForPreset()` 用。它覆盖三种真实布局：
+ *      · 标准 node 布局 `<prefix>/lib/node_modules/@deepseek-ai`（开发机 homebrew / 官方 pkg）；
+ *      · **邻居布局** `<prefix>/node_modules/@deepseek-ai`（客户机 `~/.local/node/node_modules` ——
+ *        这正是 `npm root -g` **探错**的那个陷阱：npm 报 `<prefix>/lib/node_modules`）；
+ *      · **平铺 / npx 布局** `<dir>/node_modules/@deepseek-ai`（预检树、`npx` 的
+ *        `~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）。
+ *    ⛔ 探不到就**返回 null**（由调用方响亮失败），⛔ **不**回一个"猜的" `npm root -g` 路径。
+ *
+ * ── 2026-10-14 F1 修复批（MBP 真机实测）─────────────────────────────────────────
+ * ③ `resolveDshScope()`（**遗留定位器**）**同一个病**：末尾 `cands.find(exists) || cands[last]`
+ *    ⇒ ① **不感知 npx**（`npx @deepseek-ai/dsh@0.2.0-rc.2 web` 的模块树在
+ *    `~/.npm/_npx/<hash>/node_modules/@deepseek-ai`，一条候选都不命中）；② 探不到时回一个**可能不存在**的
+ *    路径 ⇒ 调用方**无法区分"没有"与"探错"**。实测后果：0.6.0 的"native 定时"在 npx 宿主上恒判 `unknown`。
+ *    **本批修法（三条，逐字对应缺陷）**：
+ *      a. 候选链**新增 npx 形态**（'~/.npm/_npx/<hash>/node_modules/@deepseek-ai'，复用
+ *         `dsh-host-resolve.mjs#npxCacheDirs()/scanNpxCache()/pickNpxHost()` —— 判据只有一份）；
+ *      b. 命中的判据是「**该 scope 里真的有 dsh 包**」（默认 `dsh-base`/`dsh-session`，
+ *         可用 `probePackages` 收窄；⛔ 不是"目录存在"就算 —— 空壳目录/别人的 scope 不算）；
+ *      c. **探不到 ⇒ 返回 `null`**（显式"未知"）+ 路径在但内容不合法 ⇒ `{scope, source, stale:true}`；
+ *         返回值显式带 `source: 'profile'|'npx'|'global'` 与 `how`（选择理由，可诊断）。
+ *    ⚠️ **兼容性**：老调用方拿到对象时 `scope` 字段就是过去那个字符串（语义不变），
+ *       只是**新增**了 `source`/`how`/`stale`；而"探不到不再是假路径"是**有意的破坏性修复** ——
+ *       所有调用点都必须显式处理 `null`（清单与判据见 `scripts/tests/dsh-scope-npx.test.mjs`）。
+ */
+import { execSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { npxCacheDirs, pickNpxHost, scanNpxCache } from './dsh-host-resolve.mjs'
+
+/** 取 `--name value` 形式的命令行参数值（缺省 null）。 */
+export function argValue(argv, name) {
+  const i = argv.indexOf(name)
+  return i > -1 ? argv[i + 1] ?? null : null
+}
+
+/** `npm root -g` 的默认探测（注入用 ⇒ 测试零环境依赖；npm 不在 PATH 时回 `''`）。 */
+export function defaultNpmRootG() {
+  try {
+    return execSync('npm root -g', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch { return '' }
+}
+
+/** PATH 上的 `dsh`（默认探测；注入用 ⇒ 测试零环境依赖）。 */
+export function defaultPathProbe() {
+  try {
+    return execSync('command -v dsh', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch { return '' }
+}
+
+/** 候选 scope 目录（**顺序即优先级**；最后一项是兜底，允许不存在）。
+ *  ⚠️ 0.6.0 F1 修复批：末尾补上 **npx 缓存**那一档（`npx @deepseek-ai/dsh@… web` 的树在
+ *  `~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）—— 否则"只需要一份候选清单"的调用方
+ *  （`dsh-api-client` 回落到宿主树的 `ws` 包）在 npx 机器上永远回落到不存在的路径。
+ *  ⛔ 本函数**只产候选**（不判内容合法性、不保证存在）：判据在 `resolveDshScope()`/`hasDshPackage()`。 */
+export function scopeCandidates(env = process.env, { home = '', readdir = readdirSync, npxDirs = null } = {}) {
+  const cands = []
+  const root = defaultNpmRootG()
+  if (root) cands.push(join(root, '@deepseek-ai'))
+  cands.push(
+    '/opt/homebrew/lib/node_modules/@deepseek-ai',                    // 开发机 homebrew
+    join(env.HOME || homedir(), 'node', 'lib', 'node_modules', '@deepseek-ai'), // 客户机 node 官方包
+    '/usr/local/lib/node_modules/@deepseek-ai',                        // Intel mac / 官方 pkg
+  )
+  for (const cache of (npxDirs || npxCacheDirs({ home: home || env.HOME || homedir(), env }))) {
+    let hashes = []
+    try { hashes = readdir(cache) } catch { continue }
+    for (const h of [...hashes].sort()) {
+      if (h.startsWith('.')) continue
+      cands.push(join(cache, h, 'node_modules', '@deepseek-ai'))
+    }
+  }
+  return cands
+}
+
+/**
+ * 解析 dsh scope 目录（**遗留定位器**；0.6.0 F1 修复后 = npx 感知 + 未知即 `null`）。
+ *
+ * @returns {{scope: string, source: 'profile'|'npx'|'global', how: string, stale?: true} | null}
+ *   · 命中 ⇒ 对象；`scope` 字段就是**过去那个字符串**（老调用方语义不变），
+ *     `source` = 命中来自哪一档，`how` = **选择理由**（人可读，可诊断"为什么选了这棵"）；
+ *   · 路径都在、但**没有一棵是合法的 dsh scope** ⇒ `{scope, source, how, stale: true}`
+ *     （"有目录没内容" —— 例如 `file:` 依赖失效后留空壳的 profile 树）；
+ *   · **一个都没有 ⇒ `null`**（显式"未知"），⛔ **绝不**回一个 passthrough 的假路径
+ *     （那正是 MBP 上 native 定时恒判 unknown 的成因）。
+ */
+export function resolveDshScope({
+  argv = process.argv, env = process.env, home = '',
+  exists = existsSync, readdir = readdirSync, read = defaultReadText, stat = defaultStat,
+  npmRootG = defaultNpmRootG, pathProbe = defaultPathProbe,
+  npxDirs = null, probePackages = DEFAULT_PROBE_PACKAGES, hostVersion = '',
+} = {}) {
+  const H = home || env.HOME || homedir()
+  const npxRoots = npxDirs || npxCacheDirs({ home: H, env })
+  const probe = (dir) => hasDshPackage(dir, { exists, read, packages: probePackages })
+
+  // ① 显式 `--scope-dir` / `DSH_SCOPE`：说一不二 —— **原样采用**，⛔ 不回落到别的树。
+  //    ⚠️ 但要**如实标注内容合法性**（`stale`）：调用方若走 `requireDshScope()`，指了空壳/不存在的树
+  //    会**响亮失败**（点了名的路径出错 = 拼错/树被移走；⛔ 静默换一棵才是灾难）。
+  const explicit = argValue(argv, '--scope-dir') || env.DSH_SCOPE
+  if (explicit) {
+    return {
+      scope: explicit,
+      source: scopeSourceOf(explicit, npxRoots),
+      how: '`--scope-dir` / `DSH_SCOPE`（显式指定）',
+      ...(probe(explicit) ? {} : { stale: true }),
+    }
+  }
+
+  // ①′ 显式 `--global-bin` / `DSH_BIN`：**也是显式指向**（"我告诉了你哪个 dsh"）⇒ 只认它反推出的树，
+  //     反推不出存在的 scope 就回 `null`（⛔ 不偷偷改用自动探测的另一棵树 —— 那会让"你指的那个 dsh"
+  //     与"我们判机制用的 scope"不是同一棵，正是本函数要消灭的那类静默错）。
+  const binHint = argValue(argv, '--global-bin') || env.DSH_BIN
+  if (binHint) {
+    for (const d of scopeCandidatesFromBin(binHint)) {
+      if (exists(d) && probe(d)) {
+        return { scope: d, source: scopeSourceOf(d, npxRoots), how: `由 \`--global-bin\` / \`DSH_BIN\` 反推（${binHint}）` }
+      }
+    }
+    return null
+  }
+
+  // ② 自动链（顺序 = `autoScopeCandidates()`）：第一棵**真的有 dsh 包**的胜出。
+  const chain = autoScopeCandidates({ env, home: H, exists, readdir, read, npmRootG, pathProbe, npxDirs: npxRoots })
+  const dirs = new Map()                       // dir → 链上的第一处来由（去重，保留最先出现的档）
+  for (const c of chain) if (!dirs.has(c.dir)) dirs.set(c.dir, c)
+  let firstExisting = null
+  for (const [dir, c] of dirs) {
+    if (!exists(dir)) continue
+    if (firstExisting === null) firstExisting = { dir, from: c.from }
+    if (!probe(dir)) continue
+    const hit = { scope: dir, source: c.from.startsWith('npx 缓存') ? 'npx' : scopeSourceOf(dir, npxRoots), how: c.from }
+    // npx 档：多个候选命中时按 `dsh-host-resolve.mjs#pickNpxHost()` 的**既有唯一规则**择优
+    //（最近使用优先 mtime，同刻路径升序；⛔ 不按版本号挑 —— 判据不再写第二份）
+    if (hit.source === 'npx') {
+      const picked = pickNpxScope({ dirs: [...dirs.keys()], probe, env, home: H, exists, readdir, read, stat, hostVersion: hostVersion || c.version, npxDirs: npxRoots })
+      if (picked) { hit.scope = picked.scope; hit.how = picked.how }
+    }
+    return hit
+  }
+  // ③ 一个合法的都没有：有目录 ⇒ stale（"有壳没内容"）；连目录都没有 ⇒ null（未知）
+  if (firstExisting) {
+    return {
+      scope: firstExisting.dir, source: scopeSourceOf(firstExisting.dir, npxRoots), stale: true,
+      how: `${firstExisting.from} —— 目录在，但其中**没有** dsh 包（${probePackages.map((p) => `@deepseek-ai/${p}`).join(' / ')}）`,
+    }
+  }
+  return null
+}
+
+/** 默认探测用的 dsh 包名（**存在性 = "这棵树真的是 dsh 宿主树"** 的最小判据）。 */
+export const DEFAULT_PROBE_PACKAGES = ['dsh-base', 'dsh-session']
+
+/**
+ * **调用方纪律**（F1 修复批，2026-10-14）：要干活就必须有 scope —— 拿不到 ⇒ **响亮失败**。
+ *
+ * 统一文案（⛔ 别在 8 个调用点各写一份）：点名"探不到宿主 scope（可能是 npx 形态）"、
+ * 列出**试过的档位**、给出**下一步命令**。`resolveDshScope()` 返回 `null`（未知）或
+ * `stale:true`（有壳没内容）都会抛这一条。
+ *
+ * @param {{what?: string, opts?: object}} [o] `what` = 调用方要干什么（进首行，便于排障）
+ * @returns {string} scope 目录（保证非空）
+ * @throws {Error} 探不到 / 探到空壳时
+ */
+export function requireDshScope({ what = '本脚本', opts = {} } = {}) {
+  const hit = resolveDshScope(opts)
+  if (hit && !hit.stale) return hit.scope
+  const why = hit && hit.stale
+    ? `探到的那棵是**空壳**（${hit.scope}：目录在、里面没有 dsh 包）`
+    : '候选作用域**一棵都不存在**'
+  throw new Error(
+    `${what}：⛔ 探不到宿主 scope（${why}）—— 可能是 **npx 形态**\n` +
+    '  已按序试过：`--scope-dir`/`DSH_SCOPE` → `--global-bin`/`DSH_BIN` 反推 → `npm root -g` → PATH 上的 dsh →\n' +
+    '             HOME 相对布局（邻居 → 标准）→ 当前 node 前缀 → **npx 缓存（~/.npm/_npx/<hash>/…）** → homebrew / Intel 绝对兜底。\n' +
+    '  ⛔ 拿一个**可能不存在**的路径继续干活 = 假绿（旧实现 `resolveDshScope()` 就是回 passthrough 假路径）。\n' +
+    '  下一步（三选一）：① `--scope-dir <…/@deepseek-ai>`；② `DSH_SCOPE=<…>`；③ `--global-bin <该 scope 自带的 dsh>`。\n' +
+    '  npx 形态参考：`ls -d ~/.npm/_npx/*/node_modules/@deepseek-ai`（取**含** `dsh-base`/`dsh-session` 的那个）。')
+}
+
+/**
+ * **要 import 宿主内部文件**的调用方的守卫（同上，但口子在"文件在不在"这一层）。
+ *
+ * 为什么单独一条：这一类调用点（`patches/verify-*.mjs`）本来就**允许**某个包不在（降级/跳过），
+ * 但**不允许**"整棵树都探不到" —— 后者会让 `existsSync(<假路径>)` 恒 false ⇒ 一路"跳过" ⇒
+ * **假绿**（门禁报"通过"，其实什么都没验）。故：scope 探不到 ⇒ 响亮失败；探到了但文件不在 ⇒
+ * 返回 null，由调用方按自己的语义降级（打印原因）。
+ *
+ * @returns {{scope: string, path: string} | null} `path` 不存在 ⇒ `null`（scope 有效）
+ * @throws {Error} scope 探不到 / 探到空壳时（与 {@link requireDshScope} 同一份文案）
+ */
+export function requireImportTarget(rel, { what = '本脚本', opts = {}, exists = existsSync } = {}) {
+  const scope = requireDshScope({ what, opts })
+  const p = `${scope}/${String(rel || '').replace(/^\/+/, '')}`
+  return exists(p) ? { scope, path: p } : null
+}
+
+/** 读 UTF-8 文本（注入用；默认实现）。 */
+export function defaultReadText(p) { return readFileSync(p, 'utf8') }
+
+/** `stat`（注入用；默认实现；失败 ⇒ 抛，由调用方 try 住）。 */
+export function defaultStat(p) { return statSync(p) }
+
+/**
+ * **这棵 scope 里真的有 dsh 包吗**（"命中"的唯一判据；⛔ 不是"目录存在"）。
+ *
+ * 认三种形态（任一命中即算 —— 越靠前越强）：
+ *   ① `<dir>/<pkg>/package.json` 的 `name === '@deepseek-ai/<pkg>'`（**真包**，带版本号）；
+ *   ② `<dir>/dsh/package.json` 的 `name === '@deepseek-ai/dsh'`（宿主主包）；
+ *   ③ `<dir>/<pkg>` 目录存在（包名目录 —— 老树/裁剪树里常见，无 package.json 也算）;
+ *   ④ `<dir>` 目录里**存在任一 `dsh-*` 包目录**（最宽的兜底：宿主树里必然有一堆 `dsh-*`）。
+ * ⛔ 坏 JSON **不**当"没有"（那会把好树判死）—— JSON 读坏时退到 ③/④ 的目录判据。
+ * @returns {boolean}
+ */
+export function hasDshPackage(dir, { exists = existsSync, read = defaultReadText, readdir = readdirSync, packages = DEFAULT_PROBE_PACKAGES } = {}) {
+  if (!dir) return false
+  const names = [...new Set([...(packages || []), 'dsh'])]
+  for (const pkg of names) {
+    const pkgDir = join(dir, pkg)
+    if (!exists(pkgDir)) continue
+    const meta = readPkgJson(join(pkgDir, 'package.json'), { exists, read })
+    if (meta && meta.name === `@deepseek-ai/${pkg}`) return true   // ①/② 真包
+    return true                                                    // ③ 包名目录在（无/坏 package.json 也算）
+  }
+  let entries = []
+  try { entries = readdir(dir) || [] } catch { return false }
+  return entries.some((e) => /^dsh-[a-z0-9]/.test(String(e)))       // ④ 有任一 dsh-* 包目录
+}
+
+/** 读一个 package.json（不存在/坏 JSON ⇒ null；⛔ 不抛）。 */
+function readPkgJson(p, { exists = existsSync, read = defaultReadText } = {}) {
+  if (!exists(p)) return null
+  try { return JSON.parse(read(p)) } catch { return null }
+}
+
+/** 命中来自哪一档（`profile` / `npx` / `global`）—— **判据只有这一处**。
+ *  `npxRoots` = 本次探测用到的 npx 缓存根（`…/_npx`）；给了就按它精确判定
+ *  （⛔ 不靠路径里恰好有 `_npx` 字样 —— 夹具/`npm_config_cache` 覆盖会把那个字样换掉）。 */
+export function scopeSourceOf(dir, npxRoots = []) {
+  const d = String(dir || '').replace(/\\/g, '/')
+  for (const r of npxRoots || []) {
+    const root = String(r || '').replace(/\\/g, '/').replace(/\/+$/, '')
+    // ⚠️ 必须要求"真的是一条 scope 目录"（`<root>/<hash>/node_modules/@deepseek-ai`）——
+    // 否则链上任何以该缓存根开头的路径都会被误标成 npx（实测：当 npx 缓存根退化成 HOME 时，
+    // `<HOME>/node/node_modules/@deepseek-ai` 那种**邻居布局**会被错标成 npx）。
+    if (root && d.startsWith(`${root}/`) && /\/node_modules\/@deepseek-ai\/?$/.test(d)) return 'npx'
+  }
+  if (/\/profiles\/[^/]+\/node_modules\/@deepseek-ai\/?$/.test(d)) return 'profile'
+  if (/(^|\/)_npx\//.test(d)) return 'npx'
+  return 'global'
+}
+
+/**
+ * npx 档择优（**判据复用 `dsh-host-resolve.mjs`，⛔ 不写第二份**）。
+ *
+ * 规则 = `scanNpxCache()` 扫全部 npx 候选（只认能读出 `@deepseek-ai/dsh` 的 hash）；
+ * ①（本批新增的"最匹配宿主版本"）能读出与**当前 npx 宿主同版本**的那个优先；
+ * ② 其余按 `pickNpxHost()` 的既有规则（mtime 最新 → 同刻路径升序）。
+ * 选择理由写进 `how`（含落选者，便于诊断"为什么不是另一个"）。
+ * @returns {{scope: string, how: string} | null}
+ */
+function pickNpxScope({ dirs = [], probe, env, home, exists, readdir, read, stat, hostVersion = '', npxDirs = null } = {}) {
+  const allNpxDirs = npxDirs || npxCacheDirs({ home, env })
+  const npxDirsOnChain = dirs.filter((d) => scopeSourceOf(d, allNpxDirs) === 'npx' && exists(d) && probe(d))
+  if (!npxDirsOnChain.length) return null
+  if (npxDirsOnChain.length === 1) {
+    return { scope: npxDirsOnChain[0], how: `npx 缓存（${dirname(dirname(npxDirsOnChain[0]))}）—— 唯一命中且含 dsh 包` }
+  }
+  const io = { exists, readdir, read: (p) => read(p), stat: (p) => stat(p) }
+  const cands = scanNpxCache(allNpxDirs, io)
+    .filter((c) => npxDirsOnChain.includes(dirname(c.pkgDir)))
+  const { chosen, considered } = pickNpxHost(cands)
+  const versionMatch = hostVersion ? cands.find((c) => c.version === hostVersion) : null
+  // ① "最匹配宿主版本" ② `pickNpxHost()` 的既有规则（mtime 最新 → 同刻路径升序）③ 兜底按候选序
+  const scope = versionMatch ? dirname(versionMatch.pkgDir)
+    : chosen ? dirname(chosen.pkgDir) : npxDirsOnChain[0]
+  const why = versionMatch
+    ? `与当前宿主同版本（${hostVersion}）`
+    : '最近使用优先（mtime 最新；npx 每次跑会刷新）'
+  return {
+    scope,
+    how: `npx 缓存里 ${npxDirsOnChain.length} 个候选命中 ⇒ 按「${why}」选 \`${scope}\``
+      + `（考虑过：${considered.map((c) => `${c.version}@${c.pkgDir}`).join('、') || '—'}）`,
+  }
+}
+
+/**
+ * 由某个 `dsh` 可执行文件路径**反推**它所属的 scope 目录候选（顺序即优先级；可能为空）。
+ *
+ * 认这几种形态（客户机/预检树/npx 缓存实测）：
+ *   · `…/@deepseek-ai/<pkg>/…`            ⇒ 该 `@deepseek-ai` 目录本身
+ *   · `<dir>/node_modules/.bin/dsh[.cmd]`  ⇒ `<dir>/node_modules/@deepseek-ai`（平铺 / npx）
+ *   · `<prefix>/bin/dsh[.cmd]`             ⇒ `<prefix>/lib/node_modules/@deepseek-ai`（标准）
+ *                                            再试 `<prefix>/node_modules/@deepseek-ai`（邻居）
+ * @param {string} bin
+ * @returns {string[]}
+ */
+export function scopeCandidatesFromBin(bin) {
+  const b = String(bin || '').replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!b) return []
+  const out = []
+  const push = (p) => { if (p && !out.includes(p)) out.push(p) }
+  const inScope = /^(.*\/@deepseek-ai)(?:\/|$)/.exec(b)
+  if (inScope) { push(inScope[1]); return out }
+  const flat = /^(.*)\/node_modules\/\.bin\/dsh(?:\.(?:cmd|ps1|exe))?$/.exec(b)
+  if (flat) { push(`${flat[1]}/node_modules/@deepseek-ai`); return out }
+  const inBin = /^(.*)\/bin\/dsh(?:\.(?:cmd|ps1|exe))?$/.exec(b)
+  if (inBin) {
+    push(`${inBin[1]}/lib/node_modules/@deepseek-ai`)   // 标准 node 布局
+    push(`${inBin[1]}/node_modules/@deepseek-ai`)       // 邻居布局（客户机 `~/.local/node`）
+  }
+  return out
+}
+
+/**
+ * 自动探测时**按序**试的 scope 目录（含**出自哪条判据**，便于把结论打给人看）。
+ * 顺序刻意是「越贴近"这台机器实际在用的那个"越靠前」：
+ *   `npm root -g` → PATH 上的 dsh 反推 → HOME 相对（邻居 → 标准）→ 当前 node 前缀 → npx 缓存 → 绝对兜底。
+ * ⚠️ `npm root -g` 只是**候选之一**：客户机上它报的是 `<prefix>/lib/node_modules`（`@deepseek-ai` 不在那儿）
+ *    ⇒ 它会自然落选，而**不会**把结论带偏（这正是旧实现的病根）。
+ * @param {{npxDirs?: string[]|null, read?: Function}} [o]
+ *   `npxDirs` —— 覆盖 npx 缓存目录（缺省 `npxCacheDirs()`；夹具用，⛔ 不改判据本身）。
+ * @returns {Array<{dir: string, from: string, version?: string}>}
+ */
+export function autoScopeCandidates({ env = process.env, home = '', exists = existsSync, readdir = readdirSync, npmRootG = defaultNpmRootG, pathProbe = defaultPathProbe, npxDirs = null, read = defaultReadText } = {}) {
+  const H = home || env.HOME || homedir()
+  const out = []
+  const push = (dir, from, version = '') => { if (dir) out.push(version ? { dir, from, version } : { dir, from }) }
+
+  // ① npm 自己说的全局根（开发机 / 官方 pkg；客户机是错的 ⇒ 只会落选）
+  const root = npmRootG()
+  if (root) push(join(root, '@deepseek-ai'), '`npm root -g`')
+
+  // ② PATH 上的 dsh ⇒ 反推（最接近"用户实际在用的那个"）
+  const bin = pathProbe()
+  for (const d of scopeCandidatesFromBin(bin)) push(d, `PATH 上的 dsh（${bin}）`)
+
+  // ③ HOME 相对：**邻居布局在前**（客户机 `~/.local/node/node_modules/@deepseek-ai`），标准布局在后
+  push(join(H, '.local', 'node', 'node_modules', '@deepseek-ai'), '邻居布局（~/.local/node/node_modules）')
+  push(join(H, 'node', 'node_modules', '@deepseek-ai'), '邻居布局（~/node/node_modules）')
+  push(join(H, '.local', 'node', 'lib', 'node_modules', '@deepseek-ai'), '标准布局（~/.local/node/lib/node_modules）')
+  push(join(H, 'node', 'lib', 'node_modules', '@deepseek-ai'), '标准布局（~/node/lib/node_modules）')
+
+  // ④ 当前 node 前缀（nvm / 官方 pkg：`<prefix>/lib/node_modules` 与邻居布局都试）
+  if (process.execPath) {
+    const prefix = dirname(dirname(process.execPath))
+    push(join(prefix, 'lib', 'node_modules', '@deepseek-ai'), `当前 node 前缀（${prefix}）`)
+    push(join(prefix, 'node_modules', '@deepseek-ai'), `当前 node 前缀的邻居布局（${prefix}）`)
+  }
+
+  // ⑤ **平铺 / npx 布局**：`npx @deepseek-ai/dsh@<版本> web` 跑过之后的痕迹（MBP 就是这一形态）。
+  //    带 `version`（能读出 `@deepseek-ai/dsh` 时）⇒ 多个候选时按"最匹配宿主版本"择优（见 `pickNpxScope()`）。
+  for (const cache of (npxDirs || npxCacheDirs({ home: H, env }))) {
+    let hashes = []
+    try { hashes = readdir(cache) } catch { continue }
+    for (const h of [...hashes].sort()) {
+      if (h.startsWith('.')) continue
+      const tree = join(cache, h)
+      const meta = readPkgJson(join(tree, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'), { exists, read })
+      push(join(tree, 'node_modules', '@deepseek-ai'), `npx 缓存（${tree}）`, meta && meta.version ? String(meta.version).trim() : '')
+    }
+  }
+
+  // ⑥ 绝对兜底（开发机 homebrew / Intel mac）
+  push('/opt/homebrew/lib/node_modules/@deepseek-ai', '标准布局（homebrew）')
+  push('/opt/homebrew/node_modules/@deepseek-ai', '邻居布局（homebrew）')
+  push('/usr/local/lib/node_modules/@deepseek-ai', '标准布局（Intel mac / 官方 pkg）')
+  return out
+}
+
+/**
+ * **定位 dsh scope 目录**（bootcheck / 安装器判 preset 机制用）—— 找得到/找不到都**说得清**。
+ *
+ * ⚠️ 0.6.0 F1 修复批起：**自动链委托给 {@link resolveDshScope}**（单一人选：npx 感知 + 多候选择优），
+ *    本函数只做**契约适配**（`{scope,…}` → `{dir, from}`；`stale` 对它不算命中 ⇒ 沿用老口径回 `null`）。
+ *    ⛔ 不再自己拼候选、⛔ 不再"目录存在就算" —— 两处各自实现过正是旧缺陷的温床。
+ *
+ * 优先级：`--scope-dir`/`DSH_SCOPE`（**显式**）→ `--global-bin`/`DSH_BIN` 反推 → 自动探测。
+ * ⚠️ 显式给了但**不存在** ⇒ 返回 `null`（调用方响亮失败）—— ⛔ **绝不**"静默回退到
+ *    `npm root -g` 猜一个"（那正是客户机把 preset 机制判错的成因）。
+ * ⚠️ `--global-bin`/`DSH_BIN` 同理：它也是**显式**的宿主指向（"我告诉了你哪个 dsh"），
+ *    反推不出存在的 scope ⇒ 也回 `null`（⛔ 不悄悄改用另一棵树 —— 那会让"你指的那个 dsh"
+ *    与"我们判机制用的 scope"**不是同一棵**，正是本函数要消灭的那类静默错）。
+ * @returns {{dir: string, from: string} | null}
+ */
+export function resolveDshScopeDir({ argv = process.argv, env = process.env, home = '', exists = existsSync, readdir = readdirSync, npmRootG = defaultNpmRootG, pathProbe = defaultPathProbe, npxDirs = null } = {}) {
+  // ① 显式 `--scope-dir`/`DSH_SCOPE`：**存在就原样采用**（本函数是"判目标树"的口，
+  //    ⛔ 不替调用方做 content 合法性判断，也 ⛔ 不换成别的树）；不存在 ⇒ `null`（响亮失败）。
+  const explicit = argValue(argv, '--scope-dir') || env.DSH_SCOPE
+  if (explicit) return exists(explicit) ? { dir: explicit, from: '`--scope-dir` / `DSH_SCOPE`（显式指定）' } : null
+  // ② 显式 `--global-bin`/`DSH_BIN`：只认它反推出的树（**存在**即可，同样不要求有 dsh 包 ——
+  //    "你指的那个 dsh 在哪儿"这个问题与"树里有什么"无关）；反推不出 ⇒ `null`。
+  const binHint = argValue(argv, '--global-bin') || env.DSH_BIN
+  if (binHint) {
+    for (const d of scopeCandidatesFromBin(binHint)) {
+      if (exists(d)) return { dir: d, from: `由 \`--global-bin\` / \`DSH_BIN\` 反推（${binHint}）` }
+    }
+    return null
+  }
+  // ③ 自动链：委托真源单一人选（npx 感知 + 多候选择优 + **内容合法性**判据）。
+  //    空壳 ⇒ `null`（本函数的调用方要拿它去判机制/装 preset ⇒ 空壳等于"探不到"）。
+  const hit = resolveDshScope({ argv, env, home, exists, readdir, npmRootG, pathProbe, npxDirs })
+  return hit && !hit.stale ? { dir: hit.scope, from: hit.how } : null
+}
+
+/**
+ * 由**目标 scope** 推导 `dsh` 可执行入口的候选序列（**唯一实现**；顺序即优先级）。
+ *
+ * | scope 形态 | 对应 bin |
+ * |---|---|
+ * | 标准 node 布局 `<prefix>/lib/node_modules/@deepseek-ai` | `<prefix>/bin/dsh`（homebrew / 官方 pkg） |
+ * | 邻居布局 `<dir>/node_modules/@deepseek-ai` | `<dir>/bin/dsh`（客户机 `~/.local/node/…`） |
+ * | **平铺 / `--prefix` / `npx` 布局** | **`<dir>/node_modules/.bin/dsh`**（预检树、`_npx/<hash>/…`） |
+ *
+ * 平铺档由来的完整交代见文件头（P1-0 暂存 → P1-3 上移，bootcheck 侧副本已删）。
+ * @param {string} scopeDir
+ * @returns {string[]}
+ */
+export function scopeBinCandidates(scopeDir) {
+  if (!scopeDir) return []
+  const cands = []
+  const m = /^(.*)\/lib\/node_modules\/@deepseek-ai\/?$/.exec(scopeDir)
+  if (m) cands.push(join(m[1], 'bin', 'dsh')) // 标准 node 布局（homebrew / node 官方包）
+  cands.push(join(dirname(dirname(scopeDir)), 'bin', 'dsh')) // 邻居布局兜底
+  cands.push(join(dirname(scopeDir), '.bin', 'dsh')) // 平铺布局（预检树 / npx 缓存）
+  return cands
+}
+
+/**
+ * **按目标 scope 解析**被测 `dsh`（命中存在的候选即返回；一个都不存在 ⇒ **null**，
+ * ⛔ **不掺** PATH/全局兜底）。
+ *
+ * 与 `resolveDshBin()` 的分工：后者是"**给我一个能跑的 dsh**"（PATH → 推导 → 全局兜底）；
+ * 本函数是"**这个 scope 自带的那个 dsh 是谁**"——插件预检（`plugin-bootcheck`）的硬前置需要一个
+ * **与目标 scope 同源**的二进制，掺进 PATH 上那个别的版本就等于把"宿主↔scope 不同源"制造出来
+ * （实测：宿主 0.1.7 + 插件 0.2 ⇒ 0.2 的 peer 门禁把 profile 插件行**逐条** disable ×110，
+ * 输出与"Argent 坏了"无法区分）。
+ *
+ * ⚠️ **住在这里的原因（P1-3 收口，2026-10-12）**：候选序列的唯一实现是 {@link scopeBinCandidates}
+ * （本文件），而本函数只是它的"取第一个存在的"。P1-0 曾把这段逻辑放在
+ * `scripts/lib/bootcheck-wiring.mjs`（宿主预检的判据文件），但那个文件被
+ * `scripts/tests/kernel-purity.test.mjs` 显式认领为 **L1**（"纯 node 内建、零宿主 import"），
+ * 而按该门禁的既有约定 `scripts/lib/dsh-*.mjs` 是 **L2**（宿主运维档）⇒ **L1 不得 import
+ * `dsh-*` 模块**。两条纪律（"候选序列只许一份实现" + "L1 零宿主 import"）同时成立的办法就是
+ * 把本函数搬进真源（L2）：bootcheck 侧不再有副本，也不必为绕过门禁抬任何基线。
+ * 回归：`scripts/tests/bootcheck-wiring.test.mjs` 的 C1/C2/C7 + `scripts/tests/dsh-scope-resolve.test.mjs`。
+ */
+export function resolveBootcheckBin(scopeDir, { exists = existsSync } = {}) {
+  return scopeBinCandidates(scopeDir).find((c) => exists(c)) || null
+}
+
+/**
+ * 解析 `dsh` 可执行入口。
+ *
+ * ⚠️ 别用「scope 上跳两级 + bin/dsh」—— 实测两种布局都会算错（2026-09-28）：
+ *   开发机 scope `/opt/homebrew/lib/node_modules/@deepseek-ai` → 上跳两级得 `/opt/homebrew/lib`（错）
+ *   客户机 scope `~/node/lib/node_modules/@deepseek-ai`        → 上跳两级得 `~/node/lib`（错）
+ * 正确关系是 `<prefix>/lib/node_modules/@deepseek-ai` 对应 `<prefix>/bin/dsh`：
+ *   homebrew → `/opt/homebrew/bin/dsh`；客户机 → `~/node/bin/dsh`。
+ * 优先级：显式参数/环境变量 → PATH 上的 dsh（用户实际在用的那个最可靠）→ 按 scope 推导
+ *        （标准 → 邻居 → **平铺**）→ 硬编码全局兜底。
+ */
+export function resolveDshBin({ argv = process.argv, env = process.env, scopeDir = null, exists = existsSync, pathProbe = defaultPathProbe } = {}) {
+  const explicit = argValue(argv, '--global-bin') || env.DSH_BIN
+  if (explicit) return explicit
+  try {
+    const onPath = pathProbe()
+    if (onPath && exists(onPath)) return onPath
+  } catch { /* dsh 不在 PATH（cron/launchd 常见）→ 继续 */ }
+  // ⚠️ `resolveDshScope()` 自 F1 修复起返回 `{scope,…} | null` ⇒ 这里**必须取 `.scope`**；
+  //    取不到（null / 空壳）⇒ 空串（`scopeBinCandidates('')` 返回空候选 ⇒ 直接走下面三条硬编码兜底）。
+  const hit = scopeDir ? { scope: scopeDir } : resolveDshScope({ argv, env })
+  const scope = hit && !hit.stale ? hit.scope : ''
+  const cands = scopeBinCandidates(scope)
+  cands.push(
+    '/opt/homebrew/bin/dsh',
+    join(env.HOME || homedir(), 'node', 'bin', 'dsh'),
+    '/usr/local/bin/dsh',
+  )
+  return cands.find((c) => exists(c)) || cands[0]
+}

package/engine/scripts/lib/dsh-snapshot-path.mjs

@@ -0,0 +1,35 @@
+/**
+ * dsh 版本快照的**真实落点**解析（唯一真源：升级器加载与打印共用这一份）。
+ *
+ * 由来（2026-10-12 P1-0，审计 §C.1 #8）：升级器原来打印
+ * `快照: ${snapshotFile || join(LOCK_DIR, target + ".json")}` ——
+ * 候选线（未晋级）的快照实际在 `dsh-version-lock/candidate/<ver>.json`，
+ * 打印出来的却是**根目录**路径。**加载**逻辑本来认 candidate（`:208`），
+ * **打印**却编了另一个路径 ⇒ 排障时按打印去找，必然找不到，白跑一趟。
+ *
+ * 现在：加载与打印都调 {@link locateSnapshot}，命中即给**真路径 + 它在哪一档**；
+ * 都没有 ⇒ `path: null` 并附**找过哪些路径**（由调用方明说"未找到快照"）。
+ *
+ * ⚠️ 本文件只做路径判据，**不改写快照、不碰晋级逻辑**（晋级是人工/独立批次的事）。
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @param {string} lockDir  `dsh-version-lock` 目录
+ * @param {string|null} target 目标版本（如 `0.2.0-rc.2`）
+ * @param {string|null} explicitFile 显式 `--snapshot <file>`（优先，且**不检查存在性**——保持旧行为：不存在即报错）
+ * @param {(p:string)=>boolean} exists 注入以便纯夹具测试
+ * @returns {{path:string|null, tier:string|null, searched:string[]}}
+ */
+export function locateSnapshot(lockDir, target, explicitFile = null, exists = existsSync) {
+  if (explicitFile) return { path: explicitFile, tier: '显式 --snapshot', searched: [explicitFile] }
+  const cands = [
+    { path: join(lockDir, `${target}.json`), tier: '已晋级（dsh-version-lock/ 根）' },
+    { path: join(lockDir, 'candidate', `${target}.json`), tier: '候选·未晋级（dsh-version-lock/candidate/）' },
+  ]
+  const searched = cands.map((c) => c.path)
+  if (!target) return { path: null, tier: null, searched }
+  for (const c of cands) if (exists(c.path)) return { ...c, searched }
+  return { path: null, tier: null, searched }
+}

package/engine/scripts/lib/dsh-versions.mjs

@@ -0,0 +1,96 @@
+/**
+ * dsh"已验证版本清单"的解析与挑选（**唯一真源**，纯函数，可离线测试）。
+ *
+ * 规则（2026-09-28 补）：
+ *   · `dsh-version-lock/*.json`      = **已验证可用**版本（安装器会从里面挑最高的自动装）；
+ *   · `dsh-version-lock/candidate/`  = 已做升级前审查、**尚未验收**（隔离试跑 + 五项复核未过）
+ *     的候选版本 ⇒ **绝不参与自动挑选**。
+ *
+ * 由来：0.1.7-rc.2 的快照刚生成就被放进 lock 根目录，而 `pickLatestVerified()` 取最高版本 ⇒
+ * 任何**新装机**（含未来新客户）会自动装 0.1.7 —— 但隔离试跑已证明该版本上我们的 13 个
+ * preset **全部挂不上**（0.1.7 改成"preset = 组合里的一行插件"，不再扫描目录）⇒
+ * 新机器一装就是坏的。候选与已验证必须物理分开，不能靠人记得。
+ */
+
+/**
+ * **内置已验证版本基线**（安装器读不到 lock 目录时用它，例如全新机器上还没克隆仓库）。
+ *
+ * ⚠️ 纪律（缺陷 2，2026-10-12 真机实测）：**列表必须包含 `dsh-version-lock/` 里已晋级的最高版本**，
+ * 否则现役版本会被报成"未在已验证版本列表"（winpc 现场：dsh 0.1.7-rc.2 是当时**唯一现役**版本，
+ * 却因为安装器跑在 boot 克隆里、`~/.argent-dsh` 还不存在而走了这份 fallback ⇒ 列表里没有 0.1.7-rc.2
+ * ⇒ 客户看到一条毫无意义的告警）。防漂移门禁 = `verifiedListGaps()`（回归
+ * `scripts/tests/dsh-verified-list.test.mjs` 钉住"缺项即红"）。
+ */
+export const DSH_VERIFIED_FALLBACK = ['0.1.0-rc.6', '0.1.0-rc.7', '0.1.1-rc.1', '0.1.5-rc.1', '0.1.7-rc.2']
+
+/**
+ * **防漂移门禁**：`verified`（安装器实际会用的清单）是否覆盖 `lockDir` 里**已晋级**的每个版本。
+ *
+ * 判据刻意是"**全部**已晋级版本"而不是只有最高版本 —— 缺任何一个都说明列表与 lock 漂移了
+ * （只为"最高版本"设卡时，漏掉一个中间版本仍然会被放过去）。
+ * `candidate/` 下的快照**不参与**（它们是"已审查、未验收"，见 `listCandidateVersions`）。
+ * @returns {{ok:boolean, highest:string|null, promoted:string[], missing:string[]}}
+ */
+export function verifiedListGaps(verified, lockDir, io) {
+  const promoted = [...new Set(listVerifiedVersions(lockDir, io))].sort(cmpVer)
+  const missing = promoted.filter((v) => !(verified || []).includes(v))
+  return { ok: missing.length === 0, highest: promoted.length ? promoted[promoted.length - 1] : null, promoted, missing }
+}
+
+/** 版本比较：0.1.5-rc.1 < 0.1.7-rc.2 < 0.2.0-rc.1（无 rc 号视为 Infinity = 正式版更大）。 */
+export function cmpVer(a, b) {
+  const pa = String(a).split('-')
+  const pb = String(b).split('-')
+  const na = pa[0].split('.').map(Number)
+  const nb = pb[0].split('.').map(Number)
+  for (let i = 0; i < 3; i += 1) {
+    if ((na[i] || 0) !== (nb[i] || 0)) return (na[i] || 0) > (nb[i] || 0) ? 1 : -1
+  }
+  const ra = /(\d+)/.exec(pa[1] || '')
+  const rb = /(\d+)/.exec(pb[1] || '')
+  const ka = ra ? Number(ra[1]) : Infinity
+  const kb = rb ? Number(rb[1]) : Infinity
+  if (ka !== kb) return ka > kb ? 1 : -1
+  return 0
+}
+
+/**
+ * 列出**已验证**版本（只读 lockDir 顶层的 *.json；子目录一律忽略）。
+ * @param {string} lockDir
+ * @param {(p: string) => boolean} exists
+ * @param {(p: string) => string[]} readdir
+ * @param {(p: string) => string} read
+ */
+export function listVerifiedVersions(lockDir, { exists, readdir, read }) {
+  if (!exists(lockDir)) return []
+  const out = []
+  for (const f of readdir(lockDir)) {
+    if (!f.endsWith('.json')) continue
+    try {
+      const target = JSON.parse(read(joinPath(lockDir, f))).target
+      if (target) out.push(target)
+    } catch { /* 坏文件跳过 */ }
+  }
+  return out
+}
+
+/** 候选目录（已审查未验收）：永不参与自动挑选。 */
+export const CANDIDATE_DIR = 'candidate'
+
+/** 挑出最新的已验证版本；无清单时返回 null（调用方用自己的 fallback）。 */
+export function pickLatestVerified(lockDir, io) {
+  const vers = listVerifiedVersions(lockDir, io)
+  if (!vers.length) return null
+  return [...vers].sort(cmpVer)[vers.length - 1]
+}
+
+/** 列出候选版本（`candidate/` 下的快照）——仅供人工/文档查询，不参与挑选。 */
+export function listCandidateVersions(lockDir, { exists, readdir, read }) {
+  const dir = joinPath(lockDir, CANDIDATE_DIR)
+  if (!exists(dir)) return []
+  return readdir(dir).filter((f) => f.endsWith('.json'))
+    .map((f) => { try { return JSON.parse(read(joinPath(dir, f))).target } catch { return null } })
+    .filter(Boolean)
+}
+
+function joinPath(a, b) { return `${a.replace(/\/$/, '')}/${b}` }