@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_write_verify.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""flow_write_verify —— **幂等写步骤的「失败前核验」纯判据**（步骤 3 / 4 / 8）。
+
+## 为什么需要它（2026-10-09 生产实测，本模块的出生理由）
+
+货件 **79191341**（record `recvvgPQgoBScO`）：引擎步骤8 报
+`selector_not_found 预约失败：取消预约**未执行**（3/3 次未出现 Cancelar reserva 按钮…）`，
+现场其实是**平台错误页**（`Algo salió mal`）⇒ 按钮渲染不出来 ⇒ 判"没点到"。
+而只读复核显示：`status=Reserva cancelada`、`appointment` 为空、标签+箱唛已上传
+⇒ **取消确实已生效**（幂等成立），台账被人工纠正为 `done`，而表里仍是 `FULL状态=失败`。
+
+⇒ 结论：**幂等写步骤的失败判定必须先核验真相**。本模块就是那层判据：
+把「只读真相来源」变成**三态结论**，任何一处都**不可能**因为"核验本身出问题"而判成功。
+
+## 三态（**唯一口径**，调用方只认这三个值）
+
+| 值 | 含义 | 调用方该做什么 |
+|---|---|---|
+| `effective` | 只读证据**明确**显示该写操作其实已生效（幂等/续传） | **判成功**（⛔ 不产生 failed 事件），台账/备注写"报错但已核验生效（幂等）"+证据来源 |
+| `not_effective` | 只读证据**明确否定**（预约仍在/没取消/没有货件号） | **保持现在的失败路径与文案**（逐字不变） |
+| `unavailable` | 真相**取不到/不确定**（探针不可用、页面残缺、超时、两源皆 null） | **保守**：仍判失败，但文案里必须写明「核验不可用（原因）」 |
+
+⛔ **铁律（有回归钉住）**：`unavailable` **永远不是** `effective`；核验函数**抛异常**也**永远**是
+`unavailable`（见 `run()`）——"因为核验失败就当作成功"是本模块**明确禁止**的形态。
+
+## 判据表（逐条对应实现；来源全部**复用既有读取路径**，⛔ 不新造）
+
+| 步骤 | 只读真相来源 | 判 `effective` | 判 `not_effective` | 判 `unavailable` |
+|---|---|---|---|---|
+| 3 建单 | 页面货件号（`resolve_shipment_id`，既有逻辑）+ 表内货件号 | 任一非空（续传语义：已有号 ⇒ 不重建） | 探针可用 ∧ 两处都没有号 | 页面探针不可用 ∧ 表内也没有号 |
+| 4 预约 | 列表页 Shipment 行（与 `query_runner.py --mode shipment` **同一读取路径**：`INBOUNDS_URL?query=<号>` + `JS_EXTRACT_SHIPMENTS`） | `appointment` 非空（幂等：已预约就不重复预约） | 行取到 ∧ `appointment` 为空 | 行取不到 / 读取报错 / 字段残缺 |
+| 8 取消预约 | ① hub-v2 探针（`ml_hub_status.parse_hub_dump` 的 `appointment_cancelled`）② 列表页 `status` / `appointment` | hub `true` **或** 列表 `status=Reserva cancelada` **或** 列表 `appointment` 为空（任一为真） | hub **硬反证**（`Cancelar reserva` 仍在/改期入口在）**或** 列表 `appointment` 非空 | 两源都判不了（探针不可用 / 页面残缺 / 字段空） |
+
+### 步骤8 的**反证优先**（与 `ml_hub_status._appointment_cancelled` 同一条纪律）
+
+`ml_hub_status` 的模块 docstring 写明："反证优先 ⇒ `false` 压过一切正证据"。
+本模块**沿用**该纪律：hub 给出**硬反证**（判据 ∈ `HUB_ALIVE_JUDGES`：预约卡上仍有取消按钮/
+改期入口/明确"预约还活着"的文案）时，即使列表页说已取消，也判 `not_effective`
+—— 两源冲突时**以"预约还活着"为准**（⛔ 绝不把真失败洗白）。冲突事实进 `evidence`，运维可复核。
+
+## 分层（与 `ml_hub_status.py` 同构）
+
+- **纯判据（本文件 100%）**：只吃**证据 dict**、只吐结论；无浏览器、无网络、无宿主依赖（只有 stdlib）
+  ⇒ 可用纯夹具做回归（`scripts/tests/prefail-verify.test.py`）。
+- **取证据**（薄壳，在 `orchestrator.py`）：`_verify_write_step()` 只负责"只读导航 + evaluate"，
+  判据一律回落到本模块 —— ⛔ 别在编排器里再写一份 if/else 判据。
+
+## CLI（离线，不需要浏览器；供人工复核与门禁）
+
+    python3 scripts/flow_write_verify.py --step 8 --fixture cancelled-by-list
+    python3 scripts/flow_write_verify.py --step 8 --hub-file h.json --row-file r.json --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import re
+import sys
+from typing import Any, Callable, Optional
+
+# ────────────────────────────────────────────────
+# 三态常量（**唯一口径**；⛔ 不要在别处再写字符串字面量）
+# ────────────────────────────────────────────────
+VERDICT_EFFECTIVE = "effective"
+VERDICT_NOT_EFFECTIVE = "not_effective"
+VERDICT_UNAVAILABLE = "unavailable"
+VERDICTS = (VERDICT_EFFECTIVE, VERDICT_NOT_EFFECTIVE, VERDICT_UNAVAILABLE)
+
+STEPS = (3, 4, 8)
+STEP_TITLES = {3: "步骤3 建单", 4: "步骤4 预约", 8: "步骤8 取消预约"}
+# 判成功时写进备注/台账的**真相短语**（与 `STEP_TITLES` 一起构成唯一措辞的一环）
+TRUTH_LABELS = {
+    (3, VERDICT_EFFECTIVE): "已有货件号",
+    (4, VERDICT_EFFECTIVE): "已预约",
+    (8, VERDICT_EFFECTIVE): "已取消",
+}
+
+# 列表页 `status` 的**取消**文案（确定性词表；与 `ml_hub_status` 的 `_APPT_CANCELLED_RE` 同族）。
+# ⚠️ 只用区分度高的词：`cancelad` 单独太宽（"cancelada" 可能出现在别的语境），故要求带
+# `reserva`/`cita` 主体，或 `sin reserva`（"没有预约"）。
+_LIST_CANCELLED_RE = re.compile(
+    r"reserva\s+cancelada|cita\s+cancelada|cancelaste\s+la\s+reserva|sin\s+reserva",
+    re.IGNORECASE)
+
+# hub 的**硬反证**判据名（预约明确还活着）——取自 `ml_hub_status._appointment_cancelled` 的
+# `(值, 判据名, …)` 返回值，逐字对齐；⛔ 别改这里的名字而不改那边。
+HUB_ALIVE_JUDGES = (
+    "cancel-button-present",
+    "appointment-alive-text",
+    "appointment-reschedule-affordance",
+)
+
+
+# ────────────────────────────────────────────────
+# 取值原语（全部**防御式**：畸形入参一律当"取不到"，⛔ 不抛异常）
+# ────────────────────────────────────────────────
+def _text(v: Any) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v).strip()
+
+
+def _one_line(v: Any, limit: int = 160) -> str:
+    """压成单行 + 截断（证据串要能进表备注/台账，⛔ 不能带换行）。"""
+    s = " ".join(_text(v).split())
+    return s[:limit] + ("…" if len(s) > limit else "")
+
+
+# ⛔ 2026-10-10 生产事故（**假成功**）：ML 列表页在"**没有预约**"时返回的字面量是 `"-"`
+#   （只读实测：未预约票 `appointment='-'`；已预约票 `appointment='11/octubre 2026, 13:00 hs…'`）。
+#   旧实现只看"非空" ⇒ `-` 被当成已预约 ⇒ 步骤4 报错后被判 success，**表里标完成 + 发了完成卡**，
+#   而货件其实一张预约都没有。⇒ 一切"空值占位符"必须归一为空串。
+_APPT_EMPTY_TOKENS = {"-", "--", "—", "–", "n/a", "na", "none", "null", "sin cita", "sin reserva"}
+
+
+def _row_appointment(row: Any) -> str:
+    """列表页 `appointment` 的**有无判据**（唯一实现）：`-`/`—`/空/none… 一律视为"无预约"。"""
+    s = _one_line((row or {}).get("appointment")) if isinstance(row, dict) else ""
+    return "" if s.strip().lower() in _APPT_EMPTY_TOKENS else s
+
+
+# ⛔ **第二道假成功闸门**（2026-10-10，紧接上面那次占位符事故）：一次**真实预约**的 `appointment`
+#   **必带数字**（日期/时间，实测形态 `11/octubre 2026, 13:00 hs…`）。判"已预约"时**要求含数字**：
+#   平台改版/新文案带来的**未知占位符**（如 `Programada`、`Pendiente de confirmar`）一律**不算已预约**
+#   ⇒ 走**保守失败**（⛔ 宁可让人复核，也绝不表标完成）。
+#   ⚠️ 方向刻意不对称：本闸门只收紧"**判成功**"（步骤4）；步骤8 的"预约仍在"反证仍按
+#   `_row_appointment()` 的非空判断（未知值 ⇒ 当作"仍在" ⇒ 判失败）——两个方向都朝"失败"偏。
+_APPT_DIGIT_RE = re.compile(r"\d")
+
+
+def _row_appointment_booked(row: Any) -> str:
+    """**只有"确实像一次真实预约"时才返回非空**（步骤4 判"已预约"的唯一入口）。
+
+    判据 = `_row_appointment()` 归一后非空 ∧ 含数字。⛔ 未知占位符 ⇒ 空 ⇒ 不判成功。
+    """
+    s = _row_appointment(row)
+    return s if s and _APPT_DIGIT_RE.search(s) else ""
+
+
+def _row_status(row: Any) -> str:
+    return _one_line((row or {}).get("status")) if isinstance(row, dict) else ""
+
+
+def _hub_flag(hub: Any) -> Optional[bool]:
+    """hub 的 `appointment_cancelled` 三态（`True`/`False`/`None`）。
+
+    ⛔ 只认**真布尔**：字符串 `"true"`/`"false"` 一律当"判不了"（页面解析产物必须已是布尔，
+    宽松解析会把"拿不到"读成"没取消/已取消"，两个方向都危险）。探针无效（`probe_ok=False`）
+    同样当"判不了"。
+    """
+    if not isinstance(hub, dict):
+        return None
+    if not hub.get("probe_ok"):
+        return None
+    v = hub.get("appointment_cancelled")
+    return v if isinstance(v, bool) else None
+
+
+def _hub_judge(hub: Any) -> str:
+    if not isinstance(hub, dict):
+        return ""
+    return _one_line(((hub.get("signals") or {}) if isinstance(hub.get("signals"), dict) else {})
+                     .get("appointment_cancelled_by"), 60)
+
+
+def _hub_alive_hard(hub: Any) -> bool:
+    """hub 的 `appointment_cancelled=False` 是不是**硬反证**（预约明确还活着）。"""
+    return _hub_flag(hub) is False and _hub_judge(hub) in HUB_ALIVE_JUDGES
+
+
+def _result(verdict: str, why: str, evidence: list, sources: list, data: Any = None) -> dict:
+    """统一结论形状（`verdict` 一定是三态之一；`evidence`/`sources` 供收口文案逐字引用）。
+
+    `data` = **结构化事实**（调用方要据此改状态时用，例如步骤3 核验出的货件号 ⇒ 必须落表，
+    否则下一步又回到"没有货件号"）。⛔ 它只为 `effective` 服务，判失败时不带任何事实。
+    """
+    if verdict not in VERDICTS:                                  # 防御：非法值 ⇒ 保守
+        verdict, why = VERDICT_UNAVAILABLE, f"非法结论 {verdict!r} ⇒ 按不可用保守处理"
+    return {
+        "verdict": verdict,
+        "effective": verdict == VERDICT_EFFECTIVE,
+        "why": _one_line(why, 240),
+        "evidence": [e for e in (_one_line(x, 200) for x in (evidence or [])) if e],
+        "sources": [s for s in (_one_line(x, 80) for x in (sources or [])) if s],
+        "data": dict(data) if isinstance(data, dict) and verdict == VERDICT_EFFECTIVE else {},
+    }
+
+
+# ────────────────────────────────────────────────
+# 各步判据
+# ────────────────────────────────────────────────
+def verify_step3(*, table_shipment_id: Any = "", page_shipment_id: Any = "",
+                 page_from_url: bool = False, probe_ok: bool = True,
+                 probe_error: Any = "") -> dict:
+    """步骤3（建单）：**已有货件号 ⇒ 不是失败**（续传语义，⛔ 不重建）。
+
+    - `table_shipment_id` = 表内「货件号」（行里已有 ⇒ 本来就会跳过步3，这里是二次兜底）；
+    - `page_shipment_id` = **既有取号逻辑**（`orchestrator.resolve_shipment_id`，URL `/inbounds/` 优先、
+      `/plans/` 计划号永不采信）在**失败后现取**的结果（⑮ 竞态：页面其实已跳 hub 却报了失败）；
+    - `page_from_url` = 该号是否**来自 URL 的 `/inbounds/<号>`**（既有逻辑的**最高优先级**来源）。
+      ⛔ 只有它为真时页面号才算数：标题/正文兜底可能命中**列表文案里的别的号**（与缺陷⑰
+      "把计划号当货件号"同族）⇒ 宁可判"拿不准"，也不拿一个未经 URL 确认的号去判成功。
+    - `probe_ok=False` = 页面取号探针本身没跑成（evaluate 抛异常/页面已关）⇒ 只有表内号能救。
+    """
+    t_id, p_id = _text(table_shipment_id), _text(page_shipment_id)
+    if t_id:
+        return _result(VERDICT_EFFECTIVE, f"表内已有货件号 {t_id} ⇒ 续传语义（不重建）",
+                       [f"货件号={t_id}"], ["表内货件号"], {"shipment_id": t_id, "from": "table"})
+    if p_id and page_from_url:
+        return _result(VERDICT_EFFECTIVE, f"页面已产出货件号 {p_id} ⇒ 建单其实已生效",
+                       [f"货件号={p_id}", "来源：URL /inbounds/"], ["页面货件号（既有取号逻辑）"],
+                       {"shipment_id": p_id, "from": "page-url"})
+    if not probe_ok:
+        return _result(VERDICT_UNAVAILABLE,
+                       f"页面取号探针不可用（{_one_line(probe_error) or '未给出原因'}）∧ 表内无货件号",
+                       [], ["页面取号探针", "表内货件号"])
+    if p_id:
+        return _result(VERDICT_UNAVAILABLE,
+                       f"页面取到疑似号 {p_id} 但**未落到 URL /inbounds/**（可能只是列表文案里的号）"
+                       f"⇒ 判不了，按不可用保守处理",
+                       [], ["页面货件号（既有取号逻辑）", "表内货件号"])
+    return _result(VERDICT_NOT_EFFECTIVE, "页面与表内都没有货件号 ⇒ 建单确实没生效",
+                   ["货件号=（空）"], ["页面货件号（既有取号逻辑）", "表内货件号"])
+
+
+def verify_step4(*, shipment_row: Any = None, read_ok: bool = True,
+                 read_error: Any = "") -> dict:
+    """步骤4（预约）：**`appointment` 像一次真实预约 ⇒ 预约已成功**（幂等，⛔ 不重复预约）。
+
+    真相来源 = 列表页 Shipment 行，与 `query_runner.py --mode shipment` **同一读取路径**
+    （`INBOUNDS_URL?query=<号>` + `JS_EXTRACT_SHIPMENTS`）⇒ 复用，不新造。
+    ⛔ "非空"**不等于**"已预约"：空占位符（`-` 等）与未知文案都要排除（见 `_row_appointment_booked`）。
+    """
+    if not read_ok or not isinstance(shipment_row, dict):
+        return _result(VERDICT_UNAVAILABLE,
+                       f"列表页读取不可用（{_one_line(read_error) or '查不到该货件号'}）⇒ 预约状态无法核验",
+                       [], ["列表页 Shipment 行"])
+    appt, status = _row_appointment(shipment_row), _row_status(shipment_row)
+    booked = _row_appointment_booked(shipment_row)
+    if booked:
+        return _result(VERDICT_EFFECTIVE, f"列表页 appointment={booked} ⇒ 预约已成功（幂等）",
+                       [f"appointment={booked}", f"status={status}"], ["列表页 Shipment 行"])
+    shown = appt or "（空/占位符）"
+    why = (f"列表页 appointment={shown}（**不像真实预约**：无日期数字 ⇒ 不算已预约；"
+           f"status={status or '空'}）⇒ 预约未生效") if appt else \
+          f"列表页 appointment 为空（status={status or '空'}）⇒ 预约未生效"
+    return _result(VERDICT_NOT_EFFECTIVE, why,
+                   [f"appointment={shown}", f"status={status}"], ["列表页 Shipment 行"])
+
+
+def verify_step8(*, hub: Any = None, shipment_row: Any = None, list_ok: bool = True,
+                 list_error: Any = "", hub_error: Any = "") -> dict:
+    """步骤8（取消预约）：**hub 或列表页任一为真 ⇒ 取消已生效 ⇒ 判成功**。
+
+    ⛔ 反证优先：hub **硬反证**（预约卡仍有取消按钮/改期入口）⇒ `not_effective`，
+    即便列表页说已取消（两源冲突以"预约还活着"为准；冲突进 `evidence` 供复核）。
+    """
+    evidence, sources, positives, negatives, unknowns = [], [], [], [], []
+
+    # ── ① hub-v2 探针 ──────────────────────────────
+    if not isinstance(hub, dict) or not hub.get("probe_ok"):
+        why = _one_line(hub_error) or ("hub-v2 探针未运行" if hub is None else "hub-v2 页面残缺（probe_ok=false）")
+        unknowns.append(f"hub-v2 不可用（{why}）")
+        sources.append("hub-v2 探针")
+    else:
+        sources.append("hub-v2 探针")
+        flag, judge = _hub_flag(hub), _hub_judge(hub)
+        tag = f"hub-v2 appointment_cancelled={_text(flag)}" + (f"（判据 {judge}）" if judge else "")
+        if flag is True:
+            positives.append(tag)
+            evidence.append(f"{tag} ⇒ 已取消")
+        elif flag is False:
+            negatives.append(tag)
+            evidence.append(f"{tag} ⇒ 预约仍有效" if judge in HUB_ALIVE_JUDGES else f"{tag} ⇒ 环节未结束")
+        else:
+            unknowns.append(f"hub-v2 appointment_cancelled=null（判不了，判据 {judge or '无'}）")
+
+    # ── ② 列表页 ───────────────────────────────────
+    row_ok = bool(list_ok) and isinstance(shipment_row, dict)
+    if not row_ok:
+        unknowns.append(f"列表页不可用（{_one_line(list_error) or '查不到该货件号'}）")
+        sources.append("列表页 Shipment 行")
+    else:
+        sources.append("列表页 Shipment 行")
+        appt, status = _row_appointment(shipment_row), _row_status(shipment_row)
+        if _LIST_CANCELLED_RE.search(status):
+            positives.append(f"列表页 status={status}")
+            evidence.append(f"列表页 status={status} ⇒ 已取消")
+        elif appt:
+            negatives.append(f"列表页 appointment={appt}（预约仍在）")
+            evidence.append(f"列表页 appointment={appt} ⇒ 预约仍在")
+        elif status:
+            # 有 status 但预约列为空 ⇒ 没有生效中的预约 = 取消（或不曾预约）目标已达成（幂等）
+            positives.append(f"列表页 appointment 为空（status={status}）")
+            evidence.append(f"列表页 appointment 为空（status={status}）⇒ 无生效中预约")
+        else:
+            unknowns.append("列表页字段残缺（status 与 appointment 皆空）⇒ 判不了")
+
+    # ── ③ 汇总（⛔ 反证优先；unknown 永远不升级为 success）──
+    if _hub_alive_hard(hub):
+        conflict = f"；⚠️ 与列表页证据冲突（{'；'.join(positives)}）" if positives else ""
+        return _result(VERDICT_NOT_EFFECTIVE,
+                       f"hub-v2 反证：{_hub_judge(hub)} ⇒ 预约仍有效{conflict}",
+                       evidence, sources)
+    if positives:
+        return _result(VERDICT_EFFECTIVE,
+                       f"已核验取消生效（{'；'.join(positives)}）", evidence, sources)
+    if negatives:
+        return _result(VERDICT_NOT_EFFECTIVE,
+                       f"核验明确否定：{'；'.join(negatives)} ⇒ 取消未生效", evidence, sources)
+    return _result(VERDICT_UNAVAILABLE,
+                   "；".join(unknowns) or "两处真相都取不到", evidence, sources)
+
+
+VERIFIERS: dict[int, Callable[..., dict]] = {3: verify_step3, 4: verify_step4, 8: verify_step8}
+
+
+def run(step: int, *args: Any, **kwargs: Any) -> dict:
+    """**永不抛**包装：核验函数抛异常 ⇒ `unavailable`（⛔ 绝不当成功；有回归钉住）。
+
+    为什么需要它（而不是让调用方 try/except）：核验本身出问题（选择器变了、探针超时、
+    证据 dict 畸形）在**任何**调用点都**只能是"判不了"**。把这条纪律钉在一个函数里，
+    就不会出现"某条路径忘了 try ⇒ 异常冒泡被上层当成功"的形态。
+    """
+    fn = VERIFIERS.get(int(step))
+    if fn is None:
+        return _result(VERDICT_UNAVAILABLE, f"步骤{step} 没有核验器（只有 {sorted(VERIFIERS)}）", [], [])
+    try:
+        out = fn(*args, **kwargs)
+    except Exception as exc:                                     # noqa: BLE001  —— 见 docstring
+        return _result(VERDICT_UNAVAILABLE,
+                       f"核验过程异常（{type(exc).__name__}: {_one_line(exc, 120)}）⇒ 按不可用保守处理",
+                       [], [])
+    if not isinstance(out, dict):
+        return _result(VERDICT_UNAVAILABLE, f"核验返回非 dict（{type(out).__name__}）⇒ 按不可用保守处理", [], [])
+    # ⚠️ 必须把 `data` 一起收敛：它是"判成功后调用方要据此改状态"的结构化事实
+    #    （步骤3 核验出的货件号 ⇒ 要落表，否则下一轮又回到"没有货件号 ⇒ 重建"）。
+    return _result(str(out.get("verdict") or ""), str(out.get("why") or ""),
+                   list(out.get("evidence") or []), list(out.get("sources") or []),
+                   out.get("data"))
+
+
+def is_effective(verdict: Any) -> bool:
+    """**判成功的唯一入口**：只认 `effective` **且**证据串非空（空证据不算核验过）。"""
+    if not isinstance(verdict, dict):
+        return False
+    return (str(verdict.get("verdict") or "") == VERDICT_EFFECTIVE
+            and bool(verdict.get("evidence")))
+
+
+def unavailable(why: Any) -> dict:
+    """构造一个 `unavailable` 结论（核验模块缺失/取证据异常/返回畸形时的**唯一**兜底）。
+
+    ⛔ 存在的意义就是"没有第二条路能产出 `effective`"：调用方拿不到结论时只能调它。
+    """
+    return _result(VERDICT_UNAVAILABLE, _text(why) or "核验不可用（未给出原因）", [], [])
+
+
+def truth_label(step: int, verdict: Any) -> str:
+    """判成功时的真相短语（`已有货件号`/`已预约`/`已取消`）——进备注串，**单一实现**。"""
+    v = str((verdict or {}).get("verdict") if isinstance(verdict, dict) else verdict or "")
+    return TRUTH_LABELS.get((int(step), v), "已生效")
+
+
+def evidence_line(verdict: Any) -> str:
+    """证据来源串（进备注/台账：hub-v2 的哪一项 / 列表页 status）——**单一实现**。"""
+    if not isinstance(verdict, dict):
+        return ""
+    parts = [str(x) for x in (verdict.get("evidence") or []) if str(x).strip()]
+    return "；".join(parts)
+
+
+# ────────────────────────────────────────────────
+# 内置夹具（纯离线；供 CLI 演示与回归共用判据）
+# ────────────────────────────────────────────────
+# ⚠️ 夹具里的 hub dict 用**真机形态**的字段（`probe_ok` / `appointment_cancelled` / `signals`），
+# 与 `ml_hub_status.parse_hub_dump()` 的产物同形 ⇒ 夹具与真机走**同一条判据**。
+FIXTURES: dict[str, dict] = {
+    # 本现场复刻（79191341）：平台错误页 ⇒ 按钮找不到 ⇒ 脚本报失败；而真相是「已取消」。
+    "cancelled-by-list": {
+        "step": 8,
+        "hub": {"probe_ok": True, "appointment_cancelled": None,
+                "signals": {"appointment_cancelled_by": "appointment-region-missing"}},
+        "shipment_row": {"id": "79191341", "appointment": "", "status": "Reserva cancelada"},
+        "expect": VERDICT_EFFECTIVE,
+    },
+    "cancelled-by-hub": {
+        "step": 8,
+        "hub": {"probe_ok": True, "appointment_cancelled": True,
+                "signals": {"appointment_cancelled_by": "cancelled-text"}},
+        "shipment_row": None,
+        "list_error": "列表页读取超时",
+        "expect": VERDICT_EFFECTIVE,
+    },
+    "appointment-still-alive": {
+        "step": 8,
+        "hub": {"probe_ok": True, "appointment_cancelled": False,
+                "signals": {"appointment_cancelled_by": "cancel-button-present"}},
+        "shipment_row": {"id": "79191341", "appointment": "2026-10-12 14:00", "status": "Reserva programada"},
+        "expect": VERDICT_NOT_EFFECTIVE,
+    },
+    "probe-unusable": {
+        "step": 8, "hub": None, "hub_error": "store_busy", "shipment_row": None,
+        "list_error": "页面残缺", "expect": VERDICT_UNAVAILABLE,
+    },
+    "appointment-booked": {
+        "step": 4,
+        "shipment_row": {"id": "79191341", "appointment": "2026-10-12 14:00-16:00", "status": "Reserva programada"},
+        "expect": VERDICT_EFFECTIVE,
+    },
+    "appointment-missing": {
+        "step": 4,
+        "shipment_row": {"id": "79191341", "appointment": "", "status": "Pendiente de agendar"},
+        "expect": VERDICT_NOT_EFFECTIVE,
+    },
+    "resume-shipment": {
+        "step": 3, "table_shipment_id": "79191341", "expect": VERDICT_EFFECTIVE,
+    },
+    "no-shipment": {
+        "step": 3, "page_shipment_id": "", "probe_ok": True, "expect": VERDICT_NOT_EFFECTIVE,
+    },
+}
+
+
+def run_fixture(name: str) -> dict:
+    """跑内置夹具（离线；返回 `{'name','step','verdict','expect','pass'}`）。"""
+    f = dict(FIXTURES.get(name) or {})
+    if not f:
+        raise KeyError(name)
+    step = int(f.pop("step"))
+    expect = f.pop("expect", "")
+    got = run(step, **f)
+    return {"name": name, "step": step, "verdict": got["verdict"], "expect": expect,
+            "pass": got["verdict"] == expect, "why": got["why"], "evidence": got["evidence"]}
+
+
+def _load_json_arg(path: str) -> Any:
+    if not path:
+        return None
+    if path == "-":
+        return json.loads(sys.stdin.read() or "{}")
+    return json.loads(pathlib.Path(path).read_text(encoding="utf-8"))
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    ap = argparse.ArgumentParser(description="幂等写步骤的失败前核验（纯判据，离线）")
+    ap.add_argument("--step", type=int, choices=list(VERIFIERS))
+    ap.add_argument("--fixture", help="跑内置夹具（" + "、".join(FIXTURES) + "）")
+    ap.add_argument("--table-shipment-id", default="", help="步骤3：表内货件号")
+    ap.add_argument("--page-shipment-id", default="", help="步骤3：页面现取的货件号")
+    ap.add_argument("--probe-ok", default="1", help="步骤3：页面取号探针是否跑成（0/1）")
+    ap.add_argument("--hub-file", help="hub 结论 JSON（ml_hub_status.parse_hub_dump 的产物）")
+    ap.add_argument("--row-file", help="列表页 Shipment 行 JSON")
+    ap.add_argument("--list-error", default="", help="列表页读取失败原因（取不到行时填）")
+    ap.add_argument("--hub-error", default="", help="hub 探针不可用原因")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    if a.fixture:
+        r = run_fixture(a.fixture)
+        print(json.dumps(r, ensure_ascii=False, indent=2) if a.json
+              else f"  {r['name']}｜step{r['step']}｜{r['verdict']}（期望 {r['expect']}）"
+                   + ("✅" if r["pass"] else "❌") + f"｜{r['why']}")
+        return 0 if r["pass"] else 1
+
+    if not a.step:
+        print("需要 --step 或 --fixture", file=sys.stderr)
+        return 2
+    kw: dict = {}
+    if a.step == 3:
+        kw = {"table_shipment_id": a.table_shipment_id, "page_shipment_id": a.page_shipment_id,
+              "probe_ok": a.probe_ok.strip() not in ("0", "false", "no")}
+    elif a.step == 4:
+        row = _load_json_arg(a.row_file)
+        kw = {"shipment_row": row, "read_ok": row is not None, "read_error": a.list_error}
+    else:
+        hub = _load_json_arg(a.hub_file)
+        row = _load_json_arg(a.row_file)
+        kw = {"hub": hub, "shipment_row": row, "list_ok": row is not None,
+              "list_error": a.list_error, "hub_error": a.hub_error}
+    out = run(a.step, **kw)
+    if a.json:
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    else:
+        print(f"  {STEP_TITLES.get(a.step, a.step)}｜{out['verdict']}｜{out['why']}")
+        if out["evidence"]:
+            print(f"  证据：{'；'.join(out['evidence'])}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())