@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/license-gate.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * license-gate —— 生产闸门的**离线许可 / 租约二选一**判定（2026-09-30）
+ *
+ * ## 为什么单独一个脚本
+ * `flow-trigger.sh` 的租约闸门是 bash 内联的，但"许可"这一侧要做四件事：
+ * ① 读 JSON（`check-license.mjs --json`）② 三态 + 能力/业务线判定 ③ 追加一行 JSONL 证据
+ * ④ 把结论翻译成人类可读一行。全塞进 bash 就得靠 grep 中文/手拼 JSON —— 那是**不可测**的。
+ * 所以判定与取证放这里（纯 Node、可单测、可注入 --now），bash 只负责"要不要停派"。
+ *
+ * ## 模式（`ARGENT_LICENSE_ENFORCE`，与 flow-trigger.sh 同一套取值）
+ *   `0` / `off`  逃生阀：**不读许可**、不停派（连判定都跳过）
+ *   `observe`    **默认**：照常计算"能不能用"，但**无论结论如何都不停派**；必须留证据
+ *   `enforce`    不可用 ⇒ 退出码 1（调用方沿用"停派 + 台账 + 人工指南"分支）
+ *
+ * ## 判定顺序（与 flow-trigger.sh 一致，**租约优先**）
+ *   ① 有可用租约（`--lease-ok 1`）⇒ 直接放行，**根本不读许可**（最大程度不改变既有行为）
+ *   ② 否则回落到离线许可：`check-license.mjs --cap <cap> [--vertical <v>] --json`
+ *      · exit 0（valid）｜3（grace：放行但告警）⇒ 可用；1（denied）⇒ 不可用
+ *
+ * ## 退出码 = **真实判定**（映射的唯一真源；调用方按 mode 决定要不要据此停派）
+ *   0 可用（放行）｜3 宽限（可用但必须告警）｜1 不可用（拒绝）｜2 用法错误
+ *   ⚠️ observe 下**照样**返回上面的真实码，但**绝不据此停派** —— 若让 observe 恒返回 0，
+ *   调用方就再也分不清"许可有效"与"许可无效但只是告警"（实测踩到：日志会把过期许可写成
+ *   "离线许可有效 ⇒ 照常派发"，正是最该看见的那条信息被抹掉）。
+ *
+ * ## 证据（验收核心）
+ *   `$ARGENT_DATA_DIR/license-gate.jsonl`（缺省 `~/.dsh/argent/license-gate.jsonl`，0600）**每次判定追加一行**：
+ *     ts / flow / cap / mode / leaseOk / licenseState / allowed / reason / decision
+ *   `decision` ∈ `dispatch`（真放行）｜`would_block`（enforce 会停派）｜`bypassed`（逃生阀）。
+ *   **每次判定都写**（含"租约可用 ⇒ 放行"，此时 `licenseState=not_checked`、`reason=lease_ok`）——
+ *   观察期要能回答"闸门到底跑没跑、走的哪条路"。文件超过 `GATE_LOG_MAX_BYTES`（默认 5MB）就轮转一次
+ *   （`license-gate.jsonl` → `license-gate.jsonl.1`，只留一份），避免客户机上无限增长。
+ *   stdout：一行人类可读结论，由 flow-trigger.sh 追加进 `flow-trigger-<flow>.out.log`。
+ *
+ * 用法：
+ *   node scripts/license-gate.mjs --flow full --cap full [--vertical <业务线id>] \
+ *        [--mode observe] [--lease-ok 0] [--log <jsonl>] [--now <ISO>]
+ */
+import { spawnSync } from 'node:child_process'
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = resolve(HERE, '..')
+export const CHECK = join(HERE, 'check-license.mjs')
+export const GATE_LOG_NAME = 'license-gate.jsonl'
+/** 证据文件上限（超过就轮转一次，只保留一份 .1）：观察期每轮一行，不设上限会一直长。 */
+export const GATE_LOG_MAX_BYTES = Number(process.env.ARGENT_LICENSE_GATE_MAX_BYTES || 5 * 1024 * 1024)
+
+/** 模式归一：`0`/`off`/`false`/`no` ⇒ off；`enforce`/`1`/`true` ⇒ enforce；其余（含未设）⇒ observe。 */
+export function normalizeMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase()
+  if (['0', 'off', 'false', 'no', 'skip'].includes(v)) return 'off'
+  if (['enforce', '1', 'true', 'yes', 'on'].includes(v)) return 'enforce'
+  return 'observe'
+}
+
+export function defaultGateLog(env = process.env) {
+  return join(resolveDataDir({ env }).dir, GATE_LOG_NAME)   // 内核三级链（唯一判据）
+}
+
+/**
+ * "租约或离线许可是否可用"（**纯函数**，唯一判定入口）。
+ * @param {object} o
+ * @param {boolean} o.leaseOk   租约是否可用（调用方已判；true ⇒ **不读许可**，现有逻辑不变）
+ * @param {object}  o.license   `check-license.mjs --json` 的输出（leaseOk=false 时必需）
+ * @param {string}  o.mode      normalizeMode 的结果
+ * @param {string}  o.flow      流程名（仅用于证据/文案）
+ * @param {string}  o.cap       能力 id（仅用于文案）
+ * @param {string}  [o.licenseFailedReason] 许可检查**跑不起来**时的原因（脚本缺失/输出不是 JSON）
+ * @returns {{allowed:boolean, decision:'dispatch'|'would_block'|'bypassed', licenseState:string,
+ *            licenseOk:boolean, reason:string, human:string}}
+ */
+export function evaluate({ leaseOk, license, mode, flow = '?', cap = '', licenseFailedReason = null }) {
+  if (mode === 'off') {
+    return {
+      allowed: true, decision: 'bypassed', licenseState: 'skipped', licenseOk: true, reason: 'enforce_off',
+      human: `许可闸门[off]：逃生阀已开（ARGENT_LICENSE_ENFORCE=off）⇒ 跳过许可与租约判定，照常派发`,
+    }
+  }
+  if (leaseOk) {
+    return {
+      allowed: true, decision: 'dispatch', licenseState: 'not_checked', licenseOk: true, reason: 'lease_ok',
+      human: `许可闸门[${mode}]：能力租约可用 ⇒ 放行（未读离线许可；现有租约逻辑不变）`,
+    }
+  }
+  // 租约不可用 ⇒ 回落离线许可（这是**唯一**的许可读取点）
+  const lic = license && typeof license === 'object' ? license : null
+  const state = lic && typeof lic.state === 'string' ? lic.state : 'denied'
+  const licOk = !licenseFailedReason && !!(lic && lic.allowed === true)
+  const baseReason = licenseFailedReason || (lic && lic.reason) || 'unreadable'
+  const gate = lic && lic.gateReason ? String(lic.gateReason) : null
+  const reason = licOk ? baseReason : (gate || baseReason)
+  const grace = licOk && lic.inGrace === true
+
+  const why = licenseFailedReason
+    ? `许可检查跑不起来（${licenseFailedReason}）`
+    : gate === 'cap_not_allowed'
+      ? `离线许可**没有这个能力**（要 ${cap}，许可只有 ${(lic.capabilities || []).join(',') || '（空）'}）`
+      : gate === 'vertical_not_allowed'
+        ? `离线许可不含业务线 ${lic.requestedVertical}`
+        : {
+            missing: '本机没有离线许可文件',
+            no_secret: '本机没有许可验签密钥（无法确认授权）',
+            bad_signature: '离线许可**验签失败**（文件被改过或密钥不对）',
+            expired: '离线许可已过期且超出宽限期',
+            malformed: '离线许可文件不合法',
+            bad_version: '离线许可版本不支持',
+            unreadable: '离线许可读不出来',
+          }[baseReason] || `离线许可不可用（${baseReason}）`
+
+  return {
+    allowed: licOk,
+    decision: licOk ? 'dispatch' : 'would_block',
+    licenseState: state,
+    licenseOk: licOk,
+    reason,
+    human: licOk
+      ? `许可闸门[${mode}]：离线许可${grace ? '在宽限期内（已过期，请尽快续期）' : '有效'}`
+        + `（cap=${cap}${lic && lic.expiresAt ? `，至 ${lic.expiresAt}` : ''}）⇒ 放行（enforce 下也会放行）`
+      : `许可闸门[${mode}]：${why}（reason=${reason}）⇒ `
+        + (mode === 'enforce' ? '本轮不派发' : 'enforce 下会停派，当前仅告警'),
+  }
+}
+
+/** 追加一行 JSONL 证据（目录自动建、文件 0600、超限轮转；写失败**不影响判定**）。 */
+export function appendEvidence(path, row, { maxBytes = GATE_LOG_MAX_BYTES } = {}) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    // 轮转：只在超限那一刻做一次（rename 是原子的；旧的 .1 直接覆盖，只留一份历史）
+    try {
+      if (maxBytes > 0 && statSync(path).size > maxBytes) renameSync(path, `${path}.1`)
+    } catch { /* 文件不存在 / 权限问题 ⇒ 照常追加 */ }
+    appendFileSync(path, JSON.stringify(row) + '\n', { mode: 0o600 })
+    try { if ((statSync(path).mode & 0o077) !== 0) chmodSync(path, 0o600) } catch { /* 权限收不紧不致命 */ }
+    return true
+  } catch { return false }
+}
+
+/**
+ * 取 `check-license.mjs --json` 的输出。
+ * 刻意把"跑不起来"（脚本缺失/输出不是 JSON）与"判定为拒绝"分开 —— 前者是我们自己的故障，
+ * 后者是客户的授权状态，两种事的处置完全不同（证据里的 reason 一眼能分）。
+ */
+export function readLicense({ file, cap, vertical, now, env, timeout = 20000 } = {}) {
+  const args = [CHECK, '--json']
+  if (file) args.push('--file', file)
+  if (cap) args.push('--cap', cap)
+  if (vertical) args.push('--vertical', vertical)
+  if (now) args.push('--now', now)
+  const r = spawnSync(process.execPath, args, { encoding: 'utf8', env: env || process.env, timeout })
+  let json = null
+  try { json = JSON.parse(String(r.stdout || '')) } catch { json = null }
+  if (json) return { license: json, failedReason: null, code: r.status ?? 1 }
+  const err = String(r.stderr || '').trim().split('\n').filter(Boolean).pop() || ''
+  return {
+    license: null,
+    failedReason: r.error
+      ? `checker_error:${r.error.code || r.error.message}`
+      : `checker_exit_${r.status ?? '?'}${err ? `:${err.slice(0, 120)}` : ''}`,
+    code: r.status ?? 1,
+  }
+}
+
+export function parseArgs(argv, env = process.env) {
+  const has = (n) => argv.includes(n)
+  const of = (n, d = null) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? d) : d }
+  if (has('-h') || has('--help')) return { help: true }
+  return {
+    flow: of('--flow') || '?',
+    cap: of('--cap') || '',
+    vertical: of('--vertical'),
+    mode: normalizeMode(of('--mode') ?? env.ARGENT_LICENSE_ENFORCE),
+    leaseOk: ['1', 'true', 'yes', 'ok'].includes(String(of('--lease-ok', '0')).toLowerCase()),
+    log: of('--log') || defaultGateLog(env),
+    file: of('--file'),
+    now: of('--now'),
+    quiet: has('--quiet'),
+    // `--json`（2026-10-03 P1 第二批加）：只给**程序消费**用（`core/lib/license-guard.mjs` 读它拿判定，
+    // 不再自己算一遍）。**不改判定、不改证据**：证据行与退出码与不带 --json 时逐字相同。
+    json: has('--json'),
+    // `--force` 或 `ARGENT_LICENSE_GATE_FORCE=1`：即使租约可用也去读一次许可并留证。
+    // 用途：客户机想**独立核对**"离线许可本身还有效吗"（不依赖租约那条路径），
+    // 或运维想在证据里看到每轮的"闸门确实跑过"心跳。
+    force: has('--force') || ['1', 'true', 'yes', 'on'].includes(String(env.ARGENT_LICENSE_GATE_FORCE || '').toLowerCase()),
+  }
+}
+
+function die(m) { console.error(`✗ ${m}`); process.exit(2) }
+
+function main() {
+  const argv = process.argv.slice(2)
+  const a = parseArgs(argv)
+  if (a.help) {
+    console.log('用法：node scripts/license-gate.mjs --flow <flow> --cap <cap> [--vertical <v>] \\')
+    console.log('        [--mode 0|off|observe|enforce] [--lease-ok 0|1] [--log <jsonl>] [--now <ISO>] [--quiet] [--force] [--json]')
+    console.log('退出码 = 真实判定：0 可用 ｜ 3 宽限（可用但告警）｜ 1 不可用 ｜ 2 用法错误')
+    console.log('  注意：停不停派由调用方按 mode 决定 —— observe 下无论返回什么码都必须继续派发。')
+    console.log('  --force / ARGENT_LICENSE_GATE_FORCE=1：即使租约可用也去读许可并留证（默认走快速路径）')
+    process.exit(0)
+  }
+  if (!argv.length) die('缺参数：至少需要 --flow 与 --cap')
+  if (a.now && !Number.isFinite(Date.parse(a.now))) die(`--now 不是可解析的时间：${a.now}`)
+
+  // 租约可用且非 force ⇒ 走快速路径：不读许可、不落判定（客户机每 5 分钟一轮，开销接近 0）。
+  // force 时把 leaseOk 视为 false ⇒ 一定要读一次许可（这也是 `--lease-ok 1 --force` 的意义）。
+  const leaseOk = a.leaseOk && !a.force
+  if (a.mode !== 'off' && !leaseOk) {
+    const { license, failedReason } = readLicense({
+      file: a.file, cap: a.cap, vertical: a.vertical, now: a.now, env: process.env,
+    })
+    var verdict = evaluate({ leaseOk, license, mode: a.mode, flow: a.flow, cap: a.cap, licenseFailedReason: failedReason })
+  } else {
+    var verdict = evaluate({ leaseOk, license: null, mode: a.mode, flow: a.flow, cap: a.cap })
+  }
+
+  // 证据：**每次判定都留一行**（含"租约可用 ⇒ 放行、未读许可"）——
+  // 观察期要能回答"闸门跑没跑、走的哪条路"，缺了这条最常见的记录，文件里只剩异常样本。
+  // 增长由 appendEvidence 的轮转兜住（>5MB ⇒ .1，只留一份）。
+  appendEvidence(a.log, {
+    ts: new Date().toISOString(),
+    flow: a.flow,
+    cap: a.cap,
+    mode: a.mode,
+    leaseOk: a.leaseOk,
+    licenseState: verdict.licenseState,
+    allowed: verdict.allowed,
+    reason: verdict.reason,
+    decision: verdict.decision,
+  })
+  // 退出码 = 真实判定（见文件头）：0 可用 ｜ 3 宽限 ｜ 1 不可用。
+  // **停不停派由调用方按 mode 决定**：observe 下无论这个码是什么都必须继续派发。
+  const verdictCode = !verdict.allowed ? 1 : (verdict.licenseState === 'grace' ? 3 : 0)
+  if (a.json) {
+    // 一行 JSON（stdout 只有它 ⇒ 调用方直接 JSON.parse）。`human` 一并带上，日志里仍有人话。
+    console.log(JSON.stringify({ ...verdict, mode: a.mode, flow: a.flow, cap: a.cap, vertical: a.vertical || null, log: a.log, exit: verdictCode }))
+  } else if (!a.quiet) console.log(verdict.human)
+  process.exit(verdictCode)
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) main()

package/engine/scripts/lip_backlog.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""lip_backlog —— **只读对账**：lip 表里那些行，到底哪些是"人工已完成的历史数据"、
+哪些是真待处理、哪些只是没到放行条件。
+
+## 为什么需要它（2026-09-22 用户口径）
+> "lip 表中有很多行都是之前客户运营人员手动完成的数据，所以要分辨清楚了。"
+
+流程每轮只报"可派发 0｜等人补字段 0"，看不出**为什么**没有票：是表里没数据？还是数据都做完了？
+还是运营没勾放行？这三件事的处置完全不同（补录 / 什么都不用做 / 催勾选）。
+本命令把"路由到的全部行"逐行分类（**只读**，不写任何字段、不派发、不落卡），给出可核对的数字。
+
+分类**按注册表规则判定**（`source.pick`：`equals` 门 + `excludeEquals`/`excludeAllPresent` 排除），
+不硬编码列名 ⇒ 两个发票流程、FULL、日报都能用同一套口径。
+
+用法：
+  python3 scripts/lip_backlog.py --flow xzh-invoice [--flow wenyao-invoice] [--examples 3] [--json]
+退出码：0 正常；2 源读取失败
+"""
+from __future__ import annotations
+import argparse, json, pathlib, subprocess, sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+DATA = pathlib.Path(resolve_data_dir()['dir'])
+CASES = DATA / 'flow-cases'
+PY = sys.executable
+
+
+def cfg(flow: str, key: str):
+    p = subprocess.run([PY, str(HERE / 'flow_config.py'), '--flow', flow, '--get', key],
+                       capture_output=True, text=True)
+    try:
+        return json.loads(p.stdout)
+    except Exception:                                            # noqa: BLE001
+        return None
+
+
+def read_flow_fields(flow: str) -> dict:
+    """流程声明的栏位名（`source.fields.status/ready/store`）——判定"状态/放行"门要用。"""
+    return cfg(flow, 'source.fields') or {}
+
+
+def read_flow_rows(flow: str) -> tuple:
+    """拿**路由后的全部行**（不应用 pick 门）⇒ (rows, err)。只读。"""
+    kind = cfg(flow, 'source.kind') or 'feishu-base'
+    p = subprocess.run([PY, str(HERE / 'flow_source.py'), '--flow', flow, '--source', kind,
+                        '--no-pick-filter', '--json'], capture_output=True, text=True, timeout=600)
+    if not p.stdout.strip().startswith('{'):
+        return [], (p.stderr or p.stdout).strip()[:200]
+    doc = json.loads(p.stdout)
+    rows = []
+    for item in doc.get('cases') or []:
+        f = CASES / f"{flow}__{item.get('ticket')}.json"
+        fields = {}
+        if f.exists():
+            try:
+                fields = json.loads(f.read_text(encoding='utf-8')).get('fields') or {}
+            except Exception:                                    # noqa: BLE001
+                fields = {}
+        rows.append({'ticket': item.get('ticket'), 'fields': fields, 'missing': item.get('missing') or []})
+    return rows, ''
+
+
+def _truthy(v) -> bool:
+    return str(v).strip().lower() in ('true', '1', 'yes', '是', '已勾选', '✓')
+
+
+def classify(rows: list, pick: dict, fields: dict = None) -> dict:
+    """按注册表规则把每行归桶（纯函数，便于回归测试）。
+
+    镜像 `flow_source.apply_pick` 的判定顺序：排除 → 状态门 → equals 门 → 必填空 → 放行勾。
+    分桶口径（**只描述、不改数据**）：
+      done              已完成（人工/既往）：命中 excludeEquals / excludeAllPresent
+      gate_not_met      未到放行条件：状态门或 equals 门未过（等运营/等上游）
+      await_release     已识别但放行勾未勾（运营勾一下就进候选）
+      gate_met_missing  门内但缺字段（等人补）
+      gate_met_ready    真待处理（门内、字段齐）
+    """
+    names = fields or {}
+    status_col = names.get('status') or ''
+    want_status = [str(x).strip().lower() for x in (pick.get('status') or [])]
+    equals = {str(k): str(v).strip().lower() for k, v in (pick.get('equals') or {}).items()}
+    ex_eq = {str(k): [str(x).strip().lower() for x in (v if isinstance(v, list) else [v])]
+             for k, v in (pick.get('excludeEquals') or {}).items()}
+    ex_all = [[str(c) for c in grp] for grp in (pick.get('excludeAllPresent') or []) if grp]
+    require_empty = list(pick.get('requireEmpty') or [])
+    release = pick.get('release') or {}
+    rel_col = release.get('field') or names.get('ready') or ''
+    rel_want = release.get('equals', True)
+
+    def truthy(v) -> bool:
+        return str(v).strip().lower() in ('true', '1', 'yes', '是', '已勾选', '✓')
+
+    buckets, reasons, examples, miss = {}, {}, {}, {}
+    for r in rows:
+        f = r.get('fields') or {}
+
+        def val(k):
+            return str(f.get(k) or '').strip()
+
+        if (ex_eq and any(val(k).lower() in v for k, v in ex_eq.items())) or \
+           (ex_all and any(all(val(c) for c in grp) for grp in ex_all)):
+            b, why = 'done', '人工/既往已完成'
+        else:
+            unmet = [k for k, want in equals.items() if val(k).lower() != want]
+            got = val(status_col).lower() if status_col else ''
+            if status_col and want_status and got not in want_status:
+                b, why = 'gate_not_met', f'{status_col}={val(status_col) or "空"} 未识别'
+            elif unmet:
+                b, why = 'gate_not_met', '、'.join(f'{k}≠{(pick.get("equals") or {}).get(k)}' for k in unmet)
+            elif require_empty and any(val(c) for c in require_empty):
+                b, why = 'gate_not_met', f'{"、".join(require_empty)} 非空'
+            elif rel_col and not (truthy(f.get(rel_col)) if rel_want is True
+                                  else val(rel_col).lower() == str(rel_want).strip().lower()):
+                b, why = 'await_release', f'{rel_col} 未勾'
+            elif r.get('missing'):
+                b, why = 'gate_met_missing', '缺 ' + '、'.join(str(x) for x in r['missing'][:6])
+                for m in r['missing']:
+                    miss[m] = miss.get(m, 0) + 1
+            else:
+                b, why = 'gate_met_ready', '门内字段齐'
+        buckets[b] = buckets.get(b, 0) + 1
+        reasons[why] = reasons.get(why, 0) + 1
+        examples.setdefault(b, []).append(r.get('ticket'))
+    return {'total': len(rows), 'buckets': buckets, 'reasons': reasons,
+            'missingInGate': miss, 'examples': examples}
+
+
+LABELS = {'done': '已完成（人工/既往，不该动）', 'gate_not_met': '未到放行条件（等运营/等上游）',
+          'await_release': '已识别但放行勾未勾', 'gate_met_ready': '真待处理（门内、字段齐）',
+          'gate_met_missing': '门内但缺字段（等人补）'}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='lip 表只读对账：分辨人工已完成 vs 真待处理')
+    ap.add_argument('--flow', action='append', required=True)
+    ap.add_argument('--examples', type=int, default=3)
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+    out = {}
+    for flow in a.flow:
+        pick = cfg(flow, 'source.pick') or {}
+        rows, err = read_flow_rows(flow)
+        if err:
+            print(f"❌ {flow}：源读取失败：{err}", file=sys.stderr)
+            return 2
+        res = classify(rows, pick, read_flow_fields(flow))
+        out[flow] = res
+        if a.json:
+            continue
+        print(f"\n── {flow}：路由到 {res['total']} 行")
+        for b in ('done', 'gate_not_met', 'await_release', 'gate_met_ready', 'gate_met_missing'):
+            n = res['buckets'].get(b, 0)
+            if not n:
+                continue
+            print(f"   {LABELS[b]:28} {n:>4} 张"
+                  + (f"｜例：{', '.join(str(x) for x in res['examples'][b][:a.examples])}" if a.examples else ''))
+        if res['reasons']:
+            print("   原因分布：" + "｜".join(f"{k} {n} 张"
+                                          for k, n in sorted(res['reasons'].items(), key=lambda x: -x[1])[:6]))
+        if res['missingInGate']:
+            print("   门内缺字段：" + "｜".join(f"{k} {n} 张"
+                                            for k, n in sorted(res['missingInGate'].items(), key=lambda x: -x[1])))
+    if a.json:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/engine/scripts/lip_table.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""lip 表目标与字段 id 的**唯一解析入口**（2026-09-20 迭代1-残留项）。
+
+## 为什么要有它
+`wenyao_run.py` 里曾写死 `BASE/TABLE/PROFILE` + **21 条字段 id**（`fldV3Q64fj`…），
+`invoice_lip_runner.py` 里还残留 1 条。后果：
+  · **换客户/换表 = 改代码**（与"能力层 + 集成层"的目标相反）；
+  · 字段 id 是**表相关**的：客户另建一张同名字段的表，id 全不同 ⇒ 写回/上传会打到错的列；
+  · 与 FULL/发票流程"表 id 走 env"的口径不一致（同一仓库两种写法）。
+
+## 口径
+- **表/身份**：经 `flow_config.py`（唯一配置读取点）解析 ⇒ 走部署 env（`fulfillment.env` 的
+  `FULL_BASE_TOKEN/FULL_TABLE_ID/FULL_LARK_PROFILE`），解析失败**响亮失败**（不猜表）。
+- **字段 id**：运行时用 `lark-cli base +field-list` 拉一次，建 `名 → id` 映射并进程内缓存；
+  查不到的字段名**原样返回**（lark-cli 允许按名传，但按名解析偶发 `20008` ⇒ 优先用 id）。
+
+用法：
+    import lip_table
+    t = lip_table.target("wenyao-invoice")        # {'flow','base','table','profile'}
+    fid = lip_table.field_id("发票文件", t)        # 'fldvmra3Rp'（运行时解析，不写死）
+    names = lip_table.field_names(t)              # 反向映射（id → 名），排查用
+    lip_table.clear_cache()                       # 测试用
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+
+# 进程内缓存：{ (flow): {'target': {...}, 'by_name': {...}, 'by_id': {...}} }
+_CACHE: dict = {}
+
+
+def target(flow: str = "wenyao-invoice", *, base: str = "", table: str = "", profile: str = "") -> dict:
+    """解析流程的表/身份（走 flow_config ⇒ 部署 env）。显式传入的参数优先（测试/排障）。"""
+    if base and table and profile:
+        return {"flow": flow, "base": base, "table": table, "profile": profile}
+    key = f"target::{flow}"
+    if key in _CACHE:
+        return dict(_CACHE[key])
+    sys.path.insert(0, str(HERE))
+    import flow_config  # noqa: PLC0415  同目录模块，延迟导入避免循环
+
+    try:
+        cfg = flow_config.load_config(flow)      # strict：缺 env 直接 exit 2
+    except SystemExit as exc:                     # pragma: no cover - 由 flow_config 打印原因
+        raise RuntimeError(f"流程 {flow} 配置不可解析（缺部署 env？）：{exc}") from exc
+    src = cfg.get("source") or {}
+    got = {k: str(src.get(k) or "") for k in ("base", "table", "identity")}
+    if not (got["base"] and got["table"] and got["identity"]):
+        raise RuntimeError(f"流程 {flow} 未解析出 base/table/identity（检查注册表 source.*Env 与部署 env）")
+    out = {"flow": flow, "base": got["base"], "table": got["table"], "profile": got["identity"]}
+    _CACHE[key] = dict(out)
+    return out
+
+
+def field_map(t: dict | None = None, flow: str = "wenyao-invoice") -> dict:
+    """运行时拉 `+field-list` → {'by_name': {名: id}, 'by_id': {id: 名}}（进程内缓存）。
+
+    失败时抛 RuntimeError（**不静默**）：字段 id 拿不到就等于写回目标不确定，
+    宁可不跑，也不要用"按名写"去赌偶发的 20008。
+    """
+    t = t or target(flow)
+    key = f"fields::{t['flow']}::{t['base']}::{t['table']}"
+    if key in _CACHE:
+        return _CACHE[key]
+    cmd = ["lark-cli", "--profile", t["profile"], "base", "+field-list",
+           "--base-token", t["base"], "--table-id", t["table"], "--as", "bot", "--format", "json"]
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=120)
+        d = json.loads(r.stdout)
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(f"拉取字段清单失败（{t['flow']}）：{exc}") from exc
+    fields = ((d.get("data") or {}).get("fields")) or []
+    by_name, by_id = {}, {}
+    for f in fields:
+        nm, fid = str(f.get("name") or ""), str(f.get("id") or "")
+        if nm and fid:
+            by_name[nm] = fid
+            by_id[fid] = nm
+    if not by_name:
+        raise RuntimeError(f"字段清单为空（{t['flow']} {t['table']}）——检查该 bot 是否有表权限")
+    got = {"by_name": by_name, "by_id": by_id}
+    _CACHE[key] = got
+    return got
+
+
+def field_id(name: str, t: dict | None = None, flow: str = "wenyao-invoice") -> str:
+    """字段名 → id；查不到就**原样返回**（lark-cli 允许按名，但优先 id，避免偶发 20008）。"""
+    if not name:
+        return name
+    try:
+        return field_map(t, flow)["by_name"].get(name, name)
+    except RuntimeError:
+        return name          # 拉不到清单时降级为按名（调用方的读回验收会暴露问题）
+
+
+def field_names(t: dict | None = None, flow: str = "wenyao-invoice") -> dict:
+    """id → 名（排查用）。"""
+    return dict(field_map(t, flow)["by_id"])
+
+
+def clear_cache() -> None:
+    _CACHE.clear()
+
+
+def main(argv=None) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(description="lip 表目标与字段 id 解析（唯一入口）")
+    ap.add_argument("--flow", default="wenyao-invoice")
+    ap.add_argument("--field", help="查某个字段名的 id")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    try:
+        t = target(a.flow)
+        if a.field:
+            fid = field_map(t, a.flow)["by_name"].get(a.field)
+            print(json.dumps({"flow": a.flow, "field": a.field, "id": fid}, ensure_ascii=False) if a.json
+                  else f"  {a.field} → {fid or '（表里没有这个字段名）'}")
+            return 0 if fid else 1
+        fm = field_map(t, a.flow)
+        if a.json:
+            print(json.dumps({"target": t, "field_count": len(fm["by_name"]), "by_name": fm["by_name"]},
+                             ensure_ascii=False, indent=2))
+        else:
+            print(f"  流程 {a.flow}｜base {t['base'][:12]}…｜table {t['table']}｜身份 {t['profile']}"
+                  f"｜字段 {len(fm['by_name'])} 个（运行时解析，无硬编码）")
+        return 0
+    except RuntimeError as exc:
+        print(f"❌ {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+# ── 全表读取（2026-09-23 事故：分页漏行）──────────────────────────────
+# 事故：`+record-list --format json` 的 `--limit` **上限只有 200**，而表有 531 行 ⇒
+# 任何"只读前 200 行"的对账/扫描都会**静默漏行**（用户指出"就绪=真 ∧ 待执行"的 6 条没被看到，
+# 就是因为我看的是前 200 行）。正确读法：
+#   · `--format ndjson --limit 2000`：一次拿全表（ndjson 上限 2000）
+#   · `--output` 必须是**相对路径**（绝对路径被 CLI 拒：unsafe file path）
+#   · ndjson 行是**扁平**结构：字段在顶层 + `record_id`（不是嵌套 fields）
+#   · 超过 2000 行才需要分页（本表 531 行，一次到位）
+def all_rows(profile: str = None, base: str = None, table: str = None, limit: int = 2000,
+             filter_json: str = "") -> list:
+    """读**全表**（ndjson）→ [{字段…, _id}]。绝不能退回 json 格式（会截断到 200 行）。"""
+    import json as _json, os as _os, subprocess as _sp, tempfile as _tf
+    prof = profile or _os.environ.get("LARK_PROFILE") or _os.environ.get("FULL_LARK_PROFILE") or "lip-customer"
+    b = base or _os.environ.get("FULL_BASE_TOKEN") or ""
+    t = table or _os.environ.get("FULL_TABLE_ID") or ""
+    tmpdir = _tf.mkdtemp(prefix="lip-rows-")
+    out = "rows.ndjson"
+    cmd = ["lark-cli", "--profile", prof, "base", "+record-list", "--base-token", b,
+           "--table-id", t, "--as", "bot", "--format", "ndjson",
+           "--limit", str(limit), "--output", out]
+    if filter_json:
+        cmd += ["--filter-json", filter_json]        # 服务端过滤（与 ndjson 兼容，省流量）
+    r = _sp.run(cmd, capture_output=True, text=True, timeout=300, cwd=tmpdir)
+    path = _os.path.join(tmpdir, out)
+    rows = []
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    d = _json.loads(line)
+                except Exception:
+                    continue
+                if isinstance(d, dict):
+                    d = dict(d)
+                    d["_id"] = d.get("record_id") or d.get("_id")
+                    rows.append(d)
+    except OSError:
+        pass
+    if not rows:
+        raise RuntimeError(f"全表读取失败（{len(rows)} 行；stderr={(r.stderr or '')[:150]}）——"
+                           f"不要退回 --format json（会被截断到 200 行）")
+    return rows