@moonquake2004/dsh-security 0.1.7 → 0.2.0

package/src/checks/ss4-session-integrity.mjs

@@ -18,7 +18,7 @@ import { existsSync, statSync } from 'node:fs';
 import { Severity } from '../protocol/severity.mjs';
 import { CheckPhase } from '../protocol/phase.mjs';
 import { pass, fail, skip } from '../protocol/check.mjs';
-import { scanSessionLines } from '../session-reader.mjs';
+import { scanSessionLines, extractEvent } from '../session-reader.mjs';
 
 const MIN_LINES = 10;
 
@@ -39,7 +39,8 @@ export async function run(sessionFile) {
   let totalLines = 0;
   let invalidJson = 0;
   let firstInvalidLine = null;
-  const orphanCalls = new Map(); // callId → line number
+  const orphanCalls = new Map(); // callId → { line, turn }
+  let maxTurn = -1;
   let resultCount = 0;
 
   await scanSessionLines(sessionFile, (line, lineNum) => {
@@ -55,17 +56,15 @@ export async function run(sessionFile) {
       return; // 无法 parse 的行跳过后续检查
     }
 
-    // 2. tool/call 与 tool/result 配对检查
-    const type = parsed.type;
-    if (type === 'tool/call') {
-      const callId = parsed.data?.callId;
-      if (callId) orphanCalls.set(callId, lineNum);
-    } else if (type === 'tool/result') {
-      const callId = parsed.data?.callId;
-      if (callId) {
-        orphanCalls.delete(callId); // 配对成功
-        resultCount++;
-      }
+    // 2. tool/call 与 tool/result 配对检查（字段路径见 docs/session-shape-v3.md）
+    //    v3 中 tool/result 没有 data.callId，id 在 data.message.source.callId —— 旧写法导致 0 配对、
+    //    每个调用都被当成孤儿（2026-09 实测：健康会话被报 45 个孤儿）。
+    const ev = extractEvent(parsed);
+    // maxTurn 必须对**所有**事件更新（无 callId 的事件同样携带 turn），否则 in-flight 豁免判据失效
+    if (typeof ev.turn === 'number') maxTurn = Math.max(maxTurn, ev.turn);
+    if (ev.callId) {
+      if (ev.kind === 'call') orphanCalls.set(ev.callId, { line: lineNum, turn: ev.turn });
+      else if (ev.kind === 'result') { orphanCalls.delete(ev.callId); resultCount++; }
     }
   });
 
@@ -81,10 +80,13 @@ export async function run(sessionFile) {
   const issues = [];
   const refs = [];
 
-  // 汇总孤儿 tool/call
-  if (orphanCalls.size > 0) {
-    const samples = [...orphanCalls.entries()].slice(0, 5).map(([id, ln]) => `  行${ln}: callId=${id.slice(0, 16)}…`);
-    issues.push(`${orphanCalls.size} 个孤儿 tool/call（有调用无结果）：\n${samples.join('\n')}`);
+  // 汇总孤儿 tool/call —— 仅当该调用处在**已闭合的 turn** 中才算真孤儿。
+  // 活跃会话的最后一个 turn 天然可能有不配对的调用（正在执行 / 已中断），豁免之（对齐 dsh-doctor S1 的 in-flight 处理）。
+  const realOrphans = [...orphanCalls.entries()].filter(([, v]) => typeof v.turn === 'number' && v.turn < maxTurn);
+  const inflight = orphanCalls.size - realOrphans.length;
+  if (realOrphans.length > 0) {
+    const samples = realOrphans.slice(0, 5).map(([id, v]) => `  行${v.line}: callId=${id.slice(0, 16)}…`);
+    issues.push(`${realOrphans.length} 个孤儿 tool/call（有调用无结果）：\n${samples.join('\n')}`);
     refs.push('#3234');
   }
 
@@ -96,7 +98,7 @@ export async function run(sessionFile) {
 
   if (issues.length === 0) {
     return pass(id, Severity.HIGH,
-      `会话日志完整性通过：${totalLines} 行，JSON 全有效，${resultCount} 个 tool/result 均已配对`);
+      `会话日志完整性通过：${totalLines} 行，JSON 全有效，${resultCount} 个 tool/result 已配对${inflight > 0 ? `（尾部 in-flight 未配对 ${inflight} 个，属正常）` : ''}`);
   }
 
   return fail(id, Severity.HIGH,

package/src/dsh-config.mjs

@@ -0,0 +1,204 @@
+/**
+ * DSH Security Framework — dsh 宿主配置读取（SP5 用）
+ *
+ * SP5 需要报告**真实**的能力面，其中宿主侧两项是权威来源：
+ *   1. `$DSH_HOME/settings.yaml` 的 `permission` 命名空间
+ *      （schema 仅 `{ defaultPreset }`，见 dsh-permission-presets/lib/index.js:24,121）
+ *   2. `@deepseek-ai/dsh-base/cordis.patch.yml` 的
+ *      `sandbox-policy.config.mode` / `approval.config.policy` / `permission.config.presets`
+ *      （dsh-base/cordis.patch.yml:204-242）
+ * 二者都在 profile 之外，必须按模块回退锚点解析（`$DSH_HOME/profiles/node_modules`）。
+ *
+ * 这里只实现读取这两个文件所需的最小 YAML 子集解析（块式 `key:` / `key: value` / 缩进层级），
+ * 不引入依赖；块级解析用于定位 `- id: <row>` 行及其 `config:` 子树。
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** 最小块扫描：<缩进, 文本> 列表，跳过空行与整行注释 */
+function blockLines(text) {
+  const info = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const indent = raw.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+    info.push({ indent, text: raw.trim(), line: i + 1 });
+  }
+  return info;
+}
+
+/**
+ * 取 `- id: <rowId>` 行开始的块（到下一条同级 `- id:` 为止），
+ * 返回其配置子树文本（不含 id 行本身）。找不到返回 null。
+ */
+export function rowBlock(text, rowId) {
+  const info = blockLines(text);
+  const want = `id: ${rowId}`;
+  let start = -1, end = info.length, rowIndent = 0;
+  for (let i = 0; i < info.length; i++) {
+    const s = info[i].text.replace(/^-\s*/, '');
+    if (s === want || s === `${want} ` || s.startsWith(`${want} `)) {
+      start = i; rowIndent = info[i].indent;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  const reId = /^-?\s*id:\s/;
+  for (let j = start + 1; j < info.length; j++) {
+    if (info[j].indent <= rowIndent && reId.test(info[j].text)) { end = j; break; }
+  }
+  return info.slice(start, end);
+}
+
+/**
+ * 在一个行的块里取某个顶层键的子树。
+ * @returns {Array<{indent:number,text:string,line:number}>|null}
+ */
+export function keyBlock(block, key) {
+  if (!block) return null;
+  const idx = block.findIndex(l => l.text.startsWith(`${key}:`));
+  if (idx < 0) return null;
+  const base = block[idx].indent;
+  const out = [block[idx]];
+  for (let j = idx + 1; j < block.length; j++) {
+    if (block[j].indent <= base) break;
+    out.push(block[j]);
+  }
+  return out;
+}
+
+/** 在块里取 `key: value` 的裸标量（含引号/`!!js` 表达式原样返回） */
+export function scalarIn(block, key) {
+  if (!block) return null;
+  for (const l of block) {
+    const m = new RegExp(`^${key}:\\s*(.*)$`).exec(l.text);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+function unquote(v) {
+  if (v === null || v === undefined) return null;
+  const t = String(v).trim();
+  if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) return t.slice(1, -1);
+  return t;
+}
+
+/**
+ * 从 `!!js` 表达式里抽出字面量（`a ?? 'b'` / 三元 / 纯字面量）。
+ * 只做字面量识别，**不求值**——求值会让检查本身变成代码执行面。
+ * `decisive=true` 表示表达式无条件返回该字面量（无 env 读取 / 无三元）。
+ * @returns {{literal: string|null, expression: string|null, decisive: boolean}|null}
+ */
+export function evalScalarLiteral(raw) {
+  if (raw === null || raw === undefined) return null;
+  const t = String(raw).trim();
+  if (!t) return null;
+  if (t.startsWith('!!js')) {
+    const expression = t.replace(/^!!js\s*/, '').trim();
+    const strings = [...expression.matchAll(/'([^']*)'|"([^"]*)"/g)].map(m => m[1] ?? m[2]).filter(s => s !== '');
+    const hasEnv = /process\.env/.test(expression);
+    const hasTernary = /\?/.test(expression) && /:/.test(expression);
+    return {
+      literal: strings.length > 0 ? strings[0] : null,
+      expression,
+      decisive: strings.length === 1 && !hasEnv && !hasTernary,
+    };
+  }
+  return { literal: unquote(t), expression: null, decisive: !/process\.env/.test(t) };
+}
+
+/** 取文本顶层某个 key 的块 */
+export function topLevelKeyBlock(text, key) {
+  return keyBlock(blockLines(text), key);
+}
+
+/**
+ * 读取 settings.yaml 的 `permission` 命名空间。
+ * @returns {{present:boolean, defaultPreset:string|null, raw:string|null, file:string|null}}
+ */
+export function readPermissionSettings(dshHome) {
+  const file = dshHome ? join(dshHome, 'settings.yaml') : null;
+  if (!file || !existsSync(file)) return { present: false, defaultPreset: null, raw: null, file };
+  let text;
+  try { text = readFileSync(file, 'utf8'); } catch { return { present: false, defaultPreset: null, raw: null, file }; }
+  const block = topLevelKeyBlock(text, 'permission');
+  if (!block) return { present: false, defaultPreset: null, raw: null, file };
+  const raw = scalarIn(block, 'defaultPreset');
+  return { present: true, defaultPreset: unquote(raw), raw, file };
+}
+
+/**
+ * 解析 dsh-base 的 cordis.patch.yml，取出真实的沙箱/审批/预设配置。
+ * @returns {object|null} 文件不存在时 null
+ */
+export function readHostSandboxConfig(basePatchPath) {
+  if (!basePatchPath || !existsSync(basePatchPath)) return null;
+  let text;
+  try { text = readFileSync(basePatchPath, 'utf8'); } catch { return null; }
+
+  const policyBlock = rowBlock(text, 'sandbox-policy');
+  const approvalBlock = rowBlock(text, 'approval');
+  const permissionBlock = rowBlock(text, 'permission');
+  const sandboxBlock = rowBlock(text, 'sandbox');
+
+  const policyCfg = keyBlock(policyBlock, 'config');
+  const approvalCfg = keyBlock(approvalBlock, 'config');
+  const permissionCfg = keyBlock(permissionBlock, 'config');
+
+  const presets = {};
+  const presetsBlock = keyBlock(permissionCfg, 'presets');
+  if (presetsBlock) {
+    // 顶层 preset 名 = 缩进为 presets 直属子级的 key
+    const presetsIndent = presetsBlock[0].indent;
+    let current = null;
+    for (const l of presetsBlock.slice(1)) {
+      if (l.indent === presetsIndent + 2 && /^[A-Za-z0-9_-]+:\s*$/.test(l.text)) {
+        current = l.text.slice(0, -1);
+        presets[current] = {};
+        continue;
+      }
+      if (current && l.indent > presetsIndent) {
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(l.text);
+        if (m) presets[current][m[1]] = unquote(m[2]);
+      }
+    }
+  }
+
+  const modeRaw = scalarIn(policyCfg, 'mode');
+  const approvalRaw = scalarIn(approvalCfg, 'policy');
+
+  return {
+    path: basePatchPath,
+    sandboxMode: evalScalarLiteral(modeRaw),
+    approvalPolicy: evalScalarLiteral(approvalRaw),
+    sandboxService: scalarIn(sandboxBlock, 'name') ? unquote(scalarIn(sandboxBlock, 'name')) : null,
+    presets,
+    presetsRaw: presetsBlock ? 'present' : 'absent',
+  };
+}
+
+/**
+ * 在候选 node_modules / 包目录中定位 dsh-base 的 cordis.patch.yml。
+ * 复用模块回退锚点语义：profile → 逐级父目录 → CLI 安装根。
+ */
+export function resolveBasePatch(profileDir, cliRoots = []) {
+  const cands = [];
+  let dir = profileDir;
+  for (let i = 0; i < 6 && dir; i++) {
+    cands.push(join(dir, 'node_modules', '@deepseek-ai', 'dsh-base', 'cordis.patch.yml'));
+    const parent = dir.replace(/[/\\][^/\\]*$/, '');
+    if (!parent || parent === dir) break;
+    dir = parent;
+  }
+  for (const root of cliRoots) {
+    cands.push(join(root, 'node_modules', '@deepseek-ai', 'dsh-base', 'cordis.patch.yml'));
+    cands.push(join(root, 'cordis.patch.yml'));
+  }
+  for (const c of cands) {
+    try { if (existsSync(c)) return c; } catch { /* 继续 */ }
+  }
+  return null;
+}

package/src/index.mjs

@@ -26,6 +26,9 @@ export { sp7Check } from './checks/sp7-client-syntax.mjs';
 export { sp8Check } from './checks/sp8-dist-tag-health.mjs';
 export { sp9Check } from './checks/sp9-dual-instance-guard.mjs';
 export { sp10Check } from './checks/sp10-poison-pattern.mjs';
+export { sp11Check } from './checks/sp11-patch-security-override.mjs';
+export { sp12Check } from './checks/sp12-config-as-code-tag.mjs';
+export { sp13Check } from './checks/sp13-tools-mode-sandbox.mjs';
 
 // Layer 2: Runtime Checks
 export { sr1Check } from './checks/sr1-sandbox-violation.mjs';

package/src/install-tree.mjs

@@ -0,0 +1,293 @@
+/**
+ * DSH Security Framework — 安装树 / profile 布局解析（SP5、SP9 共用）
+ *
+ * 背景（2026-09 上游兼容审计 R5/R7）：
+ * 0.1.5 起 `$DSH_HOME/profiles/node_modules` 是 **dsh 自有的符号链接镜像**，
+ * 由 `healProfilesModuleFallback`（dsh-app-boot）写成 CLI 安装闭包的镜像；
+ * 而 `$DSH_HOME/profiles/<name>/node_modules` 是 pnpm 真实安装目录。
+ * 两者语义完全相反，检查必须区分「符号链接镜像」与「真实目录副本」，
+ * 因此这里集中解析：
+ *   - 安装前缀（CLI 自身所在的 @deepseek-ai 目录）
+ *   - profile 布局（DSH_HOME / 当前 profile 名）
+ *   - 符号链接目标是否落在安装前缀内
+ */
+
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+
+/** 用 profile 目录内的解析器定位真实安装位置（可命中 profile 自身的 node_modules） */
+function requireFrom(baseDir) {
+  try { return createRequire(join(baseDir, '__dsh_security_probe__.js')); } catch { return null; }
+}
+
+/**
+ * 解析 CLI 安装的 @deepseek-ai 目录（安装前缀）。
+ * 顺序：显式参数 → 从 profileDir 解析 @deepseek-ai/dsh/package.json →
+ *       npm_node_execpath → DSH_HOME 镜像 → 常见全局前缀。
+ * @returns {string|null}
+ */
+export function resolveInstallPrefix(profileDir, explicit = undefined) {
+  if (explicit) return explicit;
+
+  const candidates = [];
+  if (profileDir) {
+    const req = requireFrom(profileDir);
+    if (req) {
+      try {
+        // @deepseek-ai/dsh/package.json → <prefix>/@deepseek-ai/dsh/package.json
+        candidates.push(dirname(dirname(req.resolve('@deepseek-ai/dsh/package.json'))));
+      } catch { /* 不在该解析路径 */ }
+      try {
+        candidates.push(dirname(dirname(req.resolve('@deepseek-ai/dsh-base/package.json'))));
+      } catch { /* 不在该解析路径 */ }
+    }
+  }
+  if (process.env.npm_node_execpath) {
+    // …/lib/node_modules/npm/bin/node-gyp-bin/… 或 …/lib/node_modules/npm/…
+    const parts = process.env.npm_node_execpath.split(sep);
+    const idx = parts.lastIndexOf('node_modules');
+    if (idx > 0) candidates.push(join(parts.slice(0, idx).join(sep), 'node_modules', '@deepseek-ai'));
+  }
+  if (process.env.DSH_HOME) {
+    for (const n of ['dsh', 'dsh-base']) {
+      const p = join(process.env.DSH_HOME, 'profiles', 'node_modules', '@deepseek-ai', n);
+      if (existsSync(join(p, 'package.json'))) candidates.push(dirname(p));
+    }
+  }
+  for (const n of ['dsh', 'dsh-base']) {
+    const p = join('/opt/homebrew/lib/node_modules/@deepseek-ai', n);
+    if (existsSync(join(p, 'package.json'))) { candidates.push(dirname(p)); break; }
+  }
+  for (const n of ['dsh', 'dsh-base']) {
+    const p = join('/usr/local/lib/node_modules/@deepseek-ai', n);
+    if (existsSync(join(p, 'package.json'))) { candidates.push(dirname(p)); break; }
+  }
+
+  for (const c of candidates) if (c && existsSync(c)) return c;
+  return null;
+}
+
+/**
+ * profile 目录布局：DSH_HOME 与当前 profile 名。
+ * 支持两种入参：`<dshHome>/profiles/<name>`（doctor 传入）与 `<dshHome>/profiles`（镜像根）。
+ *
+ * 注意：<dshHome> 会做 realpath 归一（macOS 下 `/var` → `/private/var`），
+ * 因此由本函数拼出的路径可能与调用方传入的 profileDir **写法不同**（指向同一实体）。
+ * 需要"把调用方路径也列进扫描范围"的检查，应自行把入参一并加入候选。
+ * @returns {{dshHome: string|null, profilesDir: string|null, profileName: string|null}}
+ */
+export function resolveProfileLayout(profileDir) {
+  let dir;
+  try { dir = realpathSync(profileDir); } catch { dir = profileDir; }
+  const parent = dirname(dir);
+  if (parent.endsWith(`${sep}profiles`) || parent.endsWith('/profiles')) {
+    // <dshHome>/profiles/<name> — 排除直接等于 profiles 的情况
+    const name = dir.slice(parent.length + 1);
+    if (name && name !== 'profiles') {
+      return { dshHome: dirname(parent), profilesDir: parent, profileName: name };
+    }
+  }
+  if (dir.endsWith(`${sep}profiles`) || dir.endsWith('/profiles')) {
+    return { dshHome: dirname(dir), profilesDir: dir, profileName: null };
+  }
+  return { dshHome: null, profilesDir: null, profileName: null };
+}
+
+/**
+ * 共享镜像目录 `<dshHome>/profiles/node_modules`。
+ * 对 `<dshHome>/profiles/<name>` 入参返回其父级镜像；对 `<dshHome>/profiles`
+ * 入参返回自身（该目录本身就是镜像根）。无法确定 DSH_HOME 时返回 null。
+ */
+export function resolveSharedMirrorDir(profileDir) {
+  const { dshHome } = resolveProfileLayout(profileDir);
+  if (!dshHome) return null;
+  return join(dshHome, 'profiles', 'node_modules');
+}
+
+/** 符号链接的解析后目标（相对链接按链接所在目录解析）；断链也返回字面目标 */
+export function resolveLinkTarget(linkPath, rawTarget) {
+  const abs = isAbsolute(rawTarget) ? rawTarget : resolve(dirname(linkPath), rawTarget);
+  try { return realpathSync(abs); } catch { return abs; }
+}
+
+/** 目标是否落在安装前缀内（前缀为 null 时按“无法判定”返回 null） */
+export function isInsidePrefix(target, prefix) {
+  if (!prefix) return null;
+  // 两侧都先做 realpath 归一（macOS 的 /var → /private/var 等别名），
+  // 否则显式注入的前缀与链接目标可能因路径别名而比较失败——那是误报，不是发现。
+  const canon = (p) => {
+    try { return realpathSync(p); } catch { return resolve(p); }
+  };
+  const norm = (p) => (p.endsWith(sep) ? p.slice(0, -1) : p);
+  const t = norm(canon(target));
+  const p = norm(canon(prefix));
+  return t === p || t.startsWith(p + sep);
+}
+
+/** 从候选 node_modules 目录中解析某个包的 package.json（内部使用） */
+function resolvePkgJson(nmDirs, pkgName) {
+  for (const nm of nmDirs) {
+    const pj = join(nm, pkgName, 'package.json');
+    if (existsSync(pj)) return pj;
+  }
+  try {
+    const req = requireFrom(nmDirs[0] ? dirname(nmDirs[0]) : process.cwd());
+    if (req) return req.resolve(`${pkgName}/package.json`);
+  } catch { /* fallthrough */ }
+  return null;
+}
+
+/** 读取版本号（内部使用） */
+function readVersion(pkgJsonPath) {
+  if (!pkgJsonPath) return null;
+  try { return JSON.parse(readFileSync(pkgJsonPath, 'utf8')).version || null; } catch { return null; }
+}
+
+/**
+ * 解析 CLI 实际提供的核心运行时版本（installation closure / 镜像链路）。
+ * 返回值同时给出解析路径，便于检查在 detail 中如实标注来源。
+ */
+export function resolveCoreVersions(profileDir) {
+  const nmDirs = [
+    join(profileDir, 'node_modules'),
+    resolveSharedMirrorDir(profileDir) ? join(resolveSharedMirrorDir(profileDir)) : null,
+    process.env.DSH_HOME ? join(process.env.DSH_HOME, 'profiles', 'node_modules') : null,
+  ].filter(Boolean);
+
+  const out = {};
+  for (const name of ['@deepseek-ai/dsh', '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-tools', '@deepseek-ai/dsh-session', '@deepseek-ai/dsh-agent-loop']) {
+    const pj = resolvePkgJson(nmDirs, name);
+    out[name] = { version: readVersion(pj), path: pj };
+  }
+  return out;
+}
+
+/** DSH_HOME：仅凭明确信号推断，绝不猜测用户家目录内容 */
+export function resolveDshHome(profileDir) {
+  const layout = resolveProfileLayout(profileDir);
+  if (layout.dshHome) return layout.dshHome;
+  if (process.env.DSH_HOME) return process.env.DSH_HOME;
+  return null;
+}
+
+/* ================= semver ================= */
+
+/**
+ * 尽力从安装树里取到真正的 node-semver（CLI 依赖闭包里有它，7.x）。
+ * 取不到时返回 null——调用方必须据此降级为「无法判定」，不得自行近似断言不兼容。
+ */
+export function resolveSemver(profileDir, cliRoots = []) {
+  const bases = [];
+  const mirror = profileDir ? resolveSharedMirrorDir(profileDir) : null;
+  if (mirror) bases.push(join(mirror, '@deepseek-ai', 'dsh-base'));
+  if (profileDir) bases.push(join(profileDir, 'node_modules', '@deepseek-ai', 'dsh-base'));
+  for (const r of cliRoots) bases.push(join(r, 'node_modules', '@deepseek-ai', 'dsh-base'));
+  for (const dir of [...bases, ...(profileDir ? [profileDir] : [])]) {
+    const req = requireFrom(dir);
+    if (!req) continue;
+    try {
+      const mod = req('semver');
+      if (mod && typeof mod.satisfies === 'function') return { mod, from: dir };
+    } catch { /* 继续找 */ }
+  }
+  return null;
+}
+
+const splitVer = (s) => String(s).trim().replace(/^v/, '').split('-')[0].split('.').map(n => Number(n) || 0);
+const isPre = (s) => String(s).includes('-');
+
+function cmpVer(a, b) {
+  const A = splitVer(a), B = splitVer(b);
+  for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] < B[i] ? -1 : 1;
+  const pa = isPre(a), pb = isPre(b);
+  if (pa !== pb) return pa ? -1 : 1;
+  if (pa && pb && a !== b) return a < b ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 无 node-semver 时的保守近似：只覆盖 `=` / 比较符 / `~` / `^` + `||` 的字面子集。
+ * @returns {boolean|null} null = 无法判定（绝不当成 false——那会凭空造出不兼容结论）
+ */
+export function approxSatisfies(v, range) {
+  const V = String(v).trim();
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(V)) return null;
+  let anyParseable = false;
+  for (const alt of String(range).split('||').map(s => s.trim()).filter(Boolean)) {
+    const m = /^(\^|~|>=|<=|>|<|=)?\s*(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\s*$/.exec(alt);
+    if (!m) continue;
+    anyParseable = true;
+    const op = m[1] || '=', B = m[2];
+    let inBase = false;
+    const [vA, vB, vC] = splitVer(V);
+    if (op === '=') inBase = cmpVer(V, B) === 0;
+    else if (op === '>=') inBase = cmpVer(V, B) >= 0;
+    else if (op === '>') inBase = cmpVer(V, B) > 0;
+    else if (op === '<=') inBase = cmpVer(V, B) <= 0;
+    else if (op === '<') inBase = cmpVer(V, B) < 0;
+    else if (op === '~') {
+      const [bA, bB] = splitVer(B);
+      inBase = vA === bA && vB === bB && cmpVer(V, B) >= 0;
+    } else if (op === '^') {
+      const [bA, bB, bC] = splitVer(B);
+      if (bA > 0) inBase = vA === bA && cmpVer(V, B) >= 0;
+      else if (bB > 0) inBase = vA === 0 && vB === bB && cmpVer(V, B) >= 0;
+      else inBase = vA === 0 && vB === 0 && cmpVer(V, B) >= 0 && (vC === bC || V === B);
+    }
+    if (!inBase) continue;
+    if (!isPre(V)) return true;
+    // 预发布版本：只有与比较符里的预发布 base 同 [major,minor,patch] 才可判定
+    if (isPre(B)) {
+      const [bA, bB, bC] = splitVer(B);
+      if (vA === bA && vB === bB && vC === bC) return true;
+    }
+    continue;
+  }
+  return anyParseable ? false : null;
+}
+
+/**
+ * 判定 `version` 是否满足 `range`。
+ * @returns {{satisfies: boolean|null, exact: boolean}} satisfies=null 表示无法判定
+ */
+export function checkRange(version, range, semverMod = null) {
+  if (!version || !range) return { satisfies: null, exact: false };
+  if (semverMod) {
+    try {
+      return { satisfies: Boolean(semverMod.satisfies(version, range, { includePrerelease: false })), exact: true };
+    } catch { return { satisfies: null, exact: false }; }
+  }
+  return { satisfies: approxSatisfies(version, range), exact: false };
+}
+
+/**
+ * 遍历 profile node_modules 中的候选包目录（含 scoped 包）。
+ * 与 SP5/SP8/SP10 的既有语义一致：跳过隐藏目录与 .bin。
+ * @returns {Array<{dir: string, name: string}>}
+ */
+export function listPackageDirs(nmDir) {
+  const out = [];
+  if (!existsSync(nmDir)) return out;
+  let entries;
+  try { entries = readdirSync(nmDir, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    if (!entry.name || entry.name.startsWith('.') || entry.name === '.bin') continue;
+    // 注意：pnpm 会为包建符号链接，这里必须按“可进入的目录”判断，不能只看 isDirectory()
+    const isDirLike = entry.isDirectory() || entry.isSymbolicLink();
+    if (!isDirLike) continue;
+    if (entry.name.startsWith('@')) {
+      const scopeDir = join(nmDir, entry.name);
+      let pkgs = [];
+      try { pkgs = readdirSync(scopeDir, { withFileTypes: true }); } catch { continue; }
+      for (const pkg of pkgs) {
+        if (!pkg.name || pkg.name.startsWith('.')) continue;
+        if (!pkg.isDirectory() && !pkg.isSymbolicLink()) continue;
+        out.push({ dir: join(scopeDir, pkg.name), name: `${entry.name}/${pkg.name}` });
+      }
+      continue;
+    }
+    out.push({ dir: join(nmDir, entry.name), name: entry.name });
+  }
+  return out;
+}