dsh-jev-guard 0.5.1

package/lib/token.js

@@ -0,0 +1,154 @@
+/**
+ * 一次性放行令牌 —— 给"硬拦"一个明确的人工出口。
+ *
+ * 为什么需要它:在完全权限(approval=never)模式里,`revise` 和 `block` 都会变成**硬拦**,
+ * 没有审批弹窗可点。实测代价:连"删一个过期文件"这种正当清理(p≈0.62)也会被拦,
+ * 而抬阈值会让真正的破坏(0.68–0.82)有一半漏过。与其在阈值上二选一,不如给一个**精确到
+ * 单条命令**的人工出口:
+ *
+ *   1. 阀门拦下命令,并在理由里给出 `ALLOW-XXXXXXXXXX`;
+ *   2. 人在终端跑 `guard allow '<原命令>'`(或把令牌写进 allow.txt);
+ *   3. 调用方重试**同一条命令** → 阀门发现令牌 → **消费掉它** → 放行这一次。
+ *
+ * 三条安全性质:
+ *   · **绑定具体命令** —— 令牌是规范化命令的哈希前 10 位,换一条命令就换成另一个令牌;
+ *   · **一次性** —— 用掉即从文件删除,无法重放;
+ *   · **不越过 L0** —— L0 的"永不允许"规则(dd 写盘、格式化、删库…)不受令牌影响,
+ *     这是四层设计里 L0 的硬地板。
+ *
+ * @module jev-guard/token
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { HOME_DIR } from './audit.js'
+
+/** 令牌文件默认位置(一行一个令牌,`#` 后为注释)。 */
+export const DEFAULT_TOKEN_PATH = process.env.JEV_GUARD_ALLOW_FILE ?? join(HOME_DIR, 'allow.txt')
+
+/** 令牌前缀,便于在日志与对话里辨认。 */
+export const TOKEN_PREFIX = 'ALLOW-'
+
+/**
+ * 解析令牌文件路径。
+ *
+ * 与 `audit.resolveLogPath` 同一条教训(实测踩过):配置里的空串/纯空白必须当作
+ * "未配置",`??` 不够。
+ *
+ * @param options - `{ tokenPath }`。
+ * @returns 实际使用的令牌文件路径。
+ */
+export function resolveTokenPath(options = {}) {
+  const configured = options?.tokenPath
+  return typeof configured === 'string' && configured.trim() !== '' ? configured : DEFAULT_TOKEN_PATH
+}
+
+/**
+ * 把命令规范化后再哈希 —— 空白差异(多空格、换行)不应改变令牌。
+ * @param command - 原始命令文本。
+ * @returns 规范化后的命令。
+ */
+export function canonicalize(command) {
+  return String(command ?? '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * 计算一条命令的放行令牌。
+ * @param command - 原始命令文本。
+ * @returns 形如 `ALLOW-3F9A2C7B14` 的令牌。
+ */
+export function commandToken(command) {
+  const digest = createHash('sha256').update(canonicalize(command)).digest('hex')
+  return `${TOKEN_PREFIX}${digest.slice(0, 10).toUpperCase()}`
+}
+
+/**
+ * 读取令牌文件(不存在则视为空)。
+ * @param path - 令牌文件路径。
+ * @returns 令牌数组(已去注释与空白)。
+ */
+export async function readTokens(path = DEFAULT_TOKEN_PATH) {
+  try {
+    const text = await readFile(path, 'utf8')
+    return text
+      .split('\n')
+      .map(l => l.split('#')[0].trim())
+      .filter(l => l !== '')
+  } catch {
+    return []
+  }
+}
+
+/** 串行化读改写,避免并发消费互相覆盖。 */
+let chain = Promise.resolve()
+
+/**
+ * 尝试用令牌放行一条命令:命中则**消费**(从文件移除)并返回成功。
+ *
+ * @param command - 原始命令文本。
+ * @param options - `{ tokenPath }`。
+ * @returns `{ ok, token, reason? }` —— `reason` 说明为何没命中。
+ */
+export function consumeToken(command, options = {}) {
+  const path = resolveTokenPath(options)
+  const token = commandToken(command)
+  const run = chain.then(async () => {
+    const tokens = await readTokens(path)
+    if (!tokens.includes(token)) {
+      return { ok: false, token, reason: tokens.length === 0 ? '令牌文件为空' : '该命令没有对应令牌' }
+    }
+    const kept = tokens.filter(t => t !== token)
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = `${path}.tmp-${process.pid}`
+    await writeFile(tmp, kept.length > 0 ? `${kept.join('\n')}\n` : '', 'utf8')
+    await rename(tmp, path) // 原子替换
+    return { ok: true, token, remaining: kept.length }
+  })
+  chain = run.then(() => undefined, () => undefined)
+  return run
+}
+
+/**
+ * 为一条命令写入令牌(人工授权入口:`guard allow '<命令>'`)。
+ * @param command - 原始命令文本。
+ * @param options - `{ tokenPath, note }`。
+ * @returns `{ token, path, already }`。
+ */
+export function grantToken(command, options = {}) {
+  const path = resolveTokenPath(options)
+  const token = commandToken(command)
+  const run = chain.then(async () => {
+    const tokens = await readTokens(path)
+    if (tokens.includes(token)) return { token, path, already: true }
+    await mkdir(dirname(path), { recursive: true })
+    const note = options.note ? `  # ${options.note}` : `  # ${new Date().toISOString()}`
+    await writeFile(path, `${[...tokens, `${token}${note}`].join('\n')}\n`, 'utf8')
+    return { token, path, already: false }
+  })
+  chain = run.then(() => undefined, () => undefined)
+  return run
+}
+
+/**
+ * 撤销一个令牌。
+ * @param token - 形如 `ALLOW-…` 的令牌(大小写不敏感,可省略前缀)。
+ * @param options - `{ tokenPath }`。
+ * @returns `{ removed }`。
+ */
+export function revokeToken(token, options = {}) {
+  const path = resolveTokenPath(options)
+  const wanted = String(token).trim().toUpperCase()
+  const normalized = wanted.startsWith(TOKEN_PREFIX) ? wanted : `${TOKEN_PREFIX}${wanted}`
+  const run = chain.then(async () => {
+    const tokens = await readTokens(path)
+    const kept = tokens.filter(t => t.toUpperCase() !== normalized)
+    const removed = tokens.length - kept.length
+    if (removed > 0) {
+      await writeFile(path, kept.length > 0 ? `${kept.join('\n')}\n` : '', 'utf8')
+    }
+    return { removed, remaining: kept.length }
+  })
+  chain = run.then(() => undefined, () => undefined)
+  return run
+}

package/lib/verdict.js

@@ -0,0 +1,285 @@
+/**
+ * Verdict composition — the four states, the reason text, and the host mapping.
+ *
+ * Four states rather than three, because "let the model try again" and "fetch a
+ * human" are different control flows: the first closes in seconds, the second can
+ * take hours. Collapsing them either drags the human into trivia or lets the model
+ * keep rephrasing a destructive command until one phrasing slips through.
+ *
+ *   allow     — provably harmless, or the judge is confident it is.
+ *   revise    — not confident enough to run, but the model can likely do better.
+ *               Called with three deterministic downgrade templates.
+ *   block     — the judge (or an L0 rule) says this destroys something
+ *               unrecoverable; not worth retrying.
+ *   escalate  — needs a human: L0 says "always confirm", or no safer form exists.
+ */
+
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { getLang, t } from './i18n.js'
+
+/**
+ * Absolute path of the CLI entry, derived from this module's own location.
+ *
+ * Why computed instead of passed in: the hint we print tells the **user** to paste a
+ * line into their own terminal, whose cwd is arbitrary — a bare `node bin/guard.mjs`
+ * only works if they happen to sit inside the package. Deriving it here keeps every
+ * caller correct with no plumbing, and stays right if the package is moved to another
+ * machine. 调用方仍可用 `opts.cliPath` 覆盖(见 `adapters/dsh/index.js`)。
+ */
+const DEFAULT_CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'guard.mjs')
+
+/** The three deterministic downgrades offered on `revise` — no model needed. */
+const TEMPLATE_IDS = Object.freeze(['dry-run', 'narrow', 'backup-first'])
+
+/**
+ * The three downgrade templates in the language in force.
+ *
+ * Text lives in the message catalog (it is read by the model and by a human in an
+ * approval dialog), the shape stays here.
+ *
+ * @param lang - language; defaults to the one currently set.
+ * @returns `[{ id, text, examples }]`.
+ */
+export function templates(lang = getLang()) {
+  return TEMPLATE_IDS.map((id) => {
+    const examples = []
+    for (let i = 0; ; i += 1) {
+      const key = `template.${id}.example.${i}`
+      const value = t(key)
+      if (value === key) break // no such example in any language
+      examples.push(value)
+    }
+    return { id, text: t(`template.${id}.text`), examples }
+  })
+}
+
+/**
+ * 把文本包成"可以在目标 shell 里整行复制粘贴"的形式。
+ *
+ * **必须按平台分叉。** POSIX 的 `'…'` 里用 `'\''` 转义单引号;PowerShell 的 `'…'` 里靠
+ * **写两个单引号**转义。两者不通用 —— 在 PowerShell 里贴 POSIX 那种写法会直接解析失败
+ * (而这段话是给用户照抄的,失败就等于授权入口不可用)。cmd.exe 则两种都不支持,
+ * 所以另给了与 shell 无关的入口:`guard allow --command-file <文件>`。
+ *
+ * 默认用**本进程所在平台**:DSH 跑在 WSL 上时,用户能粘贴的终端通常也是 WSL/POSIX;
+ * DSH 跑在 Windows 上时,那是 PowerShell。这与"宿主和终端在同一侧"的常见部署一致。
+ *
+ * @param value - 任意文本(命令原文里可能有引号、中文、换行)。
+ * @param platform - `process.platform` 的取值;默认取当前进程。
+ * @returns 可直接粘进目标 shell 的字符串。
+ */
+export function shellQuote(value, platform = process.platform) {
+  const text = String(value)
+  if (platform === 'win32') return `'${text.replace(/'/g, "''")}'`
+  return `'${text.replace(/'/g, "'\\''")}'`
+}
+
+/**
+ * 目标 shell 的名字,写进给人看的提示里(尤其是要让用户知道该开哪个终端)。
+ * @param platform - `process.platform` 的取值。
+ * @returns 名字。
+ */
+export function shellName(platform = process.platform) {
+  return platform === 'win32' ? 'PowerShell' : t('verdict.shell.posix')
+}
+
+/**
+ * @typedef {{ action: 'allow'|'revise'|'block'|'escalate', source: string, p?: number,
+ *   model?: string, ms?: number, rule?: {id: string, why: string, kind?: 'deny'|'ask'},
+ *   reason?: string, templates?: ReturnType<typeof templates>, enriched?: string[],
+ *   error?: string, token?: string, warning?: string }} Verdict
+ */
+
+/**
+ * One-line explanation for a verdict, safe to show to a human or a model.
+ * @param command - the command under judgement.
+ * @param verdict - the verdict to explain.
+ * @param opts - `{ policy, token, cliPath, platform }`: `policy` decides what "escalate"
+ *   means for this session (see below) and, with `never`, makes a non-allow reason state
+ *   that this was an automatic decision so the model does not believe a human looked at it
+ *   and said no. `cliPath` overrides the absolute CLI path used in the one-shot-token hint.
+ *   `platform` overrides `process.platform` for the shell-quoting style of that hint.
+ * @returns the reason text.
+ */
+export function explain(command, verdict, opts = {}) {
+  const pct = verdict.p === undefined ? undefined : `${(verdict.p * 100).toFixed(1)}%`
+  const detail = verdict.rule
+    ? t('verdict.detail.rule', { id: verdict.rule.id, why: verdict.rule.why })
+    // 降级放行**不是**预筛判定出来的,不能复用那句文案 —— 否则读者会以为这条被确认过无害。
+    : verdict.source === 'degraded' ? t('verdict.detail.degraded')
+      : verdict.p === undefined ? t('verdict.detail.prefilter') : t('verdict.detail.probability', { pct })
+  // 宿主真的会弹审批框吗?这个状态**由调用方显式告知**(`opts.routedToHuman`,见 toHostDecision):
+  // 因为同一动作在不同的审批策略下会走到不同的出口(revise/block 在 ask 模式下转人工,在
+  // never 模式下仍是拒绝)。缺省推导保持旧行为(仅 escalate + ask),供 CLI / selftest 这类
+  // 不经过路由的调用使用。
+  // 读者是**弹窗**里的人和后面可能看到拒绝的模型 —— 不能说"本会话没有审批提示"。
+  // 实测(2026-09-20,ask 模式)弹窗里原样显示的就是那句旧文案,指着眼前的弹窗说没有弹窗,
+  // 还让用户复制一条终端命令 —— 所以这里按路由结果分叉。
+  const prompted = opts.routedToHuman ?? (opts.policy === 'ask' && verdict.action === 'escalate')
+  const askWait = t('verdict.askWait')
+  const head = {
+    allow: t('verdict.head.allow'),
+    revise: prompted ? t('verdict.head.prompted') : t('verdict.head.revise'),
+    block: prompted ? t('verdict.head.prompted') : t('verdict.head.block'),
+    escalate: t('verdict.head.prompted'),
+  }[verdict.action] ?? verdict.action
+  const tail = {
+    allow: '',
+    revise: prompted ? askWait : t('verdict.tail.revise'),
+    // 带 L0 `deny` 规则的 block 永远不会转人工,所以这里再挡一层:万一调用方传错,
+    // 也不能对着一条不可逆的硬规则说"等用户在弹窗里决定"。
+    block: prompted && verdict.rule?.kind !== 'deny' ? askWait : t('verdict.tail.block'),
+    escalate: prompted ? askWait : t('verdict.tail.escalate'),
+  }[verdict.action] ?? ''
+  const auto = opts.policy === 'never' && verdict.action !== 'allow' ? t('verdict.autoNote') : ''
+  // 降级告警:额度/密钥出问题时,理由必须自己说明"这一条没经过语义判定"。
+  // 否则读者会把"L0 拦下的一条"误当成"完整判定下的一条",也会把放行当成"判定过是安全的"。
+  const warn = verdict.warning ? ` ${verdict.warning}` : ''
+  // 一次性放行令牌:只在"非 allow、不是 L0 硬规则、且宿主不会真的弹审批框"时附上
+  // (见 token.js 的设计说明)。
+  // 为什么排除 prompted:那时人就在弹窗前面,再给一条"复制到终端授权"的路只会互相打架
+  // —— 实测弹窗里两条路同时出现,读者不知道该走哪条。
+  // 提示里的命令**不能截断** —— 令牌是对完整命令文本求哈希的,截断后用户授予的令牌就匹配不上。
+  // 引号按**平台**分叉(POSIX 的 `'\''` 与 PowerShell 的 `''` 不通用);Windows 上额外点明
+  // 该开哪个终端,因为 cmd.exe 两种写法都不认 —— 那种情况走 `allow --command-file`。
+  const platform = opts.platform ?? process.platform
+  const token = opts.token && verdict.action !== 'allow' && verdict.rule?.kind !== 'deny' && !prompted
+    ? t('verdict.tokenHint', {
+      winNote: platform === 'win32' ? t('verdict.winNote') : '',
+      cli: opts.cliPath || DEFAULT_CLI_PATH,
+      quoted: shellQuote(command, platform),
+      token: opts.token,
+    })
+    : ''
+  return t('verdict.line', {
+    head,
+    detail,
+    tail,
+    auto,
+    warn,
+    token,
+    command: command.length > 300 ? `${command.slice(0, 300)}…` : command,
+  })
+}
+
+/**
+ * Map a verdict onto the DSH-shaped typed decision.
+ *
+ * DSH's `ask` resolves through `ctx.approval`; under the `danger-full-access`
+ * preset the approval policy is `never`, where every ask becomes a *rejection*
+ * carrying the misleading reason "the user rejected tool bash". So when approvals
+ * are off we deny directly, with an accurate reason the model can act on.
+ *
+ * **路由随审批策略分叉**(2026-09-20 用户决定):`never`(= 全自动,没人可问)下
+ * `revise`/`block` 一律拒绝;`ask`(人就在场)下两者都转人工审批 —— 灰区本来就"证据不足",
+ * 让一个 50% 的判断替人做决定没有道理。宿主无应答者时审批是 fail-closed,所以转人工
+ * **不会**在无人值守时变成自动放行。
+ *
+ * **唯一例外**是带 L0 `deny` 规则的硬命中(`rm -rf /`、`mkfs`、`git push --force` 这类
+ * 零误报的不可逆操作):两种模式都直接拒绝,既不转人工也不发一次性令牌(见 D5/D13)。
+ *
+ * @param command - the command under judgement.
+ * @param verdict - the composed verdict.
+ * @param approvalPolicy - `'ask' | 'never'` for this session.
+ * @param opts - `{ token, cliPath, reviseInAskMode, blockInAskMode }`:一次性放行令牌会被写进
+ *   理由里(见 token.js);`cliPath` 透传给 {@link explain};后两个是 `'ask' | 'deny'` 的路由开关。
+ * @returns `{ kind: 'allow' } | { kind: 'ask', reason } | { kind: 'deny', reason }`.
+ */
+export function toHostDecision(command, verdict, approvalPolicy = 'ask', opts = {}) {
+  const reviseInAskMode = opts.reviseInAskMode ?? 'ask'
+  const blockInAskMode = opts.blockInAskMode ?? 'ask'
+  const hardRule = verdict.rule?.kind === 'deny'
+  const toHuman = approvalPolicy === 'ask' && hardRule !== true
+    && (verdict.action === 'escalate'
+      || (verdict.action === 'revise' && reviseInAskMode === 'ask')
+      || (verdict.action === 'block' && blockInAskMode === 'ask'))
+  const reason = explain(command, verdict, {
+    policy: approvalPolicy,
+    token: opts.token ?? verdict.token,
+    cliPath: opts.cliPath,
+    routedToHuman: toHuman,
+  })
+  if (verdict.action === 'allow') return { kind: 'allow' }
+  // revise and block are model-facing denials when nobody can be asked; revise additionally teaches.
+  return toHuman ? { kind: 'ask', reason } : { kind: 'deny', reason }
+}
+
+/**
+ * The full text handed to a model on `revise`, including the templates.
+ * @param command - the command under judgement.
+ * @param verdict - a `revise` verdict.
+ * @param opts - `{ policy }`, forwarded to {@link explain}.
+ * @returns multi-line guidance.
+ */
+export function reviseGuidance(command, verdict, opts = {}) {
+  const lines = [explain(command, verdict, opts), '', t('verdict.reviseHeading')]
+  // 循环变量不要叫 `t` —— 它会遮住 i18n 的查表函数。
+  for (const tpl of templates()) {
+    lines.push(t('verdict.templateLine', { text: tpl.text, examples: tpl.examples.join(' / ') }))
+  }
+  return lines.join('\n')
+}
+
+/**
+ * A coarse fingerprint of a command: whitespace collapsed, `sudo` dropped, digits
+ * masked. Good enough to notice "the model is trying the same thing again" across
+ * cosmetic rewrites, without pretending to be a semantic comparison.
+ * @param command - raw command text.
+ * @returns the fingerprint string.
+ */
+export function fingerprint(command) {
+  return String(command)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^(sudo|env|command|nohup)\s+/, '')
+    .replace(/\d+/g, '#')
+    .slice(0, 400)
+}
+
+/**
+ * Bounded per-key attempt counter.
+ *
+ * Why it exists: denying a destructive command is not the end of the story — with
+ * no human in the loop the model simply rephrases and tries again (`rm -rf` ->
+ * `find -delete` -> `python -c shutil.rmtree`). After a couple of attempts the
+ * right move is to stop the loop and surface it to a human instead of playing
+ * whack-a-mole forever.
+ */
+export class RetryBudget {
+  /**
+   * @param limit - attempts allowed before the caller should escalate.
+   * @param maxKeys - bound on tracked keys, so a long session cannot grow forever.
+   */
+  constructor(limit = 2, maxKeys = 512) {
+    this.limit = limit
+    this.maxKeys = maxKeys
+    this.map = new Map()
+  }
+
+  /**
+   * Record one attempt and report whether the budget is spent.
+   * @param key - session-scoped key (see {@link fingerprint}).
+   * @returns `{ attempts, exhausted }`.
+   */
+  hit(key) {
+    const attempts = (this.map.get(key) ?? 0) + 1
+    this.map.delete(key)
+    this.map.set(key, attempts)
+    while (this.map.size > this.maxKeys) this.map.delete(this.map.keys().next().value)
+    return { attempts, exhausted: attempts > this.limit }
+  }
+
+  /**
+   * Forget a key (call it when the command was allowed, so a later repeat starts fresh).
+   * @param key - session-scoped key.
+   */
+  clear(key) {
+    this.map.delete(key)
+  }
+
+  /** @returns the number of tracked keys. */
+  get size() {
+    return this.map.size
+  }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "dsh-jev-guard",
+  "version": "0.5.1",
+  "description": "Pre-execution safety valve for DeepSeek Harness: a TypeSafe Jev question decides whether a shell command/script would irreversibly delete or overwrite real data. Four states (allow/revise/block/escalate), mounted on tools/pre-execute. Zero dependencies; WSL/Linux (bash) and Windows (pwsh); one-shot tokens, credit-exhaustion degradation, shared audit log; bilingual (zh-CN / en) messages.",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "guard",
+    "safety",
+    "destructive-command",
+    "jev",
+    "typesafe",
+    "pre-execute",
+    "audit-log"
+  ],
+  "type": "module",
+  "main": "adapters/dsh/index.js",
+  "exports": {
+    ".": "./adapters/dsh/index.js",
+    "./gate": "./lib/gate.js",
+    "./rules": "./lib/rules.js",
+    "./verdict": "./lib/verdict.js",
+    "./audit": "./lib/audit.js",
+    "./token": "./lib/token.js",
+    "./quota": "./lib/quota.js",
+    "./cli": "./bin/guard.mjs",
+    "./adapters/dsh": "./adapters/dsh/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "jev-guard": "./bin/guard.mjs"
+  },
+  "scripts": {
+    "selftest": "node bin/guard.mjs selftest",
+    "rules": "node bin/guard.mjs rules",
+    "judge": "node bin/guard.mjs judge",
+    "status": "node bin/guard.mjs status",
+    "log": "node bin/guard.mjs log --stats"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "bin",
+    "lib",
+    "adapters",
+    "docs",
+    "tools",
+    "cordis.patch.yml",
+    "config.example.json",
+    "README.md",
+    "README.zh-CN.md",
+    "DEPLOY.md",
+    "DEPLOY.zh-CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh-CN.md",
+    "START-HERE.md",
+    "START-HERE.zh-CN.md"
+  ],
+  "license": "MIT",
+  "author": "7starsseeker",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7starsseeker/dsh-jev-guard.git"
+  },
+  "homepage": "https://github.com/7starsseeker/dsh-jev-guard#readme",
+  "bugs": {
+    "url": "https://github.com/7starsseeker/dsh-jev-guard/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/tools/check-doc-pairs.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * 文档双语对的机械校验 —— 让"两份一起改"这条规矩**可执行**,而不是靠自觉。
+ *
+ * 背景:仓库里每份给人读的文档都有两份(英文默认 + `<name>.zh-CN.md` 中文)。双语并存的
+ * 真实风险不是翻错,而是**漂移**:改了英文那份忘了中文,或者中文那份被人顺手润色,
+ * 两边从此说的不是一件事。所以这里把三件事变成断言:
+ *
+ *   A) **逐字节保真**:中文版必须等于该文件的基线(默认 `HEAD`)加上**唯一一行**语言切换行。
+ *      比对方式是枚举切换行在 H1 之后的四种插入形态(前后各 0/1 个空行)并要求逐字节命中 ——
+ *      多一个空格、少一个空行、被"顺手润色"过一个字,都会当场失败。
+ *      两边**故意一起改**的文档(切换行之外还有内容改动)用 `--edited-both` 列出,
+ *      对它们只验 B) 与"两部各有切换行"。
+ *   B) **两部同构**:英文版与中文版必须在标题层级序列、代码围栏数、表格行数、链接目标集合、
+ *      数字多重集上一致。链接比较会剔除两类注定不同的目标:同文件锚点(英文标题的锚点当然
+ *      与中文标题不同)与语言切换行互相指向的那两个文件名。
+ *   C) **残留中文清单**:英文版里剩下的中文逐行列出来供人过目。它们**只应该是被引用的实测
+ *      原文**(日志、命令样例、中文语料)—— 引用被翻译就变成了伪造,所以这类残留是对的;
+ *      除此之外的任何中文都是漏翻。
+ *
+ *   node tools/check-doc-pairs.mjs
+ *   node tools/check-doc-pairs.mjs --edited-both CHANGELOG.md,docs/DECISIONS.md
+ *   node tools/check-doc-pairs.mjs --base HEAD~1        # 换基线(例如对照上一个提交)
+ *
+ * 退出码 0 = 全部通过;1 = 有文件对没对齐(输出里逐条说明差在哪)。
+ *
+ * @module jev-guard/tools/check-doc-pairs
+ */
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** 每份"英文默认 + 中文副本"的文件。加新文档时把它加到这里,校验才有覆盖。 */
+const FILES = [
+  'README.md',
+  'CHANGELOG.md',
+  'DEPLOY.md',
+  'START-HERE.md',
+  'adapters/README.md',
+  'verification-results/README.md',
+  'docs/ARCHITECTURE.md',
+  'docs/DECISIONS.md',
+  'docs/DSH-INTEGRATION.md',
+  'docs/MEASUREMENTS.md',
+  'docs/USER-INTERVENTION.md',
+  'docs/VERIFICATION.md',
+  'docs/AGENT-TASK-dsh.md',
+]
+
+/**
+ * @param name - flag name including dashes.
+ * @param fallback - value when the flag is absent.
+ * @returns the flag's value or the fallback.
+ */
+function arg(name, fallback = undefined) {
+  const i = process.argv.indexOf(name)
+  return i > 0 ? process.argv[i + 1] : fallback
+}
+
+/** 中文副本的路径(`README.md` → `README.zh-CN.md`,其余同理)。 */
+const zhOf = (p) => (/README\.md$/.test(p) ? p.replace(/README\.md$/, 'README.zh-CN.md') : p.replace(/\.md$/, '.zh-CN.md'))
+
+/** @param p - 仓库内相对路径。 @returns 文件内容。 */
+const read = (p) => readFileSync(join(ROOT, p), 'utf8')
+
+/**
+ * @param base - git 基线。
+ * @param p - 仓库内相对路径。
+ * @returns 该文件在基线里的内容;基线里没有这份文件(刚加的新文档)时返回 null 而不是抛错。
+ */
+function atBase(base, p) {
+  try {
+    return execFileSync('git', ['show', `${base}:${p}`], { cwd: ROOT, encoding: 'utf8', maxBuffer: 1 << 26 })
+  } catch {
+    // 新加的文档在基线里当然不存在 —— 那只有"结构同构"可查,保真检查对它不适用。
+    return null
+  }
+}
+
+/** 已配对的文档名(不含 `.md`),由 FILES 推导 —— 加新文档时不必再改下面的剔除规则。 */
+const PAIR_NAMES = [...new Set(FILES.map(p => p.split('/').pop().replace(/\.md$/, '')))]
+/** 语言切换行互相指向的那两个文件名,注定不同,比对链接时剔除。 */
+const SWITCHER_TARGET = new RegExp(`(${PAIR_NAMES.join('|')})(\\.zh-CN)?\\.md$`)
+
+const headings = (s) => [...s.matchAll(/^(#{1,6})\s/gm)].map(m => m[1].length).join(',')
+const fences = (s) => (s.match(/^```/gm) ?? []).length
+const tableRows = (s) => s.split('\n').filter(l => /^\s*\|/.test(l)).length
+const links = (s) => [...s.matchAll(/\]\(([^)\s]+)\)/g)].map(m => m[1])
+  // 剔两类注定不同的目标:同文件锚点、以及语言切换行互相指向的那份文件名。
+  .filter(l => !l.startsWith('#'))
+  .filter(l => !SWITCHER_TARGET.test(l))
+  .sort()
+const numbers = (s) => [...s.matchAll(/\d+(?:\.\d+)?/g)].map(m => m[0]).sort()
+
+/**
+ * 去掉语言切换行,用于"两部同构"比较(那一行本来就该不同)。
+ * @param text - 文件内容。
+ * @returns 去掉切换行后的内容。
+ */
+const withoutSwitcher = (text) => text.split('\n').filter(l => !l.startsWith('> [English](') && !l.startsWith('> **English**')).join('\n')
+
+const base = arg('--base', 'HEAD')
+const editedBoth = new Set(String(arg('--edited-both', '')).split(',').map(s => s.trim()).filter(Boolean))
+
+let failed = 0
+for (const en of FILES) {
+  const zh = zhOf(en)
+  const zhText = read(zh)
+  const enText = read(en)
+  const original = atBase(base, en)
+
+  // A) 保真(基线里没有这份文件时,只有"两部都带切换行"这一条可查)
+  const switcher = `> [English](${en.split('/').pop()}) | **简体中文**`
+  const hasSwitchers = zhText.includes('> [English](') && enText.includes('> **English** | [简体中文](')
+  const newFile = original === null
+  let faithful = hasSwitchers
+  if (!newFile && !editedBoth.has(en)) {
+    const lines = original.split('\n')
+    const h1 = lines.findIndex(l => l.startsWith('# '))
+    const candidates = []
+    for (const before of [0, 1]) {
+      for (const after of [0, 1]) {
+        const copy = [...lines]
+        copy.splice(h1 + 1, 0, ...Array(before).fill(''), switcher, ...Array(after).fill(''))
+        candidates.push(copy.join('\n'))
+      }
+    }
+    faithful = candidates.includes(zhText)
+  }
+  if (!faithful) failed += 1
+
+  // B) 两部同构
+  const zhBody = withoutSwitcher(zhText)
+  const diff = []
+  const cmp = (name, a, b) => { if (JSON.stringify(a) !== JSON.stringify(b)) diff.push(name) }
+  cmp('标题', headings(enText), headings(zhBody))
+  cmp('代码围栏', fences(enText), fences(zhBody))
+  cmp('表格行', tableRows(enText), tableRows(zhBody))
+  cmp('链接', links(enText), links(zhBody))
+  cmp('数字', numbers(enText), numbers(zhBody))
+  // 纯数字差异通常是"中文标题序号 一/二/三 译成 1./2./3.",提示人工确认即可。
+  const onlyNumbers = diff.length > 0 && diff.every(d => d === '数字')
+  if (diff.length > 0 && !onlyNumbers) failed += 1
+
+  // C) 残留中文
+  const leftovers = enText.split('\n').filter(l => /[\u4e00-\u9fff]/.test(l) && !l.startsWith('> **English**'))
+  console.log(`${faithful && (diff.length === 0 || onlyNumbers) ? 'ok  ' : 'FAIL'} ${en}`)
+  if (!faithful) console.log(`     中文版不等于"基线 + 仅一行切换行"的任一种形态${editedBoth.has(en) ? '(该文件声明了两边一起改,只查切换行是否都在)' : ''}`)
+  if (newFile && faithful && (diff.length === 0 || onlyNumbers)) console.log('     (基线里没有这份文件:新文档只查结构同构与切换行,保真检查要等它进了基线才算数)')
+  if (diff.length) console.log(`     ${onlyNumbers ? '仅数字多重集差异(标题序号 一→1. 会造成这个)' : '两部未对齐'}: ${diff.join(', ')}`)
+  if (leftovers.length) console.log(`     英文版残留中文 ${leftovers.length} 行(应只有实测引用): ${leftovers.map(l => l.trim().slice(0, 60)).join(' || ')}`)
+}
+console.log(failed === 0 ? '\n全部文件对通过' : `\n${failed} 项失败`)
+process.exit(failed === 0 ? 0 : 1)