@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/lib/guard-http.mjs

@@ -1,93 +1,90 @@
-// ============================================================
-//  guard-http.mjs · 守护鱼/分身「HTTP 存活判据」单一真源（H1 · 2026-09-22）
-//  ------------------------------------------------------------
-//  ⚠️ 本模块**纯函数、零依赖、零 IO**（不 import 任何东西、不碰网络/进程/文件）：
-//     传输层（curl 调用形态）仍留在各消费者里（guard.mjs / repair.mjs），
-//     本模块只回答一个问题 —— **"这个 HTTP 响应算不算'服务活着'"**。
+// 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。
+// 它只回答一个问题：一次探测拿回来的状态码，能不能当作"服务在监听"。
+// 传输怎么探测（用 curl 还是内置 http、超时给多少）留在各自的调用方，本件不插嘴。
 //
-//  口径（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：宁可多探一轮，不把未知当健康
-//    └
+// 为什么不能只认 200：带 cookie token 认证的构建，匿名访问根路径会回 401 ——
+// 那恰恰证明 HTTP 层还站着、还在应答、只是拒绝没凭证的请求。若判据是"必须 200"，
+// 一个健康的进程会被当成死掉，杀死、拉起、再杀死，越修越坏。
 //
-//  消费者（H1 收敛后的全部读点，改口径只需改本文件）：
-//    ① 守护进程 guard.mjs   probeHttp() → waitHttpReady(START 路径) + 主循环 httpOk
-//                          （→ guard-core.mjs 的 STUCK?/kill-dsh 判据）
-//    ② 自愈分身 repair.mjs  probeHttp() → 现场诊断 ev.dsh.httpOk + relaunch 后就绪等待
-// ============================================================
+// 定下的口径（按顺序取第一条命中的）：
+//   2xx          活 —— 最老的口径，必须继续认
+//   3xx          活 —— 认证通过后落到 cookie 的跳转；重定向本身就是应用在处理请求
+//   401 / 403    活 —— 授权类拒绝，说明"有个 HTTP 服务在答话"
+//   404          不活 —— 正常部署下根路径不该 404；出现了说明占着端口的是别的东西
+//   其它 4xx     不活 —— 与老口径保持一致：宁可多探一轮重拉，也不把陌生应答当健康
+//   5xx          不活 —— 进程在但应用层还没就绪，保留"再探、必要时重启"
+//   000 / 非数字  不活 —— 无应答、超时、解析不了，一律不算活（未知不当健康）
+//
+// 状态码判定只写在这里：调用方拿 judgeHttp 的结果，别在业务代码里再写一遍整数比较。
 
-/** 口径版本（写进日志与报告，便于事后对照哪一版判据在跑） */
+/** 口径版本：写进日志与报告，事后能对上"当时跑的是哪一版判据" */
 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、无应答 = 不活';
 
+const DIGITS_3 = /^\d{3}$/;
+
+// 判定表：自上而下取第一条命中的。顺序本身是语义 —— 401/403/404 必须排在
+// "其它 4xx" 之前，否则永远轮不到它们。
+const VERDICT_TABLE = [
+  { reason: 'ok-2xx', alive: true, accept: (code) => code >= 200 && code <= 299 },
+  { reason: 'redirect-3xx', alive: true, accept: (code) => code >= 300 && code <= 399 },
+  { reason: 'auth-401', alive: true, accept: (code) => code === 401 },
+  { reason: 'auth-403', alive: true, accept: (code) => code === 403 },
+  { reason: 'not-found-404', alive: false, accept: (code) => code === 404 },
+  { reason: 'client-4xx', alive: false, accept: (code) => code >= 400 && code <= 499 },
+  { reason: 'server-5xx', alive: false, accept: (code) => code >= 500 && code <= 599 },
+];
+
+/** 统一的结果形状 —— 四个字段恒定，不按分支增减 */
+function report(code, alive, reason) {
+  return { code, alive, reason, rule: RULE_VERSION };
+}
+
 /**
- * 把 curl `-w '%{http_code}'` 的原始输出解析成状态码。
- * 取择：**严格三位数字**才算解析成功（curl 无应答时输出 `000`，非数字输出如 `abc`/空串一律 null）。
+ * 解析探测命令打印出来的状态码。
+ * 只认严格的三个数字：无应答时的 `000` 会解析成 0，`abc`、空串、`20x` 这类一律 null。
  * @param {unknown} raw
- * @returns {number|null} 0=无应答（000）… 599；null=解析不了
+ * @returns {number|null}
  */
 export function parseHttpCode(raw) {
-  const s = String(raw ?? '').trim();
-  if (!/^\d{3}$/.test(s)) return null;
-  return Number(s);
+  const text = String(raw ?? '').trim();
+  if (!DIGITS_3.test(text)) return null;
+  return Number(text);
 }
 
 /**
- * 判活 + 给理由（消费者的唯一入口）。
- * @param {unknown} raw curl 输出的状态码原串
+ * 判活并给出理由（消费者只需要这一个入口）。
+ * @param {unknown} raw 探测输出里的状态码原串
  * @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 };
+  if (code === null) return report(null, false, 'unparsable');
+  if (code === 0) return report(0, false, 'no-answer');
+  for (const row of VERDICT_TABLE) {
+    if (row.accept(code)) return report(code, row.alive, row.reason);
+  }
+  // 三位数字但落在 1xx / 6xx 之后：没见过的区间，交给"未知不算活"
+  return report(code, false, 'unparsable');
 }
 
-/** 只要布尔（沿用旧 `probeHttp` 的返回形状，便于调用方最小改动） */
+/** 只要一个布尔值（与老的探测函数返回形状对齐，调用方改一行就能接上） */
 export function isHttpAlive(raw) {
   return judgeHttp(raw).alive;
 }
 
-/** 日志用一行描述，例如 `code=401 (auth-401)` / `no-answer` */
+/** 一行日志描述：`code=401 (auth-401)` / `no-answer (code=000)` / `unparsable` */
 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})`;
+  const judged = judgeHttp(raw);
+  if (judged.code === null) return judged.reason;
+  if (judged.code === 0) return 'no-answer (code=000)';
+  return `code=${judged.code} (${judged.reason})`;
 }

package/lib/pitfall-form-map.mjs

@@ -1,130 +1,140 @@
-// dsh-butler / lib/pitfall-form-map.mjs —— P4「错误码 / 签名 → 建议形态」映射表
+// 错误码 / 签名 → 建议形态：查表在前，启发式在后。
 //
-// 为什么需要这张表（2026-09-12 主人点名）：
-//   `pitfall-score.mjs` 的 suggestForm 原先只按文本特征猜形态，实测跑偏——
-//   `AUDIT_NOT_PASSED`（真实成因：写保护区没先走 P5 审计）被猜成「路径存在性预检」check，
-//   方向完全不对。**已知错误码的坑，成因是确定的**，不应交给启发式猜。
+// 一个坑反复踩，就得替它挑一个"以后怎么才能不再踩"的落点，形态只有三种：
+//   check    —— 能脚本化判定的，做成自动检查项（最优：坑不再有第二次机会）
+//   skill    —— 只在动手那一刻要看到的，内联进相关技能（加载即见）
+//   persona  —— 真正全局、反复踩的铁律级，才值得动 persona
 //
-// 口径（判定顺序，命中即返回，不再往下走）：
-//   ① 错误码精确命中本条表（code 字段 > sigKey 的第 2 段 > normText 中出现的 SCREAMING_SNAKE 码）
-//   ② 签名正则命中（sigRe；用于没有稳定错误码、只能靠签名特征认的坑）
-//   ③ 都没命中 → 回落 `pitfall-score.mjs` 的原启发式（行为与改动前完全一致）
+// 为什么不能全靠文本特征猜：成因确定的坑，文本里往往只留下表象。举例来说，
+// "写保护区没先走审计"这种坑的文本里会带一串路径，按文本猜出来就成了"路径存在性预检"，
+// 方向完全错了。已知错误码的坑，成因是确定的 —— 先让表说话；表里没有，再交回启发式。
 //
-// 形态只有三种（与方案 §4 P4 一致）：`check` 自动检查项 / `skill` 内联技能 / `persona` persona 铁律。
-// 本文件是**纯数据 + 纯函数**，不碰状态、不写盘。
+// 判定顺序（命中即返回，不往下走）：
+//   ① 错误码：pitfall.code → sigKey 的第 2 段 → normText 里出现的 SCREAMING_SNAKE
+//   ② 签名正则：没有稳定错误码、只能靠文本特征认的坑走这条
+//   ③ 都没命中 → 返回 null，由调用方回落到原来的启发式
 //
-// 维护：新增一行即可生效（无副作用、无需改 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       给主人看的一句话理由（写清真实成因）
- */
+// 规则工厂：按固定字段顺序拼出规则对象，缺的可选字段不占位（保持对象形状干净）
+function rule({ id, codes, sigRe, form, why }) {
+  const built = { id };
+  if (codes) built.codes = codes;
+  if (sigRe) built.sigRe = sigRe;
+  built.form = form;
+  built.why = why;
+  return built;
+}
 
-/** @type {FormRule[]} */
 export const FORM_RULES = [
-  {
-    id: 'audit-not-passed',
-    codes: ['AUDIT_NOT_PASSED'],
-    form: 'skill',
+  rule({
+    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',
+  }),
+  rule({
+    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',
+  }),
+  rule({
+    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',
+  }),
+  rule({
+    id: 'fs-stale-version', codes: ['FS_STALE_VERSION'], form: 'persona',
     why: '铁律级（全局）：junction 路径与同文件多处修改必须重读后**串行 edit**（并行 edit 会互相刷新 mtime）；已进 persona 对应铁律',
-  },
-  {
-    id: 'search-failed',
-    codes: ['SEARCH_FAILED'],
-    form: 'check',
+  }),
+  rule({
+    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);
+// 码 → 规则（大小写不敏感；后注册者覆盖前者，与表内顺序一致）
+const RULE_BY_CODE = new Map();
+for (const entry of FORM_RULES) {
+  for (const code of entry.codes ?? []) RULE_BY_CODE.set(String(code).toUpperCase(), entry);
 }
 
-/** SCREAMING_SNAKE 错误码（至少含一个下划线，避免把 FsError 之类类名当码）。 */
+/** 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 时签名里写的占位，不是真错误码
+const PLACEHOLDER_CODES = new Set(['NO_CODE']);
+
+// 单个码的"像不像码"判据（提取与查表口径一致：大写 + 恰好的形态）
+const CODE_SHAPE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
+
+function asCode(value) {
+  const upper = String(value ?? '').toUpperCase().trim();
+  if (!upper) return null;
+  if (PLACEHOLDER_CODES.has(upper)) return null;
+  return CODE_SHAPE.test(upper) ? upper : null;
+}
 
 /**
- * 按优先级提取这条坑里出现的错误码：code 字段 → sigKey 第 2 段 → 文本中出现的码。
+ * 按优先级把这条坑里出现的错误码捞出来。
  * @param {object} pitfall
- * @returns {string[]} 去重后的候选码（越靠前越权威）
+ * @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);
+  const found = [];
+  const remember = (value) => {
+    const code = asCode(value);
+    if (code && !found.includes(code)) found.push(code);
   };
-  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]);
+  remember(pitfall?.code);
+
+  const signature = String(pitfall?.sigKey ?? '');
+  if (signature) {
+    remember(signature.split('|')[1]);
+    for (const hit of signature.matchAll(ERROR_CODE_RE)) remember(hit[1]);
+  }
+
+  const body = String(pitfall?.normText ?? '');
+  if (body) {
+    for (const hit of body.matchAll(ERROR_CODE_RE)) remember(hit[1]);
   }
-  const text = String(pitfall?.normText ?? '');
-  if (text) for (const m of text.matchAll(ERROR_CODE_RE)) push(m[1]);
-  return out;
+  return found;
+}
+
+// 命中结果的统一形状（why 前面挂规则 id，便于日志里直接看出"哪条规则判的"）
+function mapped(entry, via, matched) {
+  return { form: entry.form, why: `【映射表 ${entry.id}】${entry.why}`, ruleId: entry.id, via, matched };
 }
 
 /**
  * 查表：错误码优先，其次签名正则。
  * @param {object} pitfall
  * @returns {{form:'check'|'skill'|'persona', why:string, ruleId:string, via:'code'|'sig', matched:string}|null}
- *          未命中返回 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 };
+  for (const code of extractErrorCodes(pitfall)) {
+    const entry = RULE_BY_CODE.get(code);
+    if (entry) return mapped(entry, 'code', code);
   }
-  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) };
-    }
+
+  const haystack = [pitfall?.name, pitfall?.code, pitfall?.sigKey, pitfall?.normText]
+    .map((part) => String(part ?? ''))
+    .join('|');
+  for (const entry of FORM_RULES) {
+    if (!entry.sigRe) continue;
+    if (!entry.sigRe.test(haystack)) continue;
+    return mapped(entry, 'sig', String(entry.sigRe));
   }
   return null;
 }
 
-/** 该错误码是否在表内（面板/调试用）。 */
+/** 这个码表里有没有（面板 / 调试用） */
 export function isMappedCode(code) {
-  return CODE_INDEX.has(String(code ?? '').toUpperCase());
+  return RULE_BY_CODE.has(String(code ?? '').toUpperCase());
 }
 
-/** 表内全部错误码（单测断言用）。 */
+/** 表内全部错误码，字典序（单测断言用） */
 export function mappedCodes() {
-  return [...CODE_INDEX.keys()].sort();
+  return [...RULE_BY_CODE.keys()].sort();
 }