@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/_engine_rules_probe.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""门禁用探针：打印引擎**生效的**网络类判据（P3）。
+
+为什么单独一个文件：`python3 -c` 传多行脚本在某些调用方式下会失败（实测门禁里报
+"Command failed" 而手工跑同一段却正常），而门禁**不允许静默跳过**。改成文件调用，
+参数传递不再有歧义；输出用 `__JSON__` 前缀标记，容忍 stdout 噪声。
+"""
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+import orchestrator as o  # noqa: E402
+
+print("__JSON__" + json.dumps(o._engine_network_rules()))

package/engine/scripts/analyze-full-day.py

@@ -0,0 +1,568 @@
+#!/usr/bin/env python3
+"""当日 FULL 归因报表 —— **只读、零网络、零写入**（FULL 自动路径成功率修复批，2026-10-10）。
+
+## 为什么需要它
+
+客户机 10-10 跑约 30 条 FULL，**约 1/3 失败**；同一天用 CLI 手动串行跑 6 票**全部 8/8 成功**。
+"为什么自动路径比手动差"必须能**一条命令答出来**，而不是靠人翻日志 —— 否则每轮都只能凭印象
+调参（本批的窗口默认值、仓容闸门正是这么定下来的）。本脚本就是那个"答出来"的口子。
+
+## 数据源（**只有两个本地文件**，⛔ 不联网、不读表、不写任何东西）
+
+| 源 | 默认路径 | 用途 |
+|---|---|---|
+| 统一台账 | `<数据目录>/flow-ledger.jsonl` | 当日 case 数 / 终态 / 小时×终态 / 店铺×终态 / 时间线 |
+| 失败诊断 | `<数据目录>/fulfillment-logs/failures.jsonl` | 失败原因分类 / 反事实三态（**页面证据在这里**） |
+
+数据目录走内核**唯一判据**（`scripts/lib/argent_datadir.py`，与编排器/CLI 同一份），
+⛔ 不在这里复制三级链。
+
+## 输出五段（每段都带**计数 + 证据来源**，可复算）
+
+```
+① 当日 case 数 / 终态分布（done / failed / blocked / 其他）
+② 失败原因分类计数（仓容满 ｜ 预约页形态异常 ｜ 步骤8 找不到取消按钮 ｜ 提交未跳转 hub-v2 ｜ 其他）
+③ 按小时 × 终态、按店铺 × 终态
+④ 反事实估算：若「窗口=<给定值> ∧ 仓容可用」⇒ 本可成功 / 仍会失败 / 证据不足（**三态，⛔ 不许猜**）
+⑤ 与「手动路径」对照的时间线（同一 case 的人工 done 事件 vs 自动 failed 事件）
+```
+
+## 口径（**逐条对应实现，改这条 = 改判据**）
+
+### 终态（①③）
+- 只看**当日**（`--date`，本地时区）的事件；台账 `ts` 是 epoch 秒。
+- **信息性事件不算状态**（与 `flow_triage.INFO_EVENTS` **同一口径**：`phase` / `wake` /
+  `policy_apply` / `policy_new`）⇒ 取当日最后一条**状态性**事件：
+  `done` ⇒ done；`failed` ⇒ failed；`blocked` / `failed_ack` ⇒ blocked；
+  `planned` / `dispatched` / `retry` / `requeued` / 无 ⇒ 其他。
+- 为什么不能只数事件：一张票一天可能 `failed` 3 次再 `done` —— 数事件会把"最终成功"报成失败。
+
+### 失败原因分类（②）
+判据是**失败文案里的标记串**（⛔ 不猜语义），逐条出自既有实现：
+
+| 桶 | 判据（正则，命中即归桶；**顺序即优先级**） | 出处 |
+|---|---|---|
+| 仓容满 | `capacity_full` / 平台原文片段（`liberar espacio` 等）/ `仓容满` / `库容满` | `scripts/ml_capacity_probe.py#PLATFORM_QUOTES`（**同一份**） |
+| 预约页形态异常 | `预约页形态异常` / `calendar_absent` | `orchestrator.APPT_FORM_ANOMALY` |
+| 步骤8 找不到取消按钮 | `Cancelar reserva` ∧ `未出现`/`未执行`/`找不到`，或 `cancel_button_not_found` | 步骤8 取消链 |
+| 提交未跳转 hub-v2 | `hub-v2` ∧ `未跳转`/`未生效`/`permancer`/`no redirig` | 步骤4 提交链 |
+| 其他 | 其余全部 | —— |
+
+### 反事实三态（④）—— **前提 = 窗口取 `--window` ∧ 仓容可用**
+对**每一条**失败记录（`failures.jsonl` 优先；台账 `failed` 作补充），按**当时的页面证据**判：
+
+| 结论 | 判据（**全部**条件都要满足） |
+|---|---|
+| `would_succeed` | 阻塞**唯一落在**两个轴上之一：① 仓容满（前提"仓容可用"直接消除该阻塞 ⇒ 前提即结论）② 顺延窗口耗尽（文案含 `已顺延到 平台今天+N 天`，且 `--window - 1 > N` ⇒ 更大窗口会继续往later 日期试） |
+| `would_fail` | 证据显示阻塞**不在**这两个轴上（页面形态 / 坏货件号 / CDP/网络 / 步骤8 取消按钮 / 数据缺口…）⇒ 前提消除不了它 |
+| `insufficient` | 证据缺失或不足（无文案 / 判不出属于哪条链 / 窗口类但**解析不出**当时试到第几天 ⇒ ⛔ 不许猜"更大窗口就能成"） |
+
+⛔ **三态不许猜**：`insufficient` 是一个**正常且必须存在**的结论（"证据不足" ≠ "会失败"）。
+
+### 时间线（⑤）
+同一 case 当日既有**自动 failed** 又有**人工 done** ⇒ 打印两条事件的时刻与文本
+（人工 done 的判据 = `event=done` ∧ `by` 不是引擎自己的 `orchestrator`）。
+
+## 用法
+
+    python3 scripts/analyze-full-day.py                          # 今天
+    python3 scripts/analyze-full-day.py --date 2026-10-10 --json
+    python3 scripts/analyze-full-day.py --ledger L --failures F --store 墨西哥-1店-子账号 --window 5
+
+退出码：0 正常（**即使当天 0 条 case 也是 0**，那是事实不是错误）；2 参数/源不可读。
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import pathlib
+import re
+import sys
+from typing import Any, Optional
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / "lib"))
+from argent_datadir import resolve_data_dir            # noqa: E402  数据目录唯一判据（勿复制链）
+
+# 仓容判据**同一份**（⛔ 不在这里再写一遍平台原文片段）
+try:
+    from ml_capacity_probe import ACTION_TEXT as _CAPACITY_ACTION        # noqa: E402
+    from ml_capacity_probe import CLASS_MARKER as _CAPACITY_MARKER       # noqa: E402
+    from ml_capacity_probe import DEFER_TAG as _CAPACITY_TAG             # noqa: E402
+    from ml_capacity_probe import PLATFORM_QUOTES as _PLATFORM_QUOTES    # noqa: E402
+except Exception:                                                        # noqa: BLE001
+    _CAPACITY_MARKER, _CAPACITY_TAG = "capacity_full", "仓容满"
+    _CAPACITY_ACTION = "需运营清低质库存腾库容"
+    _PLATFORM_QUOTES = ("liberar espacio",)
+
+DATA_DIR = pathlib.Path(resolve_data_dir()["dir"])
+DEFAULT_LEDGER = DATA_DIR / "flow-ledger.jsonl"
+DEFAULT_FAILURES = DATA_DIR / "fulfillment-logs" / "failures.jsonl"
+
+# ── 终态口径（与 flow_triage 同一份：信息性事件不算状态）──────────────────────
+INFO_EVENTS = ("phase", "wake", "policy_apply", "policy_new")
+STATE_BUCKETS = {
+    "done": "done",
+    "failed": "failed",
+    "blocked": "blocked",
+    "failed_ack": "blocked",
+}
+OTHER = "其他"
+
+# ── 失败原因分类（顺序即优先级；判据是**标记串**，⛔ 不猜语义）────────────────
+_QUOTE_RE = "|".join(re.escape(q) for q in _PLATFORM_QUOTES)
+BUCKET_CAPACITY = "仓容满"
+BUCKET_APPT_FORM = "预约页形态异常"
+BUCKET_STEP8_CANCEL = "步骤8 找不到取消按钮"
+BUCKET_HUBV2 = "提交未跳转 hub-v2"
+BUCKET_OTHER = "其他"
+BUCKET_ORDER = (BUCKET_CAPACITY, BUCKET_APPT_FORM, BUCKET_STEP8_CANCEL, BUCKET_HUBV2, BUCKET_OTHER)
+REASON_RULES = (
+    (BUCKET_CAPACITY, "capacity-full", re.compile(
+        rf"{re.escape(_CAPACITY_MARKER)}|{_QUOTE_RE}|{re.escape(_CAPACITY_TAG)}|库容满", re.I)),
+    (BUCKET_APPT_FORM, "appointment-form", re.compile(r"预约页形态异常|calendar_absent", re.I)),
+    (BUCKET_STEP8_CANCEL, "step8-cancel-button", re.compile(
+        r"(?:Cancelar reserva|cancel_button_not_found|取消预约).{0,40}?"
+        r"(?:未出现|未执行|找不到|按钮|not found|超时)", re.I)),
+    (BUCKET_HUBV2, "submit-no-hubv2", re.compile(
+        r"hub-v2.{0,30}?(?:未跳转|未生效|未到达|no redirig)|(?:未跳转|未生效).{0,20}?hub-v2", re.I)),
+)
+
+# ── 反事实前提里"阻塞在哪条链"的判据（**与上面同一批标记**，⛔ 不另写一套）──────
+WINDOW_EXHAUSTED_RE = re.compile(r"已顺延到\s*平台今天\+?(\d+)\s*天")
+WINDOW_AXIS_RE = re.compile(
+    r"可用时段不足|时段不足|hub-v2.{0,30}?(?:未跳转|未生效)|(?:未跳转|未生效).{0,20}?hub-v2"
+    r"|当前无可预约时段|无可用日|时段被平台拒", re.I)
+NON_AXIS_RE = re.compile(
+    r"预约页形态异常|calendar_absent|bad_shipment_id|取号错位|不可解析|"
+    r"未找到\s*Veh[íi]culo|CDP|ECONN|ETIMEDOUT|EAI_AGAIN|net::ERR|Target closed|"
+    r"browser has been closed|Cancelar reserva|取消预约|SKU.{0,40}在店铺|未授权|登录|"
+    # 代码级缺陷（我方缺陷类）同样落在前提之外：换窗口/腾库容都修不好它
+    r"object has no attribute|AttributeError|Traceback|TypeError|KeyError",
+    re.I)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 读源（**只读**；每行都带 `src` 与行号，保证结论可复算）
+# ══════════════════════════════════════════════════════════════════════════
+
+def read_jsonl(path: pathlib.Path) -> list:
+    """逐行读 JSONL，返回 `[{... , "_src": "<path>", "_line": N}]`（坏行跳过但计数）。"""
+    out: list = []
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return out
+    for i, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(d, dict):
+            continue
+        d["_src"], d["_line"] = str(path), i
+        out.append(d)
+    return out
+
+
+def ledger_date_of(ev: dict) -> str:
+    """台账事件日期（epoch → **本地**日期；与 failures.jsonl 的本地时间串同口径）。"""
+    ts = ev.get("ts")
+    try:
+        return dt.datetime.fromtimestamp(float(ts)).date().isoformat()
+    except (TypeError, ValueError, OSError, OverflowError):
+        return ""
+
+
+def failures_date_of(rec: dict) -> str:
+    """失败诊断日期（`YYYY-MM-DD HH:MM:SS` 前 10 位）。"""
+    return str(rec.get("ts") or "")[:10]
+
+
+STORE_IN_ERROR_RE = re.compile(r"\[store=([^\]]*)\]")
+
+
+def store_of(ev: dict) -> str:
+    """事件所属店铺：优先 `store` 字段，其次 `error` 里的 `[store=…]` 身份前缀。"""
+    s = str(ev.get("store") or "").strip()
+    if s:
+        return s
+    m = STORE_IN_ERROR_RE.search(str(ev.get("error") or ""))
+    return m.group(1).strip() if m else ""
+
+
+def case_of(ev: dict) -> str:
+    return str(ev.get("caseId") or "")
+
+
+def record_of(case_id: str) -> str:
+    """`full__<rec>` → `<rec>`（非 full case 原样返回）。"""
+    return case_id.split("__", 1)[1] if "__" in case_id else case_id
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 纯判据
+# ══════════════════════════════════════════════════════════════════════════
+
+def state_bucket(event: str) -> str:
+    """状态性事件 → 终态桶；信息性事件返回空串（**不算状态**）。"""
+    e = str(event or "")
+    if e in INFO_EVENTS:
+        return ""
+    return STATE_BUCKETS.get(e, OTHER)
+
+
+def classify_reason(text: str) -> tuple:
+    """失败文案 → 原因桶。返回 `(bucket, rule_id)`。"""
+    t = str(text or "")
+    for bucket, rid, pat in REASON_RULES:
+        if pat.search(t):
+            return bucket, rid
+    return BUCKET_OTHER, "none"
+
+
+def counterfactual(reason: str, window: int, *, extra_text: str = "") -> dict:
+    """反事实三态 —— **前提 = 窗口取 `window` ∧ 仓容可用**（判据表见模块 docstring）。
+
+    返回 `{verdict, axis, basis, observed_window}`；`verdict ∈ {would_succeed, would_fail, insufficient}`。
+    ⛔ 三态不许猜：解析不出"当时试到第几天"就判 `insufficient`，**不**默认"更大窗口就能成"。
+    """
+    t = f"{reason or ''} {extra_text or ''}".strip()
+    if not t:
+        return {"verdict": "insufficient", "axis": "none",
+                "basis": "无失败文案（证据缺失）", "observed_window": None}
+
+    # ① 仓容轴：前提"仓容可用"**直接消除**该阻塞 ⇒ 前提即结论
+    if REASON_RULES[0][2].search(t):
+        # 但若同一段证据里另有一条**不在前提射程内**的硬阻塞 ⇒ 前提消除不了它
+        if NON_AXIS_RE.search(t):
+            m = NON_AXIS_RE.search(t)
+            return {"verdict": "would_fail", "axis": "capacity+other",
+                    "basis": f"仓容是该条阻塞，但同时存在前提消除不了的硬阻塞「{m.group(0)}」",
+                    "observed_window": None}
+        return {"verdict": "would_succeed", "axis": "capacity",
+                "basis": f"阻塞唯一落在仓容轴：命中平台原文/`{_CAPACITY_MARKER}`；"
+                         f"前提「仓容可用」直接消除该阻塞", "observed_window": None}
+
+    # ② 顺延窗口轴：必须**同时**有"窗口耗尽"证据与"更大窗口能继续"的算术关系
+    if WINDOW_AXIS_RE.search(t):
+        if NON_AXIS_RE.search(t):
+            m = NON_AXIS_RE.search(t)
+            return {"verdict": "would_fail", "axis": "window+other",
+                    "basis": f"窗口类失败但同时存在前提消除不了的硬阻塞「{m.group(0)}」",
+                    "observed_window": None}
+        m = WINDOW_EXHAUSTED_RE.search(t)
+        if not m:
+            return {"verdict": "insufficient", "axis": "window",
+                    "basis": "窗口类失败，但文案里**没有**「已顺延到 平台今天+N 天」⇒ "
+                             "解析不出当时试到第几天（⛔ 不猜）", "observed_window": None}
+        n = int(m.group(1))
+        observed = n + 1
+        if window > observed:
+            return {"verdict": "would_succeed", "axis": "window",
+                    "basis": f"当时窗口耗尽于 平台今天+{n} 天（= 窗口 {observed}）；"
+                             f"给定窗口 {window} > {observed} ⇒ 会继续往更晚日期试",
+                    "observed_window": observed}
+        return {"verdict": "would_fail", "axis": "window",
+                "basis": f"当时窗口已试到 平台今天+{n} 天（= 窗口 {observed}），"
+                         f"给定窗口 {window} ≤ {observed} ⇒ 换窗口也够不到",
+                "observed_window": observed}
+
+    # ③ 非前提轴（页面形态/坏号/CDP/取消按钮…）⇒ 前提消除不了
+    if NON_AXIS_RE.search(t):
+        m = NON_AXIS_RE.search(t)
+        return {"verdict": "would_fail", "axis": "non-axis",
+                "basis": f"阻塞不在窗口/仓容两轴上（命中「{m.group(0)}」）⇒ 前提消除不了它",
+                "observed_window": None}
+
+    return {"verdict": "insufficient", "axis": "unknown",
+            "basis": "文案既不像仓容/窗口类、也没命中任何已知非前提轴 ⇒ 判不出（⛔ 不猜）",
+            "observed_window": None}
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 报表装配
+# ══════════════════════════════════════════════════════════════════════════
+
+def build_report(ledger: list, failures: list, *, date: str, store: str = "",
+                 window: int = 5) -> dict:
+    """纯函数：两份已读入的记录 + 参数 → 报表（**无 IO、无时间依赖**，可纯夹具回归）。"""
+    def _store_ok(s: str) -> bool:
+        return (not store) or (s == store)
+
+    # ── 当日事件（台账）────────────────────────────────────────────────────
+    day_events = [e for e in ledger
+                  if ledger_date_of(e) == date and _store_ok(store_of(e))]
+    by_case: dict[str, list] = {}
+    for e in day_events:
+        by_case.setdefault(case_of(e), []).append(e)
+    for lst in by_case.values():
+        lst.sort(key=lambda x: (float(x.get("ts") or 0), int(x.get("_line") or 0)))
+
+    # 店铺回填（台账事件常没有 store 字段 ⇒ 从当日失败诊断里按 record_id 补）
+    rec_store = {}
+    for r in failures:
+        rid = str(r.get("record_id") or "")
+        if rid and r.get("store"):
+            rec_store.setdefault(rid, str(r["store"]))
+
+    def _store_of_case(cid: str) -> str:
+        for e in by_case.get(cid, []):
+            s = store_of(e)
+            if s:
+                return s
+        return rec_store.get(record_of(cid), "") or "（未知）"
+
+    # ── ① 当日 case 数 / 终态分布 ──────────────────────────────────────────
+    terminal: dict[str, int] = {"done": 0, "failed": 0, "blocked": 0, OTHER: 0}
+    case_rows = []
+    failed_ever = 0
+    for cid, evs in sorted(by_case.items()):
+        states = [(e, state_bucket(e.get("event"))) for e in evs]
+        states = [(e, b) for e, b in states if b]
+        last_ev, last_b = (states[-1] if states else (None, OTHER))
+        terminal[last_b] = terminal.get(last_b, 0) + 1
+        ever = any(str(e.get("event") or "") == "failed" for e in evs)
+        failed_ever += 1 if ever else 0
+        case_rows.append({
+            "case": cid, "record_id": record_of(cid), "store": _store_of_case(cid),
+            "events_on_day": len(evs),
+            "failed_ever": ever,
+            "last_state_event": (last_ev or {}).get("event") or "",
+            "last_state_ts": int(last_ev.get("ts") or 0) if last_ev else None,
+            "terminal": last_b,
+            "src": [f"{(last_ev or {}).get('_src', '')}:{(last_ev or {}).get('_line', '')}"]
+                   if last_ev else [],
+        })
+
+    # ── ② 失败原因分类计数 ────────────────────────────────────────────────
+    day_failures = [r for r in failures
+                    if failures_date_of(r) == date and _store_ok(str(r.get("store") or ""))]
+    day_failed_events = [e for e in day_events if str(e.get("event") or "") == "failed"]
+    reasons: list = []
+    for r in day_failures:
+        text = str(r.get("error_message") or "")
+        b, rid = classify_reason(text)
+        reasons.append({"bucket": b, "rule": rid, "record_id": str(r.get("record_id") or ""),
+                        "store": str(r.get("store") or ""), "ts": str(r.get("ts") or ""),
+                        "step": r.get("failed_step"), "err_type": str(r.get("error_type") or ""),
+                        "reason": text, "source": "failures",
+                        "src": f"{r.get('_src')}:{r.get('_line')}"})
+    # 台账里 failed 但当日 failures.jsonl **已经**记过同一次失败 ⇒ 跳过（⛔ 不许双重计数）：
+    # 同一次失败会同时进两处（`_record_failure` 写 failures.jsonl、`_ledger_record_full_failure`
+    # 写台账）⇒ 两条都数会把"当日失败数"翻倍，归因表当场失真。
+    # 去重键 =（record_id, 分钟级时刻）：两处的时间戳都取自同一次失败，分钟必然相同。
+    _fail_keys = {(str(r.get("record_id") or ""), str(r.get("ts") or "")[:16])
+                  for r in day_failures}
+    _seen = {(x["record_id"], x["reason"][:60]) for x in reasons}
+    deduped = 0
+    for e in day_failed_events:
+        text = str(e.get("reason") or e.get("error") or "")
+        rid = record_of(case_of(e))
+        _at = (dt.datetime.fromtimestamp(float(e.get("ts") or 0)).strftime("%Y-%m-%d %H:%M")
+               if e.get("ts") else "")
+        if (rid, _at) in _fail_keys:
+            deduped += 1
+            continue
+        if (rid, text[:60]) in _seen:
+            continue
+        b, rule = classify_reason(text)
+        reasons.append({"bucket": b, "rule": rule, "record_id": rid, "store": store_of(e),
+                        "ts": dt.datetime.fromtimestamp(float(e.get("ts") or 0)).strftime("%Y-%m-%d %H:%M:%S")
+                              if e.get("ts") else "",
+                        "step": None, "err_type": str(e.get("errType") or ""),
+                        "reason": text, "source": "ledger",
+                        "src": f"{e.get('_src')}:{e.get('_line')}"})
+    reason_counts = {b: 0 for b in BUCKET_ORDER}
+    for x in reasons:
+        reason_counts[x["bucket"]] = reason_counts.get(x["bucket"], 0) + 1
+
+    # ── ③ 小时 × 终态 / 店铺 × 终态 ───────────────────────────────────────
+    hour_state: dict[str, dict] = {}
+    store_state: dict[str, dict] = {}
+    for row in case_rows:
+        ts = row.get("last_state_ts")
+        hour = dt.datetime.fromtimestamp(ts).strftime("%H") if ts else "??"
+        h = hour_state.setdefault(hour, {k: 0 for k in ("done", "failed", "blocked", OTHER)})
+        h[row["terminal"]] = h.get(row["terminal"], 0) + 1
+        s = store_state.setdefault(row["store"] or "（未知）",
+                                   {k: 0 for k in ("done", "failed", "blocked", OTHER)})
+        s[row["terminal"]] = s.get(row["terminal"], 0) + 1
+
+    # ── ④ 反事实三态（逐条失败）────────────────────────────────────────────
+    counter = []
+    for x in reasons:
+        cf = counterfactual(x["reason"], window)
+        counter.append({**{k: x[k] for k in ("record_id", "store", "ts", "bucket", "reason", "src")},
+                        "window": window, **cf})
+    cf_counts = {"would_succeed": 0, "would_fail": 0, "insufficient": 0}
+    for c in counter:
+        cf_counts[c["verdict"]] = cf_counts.get(c["verdict"], 0) + 1
+
+    # ── ⑤ 与手动路径对照的时间线 ──────────────────────────────────────────
+    timelines = []
+    for cid, evs in sorted(by_case.items()):
+        fails = [e for e in evs if str(e.get("event") or "") == "failed"]
+        dones = [e for e in evs if str(e.get("event") or "") == "done"]
+        manual = [e for e in dones if str(e.get("by") or "") not in ("", "orchestrator")]
+        if fails and manual:
+            timelines.append({
+                "case": cid, "record_id": record_of(cid), "store": _store_of_case(cid),
+                "auto_failed": [{"ts": int(e.get("ts") or 0),
+                                 "at": dt.datetime.fromtimestamp(float(e.get("ts") or 0))
+                                       .strftime("%Y-%m-%d %H:%M:%S"),
+                                 "text": str(e.get("reason") or e.get("error") or "")[:200],
+                                 "src": f"{e.get('_src')}:{e.get('_line')}"} for e in fails],
+                "manual_done": [{"ts": int(e.get("ts") or 0),
+                                 "at": dt.datetime.fromtimestamp(float(e.get("ts") or 0))
+                                       .strftime("%Y-%m-%d %H:%M:%S"),
+                                 "by": str(e.get("by") or ""),
+                                 "text": str(e.get("detail") or e.get("reason") or "")[:200],
+                                 "src": f"{e.get('_src')}:{e.get('_line')}"} for e in manual],
+            })
+
+    return {
+        "schema": "argent-full-day-attribution/1",
+        "date": date,
+        "filters": {"store": store or None, "window": window},
+        "sources": {
+            "ledger": {"events_total": len(ledger), "events_on_day": len(day_events)},
+            "failures": {"records_total": len(failures), "records_on_day": len(day_failures)},
+        },
+        "cases": {"count": len(case_rows), "terminal": terminal,
+                  # 「曾失败」与「终态=失败」是**两个不同的数**：一张票当天失败过、后来人工补完
+                  # ⇒ 终态算 done，但它确实是自动路径的一次失败（成功率口径要看这个数）。
+                  "failed_ever": failed_ever, "rows": case_rows},
+        "failures": {"count": len(reasons), "by_reason": reason_counts, "rows": reasons,
+                     "ledger_only": len(reasons) - len(day_failures),
+                     "deduped_ledger_events": deduped},
+        "matrix": {"by_hour": hour_state, "by_store": store_state},
+        "counterfactual": {"window": window, "counts": cf_counts, "rows": counter,
+                           "action_if_capacity": _CAPACITY_ACTION},
+        "timelines": {"count": len(timelines), "rows": timelines},
+    }
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 渲染（人读）
+# ══════════════════════════════════════════════════════════════════════════
+
+def render(rep: dict) -> str:
+    L = []
+    L.append(f"═══ FULL 当日归因 {rep['date']} ═══"
+             + (f"（店铺={rep['filters']['store']}）" if rep["filters"]["store"] else "")
+             + f"  反事实窗口={rep['filters']['window']}")
+    L.append(f"源：台账 {rep['sources']['ledger']['events_on_day']}/"
+             f"{rep['sources']['ledger']['events_total']} 条（当日/全部）；"
+             f"失败诊断 {rep['sources']['failures']['records_on_day']}/"
+             f"{rep['sources']['failures']['records_total']} 条")
+    L.append("")
+    c = rep["cases"]
+    L.append(f"① 当日 case 数 = {c['count']}｜终态：" +
+             " / ".join(f"{k} {v}" for k, v in c["terminal"].items())
+             + f"｜当日**曾失败**的 case = {c.get('failed_ever', 0)}"
+             + "（终态=done 里可能含「失败后人工补完」，两个数口径不同）")
+    for r in c["rows"]:
+        L.append(f"   · {r['record_id']} [{r['store']}] 当日事件 {r['events_on_day']} 条 ⇒ "
+                 f"{r['terminal']}（末条状态事件={r['last_state_event'] or '（无）'}；{r['src'][0] if r['src'] else ''}）")
+    L.append("")
+    f = rep["failures"]
+    L.append(f"② 失败记录 {f['count']} 条｜分类：" +
+             " ｜ ".join(f"{k} {f['by_reason'].get(k, 0)}" for k in BUCKET_ORDER))
+    for x in f["rows"]:
+        L.append(f"   · [{x['bucket']}] {x['record_id']} {x['ts']} step={x['step']} "
+                 f"rule={x['rule']}｜{x['reason'][:90]}（{x['src']}）")
+    L.append("")
+    L.append("③ 小时 × 终态：")
+    for h in sorted(rep["matrix"]["by_hour"]):
+        d = rep["matrix"]["by_hour"][h]
+        L.append(f"   {h} 时：" + " ".join(f"{k}={d.get(k, 0)}" for k in ("done", "failed", "blocked", OTHER)))
+    L.append("   店铺 × 终态：")
+    for s in sorted(rep["matrix"]["by_store"]):
+        d = rep["matrix"]["by_store"][s]
+        L.append(f"   {s}：" + " ".join(f"{k}={d.get(k, 0)}" for k in ("done", "failed", "blocked", OTHER)))
+    L.append("")
+    cf = rep["counterfactual"]
+    L.append(f"④ 反事实（窗口={cf['window']} ∧ 仓容可用）："
+             f"本可成功 {cf['counts'].get('would_succeed', 0)} / "
+             f"仍会失败 {cf['counts'].get('would_fail', 0)} / "
+             f"证据不足 {cf['counts'].get('insufficient', 0)}")
+    for x in cf["rows"]:
+        L.append(f"   · [{x['verdict']}] {x['record_id']}（axis={x['axis']}）{x['basis']}")
+    L.append("")
+    t = rep["timelines"]
+    L.append(f"⑤ 与手动路径对照的时间线：{t['count']} 个 case")
+    for row in t["rows"]:
+        L.append(f"   · {row['record_id']} [{row['store']}]")
+        for e in row["auto_failed"]:
+            L.append(f"       自动 failed {e['at']}｜{e['text'][:80]}（{e['src']}）")
+        for e in row["manual_done"]:
+            L.append(f"       人工 done  {e['at']}｜by={e['by']}｜{e['text'][:80]}（{e['src']}）")
+    L.append("")
+    L.append("（本报表**只读**：零网络、零写入；每条结论都带计数与证据行号，可复算）")
+    return "\n".join(L)
+
+
+def _main(argv: Optional[list[str]] = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="analyze-full-day.py",
+        description="当日 FULL 归因报表（只读、零网络、零写入；数据源=统一台账 + 失败诊断）")
+    p.add_argument("--ledger", default=str(DEFAULT_LEDGER), help=f"统一台账（默认 {DEFAULT_LEDGER}）")
+    p.add_argument("--failures", default=str(DEFAULT_FAILURES),
+                   help=f"失败诊断 JSONL（默认 {DEFAULT_FAILURES}）")
+    p.add_argument("--date", default=dt.date.today().isoformat(),
+                   help="统计日期 YYYY-MM-DD（默认今天，本地时区）")
+    p.add_argument("--store", default="", help="只看该店铺（精确匹配）")
+    p.add_argument("--window", type=int, default=None,
+                   help="反事实前提里的顺延窗口（天）；缺省 = 当前生效值"
+                        "（`flow_config.appointment_max_day()`：env → 声明 default）")
+    p.add_argument("--json", action="store_true", help="机读形状（含每条的 src/行号）")
+    a = p.parse_args(argv)
+
+    try:
+        dt.date.fromisoformat(a.date)
+    except ValueError:
+        print(f"⛔ --date 必须是 YYYY-MM-DD：{a.date}", file=sys.stderr)
+        return 2
+
+    window = a.window
+    if window is None:
+        try:
+            sys.path.insert(0, str(HERE))
+            from flow_config import appointment_max_day as _amd      # noqa: E402
+            window = int(_amd())
+        except Exception:                                            # noqa: BLE001
+            window = 5
+    if window < 1:
+        print("⛔ --window 必须 ≥1", file=sys.stderr)
+        return 2
+
+    ledger_path, fail_path = pathlib.Path(a.ledger), pathlib.Path(a.failures)
+    ledger, failures = read_jsonl(ledger_path), read_jsonl(fail_path)
+    # ⛔ 「读不到文件」与「文件在但当天没数据」必须分得开：前者是**用法/环境问题**（exit 2），
+    #    后者是**事实**（0 条，exit 0）—— 混成一种会把"路径写错"报成"今天全成功"。
+    missing = [str(x) for x in (ledger_path, fail_path) if not x.exists()]
+    if len(missing) == 2:
+        print(f"⛔ 两个数据源都读不到（路径写错？）：{', '.join(missing)}", file=sys.stderr)
+        return 2
+
+    rep = build_report(ledger, failures, date=a.date, store=a.store, window=window)
+    rep["sources"]["paths"] = {"ledger": str(ledger_path), "failures": str(fail_path),
+                               "missing": missing}
+    if a.json:
+        print(json.dumps(rep, ensure_ascii=False, indent=2))
+    else:
+        print(render(rep))
+        if missing:
+            print(f"⚠️ 数据源缺失（按空处理）：{', '.join(missing)}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main())