@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_failure.py

@@ -0,0 +1,588 @@
+#!/usr/bin/env python3
+"""flow_failure —— **失败分类 + 未处置失败扫描**（"出错有 agent 接手"回路的确定性内核）。
+
+设计口径（2026-09-16 用户确认）：
+  "出错有 agent 接手" ≠ 另一个 subagent 抢活；而是**把掌舵者叫醒，让它判断**
+  「重试 / 等人 / 升级」，并把判断与理由记进台账。
+
+关键分界（避免死循环烧 token）：
+  · **retryable**（网络抖动/超时/429/5xx）→ 确定性可重试，**不叫醒任何人**（脚本自己重试即可）；
+  · **needs_human**（缺字段/需运营补数据/路由选错行）→ 唤醒也无用，应记 blocked + 落卡等人；
+  · **needs_agent**（其余：选择器变化/未知退出码/门户异常）→ **只有这一类唤醒角色判断**。
+
+用法：
+  python3 scripts/flow_failure.py --error "P1 路由守卫拦截：货代=冲港" [--attempt 2] [--json]
+  python3 scripts/flow_failure.py --scan --flow wenyao-invoice [--ledger L] [--json]
+      → 列出"尚未处置"的失败（该 case 最近一次 failed 之后没有 wake/retry/blocked/done 事件）
+        并附分类、唤醒次数、冷却剩余秒数。
+  python3 scripts/flow_failure.py --flow full --case full__<rec> [--ledger L]
+      → 打印该 case 的**规范失败原因**（引擎写进台账 `failed.reason` 的那一串 = 表备注同一串；
+        老台账没有该字段时回落到 `error` 去掉身份前缀）。
+        **口径统一入口**：写 `blocked` 时 `--error` 逐字用它 ⇒ 表备注与账本同源同文
+        （⛔ 不许改写/翻译/加解读；生产实测 79096447 的误导就是"解读"造成的）。
+  python3 scripts/flow_failure.py --flow <flow> --error "<原始原因>" [--missing 产品图片,HS编码] --ops-message
+      → 组成**运营可见文案**（`结论：<业务类|系统类|我方缺陷类>｜<原因>｜动作：<可照做的动作>`）——
+        这是**唯一措辞来源**：发票流程写表「发票错误信息」与台账 `blocked/failed` 必须用它产出的
+        **同一串**（`scripts/invoice_fail_closeout.py` 就是这条链的执行者）。⛔ 代码级异常
+        （`AttributeError`/裸栈/`object has no attribute`…）一律归**我方缺陷类**且**不回原文**。
+  python3 scripts/flow_failure.py --flow <flow> --release-only
+      → 打印该流程的放行位（门控列）、Rule R 是否开启、上限/冷却与运营动作提示。
+退出码：0 正常；2 参数错误 / `--case` 取不到原因。
+
+**失败前核验的两句文案也在这里**（`verified_effective_note()` / `unverified_reason()`，2026-10-09）：
+幂等写步骤（3/4/8）判成功时台账/备注必须说清"报错但已核验生效（幂等）"并带证据来源；
+核验**不可用**时仍判失败、但文案必须写明「核验不可用（原因）」。⛔ 不许在别处再写第二套措辞。
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import pathlib
+import re
+import sys
+import time
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+# 台账默认位置：数据目录走**唯一判据**（三级链；勿在此复制链）
+DEFAULT_LEDGER = pathlib.Path(resolve_data_dir()['dir']) / 'flow-ledger.jsonl'
+HANDLED_EVENTS = ('wake', 'retry', 'blocked', 'done', 'failed_ack')
+
+# 分类规则（顺序敏感：先匹配到的赢）
+def rule_patterns(group: str) -> list:
+    """从注册表读某组失败分类规则（P3：判据唯一权威副本）；读不到返回空（调用方用内置兜底）。"""
+    try:
+        doc = _registry_doc()   # 兜底语义不变（读不到用内置规则；冲突由门禁响亮拦）
+        grp = (doc.get('failureClasses') or {}).get(group) or {}
+        return [str(x) for x in (grp.get('patterns') or []) if str(x).strip()]
+    except Exception:
+        return []
+
+
+_BUILTIN = {
+    'needs_human': (
+        r'缺(?:[失了少]|\s)|未填|为空|空值|missing|不存在|未就绪|闸门|校验不通过|需运营|等运营|请补|'
+        r'路由守卫|货代.*[≠!=]|不匹配|非.{0,6}货代|选错|人工|'
+        # 2026-09-17 门禁金样例暴露：这类是**可人工处理**的运行前提问题（有人去授权/登录即可），
+        # 不是"需要角色判断"的模糊故障 ⇒ 归 needs_human（落卡等人），不惊动角色白跑一趟。
+        r'未授权|未登录|登录失效|登录墙|login_expired|无权限|permission'),
+    # 2026-09-18：页面/选择器类（UI 选择器超时 ≠ 网络超时）。旧架构既定规则 = 选择器/业务类
+    # **绝不自动重置**；但下面的 retryable 里有 `超时|timeout` 会把它吞掉 ⇒ 允许清号重建 = 重复建单。
+    # 本组在 retryable **之前**匹配 ⇒ 归 needs_agent（交掌舵者判断）。
+    'pageFlaky': (
+        r'等待选择器超时|选择器\s*超时|selector\s*(timeout|超时)|wait_for_selector|'
+        r'locator.*(timeout|超时)|input\[[a-z]+\]|date_input'),
+    'retryable': (
+        r'timeout|timed out|超时|连接|connection|ECONN|ETIMEDOUT|EAI_AGAIN|socket|网络|'
+        r'429|502|503|504|rate limit|限流|too many requests|temporar|稍后重试|重试即可|'
+        # 2026-09-23 实测：美客多限流/前端模块加载失败的原字样（此前 `rate limit` 带空格，
+        # 匹配不上 ML 的 `local_rate_limited` 下划线写法 ⇒ 被归到"需判断"，没走自动重试）。
+        r'local_rate_limited|rate_limit|resolveProps|fbm-shipment-planning-frontend|'
+        r'Error loading|上下文销毁|context destroyed|Cannot load\.|'
+        # 2026-09-17（真实失败票实测）：**浏览器/页面瞬时类** —— 旧架构对这类本来就是
+        # 「下一轮轮询自动重置重跑」（AUTO_RETRY_MAX=2），不是要人判断的业务失败。
+        r'页面导航失败|导航失败|Target page|browser has been closed|Target closed|Page\.goto|'
+        r'net::ERR_|ERR_SOCKS_CONNECTION_FAILED|NS_ERROR_|context or browser|browser context'),
+    # 2026-10-10（FULL 自动路径成功率修复批）：**仓容满**。判据与文案的唯一真源是
+    # `scripts/ml_capacity_probe.py`（`PLATFORM_QUOTES` + `capacity_failure_text`），
+    # 这里是**注册表**侧的同一份口径（`failureClasses.capacityFull`）。内置兜底只留"平台原文
+    # 片段 + 分类标记"，与注册表逐字一致；⛔ 不在这里另加"预约页形态"类判据（那是另一条链）。
+    'capacityFull': (
+        r'capacity_full|liberar espacio de almacenamiento|liberar espacio|'
+        r'retirar stock de baja calidad|retirando stock de baja calidad|'
+        r'stock de baja calidad|仓容满|库容满'),
+}
+# 注册表优先（P3 判据收敛）：注册表有该组规则就用它，否则用内置兜底（保证老部署/离线也能跑）
+EFFECTIVE = {
+    'capacityFull': rule_patterns('capacityFull') or [_BUILTIN['capacityFull']],
+    'pageFlaky': rule_patterns('pageFlaky') or [_BUILTIN['pageFlaky']],
+    'needs_human': rule_patterns('needsHuman') or [_BUILTIN['needs_human']],
+    'retryable': rule_patterns('flowRetryable') or [_BUILTIN['retryable']],
+}
+# 顺序敏感：pageFlaky **必须**在 retryable 之前（否则被 `超时|timeout` 吞掉）。
+# 2026-10-10：**capacityFull 排在最前**（在 needs_human 之前）—— 仓容满的文案里带
+# `需运营` 与 `仓容满` 两个字样，若让 needsHuman 先匹配就再也分不出"是哪条链"，
+# 而它俩的正确动作完全不同（补数据/放行 vs 清低质库存腾库容），且只有它允许当日在
+# 预检证据下解除 defer。⚠️ 它**不**抢 retryable 的活：本组只认平台原文与显式标记。
+# 分组 → **派发用的 kind**：pageFlaky 派发为 needs_agent（唤醒掌舵者判断），
+# 但它的理由单独给（GROUP_WHY），避免与"未知类兜底"混为一谈。
+GROUPS = (('capacityFull', 'needs_human'), ('pageFlaky', 'needs_agent'),
+          ('needs_human', 'needs_human'), ('retryable', 'retryable'))
+RULES = tuple((g, k, re.compile('|'.join(EFFECTIVE[g]), re.I)) for g, k in GROUPS)
+DEFAULT_KIND = 'needs_agent' 
+GROUP_WHY = {
+    'pageFlaky': '页面/选择器类（UI 选择器超时，**非网络类**）⇒ 交掌舵者判断；'
+                 '**禁止自动清号重建**（旧架构规则：选择器/业务类绝不自动重置，防重复建单）',
+    'capacityFull': '仓容（库容）满（平台原文拒绝继续发货）⇒ 前提问题，正确动作**唯一**'
+                    '（需运营清低质库存腾库容）⇒ 落卡等人；有**独立**的当日重试语义'
+                    '（预检发现仓容恢复 ⇒ 当日解除 defer），⛔ 绝不与"预约页形态异常"混链',
+}
+KIND_WHY = {
+    'retryable': '确定性可重试（网络/限流类）⇒ 脚本自行重试，不唤醒角色',
+    'needs_human': '需人工/运营介入（缺数据或选错行）⇒ 应记 blocked 落卡等人，唤醒角色无意义',
+    'needs_agent': '需要判断（其余未知类）⇒ 唤醒掌舵者判断「重试/等人/升级」',
+}
+
+
+def classify(error: str, attempt: int | None = None, max_attempts: int = 3) -> dict:
+    """把一段失败文本分类成 retryable / needs_human / needs_agent。"""
+    text = str(error or '')
+    kind, why = DEFAULT_KIND, KIND_WHY[DEFAULT_KIND]
+    for grp, k, pat in RULES:
+        if pat.search(text):
+            kind, why = k, (GROUP_WHY.get(grp) or KIND_WHY[k])
+            break
+    if kind == 'retryable' and attempt is not None and attempt >= max_attempts:
+        kind, why = 'needs_agent', f'已达自动重试上限（attempt={attempt}）⇒ 需角色判断'
+    return {'kind': kind, 'reason': why, 'error': text[:300]}
+
+
+# ── 运营可见文案：**唯一措辞来源**（2026-10-09，缺陷 B）────────────────────────
+# 背景（客户机现场）：`recvvgPQgoUOwx` 跑失败后，表里「发票就绪」被取消、而「发票错误信息」
+# **是空的**（原因只在台账里）⇒ 运营看到"勾没了 + 没有任何说明"，以为脚本坏了、也不知道怎么处理。
+# 纪律（用户口径）：
+#   ① 失败必须写原因 + **可照做的动作**，且**表字段与台账同源同文**（同一函数产出、同一串）；
+#   ② 先一句**结论**（业务类 / 系统类 / 我方缺陷类，明确区分），再一句**动作**；
+#   ③ ⛔ 绝不把裸异常栈 / "某某 object has no attribute" 直接塞给运营（那既不可读也不可执行）。
+# 出口只有本模块的三个函数：`ops_category` / `ops_message`（+ `release_hint` 取放行位文案）。
+OPS_CATEGORY_BUSINESS = '业务类'
+OPS_CATEGORY_SYSTEM = '系统类'
+OPS_CATEGORY_DEFECT = '我方缺陷类'
+OPS_PREFIX = '结论：'
+# **我方缺陷类**判据（代码级异常特征）——刻意**窄**：只认"这是程序自己炸了"的形态，
+# 不认业务词（缺字段/路由不匹配等仍归业务类）。命中即**不把原文**给运营（见 ops_reason）。
+CODE_NOISE = (
+    r'object has no attribute',
+    r'\bAttributeError\b', r'\bTypeError\b', r'\bKeyError\b', r'\bIndexError\b',
+    r'\bValueError\b', r'\bNameError\b', r'\bUnboundLocalError\b', r'\bZeroDivisionError\b',
+    r'\bRecursionError\b', r'\bSyntaxError\b', r'\bIndentationError\b',
+    r'\bModuleNotFoundError\b', r'\bImportError\b', r'\bFileNotFoundError\b',
+    r'ERR_MODULE_NOT_FOUND', r'ERR_INVALID_ARG_TYPE',
+    r'Traceback \(most recent call last\)', r'\bNoneType\b',
+    r'\.py", line \d+', r'\bat [\w$.]+ \(', r'\bTypeError:', r'\bError: ',
+)
+_CODE_NOISE_RE = tuple(re.compile(p, re.I) for p in CODE_NOISE)
+OPS_REASON_LIMIT = 300          # 台账 `--detail` 的上限就是 300（flow_ledger.py）⇒ 同源同文必须 ≤ 它
+
+
+def is_code_noise(text: str) -> bool:
+    """这段失败文本是不是**代码级异常**（= 我方缺陷类）？"""
+    t = str(text or '')
+    return bool(t.strip()) and any(p.search(t) for p in _CODE_NOISE_RE)
+
+
+def _flow_spec(flow_id: str) -> dict:
+    """注册表里某流程的声明（走别名；读不到返回 {}）。"""
+    try:
+        doc = _registry_doc()
+    except Exception:                                          # noqa: BLE001
+        return {}
+    canon = (doc.get('aliases') or {}).get(flow_id, flow_id)
+    return ((doc.get('flows') or {}).get(canon) or {})
+
+
+def _picks_of(src: dict) -> list:
+    """流程声明的全部 `pick`（**变体优先，其次顶层**）+ 各自的 fields。
+
+    为什么两份都要看：FULL 的 pick 写在 `source.variants.<名>.pick`，发票流程写在**顶层**
+    `source.pick` —— 旧实现只看变体 ⇒ 发票流程的放行位/提示恒为空（2026-10-09 一并修对）。
+    """
+    out = []
+    variants = src.get('variants') or {}
+    order = [k for k in [str(src.get('default') or ''), *variants.keys()] if k in variants] or list(variants)
+    for name in order:
+        v = variants.get(name) or {}
+        out.append(((v.get('pick') or {}), (v.get('fields') or {})))
+    out.append(((src.get('pick') or {}), (src.get('fields') or {})))
+    return out
+
+
+def release_config(flow_id: str) -> dict:
+    """人工放行（Rule R）声明 → `{'enabled','maxPerCase','cooldownMin','field','hint'}`。
+
+    `field` = 该流程**自己的门控列**（例如物流流程是「就绪」、发票流程是「发票就绪」）——⛔ 不写死、不照抄。
+    `hint` = 注册表 `failureClasses.opsAction.text` 把 `{release}` 换成该列名后的运营动作提示；
+    流程**没开** `releaseReDispatch` ⇒ `hint=''`（宁可不提示，也不写一句兑现不了的话）。
+    """
+    src = (_flow_spec(flow_id).get('source') or {})
+    tpl = ''
+    try:
+        tpl = str(((_registry_doc().get('failureClasses') or {}).get('opsAction') or {}).get('text') or '')
+    except Exception:                                          # noqa: BLE001
+        tpl = ''
+    fallback_field = ''
+    for pick, fields in _picks_of(src):
+        field = str(((pick.get('release') or {}).get('field') or (fields or {}).get('ready') or ''))
+        rd = pick.get('releaseReDispatch') or {}
+        if not fallback_field and field:
+            fallback_field = field
+        if rd.get('enabled') and field:
+            return {'enabled': True, 'maxPerCase': int(rd.get('maxPerCase') or 0) or 3,
+                    'cooldownMin': int(rd.get('cooldownMin') or 0), 'field': field,
+                    'hint': (tpl.replace('{release}', field) if tpl else '')}
+    return {'enabled': False, 'maxPerCase': 0, 'cooldownMin': 0, 'field': fallback_field, 'hint': ''}
+
+
+def release_hint(flow_id: str) -> str:
+    """该流程的"运营动作提示"（未开 Rule R ⇒ 空串）。**唯一实现**：orchestrator 与发票侧共用。"""
+    return release_config(flow_id)['hint']
+
+
+def ops_category(reason: str, kind: str | None = None) -> str:
+    """结论类别（给运营看的第一句）：业务类 / 系统类 / 我方缺陷类。
+
+    判据（顺序敏感）：**代码级异常特征 ⇒ 我方缺陷类**（哪怕分类器兜到 needs_agent）；
+    其余按 `classify()` 的 kind：needs_human ⇒ 业务类，retryable/needs_agent ⇒ 系统类。
+    """
+    if is_code_noise(reason):
+        return OPS_CATEGORY_DEFECT
+    k = kind or str(classify(reason).get('kind') or '')
+    return OPS_CATEGORY_BUSINESS if k == 'needs_human' else OPS_CATEGORY_SYSTEM
+
+
+def ops_reason(reason: str, category: str) -> str:
+    """结论里的"原因"部分：单行化 + 去身份前缀；**我方缺陷类一律不回原文**（防裸栈进表）。"""
+    if category == OPS_CATEGORY_DEFECT:
+        return '流程脚本内部错误（异常明细在运行日志/台账，⛔ 未把原始栈写进本列）'
+    one = ' '.join(canonical_reason(reason).split())
+    return one or '（原因缺失：请把台账 failed.error 原文交维护者核对）'
+
+
+def _brief(items, n: int = 6) -> str:
+    """把字段清单压成可读的一行（超过 n 项省略）——防止动作句被长度上限截掉尾巴。"""
+    xs = [str(x) for x in (items or [])]
+    return '、'.join(xs[:n]) + ('…' if len(xs) > n else '')
+
+
+def ops_action(flow_id: str, category: str, missing=(), kind: str | None = None) -> str:
+    """动作部分（第二句）：**可照做**，且只说兑现得了的话（未开 Rule R 就不说"会自动重跑"）。"""
+    rc = release_config(flow_id)
+    rel = rc['field'] or '放行位'
+    if category == OPS_CATEGORY_DEFECT:
+        return f"无需你处理：已上报问述科技排查（本行已留证据）；请勿重复勾选「{rel}」"
+    if category == OPS_CATEGORY_BUSINESS:
+        what = f"补齐 {_brief(missing)} 后" if missing else "按上面的原因在表内补齐数据后"
+        tail = (f"，系统下一轮会自动重跑（无需通知运维）" if rc['enabled']
+                else "，并通知运维重跑（本流程未开「人工放行重跑」）")
+        return f"{what}重新勾选「{rel}」{tail}"
+    k = kind or DEFAULT_KIND
+    if k == 'retryable':
+        return "无需你补数据：系统会自动重试（网络/门户瞬时类）；若下一轮仍未恢复，会由角色接手判断"
+    return f"无需你补数据：已转交运维/角色判断（页面/门户类）；请勿重复勾选「{rel}」（重复勾选不会加速）"
+
+
+def ops_message(flow_id: str, reason: str, *, missing=(), kind: str | None = None,
+                limit: int = OPS_REASON_LIMIT) -> str:
+    """**结论 + 动作**的运营可见文案 —— 表字段与台账 `blocked/failed` 文案的**唯一来源**。
+
+    形状：`结论：<类别>｜<原因>｜动作：<动作>`（单行；≤ `limit` = 台账 `--detail` 上限 300，
+    这样"表里那串"与"台账里那串"可以**逐字节相等**，不会因截断而分叉）。
+    已带 `结论：` 前缀的输入**原样返回**（幂等：重复收口不会套两层壳）。
+    """
+    text = str(reason or '').strip()
+    if text.startswith(OPS_PREFIX):
+        return text[:limit]
+    k = kind or str(classify(text).get('kind') or DEFAULT_KIND)
+    cat = ops_category(text, k)
+    act = ops_action(flow_id, cat, missing, k)
+    body = ops_reason(text, cat)
+    head = f"{OPS_PREFIX}{cat}｜"
+    tail = f"｜动作：{act}"
+    room = max(20, limit - len(head) - len(tail))
+    if len(body) > room:
+        body = body[:max(1, room - 1)] + '…'
+    return f"{head}{body}{tail}"[:limit]
+
+
+# ── 「失败前核验」的两句**唯一措辞**（2026-10-09，步骤3/4/8 幂等误报）──────────────
+# 现场：货件 79191341 的取消其实**已生效**（列表页 `Reserva cancelada`、`appointment` 空），
+# 而引擎把"平台错误页导致按钮找不到"报成了失败 ⇒ 表 `FULL状态=失败`、台账被人工纠正成 done。
+# 判据层在 `scripts/flow_write_verify.py`（纯函数三态）；**文案**只在这里，⛔ 不许在别处再写一套。
+VERIFY_OK_MARK = '已核验生效（幂等）'
+VERIFY_UNAVAILABLE_MARK = '核验不可用'
+
+
+def verified_effective_note(step_title: str, truth: str, evidence: str,
+                            *, limit: int = OPS_REASON_LIMIT) -> str:
+    """**判成功**时的台账/备注串（唯一措辞）：
+    `<步骤> 脚本报错但核验为<真相>（<证据来源>）⇒ 判成功（已核验生效（幂等））`。
+
+    为什么必须带证据来源：运维看到的不能只是"引擎说成功了"，而是"**凭什么**说成功"
+    ——hub-v2 的哪一项（判据名）/ 列表页的 `status`，可当场复核（本现场就是这么纠正的）。
+    """
+    ev = ' '.join(str(evidence or '').split()) or '无证据串（不应发生）'
+    head = f"{' '.join(str(step_title or '').split())} 脚本报错但核验为{str(truth or '已生效').strip()}"
+    tail = f"⇒ 判成功（{VERIFY_OK_MARK}）"
+    room = max(20, limit - len(head) - len(tail) - 3)
+    if len(ev) > room:
+        ev = ev[:max(1, room - 1)] + '…'
+    return f"{head}（{ev}）{tail}"[:limit]
+
+
+def unverified_reason(reason: str, why: str, *, limit: int = OPS_REASON_LIMIT) -> str:
+    """**失败侧**的文案收口（唯一实现）：
+
+    · `why` 为空 ⇒ **原样返回**（= 核验"明确否定"或没跑核验 ⇒ **保持现在的失败路径与文案**，逐字不变）；
+    · `why` 非空 ⇒ 在原失败原因尾部追加 `；核验不可用（<why>）`（⛔ 不改原话、⛔ 不当成功）。
+
+    为什么不可用也要写进文案：运维看到"脚本说没取消"时，必须知道**引擎有没有核验过**
+    ——没核验过（探针 store_busy / 页面残缺 / 超时）与"核验过且确认没取消"的处置完全不同。
+    """
+    base = ' '.join(str(reason or '').split())
+    w = ' '.join(str(why or '').split())
+    if not w:
+        return base[:limit]
+    suffix = f"；{VERIFY_UNAVAILABLE_MARK}（{w}）"
+    room = max(10, limit - len(suffix))
+    if len(base) > room:
+        base = base[:max(1, room - 1)] + '…'
+    return f"{base}{suffix}"[:limit]
+
+
+def read(path: pathlib.Path) -> list:
+    if not path.exists():
+        return []
+    out = []
+    for ln in path.read_text(encoding='utf-8').splitlines():
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            out.append(json.loads(ln))
+        except Exception:
+            continue
+    return out
+
+
+def _prefixes(flow: str | None) -> tuple:
+    """该流程在台账里可能出现的**所有** caseId 前缀（P2a）。
+
+    台账里写的是"当时那条流程叫什么"：业务线落位前的短名（如 `<短名>__…`）与落位后的规范 id
+    （`<vertical>.<flow>`）并存。失败回路按前缀归属 ⇒ 只认规范前缀会让历史未处置**集体消失**
+    （统计与失败卡都会少算）。这里把规范 id 与所有指向它的别名一起作为可接受前缀。
+    """
+    if not flow:
+        return ()
+    names = {flow}
+    try:
+        import flow_registry                                  # 延迟导入：失败回路要在半坏机器上也能跑
+        for short, target in (flow_registry.load_doc().get('aliases') or {}).items():
+            if target == flow:
+                names.add(short)
+    except Exception:                                         # noqa: BLE001
+        pass
+    return tuple(f'{n}__' for n in sorted(names, key=len, reverse=True))
+
+
+def _prefix(flow: str | None) -> str | None:
+    """兼容旧调用点：返回**最长**前缀（规范 id 优先）。"""
+    ps = _prefixes(flow)
+    return ps[0] if ps else None
+
+
+def case_prefixes(flow: str | None) -> tuple:
+    """**公开入口**：该流程在台账里可能出现的全部 caseId 前缀（规范 id + 指向它的旧短名）。
+
+    给"按前缀找该流程 case"的外部工具用（如 `scripts/flow_status_reconcile.py` 的对账）；
+    ⛔ 别在调用方自己拼 `<flow>__` —— 台账里写的是"当时那条流程叫什么"，只认规范前缀会让
+    历史 case **集体消失**（见 `_prefixes` 的说明）。
+    """
+    return _prefixes(flow)
+
+
+def pending(path: pathlib.Path, flow: str | None = None, now: int | None = None,
+            cooldown_min: int = 15, max_attempts: int = 3) -> list:
+    """未处置的失败清单（含分类/唤醒次数/冷却）。
+
+    判定：该 case 的**最后一次 failed** 之后，若没有任何处置事件（wake/retry/blocked/done）
+    ⇒ 仍未处置。
+    """
+    now = int(now if now is not None else time.time())
+    prefixes = _prefixes(flow)
+    events = [e for e in read(path)
+              if e.get('caseId') and (not prefixes or str(e['caseId']).startswith(prefixes))]
+
+    by_case: dict = {}
+    for e in events:
+        by_case.setdefault(str(e['caseId']), []).append(e)
+
+    out = []
+    for cid, evs in by_case.items():
+        evs.sort(key=lambda e: (e.get('ts') or 0))
+        failed = [e for e in evs if e.get('event') == 'failed']
+        if not failed:
+            continue
+        last = failed[-1]
+        ts = last.get('ts') or 0
+        after = [e for e in evs if (e.get('ts') or 0) >= ts and e.get('event') in HANDLED_EVENTS]
+        # 2026-09-18（用户实测"失败了没人管"）：`blocked` 过去被当成"已处置"⇒ 队列清空、
+        # 工作台也看不到 ⇒ 半成品残留这类"等人裁定"的票彻底消失。改为：
+        #   · blocked 之后**没有** failed_ack ⇒ 仍留在队列（标 awaitingAck，kind=needs_human ⇒ 只展示不唤醒）；
+        #   · 人工在工作台确认（ackCase ⇒ failed_ack）后才真正消案。
+        if after:
+            acked = [e for e in after if e.get('event') != 'blocked']
+            if not acked and any(e.get('event') == 'blocked' for e in after):
+                pass          # 落到下面：作为"待人工确认"入队
+            else:
+                continue
+        wakes = [e for e in evs if e.get('event') == 'wake']
+        last_wake = max([w.get('ts') or 0 for w in wakes], default=0)
+        cool = max(0, cooldown_min * 60 - (now - last_wake)) if last_wake else 0
+        attempt = last.get('attempt') or len(failed)
+        cls = classify(last.get('error') or '', attempt, max_attempts)
+        awaiting = bool(after) and all(e.get('event') == 'blocked' for e in after)
+        out.append({
+            'caseId': cid,
+            'attempt': attempt,
+            'error': cls['error'],
+            'ts': ts,
+            'phase': last.get('phase'),
+            # 已判 blocked 但**人工未确认**（failed_ack）⇒ 只展示、不唤醒（kind=needs_human）
+            'kind': 'needs_human' if awaiting else cls['kind'],
+            'awaitingAck': awaiting,
+            'reason': ('已判 blocked、等人工确认（未 failed_ack）⇒ 不唤醒角色' if awaiting else cls['reason']),
+            'wakeCount': len(wakes),
+            'cooldownLeftSec': cool,
+        })
+    out.sort(key=lambda x: (-(x['ts'] or 0)))
+    return out
+
+
+def canonical_reason(error_text: str) -> str:
+    """台账 `failed.error` → **规范失败原因**（表备注与账本 blocked 的同源同文口径）。
+
+    台账里的 `failed.error` 形如 `[rec=<id>] [sku=<…>] [store=<…>] <err_type> <失败原因>`
+    （身份前缀是缺陷⑯ 为"摘要自证属于哪张票"加的，见 orchestrator._ledger_record_full_failure）。
+    本函数把**身份前缀剥掉**，剩下的就是引擎写给**表备注**的同一串原因（`orchestrator._fail_note`
+    里的 `<原因>` 部分）⇒ 角色/运维写 `blocked` 时**逐字**用它，就不会再出现
+    "表里写『未找到 Vehículo 运输选项』、账本写『平台无预约时段』"这种两处口径不一致
+    （生产实测 79096447 的误导就是这样产生的：账本那句是**模型对页面的解读**，不是引擎的判据）。
+    """
+    text = str(error_text or '').strip()
+    # 剥身份前缀：`[rec=…]`、`[sku=…]`、`[store=…]`（可能缺项，只剥**开头连续**的那些）
+    while text.startswith('['):
+        end = text.find(']')
+        if end <= 0 or '=' not in text[:end]:
+            break
+        text = text[end + 1:].lstrip()
+    return text
+
+
+def reasons(path: pathlib.Path, case_id: str, flow: str | None = None) -> dict:
+    """取某 case 的**规范失败原因**（= 引擎写进表备注的同一串，逐字）。
+
+    优先读引擎单列的 `reason` 字段（2026-10-09 起写入，与表备注同源同文）；老台账没这个字段
+    ⇒ 回落到 `error` 去掉身份前缀（`canonical_reason`，也是同一句话，只是还带着 err_type 前缀）。
+
+    找不到该 case / 没有 failed 事件 ⇒ `{'ok': False, 'reason': ''}`（调用方据此**照实说
+    "取不到规范原因"**，⛔ 不要自己编一句顶上 —— 生产实测 79096447 的误导正是"自己解读"造成的）。
+    `case_id` 可给全（`<flow>__<ticket>`）或只给 ticket（给了 `flow` 就自动补前缀）。
+    """
+    cid = str(case_id or '').strip()
+    if flow and cid and '__' not in cid:
+        cid = f'{flow}__{cid}'
+    if not cid:
+        return {'ok': False, 'case_id': '', 'reason': '', 'why': '需要 --case <caseId|ticket>'}
+    evs = [e for e in read(path) if str(e.get('caseId') or '') == cid and e.get('event') == 'failed']
+    if not evs:
+        return {'ok': False, 'case_id': cid, 'reason': '',
+                'why': f'台账里没有 {cid} 的 failed 事件（先确认票号/流程前缀）'}
+    evs.sort(key=lambda e: (e.get('ts') or 0))
+    last = evs[-1]
+    reason = str(last.get('reason') or '').strip() or canonical_reason(last.get('error') or '')
+    return {'ok': True, 'case_id': cid, 'reason': reason,
+            'errType': str(last.get('errType') or ''),
+            'source': 'reason' if str(last.get('reason') or '').strip() else 'error(去身份前缀)',
+            'attempt': last.get('attempt'), 'ts': last.get('ts'), 'phase': last.get('phase')}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='失败分类 / 未处置失败扫描 / 规范失败原因')
+    ap.add_argument('--error', help='一段失败文本（分类用）')
+    ap.add_argument('--attempt', type=int)
+    ap.add_argument('--max-attempts', type=int, default=3)
+    ap.add_argument('--scan', action='store_true', help='扫描台账里未处置的失败')
+    ap.add_argument('--flow', help='只看该流程（caseId 前缀）')
+    ap.add_argument('--case', dest='case', help='取该 case 的**规范失败原因**（写账本 blocked 时逐字用）')
+    ap.add_argument('--ops-message', action='store_true',
+                    help='把 --error 组成**运营可见文案**（结论+动作；表字段与台账的同一串）')
+    ap.add_argument('--missing', help='逗号分隔的缺口字段名（业务类动作用它写"补齐 X 后…"）')
+    ap.add_argument('--release-only', action='store_true',
+                    help='只打印该流程的放行位与运营动作提示（诊断用）')
+    ap.add_argument('--limit', type=int, default=OPS_REASON_LIMIT, help='文案长度上限（默认 300 = 台账 detail 上限）')
+    ap.add_argument('--ledger', default=str(DEFAULT_LEDGER))
+    ap.add_argument('--cooldown-min', type=int, default=15)
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--patterns', action='store_true', help='打印实际生效的分类规则（供门禁比对）')
+    a = ap.parse_args(argv)
+
+    if a.patterns:
+        # 门禁用：打印**实际生效**的分类规则（注册表优先，离线时是内置兜底）
+        print(json.dumps(EFFECTIVE, ensure_ascii=False, indent=2) if a.json else json.dumps(EFFECTIVE, ensure_ascii=False))
+        return 0
+
+    if a.release_only:
+        rc = release_config(a.flow or '')
+        print(json.dumps(rc, ensure_ascii=False, indent=2) if a.json
+              else f"  {a.flow or '(缺 --flow)'}｜放行位 {rc['field'] or '(无)'}｜重跑 {'开' if rc['enabled'] else '未开'}"
+                   f"｜上限 {rc['maxPerCase'] or '-'} 次｜冷却 {rc['cooldownMin'] or '-'} 分｜提示 {rc['hint'] or '(空)'}")
+        return 0
+
+    if a.ops_message:
+        if not a.error:
+            print('需要 --error（原始失败原因；⛔ 不要给空串 —— 正是缺陷 B 的现场）', file=sys.stderr)
+            return 2
+        miss = [x.strip() for x in str(a.missing or '').split(',') if x.strip()]
+        msg = ops_message(a.flow or '', a.error, missing=miss,
+                          kind=classify(a.error, a.attempt, a.max_attempts).get('kind'), limit=a.limit)
+        print(json.dumps({'flow': a.flow, 'category': ops_category(a.error),
+                          'message': msg, 'len': len(msg)}, ensure_ascii=False, indent=2) if a.json else msg)
+        return 0
+
+    if a.case:
+        # 口径统一的**取数口**：账本 blocked 的 --error 必须逐字用本命令的输出
+        # （⛔ 不许改写/翻译/加自己的解读 —— 生产实测就是"解读"把运维带偏的）。
+        r = reasons(pathlib.Path(a.ledger), a.case, a.flow)
+        if a.json:
+            print(json.dumps(r, ensure_ascii=False, indent=2))
+        elif r['ok']:
+            print(r['reason'])
+        else:
+            print(f"（取不到规范原因：{r['why']}）", file=sys.stderr)
+        return 0 if r['ok'] else 2
+
+    if a.scan:
+        items = pending(pathlib.Path(a.ledger), a.flow, cooldown_min=a.cooldown_min,
+                        max_attempts=a.max_attempts)
+        if a.json:
+            print(json.dumps({'flow': a.flow, 'pending': items}, ensure_ascii=False, indent=2))
+        else:
+            if not items:
+                print('  无未处置失败')
+            for it in items:
+                print(f"  {it['caseId']}  attempt={it['attempt']}  {it['kind']}  "
+                      f"唤醒×{it['wakeCount']}  冷却{it['cooldownLeftSec']}s  {it['error'][:60]}")
+        return 0
+
+    if not a.error:
+        print('需要 --error（分类）或 --scan（扫描）', file=sys.stderr)
+        return 2
+    cls = classify(a.error, a.attempt, a.max_attempts)
+    if a.json:
+        print(json.dumps(cls, ensure_ascii=False))
+    else:
+        print(f"  {cls['kind']}｜{cls['reason']}")
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())