@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-docs-drift.mjs

@@ -0,0 +1,522 @@
+#!/usr/bin/env node
+/**
+ * check-docs-drift.mjs —— 文档漂移**只报告**检查（2026-10-03，Argent 文档一致性）
+ *
+ * 为什么有它：《Argent 产品化策划案（第三方可安装）》§4.3 点出过"把过期当现行"的两处口径
+ * （`docs/Argent-0.3.0-验收清单.md` 的"本机跑生产"、`docs/客户机部署与上线.md` 的客户机
+ * dsh 旧路径/旧版本），以及一类"版本号 / README 数字漂移"。人工复读文档不可持续 ⇒ 固化成
+ * 一条**只报告**的检查：只打印「文件:行 + 命中内容 + 为什么可疑」，**绝不修改任何文件**。
+ *
+ * 三条规则
+ *   R1 旧 dsh 版本号当现行
+ *      出现 `0.1.<n>[-rc.<m>]` 且 ≠ **现役 dsh 版本**（判据 = `dsh-version-lock/` 里晋级过的
+ *      最高快照，可用 `--dsh-version` 覆盖；与 `~/.dsh/AGENTS.md`「版本现状」一致）⇒ 可疑。
+ *      · 先过一道**真伪闸**：该命中必须"确实在说 dsh"——属于 `dsh-version-lock/` 的版本族，
+ *        或所在行含 `dsh` / `宿主` / `harness`。否则（如能力包版本 `daily-report-lite 0.1.46`）
+ *        **不报**，避免把包版本误当宿主版本。
+ *      **降级为信息**的情形（逐行判据，同一行出现即降级）：
+ *        · 历史字样：历史 / 升级记录 / 回滚 / 归档 / 当时 / 曾 / 旧版 / 遗留 / 退役 / 此前 …
+ *        · 版本推移：写成 `0.1.1→0.1.5` 这种**过渡对**（不是"现役/目标"声明）
+ *        · 行为沿革：`0.1.5 起根路径带 token 鉴权` 这种"自某版起的行为"，不是版本声明
+ *        · 快照/备份产物引用：`dsh-version-lock/0.1.5-rc.1.json`、`backup/dsh-0.1.5-…`
+ *        · 位于 `docs/archive/`，或**文件名带日期**（`…-2026-09-29.md` = 阶段性记录），
+ *          或所在小节的标题带日期/历史/快照字样（整节降级）
+ *      **反向规则**：命中附近 ±24 字符若有"这是现役"的声明词（当前/现役/现行/锁定…），
+ *      则**压过**同行的历史字样 —— 表里写「当前 = 旧版本」正是要抓的漂移。
+ *      代码块（```）里的 `# 注释` 不当标题；每行判据独立，不因上下文串味。
+ *   R2 README 数字漂移
+ *      `README.md` / `docs/README.md` 里「N 个 preset / N 个角色 / N 个技能 / N 条业务线」
+ *      （含 `presets/ 下 N 个` 形态）与**实际计数**不符 ⇒ 可疑。
+ *      实际计数来源：`presets/<角色>/agent.cordis.yml`（或 `plugins/argent-presets/presets/<角色>.patch.yml`）、
+ *      `skills/<技能>/SKILL.md`、`verticals/<业务线>/manifest.json`。
+ *   R3 已废弃路径当现行
+ *      `~/node/bin`、`$HOME/node/lib`、`/Users/<user>/node/`、裸 `~/node` 等**旧 node 前缀**
+ *      （现役 = `~/.local/node/bin`），且不在历史语境 ⇒ 可疑。
+ *   R4 宿主矩阵结构（`docs/Argent-宿主适配契约.md` §3 能力×宿主矩阵）
+ *      **只判表格还成不成形，不判内容对错**（内容真伪是 review 的活，不是本检查的）：
+ *        · **表头列数 == 每一行的格数**（错位即报：2026-10-04 的在途改动把 ③ 行写成 7 格、
+ *          把 Android 的长文塞进 `MCP 云端` 格，而当时**四条门禁全绿** —— 它们一条都不读这张表的结构）；
+ *        · **无空标签**（整格为空 = `||` / `| |`，含行首"接口名"格与表头宿主名格）；
+ *        · **状态符号合法**（每格以 `✅` 已实现 / `🟡` 部分 / `⬜` 待接入 / `—` 不适用 开头，
+ *          允许前面带 `**` 粗体标记；图例见该文档 §3 首行）。
+ *      ⇒ 报的是"第几行几格"，改法只有一种：**让表格回到 N 列**（⛔ 不许靠删符号糊过去）。
+ *
+ * 用法
+ *   node scripts/check-docs-drift.mjs                  # 只报告，**恒 exit 0**
+ *   node scripts/check-docs-drift.mjs --strict         # 有可疑条目才 exit 1（给人手动跑 / 单独 CI 用）
+ *   node scripts/check-docs-drift.mjs --json           # 机器可读
+ *   node scripts/check-docs-drift.mjs --root <dir>     # 换根目录（自测夹具用；仍然只读）
+ *   node scripts/check-docs-drift.mjs --dsh-version <v># 覆盖现役 dsh 版本判据
+ *   node scripts/check-docs-drift.mjs --strict --matrix-only
+ *                                                      # **只**跑 R4（CI 的 `host-matrix` 条用：
+ *                                                      #  失败时点名"结构错位"而不是"口径漂移" ——
+ *                                                      #  两类缺陷的修法完全不同，故各占一条判据）
+ *
+ * 纪律
+ *   · **只读**：不改文件、不写台账/数据目录、不读凭据、不联网；扫描对象是 `docs/**\/*.md`
+ *     （R1/R3）、两处 README（R2）与**一份**矩阵文档（R4，路径写死 = 契约 §3 的唯一落点）。
+ *   · **默认不失败**：它**不接** `scripts/run-tests.sh` 的失败判据（文档漂移常年存在，
+ *     接进去就是恒红陷阱）。回归只覆盖 `scripts/tests/docs-drift.test.mjs` 的**纯夹具**。
+ * · **R4 例外说明**：R4 与 R1–R3 同档（默认报告、`--strict` 才红），但它是**结构性**判据 ——
+ *   接进 CI 的是 `--matrix-only` 那一条（见 `scripts/ci-run.sh#CRITERIA`）。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = resolve(HERE, '..')
+
+// ── 参数 ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const val = (f) => {
+  const i = argv.indexOf(f)
+  return i >= 0 ? argv[i + 1] : undefined
+}
+if (has('-h') || has('--help')) {
+  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').trim())
+  process.exit(0)
+}
+const STRICT = has('--strict')
+const JSON_OUT = has('--json')
+const MATRIX_ONLY = has('--matrix-only')   // 只跑 R4（CI 的 host-matrix 条；见文件头「用法」）
+const ROOT = resolve(val('--root') || SELF_ROOT)
+const OVERRIDE_VERSION = val('--dsh-version')
+
+// ── 判据（现役 dsh 版本 / 实际计数）─────────────────────────────────────────
+/** semver-ish 比较：只处理 `0.1.x-rc.y`（本仓库实际形态）。 */
+function cmpVersion(a, b) {
+  const p = (s) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?$/.exec(s)
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? Number.MAX_SAFE_INTEGER : Number(m[4])] : null
+  }
+  const x = p(a)
+  const y = p(b)
+  if (!x || !y) return null
+  for (let i = 0; i < 4; i += 1) {
+    if (x[i] !== y[i]) return x[i] - y[i]
+  }
+  return 0
+}
+
+/** 现役 dsh 版本 = `dsh-version-lock/` 顶层晋级快照里最高的一版（排除 candidate/）。 */
+function resolveActiveDshVersion(root) {
+  if (OVERRIDE_VERSION) return { version: OVERRIDE_VERSION, source: '--dsh-version 覆盖', all: [OVERRIDE_VERSION] }
+  const dir = join(root, 'dsh-version-lock')
+  if (!existsSync(dir)) return { version: null, source: '未找到 dsh-version-lock/（R1 跳过）', all: [] }
+  const versions = readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''))
+    .filter((v) => cmpVersion(v, v) !== null)
+  if (!versions.length) return { version: null, source: 'dsh-version-lock/ 无可用快照（R1 跳过）', all: [] }
+  versions.sort(cmpVersion)
+  const top = versions[versions.length - 1]
+  return { version: top, source: `dsh-version-lock/${top}.json`, all: versions }
+}
+
+function countPresets(root) {
+  const dir = join(root, 'presets')
+  if (existsSync(dir)) {
+    const n = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'agent.cordis.yml'))).length
+    if (n > 0) return { n, source: 'presets/*/agent.cordis.yml' }
+  }
+  const pdir = join(root, 'plugins', 'argent-presets', 'presets')
+  if (existsSync(pdir)) {
+    const n = readdirSync(pdir).filter((f) => f.endsWith('.patch.yml')).length
+    if (n > 0) return { n, source: 'plugins/argent-presets/presets/*.patch.yml' }
+  }
+  return { n: 0, source: '（未找到 preset 目录）' }
+}
+
+function countSkills(root) {
+  const dir = join(root, 'skills')
+  if (!existsSync(dir)) return { n: 0, source: '（未找到 skills/）' }
+  const n = readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'SKILL.md'))).length
+  return { n, source: 'skills/*/SKILL.md' }
+}
+
+function countVerticals(root) {
+  const dir = join(root, 'verticals')
+  if (!existsSync(dir)) return { n: 0, source: '（未找到 verticals/）' }
+  const n = readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'manifest.json'))).length
+  return { n, source: 'verticals/*/manifest.json' }
+}
+
+// ── 语境判据（降级用）──────────────────────────────────────────────────────
+const HISTORY_RE = /历史|升级记录|升级日志|回滚|归档|当时|当年|曾经|曾|此前|旧版|旧前缀|过时|退役|遗留|撤销|已删除|删除|弃用|废弃|事故|教训|踩坑|复盘|deprecated|legacy/i
+/** 明确的"这是现役"声明词：同行即使有历史字样，也不能拿它解释掉。 */
+const CURRENCY_RE = /当前|现役|现行|目前|现在|正在用|锁定|正在跑/g
+const ARTIFACT_RE = /快照|snapshot|backup|备份|离线包|\.tgz|\.tar\.gz/i
+const WORD_CH = /[\w./@+-]/
+const DATED_RE = /20\d\d-\d\d-\d\d/
+const DSH_MENTION_RE = /dsh|宿主|harness/gi
+
+/** 命中是否属于"路径/文件名的一部分"（快照产物引用，而不是版本声明）。 */
+function isArtifactRef(line, idx, token) {
+  let s = idx
+  let e = idx + token.length
+  while (s > 0 && WORD_CH.test(line[s - 1])) s -= 1
+  while (e < line.length && WORD_CH.test(line[e])) e += 1
+  const word = line.slice(s, e)
+  return word.includes('/') || /\.(json|tgz|tar\.gz|zip|txt)$/.test(word)
+}
+
+/** 命中处附近（默认 ±radius 字符）有没有在谈 dsh / 宿主 / harness。 */
+function nearDsh(line, idx, token, radius = 12) {
+  const lo = Math.max(0, idx - radius)
+  const hi = idx + token.length + radius
+  for (const m of line.matchAll(DSH_MENTION_RE)) if (m.index >= lo && m.index <= hi) return true
+  return false
+}
+
+/** 能力包 / 业务能力版本也用 `0.1.x` 形状（`daily-report-lite 0.1.46`、`hr 0.1.37`）——不是宿主版本。 */
+const PACK_NAME_RE = /(?:daily-report-lite|lite|hr|invoice|full|daily-report|pack|capability|能力包)\s*[:=]?\s*$/i
+function looksLikePackVersion(line, idx) {
+  return PACK_NAME_RE.test(line.slice(Math.max(0, idx - 32), idx))
+}
+
+/** 一行里的降级理由；返回 null = 不得降级（可疑）。 */
+function infoReason(line, idx, token) {
+  if (HISTORY_RE.test(line)) return '行内含历史字样（历史/升级记录/回滚/归档/当时/旧版/事故教训…）'
+  const before = line.slice(Math.max(0, idx - 16), idx)
+  const rawAfter = line.slice(idx + token.length, idx + token.length + 16)
+  const after = rawAfter.replace(/^[\s`'"（(）)\]]*/, '') // 去掉反引号/引号/括号等包裹
+  if (/→|->/.test(before) || /^(?:→|->)/.test(after)) return '版本推移记录（`A→B`），不是"现役/目标"声明'
+  if (/(?:>=|<=|>|<|~|\^)\s*$/.test(before)) return '版本约束/范围表达式（如 `dsh >=0.1.5 <0.2`），不是"现役版本"声明'
+  if (/^(?:\+|起|CLI|禁止|不支持|支持|以上|以下|之后|之前|及以后|开始|兼容)/.test(after)) {
+    return '版本作用域行为陈述（`0.1.5+` / `0.1.5 起` / `0.1.5 禁止…`），不是版本声明'
+  }
+  if (/(?:自|从)\s*$/.test(before)) return '行为沿革（"自某版起…"），不是版本声明'
+  if (isArtifactRef(line, idx, token) || ARTIFACT_RE.test(line)) return '快照 / 备份产物引用（不是现行版本口径）'
+  return null
+}
+
+/** 命中附近（±24 字符）有没有"这是现役"的声明词。 */
+function currencyClaim(line, idx, token, radius = 24) {
+  for (const m of line.matchAll(CURRENCY_RE)) {
+    const dist = Math.min(
+      Math.abs(m.index - (idx + token.length)),
+      Math.abs(idx - (m.index + m[0].length)),
+    )
+    if (dist <= radius) return true
+  }
+  return false
+}
+
+/** 小节语境：所在标题栈里有带日期 / 历史字样 / 快照字样的标题 ⇒ 整节降级。 */
+function sectionHeadingReason(stack) {
+  for (const h of stack) {
+    const title = h.text.trim()
+    if (DATED_RE.test(title)) return `所在小节标题带日期（\`${clip(title, 40)}\` = 阶段性记录）`
+    if (HISTORY_RE.test(title)) return `所在小节是历史/复盘小节（\`${clip(title, 40)}\`）`
+    if (ARTIFACT_RE.test(title)) return `所在小节讲快照/备份产物（\`${clip(title, 40)}\`）`
+  }
+  return null
+}
+
+// ── 规则 ───────────────────────────────────────────────────────────────────
+const VERSION_RE = /(?<![\d.])0\.1\.(\d+)(?:-rc\.(\d+))?(?!\d)/g
+const DATED_DOC_RE = /20\d\d-\d\d-\d\d/
+
+/**
+ * 这个 `0.1.x` 命中是否**真的在说 dsh 版本**？
+ * 不设这道闸就会把能力包版本（`daily-report-lite 0.1.46`、`hr 0.1.0`）误报成 dsh 漂移。
+ * 判据：① 带 `-rc.N` 后缀 —— dsh 的版本命名（能力包不用 rc 后缀）；
+ *       ② 裸版本号则要求**紧邻**（±12 字符）dsh / 宿主 / harness（"dsh 0.1.5"、"宿主 0.1.5"）；
+ *       ③ 命中前紧挨着能力包名（`lite 0.1.1`、`hr 0.1.0`）⇒ 一律不算 dsh 版本。
+ */
+function isDshVersionToken(token, line, idx) {
+  if (looksLikePackVersion(line, idx)) return false
+  if (/-rc\.\d+$/.test(token)) return true
+  return nearDsh(line, idx, token)
+}
+const DEPRECATED_PATHS = [
+  { re: /(?:\$HOME|~|\/Users\/[\w.-]+)\/node\/(?:bin|lib)\b/g, label: '旧 node 前缀路径（`~/node/bin` / `~/node/lib`）' },
+  { re: /\/Users\/[\w.-]+\/node\//g, label: '旧 node 前缀绝对路径（`/Users/<user>/node/`）' },
+  { re: /(?:\$HOME|~)\/node(?![\w/.-])/g, label: '旧 node 前缀（裸 `~/node`）' },
+]
+
+function clip(s, max = 160) {
+  const t = s.replace(/\s+/g, ' ').trim()
+  return t.length <= max ? t : `${t.slice(0, max - 1)}…`
+}
+
+function walkMd(dir, out = []) {
+  if (!existsSync(dir)) return out
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.')) continue
+    const p = join(dir, e.name)
+    if (e.isDirectory()) walkMd(p, out)
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(p)
+  }
+  return out
+}
+
+const findings = []
+const push = (rule, level, file, line, text, token, why) =>
+  findings.push({ rule, level, file, line, token, text: clip(text), why })
+
+function scanVersionsAndPaths(file, rel) {
+  const text = readFileSync(file, 'utf8')
+  const lines = text.split('\n')
+  const inArchive = rel.split(sep).includes('archive')
+  const dated = DATED_DOC_RE.test(rel.split(sep).pop() || '')
+  const fileReason = inArchive ? 'docs/archive/ 内（按定义是历史文档）'
+    : dated ? '文件名带日期（阶段性记录，不是现行口径文档）' : null
+  const headings = [] // 标题栈：{ level, text }
+  let inFence = false
+  lines.forEach((line, i) => {
+    const lineNo = i + 1
+    if (/^\s*(```|~~~)/.test(line)) { // 代码块里的 `# 注释` 不是标题
+      inFence = !inFence
+      return
+    }
+    const h = inFence ? null : /^(#{1,6})\s+(.*)$/.exec(line)
+    if (h) {
+      const level = h[1].length
+      while (headings.length && headings[headings.length - 1].level >= level) headings.pop()
+      headings.push({ level, text: h[2] })
+      return
+    }
+    const sectionReason = fileReason || sectionHeadingReason(headings)
+    // R1
+    if (ACTIVE.version) {
+      for (const m of line.matchAll(VERSION_RE)) {
+        const token = m[0]
+        const idx = m.index
+        if (!isDshVersionToken(token, line, idx)) continue
+        const base = `0.1.${m[1]}`
+        const isActive = token === ACTIVE.version || (m[2] === undefined && ACTIVE.version.startsWith(`${base}-`))
+        if (isActive) continue
+        const lineReason = infoReason(line, idx, token)
+        const currency = currencyClaim(line, idx, token)
+        // 现役声明词（当前/现役/锁定…）**压过**同行的历史字样：表里写"当前 = 旧版本"就是漂移。
+        const reason = fileReason || sectionReason || (lineReason && !currency ? lineReason : null)
+        if (reason) push('R1', 'info', rel, lineNo, line, token, reason)
+        else push('R1', 'suspect', rel, lineNo, line, token, currency && lineReason
+          ? `现役 dsh 是 ${ACTIVE.version}（判据 ${ACTIVE.source}），此行含现役声明词（当前/现役/锁定）并把 ${token} 当现行版本`
+          : `现役 dsh 是 ${ACTIVE.version}（判据 ${ACTIVE.source}），此行把 ${token} 当现行/目标版本，且行内无历史语境`)
+      }
+    }
+    // R3
+    const taken = []
+    for (const { re, label } of DEPRECATED_PATHS) {
+      for (const m of line.matchAll(re)) {
+        const s = m.index
+        const e = s + m[0].length
+        if (taken.some(([a, b]) => s < b && e > a)) continue
+        taken.push([s, e])
+        const reason = sectionReason || (HISTORY_RE.test(line) ? '行内含历史字样（归档/删除/旧前缀…）' : null)
+        if (reason) push('R3', 'info', rel, lineNo, line, m[0], reason)
+        else push('R3', 'suspect', rel, lineNo, line, m[0],
+          `${label} 已废弃（现役 = \`~/.local/node/bin\`；旧前缀 \`~/node\` 已于 2026-10-03 归档删除），此行把它当现行路径`)
+      }
+    }
+  })
+}
+
+const NUMBER_PATTERNS = [
+  { re: /(\d+)\s*个\s*[Pp]resets?/g, what: 'preset 数', pick: (c) => c.presets },
+  { re: /presets\/`?\s*下\s*(\d+)\s*个/g, what: 'preset 数', pick: (c) => c.presets },
+  { re: /(\d+)\s*个角色/g, what: '角色数（一角色一 preset）', pick: (c) => c.presets },
+  { re: /(\d+)\s*个技能/g, what: '技能数', pick: (c) => c.skills },
+  { re: /(\d+)\s*[条个]业务线/g, what: '业务线数', pick: (c) => c.verticals },
+]
+
+function scanReadmeNumbers(file, rel, counts) {
+  const lines = readFileSync(file, 'utf8').split('\n')
+  lines.forEach((line, i) => {
+    for (const { re, what, pick } of NUMBER_PATTERNS) {
+      for (const m of line.matchAll(re)) {
+        const claimed = Number(m[1])
+        const { n, source } = pick(counts)
+        if (claimed === n) continue
+        const why = `README 写「${what} = ${claimed}」，实际 ${n}（计数来源：${source}）`
+        if (HISTORY_RE.test(line)) push('R2', 'info', rel, i + 1, line, m[0], `${why}；但行内含历史字样 ⇒ 降级`)
+        else push('R2', 'suspect', rel, i + 1, line, m[0], why)
+      }
+    }
+  })
+}
+
+// ── R4：宿主矩阵结构 ────────────────────────────────────────────────────────
+/** 矩阵的唯一落点（契约 §3）。⛔ 不扫别的文档 —— 矩阵**只此一处**（§4 SOP：新宿主只加一列）。 */
+const HOST_MATRIX_REL = 'docs/Argent-宿主适配契约.md'
+const MATRIX_HEADER_PREFIX = '| 接口'      // 表头首格 = `接口 \ 宿主`
+const STATUS_SYMBOLS = ['✅', '🟡', '⬜', '—']
+
+/** Markdown 表格行 ⇒ 单元格数组（去首尾空段；不是表格行 ⇒ null）。 */
+function cellsOf(line) {
+  const s = line.trim()
+  if (!s.startsWith('|')) return null
+  const body = s.endsWith('|') ? s.slice(0, -1) : s
+  return body.slice(1).split('|').map((c) => c.trim())
+}
+
+/** `|---|---|` 形态的分隔行。 */
+const isSeparatorCells = (cells) => cells.length > 0 && cells.every((c) => /^:?-{2,}:?$/.test(c))
+
+/** 状态符号判据：允许前置 `**` / `*` / 反引号 / 空白，第一个**实义字符**必须是四个符号之一。
+ *  ⚠️ 必须按**码点**取首字符：`✅`/`🟡`/`⬜` 在 UTF-16 里是代理对（2 个 code unit），
+ *  用 `[\s\S]` 会只取到半个代理 ⇒ 恒判非法（本规则首版就踩了这个，见 2026-10-06 记录）。 */
+function statusSymbolOf(cell) {
+  return Array.from(cell.replace(/^[\s*`>]+/, ''))[0] || ''
+}
+
+/**
+ * R4：`docs/Argent-宿主适配契约.md` §3 能力×宿主矩阵的**结构**判据。
+ * 三条：① 每行列数 == 表头列数（含分隔行）② 无空标签 ③ 状态符号合法。
+ * 返回该文件的统计（给 --json 与汇总行用）；文件不存在 ⇒ null（夹具仓库不必带这份文档）。
+ */
+function scanHostMatrix(root, rel) {
+  const file = join(root, rel)
+  if (!existsSync(file)) return null
+  const lines = readFileSync(file, 'utf8').split('\n')
+  const headIdx = lines.findIndex((l) => l.trim().startsWith(MATRIX_HEADER_PREFIX))
+  if (headIdx < 0) {
+    push('R4', 'suspect', rel, 1, '', '', `找不到 §3 矩阵表头（首格应为 \`${MATRIX_HEADER_PREFIX} \\ 宿主\`）—— 表格被改名/删除后本检查就瞎了`)
+    return { found: false, headerCols: 0, dataRows: 0, defects: 1 }
+  }
+  const header = cellsOf(lines[headIdx])
+  const cols = header.length
+  let dataRows = 0
+  let defects = 0
+  const bad = (lineNo, text, why, token = '') => { defects += 1; push('R4', 'suspect', rel, lineNo, text, token, why) }
+
+  // 表头自己的空标签（宿主名不得留空）
+  header.forEach((c, j) => {
+    if (!c) bad(headIdx + 1, lines[headIdx], `表头第 ${j + 1} 格是空标签（宿主名/接口名不得留空）`)
+  })
+
+  for (let i = headIdx + 1; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (!raw.trim().startsWith('|')) break          // 表格结束
+    const cells = cellsOf(raw)
+    const lineNo = i + 1
+    const sep = isSeparatorCells(cells)
+    if (cells.length !== cols) {
+      const delta = cells.length - cols
+      bad(lineNo, raw, `表格错位：本行 ${cells.length} 格，表头 ${cols} 格（${delta > 0 ? `多 ${delta}` : `少 ${-delta}`} 格）`
+        + ` ⇒ 该行以下所有格的内容都串位了（修法：让本行回到 ${cols} 格，⛔ 不要靠删状态符号糊过去）`)
+      continue
+    }
+    if (sep) continue
+    const isEmptyLabelRow = cells.every((c) => c === '')
+    if (isEmptyLabelRow) { bad(lineNo, raw, '整行所有格都为空（空标签行）'); continue }
+    dataRows += 1
+    cells.forEach((c, j) => {
+      if (!c) { bad(lineNo, raw, `第 ${j + 1} 格是空标签（${j === 0 ? '行首"接口名"格' : '宿主格'}不得留空）`); return }
+      if (j === 0) return                              // 第 1 格 = 接口名，不是状态格
+      const sym = statusSymbolOf(c)
+      if (!STATUS_SYMBOLS.includes(sym)) {
+        bad(lineNo, raw, `第 ${j + 1} 格的状态符号非法：以 ${JSON.stringify(sym)} 开头，`
+          + `合法符号只有 ${STATUS_SYMBOLS.join(' / ')}（图例见该文档 §3）`, sym)
+      }
+    })
+  }
+  if (dataRows === 0) {
+    bad(headIdx + 1, lines[headIdx], '表头下面没有数据行（矩阵被清空？）')
+  }
+  return { found: true, headerCols: cols, dataRows, defects }
+}
+
+
+// ── 执行 ───────────────────────────────────────────────────────────────────
+const ACTIVE = resolveActiveDshVersion(ROOT)
+const counts = { presets: countPresets(ROOT), skills: countSkills(ROOT), verticals: countVerticals(ROOT) }
+
+const docsDir = join(ROOT, 'docs')
+const docsFiles = MATRIX_ONLY ? [] : walkMd(docsDir)
+  .map((p) => relative(ROOT, p))
+  .sort()
+for (const rel of docsFiles) scanVersionsAndPaths(join(ROOT, rel), rel)
+
+const readmes = MATRIX_ONLY ? [] : ['README.md', join('docs', 'README.md')].filter((r) => existsSync(join(ROOT, r)))
+for (const rel of readmes) scanReadmeNumbers(join(ROOT, rel), rel, counts)
+
+// R4：宿主矩阵结构（**不随 --matrix-only 开关，永远跑** —— 它是结构性判据，任何模式下都该看得见）
+const matrix = scanHostMatrix(ROOT, HOST_MATRIX_REL)
+
+const suspects = findings.filter((f) => f.level === 'suspect')
+const infos = findings.filter((f) => f.level === 'info')
+const byRule = (lvl, rule) => findings.filter((f) => f.level === lvl && f.rule === rule).length
+const RULE_TITLE = {
+  R1: 'R1 旧 dsh 版本号当现行', R2: 'R2 README 数字漂移',
+  R3: 'R3 已废弃路径当现行', R4: 'R4 宿主矩阵结构（列数/空标签/状态符号）',
+}
+const INFO_PRINT_PER_RULE = 12 // 每条规则的信息项逐条打印上限（避免刷屏；全量用 --json）
+
+/** 矩阵结构汇总行（两个 CI 判据共用；`host-matrix` 的 expect 命中它）。 */
+function matrixSummary() {
+  if (!matrix) return `矩阵结构：跳过（${HOST_MATRIX_REL} 不存在）`
+  if (!matrix.found) return '矩阵结构：表头缺失（见上）'
+  return `矩阵结构：${matrix.defects} 处（表头 ${matrix.headerCols} 列 ｜ 数据行 ${matrix.dataRows}）`
+}
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({
+    root: ROOT,
+    activeDshVersion: ACTIVE.version,
+    activeDshVersionSource: ACTIVE.source,
+    docsScanned: docsFiles.length,
+    matrixOnly: MATRIX_ONLY,
+    counts: Object.fromEntries(Object.entries(counts).map(([k, v]) => [k, v.n])),
+    matrix,
+    suspects: suspects.length,
+    infos: infos.length,
+    findings,
+  }, null, 2))
+} else {
+  console.log('check-docs-drift —— 文档漂移**只报告**检查（不改任何文件）')
+  console.log(`  仓库根：${ROOT}`)
+  if (MATRIX_ONLY) {
+    console.log('  模式：--matrix-only（**只**跑 R4 宿主矩阵结构；R1/R2/R3 本轮未跑）')
+  } else {
+    console.log(`  扫描：docs/**/*.md ${docsFiles.length} 个（archive/ 按历史语境降级）｜README 数字：${readmes.join(' · ') || '（无）'}`)
+  }
+  console.log(`  现役 dsh 版本（R1 判据）：${ACTIVE.version || '未知'}   ← ${ACTIVE.source}`)
+  console.log(`  实际计数（R2 判据）：preset ${counts.presets.n} · 技能 ${counts.skills.n} · 业务线 ${counts.verticals.n}`)
+  console.log(`  ${matrixSummary()}   ← 文档：${HOST_MATRIX_REL}`)
+  console.log('')
+  console.log(`⚠️ 可疑 ${suspects.length} 条`)
+  for (const rule of ['R1', 'R2', 'R3', 'R4']) {
+    const list = suspects.filter((f) => f.rule === rule)
+    if (!list.length) continue
+    console.log(`  ── ${RULE_TITLE[rule]}（${list.length} 条）`)
+    for (const f of list) {
+      console.log(`     ${f.file}:${f.line}`)
+      console.log(`       命中：${f.token}`)
+      console.log(`       原文：${f.text}`)
+      console.log(`       为什么可疑：${f.why}`)
+    }
+  }
+  console.log('')
+  console.log(`ℹ️ 信息（历史/沿革语境，不计入可疑）${infos.length} 条`)
+  let infoSkipped = 0
+  for (const rule of ['R1', 'R2', 'R3', 'R4']) {
+    const list = infos.filter((f) => f.rule === rule)
+    if (!list.length) continue
+    console.log(`  ── ${RULE_TITLE[rule]}（${list.length} 条）`)
+    list.forEach((f, i) => {
+      if (i >= INFO_PRINT_PER_RULE) { infoSkipped += 1; return }
+      console.log(`     ${f.file}:${f.line}  「${f.token}」 — ${f.why}`)
+    })
+  }
+  if (infoSkipped) console.log(`  …另有 ${infoSkipped} 条信息未逐条打印（需要全量看 --json）`)
+  console.log('')
+  console.log(`  =============================================`)
+  console.log(`    ${matrixSummary()}`)
+  console.log(`    可疑 ${suspects.length} 条（R1=${byRule('suspect', 'R1')} / R2=${byRule('suspect', 'R2')} / R3=${byRule('suspect', 'R3')} / R4=${byRule('suspect', 'R4')}）`
+    + `｜信息 ${infos.length} 条（R1=${byRule('info', 'R1')} / R2=${byRule('info', 'R2')} / R3=${byRule('info', 'R3')} / R4=${byRule('info', 'R4')}）`)
+  console.log(`    如何修：现行口径写**现役值**（dsh ${ACTIVE.version || '<现役版本>'}、路径 \`~/.local/node/bin\`、README 数字按实际计数），`
+    + `历史内容**不要删**、只补「历史/升级记录」字样即可让本检查降级为信息；`
+    + `矩阵结构（R4）另有修法：让出问题的行**回到表头的列数**（内容一格都不许丢）。`)
+  console.log(`    本检查只报告：默认 exit 0；要当门禁用 --strict（有可疑条才非零）；只查矩阵用 --strict --matrix-only。`)
+  console.log(`  =============================================`)
+}
+
+process.exit(STRICT && suspects.length > 0 ? 1 : 0)

package/engine/scripts/check-dsh-web-expose.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# check-dsh-web-expose.sh — 检查 dsh web 是否已对局域网/组网暴露（方案 C：--host 0.0.0.0）
+#
+# 背景：dsh web 默认只绑 127.0.0.1；`/api` 还有一道**浏览器信任围栏**
+# （`dsh-client-connection` 的 isTrustedApiRequest）：非回环 Host 且不在 trustedHosts 里 → **403**。
+# 而 trustedHosts 仅在 `--host 0.0.0.0` 时自动填入本机所有非回环 IPv4（`resolveLanTrust`）。
+#
+# 所以暴露成功要同时满足：① 监听在 0.0.0.0（或指定网卡）② 目标 Host 在信任表里 ③ token 对。
+#
+# ⑩b（2026-10-08）：取 token 的日志落点**不再写死 `/tmp/dsh-web.log`**，也不在取不到时打印
+#   占位提示（那是**半静默**：看的人会以为"只是没取到"，实际是链路断了）。候选顺序的唯一真源是
+#   `scripts/lib/wake-auth.mjs#logPaths()`（`node …/wake-auth.mjs --log-paths`）：
+#     DSH_WEB_LOG → plist 的 StandardOutPath → $DSH_HOME/dsh-web.log → ~/Library/Logs/dsh-web.log
+#     → /tmp/dsh-web.log（历史兜底，排最后）；逐项试、**命中即停**。
+#   全部落空 ⇒ 第 3 段**响亮失败**：非零退出 + 点名每个落点与分类 + 修法。
+#
+# 用法：bash scripts/check-dsh-web-expose.sh [port]
+# 退出码：0 三段都拿到证据；1 取不到 token（第 3 段失败，点名列过的落点与修法）
+set -uo pipefail
+PORT="${1:-3080}"
+
+SELF="${BASH_SOURCE[0]}"
+. "$(dirname "${SELF}")/lib/repo-root.sh"
+REPO="$(argent_repo_root "${SELF}")"
+WAKE_AUTH="${REPO}/scripts/lib/wake-auth.mjs"
+
+# ── 日志落点链（唯一真源）：逐项试、命中即停 ─────────────────────────────────────
+CANDS="$(node "${WAKE_AUTH}" --log-paths 2>&1)"
+NODE_RC=$?
+LOG=""
+TRIED=""
+if [ "${NODE_RC}" -ne 0 ] || [ -z "${CANDS}" ]; then
+  TRIED="  ❌ （候选表都取不到：node ${WAKE_AUTH} --log-paths exit=${NODE_RC}）"$'\n'
+else
+  while IFS= read -r p; do
+    [ -n "${p}" ] || continue
+    if [ ! -f "${p}" ]; then
+      TRIED="${TRIED}  ❌ ${p}：文件不存在（日志被系统清理或被运维挪走）"$'\n'
+      continue
+    fi
+    if grep -q "dsh web: http" "${p}" 2>/dev/null; then LOG="${p}"; break; fi
+    TRIED="${TRIED}  ❌ ${p}：有文件，但没有「dsh web: http」那一行（多半是别的进程/旧日志）"$'\n'
+  done <<< "${CANDS}"
+fi
+
+echo "=== 1. 监听绑定 ==="
+lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN 2>/dev/null | sed -n '1,4p'
+bind=$(lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN 2>/dev/null | awk 'NR==2{print $9}')
+echo "  → ${bind:-（未监听）}"
+case "${bind}" in
+  *0.0.0.0*)  echo "  ✅ 已绑所有网卡：局域网 + 组网都能连" ;;
+  *127.0.0.1*) echo "  ❌ 仍只绑回环 —— LaunchAgent 的 --host 没生效。" ;;
+  "")          echo "  ⚠️ 没在监听：服务没起来，先跑 bash ${REPO}/scripts/dsh-restart.sh（它会打印日志落点）" ;;
+  *)           echo "  ℹ️ 绑在指定网卡上：${bind}" ;;
+esac
+
+echo
+echo "=== 2. Host 信任围栏（/api）==="
+ips=$(node -e "const os=require('os');console.log(Object.values(os.networkInterfaces()).flat().filter(i=>i&&i.family==='IPv4'&&!i.internal).map(i=>i.address).join(' '))" 2>/dev/null)
+for h in 127.0.0.1 ${ips:-}; do
+  code=$(curl -s -o /dev/null -w '%{http_code}' -m 5 -H "Host: ${h}:${PORT}" "http://127.0.0.1:${PORT}/api" 2>/dev/null || echo 000)
+  case "${code}" in
+    403) verdict="❌ 被围栏拒绝（该 Host 不在信任表）" ;;
+    000) verdict="⚠️ 连不上" ;;
+    *)   verdict="✅ 过了围栏（${code} = 缺 token，属正常）" ;;
+  esac
+  printf "  Host=%-20s /api → %s   %s\n" "${h}:${PORT}" "${code}" "${verdict}"
+done
+
+echo
+echo "=== 3. 手机该打开的地址 ==="
+if [ -z "${LOG}" ]; then
+  {
+    echo "❌ 取不到 dsh web 的启动 token：候选日志**全部不可用**"
+    printf '%s' "${TRIED}"
+    echo "   修法（按代价从低到高）："
+    echo "     · 日志若被挪走，本链会自动跟随 plist 的声明：plutil -p ~/Library/LaunchAgents/com.whyshu.dsh-web.plist | grep -i path"
+    echo "     · 重启并打印落点：bash ${REPO}/scripts/dsh-restart.sh"
+    echo "     · 或显式指定落点（冒号分隔可给多个）：export DSH_WEB_LOG=<日志路径> ／ export ARGENT_WAKE_LOG_PATHS=<路径1>:<路径2>"
+    echo "     · 候选表由 scripts/lib/wake-auth.mjs#logPaths() 给出：node ${WAKE_AUTH} --log-paths"
+    echo "     · ⛔ 这里**不再**打印占位提示：取不到 token 时「手机该打开的地址」是**不可知**的，不是让人自己填"
+  } >&2
+  exit 1
+fi
+tok=$(grep -o 'token=[A-Za-z0-9_-]*' "${LOG}" 2>/dev/null | tail -1 | cut -d= -f2)
+if [ -z "${tok}" ]; then
+  {
+    echo "❌ 命中日志 ${LOG}，但里面没有可用的 token（取到了文件、解析不出 = 另一种故障）"
+    echo "   修法：确认它是**当前进程**的启动日志：grep -c 'dsh web: http' '${LOG}'；必要时 bash ${REPO}/scripts/dsh-restart.sh"
+  } >&2
+  exit 1
+fi
+for h in ${ips:-}; do
+  echo "  http://${h}:${PORT}/?token=${tok}"
+done
+echo
+echo "说明：token 每次启动都会变；首次访问带 token，之后浏览器有 30 天 cookie。"
+echo "      本次 token 取自：${LOG}（候选链见 node ${WAKE_AUTH} --log-paths）"