@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.1

package/lib/deploy-guard.mjs

@@ -0,0 +1,391 @@
+// tools\lib\deploy-guard.mjs —— 部署门禁共享件（参数白名单 / 逃逸 import 静态扫 / 部署位置冒烟 import）
+//
+// ❗来由（2026-09-16 23:21 DSH 崩溃事故，2026-09-17 推广）：某 deploy.mjs 收到不认识的 `--verify`
+//   被**静默忽略** → 以为在做只读检查，实际执行了真备份 + 真部署 + 内部 spawnSync dsh-restart.ps1
+//   硬重启（绕开 P0 闸门）；而部署进 profile 的模块用相对路径跨包 import（仓库里层级恰好对上、
+//   装进 profiles\web\node_modules 后指向不存在的包）→ dsh boot 期 ERR_MODULE_NOT_FOUND，
+//   120s 内连崩 3 次唤分身。教训：`node --check` 只查**语法**，查不出**解析期**失败。
+//   首版落地在 tools\dsh-butler-panel\{preflight-imports.mjs,deploy.mjs}（拷问修复·B 卡），本文件是
+//   同口径的共享实现，供其余 deploy.mjs 复用。
+//
+// 三个导出（纯函数 + 薄 IO，零外部依赖）：
+//   parseArgs(argv, known)             fail-closed 参数白名单：未知参数 → ok:false（调用方 rc=2 退出）
+//   findEscapingImports(srcDir, opts)  静态扫「相对 import 解析后逃出插件根」的写法 → 命中清单
+//   smokeImportAll(entityDir, libSpec) 以**部署位置**为解析上下文，逐模块冒烟 import（子进程隔离）
+//
+// 退出码口径（与 tools\dsh-butler-panel\deploy.mjs 对齐）：
+//   0 = 通过 · 1 = 门禁未过（拒绝部署）· 2 = 用法/参数错误
+//
+// 用法示例见各 deploy.mjs 接入段；本文件自身不写任何文件（除子进程无副作用）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export const EXIT = { OK: 0, GATE: 1, USAGE: 2 };
+
+// 递归扫描时一律跳过的目录（node_modules 是依赖闭包、_archive/_tmp 是历史与临时产物；
+// task-board-local 的 node_modules 还是 junction → 扫进去会顺着盘外闭包跑几十个包）。
+const DEFAULT_EXCLUDE_DIRS = new Set([
+  'node_modules', '.git', '.hg', '.svn', '_archive', '_tmp', 'dist', 'build',
+  'coverage', '.cache', '.dsh', '.venv', '__pycache__', 'snapshots', 'backups',
+]);
+const JS_EXT = new Set(['.mjs', '.js', '.cjs']);
+// 前端产物：浏览器 bundle 本来就不该在 node 里 import（真 import 必报 window is not defined）。
+const DEFAULT_SMOKE_SKIP = [/^client\.js$/, /\.browser\.js$/, /\.min\.js$/];
+
+// ───────────────────────────────────────────────────────────── 1) 参数白名单
+
+/**
+ * fail-closed 解析命令行参数。
+ * @param {string[]} argv           process.argv.slice(2)
+ * @param {Array<string|{flag:string, takesValue?:boolean, alias?:string}>} known 白名单
+ *        字符串 = 布尔开关；对象 = 可取值的参数（--src X 或 --src=X）
+ * @returns {{ok:boolean, unknown:string[], flags:Record<string,boolean>,
+ *            values:Record<string,string>, positionals:string[]}}
+ *          ok=false 时 unknown 为全部不认识的 token（调用方负责打印 + 以 rc=2 退出）
+ */
+export function parseArgs(argv, known = []) {
+  const spec = new Map();
+  for (const k of known) {
+    if (typeof k === 'string') spec.set(k, { takesValue: false });
+    else if (k && k.flag) {
+      spec.set(k.flag, { takesValue: !!k.takesValue });
+      if (k.alias) spec.set(k.alias, { takesValue: !!k.takesValue, aliasOf: k.flag });
+    }
+  }
+  const flags = {};
+  const values = {};
+  const unknown = [];
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok.startsWith('-')) { positionals.push(tok); continue; }
+    const eq = tok.indexOf('=');
+    const name = eq > 0 ? tok.slice(0, eq) : tok;
+    const s = spec.get(name);
+    if (!s) { unknown.push(tok); continue; }
+    const key = s.aliasOf ?? name;
+    if (s.takesValue) {
+      let v = eq > 0 ? tok.slice(eq + 1) : null;
+      if (v === null) { v = argv[i + 1] ?? null; i++; }
+      values[key] = v;
+      flags[key] = true;
+    } else if (eq > 0) {
+      unknown.push(tok); // 布尔开关不许带 =值（写错了要响，不要静默）
+    } else {
+      flags[key] = true;
+    }
+  }
+  // 位置参数一律拒绝：这些 deploy 脚本都不吃位置参数，静默吞掉正是事故形态。
+  unknown.push(...positionals);
+  return { ok: unknown.length === 0, unknown, flags, values, positionals };
+}
+
+/** 把 unknown 渲染成人话（各脚本拼自己的「只读模式请用 X」尾巴）。 */
+export function describeUnknown(unknown, known) {
+  const all = known.map((k) => (typeof k === 'string' ? k : k.flag)).join(' ');
+  return `不认识的参数：${unknown.join(' ')}（本脚本只认 ${all}）`;
+}
+
+// ───────────────────────────────────────────────────── 2) 逃逸 import 静态扫
+
+/**
+ * 归一化路径：**存在的部分走 realpath，不存在的尾巴接回去**。
+ * ⚠️ 必须两边都归一 —— 工作区里的目录 junction 很常见：只 realpath 一边会把
+ *    「逻辑路径 vs 物理路径」比成 ..\..\...，于是合法的 './state.js' 也被误判成逃逸（实测踩过）。
+ */
+export function normalizePath(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native ? fs.realpathSync.native(cur) : fs.realpathSync(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.resolve(p);
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * 去注释：注释内容替换成空格（保留换行与列位置），引号内原样保留。
+ * 目的 = 避免把注释里写的路径当成真 import（事故文件头注里就写着示例路径）。
+ * 简易状态机：支持 // 、/* *\/ 、'…'、"…"、`…`（模板串内的 ${} 不再细分，漏掉的由门禁②兜底）。
+ */
+export function stripComments(text) {
+  const out = [];
+  let i = 0;
+  let inBlock = false;
+  let quote = null;
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (inBlock) {
+      if (c === '*' && n === '/') { out.push('  '); i += 2; inBlock = false; continue; }
+      out.push(c === '\n' ? '\n' : ' ');
+      i++;
+      continue;
+    }
+    if (quote) {
+      if (c === '\\') { out.push(c, n === undefined ? '' : n); i += 2; continue; }
+      out.push(c);
+      i++;
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '/' && n === '*') { out.push('  '); i += 2; inBlock = true; continue; }
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') { out.push(' '); i++; }
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out.push(c); i++; continue; }
+    out.push(c);
+    i++;
+  }
+  return out.join('');
+}
+
+// 只认「import/export … from '…'」「import '…'」「import('…')」「require('…')」四种形态。
+const SPEC_RES = [
+  /(?:^|[^\w$.])(?:import|export)\b[^;]*?\bfrom\s*(['"])([^'"]+)\1/,
+  /(?:^|[^\w$.])import\s*(['"])([^'"]+)\1/,
+  /(?:^|[^\w$.])import\s*\(\s*(['"])([^'"]+)\1\s*\)/,
+  /(?:^|[^\w$.])require\s*\(\s*(['"])([^'"]+)\1\s*\)/,
+];
+
+/** 列出目录下全部 js/mjs/cjs（递归、排序、跳过黑名单目录）。 */
+export function listJsFiles(root, opts = {}) {
+  const { excludeDirs = DEFAULT_EXCLUDE_DIRS, exts = JS_EXT } = opts;
+  const out = [];
+  const walk = (d) => {
+    let ents = [];
+    try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.isSymbolicLink()) continue; // junction/链接不跟随（跨盘闭包、盘外目录）
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (!excludeDirs.has(e.name)) walk(full);
+      } else if (exts.has(path.extname(e.name))) {
+        out.push(full);
+      }
+    }
+  };
+  walk(root);
+  return out.sort();
+}
+
+/**
+ * 静态扫：srcDir 下 js/mjs/cjs 里「相对 import 解析后逃出 root」的写法。
+ * @param {string} srcDir 扫描起点 —— **只扫「会被复制进实体的那部分」**（各插件都是 lib/）。
+ *        传插件根会把工具脚本一起扫进来（deploy.mjs / restore.mjs 自己 import '../lib/dsh-home.mjs'
+ *        是合法姿势、且它们根本不进 profile）→ 自报假警，实测踩过。
+ * @param {{root?:string}} [opts] root = 逃逸判定的根 = **实体的根**（插件被装进 profile 后的那个目录）。
+ *        原地部署、不复制进 profile 的插件（如 tools\dsh-butler：整棵 tools 树是它的搬迁单位、
+ *        跨子目录引用是合法设计）可放宽到树根。两边都走 realpath 归一（junction 坑）。
+ *        跨目录引用的正解是 `file:///<绝对路径>` URL（绝对路径不计逃逸）。
+ * @returns {{root:string, scanned:number, specs:number, absolute:number,
+ *            bad:Array<{file:string,line:number,spec:string,resolved:string,text:string}>}}
+ */
+export function findEscapingImports(srcDir, opts = {}) {
+  const root = opts.root ?? srcDir;
+  const rootReal = normalizePath(root);
+  const files = listJsFiles(srcDir, opts);
+  const bad = [];
+  let specs = 0;
+  let absolute = 0;
+  for (const file of files) {
+    let raw = '';
+    try { raw = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    const lines = stripComments(raw).split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.includes('import') && !line.includes('require')) continue;
+      const seen = new Set();
+      for (const re of SPEC_RES) {
+        const m = re.exec(line);
+        if (!m || !m[2] || seen.has(m[2])) continue;
+        seen.add(m[2]);
+        const spec = m[2];
+        if (path.isAbsolute(spec)) { absolute++; continue; } // 绝对路径是 B 卡推荐的跨目录姿势，不算逃逸
+        if (!spec.startsWith('.')) continue;                 // 裸包名（走 node_modules 解析）
+        specs++;
+        const resolved = path.resolve(path.dirname(file), spec);
+        const rel = path.relative(rootReal, normalizePath(resolved));
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+          bad.push({
+            file: path.relative(srcDir, file),
+            line: i + 1,
+            spec,
+            resolved,
+            text: raw.split(/\r?\n/)[i].trim().slice(0, 200),
+          });
+        }
+      }
+    }
+  }
+  return { root, scanned: files.length, specs, absolute, bad };
+}
+
+// ─────────────────────────────────────────── 3) 部署位置冒烟 import（子进程）
+
+// 子进程内跑的两段代码（代码走 stdin，路径走 env —— 无引号/转义地狱）。
+// 快路径 · 批量：一个进程 import 全部模块，结果用 `DG_RESULT:` 前缀单行输出
+//   （用前缀而非裸 JSON，是为了容忍被 import 的模块自己往 stdout 打日志）。
+const BATCH_CODE = [
+  "const files = JSON.parse(process.env.DG_BATCH_FILES || '[]');",
+  "const out = [];",
+  "for (const item of files) {",
+  "  try { await import(item.url); out.push({ file: item.file, ok: true }); }",
+  "  catch (e) { out.push({ file: item.file, ok: false, err: String((e && (e.message || e)) || e) }); }",
+  "}",
+  "process.stdout.write('\\nDG_RESULT:' + JSON.stringify(out) + '\\n');",
+  "if (process.env.DG_EXIT_AFTER === '1') process.exit(0);",
+  "",
+].join('\n');
+
+// 慢路径 · 单模块：批量判失败（或进程崩/超时）时逐个定位，并区分「解析失败」与「挂住」。
+const SMOKE_CODE = [
+  "const url = process.env.DG_TARGET_URL;",
+  "try {",
+  "  await import(url);",
+  "} catch (e) {",
+  "  process.stderr.write('DG_IMPORT_FAIL: ' + String((e && (e.message || e)) || e));",
+  "  process.exitCode = 1;",
+  "}",
+  "// 模块 import 成功但挂着事件循环（定时器/监听）时，DG_EXIT_AFTER=1 让子进程主动收尾，",
+  "// 以便把「解析失败」与「解析成功但进程不退出」分开判（后者不该判 FAIL）。",
+  "if (!process.exitCode && process.env.DG_EXIT_AFTER === '1') process.exit(0);",
+  "",
+].join('\n');
+
+function spawnSmoke(file, timeoutMs, exitAfter) {
+  return spawnSync(process.execPath, ['--input-type=module'], {
+    input: SMOKE_CODE,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      DG_TARGET_URL: pathToFileURL(file).href,
+      DG_EXIT_AFTER: exitAfter ? '1' : '0',
+    },
+  });
+}
+
+function runBatchFast(items, timeoutMs) {
+  return spawnSync(process.execPath, ['--input-type=module'], {
+    input: BATCH_CODE,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      DG_BATCH_FILES: JSON.stringify(items),
+      DG_EXIT_AFTER: '1', // 批量模式只回答「能否全部解析」，import 完立刻收尾（免被定时器拖住）
+    },
+  });
+}
+
+/** 从（可能被模块日志污染的）stdout 里取最后一条 DG_RESULT 行。 */
+function extractBatchResult(stdout) {
+  const marker = 'DG_RESULT:';
+  const i = (stdout ?? '').lastIndexOf(marker);
+  if (i < 0) return null;
+  const line = stdout.slice(i + marker.length).split(/\r?\n/)[0];
+  try {
+    const arr = JSON.parse(line);
+    return Array.isArray(arr) ? arr : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 以**部署位置**为解析上下文，逐个 import lib 里的模块。
+ * 关键点：import 的是**实体目录里的那个文件**（file URL），模块内部的相对 import 才会按实体
+ * 位置解析 —— 这正是「仓库里跑得通、装进 profile 就崩」的暴露面。子进程隔离：模块若有
+ * 副作用/挂住事件循环，不会污染部署进程。
+ * @param {string} entityDir 部署实体目录（必须是真实存在的路径；原地部署的插件传源码目录自身）
+ * @param {string|{dir?:string, skip?:RegExp[], timeoutMs?:number}} [libSpec='lib']
+ * @param {{dir?:string, skip?:RegExp[], timeoutMs?:number, only?:RegExp}} [opts]
+ * @returns {{dir:string, error:string|null, total:number, skipped:number,
+ *            bad:Array<{file:string,err:string,timeout:boolean}>, results:Array<{file:string,ok:boolean,ms:number}>}}
+ */
+export function smokeImportAll(entityDir, libSpec = 'lib', opts = {}) {
+  const cfg = typeof libSpec === 'string' ? { ...opts, dir: libSpec } : { ...opts, ...libSpec };
+  const {
+    skip = DEFAULT_SMOKE_SKIP, timeoutMs = 20000, batchTimeoutMs = 90000,
+    batch = true, only = null,
+  } = cfg;
+  const ent = path.resolve(entityDir);
+  const libDir = path.isAbsolute(cfg.dir ?? 'lib') ? cfg.dir : path.join(ent, cfg.dir ?? 'lib');
+  const empty = { dir: libDir, error: null, mode: null, total: 0, skipped: 0, bad: [], results: [] };
+
+  if (!fs.existsSync(ent)) return { ...empty, error: '实体目录不存在：' + ent };
+  if (!fs.existsSync(libDir)) return { ...empty, error: '实体下没有 lib 目录：' + libDir };
+  // 解析上下文必须是实体目录里的文件：lib 不在实体之下 → 拒绝（防"扫了源码目录还以为在测实体"）
+  const relLib = path.relative(normalizePath(ent), normalizePath(libDir));
+  if (relLib.startsWith('..') || path.isAbsolute(relLib)) {
+    return { ...empty, error: 'lib 目录不在实体目录内（解析上下文错位）：' + libDir };
+  }
+
+  const files = listJsFiles(libDir).filter((f) => !only || only.test(path.relative(libDir, f)));
+  const targets = files.filter((f) => !skip.some((re) => re.test(path.relative(libDir, f))));
+  const skipped = files.length - targets.length;
+  const bad = [];
+  const results = [];
+
+  // 快路径：单进程批量 import 全部模块（dsh-butler 82 个模块从 ~18s 降到 ~2s）。
+  // 判据严格：**只有「批量说全部 ok」才算通过**，否则一律落慢路径逐个确认 —— 批量的假失败
+  // （模块间串扰）由慢路径澄清，批量的假成功不存在（每个模块都真 import 过）。
+  if (batch && targets.length > 1) {
+    const r = runBatchFast(
+      targets.map((f) => ({ file: path.relative(libDir, f), url: pathToFileURL(f).href })),
+      batchTimeoutMs,
+    );
+    const parsed = extractBatchResult(r.stdout ?? '');
+    if (parsed && parsed.length === targets.length && parsed.every((x) => x.ok)) {
+      return {
+        dir: libDir, error: null, mode: 'batch', total: targets.length, skipped, bad: [],
+        results: parsed.map((x) => ({ file: x.file, ok: true, ms: 0, hung: null })),
+      };
+    }
+  }
+
+  // 慢路径：逐模块（精确定位到文件 + 区分「解析失败」与「import 成功但挂着不退出」）
+  for (const f of targets) {
+    const rel = path.relative(libDir, f);
+    const t0 = Date.now();
+    let r = spawnSmoke(f, timeoutMs, false);
+    let timeout = !!(r.error || r.signal);
+    let hung = false;
+    if (timeout) {
+      // 第一次超时可能是「模块挂住事件循环」而非解析失败 → 用 import 完主动收尾再试一次区分。
+      const r2 = spawnSmoke(f, timeoutMs, true);
+      if (r2.status === 0) { r = r2; timeout = false; hung = true; }
+      else if (!(r2.error || r2.signal)) { r = r2; timeout = false; }
+    }
+    const ms = Date.now() - t0;
+    if (!timeout && r.status === 0) {
+      results.push({ file: rel, ok: true, ms, hung });
+      continue;
+    }
+    const err = timeout
+      ? `${r.error?.code ?? r.signal ?? '超时'}：${timeoutMs}ms 内未结束（import 后进程既不退出也不报错）`
+      : extractSmokeError(r.stderr ?? '') || `exit ${r.status}`;
+    bad.push({ file: rel, err, timeout });
+    results.push({ file: rel, ok: false, ms, hung: false });
+  }
+  return { dir: libDir, error: null, mode: 'per-module', total: targets.length, skipped, bad, results };
+}
+
+function extractSmokeError(stderr) {
+  const marker = stderr.indexOf('DG_IMPORT_FAIL: ');
+  let msg = marker >= 0 ? stderr.slice(marker + 'DG_IMPORT_FAIL: '.length) : stderr;
+  msg = msg.split(/\r?\n/).filter((l) => l.trim())[0] ?? '';
+  return msg.trim().slice(0, 300);
+}

package/lib/guard-http.mjs

@@ -0,0 +1,93 @@
+// ============================================================
+//  guard-http.mjs · 守护鱼/分身「HTTP 存活判据」单一真源（H1 · 2026-09-22）
+//  ------------------------------------------------------------
+//  ⚠️ 本模块**纯函数、零依赖、零 IO**（不 import 任何东西、不碰网络/进程/文件）：
+//     传输层（curl 调用形态）仍留在各消费者里（guard.mjs / repair.mjs），
+//     本模块只回答一个问题 —— **"这个 HTTP 响应算不算'服务活着'"**。
+//
+//  为什么需要它（2026-09-17 升级硬前置 · 实测钉死）：
+//    0.1.5-rc.2 起 dsh web 加了 cookie token 认证门：无 token 访问
+//    `http://127.0.0.1:<port>/` → **401**（带 token → 303 落 cookie）。
+//    旧判据 = 「必须 HTTP 200」（`(r.stdout||'').trim() === '200'`）⇒ 401 被判
+//    "服务没起来" ⇒ KILL → 拉起 → 再杀 的死循环：主包一升 0.1.5，守护鱼就会
+//    把生产 dsh 打进 KILL/CRASH。
+//
+//  口径（H1）：「**有 HTTP 应答即活**」，同时**保持 0.1.1-rc.2 线行为等价**
+//  （200 仍判活、真死仍判死）。逐码取择与理由：
+//    ┌ 状态码        判   理由
+//    │ 2xx (200/204) 活   原有唯一判活值，必须保持不变（0.1.1 线 200）
+//    │ 3xx (301/303) 活   0.1.5 带 token 访问 `/` = 303（重定向落 cookie）；
+//    │                   重定向 = 应用在正常处理请求，不是"没起来"
+//    │ 401           活   **本次改造核心**：token 认证门 —— 服务在监听，
+//    │                   并主动拒绝未认证请求（响应体 "dsh web authentication required"）
+//    │ 403           活   同属"授权类拒绝"：HTTP 服务确实在应答，只是不给内容；
+//    │                   与 401 同类（认得出的是"HTTP 服务在"，不是"内容对不对"）
+//    │ 404 等其它 4xx 死   0.1.1 与 0.1.5 的 `/` 都不会 404 ⇒ 出现 404 说明 3080 上的
+//    │                   监听者不是 dsh 本体（如端口被别的进程占了）⇒ 正需要"卡死→重启"；
+//    │                   取择 = 与旧口径一致（宁可误杀重拉，也不把"不是 dsh"当健康）
+//    │ 5xx           死   服务进程在但应用层报错/未就绪：保留旧"再探 → 必要时重启"语义，
+//    │                   并避免 START 阶段在 bundle 未就绪时过早判 OK
+//    │ 无应答/超时    死   与旧口径等价（curl 无输出/000/失败）
+//    │ 解析不了(abc) 死   fail-closed：宁可多探一轮，不把未知当健康
+//    └
+//
+//  消费者（H1 收敛后的全部读点，改口径只需改本文件）：
+//    ① 守护进程 guard.mjs   probeHttp() → waitHttpReady(START 路径) + 主循环 httpOk
+//                          （→ guard-core.mjs 的 STUCK?/kill-dsh 判据）
+//    ② 自愈分身 repair.mjs  probeHttp() → 现场诊断 ev.dsh.httpOk + relaunch 后就绪等待
+// ============================================================
+
+/** 口径版本（写进日志与报告，便于事后对照哪一版判据在跑） */
+export const RULE_VERSION = 'h1-20260922';
+
+/** 判活的状态码集合（唯一口径，别在消费者里另写判断） */
+export const ALIVE_CODES = [200, 204, 301, 302, 303, 307, 308, 401, 403];
+
+/** 判活规则文字说明（报告 / 日志 / 帮助文本共用） */
+export const ALIVE_RULE_TEXT = '2xx/3xx/401/403 = 活；404 等其它 4xx、5xx、无应答 = 不活';
+
+/**
+ * 把 curl `-w '%{http_code}'` 的原始输出解析成状态码。
+ * 取择：**严格三位数字**才算解析成功（curl 无应答时输出 `000`，非数字输出如 `abc`/空串一律 null）。
+ * @param {unknown} raw
+ * @returns {number|null} 0=无应答（000）… 599；null=解析不了
+ */
+export function parseHttpCode(raw) {
+  const s = String(raw ?? '').trim();
+  if (!/^\d{3}$/.test(s)) return null;
+  return Number(s);
+}
+
+/**
+ * 判活 + 给理由（消费者的唯一入口）。
+ * @param {unknown} raw curl 输出的状态码原串
+ * @returns {{ code: number|null, alive: boolean, reason: string, rule: string }}
+ *   reason ∈ ok-2xx | redirect-3xx | auth-401 | auth-403 | not-found-404 |
+ *            client-4xx | server-5xx | no-answer | unparsable
+ */
+export function judgeHttp(raw) {
+  const code = parseHttpCode(raw);
+  if (code === null) return { code: null, alive: false, reason: 'unparsable', rule: RULE_VERSION };
+  if (code === 0) return { code: 0, alive: false, reason: 'no-answer', rule: RULE_VERSION };
+  if (code >= 200 && code <= 299) return { code, alive: true, reason: 'ok-2xx', rule: RULE_VERSION };
+  if (code >= 300 && code <= 399) return { code, alive: true, reason: 'redirect-3xx', rule: RULE_VERSION };
+  if (code === 401) return { code, alive: true, reason: 'auth-401', rule: RULE_VERSION };
+  if (code === 403) return { code, alive: true, reason: 'auth-403', rule: RULE_VERSION };
+  if (code === 404) return { code, alive: false, reason: 'not-found-404', rule: RULE_VERSION };
+  if (code >= 400 && code <= 499) return { code, alive: false, reason: 'client-4xx', rule: RULE_VERSION };
+  if (code >= 500 && code <= 599) return { code, alive: false, reason: 'server-5xx', rule: RULE_VERSION };
+  return { code, alive: false, reason: 'unparsable', rule: RULE_VERSION };
+}
+
+/** 只要布尔（沿用旧 `probeHttp` 的返回形状，便于调用方最小改动） */
+export function isHttpAlive(raw) {
+  return judgeHttp(raw).alive;
+}
+
+/** 日志用一行描述，例如 `code=401 (auth-401)` / `no-answer` */
+export function describeHttp(raw) {
+  const j = judgeHttp(raw);
+  if (j.code === null) return `${j.reason}`;
+  if (j.code === 0) return 'no-answer (code=000)';
+  return `code=${j.code} (${j.reason})`;
+}

package/lib/pitfall-form-map.mjs

@@ -0,0 +1,130 @@
+// dsh-butler / lib/pitfall-form-map.mjs —— P4「错误码 / 签名 → 建议形态」映射表
+//
+// 为什么需要这张表（2026-09-12 主人点名）：
+//   `pitfall-score.mjs` 的 suggestForm 原先只按文本特征猜形态，实测跑偏——
+//   `AUDIT_NOT_PASSED`（真实成因：写保护区没先走 P5 审计）被猜成「路径存在性预检」check，
+//   方向完全不对。**已知错误码的坑，成因是确定的**，不应交给启发式猜。
+//
+// 口径（判定顺序，命中即返回，不再往下走）：
+//   ① 错误码精确命中本条表（code 字段 > sigKey 的第 2 段 > normText 中出现的 SCREAMING_SNAKE 码）
+//   ② 签名正则命中（sigRe；用于没有稳定错误码、只能靠签名特征认的坑）
+//   ③ 都没命中 → 回落 `pitfall-score.mjs` 的原启发式（行为与改动前完全一致）
+//
+// 形态只有三种（与方案 §4 P4 一致）：`check` 自动检查项 / `skill` 内联技能 / `persona` persona 铁律。
+// 本文件是**纯数据 + 纯函数**，不碰状态、不写盘。
+//
+// 维护：新增一行即可生效（无副作用、无需改 render / 面板）；改完跑 `_test/test-pitfall.mjs`。
+
+export const FORM_MAP_VERSION = '0.1.0';
+
+/**
+ * @typedef {object} FormRule
+ * @property {string} id        规则 id（进 why/日志，稳定可断言）
+ * @property {string[]} [codes] 命中的错误码（大写 SCREAMING_SNAKE）
+ * @property {RegExp} [sigRe]   签名/文本正则（无稳定错误码时用）
+ * @property {'check'|'skill'|'persona'} form 建议形态
+ * @property {string} why       给主人看的一句话理由（写清真实成因）
+ */
+
+/** @type {FormRule[]} */
+export const FORM_RULES = [
+  {
+    id: 'audit-not-passed',
+    codes: ['AUDIT_NOT_PASSED'],
+    form: 'skill',
+    why: '流程类（不是路径问题）：写 persona / 技能 / 核心启动链前必须「先落临时文件 → butler-audit-cli 审计 → 用 write 写同一内容」；建议内联进 persona-maintain / P5 写入守门人相关技能',
+  },
+  {
+    id: 'audit-hash-mismatch',
+    codes: ['AUDIT_HASH_MISMATCH'],
+    form: 'skill',
+    why: '流程类：审计凭证与被写内容 hash 绑定——一处一审计、改完再验 hash，staged 内容必须与写入内容逐字节一致；建议内联进 persona-maintain 技能',
+  },
+  {
+    id: 'fs-not-observed',
+    codes: ['FS_NOT_OBSERVED'],
+    form: 'persona',
+    why: '铁律级（全局、高频）：改/覆盖已存在文件前必须先 read；已进 persona【铁律·edit/write 必须先读】，此处不再新增检查项',
+  },
+  {
+    id: 'fs-stale-version',
+    codes: ['FS_STALE_VERSION'],
+    form: 'persona',
+    why: '铁律级（全局）：junction 路径与同文件多处修改必须重读后**串行 edit**（并行 edit 会互相刷新 mtime）；已进 persona 对应铁律',
+  },
+  {
+    id: 'search-failed',
+    codes: ['SEARCH_FAILED'],
+    form: 'check',
+    why: '路径假设类：rg/grep/glob 目标不存在或不可达，可做成"搜索前先验路径存在"的只读检查项',
+  },
+];
+
+/** 快速查码表（大小写不敏感）。 */
+const CODE_INDEX = new Map();
+for (const r of FORM_RULES) {
+  for (const c of r.codes ?? []) CODE_INDEX.set(String(c).toUpperCase(), r);
+}
+
+/** SCREAMING_SNAKE 错误码（至少含一个下划线，避免把 FsError 之类类名当码）。 */
+export const ERROR_CODE_RE = /\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g;
+
+/** 不是错误码的占位（signatureOf 在拿不到 code 时写 NO_CODE）。 */
+const NOT_A_CODE = new Set(['NO_CODE']);
+
+/**
+ * 按优先级提取这条坑里出现的错误码：code 字段 → sigKey 第 2 段 → 文本中出现的码。
+ * @param {object} pitfall
+ * @returns {string[]} 去重后的候选码（越靠前越权威）
+ */
+export function extractErrorCodes(pitfall) {
+  const out = [];
+  const push = (v) => {
+    const s = String(v ?? '').toUpperCase().trim();
+    if (!s || NOT_A_CODE.has(s)) return;
+    if (!/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/.test(s)) return;
+    if (!out.includes(s)) out.push(s);
+  };
+  push(pitfall?.code);
+
+  const sig = String(pitfall?.sigKey ?? '');
+  if (sig) {
+    const seg = sig.split('|')[1];
+    push(seg);
+    for (const m of sig.matchAll(ERROR_CODE_RE)) push(m[1]);
+  }
+  const text = String(pitfall?.normText ?? '');
+  if (text) for (const m of text.matchAll(ERROR_CODE_RE)) push(m[1]);
+  return out;
+}
+
+/**
+ * 查表：错误码优先，其次签名正则。
+ * @param {object} pitfall
+ * @returns {{form:'check'|'skill'|'persona', why:string, ruleId:string, via:'code'|'sig', matched:string}|null}
+ *          未命中返回 null（调用方回落启发式）
+ */
+export function lookupFormByMap(pitfall) {
+  const codes = extractErrorCodes(pitfall);
+  for (const c of codes) {
+    const rule = CODE_INDEX.get(c);
+    if (rule) return { form: rule.form, why: `【映射表 ${rule.id}】${rule.why}`, ruleId: rule.id, via: 'code', matched: c };
+  }
+  const hay = `${pitfall?.name ?? ''}|${pitfall?.code ?? ''}|${pitfall?.sigKey ?? ''}|${pitfall?.normText ?? ''}`;
+  for (const rule of FORM_RULES) {
+    if (rule.sigRe && rule.sigRe.test(hay)) {
+      return { form: rule.form, why: `【映射表 ${rule.id}】${rule.why}`, ruleId: rule.id, via: 'sig', matched: String(rule.sigRe) };
+    }
+  }
+  return null;
+}
+
+/** 该错误码是否在表内（面板/调试用）。 */
+export function isMappedCode(code) {
+  return CODE_INDEX.has(String(code ?? '').toUpperCase());
+}
+
+/** 表内全部错误码（单测断言用）。 */
+export function mappedCodes() {
+  return [...CODE_INDEX.keys()].sort();
+}