@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/wenyao-fixture-export.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""wenyao-fixture-export.py — 从（有权限的）机器上只读导出「上海文鳐」测试夹具（2026-09-10）
+
+用途：lip 表在客户 Base（`K8zjbMB9TaGKADsruYRcuKPFnAe`），**本机 bot 无权限（91403）**。
+在**有权限的机器**（Huangwei 客户机）上跑本脚本，把 `FULL状态=已完成` 且 `货代` 含目标货代的行
+以 **JSON 全字段**导出（我不预设 lip 表列名，导出后按实际字段名适配），再把这一个 JSON 文件
+拷到本机 `~/.dsh/argent/` 做夹具 —— 本机全程不碰 lip 表、不碰生产。
+
+只读：只调用 `base +record-list`，不写任何字段。
+
+用法（在客户机执行）：
+  ~/.dsh/argent/venv/bin/python3 scripts/wenyao-fixture-export.py --carrier 文鳐 --limit 3 --out ~/wenyao-fixture.json
+  然后：scp ~/wenyao-fixture.json <本机>:~/.dsh/argent/wenyao-fixture.json   （或飞书发文件给自己）
+
+参数：--profile（默认 ml-fulfillment）--base-token（默认 lip base）--table-id（默认 lip 表）
+      --carrier（货代匹配子串，默认 文鳐）--fstate（FULL 状态列名，默认 FULL状态）--limit（默认 3）
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+# 2026-09-20（迭代1-残留项）：底座/表改走部署 env（可 --base/--table 覆盖），不再写死。
+# 用途是"导出夹具"，所以缺 env 时给的是**明确的报错**而不是猜一张表。
+LIP_BASE = os.environ.get("FULL_BASE_TOKEN", "")
+LIP_TABLE = os.environ.get("FULL_TABLE_ID", "")
+
+
+def find_lark():
+    for c in (shutil.which("lark-cli"), f"{os.path.expanduser('~')}/.local/bin/lark-cli",
+              f"{os.path.expanduser('~')}/node/bin/lark-cli", "/opt/homebrew/bin/lark-cli"):
+        if c and os.path.exists(c):
+            return c
+    return "lark-cli"
+
+
+def fetch_markdown(lark, profile, base, table, limit):
+    cmd = [lark, "--profile", profile, "base", "+record-list",
+           "--base-token", base, "--table-id", table, "--as", "bot", "--format", "markdown",
+           "--limit", str(limit)]
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise RuntimeError(f"lark-cli 失败({r.returncode}): {(r.stderr or r.stdout)[:300]}")
+    return r.stdout
+
+
+def parse_md(text):
+    rows = [l for l in text.splitlines() if l.strip().startswith("|")]
+    if len(rows) < 2:
+        return [], []
+    def cells(line):
+        return [c.strip() for c in line.strip().strip("|").split("|")]
+    header = cells(rows[0])
+    body = [cells(r) for r in rows[2:] if r.strip().startswith("|")]
+    return header, body
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--profile", default="ml-fulfillment")
+    ap.add_argument("--base-token", default=LIP_BASE)
+    ap.add_argument("--table-id", default=LIP_TABLE)
+    ap.add_argument("--carrier", default="文鳐")
+    ap.add_argument("--fstate", default="FULL状态")
+    ap.add_argument("--limit", type=int, default=3)
+    ap.add_argument("--out", default="-")
+    a = ap.parse_args()
+
+    lark = find_lark()
+    md = fetch_markdown(lark, a.profile, a.base_token, a.table_id, a.limit)
+    header, body = parse_md(md)
+    if not header:
+        print(json.dumps({"ok": False, "why": "未解析到表格（可能无权限或表为空）", "head": md[:200]}, ensure_ascii=False))
+        return 1
+    idx = {name: i for i, name in enumerate(header)}
+
+    def val(row, name):
+        i = idx.get(name)
+        return row[i] if i is not None and i < len(row) else ""
+
+    picked = []
+    for row in body:
+        fstate = val(row, a.fstate)
+        carrier = val(row, "货代公司") or val(row, "货代")
+        if "已完成" not in fstate:
+            continue
+        if a.carrier and a.carrier not in carrier:
+            continue
+        rec = {}
+        for i, name in enumerate(header):
+            if i < len(row):
+                rec[name] = row[i]
+        picked.append(rec)
+        if len(picked) >= a.limit:
+            break
+
+    out = {"ok": True, "source": {"base": a.base_token, "table": a.table_id, "profile": a.profile},
+           "filter": {"FULL状态": "contains 已完成", "货代": f"contains {a.carrier}"},
+           "columns": header, "rows": picked}
+    payload = json.dumps(out, ensure_ascii=False, indent=1)
+    if a.out == "-":
+        print(payload)
+    else:
+        with open(a.out, "w", encoding="utf-8") as f:
+            f.write(payload)
+        os.chmod(a.out, 0o600)
+        print(json.dumps({"ok": True, "rows": len(picked), "columns": len(header), "out": a.out,
+                          "hint": f"拷到本机：scp {a.out} <本机>:~/.dsh/argent/wenyao-fixture.json"}, ensure_ascii=False))
+    return 0 if picked else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engine/scripts/wenyao-invoice-writeback.mjs

@@ -0,0 +1,540 @@
+#!/usr/bin/env node
+/**
+ * 上海文鳐发票流程 · 生产表回写器（P1，2026-09-11）
+ *
+ * 目标：把**已确认的**填报件写回客户 lip 表（Base `K8zjbMB9TaGKADsruYRcuKPFnAe` /
+ * 表 `tblj6CBX0JQWDLhh`）的**指定一条记录**：附件字段 `发票文件` 追加文件 + `发票状态` 置「填写中」。
+ *
+ * 设计红线（在客户生产表上写入，必须可回滚、可审计、最小面）：
+ *  ① **字段白名单**：只允许 `发票状态` / `发票文件` / `大货标签` / `发票错误信息`；其余字段一律拒绝。
+ *     附件字段**不允许**当普通 CellValue 写（必须走 `+record-upload-attachment`）。
+ *  ② **记录白名单**：必须显式 `--allow-record <record_id>`；不给就拒绝，避免误伤其他行。
+ *  ③ **状态机**：`已完成/已上传/标签已下载` 属终态，回写需 `--force`；同值写视为 noop。
+ *  ④ **写前整行备份**：以「字段名 → 值」结构落 `~/.dsh/argent/invoice-writeback/backup/`（按名映射，不用位置猜）。
+ *  ⑤ **写后读回验收** + **审计 JSONL**（每次写入一行，含 old/new/file_token）。
+ *  ⑥ 默认 `--dry-run`（只打印计划，不写）；真写需显式 `--yes`。
+ *
+ * 守卫函数是纯函数（无 IO），`scripts/tests/wenyao-writeback.test.mjs` 直接 import 断言。
+ *
+ * 用法：
+ *   node scripts/wenyao-invoice-writeback.mjs \
+ *     --record-id recvuIaAFrq4Cg --allow-record recvuIaAFrq4Cg \
+ *     --file ~/.dsh/argent/wenyao-output/xxx.xlsx --status 填写中 --dry-run
+ *   去掉 `--dry-run` 并加 `--yes` 才真正落库。
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, basename, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+// 2026-09-20（迭代1-步骤4）：**不再硬编码**表/身份 —— 那是"换客户=改代码"的根。
+// 缺省目标改为**惰性解析**（首次使用时经 flow_config 走部署 env：envFile + baseEnv/tableEnv/
+// identityEnv）；解析失败 ⇒ 抛错拒绝执行（绝不"猜一张表写进去"）。
+// 为什么惰性而不是 import 时解析：纯函数（守卫）单测不该因为缺 env 就跑不起来。
+
+/**
+ * 回写目标（**共用守卫**，2026-09-17 起按用户口径「鑫中航复用文鳐这套守卫」）。
+ *
+ * 默认 = 上海文鳐 lip 表；`--flow <id>` 时用 `flow_config.py`（唯一配置读取点）解析出
+ * 该流程声明的 base/table/identity ⇒ 同一份守卫服务多条发票流程，**不复制第二套逻辑**。
+ * 解析失败（缺部署 env / 表 id 拿不到）⇒ 直接拒绝执行，绝不"猜一张表写进去"。
+ */
+const DEFAULT_FLOW = 'wenyao-invoice'
+let _default = null
+/** 缺省回写目标（惰性解析一次并缓存）。 */
+export function defaultTarget() {
+  if (!_default) _default = resolveTarget(DEFAULT_FLOW)
+  return { ..._default }
+}
+let TARGET = null
+export function getTarget() { return TARGET ? { ...TARGET } : defaultTarget() }
+export function setTarget(t = {}) {
+  TARGET = { ...getTarget(), ...t }   // 基线取当前目标（可能是惰性解析出的缺省）
+  return getTarget()
+}
+
+/** 按流程 id 解析回写目标（读注册表 + 部署 env；失败即抛，宁可不写）。 */
+export function resolveTarget(flowId, { repo, argv = process.argv } = {}) {
+  const root = repo || join(dirname(fileURLToPath(import.meta.url)), '..')
+  const py = (process.env.ARGENT_PY || process.env.ARGENT_PYTHON || `${process.env.DSH_HOME || `${process.env.HOME}/.dsh`}/argent/venv/bin/python3`)
+  let cfg
+  try {
+    cfg = JSON.parse(execFileSync(py, [join(root, 'scripts', 'flow_config.py'), '--flow', flowId, '--json'],
+      { encoding: 'utf8' }))
+  } catch (e) {
+    throw new Error(`流程 ${flowId} 配置不可解析（缺部署 env？）：${String(e.stderr || e.message).trim().split('\n').pop()}`)
+  }
+  const src = cfg.source || {}
+  const base = String(src.base || '')
+  const table = String(src.table || '')
+  const profile = String(src.identity || '')
+  if (!base || !table) throw new Error(`流程 ${flowId} 未解析出 base/table（${JSON.stringify(src).slice(0, 200)}）`)
+  if (!profile) throw new Error(`流程 ${flowId} 未声明 identity（回写需要知道用哪个 bot 身份）`)
+  return { flow: flowId, base, table, profile }
+}
+
+/** 只许碰这四个字段；`发票文件` 必须走附件上传通道。 */
+export const ALLOWED_FIELDS = ['发票状态', '发票文件', '大货标签', '发票错误信息']
+export const ATTACHMENT_FIELDS = ['发票文件', '大货标签']
+/**
+ * **单向释放字段**（2026-09-18）：运营的「放行勾」只允许被**取消**，永不允许由程序勾上。
+ *
+ * 背景（真实事故）：文鳐收口只写「发票状态=已完成」，**没有释放放行勾** ⇒ 该行长期处于
+ * `FULL状态=已完成 ∧ 发票就绪=true` ＝ 表上看着"还等着跑"；而且只要台账那条 `done` 一失效
+ * （身份漂移／台账轮转），开启闸门就会重新放行 ⇒ 重复开票、重复上传
+ * （2026-09-18 23:17 已真实预演过一次：同一业务行被重新认领，靠角色判 blocked 才没重复写）。
+ * 鑫中航的 runner 早就做了这件事（`{发票状态:已完成, 发票就绪:False}`），文鳐漏了。
+ *
+ * 为什么不把「发票就绪」塞进 ALLOWED_FIELDS：那是**双向可写**的普通字段边界；
+ * 勾选权必须永远归运营，所以单独约束 —— **值只允许 false**，写 true 一律拒绝。
+ */
+export const ONEWAY_FALSE_FIELDS = ['发票就绪']
+export const STATUS_OPTIONS = ['未开发票', '待勾选', '待生成', '填写中', '已上传', '标签已下载', '已完成', '失败', '跳过']
+/** 可以开始/重跑的状态。 */
+export const STATUS_STARTABLE = ['', '未开发票', '待勾选', '待生成', '失败', '跳过']
+/** 已进入流程、允许覆盖自身（重跑/重传）。 */
+export const STATUS_IN_PROGRESS = ['填写中']
+/** 终态：回写要 --force。 */
+export const STATUS_TERMINAL = ['已上传', '标签已下载', '已完成']
+export const SHIPPING_STATE = '填写中'
+
+/** select/attachment 常以数组返回；统一取首值。 */
+export function pickValue(v) {
+  if (Array.isArray(v)) return v.length === 0 ? '' : pickValue(v[0])
+  if (v === null || v === undefined) return ''
+  if (typeof v === 'object') return v.name ?? v.text ?? ''
+  return v
+}
+
+/** 飞书 checkbox 的"真值"判断：'True'/'true'/'是'/true 都算勾上；''/None/'False' 都算没勾。 */
+export function isTruthy(v) {
+  const s = pickValue(v)
+  if (s === true) return true
+  if (s === false || s === null || s === undefined) return false
+  return ['true', '1', 'yes', '是'].includes(String(s).trim().toLowerCase())
+}
+
+export function normalizeStatus(v) {
+  const s = pickValue(v)
+  return typeof s === 'string' ? s.trim() : String(s)
+}
+
+/**
+ * 字段级守卫。返回 `{ errors, warnings, clean }`；errors 非空 ⇒ 拒绝写入。
+ */
+export function guardPatch(patch, allowed = ALLOWED_FIELDS) {
+  const errors = []
+  const warnings = []
+  const clean = {}
+  if (!patch || typeof patch !== 'object') return { errors: ['empty-patch'], warnings, clean }
+  const keys = Object.keys(patch)
+  if (keys.length === 0) errors.push('empty-patch')
+  for (const k of keys) {
+    // 单向释放字段：只允许显式 false —— 「勾上」这件事永远只能由运营在表里做
+    if (ONEWAY_FALSE_FIELDS.includes(k)) {
+      if (patch[k] !== false) { errors.push(`oneway-field-only-false:${k}`); continue }
+      clean[k] = false
+      continue
+    }
+    if (!allowed.includes(k)) { errors.push(`field-not-whitelisted:${k}`); continue }
+    if (ATTACHMENT_FIELDS.includes(k)) { errors.push(`attachment-field-needs-upload:${k}`); continue }
+    const v = patch[k]
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) { errors.push(`value-not-lossless:${k}`); continue }
+    if (Array.isArray(v) && v.some((x) => x && typeof x === 'object')) { errors.push(`value-not-lossless:${k}`); continue }
+    clean[k] = v
+  }
+  return { errors, warnings, clean }
+}
+
+/** 记录级守卫：必须显式授权目标记录。 */
+export function guardRecord(recordId, allowedRecords) {
+  if (!recordId || typeof recordId !== 'string') return { ok: false, error: 'missing-record-id' }
+  if (!Array.isArray(allowedRecords) || allowedRecords.length === 0) return { ok: false, error: 'missing-allow-record' }
+  if (!allowedRecords.includes(recordId)) return { ok: false, error: `record-not-whitelisted:${recordId}` }
+  return { ok: true }
+}
+
+/** 状态机守卫：返回 `{ ok, action }`，action ∈ write|noop。 */
+export function guardStatusTransition(current, target, { force = false } = {}) {
+  const from = normalizeStatus(current)
+  const to = normalizeStatus(target)
+  if (!STATUS_OPTIONS.includes(to)) return { ok: false, error: `unknown-status:${to}` }
+  if (from === to) return { ok: true, action: 'noop', from, to }
+  if (STATUS_TERMINAL.includes(from) && !force) return { ok: false, error: `terminal-status-needs-force:${from}`, from, to }
+  return { ok: true, action: 'write', from, to }
+}
+
+/** 每个附件字段允许的文件类型（发票文件收表格；大货标签收唛头 PDF/压缩包）。 */
+export const FIELD_FILE_PATTERN = {
+  发票文件: /\.(xlsx|xls)$/i,
+  大货标签: /\.(pdf|zip)$/i,
+}
+
+/** 附件守卫：真实存在、非空、后缀符合该字段的类型（生产件的语义由调用方保证）。 */
+export function guardFile(path, pattern = FIELD_FILE_PATTERN['发票文件']) {
+  if (!path) return { ok: false, error: 'missing-file' }
+  if (!existsSync(path)) return { ok: false, error: `file-not-found:${path}` }
+  const st = statSync(path)
+  if (!st.isFile() || st.size === 0) return { ok: false, error: `file-empty:${path}` }
+  if (pattern && !pattern.test(path)) return { ok: false, error: `file-type-not-allowed:${basename(path)}` }
+  return { ok: true, size: st.size, name: basename(path) }
+}
+
+/** 审计行（纯函数，便于断言）。 */
+export function auditLine({ at, recordId, op, field, from, to, file, fileToken, bytes, ok, error }) {
+  return JSON.stringify({
+    at, record: recordId, op, field,
+    from: from ?? null, to: to ?? null,
+    file: file ?? null, fileToken: fileToken ?? null, bytes: bytes ?? null,
+    ok: !!ok, error: error ?? null,
+    who: 'argent/wenyao-invoice P1',
+  })
+}
+
+// ───────────────────────────── IO ─────────────────────────────
+
+const HOME = homedir()
+const WB_DIR = process.env.WENYAO_WB_DIR || join(resolveDataDir({ env: process.env }).dir, 'invoice-writeback')
+const BACKUP_DIR = join(WB_DIR, 'backup')
+const AUDIT = join(WB_DIR, 'audit.jsonl')
+
+/** 瞬时错误（实测 20008 在按名解析时约 20% 概率偶发）→ 有限重试。 */
+const TRANSIENT = /20008|The user does not exist|rate limit|internal error/i
+
+function larkOnce(args) {
+  const out = execFileSync('lark-cli', ['--profile', getTarget().profile, 'base', ...args, '--as', 'bot', '--format', 'json'], {
+    encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const j = JSON.parse(out)
+  if (j.ok === false) throw new Error(`lark-cli: ${j.error?.code} ${j.error?.message}`)
+  return j
+}
+
+function lark(args, { tries = 3 } = {}) {
+  let last
+  for (let i = 0; i < tries; i++) {
+    try { return larkOnce(args) } catch (e) {
+      last = e
+      if (!TRANSIENT.test(String(e.message))) throw e
+      sleep(400 * (i + 1))
+    }
+  }
+  throw last
+}
+
+function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) }
+
+/** 全部字段（id/name/type 真源，来自 field-list，不猜位置）。 */
+export function listFields() {
+  const j = lark(['+field-list', '--base-token', getTarget().base, '--table-id', getTarget().table])
+  return j.data.fields.map((f) => ({ id: f.id, name: f.name, type: f.type }))
+}
+
+/**
+ * 读取记录：**一律传 field_id**（按名解析既会 20008 偶发，也依赖名字唯一）。
+ * 返回「字段名 → 值」的映射：名字来自接口回显的 `fields`，逐名对应，避免宽投影错位。
+ */
+export function readRecord(recordId, fieldIds) {
+  const args = ['+record-get', '--base-token', getTarget().base, '--table-id', getTarget().table, '--record-id', recordId]
+  for (const f of fieldIds) args.push('--field-id', f)
+  const j = lark(args)
+  const d = j.data
+  const names = d.fields
+  const row = d.data?.[0] ?? []
+  const out = {}
+  names.forEach((n, i) => { out[n] = row[i] ?? null })
+  return out
+}
+
+function backup(recordId, fieldIds, tag) {
+  mkdirSync(BACKUP_DIR, { recursive: true })
+  const row = readRecord(recordId, fieldIds)
+  const at = new Date().toISOString().replace(/[:.]/g, '-')
+  const p = join(BACKUP_DIR, `${tag}-${recordId}-${at}.json`)
+  writeFileSync(p, JSON.stringify({ flow: getTarget().flow, base: getTarget().base, table: getTarget().table, record: recordId, at, fields: row }, null, 2))
+  return { path: p, row }
+}
+
+/**
+ * 附件上传：**必须用 field_id**。
+ * 实测：用字段名（`--field-id 发票文件`）走 `/base/v3/.../fields/<name>` 解析会返回
+ * `20008 The user does not exist`；换 field_id 立刻成功 —— 与附件下载那次的坑同源。
+ * lark-cli 安全策略：`--file` 必须是**当前目录内**的相对路径（绝对路径被拒），故切到文件所在目录传 ./basename。
+ */
+function uploadAttachment(recordId, fieldId, file) {
+  const cwd = dirname(file)
+  const rel = `./${basename(file)}`
+  let out
+  try {
+    out = execFileSync('lark-cli', ['--profile', getTarget().profile, 'base', '+record-upload-attachment',
+      '--base-token', getTarget().base, '--table-id', getTarget().table,
+      '--record-id', recordId, '--field-id', fieldId, '--file', rel, '--as', 'bot', '--format', 'json'],
+    { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] })
+  } catch (e) {
+    throw new Error(`step②upload 失败（field_id=${fieldId}）：${String(e.stderr || e.message).slice(0, 500)}`)
+  }
+  const j = JSON.parse(out)
+  if (j.ok === false) throw new Error(`step②upload 失败：${j.error?.code} ${j.error?.message}`)
+  const tokens = JSON.stringify(j).match(/file_token"\s*:\s*"([^"]+)"/g) || []
+  return { raw: j, token: tokens.length ? tokens[tokens.length - 1].split('"')[3] : null }
+}
+
+/** 移除附件格里的指定 file_token（清理重复上传用）。 */
+function removeAttachments(recordId, fieldId, tokens) {
+  if (tokens.length === 0) return null
+  const args = ['--profile', getTarget().profile, 'base', '+record-remove-attachment', '--base-token', getTarget().base,
+    '--table-id', getTarget().table, '--record-id', recordId, '--field-id', fieldId, '--as', 'bot', '--format', 'json', '--yes']
+  for (const t of tokens) args.push('--file-token', t)
+  const out = execFileSync('lark-cli', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  const j = JSON.parse(out)
+  if (j.ok === false) throw new Error(`remove-attachment 失败：${j.error?.code} ${j.error?.message}`)
+  return j
+}
+
+/** 同名列里已存在的附件（按 名 + 大小 判定同一份）——用于幂等跳过与去重。 */
+export function findExisting(attachments, name, size) {
+  if (!Array.isArray(attachments)) return []
+  return attachments.filter((a) => a && a.name === name && (size == null || Number(a.size) === Number(size)))
+}
+
+/**
+ * 附件格的写入计划（纯函数，可单测）。
+ *
+ * 为什么按**名字**而不是"名字+大小"决定要不要清：内容更新后大小会变，
+ * 若只按"同名同大小"判重，重传的新件会被当成"格内没有"，而**旧件仍在** ⇒ 一格里两份。
+ * 规则：
+ *   · `--replace`（内容已变、要覆盖）：移除格内**所有同名**件，再传新的；
+ *   · 否则：同名 + 同大小视为同一份 ⇒ 跳过上传；同名多份 ⇒ 只留第一份，其余移除。
+ */
+export function planAttachment({ cell, name, size, replace = false } = {}) {
+  const all = Array.isArray(cell) ? cell.filter((a) => a && a.name === name) : []
+  const same = all.filter((a) => Number(a.size) === Number(size))
+  if (replace) {
+    return { needUpload: true, removeTokens: all.map((a) => a.file_token).filter(Boolean), keepToken: null, sameName: all.length }
+  }
+  if (same.length === 0) {
+    return { needUpload: true, removeTokens: [], keepToken: null, sameName: all.length }
+  }
+  return {
+    needUpload: false,
+    removeTokens: all.slice(1).map((a) => a.file_token).filter(Boolean),
+    keepToken: same[0]?.file_token ?? all[0]?.file_token ?? null,
+    sameName: all.length,
+  }
+}
+
+/** 单次 batch-update 提交全部普通字段（附件字段不走这里）。 */
+function updateFields(recordId, map) {
+  const payload = JSON.stringify({ update_records: { [recordId]: map } })
+  return lark(['+record-batch-update', '--base-token', getTarget().base, '--table-id', getTarget().table, '--json', payload])
+}
+
+// ── 守卫姿态导出（供 flow_preflight 比对；2026-09-20 迭代1-步骤4）──
+// 为什么需要：注册表的 `guards.backup/audit/writeFields` 此前**没有任何执行者**（死配置），
+// 且两条发票 flow 声明相反（true/true vs false/false）而注释又写着"有备份+审计" —— 声明说谎。
+// 现在把"实际写手怎么做的"导出成机器可读，由 preflight 强制一致（不一致就 FAIL）。
+const PRINT_POSTURE = process.argv.includes('--print-posture')
+if (PRINT_POSTURE) {
+  console.log(JSON.stringify({
+    flowDefault: getTarget().flow,
+    allowedFields: ALLOWED_FIELDS,
+    attachmentFields: ATTACHMENT_FIELDS,
+    onewayFalseFields: ONEWAY_FALSE_FIELDS,
+    statusOptions: STATUS_OPTIONS,
+    backup: true,      // 写前整行备份（backup()）
+    audit: true,       // 审计 JSONL（audit()）
+    readback: true,    // 写后读回验收（轮询重试）
+  }))
+  process.exit(0)
+}
+
+// ─────────────────────────── CLI ───────────────────────────
+
+function parseArgv(argv) {
+  const o = { status: SHIPPING_STATE, 'dry-run': true, yes: false, force: false, clearError: false, replace: false, field: '发票文件', textOnly: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dry-run') { o['dry-run'] = true; continue }
+    if (a === '--yes') { o.yes = true; o['dry-run'] = false; continue }
+    if (a === '--force') { o.force = true; continue }
+    if (a === '--replace') { o.replace = true; continue }
+    if (a === '--clear-error') { o.clearError = true; continue }
+    if (a === '--text-only') { o.textOnly = true; continue }   // 纯文本更正：不涉及附件
+    if (a === '--clear-ready') { o.clearReady = true; continue }  // 释放运营放行勾（单向：只置 false）
+    if (a === '--status') { o.status = argv[++i]; o.statusGiven = true; continue }
+    if (a === '--error-message') { o.errorMessage = argv[++i]; continue }
+    if (a === '--write') { o['dry-run'] = false; continue }
+    if (a.startsWith('--')) { o[a.slice(2)] = argv[++i]; continue }
+  }
+  return o
+}
+
+function main() {
+  const o = parseArgv(process.argv.slice(2))
+  const recordId = o['record-id']
+  const allow = String(o['allow-record'] || '').split(',').map((s) => s.trim()).filter(Boolean)
+  const file = o.file
+
+  // 目标解析：缺省文鳐 lip 表；`--flow xzh-invoice` ⇒ 按注册表里该流程声明的表与身份（共用同一套守卫）。
+  if (o.flow) {
+    try {
+      setTarget(resolveTarget(String(o.flow)))
+    } catch (e) {
+      console.error(`❌ 目标解析失败：${e.message}`)
+      process.exit(2)
+    }
+  }
+  const tag = o.tag || getTarget().flow
+
+  const targetField = String(o.field || '发票文件')
+  const problems = []
+  const rGuard = guardRecord(recordId, allow)          // 记录白名单：两种模式都必填
+  if (!rGuard.ok) problems.push(rGuard.error)
+  // 纯文本更正模式（2026-09-18）：只改 `发票错误信息`（+可选 `发票状态`），**不碰附件** ——
+  // 用于更正历史遗留的过时/错误文案（如"未接入发票自动化"其实早已接入）。
+  let fGuard = { ok: true, name: '', size: 0 }
+  if (!o.textOnly) {
+    if (!ATTACHMENT_FIELDS.includes(targetField)) problems.push(`field-not-an-attachment:${targetField}`)
+    fGuard = guardFile(file, FIELD_FILE_PATTERN[targetField])
+    if (!fGuard.ok) problems.push(fGuard.error)
+  } else if (!o.errorMessage && !o.clearError && !o.statusGiven && !o.clearReady) {
+    problems.push('text-only-needs-something-to-write（--error-message / --clear-error / --status / --clear-ready 至少一个）')
+  }
+
+  if (problems.length) { console.error('❌ 拒绝执行：\n  - ' + problems.join('\n  - ')); process.exit(2) }
+
+  const fieldList = listFields()
+  const ids = fieldList.map((f) => f.id)
+  const idOf = (n) => fieldList.find((f) => f.name === n)?.id
+  const before = readRecord(recordId, ids)
+  const currentStatus = normalizeStatus(before['发票状态'])
+  const wantStatus = (o.textOnly && !o.statusGiven) ? currentStatus : o.status   // text-only 未显式给状态 ⇒ 保持原值
+  const sGuard = guardStatusTransition(currentStatus, wantStatus, { force: o.force })
+  if (!sGuard.ok) { console.error(`❌ 状态守卫拒绝：${sGuard.error}（当前=${currentStatus}）`); process.exit(2) }
+
+  const patch = {}
+  const touched = []            // 审计用：**实际**要写的字段（下面每加一项就记一笔）
+  if (sGuard.action === 'write') { patch['发票状态'] = [sGuard.to]; touched.push('发票状态') }
+  // 释放放行勾（2026-09-18）：**只允许 false**（守卫 ONEWAY_FALSE_FIELDS）。已是 false ⇒ 幂等不动。
+  const readyBefore = isTruthy(before['发票就绪'])
+  if (o.clearReady && readyBefore) { patch['发票就绪'] = false; touched.push('发票就绪') }
+  if (o.clearError && pickValue(before['发票错误信息'])) { patch['发票错误信息'] = null; touched.push('发票错误信息(清空)') }
+  if (o.errorMessage !== undefined && String(o.errorMessage) !== String(pickValue(before['发票错误信息']) || '')) {
+    patch['发票错误信息'] = String(o.errorMessage); touched.push('发票错误信息')
+  }
+  // 状态同值 = noop 时 patch 为空是正常的（只剩附件幂等/去重要做），不当错误。
+  const pGuard = Object.keys(patch).length ? guardPatch(patch) : { errors: [], clean: {} }
+  if (pGuard.errors.length) { console.error('❌ 字段守卫拒绝：' + pGuard.errors.join(', ')); process.exit(2) }
+
+  // 幂等/覆盖：同名同大小 ⇒ 跳过上传；`--replace` ⇒ 传新件并清掉全部同名旧件（内容更新用）。
+  const plan = o.textOnly
+    ? { sameName: 0, needUpload: false, keepToken: null, removeTokens: [] }
+    : planAttachment({ cell: before[targetField], name: fGuard.name, size: fGuard.size, replace: !!o.replace })
+
+  console.log('── 计划 ──')
+  console.log(`  流程/表   : ${getTarget().flow}｜base ${getTarget().base}｜table ${getTarget().table}｜身份 ${getTarget().profile}`)
+  console.log(`  记录      : ${recordId}（字段 id: ${targetField}=${idOf(targetField)} 发票状态=${idOf('发票状态')}）`)
+  console.log(`  货件号    : ${pickValue(before['货件号']) || '(空)'} | 货代: ${pickValue(before['货代公司'])}`)
+  console.log(`  发票状态  : ${currentStatus || '(空)'} → ${wantStatus}${sGuard.action === 'noop' ? '（同值，noop：text-only 未显式给状态时保持不动）' : ''}`)
+  if (o.clearReady) {
+    console.log(`  放行勾    : 发票就绪 ${readyBefore ? 'True → False（本次释放）' : 'False（已是取消态，幂等跳过）'}`)
+  }
+  if (o.textOnly) {
+    console.log(`  纯文本更正: 发票错误信息 → ${JSON.stringify(o.errorMessage !== undefined ? o.errorMessage : (pickValue(before['发票错误信息']) || ''))}`)
+    console.log(`              （当前值：${JSON.stringify(pickValue(before['发票错误信息']) || '')}）`)
+  } else {
+    console.log(`  ${targetField}  : 格内已有同名件 ${plan.sameName} 份 → ${plan.needUpload ? `${o.replace ? '覆盖为' : '追加'} ${fGuard.name}（${fGuard.size} bytes）` : '跳过上传（幂等，同一份）'}`)
+  }
+  if (plan.removeTokens.length) console.log(`  清理      : 将移除同名旧件 ${plan.removeTokens.length} 份（${plan.removeTokens.join(', ')}）`)
+  console.log(`  字段白名单: ${Object.keys(patch).join(', ') || '(仅附件)'}`)
+  if (o['dry-run']) { console.log('\n[dry-run] 未写入任何数据。加 --yes 才落库。'); return }
+
+  const bk = backup(recordId, ids, tag)
+  console.log(`\n① 已备份整行 → ${basename(bk.path)}`)
+
+  let fileToken = plan.keepToken
+  try {
+    if (plan.needUpload) {
+      const up = uploadAttachment(recordId, idOf(targetField), file)
+      fileToken = up.token || findTokenInRecord(recordId, idOf(targetField), fGuard.name)
+      console.log(`② 已上传附件（file_token=${fileToken || '?'}）`)
+    } else {
+      console.log(`② 跳过上传（格内已是同一份，file_token=${fileToken}）`)
+    }
+    if (plan.removeTokens.length) {
+      // 先传后清：万一清理失败至少新件已在，不会丢内容。
+      removeAttachments(recordId, idOf(targetField), plan.removeTokens)
+      console.log(`②b 已移除同名旧件 ${plan.removeTokens.length} 份`)
+    }
+    if (Object.keys(patch).length) {
+      updateFields(recordId, patch)
+      console.log(`③ 已更新字段 → ${Object.keys(patch).map((k) => `${k}=${JSON.stringify(patch[k])}`).join(', ')}`)
+    } else {
+      console.log('③ 普通字段无变更，跳过更新')
+    }
+  } catch (e) {
+    audit({ recordId, op: 'upload+status', field: [...(o.textOnly ? [] : [targetField]), ...touched].join(',') || '(无字段变更)', from: currentStatus, to: sGuard.to,
+      file: fGuard.name, fileToken, bytes: fGuard.size, ok: false, error: String(e.message).slice(0, 300) })
+    console.error(`\n❌ ${e.message}`)
+    console.error('   （写前备份已留存，可用备份 JSON 逐字段回滚）')
+    process.exit(1)
+  }
+
+  // ⚠️ 写后读回必须**轮询重试**：飞书 Base 更新走异步链路，写完立刻读可能还是旧值
+  //（2026-09-11 实测：收口那次明明写成功，读回却报 `填写中 ❌` 假失败）。
+  let after = {}, afterStatus = '', afterFiles = null, kept = []
+  for (let i = 0; i < 8; i++) {
+    after = readRecord(recordId, [idOf('发票状态'), idOf(targetField), idOf('发票错误信息'), idOf('发票就绪')])
+    afterStatus = normalizeStatus(after['发票状态'])
+    afterFiles = after[targetField]
+    kept = findExisting(afterFiles, fGuard.name, fGuard.size)
+    if (afterStatus === sGuard.to && kept.length === 1 && !(o.clearReady && isTruthy(after['发票就绪']))) break
+    if (i < 7) sleep(1500)
+  }
+  const okStatus = afterStatus === sGuard.to
+  const okReady = !o.clearReady || !isTruthy(after['发票就绪'])
+  const okFile = o.textOnly
+    ? (pickValue(after['发票错误信息']) || '') === (o.errorMessage !== undefined ? String(o.errorMessage) : (pickValue(after['发票错误信息']) || ''))
+    : (kept.length === 1 && (!Array.isArray(afterFiles) || afterFiles.length === 1))
+  console.log(o.textOnly
+    ? `\n④ 读回验收：状态=${afterStatus} ${okStatus ? '✅' : '❌'} | 错误信息=${JSON.stringify(pickValue(after['发票错误信息']) || '')} ${okFile ? '✅' : '❌'}`
+    : `\n④ 读回验收：状态=${afterStatus} ${okStatus ? '✅' : '❌'} | 目标附件恰 1 份=${okFile ? '✅' : '❌'}（格内共 ${Array.isArray(afterFiles) ? afterFiles.length : 0} 份）`)
+  if (o.clearReady) console.log(`   放行勾    : 发票就绪=${isTruthy(after['发票就绪']) ? 'True ❌（未释放）' : 'False ✅'}`)
+
+  audit({ recordId, op: 'upload+status', field: [...(o.textOnly ? [] : [targetField]), ...touched].join(',') || '(无字段变更)', from: currentStatus, to: sGuard.to,
+    file: fGuard.name, fileToken, bytes: fGuard.size,
+    readyReleased: o.clearReady ? (readyBefore ? 'true→false' : 'already-false') : undefined,
+    ok: okStatus && okFile && okReady, error: null })
+  console.log(`⑤ 审计已追加 → ${AUDIT}`)
+  if (!okStatus || !okFile || !okReady) process.exit(1)
+}
+
+function audit(rec) {
+  mkdirSync(WB_DIR, { recursive: true })
+  appendFileSync(AUDIT, auditLine({ at: new Date().toISOString(), ...rec }) + '\n')
+}
+
+function findTokenInRecord(recordId, fieldId, name, tries = 4) {
+  // 表格写入是**异步生效**的：传完立刻读可能还看不到（实测审计里 file_token 因此记成 None）。
+  // 这里重试几次；并且同名可能有多份，取**最后一个**（新传的通常在后面）。
+  for (let i = 0; i < tries; i++) {
+    try {
+      const row = readRecord(recordId, [fieldId])
+      const v = row[Object.keys(row)[0]]
+      if (Array.isArray(v)) {
+        const hits = v.filter((x) => x && x.name === name)
+        if (hits.length) return hits[hits.length - 1].file_token
+      }
+    } catch { /* 读回失败不影响主流程，继续重试 */ }
+    if (i < tries - 1) sleep(500)
+  }
+  return null
+}
+
+export { backup, readRecord as _readRecord, findTokenInRecord }
+
+const isMain = isDirectRun(import.meta.url)
+if (isMain) main()