dsh-jev-guard 0.5.1

package/lib/quota.js

@@ -0,0 +1,389 @@
+/**
+ * 额度与降级 —— 付费判定 API 一定会用完,用完以后阀门必须**变安静,但不装死**。
+ *
+ * 背景与设计取舍:
+ *
+ * 1. **额度耗尽不是异常,是必然。** 这是一个收费 API,`HTTP 402` / 余额不足 / 密钥被撤销
+ *    迟早会发生。旧行为是"每次调用各自 fail-open 并写一条 `source: error`" —— 功能上没错,
+ *    但有三个问题:①每个命令都要打一次注定失败的请求(慢);②日志里堆满 error 记录,
+ *    看不出"是偶发抖动还是已经彻底不可用";③**没有任何人会发现它在瞎**。
+ *
+ * 2. **所以状态是持久的、可读的、有失效时间的。** 一旦判定失败属于"持久性"类
+ *    (`quota` / `auth` / `no-key`),就写一份 `<JEV_GUARD_HOME>/degraded.json`,
+ *    在冷却窗口内**不再发请求**(省钱、省时间),窗口到期后放**一次**探测请求过去:
+ *      · 探测成功 → 自动恢复(不需要人做任何事);
+ *      · 探测失败 → 继续降级(失败一次只花一次请求,不会每命令都试)。
+ *
+ * 3. **降级不等于整条阀门失效。** 默认 `degradePolicy: 'l0-only'` —— 免费的 L0 静态规则
+ *    与预筛照常工作,停的只是"要花钱联网"的 L1 语义层。这不是自作主张:那一层不花钱、
+ *    不联网、确定性强,正好覆盖最坏的一类(`mkfs` / `dd of=/dev/*` / `git push --force`)。
+ *    想连它一起停,设 `degradePolicy: 'off'`。
+ *
+ * 4. **瞬态失败不降级。** 超时 / 网络抖 / 5xx / 429 只是这一次不通,不该把阀门按下去 15 分钟;
+ *    它们照旧逐次 fail-open,但**会被分类记录**,于是 `guard log --stats` 能回答
+ *    "今天 fail-open 了几次、各是什么原因"。
+ *
+ * 5. **两种降级:有对象可探测的,和没有的**(2026-09-20,见 docs/DECISIONS.md D15)。
+ *    · `quota` / `auth` 是**服务侧**状况 → 冷却式:到期放一次探测请求,成功即自动恢复。
+ *    · `no-key` 是**本地配置**状况 → **粘性**:没密钥时一次 HTTP 都不发,没有"可探测对象",
+ *      所以它不靠时间结束,而是靠"密钥出现了"结束(见 gate.js 里读到密钥即自动清除)。
+ *    两者都受**作用域**约束:`scope: 'global'` 的服务侧状态压制所有入口;
+ *    `scope: 'local'` 的本地状态**只压制写下它的那个入口**。这正是"局部问题不该造成全局
+ *    失能"的解法 —— 旧版本的做法是干脆不降级,代价是没人看得见(见 KINDS 里的长注释)。
+ *
+ * @module jev-guard/quota
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { HOME_DIR } from './audit.js'
+import { t } from './i18n.js'
+
+/** 降级状态文件;`JEV_GUARD_DEGRADED_STATE` 可覆盖(测试/多实例用)。 */
+export const DEFAULT_DEGRADED_PATH = process.env.JEV_GUARD_DEGRADED_STATE ?? join(HOME_DIR, 'degraded.json')
+
+/**
+ * 失败分类表 —— **只放判定用的东西**。
+ *
+ * `degraded: true` 的类别 = "这不是抖一下,是人得处理点什么" → 写状态、停联网判定。
+ * `cooldownMs` 既是"停止发请求"的时长,也是"下次探测"的间隔。
+ *
+ * 给人看的 label / hint 不在这里,在 `lib/i18n.js` 的 `quota.<kind>.label|hint`
+ * (以前这里还挂着一组 `cliHints`,从头到尾没有任何调用方读取 —— 2026-09-20 清掉,
+ * 免得它成为一份不受 i18n 覆盖的隐藏文案)。
+ */
+export const KINDS = Object.freeze({
+  quota: Object.freeze({ degraded: true, scope: 'global', cooldownMs: 15 * 60 * 1000 }),
+  auth: Object.freeze({ degraded: true, scope: 'global', cooldownMs: 30 * 60 * 1000 }),
+  // "没解析到密钥"是**本地配置**状况,不是服务状况。它**也要降级**(没有效密钥时必须像
+  // 额度耗尽那样明说,而不是每条命令静默 fail-open),但降级方式与服务侧相反:
+  //   · `sticky: true` —— 一次 HTTP 都不发,没有可探测对象,所以不靠冷却到期结束,
+  //     而是靠"密钥出现了"结束(gate.js 读到密钥即自动清除,零请求)。
+  //   · `scope: 'local'` —— 密钥解析各入口独立(DSH 插件走 ctx.credentials / 环境变量 /
+  //     包根 secrets.json,CLI 走环境变量 / 那个文件),而 degraded.json 是**全局共享**的
+  //     文件。若写成全局状态,某条入口读不到密钥就会把**密钥其实是好的**其它入口一起按停
+  //     —— 那是"一个局部问题造成全局失能"。作用域把它的影响限制在写下它的入口内。
+  'no-key': Object.freeze({ degraded: true, sticky: true, scope: 'local', cooldownMs: 0 }),
+  'rate-limit': Object.freeze({ degraded: false, cooldownMs: 60 * 1000 }),
+  server: Object.freeze({ degraded: false, cooldownMs: 30 * 1000 }),
+  timeout: Object.freeze({ degraded: false, cooldownMs: 0 }),
+  network: Object.freeze({ degraded: false, cooldownMs: 0 }),
+  shape: Object.freeze({ degraded: false, cooldownMs: 0 }),
+  unknown: Object.freeze({ degraded: false, cooldownMs: 0 }),
+})
+
+/**
+ * 一个类别的可读名字(当前语言)。
+ * @param kind - 分类名。
+ * @returns 给人看的一行;未知类别原样回显分类名。
+ */
+export function kindLabel(kind) {
+  const key = `quota.${kind}.label`
+  return t(key) === key ? String(kind ?? '') : t(key)
+}
+
+/**
+ * 一个类别的处置建议(当前语言)。
+ * @param kind - 分类名。
+ * @returns 一行建议;未知类别退回 `unknown` 的建议。
+ */
+export function kindHint(kind) {
+  const key = `quota.${kind}.hint`
+  return t(key) === key ? t('quota.unknown.hint') : t(key)
+}
+
+/** 会触发"降级状态"的分类。 */
+export const DEGRADING_KINDS = Object.freeze(Object.keys(KINDS).filter(k => KINDS[k].degraded))
+
+/**
+ * 一个分类的作用域:`'global'`(服务侧,压制所有入口)或 `'local'`(本地配置,只压制写它的入口)。
+ * @param kind - 分类名。
+ * @returns 作用域名;未知分类按 `global`(宁可多压制一个未知状态,也不要让它漏过)。
+ */
+export function kindScope(kind) {
+  return KINDS[kind]?.scope === 'local' ? 'local' : 'global'
+}
+
+/**
+ * 这个状态是不是"粘性"的(= 不靠时间结束,靠条件消失结束)。
+ *
+ * 同时看状态自身与分类表:老状态文件里没有 `sticky` 字段,按分类表认出来才不会误判成
+ * "冷却已经过期了,可以再去问一次" —— 那会让没密钥的部署每个命令都重进一次判定。
+ *
+ * @param state - 降级状态。
+ * @returns true = 忽略 `until`,永不探测。
+ */
+export function isSticky(state) {
+  if (!state) return false
+  return state.sticky === true || KINDS[state.kind]?.sticky === true
+}
+
+/**
+ * 这个状态是否适用于某个入口(作用域匹配)。
+ * `global` 状态压制所有入口;`local` 状态只压制写下它的入口。
+ * @param state - 降级状态。
+ * @param scope - 入口身份(如 `'dsh-adapter'` / `'cli'`);不传 = 只认服务侧状态。
+ * @returns true = 该入口应当遵守这个状态。
+ */
+export function appliesTo(state, scope = undefined) {
+  if (!state) return false
+  const written = typeof state.scope === 'string' && state.scope !== ''
+    ? state.scope
+    : (kindScope(state.kind) === 'local' ? 'local' : 'global')
+  return written === 'global' || written === scope
+}
+
+/**
+ * 按失败类别返回冷却时长(可被配置覆盖)。
+ * @param kind - 分类名。
+ * @param cfg - 可选 `{ quotaCooldownMs, authCooldownMs }`。
+ * @returns 毫秒。
+ */
+export function cooldownMs(kind, cfg = {}) {
+  if (kind === 'quota') return Number(cfg.quotaCooldownMs ?? KINDS.quota.cooldownMs)
+  if (kind === 'auth') return Number(cfg.authCooldownMs ?? KINDS.auth.cooldownMs)
+  // 粘性分类靠"条件消失"结束,不靠时间 —— 冷却时长对它没有意义。
+  if (KINDS[kind]?.sticky === true) return 0
+  return Number(KINDS[kind]?.cooldownMs ?? 0)
+}
+
+/**
+ * 把人话/异常翻译成分类。
+ *
+ * 为什么用关键词兜底:额度耗尽的 HTTP 形状各家不同(有 402,也有 429 + "insufficient credits"),
+ * 我们**不能假设**自己猜对了。所以规则是:状态码能定就定;定不了就看正文关键词;
+ * 还定不了就是 `unknown`(不降级,只逐次放行并留痕)。宁可少降级,不要误降级 —— 误降级会让
+ * 阀门在额度充足时也停止防护。
+ *
+ * @param error - 抛出的异常(带 `status` / `code` / `name` / `message`)。
+ * @returns `{ kind, status?, detail }`。
+ */
+export function classifyFailure(error) {
+  const status = Number(error?.status) || undefined
+  const code = typeof error?.code === 'string' ? error.code : undefined
+  const name = String(error?.name ?? '')
+  const text = `${code ?? ''} ${error?.body ?? ''} ${error?.message ?? ''}`.toLowerCase()
+  const detail = String(error?.message ?? error).slice(0, 300)
+
+  if (code === 'no-key') return { kind: 'no-key', detail }
+  if (code === 'shape') return { kind: 'shape', detail }
+  if (status === 402) return { kind: 'quota', status, detail }
+  if (status === 401 || status === 403) return { kind: 'auth', status, detail }
+  if (status === 429) {
+    // 429 有两种含义:限流(等一下就好)与额度耗尽(得充钱)。正文能区分才降级。
+    return { kind: /quota|credit|insufficient|balance|payment|billing|exceed/.test(text) ? 'quota' : 'rate-limit', status, detail }
+  }
+  if (status !== undefined && status >= 500) return { kind: 'server', status, detail }
+  if (name === 'TimeoutError' || name === 'AbortError') return { kind: 'timeout', detail }
+  if (/quota|credit|insufficient|balance|payment|billing/.test(text)) return { kind: 'quota', status, detail }
+  if (/enotfound|econnrefused|econnreset|etimedout|fetch failed|network|socket/.test(text)) return { kind: 'network', detail }
+  return { kind: 'unknown', status, detail }
+}
+
+/**
+ * 解析降级状态文件路径(空串/纯空白 = 未配置 → 默认路径,与 audit 的教训一致)。
+ * @param options - `{ degradedPath }`。
+ * @returns 实际路径。
+ */
+export function resolveDegradedPath(options = {}) {
+  const configured = options?.degradedPath
+  return typeof configured === 'string' && configured.trim() !== '' ? configured : DEFAULT_DEGRADED_PATH
+}
+
+/**
+ * 读降级状态。**任何异常都当作"没有降级"**(读不出来时宁可去问一次 API,也不要卡在降级态)。
+ *
+ * 校验必须走 `untilMs()` 而不是 `Number(until)`:`until` 存的是 ISO 字符串,`Number()` 对它
+ * 恒为 NaN,于是"写进去了却永远读不出来"。本模块第一版就是这样 —— 不抛异常、不报错,
+ * 只是整个降级机制静默失效(冒烟测试当场抓到)。
+ *
+ * @param options - `{ degradedPath }`。
+ * @returns 状态对象,或 null。
+ */
+export async function readDegraded(options = {}) {
+  const path = resolveDegradedPath(options)
+  try {
+    const raw = JSON.parse(await readFile(path, 'utf8'))
+    if (!raw || typeof raw !== 'object' || typeof raw.kind !== 'string') return null
+    const until = untilMs(raw)
+    if (!Number.isFinite(until)) return null
+    // 归一成毫秒数,调用方不必再关心存的是字符串还是数字。
+    return { ...raw, until, path }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 进入(或续期)降级状态。
+ * @param kind - 失败分类。
+ * @param options - `{ error, detail, status, cfg, now, scope, probe }`;`scope` 是入口身份,
+ *   只对 `local` 分类有意义(它决定这份状态会压制谁)。
+ * @returns 写入后的状态对象(即使写盘失败也返回,调用方照常降级)。
+ */
+export async function enterDegraded(kind, options = {}) {
+  const now = Number(options.now ?? Date.now())
+  const cfg = options.cfg ?? {}
+  const path = resolveDegradedPath(cfg)
+  const cooldown = cooldownMs(kind, cfg)
+  const sticky = KINDS[kind]?.sticky === true
+  // 服务侧状态一律 global(它是整个服务的事);本地状态记下"谁写的",作用域过滤据此
+  // 把它限制在那条入口内。调用方没给身份时记 'local' —— 那个值压制不了任何入口,
+  // 也就是"宁可少压制,不要误压制"。
+  const scope = kindScope(kind) === 'local' ? String(options.scope ?? 'local') : 'global'
+  const previous = await readDegraded(cfg)
+  // 计数只在"同类别 + 同入口"时延续,否则两份无关的失败会被累加成一条假历史。
+  const sameKind = previous?.kind === kind && (previous.scope ?? 'global') === scope
+  const state = {
+    kind,
+    scope,
+    sticky,
+    // 落盘的 label 只是给"人肉读 degraded.json"用的快照;**显示**一律现查 kindLabel(),
+    // 否则语言一换,旧文件里另一种语言的标签会被原样打印出来。
+    label: kindLabel(kind) || kind,
+    since: sameKind ? previous.since : new Date(now).toISOString(),
+    until: new Date(now + cooldown).toISOString(),
+    cooldownMs: cooldown,
+    failures: (sameKind ? Number(previous.failures ?? 0) : 0) + 1,
+    probes: Number(previous?.probes ?? 0) + (options.probe ? 1 : 0),
+    status: options.status,
+    detail: String(options.detail ?? options.error ?? '').slice(0, 300),
+    policy: cfg.degradePolicy ?? 'l0-only',
+    at: new Date(now).toISOString(),
+  }
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = `${path}.tmp`
+    await writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`)
+    await rename(tmp, path)
+  } catch {
+    // 写不进去也要降级(内存里这次仍然按降级处理),只是下次可能会再试一次 API。
+  }
+  // 与 readDegraded 保持同一形状:`until` 对外一律是毫秒数(存储里是 ISO,便于人肉阅读)。
+  return { ...state, until: now + cooldown, path }
+}
+
+/**
+ * 清除降级状态(探测成功后自动调用;也可由 `guard status --clear` 手动调用)。
+ * @param options - `{ degradedPath }`。
+ * @returns true = 确实清掉了一个状态文件。
+ */
+export async function clearDegraded(options = {}) {
+  const path = resolveDegradedPath(options)
+  try {
+    const { unlink } = await import('node:fs/promises')
+    await unlink(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `until` 的毫秒表示(ISO 字符串;兼容直接存数字的老状态文件)。
+ * @param state - 降级状态。
+ * @returns 毫秒时间戳,或 NaN。
+ */
+function untilMs(state) {
+  const raw = state?.until
+  if (typeof raw === 'number') return raw
+  return Date.parse(String(raw ?? ''))
+}
+
+/**
+ * 现在是否处于降级窗口内。
+ * @param state - readDegraded() 的结果。
+ * @param now - 当前毫秒时间戳。
+ * @param scope - 本入口的身份;本地状态只压制写下它的入口(不传 = 只认服务侧状态)。
+ * @returns true = 应当跳过联网判定。
+ */
+export function isDegraded(state, now = Date.now(), scope = undefined) {
+  if (!state) return false
+  if (!appliesTo(state, scope)) return false
+  // 粘性状态没有"窗口"这回事:它一直有效,直到它描述的条件消失(见 isSticky)。
+  if (isSticky(state)) return true
+  const until = untilMs(state)
+  return Number.isFinite(until) ? until > now : false
+}
+
+/**
+ * 降级窗口是否已到期(= 下一次调用可以作为探测请求)。
+ * @param state - readDegraded() 的结果。
+ * @param now - 当前毫秒时间戳。
+ * @param scope - 本入口的身份(同 isDegraded)。
+ * @returns true = 放一次探测请求。
+ */
+export function probeDue(state, now = Date.now(), scope = undefined) {
+  if (!state) return false
+  if (!appliesTo(state, scope)) return false
+  // 粘性状态**永不探测**:没密钥时一次 HTTP 都不发,没有"可探测对象"可放。
+  // 放它过去只会让每条命令都重新撞一次 no-key,把降级变成刷屏。
+  if (isSticky(state)) return false
+  const until = untilMs(state)
+  return Number.isFinite(until) ? until <= now : true
+}
+
+/**
+ * 距离自动探测还有多少毫秒(粘性状态恒为 0:它不等时间)。
+ * @param state - 降级状态。
+ * @param now - 当前时间。
+ * @returns 毫秒(最小 0)。
+ */
+export function retryInMs(state, now = Date.now()) {
+  if (isSticky(state)) return 0
+  const until = untilMs(state)
+  return Number.isFinite(until) ? Math.max(0, until - now) : 0
+}
+
+/**
+ * 一行告警文本(会出现在拒绝理由、CLI 输出、审计记录里)。
+ * @param state - 降级状态。
+ * @param now - 当前时间。
+ * @returns 单行文本。
+ */
+export function warningLine(state, now = Date.now()) {
+  if (!state) return ''
+  const common = {
+    label: kindLabel(state.kind) || state.label,
+    since: String(state.since ?? '').slice(11, 19),
+    failures: state.failures,
+    policy: t(state.policy === 'off' ? 'quota.policy.off' : 'quota.policy.l0-only'),
+  }
+  // 粘性状态没有"多少分钟后自动恢复"这句话 —— 对它说"等 0 分钟"等于骗人,所以换一条文案。
+  if (isSticky(state)) return t('quota.warning.sticky', common)
+  return t('quota.warning', { ...common, mins: Math.round(retryInMs(state, now) / 60000) })
+}
+
+/**
+ * 多行状态报告(`guard status` 与适配器的日志都用它)。
+ * @param state - 降级状态,或 null(健康)。
+ * @param now - 当前时间。
+ * @param extra - `{ judgeUrl, apiKeyPresent }` 之类的补充信息。
+ * @returns 可直接打印的文本。
+ */
+export function statusText(state, now = Date.now(), extra = {}) {
+  if (!state) {
+    return [
+      t('quota.status.ok'),
+      t('quota.status.ok.layers'),
+      extra.apiKeyPresent === false ? t('quota.status.ok.noKey') : '',
+    ].filter(Boolean).join('\n')
+  }
+  const mins = Math.round(retryInMs(state, now) / 60000)
+  const sticky = isSticky(state)
+  return [
+    t('quota.status.degraded.title', { kind: state.kind }),
+    t('quota.status.degraded.reason', { label: kindLabel(state.kind) || state.label }),
+    t('quota.status.degraded.counters', { since: state.since, failures: state.failures, probes: state.probes ?? 0 }),
+    // 粘性状态不是在"等一个窗口",所以不打印倒计时,直接说清它什么时候结束。
+    sticky ? t('quota.status.degraded.sticky') : t('quota.status.degraded.recovery', { mins }),
+    t('quota.status.degraded.now', {
+      now: t(state.policy === 'off' ? 'quota.status.degraded.now.off' : 'quota.status.degraded.now.l0-only'),
+    }),
+    t('quota.status.degraded.action', { hint: kindHint(state.kind) }),
+    // 本地状态只影响写下它的那条入口 —— 不说清楚,别的入口会以为自己也坏了。
+    state.scope && state.scope !== 'global' ? t('quota.status.degraded.scope', { scope: state.scope }) : '',
+    state.detail ? t('quota.status.degraded.detail', { detail: state.detail }) : '',
+    t('quota.status.degraded.retry'),
+  ].filter(Boolean).join('\n')
+}

package/lib/rules.js

@@ -0,0 +1,174 @@
+/**
+ * L0 — deterministic hard rules.
+ *
+ * This layer exists because the semantic judge (L1) depends on the network, on a
+ * third-party model, and on the caller's honesty. Anything that must NEVER happen
+ * has to be decided here: no network, no model, no override, same answer every
+ * time. Rules are intentionally conservative and pattern-based; they are the
+ * cheapest layer and the one that keeps working when everything else is down.
+ *
+ * Verdicts:
+ *   'deny'  — never allow (the operation destroys something unrecoverable, or
+ *             destroys the ability to recover).
+ *   'ask'   — always confirm with a human, regardless of what L1 thinks.
+ *
+ * Edit this file to taste: every rule carries an `id`, a regex, a `why`, and
+ * optionally `where: 'command'`.
+ */
+
+/**
+ * @typedef {{ id: string, re: RegExp, why: Record<'zh-CN'|'en', string>, where?: 'command' | 'anywhere' }} Rule
+ *
+ * `why` 是**双语对象**而不是一句话:这条理由会出现在拒绝理由、`guard rules` 清单与
+ * 审计复盘里,读者可能是中文会话的人,也可能是英文部署里的人或模型。两种语言都写在
+ * 规则自己旁边(而不是集中到 i18n 目录),因为一条规则是一个自洽单元 ——
+ * 改正则的人顺手就能改理由。缺语言的规则会被 `tools/selftest-i18n.mjs` 判失败。
+ *
+ * `where: 'command'`(**默认应当是这个**)表示规则只在 COMMAND POSITION 命中:行首、或紧跟
+ * `;` `&` `|` `(` `$(` 与反引号之后、或紧跟 `bash -c "` 这类"把字符串当脚本执行"的引号之后;
+ * 中间允许一串包装器(`sudo` / `timeout 30` / `xargs -0` / `find … -exec` …)。
+ *
+ * `where: 'anywhere'` 是**显式例外**:只有那两个模式结构上无法锚定(以运算符 `>` 或
+ * 纯语法 `:(){…};:` 开头)的规则才该用它。写别的规则时不要用 —— 全文匹配会在"引号里的
+ * 数据、注释、变量赋值、代码字符串"里命中,把操作者自己的正当操作拦下来(2026-09-20 实测)。
+ *
+ * Why anchoring exists: on 2026-09-20 this valve blocked its own operator twice — once
+ * for passing a rule description as a CLI argument, once for writing a test case
+ * inside a bash heredoc. Both times the dangerous phrase was *prose*, not a call.
+ * Real invocations sit at a command position; commands hidden inside quotes are
+ * still covered by Jev (measured p for prose: 0.02–0.08; for the real thing via
+ * Jev: 0.8–1.0), so nothing meaningful is lost by anchoring.
+ *
+ * 2026-09-20 第二次修正(两个方向的偏,同一个根因 —— 锚定只做了一半):
+ *   · 假阳:21 条 deny 里只有 7 条锚定,`mkfs` 这类命令开头型规则仍在全文匹配,
+ *     于是 `python3 -c "print('mkfs.ext4 /dev/sdb1')"` 这种**数据**也会被 deny。
+ *   · 漏判:锚定用的 `^` **没有 `m` 标志**,所以"命令位置"实际只等于整串开头 ——
+ *     多行脚本(heredoc)与多行 `-c` 里的真命令全看不见,而 L0 的全部意义就是
+ *     在降级(l0-only,没有 Jev 兜底)时抓住这一类。
+ *   两者一起修:命令开头型规则统一锚定,锚定加 `m`,包装器列表扩到常见前缀。
+ *   边界矩阵在 `tools/selftest-rules.mjs`(18 种形态)。
+ */
+
+import { FALLBACK_LANG, getLang } from './i18n.js'
+
+/** `bash -c "…"`:把引号里的字符串当脚本执行 —— 那里面是一个命令位置。 */
+const SHELL_C = String.raw`(?:bash|sh|zsh|dash|ksh|pwsh|powershell|cmd)(?:\.exe)?\s+-[a-z]*c\s*["']`
+
+/**
+ * 包装器:`sudo mkfs`、`timeout 30 mkfs`、`xargs -0 mkfs`、`nice -n 5 mkfs`、`find … -exec mkfs`。
+ * 吞掉的"参数"只允许 ASCII 词/flag/路径字符 —— 刻意的:中文散文里出现 `xargs … mkfs`
+ * 这种句子不该命中(散文交给 Jev,p 只有 0.02–0.08)。
+ */
+const WRAPPERS = String.raw`(?:sudo|doas|env|command|nohup|time|nice|ionice|setsid|stdbuf|watch|timeout|xargs|parallel|find)\b\s*(?:[-\w./=:$~]+\s+)*`
+
+/** 命令位置前缀:行首(`m` 标志下即每行行首)、分隔符之后、`$(` 之后、`-c "` 之后,再加可选包装器。 */
+const COMMAND_POSITION = String.raw`(?:^|[;&|(` + '`' + String.raw`]\s*|\$\(\s*|` + SHELL_C + String.raw`)(?:` + WRAPPERS + String.raw`)?`
+
+/** 缓存:同一条规则只构造一次"命令位置"版本的正则。 */
+const anchoredCache = new WeakMap()
+
+/**
+ * 取一条规则实际用于匹配的正则。
+ * @param rule - 规则对象。
+ * @returns 用于测试的正则。
+ */
+function ruleRegex(rule) {
+  if (rule.where !== 'command') return rule.re
+  let re = anchoredCache.get(rule)
+  if (re === undefined) {
+    // `m` 必须加:否则 `^` 只匹配整串开头,多行命令里第二行起的命令位置全部失效。
+    const flags = rule.re.flags.includes('m') ? rule.re.flags : `${rule.re.flags}m`
+    re = new RegExp(COMMAND_POSITION + rule.re.source, flags)
+    anchoredCache.set(rule, re)
+  }
+  return re
+}
+
+/** Operations with no legitimate "oops I meant that" story. */
+export const DENY_RULES = /** @type {Rule[]} */ ([
+  { id: 'block-device-write', where: 'command', re: /\bdd\b[^\n]*\bof=\/dev\/(sd|nvme|vd|hd|mmcblk)/i, why: { 'zh-CN': '直接写块设备,会不可逆地覆盖磁盘内容', en: 'writes straight to a block device, irreversibly overwriting the disk' } },
+  { id: 'mkfs', where: 'command', re: /\bmkfs(\.\w+)?\b[^\n]*\/dev\//i, why: { 'zh-CN': '格式化文件系统', en: 'formats a filesystem' } },
+  // 仅有的两条 anywhere:模式以运算符 / 纯语法开头,锚定到"命令位置"没有意义。
+  { id: 'redirect-to-device', where: 'anywhere', re: />\s*\/dev\/(sd|nvme|vd|hd)/i, why: { 'zh-CN': '把输出重定向进块设备(模式以 > 开头,无法锚定)', en: 'redirects output into a block device (the pattern starts with >, so it cannot be anchored)' } },
+  { id: 'no-preserve-root', where: 'command', re: /rm\s+[^\n]*--no-preserve-root/i, why: { 'zh-CN': '带 --no-preserve-root 的递归删除', en: 'recursive delete with --no-preserve-root' } },
+  { id: 'rm-root', where: 'command', re: /rm\s+-[a-z]*\s*\/(\s|$)/i, why: { 'zh-CN': '删除文件系统根目录', en: 'deletes the filesystem root' } },
+  { id: 'fork-bomb', where: 'anywhere', re: /:\(\)\s*\{[^\n]*\}\s*;\s*:/, why: { 'zh-CN': 'fork 炸弹,会耗死机器(纯语法模式,无法锚定)', en: 'fork bomb, exhausts the machine (a pure-syntax pattern, cannot be anchored)' } },
+  { id: 'drop-database', where: 'command', re: /\bDROP\s+(DATABASE|SCHEMA|TABLE)\b/i, why: { 'zh-CN': '删除数据库/表', en: 'drops a database/table' } },
+  { id: 'truncate-database', where: 'command', re: /\bTRUNCATE\s+TABLE\b/i, why: { 'zh-CN': '清空表数据', en: 'empties a table' } },
+  { id: 'git-force-push', where: 'command', re: /git\s+push[^\n]*(\s--force(?!-with-lease)\b|\s-f\b)/i, why: { 'zh-CN': '强制推送到远端,会抹掉远端历史(此项远端不可恢复)', en: 'force-pushes to the remote, erasing remote history (this one is unrecoverable on the remote)' } },
+  { id: 'git-history-rewrite', where: 'command', re: /git\s+(filter-branch|filter-repo)\b/i, why: { 'zh-CN': '重写 git 历史', en: 'rewrites git history' } },
+  { id: 'shred-keys', where: 'command', re: /\bshred\b[^\n]*(\.ssh|\/dev\/)/i, why: { 'zh-CN': '不可恢复地销毁私钥/设备', en: 'irreversibly destroys a private key / a device' } },
+  { id: 'chmod-root', where: 'command', re: /chmod\s+-R\s+[0-7]{3,4}\s+\/(\s|$)/i, why: { 'zh-CN': '递归改根目录权限', en: 'recursively changes permissions on the root directory' } },
+  { id: 'shadow-copy-delete', where: 'command', re: /\bvssadmin\b[^\n]*delete\s+shadows/i, why: { 'zh-CN': '删除卷影副本,会毁掉还原点', en: 'deletes shadow copies, destroying restore points' } },
+  { id: 'backup-delete', where: 'command', re: /\bwbadmin\b[^\n]*delete\b/i, why: { 'zh-CN': '删除系统备份', en: 'deletes system backups' } },
+  { id: 'cipher-wipe', where: 'command', re: /\bcipher\s+\/w/i, why: { 'zh-CN': '不可恢复地擦除磁盘空闲空间', en: 'irreversibly wipes the free space on a disk' } },
+  // 原来的 `^\s*` 在加上外层锚定后会与"分隔符之后也算命令位置"打架(`cd /x && diskpart` 不命中),故去掉内层 ^。
+  { id: 'diskpart', where: 'command', re: /\bdiskpart\b/i, why: { 'zh-CN': '磁盘分区操作,极易误伤整盘', en: 'disk partitioning; very easy to hit the whole disk by mistake' } },
+  { id: 'wsl-unregister', where: 'command', re: /wsl(\.exe)?\s+--unregister/i, why: { 'zh-CN': '注销 WSL 发行版,会删除整个发行版文件系统', en: 'unregisters a WSL distribution, deleting its entire filesystem' } },
+  { id: 'kubectl-delete-ns', where: 'command', re: /kubectl\s+delete\s+(ns|namespace|pv|pvc)\b/i, why: { 'zh-CN': '删除命名空间/持久卷,会连带删除其中的数据', en: 'deletes a namespace/persistent volume, taking the data inside with it' } },
+  { id: 'ps-clear-disk', where: 'command', re: /\b(Clear-Disk|Format-Volume|Initialize-Disk)\b/i, why: { 'zh-CN': 'PowerShell 磁盘级破坏操作', en: 'a PowerShell disk-level destructive operation' } },
+  { id: 'ps-remove-item-drive-root', where: 'command', re: /Remove-Item[^\n]*-Recurse[^\n]*\b[A-Za-z]:\\\s*($|[^*])/i, why: { 'zh-CN': '递归删除整个盘符根目录', en: 'recursively deletes a whole drive root' } },
+  { id: 'rm-rf-home-root', where: 'command', re: /rm\s+-[a-z]*r[a-z]*f?\s+~\/?(\s|$)/i, why: { 'zh-CN': '删除整个家目录', en: 'deletes the entire home directory' } },
+])
+
+/** Operations that are legitimate but never silent: a human must see them once. */
+export const ASK_RULES = /** @type {Rule[]} */ ([
+  { id: 'terraform-destroy', where: 'command', re: /terraform\s+(destroy|apply\s+-auto-approve)\b/i, why: { 'zh-CN': 'terraform 会不可逆地改动真实基础设施', en: 'terraform changes real infrastructure irreversibly' } },
+  { id: 'kubectl-delete', where: 'command', re: /kubectl\s+delete\b/i, why: { 'zh-CN': '删除 Kubernetes 资源', en: 'deletes Kubernetes resources' } },
+  { id: 'docker-volume-rm', where: 'command', re: /docker\s+(volume\s+(rm|prune)|compose\s+down\s+-v)/i, why: { 'zh-CN': '删除数据卷,容器里的数据会一起没', en: 'deletes a data volume, taking the data inside the container with it' } },
+  { id: 'docker-prune-all', where: 'command', re: /docker\s+system\s+prune\s+-a/i, why: { 'zh-CN': '清理全部未使用镜像/卷', en: 'prunes every unused image/volume' } },
+  { id: 'rm-rf-git-dir', where: 'command', re: /rm\s+-[a-z]*r[a-z]*f?[^\n]*\.git\b/i, why: { 'zh-CN': '删除 .git,会丢掉全部版本历史', en: 'deletes .git, losing all version history' } },
+  { id: 'git-clean-fdx', where: 'command', re: /git\s+clean\s+-[a-z]*[fdx]/i, why: { 'zh-CN': 'git clean 会删除未跟踪文件', en: 'git clean deletes untracked files' } },
+  { id: 'git-reset-hard', where: 'command', re: /git\s+reset\s+--hard/i, why: { 'zh-CN': '丢弃未提交的改动', en: 'discards uncommitted changes' } },
+  { id: 'git-checkout-discard', where: 'command', re: /git\s+(checkout|restore)\s+(--\s|\.\s*$)/i, why: { 'zh-CN': '覆盖工作区改动', en: 'overwrites working-tree changes' } },
+  { id: 'find-delete', where: 'command', re: /\bfind\b[^\n]*-(delete|exec\s+rm)/i, why: { 'zh-CN': 'find 批量删除', en: 'bulk deletion through find' } },
+  { id: 'rsync-delete', where: 'command', re: /\brsync\b[^\n]*--delete/i, why: { 'zh-CN': 'rsync --delete 会让目标端变成源的镜像', en: 'rsync --delete makes the destination a mirror of the source' } },
+  { id: 'sql-delete-without-where', where: 'command', re: /\bDELETE\s+FROM\s+\w+\s*;?\s*$/i, why: { 'zh-CN': 'DELETE 没有 WHERE,会清空整表', en: 'DELETE without WHERE empties the whole table' } },
+  { id: 'truncate-file', where: 'command', re: /truncate\s+-s\s*0\b|(?::|true|echo)\s+(?:""|'')\s*>\s*[^\s|&]+/i, why: { 'zh-CN': '把文件截断/覆盖为空(只认显式形态;普通重定向交给 Jev 判)', en: 'truncates/overwrites a file down to empty (explicit forms only; plain redirection goes to Jev)' } },
+  { id: 'remote-code-exec', where: 'command', re: /(curl|wget|iwr|Invoke-WebRequest|Invoke-RestMethod)[^\n]*\|\s*(bash|sh|zsh|iex|Invoke-Expression)/i, why: { 'zh-CN': '把远端脚本直接喂给 shell 执行', en: 'pipes a remote script straight into a shell' } },
+  { id: 'publish-irreversible', where: 'command', re: /\b(npm|cargo|twine|poetry)\s+publish\b/i, why: { 'zh-CN': '发布到公共仓库,基本不可撤回', en: 'publishes to a public registry; effectively irreversible' } },
+  { id: 'chown-recursive-root', where: 'command', re: /chown\s+-R[^\n]*\s\/(\s|$)/i, why: { 'zh-CN': '递归改根目录属主', en: 'recursively changes ownership of the root directory' } },
+  { id: 'systemd-mask-critical', where: 'command', re: /systemctl\s+(mask|disable)\s+(ssh|network|networking|systemd-networkd)/i, why: { 'zh-CN': '停用关键系统服务,可能把机器锁在外面', en: 'disables a critical system service; can lock you out of the machine' } },
+])
+
+/**
+ * 一条规则在指定语言下的理由(`why` 是双语对象,见上面的 typedef)。
+ *
+ * 缺该语言时退回 `zh-CN`(目录语言的兜底),再缺就退回规则 id —— 理由绝不会是
+ * `undefined`,因为它会被拼进给人和模型看的拒绝理由里。
+ *
+ * @param rule - 规则对象。
+ * @param lang - 语言;默认取当前生效的语言。
+ * @returns 该语言下的理由文本。
+ */
+export function ruleWhy(rule, lang = getLang()) {
+  const table = rule?.why
+  if (typeof table === 'string') return table // 兼容老形状(单语言字符串)
+  return table?.[lang] ?? table?.[FALLBACK_LANG] ?? String(rule?.id ?? '')
+}
+
+/**
+ * Evaluate L0 for one command.
+ * @param command - raw command text.
+ * @returns the matching rule verdict, or undefined when L0 has no opinion. `why` is
+ *   already localised, so callers can paste it straight into a reason.
+ */
+export function staticRule(command) {
+  const text = String(command ?? '')
+  for (const rule of DENY_RULES) {
+    if (ruleRegex(rule).test(text)) return { kind: 'deny', id: rule.id, why: ruleWhy(rule) }
+  }
+  for (const rule of ASK_RULES) {
+    if (ruleRegex(rule).test(text)) return { kind: 'ask', id: rule.id, why: ruleWhy(rule) }
+  }
+  return undefined
+}
+
+/** Rule counts, for diagnostics. */
+export const RULE_STATS = Object.freeze({
+  deny: DENY_RULES.length,
+  ask: ASK_RULES.length,
+  anchored: [...DENY_RULES, ...ASK_RULES].filter(r => r.where === 'command').length,
+  /** 全文匹配的例外(应当恒为 2:redirect-to-device 与 fork-bomb)。 */
+  anywhere: [...DENY_RULES, ...ASK_RULES].filter(r => r.where !== 'command').length,
+})