@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/invoice_carrier_notice.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""invoice_carrier_notice —— 给"勾了就绪、但货代未接入"的行写「发票错误信息」（2026-09-21 用户要求）。
+
+**为什么需要**：lip 表是多货代共用表（允墨/商达/鑫隆/美加运通/冲港/三瀛/鸿泰信…），而自动开票目前只接入
+上海文鳐 与 鑫中航-美墨 两家。运营勾了「发票就绪」的行如果属于未接入的货代，**不会被任何流程拾取** ——
+这是正确行为（我们不该去动没接入的货代），但运营在表上看不出来：她以为"勾了就等着"。
+用户口径（逐字）：「能否将这个原因写入发票错误信息中让运营知道呢？」
+
+**写法（三条纪律，与发票回写器同规格）**：
+  ① 只写一个字段 `发票错误信息`（白名单）；不改状态、不勾/不摘「发票就绪」、不碰附件；
+  ② 只写"**我方确实无法承接**"的行：`发票就绪=true ∧ FULL状态=已完成`（发票流程的开启前提）
+     ∧ `货代公司 ∉ 已接入货代`（后者从**注册表**的 `flows.*.routing.match` 派生，不写死）；
+  ③ 幂等 + 不覆盖人工：已是我们自己的标记 ⇒ 跳过；字段里是**别人的话** ⇒ 默认不覆盖（`--force` 才覆盖）。
+  另有：写前整行备份、写后读回验收、审计 JSONL、默认 dry-run（`--yes` 才真写）。
+
+用法：
+  python3 scripts/invoice_carrier_notice.py                 # 预览（不写）
+  python3 scripts/invoice_carrier_notice.py --yes           # 真写（逐行备份 + 读回 + 审计）
+  python3 scripts/invoice_carrier_notice.py --json          # 机器可读（供工作台/巡检）
+  python3 scripts/invoice_carrier_notice.py --record recXXX [--yes]   # 只处理一行（排障）
+退出码：0 正常；1 有读取/写入失败；2 参数错误
+"""
+from __future__ import annotations
+import argparse, json, os, pathlib, subprocess, sys, time
+
+HERE = pathlib.Path(__file__).resolve().parent
+REGISTRY = HERE / "flow-requirements.json"
+
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        return json.loads((pathlib.Path(path) if path else REGISTRY).read_text(encoding="utf-8"))
+
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+DATA = pathlib.Path(resolve_data_dir()['dir'])
+AUDIT = DATA / "invoice-carrier-notice"
+MARK = "[未接入货代]"          # 我方标记：幂等判据 + 将来接入后可按此清理
+
+# 字段：**运行时按名解析 id**（`scripts/lip_table.py` 是唯一入口 —— 写死物理 id 会被
+# `no-hardcoded-customer-ids` 门禁拦下，因为字段 id 是客户表的事实、可能变）。命中不了会降级按名，
+# 那时的读回验收会暴露问题。写入一律用解析出来的 id（按名解析偶发 20008，见 AGENTS.md）。
+FIELDS_NAMES = ("货件号", "货代公司", "发票就绪", "FULL状态", "发票状态", "发票错误信息")
+
+
+def resolve_fields(env: dict) -> dict:
+    """字段名 → id（走 lip_table；解析失败降级为按名，不静默改语义）。"""
+    try:
+        sys.path.insert(0, str(HERE))
+        import lip_table
+        t = {"base": env.get("base", ""), "table": env.get("table", ""), "profile": env.get("profile", "")}
+        return {n: lip_table.field_id(n, t) for n in FIELDS_NAMES}
+    except Exception:                                            # noqa: BLE001
+        return {n: n for n in FIELDS_NAMES}
+
+
+def load_registry() -> dict:
+    return _registry_doc()
+
+
+def connected_carriers(doc: dict) -> dict:
+    """已接入的货代 → 负责流程（从注册表 routing.match 派生；适配器契约是第二处，这里够用）。"""
+    out = {}
+    for fid, f in (doc.get("flows") or {}).items():
+        cap = str((f or {}).get("capability") or "")
+        if cap != "invoice":
+            continue
+        match = str(((f or {}).get("routing") or {}).get("match") or "").strip()
+        if match:
+            out[match] = fid
+    return out
+
+
+def base_env(doc: dict) -> dict:
+    """lip 表坐标与身份：与发票流程同源（source.baseEnv/tableEnv/identityEnv → 部署 env 文件）。"""
+    for fid, f in (doc.get("flows") or {}).items():
+        src = (f or {}).get("source") or {}
+        if str((f or {}).get("capability") or "") != "invoice" or not src.get("baseEnv"):
+            continue
+        env_file = DATA / str(src.get("envFile") or "fulfillment.env")
+        vals = {}
+        try:
+            for line in env_file.read_text(encoding="utf-8").splitlines():
+                t = line.strip()
+                if t.startswith("#") or "=" not in t:
+                    continue
+                k, v = t.split("=", 1)
+                vals[k.strip()] = v.strip().strip('"').strip("'")
+        except Exception:                                        # noqa: BLE001
+            pass
+        return {"base": os.environ.get(str(src["baseEnv"])) or vals.get(str(src["baseEnv"]), ""),
+                "table": os.environ.get(str(src["tableEnv"])) or vals.get(str(src["tableEnv"]), ""),
+                "profile": os.environ.get(str(src.get("identityEnv") or "")) or vals.get(str(src.get("identityEnv") or ""), "")
+                or str(src.get("identity") or "ml-fulfillment")}
+    return {}
+
+
+def lark(args: list, profile: str, tries: int = 3) -> tuple:
+    """调 lark-cli —— 带重试：实测 `accounts.feishu.cn/oauth/v3/token` 偶发
+    `context deadline exceeded`（令牌刷新超时，与具体操作无关），一次失败不代表操作有问题。
+    只对**这类瞬时失败**重试（退避 2s/4s），业务错误（如字段不存在）照样立刻返回。"""
+    last = (1, "", "")
+    for i in range(max(1, tries)):
+        p = subprocess.run(["lark-cli", "--profile", profile, *args], capture_output=True, text=True)
+        out = (p.stdout or "") + (p.stderr or "")
+        transient = p.returncode != 0 and any(k in out for k in (
+            "deadline exceeded", "context deadline", "rate limit", "too many requests",
+            '"type": "network"', '"subtype": "transport"', "ECONNRESET", "ETIMEDOUT",
+            "socket hang up", "connection reset", "temporarily unavailable"))
+        if not transient:
+            return p.returncode, p.stdout, p.stderr
+        last = (p.returncode, p.stdout, p.stderr)
+        time.sleep(2 * (i + 1))
+    return last
+
+
+def first(v):
+    if isinstance(v, list):
+        return " ".join(str(x.get("text") if isinstance(x, dict) else x) for x in v)
+    return v
+
+
+def list_rows(env: dict, limit: int = 600) -> list:
+    """窄投影读表（≤6 列；宽投影在 lip 表上会错位 —— AGENTS.md 实测）。"""
+    tmpdir = pathlib.Path("/tmp/invoice-carrier-notice")
+    tmpdir.mkdir(parents=True, exist_ok=True)
+    out = tmpdir / "rows.ndjson"
+    cmd = ["base", "+record-list", "--base-token", env["base"], "--table-id", env["table"],
+           "--as", "bot", "--format", "ndjson", "--output", "./rows.ndjson", "--overwrite",
+           "--limit", str(limit)]
+    for fid in resolve_fields(env).values():
+        cmd += ["--field-id", fid]
+    p = subprocess.run(["lark-cli", "--profile", env["profile"], *cmd], capture_output=True, text=True, cwd=str(tmpdir))
+    if p.returncode != 0:
+        raise RuntimeError(f"读表失败（exit {p.returncode}）：{(p.stderr or p.stdout).strip()[:200]}")
+    rows = []
+    for line in out.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            try:
+                rows.append(json.loads(line))
+            except Exception:                                    # noqa: BLE001
+                continue
+    return rows
+
+
+def row_field(row: dict, name: str):
+    return first((row.get("fields") or row).get(name))
+
+
+def notice_text(carrier: str, connected: list) -> str:
+    return (f"{MARK}自动化未接入该货代「{carrier}」：当前自动开票只支持 {'、'.join(connected)}"
+            f" ⇒ 本行不会被自动拾取，请人工处理或联系问述科技接入")
+
+
+def plan(rows: list, doc: dict) -> list:
+    """纯函数：给出该写哪些行、写什么（便于离线回归）。"""
+    conn = connected_carriers(doc)
+    out = []
+    for r in rows:
+        carrier = str(row_field(r, "货代公司") or "").strip()
+        if not carrier or carrier in conn:
+            continue
+        if str(row_field(r, "发票就绪")).strip().lower() != "true":
+            continue
+        if str(row_field(r, "FULL状态") or "").strip() != "已完成":
+            continue                      # 发票流程的开启前提没满足 ⇒ 还没到"该被拾取"的时候
+        cur = str(row_field(r, "发票错误信息") or "").strip()
+        text = notice_text(carrier, sorted(conn))
+        if cur == text:
+            action = "skip"               # 幂等：已提示过同样的话
+        elif cur.startswith(MARK):
+            action = "update"             # 我们自己的旧提示（例如已接入货代列表变了）
+        elif cur:
+            action = "occupied"           # 有人写过别的话 ⇒ 默认不覆盖
+        else:
+            action = "write"
+        out.append({"recordId": r.get("record_id"), "shipment": str(row_field(r, "货件号") or ""),
+                    "carrier": carrier, "current": cur, "text": text, "action": action})
+    return out
+
+
+def write_note(env: dict, item: dict, doc: dict) -> str:
+    AUDIT.mkdir(parents=True, exist_ok=True)
+    ts = time.strftime("%Y%m%d-%H%M%S")
+    # ① 写前备份整行
+    rc, so, se = lark(["api", "GET",
+                       f"/open-apis/bitable/v1/apps/{env['base']}/tables/{env['table']}/records/{item['recordId']}",
+                       "--as", "bot"], env["profile"])
+    if rc == 0:
+        (AUDIT / f"{item['recordId']}-{ts}.json").write_text(so, encoding="utf-8")
+    # ② 写入（单字段、按 field_id）
+    err_field = resolve_fields(env)["发票错误信息"]
+    body = json.dumps({"update_records": {item["recordId"]: {err_field: item["text"]}}}, ensure_ascii=False)
+    rc, so, se = lark(["base", "+record-batch-update", "--base-token", env["base"], "--table-id", env["table"],
+                       "--as", "bot", "--json", body], env["profile"])
+    ok = rc == 0 and '"record_id_list"' in (so or "")
+    err_tail = (se or so or "").strip().replace("\n", " ")[:200]
+    # ③ 读回验收（Base 最终一致：稍等再读）
+    time.sleep(3)
+    rc2, so2, _ = lark(["api", "GET",
+                        f"/open-apis/bitable/v1/apps/{env['base']}/tables/{env['table']}/records/{item['recordId']}",
+                        "--as", "bot"], env["profile"])
+    got = ""
+    if rc2 == 0:
+        try:
+            got = str(first(((json.loads(so2).get("data") or {}).get("record") or {}).get("fields", {}).get("发票错误信息")) or "")
+        except Exception:                                        # noqa: BLE001
+            got = ""
+    verified = got.strip() == item["text"]
+    with (AUDIT / "audit.jsonl").open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps({"ts": ts, "recordId": item["recordId"], "shipment": item["shipment"],
+                             "carrier": item["carrier"], "action": item["action"], "text": item["text"],
+                             "writeOk": ok, "readBackOk": verified, "err": "" if ok else err_tail,
+                             "by": "invoice_carrier_notice"},
+                            ensure_ascii=False) + "\n")
+    return "verified" if verified else ("written-unverified" if ok else "failed")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="给未接入货代的「已就绪」发票行写提示（默认 dry-run）")
+    ap.add_argument("--yes", action="store_true", help="真写（默认只预览）")
+    ap.add_argument("--force", action="store_true", help="连人工写过的行也覆盖（默认跳过）")
+    ap.add_argument("--record", help="只处理指定 record_id（排障）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    doc = load_registry()
+    env = base_env(doc)
+    if not env.get("base") or not env.get("table"):
+        print("❌ 缺 lip 表坐标（FULL_BASE_TOKEN/FULL_TABLE_ID 未解析）——检查 fulfillment.env", file=sys.stderr)
+        return 1
+    try:
+        rows = list_rows(env)
+    except Exception as exc:                                     # noqa: BLE001
+        print(f"❌ {exc}", file=sys.stderr)
+        return 1
+    items = plan(rows, doc)
+    if a.record:
+        items = [x for x in items if x["recordId"] == a.record]
+    todo = [x for x in items if x["action"] in ("write", "update")]
+    occ = [x for x in items if x["action"] == "occupied"]
+    skipped = [x for x in items if x["action"] == "skip"]
+
+    if not a.yes:
+        if a.json:
+            print(json.dumps({"connected": connected_carriers(doc), "todo": todo, "occupied": occ,
+                              "alreadyNoticed": len(skipped), "dryRun": True}, ensure_ascii=False, indent=2))
+        else:
+            print(f"  已接入货代：{'、'.join(sorted(connected_carriers(doc)))}")
+            print(f"  待写 {len(todo)} 行｜已提示过（跳过）{len(skipped)}｜人工写过（不覆盖）{len(occ)}")
+            for x in todo:
+                print(f"    + {x['recordId']} 货件号={x['shipment']} 货代={x['carrier']} ⇒ 「{x['text']}」")
+            for x in occ:
+                print(f"    ! {x['recordId']} 货代={x['carrier']} 已有他人文字，跳过：{x['current'][:40]}")
+            print("  （这是预览；加 --yes 才真写）")
+        return 0
+
+    results = []
+    for x in items:
+        if x["action"] == "skip":
+            continue
+        if x["action"] == "occupied" and not a.force:
+            continue
+        results.append({**x, "result": write_note(env, x, doc)})
+    if a.json:
+        print(json.dumps({"results": results}, ensure_ascii=False, indent=2))
+    else:
+        for r in results:
+            icon = {"verified": "✅", "written-unverified": "⚠️", "failed": "❌"}[r["result"]]
+            print(f"  {icon} {r['recordId']} 货件号={r['shipment']} 货代={r['carrier']} → {r['result']}")
+        print(f"  共处理 {len(results)} 行（审计：{AUDIT}/audit.jsonl）")
+    return 0 if all(r["result"] == "verified" for r in results) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/invoice_fail_closeout.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""invoice_fail_closeout —— 发票流程的**失败收口 / 成功收口**：把"为什么失败 + 怎么续跑"写进表。
+
+背景（2026-10-09 客户机生产实测，缺陷 B）：`recvvgPQgoUOwx` 跑失败后，表里「发票就绪」被取消，
+而「发票错误信息」**是空的**（真实原因只在台账里）⇒ 运营看到"勾没了 + 没有任何说明"，
+以为脚本坏了，也不知道怎么处理。用户口径（逐字要求）：**失败原因 + 续跑方式必须写进表**。
+
+三条纪律（本脚本就是它们的唯一执行者）：
+  ① **文案唯一来源** = `flow_failure.ops_message()`（`结论：<业务类|系统类|我方缺陷类>｜<原因>｜动作：<可照做>`）。
+     本脚本把**同一串**分别写进 ① 表字段（`guards.errorField`，发票流程 =「发票错误信息」）
+     与 ② 台账（`failed.error` = 规范原因原文；`failed.detail` = 该串）⇒ **两处不可能各写一套**。
+  ② **绝不空写**：`--error` 与台账都取不到原因时**响亮拒绝**（exit 2）——"表里空白"正是本次要消灭的形态。
+  ③ **绝不把裸异常栈给运营**：代码级异常（`AttributeError` / `object has no attribute` / traceback…）
+     归**我方缺陷类**，表里只写"流程脚本内部错误（明细在日志/台账）"+ 可照做的动作（`ops_reason`）。
+
+写表守卫**复用**该流程**声明**的写手（`guards.writer` —— 白名单 / 记录白名单 / 写前整行备份 /
+写后读回 / 审计 JSONL / 终态需 --force / 默认 dry-run）—— ⛔ 本脚本**不自己写表**，只做编排与文案；
+未声明 `guards.writer` 的流程**拒绝执行**（不许猜一个写手去写生产表）。
+
+用法：
+  # 失败收口（默认 dry-run；两件真动作：写表 + 记台账）
+  python3 scripts/invoice_fail_closeout.py --flow <发票流程> --case <flow>__<record_id> \
+      --error "缺 产品海关编码、产品图片" --missing 产品海关编码,产品图片 --clear-ready --yes
+  # 成功收口（清空过时错误信息，避免陈旧文案误导）
+  python3 scripts/invoice_fail_closeout.py --flow <发票流程> --case <flow>__<record_id> --outcome success --yes
+  # 离线/夹具：--error 直接给原因；--fields-from-json 给行字段（缺口自动算）
+退出码：0 成功；2 用法/前置错误；3 写表失败；4 读回不一致；5 台账写入失败
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+import flow_config                                   # noqa: E402  唯一配置读取点
+import flow_failure as F                             # noqa: E402  分类 + **文案唯一来源**
+from argent_datadir import resolve_data_dir          # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+LEDGER = HERE / 'flow_ledger.py'
+AUDIT = pathlib.Path(resolve_data_dir()['dir']) / 'invoice-closeout-audit.jsonl'
+EVENTS = ('failed', 'blocked')
+
+
+def writer_of(flow: str) -> str:
+    """该流程声明的**写手**（`guards.writer`，仓库内相对路径）—— 未声明则返回空串（调用方拒绝执行）。
+
+    为什么由注册表声明而不是写死在脚本里：① 写手是**能力专属**的（换货代/换表可能换写手）；
+    ② 引擎脚本不得出现业务词（`vertical-lint` 的 engine-words 判据）——路径写在流程声明里，
+    这里只做「读声明 + 存在性校验」。
+    """
+    g = (flow_config.load_config(flow, strict=False).get('guards') or {})
+    rel = str(g.get('writer') or '')
+    if not rel:
+        return ''
+    p = (HERE.parent / rel) if not rel.startswith('/') else pathlib.Path(rel)
+    return str(p) if p.exists() else ''
+
+
+def error_field(flow: str) -> str:
+    """该流程声明的**失败原因列**（`guards.errorField`，退化到 `guards.writeFields` 里的同名项）。
+
+    未声明的流程**拒绝执行**：⛔ 不许把发票那一列写到别的流程的表上（FULL 的失败原因在
+    `FULL备注`，走 `orchestrator._fail_note`，不归本脚本管）。
+    """
+    g = (flow_config.load_config(flow, strict=False).get('guards') or {})
+    fld = str(g.get('errorField') or '')
+    if not fld and '发票错误信息' in [str(x) for x in (g.get('writeFields') or [])]:
+        fld = '发票错误信息'
+    return fld
+
+
+def human_gaps(flow: str, fields: dict) -> list:
+    """需要**运营**补的缺口字段（复用 `flow_return_to_ops.human_gaps` 的判据，不写第二套）。"""
+    try:
+        import flow_return_to_ops as R2O                          # noqa: PLC0415
+        return R2O.human_gaps(flow, fields)
+    except Exception:                                             # noqa: BLE001
+        return []
+
+
+def read_case_fields(flow: str, record: str) -> dict:
+    """读该行字段（**只读**，用于自动算缺口）；读不到返回 {}（调用方降级成通用动作，绝不静默）。
+
+    ⚠️ 必须连 `SystemExit` 一起吞：`flow_return_to_ops.read_row()` 读表失败时是 `raise SystemExit`
+    （`BaseException` 子类，`except Exception` **接不住**）⇒ 生产里"身份失效"会变成整条收口**崩掉**，
+    而正确行为是降级成通用动作、**照常把原因写进表**（写不写表由写手自己的守卫决定）。
+    子进程/库的 stderr 也一并吞掉（那是给排障的，不是给运营的）——但降级**会打印可见说明**。
+    """
+    try:
+        import contextlib
+        import io
+        import flow_return_to_ops as R2O                          # noqa: PLC0415
+        cfg = flow_config.load_config(flow, strict=False)
+        src = cfg.get('source') or {}
+        buf = io.StringIO()
+        with contextlib.redirect_stderr(buf):
+            row = R2O.read_row(str(src.get('identity') or ''), str(src.get('base') or ''),
+                               str(src.get('table') or ''), record)
+        return row or {}
+    except (Exception, SystemExit):                               # noqa: BLE001
+        return {}
+
+
+def canonical_from_ledger(flow: str, case_id: str, ledger: pathlib.Path) -> tuple[str, str]:
+    """台账里的**规范失败原因**（`flow_failure.reasons`）→ (原因, 来源说明)。取不到返回 ('','')。"""
+    try:
+        r = F.reasons(ledger, case_id, flow)
+    except Exception:                                             # noqa: BLE001
+        return '', ''
+    if r.get('ok') and str(r.get('reason') or '').strip():
+        return str(r['reason']).strip(), f"台账 failed（{r.get('source')}）"
+    return '', ''
+
+
+def writeback(args, record: str, *, error_message: str | None, clear_error: bool,
+              clear_ready: bool, status: str | None) -> int:
+    """调共用写手（真跑与否由 `--yes` 决定）；返回退出码。"""
+    wb = str(args.writeback or args._writer)
+    if args.writeback:
+        # 只在**夹具/排障**时走这里；真跑永远用**流程声明**的写手（守卫都在它里面）
+        print(f"  ⚠️ 写手路径被覆盖（仅夹具/排障用）：{wb}")
+    cmd = ['node', wb, '--flow', args.flow, '--record-id', record,
+           '--allow-record', record, '--text-only']
+    if error_message is not None:
+        cmd += ['--error-message', error_message]
+    if clear_error:
+        cmd += ['--clear-error']
+    if clear_ready:
+        cmd += ['--clear-ready']
+    if status:
+        cmd += ['--status', status]
+    cmd += ['--yes'] if args.yes else ['--dry-run']
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    out = (p.stdout or '') + (('\n' + p.stderr) if p.stderr else '')
+    print('\n'.join('      ' + ln for ln in out.strip().splitlines()))
+    return p.returncode
+
+
+def ledger_write(case_id: str, event: str, *, error: str, detail: str, by: str,
+                 ledger: pathlib.Path | None = None) -> int:
+    """写台账（**同一串** `detail`）——`error` 放规范原因原文，供分类器/取数口使用。
+
+    ⚠️ `--ledger` **必须**透传：漏了它会写进**默认数据目录**的台账，而夹具/隔离实例期望的是
+    它自己那份（实测踩到：夹具那次写进了真实 `~/.dsh/argent/flow-ledger.jsonl`）。
+    """
+    cmd = [sys.executable, str(LEDGER), '--case-id', case_id, '--event', event, '--by', by,
+           '--detail', detail]
+    if ledger:
+        cmd += ['--ledger', str(ledger)]
+    if error:
+        cmd += ['--error', error]
+    return subprocess.run(cmd, capture_output=True, text=True).returncode
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='发票流程失败/成功收口：写表「发票错误信息」+ 台账（同源同文）')
+    ap.add_argument('--flow', required=True,
+                    help='发票流程 id（须在业务线声明 `guards.errorField` 与 `guards.writer`）')
+    ap.add_argument('--case', help='台账 case id（<flow>__<record_id>）或 ticket')
+    ap.add_argument('--record', help='record_id（与 --case 二选一）')
+    ap.add_argument('--outcome', choices=('failed', 'success'), default='failed',
+                    help='failed=写原因+动作（默认）；success=**清空**该列，避免陈旧文案误导')
+    ap.add_argument('--error', help='原始失败原因（不给则取台账里的规范原因；两处都取不到 ⇒ 拒绝执行）')
+    ap.add_argument('--missing', help='逗号分隔的运营缺口字段（不给则自动算：行可读时用 human_gaps）')
+    ap.add_argument('--attempt', type=int, help='第几次失败（影响分类：retryable 超上限 ⇒ 需判断）')
+    ap.add_argument('--event', choices=EVENTS, default='failed',
+                    help='台账事件（默认 failed；角色裁定后改用 blocked）')
+    ap.add_argument('--status', help='顺带推进「发票状态」（如 失败）；不给则**不动**状态')
+    ap.add_argument('--clear-ready', action='store_true',
+                    help='同时取消勾选「发票就绪」（**运营类**缺口的既定口径；单向：只允许 false）')
+    ap.add_argument('--fields-from-json', help='离线：该行字段 JSON（夹具；跳过读表）')
+    ap.add_argument('--ledger', help='台账路径（夹具用）')
+    ap.add_argument('--writeback', help='写手路径覆盖（**仅夹具/排障**；默认 = 流程声明的 `guards.writer`）')
+    ap.add_argument('--by', default='invoice-closeout', help='台账记录者')
+    ap.add_argument('--yes', action='store_true', help='真跑（默认 dry-run：只打印计划）')
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+
+    a._writer = writer_of(a.flow)          # 流程声明的写手（--writeback 可覆盖，仅夹具/排障）
+    if not a._writer and not a.writeback:
+        print(f"❌ 流程 {a.flow} 未声明 `guards.writer`（写手路径）⇒ 拒绝执行：\n"
+              f"   本命令**不自己写表**，只编排「流程声明的写手」（守卫都在写手里）；"
+              f"⛔ 缺声明时猜一个写手写生产表是不可接受的。", file=sys.stderr)
+        return 2
+    fld = error_field(a.flow)
+    if not fld:
+        print(f"❌ 流程 {a.flow} 未声明 `guards.errorField`（失败原因列）⇒ 拒绝执行：\n"
+              f"   本命令只服务**发票流程**（运营看的列 =「发票错误信息」）；FULL 的失败原因在 `FULL备注`，"
+              f"由 orchestrator._fail_note 负责。", file=sys.stderr)
+        return 2
+    record = a.record or (a.case.split('__', 1)[1] if a.case and '__' in a.case else '')
+    if not record:
+        print('❌ 需要 --case <flow>__<record_id> 或 --record <record_id>（记录白名单，一次一条）', file=sys.stderr)
+        return 2
+    case_id = a.case if (a.case and '__' in a.case) else f'{a.flow}__{record}'
+    ledger = pathlib.Path(a.ledger) if a.ledger else pathlib.Path(resolve_data_dir()['dir']) / 'flow-ledger.jsonl'
+
+    # ── 成功收口：清空该列（避免陈旧错误误导）────────────────────────────────
+    if a.outcome == 'success':
+        rc = writeback(a, record, error_message=None, clear_error=True,
+                       clear_ready=a.clear_ready, status=a.status)
+        print(f"  {'✅' if rc == 0 else '❌'} 成功收口：清空「{fld}」"
+              f"{'（+ 取消「发票就绪」）' if a.clear_ready else ''}"
+              f"{'（dry-run，未落库）' if not a.yes else ''}")
+        if a.yes and rc == 0:
+            ledger_write(case_id, 'done', error='', detail=f'成功收口：已清空「{fld}」', by=a.by,
+                         ledger=ledger)
+        return 0 if rc == 0 else 3
+
+    # ── 失败收口：原因必须**取得到**（取不到就响亮拒绝，⛔ 绝不写空）──────────
+    raw, src = str(a.error or '').strip(), '命令行 --error'
+    if not raw:
+        raw, src = canonical_from_ledger(a.flow, case_id, ledger)
+    if not raw:
+        print(f"❌ 取不到失败原因（--error 未给，台账 {ledger} 里也没有 {case_id} 的 failed 事件）⇒ **拒绝执行**：\n"
+              f"   「{fld}」写一条空/占位说明比不写更糟（运营会以为脚本坏了）——请把真实原因用 --error 传入。",
+              file=sys.stderr)
+        return 2
+
+    # 缺口：显式 --missing > 行字段（离线 JSON 或只读读表）> 通用动作（可见降级）
+    miss = [x.strip() for x in str(a.missing or '').split(',') if x.strip()]
+    miss_src = '命令行 --missing' if miss else ''
+    if not miss:
+        row = {}
+        if a.fields_from_json:
+            row = json.loads(pathlib.Path(a.fields_from_json).read_text(encoding='utf-8'))
+            miss_src = '--fields-from-json 自动算'
+        else:
+            row = read_case_fields(a.flow, record)
+            miss_src = '读表自动算' if row else ''
+            if not row:
+                # **可见**降级（不是静默）：动作退成通用版，原因照写 —— 缺字段名不影响"必写原因"
+                print('  ℹ️ 读不到该行字段（身份/网络/记录不存在）⇒ 缺口名不写进动作，'
+                      '改用通用动作；原因与结论照写（可见降级，非静默）')
+        if row:
+            miss = human_gaps(a.flow, row)
+
+    msg = F.ops_message(a.flow, raw, missing=miss,
+                        kind=F.classify(raw, a.attempt).get('kind'))
+    rc_hint = F.release_config(a.flow)
+    plan = {'flow': a.flow, 'caseId': case_id, 'record': record, 'field': fld,
+            'outcome': 'failed', 'event': a.event, 'reasonFrom': src,
+            'missing': miss, 'missingFrom': miss_src or '(未给 ⇒ 用通用动作)',
+            'category': F.ops_category(raw), 'message': msg, 'len': len(msg),
+            'clearReady': bool(a.clear_ready), 'status': a.status,
+            'release': {'enabled': rc_hint['enabled'], 'field': rc_hint['field'],
+                        'maxPerCase': rc_hint['maxPerCase'], 'cooldownMin': rc_hint['cooldownMin']},
+            'tableWrite': bool(a.yes), 'ledgerWrite': bool(a.yes), 'dryRun': not a.yes}
+
+    print('── 现场 ──')
+    print(f"  流程/列   : {a.flow}｜{fld}")
+    print(f"  记录      : {record}（case {case_id}）")
+    print(f"  原因来源  : {src}")
+    print(f"  结论类别  : {plan['category']}")
+    print(f"  运营缺口  : {'、'.join(miss) if miss else '（未取到 / 无需）——来源：' + (miss_src or '未给')}")
+    print('── 计划（表 + 台账**同一串**）──')
+    print(f"  ① 表 {fld} → {msg}")
+    print(f"  ② 台账 {a.event}: error={F.canonical_reason(raw)[:120]!r}｜detail={msg[:80]!r}…")
+    if a.clear_ready:
+        print("  ③ 取消勾选「发票就绪」（单向：只允许 false；⚙️ 仅在**运营类**缺口时该口径成立）")
+    if a.event == 'failed' and rc_hint['enabled'] and a.clear_ready:
+        print(f"      ↳ 运营补齐后重勾「{rc_hint['field']}」⇒ 下一轮自动重跑"
+              f"（上限 {rc_hint['maxPerCase']} 次 / 冷却 {rc_hint['cooldownMin']} 分；Rule R）")
+    if len(msg) > F.OPS_REASON_LIMIT:
+        print(f"  ⚠️ 文案 {len(msg)} 字 > 台账 detail 上限 {F.OPS_REASON_LIMIT} ⇒ 会被截断（同源同文不成立）",
+              file=sys.stderr)
+        return 2
+    if a.json:
+        print(json.dumps(plan, ensure_ascii=False, indent=2))
+    if not a.yes:
+        print('\n[dry-run] 未写表、未记台账。加 --yes 才落库。')
+        return 0
+
+    rc = writeback(a, record, error_message=msg, clear_error=False,
+                   clear_ready=a.clear_ready, status=a.status)
+    if rc != 0:
+        print(f"❌ 写表失败（写手退出码 {rc}）——台账**不写**（宁可留证据缺口，也不留「表已写」的假象）",
+              file=sys.stderr)
+        return 3
+    if ledger_write(case_id, a.event, error=F.canonical_reason(raw), detail=msg, by=a.by,
+                    ledger=ledger) != 0:
+        print('❌ 台账写入失败（表已写成功；请重跑本命令，写表是幂等的）', file=sys.stderr)
+        return 5
+    AUDIT.parent.mkdir(parents=True, exist_ok=True)
+    with AUDIT.open('a', encoding='utf-8') as fh:
+        fh.write(json.dumps({**plan, 'dryRun': False, 'ok': True}, ensure_ascii=False) + '\n')
+    print(f"  ✅ 收口完成：表「{fld}」与台账 {a.event}.detail **同一串**｜审计 {AUDIT.name}")
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())