@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_registry.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""流程注册表加载器（**引擎级 base + 每条业务线一份**）—— 唯一真源。
+
+Argent 0.2 平台化第一步（P1，2026-09-29）
+========================================
+此前注册表是**单个全局文件** `scripts/flow-requirements.json`：所有业务线的流程
+声明挤在一起，于是"两条业务线同机"必然撞名（flow id / 角色 / env / 暂停开关 /
+技能名），独立迭代是假解耦。现在拆成：
+
+    scripts/flow-requirements.json     引擎级 base（引擎契约、错误词表、lease、billing 规则）
+    verticals/<id>/flows.json          该业务线的流程/能力/计费单位/错误类
+    verticals/<id>/manifest.json       该业务线元数据（版本、依赖、端口、角色、技能）
+
+合并规则（冲突**一律 fail**，不静默覆盖）：
+  · flow      ：局部 id `<local>` → 规范 id `<vertical>.<local>`；重复规范 id ⇒ 冲突
+  · capability：同上（局部 id 不带点）
+  · billing.units / entitlements.roleMinPlan / failureClasses：按键合并，同名 ⇒ 冲突
+  · aliases   ：短名 → 规范 id（向后兼容用；别名撞车 ⇒ 冲突）
+
+兼容与开关：
+  · `--registry <path>` 显式指定单文件 ⇒ **legacy 单文件模式**（历史行为，测试依赖）
+  · 环境变量 `ARGENT_REGISTRY_MODE=legacy` ⇒ 只读 base（不扫 verticals）
+  · 环境变量 `ARGENT_REGISTRY_ROOT` ⇒ 覆盖仓库根（测试用隔离目录）
+
+设计约束：**零第三方依赖**（与 `scripts/lib/dsh-scope.mjs` 同规矩——升级链路与
+半坏机器上也要能跑）。Node/shell 侧不要自己实现合并，调本文件的 `--json`。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import re
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+REPO_ROOT = HERE.parent
+sys.path.insert(0, str(HERE / 'lib'))
+try:
+    from stdio_utf8 import use_utf8_stdio          # 出口编码唯一判据（stdout/stderr 钉 UTF-8）
+except ImportError:  # noqa: BLE001 —— 只拷了单个脚本的夹具/半同步的树：**不许把注册表加载器打崩**
+    def use_utf8_stdio() -> bool:
+        print('⚠️ 缺 scripts/lib/stdio_utf8.py ⇒ stdout 不做 UTF-8 重配（中文 Windows 的 GBK 管道下'
+              '非 ASCII 会崩）；补齐该文件即可（它在 pack.engine 的清单里）', file=sys.stderr)
+        return False
+BASE_NAME = 'flow-requirements.json'
+VERTICALS_DIRNAME = 'verticals'
+
+# 局部 id 允许的字符：小写字母/数字/连字符（与技能名同规矩）；**不许带点**（点留给命名空间）
+LOCAL_ID_RE = re.compile(r'^[a-z0-9]+(?:-[a-z0-9]+)*$')
+
+REQUIRED_MANIFEST = ('id', 'version', 'title', 'requires', 'ports', 'capabilities')
+
+
+class Conflict(Exception):
+    """合并冲突：调用方应 fail 而不是继续（静默覆盖是这类架构最贵的 bug）。"""
+
+
+def repo_root() -> pathlib.Path:
+    return pathlib.Path(os.environ.get('ARGENT_REGISTRY_ROOT') or REPO_ROOT)
+
+
+def base_path(root: pathlib.Path | None = None) -> pathlib.Path:
+    return (root or repo_root()) / 'scripts' / BASE_NAME
+
+
+def verticals_dir(root: pathlib.Path | None = None) -> pathlib.Path:
+    return (root or repo_root()) / VERTICALS_DIRNAME
+
+
+def mode() -> str:
+    m = (os.environ.get('ARGENT_REGISTRY_MODE') or 'merged').strip().lower()
+    return m if m in ('merged', 'legacy') else 'merged'
+
+
+def _read_json(p: pathlib.Path) -> dict:
+    try:
+        return json.loads(p.read_text(encoding='utf-8'))
+    except FileNotFoundError:
+        raise Conflict(f'注册表文件不存在: {p}')
+    except Exception as exc:  # noqa: BLE001 —— 报错口径统一：文件 + 原因
+        raise Conflict(f'读取注册表失败: {p}: {exc}')
+
+
+def _prefix(vertical: str, local: str) -> str:
+    """局部 id → 规范 id；已带 `<vertical>.` 前缀的原样返回（幂等）。"""
+    return local if local.startswith(f'{vertical}.') else f'{vertical}.{local}'
+
+
+def _check_local_id(vertical: str, kind: str, local: str) -> None:
+    if not LOCAL_ID_RE.match(local):
+        raise Conflict(
+            f'{vertical}: {kind} 局部 id 不合法 `{local}`（只允许小写字母/数字/连字符，且**不含点**——点用于命名空间）'
+        )
+
+
+def discover_verticals(root: pathlib.Path | None = None) -> list[tuple[str, pathlib.Path]]:
+    """列出已安装的业务线：目录名即 vertical id，必须含 manifest.json 与 flows.json。"""
+    vd = verticals_dir(root)
+    out: list[tuple[str, pathlib.Path]] = []
+    if not vd.is_dir():
+        return out
+    for d in sorted(vd.iterdir()):
+        if not d.is_dir() or d.name.startswith(('.', '_')):
+            continue
+        if not (d / 'manifest.json').exists() and not (d / 'flows.json').exists():
+            continue  # 占位目录（如 README.md 同级空目录）不算业务线
+        out.append((d.name, d))
+    return out
+
+
+def load_vertical(vid: str, vdir: pathlib.Path) -> dict:
+    """读一条业务线的 manifest + flows，做**结构级**校验（策略级检查在 vertical-lint）。"""
+    manifest_p = vdir / 'manifest.json'
+    flows_p = vdir / 'flows.json'
+    manifest = _read_json(manifest_p) if manifest_p.exists() else {}
+    if not manifest:
+        raise Conflict(f'{vid}: 缺 manifest.json（业务线必须有元数据）')
+    if manifest.get('id') != vid:
+        raise Conflict(f'{vid}: manifest.id=`{manifest.get("id")}` 与目录名不一致')
+    missing = [k for k in REQUIRED_MANIFEST if not manifest.get(k)]
+    if missing:
+        raise Conflict(f'{vid}: manifest.json 缺字段 {missing}（必需 {list(REQUIRED_MANIFEST)}）')
+
+    doc = _read_json(flows_p) if flows_p.exists() else {}
+    if not doc:
+        raise Conflict(f'{vid}: 缺 flows.json（业务线至少要有 flows 声明；空业务线用 `{{}}` 也应显式存在）')
+    declared = doc.get('vertical')
+    if declared != vid:
+        raise Conflict(f'{vid}: flows.json 的 `vertical` 字段=`{declared}` 与目录名不一致（防复制粘贴串线）')
+    return {'id': vid, 'dir': vdir, 'manifest': manifest, 'doc': doc}
+
+
+def merge(root: pathlib.Path | None = None) -> dict:
+    """合并 base + 所有业务线，返回**完整注册表文档**（形状与旧单文件一致，可直接替换）。"""
+    root = root or repo_root()
+    if mode() == 'legacy':
+        doc = _read_json(base_path(root))
+        doc.setdefault('_meta', {})['registryMode'] = 'legacy'
+        doc['_meta']['sources'] = [str(base_path(root))]
+        return doc
+
+    doc = _read_json(base_path(root))
+    out = dict(doc)
+    out['flows'] = dict(doc.get('flows') or {})
+    out['capabilities'] = dict(doc.get('capabilities') or {})
+    out['billing'] = dict(doc.get('billing') or {})
+    out['billing']['units'] = dict((doc.get('billing') or {}).get('units') or {})
+    out['entitlements'] = dict(doc.get('entitlements') or {})
+    out['entitlements']['roleMinPlan'] = dict((doc.get('entitlements') or {}).get('roleMinPlan') or {})
+    out['failureClasses'] = dict(doc.get('failureClasses') or {})
+
+    origin: dict[tuple[str, str], str] = {}          # (空间, 键) → 来源，用于冲突信息
+    for k in out['flows']:
+        origin[('flows', k)] = 'base'
+    for k in out['capabilities']:
+        if not k.startswith('_'):
+            origin[('capabilities', k)] = 'base'
+    for k in out['billing']['units']:
+        origin[('billing.units', k)] = 'base'
+    for k in out['entitlements']['roleMinPlan']:
+        origin[('entitlements.roleMinPlan', k)] = 'base'
+    for k in out['failureClasses']:
+        if not k.startswith('_'):
+            origin[('failureClasses', k)] = 'base'
+
+    aliases: dict[str, str] = dict(doc.get('aliases') or {})
+    verticals_meta: dict[str, dict] = {}
+    sources = [str(base_path(root))]
+
+    def put(space: str, key: str, value, src: str) -> None:
+        if key.startswith('_'):
+            return  # `_why`/`_note` 之类的说明键不参与合并（base 的保留）
+        seen = origin.get((space, key))
+        if seen is not None and seen != src:
+            raise Conflict(f'{space} 键 `{key}` 在 {seen} 与 {src} 重复定义（冲突即 fail，不静默覆盖）')
+        origin[(space, key)] = src
+        if space == 'billing.units':
+            out['billing']['units'][key] = value
+        elif space == 'entitlements.roleMinPlan':
+            out['entitlements']['roleMinPlan'][key] = value
+        elif space == 'failureClasses':
+            out['failureClasses'][key] = value
+        else:
+            out[space][key] = value
+
+    for vid, vdir in discover_verticals(root):
+        v = load_vertical(vid, vdir)
+        sources.append(str(vdir))
+        man, vdoc = v['manifest'], v['doc']
+        verticals_meta[vid] = {
+            'title': man.get('title'),
+            'version': man.get('version'),
+            'requires': man.get('requires'),
+            'verifiedOn': man.get('verifiedOn'),
+            'ports': man.get('ports'),
+            'roles': man.get('roles') or [],
+            'skills': man.get('skills') or [],
+        }
+
+        for local, spec in (vdoc.get('flows') or {}).items():
+            _check_local_id(vid, 'flow', local)
+            put('flows', _prefix(vid, local), spec, vid)
+
+        for local, spec in (vdoc.get('capabilities') or {}).items():
+            _check_local_id(vid, 'capability', local)
+            put('capabilities', _prefix(vid, local), spec, vid)
+
+        for name, spec in (vdoc.get('billing', {}).get('units') or {}).items():
+            put('billing.units', name, spec, vid)
+        for name, spec in (vdoc.get('entitlements', {}).get('roleMinPlan') or {}).items():
+            put('entitlements.roleMinPlan', name, spec, vid)
+        for name, spec in (vdoc.get('failureClasses') or {}).items():
+            put('failureClasses', name, spec, vid)
+
+        for short, target in (vdoc.get('aliases') or {}).items():
+            if short in aliases and aliases[short] != target:
+                raise Conflict(f'别名 `{short}` 冲突：{aliases[short]} vs {target}（来自 {vid}）')
+            aliases[short] = target
+
+        declared_flows = set(man.get('flows') or [])
+        if declared_flows:
+            actual = {_prefix(vid, k) for k in (vdoc.get('flows') or {})}
+            if declared_flows != actual:
+                raise Conflict(
+                    f'{vid}: manifest.flows 与 flows.json 不一致 —— 只在 manifest 里: {sorted(declared_flows - actual)}；'
+                    f'只在 flows.json 里: {sorted(actual - declared_flows)}'
+                )
+
+    out['aliases'] = aliases
+    out['verticals'] = verticals_meta
+    out['_meta'] = {
+        'registryMode': 'merged',
+        'sources': sources,
+        'verticals': sorted(verticals_meta),
+    }
+    return out
+
+
+def consumer_doc(path=None) -> dict:
+    """给既有消费者（flow_source / orchestrator / 计费 / 权限 / 打包…）的统一读入点。
+
+    · `path` 给定 ⇒ 读该文件的纯内容（保留"显式传注册表"的历史语义，测试夹具依赖）。
+    · 未给定 ⇒ 合并 base + 各业务线。**合并冲突照常抛**（冲突必须响亮失败，
+      不能因为"消费者怕麻烦"就静默回退成单文件 —— 那会让两条业务线悄悄撞名）。
+    """
+    return _read_json(pathlib.Path(path)) if path else merge()
+
+
+def resolve_flow_id(flow_id: str, doc: dict | None = None) -> str:
+    """把别名解析成规范 flow id（无别名时原样返回）。"""
+    doc = doc if doc is not None else merge()
+    return (doc.get('aliases') or {}).get(flow_id, flow_id)
+
+
+def load_flows(registry_path=None) -> dict:
+    """返回 flows 字典（历史形状：`load_registry()` 只返回 flows，多处依赖）。
+
+    `registry_path` 显式给出 ⇒ legacy 单文件模式（历史行为）。
+    """
+    if registry_path:
+        doc = _read_json(pathlib.Path(registry_path))
+    else:
+        doc = merge()
+    flows = doc.get('flows')
+    if not isinstance(flows, dict):
+        raise Conflict(f'流程注册表格式错误（缺 flows 对象）: {registry_path or base_path()}')
+    return flows
+
+
+def load_capabilities(registry_path=None) -> dict:
+    """返回 capabilities 段（与 flows 同级；空则 {}）。"""
+    try:
+        doc = _read_json(pathlib.Path(registry_path)) if registry_path else merge()
+    except Conflict:
+        return {}
+    caps = doc.get('capabilities')
+    return caps if isinstance(caps, dict) else {}
+
+
+def load_doc(registry_path=None) -> dict:
+    return _read_json(pathlib.Path(registry_path)) if registry_path else merge()
+
+
+def main(argv=None) -> int:
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    ap = argparse.ArgumentParser(description='流程注册表加载器（base + verticals 合并，冲突即 fail）')
+    ap.add_argument('--json', action='store_true', help='输出合并后的完整注册表（供 Node/shell 消费）')
+    ap.add_argument('--check', action='store_true', help='只做合并与冲突检查（成功打印摘要）')
+    ap.add_argument('--list', action='store_true', help='列出规范 flow id（含所属业务线）')
+    ap.add_argument('--flow', help='按 id 或别名取单条 flow 的规范 id')
+    ap.add_argument('--registry', help='legacy：显式指定单文件注册表（跳过合并）')
+    ap.add_argument('--mode', choices=('merged', 'legacy'), help='覆盖 ARGENT_REGISTRY_MODE')
+    a = ap.parse_args(argv)
+
+    if a.mode:
+        os.environ['ARGENT_REGISTRY_MODE'] = a.mode
+    try:
+        doc = load_doc(a.registry)
+    except Conflict as exc:
+        print(f'✗ 注册表合并失败：{exc}', file=sys.stderr)
+        return 2
+
+    if a.flow:
+        canonical = resolve_flow_id(a.flow, doc)
+        if canonical not in (doc.get('flows') or {}):
+            print(f'✗ 未知流程 `{a.flow}`（规范 id `{canonical}` 不在注册表中）', file=sys.stderr)
+            return 2
+        print(canonical)
+        return 0
+
+    if a.list:
+        for fid in sorted(doc.get('flows') or {}):
+            print(f'  {fid}')
+        return 0
+
+    if a.check:
+        meta = doc.get('_meta') or {}
+        vs = meta.get('verticals') or []
+        # ⚠️ 不要用"嵌套同引号 f-string"（PEP 701，Python 3.12+ 才允许）：
+        # 本仓库的流程脚本跑在 venv（**3.11**）里，系统 python 是 3.14 ⇒ 只有系统解释器能过，
+        # 真跑起来 SyntaxError（2026-09-29 实测：分诊全报"注册表为空"）。
+        cap_n = len([k for k in (doc.get('capabilities') or {}) if not k.startswith('_')])
+        vs_note = f'（{", ".join(vs)}）' if vs else ''
+        print(f'✅ 注册表合并通过：模式={meta.get("registryMode")}、'
+              f'flow {len(doc.get("flows") or {})} 条、能力 {cap_n} 个、'
+              f'业务线 {len(vs)} 条{vs_note}')
+        return 0
+
+    if a.json:
+        # 供 Node/shell 消费：稳定输出（键序固定，便于比对）
+        print(json.dumps(doc, ensure_ascii=False, sort_keys=True))
+        return 0
+
+    ap.print_help()
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/engine/scripts/flow_retry.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""流程重跑（**重置后重建**）—— 用户口径 A 的落地面（2026-09-17）。
+
+背景（真实票 77328544 暴露）：lip 表「一行一货件」，一轮跑挂掉后该行会停在
+`状态=失败` + 货件号仍在（美客多那边预约已 `Reserva cancelada`、标签/箱唛没产出）。
+旧架构对这类行的恢复语义是 **清货件号 + 清备注 + 置「待执行」+ 就绪=true**
+（orchestrator.py `_maybe_auto_reset` 的 lip 分支，KB-109「方案 A 重建」）⇒ 下一轮从头
+重建一个新货件，**不需要运营插手**。本脚本把这套语义做成**带守卫的独立动作**，
+供失败回路（retryable 类）与人工/掌舵者显式调用。
+
+守卫（写生产表，与发票回写器同规格）：
+  ① 字段白名单：只许改 `状态 / 就绪 / 备注 / 货件号`（来自流程注册表的 fields 映射）；
+  ② 记录白名单：必须 `--case`（或 `--record`）显式指定，一次一条；
+  ③ 分类闸门：该行备注必须分类为 **retryable**（flow_failure 同一套分类器）；
+     业务/门户状态类（如 `Reserva cancelada`、缺字段）**拒绝重置**，交人裁定；
+  ④ 次数上限：台账里该 case 的 `retry` 事件数 ≥ 上限（默认 2，同 AUTO_RETRY_MAX）⇒ 拒绝；
+  ⑤ 写前整行备份 + 写后读回验收 + 审计 JSONL + 台账 `retry` 事件；
+  ⑥ 默认 `--dry-run`，真写要 `--yes`。
+
+用法：
+  python3 scripts/flow_retry.py --flow full --case full__recvvgPQgoZW9B            # 预览
+  python3 scripts/flow_retry.py --flow full --case full__recvvgPQgoZW9B --yes      # 真写
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+import flow_config  # noqa: E402  唯一配置读取点
+from flow_failure import classify  # noqa: E402  同一套分类器（避免两套规则漂移）
+from flow_source import load_allowed_stores  # noqa: E402
+
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+AUDIT = DATA_DIR / "flow-retry-audit.jsonl"
+BACKUP_DIR = DATA_DIR / "flow-retry-backup"
+LEDGER = DATA_DIR / "flow-ledger.jsonl"
+DEFAULT_MAX = 2
+
+
+def lark(profile: str, args: list[str], timeout: int = 60):
+    p = subprocess.run(["lark-cli", "--profile", profile, "base", *args, "--as", "bot", "--format", "json"],
+                       capture_output=True, text=True, timeout=timeout)
+    if p.returncode != 0:
+        raise SystemExit(f"❌ lark-cli 失败：{(p.stderr or p.stdout).strip()[:300]}")
+    try:
+        return json.loads(p.stdout or "{}")
+    except json.JSONDecodeError:
+        raise SystemExit(f"❌ lark-cli 返回不是 JSON：{(p.stdout or '')[:200]}")
+
+
+def field_map(profile: str, base: str, table: str) -> dict:
+    d = lark(profile, ["+field-list", "--base-token", base, "--table-id", table])
+    items = ((d.get("data") or {}).get("fields") or d.get("fields") or [])
+    return {str(f.get("field_name") or f.get("name")): str(f.get("field_id") or f.get("id")) for f in items}
+
+
+def read_row(profile: str, base: str, table: str, record: str, fmap: dict) -> dict:
+    """读整行（按**字段名**取值）。
+
+    2026-09-17 实测：`+record-get` 返回**位置数组**形态 ——
+    `data.data=[值,…]` + `data.field_id_list=[字段id,…]`（与 record-list 同款，不带表头名），
+    另有两种 dict 形态（`data.record.fields` / `data.fields`）在老版本里出现过。
+    第一版只认 dict ⇒ **静默读成空行**（差点把"失败"误判成"已被重置"）⇒
+    现在三种形态都试，且**一个字段都读不出来就抛错**（宁可失败也不拿空行往下走）。
+    """
+    d = lark(profile, ["+record-get", "--base-token", base, "--table-id", table, "--record-id", record])
+    data = d.get("data") or {}
+    for c in (((data.get("record") or {}).get("fields")), data.get("fields")):
+        if isinstance(c, dict) and c:
+            return c
+    # 实测形态：data.data = [[值,…]]（**行数组**，每行是位置数组），data.fields = [列名,…]（同序）；
+    # 另有 data.field_id_list 可兜底（列名缺失时按 id→名 映射）。
+    vals = data.get("data")
+    names = data.get("fields")
+    if isinstance(vals, list) and vals and isinstance(vals[0], list):
+        row = vals[0]
+        if isinstance(names, list) and len(names) >= len(row):
+            return {str(n): v for n, v in zip(names, row)}
+        ids = data.get("field_id_list") or []
+        if ids:
+            id2name = {v: k for k, v in fmap.items()}
+            return {id2name.get(str(fid), str(fid)): v for fid, v in zip(ids, row)}
+    if isinstance(vals, dict) and vals:
+        return vals
+    raise SystemExit(f"❌ 读不到记录 {record} 的任何字段（返回形状异常：{list(data)[:8]}）—— 拒绝继续")
+
+
+def retry_count(case_id: str) -> int:
+    n = 0
+    try:
+        for line in LEDGER.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except Exception:
+                continue
+            if e.get("caseId") == case_id and e.get("event") == "retry":
+                n += 1
+    except FileNotFoundError:
+        pass
+    return n
+
+
+def first(v):
+    if isinstance(v, list):
+        return first(v[0]) if v else ""
+    if isinstance(v, dict):
+        return v.get("text") or v.get("name") or v.get("value") or ""
+    return "" if v is None else str(v)
+
+
+FAILURES_JSONL = DATA_DIR / "fulfillment-logs" / "failures.jsonl"
+
+
+def last_failed_step(record_id: str) -> int | None:
+    """从 failures.jsonl 取该 record **最近一条带 failed_step** 的记录（回退：None）。"""
+    try:
+        step = None
+        for ln in FAILURES_JSONL.read_text(encoding="utf-8").splitlines():
+            ln = ln.strip()
+            if not ln or record_id not in ln:
+                continue
+            try:
+                d = json.loads(ln)
+            except Exception:
+                continue
+            if d.get("record_id") == record_id and d.get("failed_step") is not None:
+                step = int(d["failed_step"])
+        return step
+    except Exception:
+        return None
+
+
+# 2026-09-18 用户业务规则（逐字）：
+#   「FULL流程如果失败了，如果是已经预约了要取消预约的，否则会有违约金；
+#     如果已经取消预约了，就可以从第一步开始重建货件号。」
+# ⇒ 清号重建（本脚本的动作）**必须先确认无预约残留**。判据全部来自本地既有留痕，无需开浏览器：
+def appointment_gate(note: str, failed_step: int | None) -> dict:
+    text = str(note or "")
+    if "预约已自动取消" in text or "无超时罚款风险" in text:
+        return {"ok": True, "why": "备注显示预约已自动取消 ⇒ 无残留，可重建"}
+    if "预约取消失败" in text or "请立即人工取消" in text:
+        return {"ok": False, "why": "备注显示**预约取消失败** ⇒ 必须先人工取消预约，禁止重建（违约金风险）"}
+    if failed_step is not None and failed_step <= 4:
+        return {"ok": True, "why": f"失败在步骤{failed_step}（步骤4未完成）⇒ 预约从未提交，无残留，可重建"}
+    if failed_step is not None and failed_step >= 5:
+        return {"ok": False,
+                "why": f"失败在步骤{failed_step}（步骤4已完成 ⇒ 曾建立预约）但备注里**没有任何取消留痕**"
+                       f"（异常终止/取消未落痕）⇒ 先人工核对门户预约并取消，再重建"}
+    return {"ok": False, "why": "无法判定预约状态（备注与 failures.jsonl 都无留痕）⇒ 人工核对门户后放行"}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="流程重跑（重置后重建，带守卫）")
+    ap.add_argument("--flow", required=True, help="流程 id（如 full）")
+    ap.add_argument("--case", help="台账 case id（full__<record_id>）")
+    ap.add_argument("--record", help="直接给 record_id")
+    ap.add_argument("--max", type=int, default=DEFAULT_MAX, help=f"自动重跑上限（默认 {DEFAULT_MAX}，同 AUTO_RETRY_MAX）")
+    ap.add_argument("--reason", default="", help="重跑原因（写进审计/台账）")
+    ap.add_argument("--yes", action="store_true", help="真写（默认 dry-run）")
+    ap.add_argument("--allow-clear-shipment", action="store_true",
+                    help="显式放行**清空已有货件号**（缺陷④ 闸门；默认拒绝——清号后重建会在平台留孤儿货件）")
+    ap.add_argument("--override", action="store_true",
+                    help="人工授权覆盖分类闸门（仅当人已判断应重跑；必须配 --reason，会记审计）")
+    a = ap.parse_args(argv)
+
+    cfg = flow_config.load_config(a.flow)
+    src = cfg.get("source") or {}
+    base, table, profile = str(src.get("base") or ""), str(src.get("table") or ""), str(src.get("identity") or "")
+    if not (base and table and profile):
+        print("❌ 流程未解析出 base/table/identity", file=sys.stderr)
+        return 2
+    names = src.get("fields") or {}
+    f_status, f_ready = names.get("status"), names.get("ready")
+    f_note, f_ship = names.get("note"), None
+    # 货件号：票号列（source.ticketField 或默认「货件号」）
+    f_ship = src.get("ticketField") or "货件号"
+
+    record = a.record or (a.case.split("__", 1)[1] if a.case and "__" in a.case else "")
+    if not record:
+        print("❌ 需要 --case full__<record_id> 或 --record <record_id>（记录白名单，一次一条）", file=sys.stderr)
+        return 2
+    case_id = a.case or f"{a.flow}__{record}"
+
+    fmap = field_map(profile, base, table)
+    need = {f_status: "状态", f_ready: "就绪", f_note: "备注", f_ship: "货件号"}
+    missing = [n for n in need if not n or n not in fmap]
+    if missing:
+        print(f"❌ 表里缺这些列：{missing}（可用：{', '.join(list(fmap)[:12])}）", file=sys.stderr)
+        return 2
+
+    row = read_row(profile, base, table, record, fmap)
+    status = first(row.get(f_status))
+    note = first(row.get(f_note))
+    ship = first(row.get(f_ship))
+    kind = classify(note, attempt=retry_count(case_id) + 1, max_attempts=a.max)
+    print(f"── 现场 ──")
+    print(f"  流程/表 : {a.flow}｜{table}")
+    print(f"  记录    : {record}（{f_ship}={ship or '(空)'}）")
+    print(f"  状态    : {status or '(空)'}｜就绪={first(row.get(f_ready)) or '(空)'}")
+    print(f"  备注    : {note[:120] or '(空)'}")
+    print(f"  分类    : {kind.get('kind')}｜已重跑 {retry_count(case_id)}/{a.max} 次")
+
+    if status != "失败":
+        print(f"❌ 只重置「失败」行（当前={status or '空'}）—— 其余状态请走正常链路", file=sys.stderr)
+        return 2
+    override = bool(a.override)
+    if kind.get("kind") != "retryable" and not override:
+        print(f"❌ 分类不是 retryable（{kind.get('kind')}）⇒ 拒绝重置，交人裁定：{kind.get('reason')}", file=sys.stderr)
+        print("   若人工已判断「应当重跑」（例如原始失败是瞬时类、只是备注被取证结论覆盖），"
+              "用 --override --reason '<授权说明>' 显式放行；该动作会记进审计与台账。", file=sys.stderr)
+        return 3
+    if override and kind.get("kind") != "retryable":
+        print(f"⚠️ 人工覆盖分类闸门（原分类 {kind.get('kind')}）—— 授权说明：{a.reason or '(未填写)'}")
+    # 预约闸门（用户业务规则）：清号重建前必须确认**无预约残留**，否则违约金。
+    fstep = last_failed_step(record)
+    gate = appointment_gate(note, fstep)
+    print(f"  预约闸门: {'✅ 放行' if gate['ok'] else '⛔ 拒绝'}｜{gate['why']}")
+    if not gate["ok"] and not override:
+        print(f"❌ 预约闸门拒绝（{gate['why']}）", file=sys.stderr)
+        print("   业务规则：失败时若已预约必须先取消预约（否则违约金）；确认无残留后才可从第一步重建。"
+              "\n   人工已核对门户确认无预约残留时，用 --override --reason '<核对说明>' 显式放行。", file=sys.stderr)
+        return 3
+    if retry_count(case_id) >= a.max:
+        print(f"❌ 已达自动重跑上限（{a.max}）⇒ 拒绝重置，保持失败走人工", file=sys.stderr)
+        return 3
+
+    # ── 缺陷④ 闸门（2026-09-23 角色交接）：行内**已有货件号**时，默认**拒绝清号重置** ────────
+    # 为什么必须拦：货件号是我们找回"平台半成品货件"的唯一线索（MEDg 77832069 就是活例：
+    # 脚本清号重建过一次，平台侧那个货件仍在 En preparación）。清号 = 平台多一个孤儿货件。
+    # 实测三例（角色给的夹具）：Ujxv 77840232 / KSA5 77843263 / r9ZC 77849070。
+    # 正确路径排序：① 改号后续跑（保留货件号，见缺陷⑰）；② 确认平台侧已取消/无残留后**显式**放行；
+    #              ③ 交人工裁定。
+    # ⚠️ 2026-10-13 修复（**死守卫**）：此处原为 `one(row.get(f_ship))`，而本文件**没有** `one()` 定义
+    # ⇒ NameError 被下面的 `except Exception` 静默吞掉 ⇒ `ship_now=None` ⇒ **已有货件号也会被清号重置**：
+    # 这条"必须拦"的红线事实上从未生效。本文件其它取值点一律用 `first()`（见 :205-207）。
+    # 修法：改用唯一取值助手 `first()`（对 list/dict/None 都是全函数 ⇒ 不会抛），并**去掉那层吞噬**
+    # ⇒ 将来再写错名字会**响亮炸**，而不是静默退化成"守卫不生效"。
+    # 门禁：`scripts/tests/flow-retry-guard4.test.py` 钉住"本块不得再出现未定义助手 / 不得再被 except 吞"。
+    ship_now = first(row.get(f_ship))
+    if ship_now and not getattr(a, "allow_clear_shipment", False):
+        print(f"❌ 拒绝清号重置：本行已有货件号 {ship_now!r}（record={record}）。", file=sys.stderr)
+        print("   货件号是找回平台半成品货件的唯一线索；清掉再重建会在平台留下**孤儿货件**。", file=sys.stderr)
+        print("   正确路径：① 若号码错位（缺陷⑰）⇒ 改号后保留货件号续跑；"
+              "② 已核对门户确认该货件无残留 ⇒ 用 --allow-clear-shipment --reason '<核对说明>' 显式放行；"
+              "③ 否则交人工裁定。", file=sys.stderr)
+        return 3
+
+    # lip 语义：清货件号 + 清备注 + 状态→待执行 + 就绪=true（下一轮从头重建）
+    pending = "待执行"
+    patch = {fmap[f_status]: pending, fmap[f_ready]: True, fmap[f_note]: "", fmap[f_ship]: ""}
+    allowed = {fmap[f_status], fmap[f_ready], fmap[f_note], fmap[f_ship]}
+    assert set(patch) <= allowed, "内部错误：补丁越界"
+
+    print("── 计划（重置后重建）──")
+    for k, v in patch.items():
+        label = {fmap[f_status]: f_status, fmap[f_ready]: f_ready, fmap[f_note]: f_note, fmap[f_ship]: f_ship}[k]
+        print(f"  {label:8} → {v!r}")
+    if not a.yes:
+        print("\n[dry-run] 未写入。加 --yes 才落库。")
+        return 0
+
+    BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+    at = datetime.datetime.now().isoformat(timespec="seconds")
+    bk = BACKUP_DIR / f"{a.flow}__{record}__{at.replace(':', '')}.json"
+    bk.write_text(json.dumps({"flow": a.flow, "base": base, "table": table, "record": record,
+                              "at": at, "fields": row}, ensure_ascii=False, indent=2), encoding="utf-8")
+    # 载荷形状以**同表已验证**的发票回写器为准（wenyao-invoice-writeback.mjs:updateFields）：
+    #   {"update_records": {"<record_id>": {"<field_id>": 值, …}}}
+    # 第一版用了 {"records":[{record_id,fields}]} ⇒ 800010701 校验失败（record_id_list 等 3 处不合法）。
+    lark(profile, ["+record-batch-update", "--base-token", base, "--table-id", table,
+                   "--json", json.dumps({"update_records": {record: patch}}, ensure_ascii=False)])
+    after = read_row(profile, base, table, record, fmap)
+    ok = (first(after.get(f_status)) == pending and str(after.get(f_ship) or "") == ""
+          and not first(after.get(f_note)))
+    with AUDIT.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps({"at": at, "flow": a.flow, "record": record, "caseId": case_id,
+                             "action": "reset-rebuild", "kind": kind.get("kind"), "reason": a.reason,
+                             "before": {"status": status, "shipment": ship, "note": note[:200]},
+                             "after": {"status": first(after.get(f_status)), "shipment": first(after.get(f_ship))},
+                             "backup": str(bk), "ok": bool(ok)}, ensure_ascii=False) + "\n")
+    subprocess.run([sys.executable, str(HERE / "flow_ledger.py"), "--ledger", str(LEDGER), "--case-id", case_id,
+                    "--event", "retry", "--attempt", str(retry_count(case_id) + 1), "--by", "flow_retry",
+                    "--detail", f"重置后重建（{kind.get('kind')}）：状态→{pending}｜清货件号/备注｜就绪=true"
+                                + (f"｜{a.reason}" if a.reason else "")], check=False)
+    print(f"  ✅ 已重置并读回{'一致' if ok else '**不一致**'}｜备份 {bk.name}｜审计 flow-retry-audit.jsonl")
+    print(f"     下一轮该行会以「{pending}」+ 就绪=true 被识别为执行相，从头重建新货件（无需运营操作）")
+    return 0 if ok else 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())