@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_claim.py

@@ -0,0 +1,497 @@
+#!/usr/bin/env python3
+"""flow_claim —— **原子认领**待跑票（防重复跑同一票）。
+
+为什么需要（2026-09-15 实测竞态）：
+  定时触发 T=0 看到 in_flight=0 ⇒ 唤起角色；角色要几十秒才派发并记账；
+  T=+5min 下一个触发：台账里仍 in_flight=0 ⇒ **又唤起一次 ⇒ 同一票被派两遍**。
+⇒ 唤起前必须先**原子认领**：写 `planned`（带租约，默认 10 分钟），triage 把它计入在飞；
+  角色只处理被认领的票；派发时升级为 `dispatched`；到期未升级 ⇒ triage 视为可回收（stale）。
+
+用法：
+  python3 scripts/flow_claim.py --flow wenyao-invoice [--max 2] [--lease-min 10] [--json] [--dry-run]
+  python3 scripts/flow_claim.py --flow <flow> --cases-from-dir /tmp/cases --json   # 离线/夹具
+  · `--max/--lease-min` 缺省取**流程配置**（`flow_config.py` ← 注册表 concurrency 段）；
+  · 锁**按流程分文件**（`flow-claim-<flow>.lock`）—— 两条流程的触发互不阻塞；
+  · `--cases-from-dir` **原样透传给分诊**（`flow_triage.py:217`）⇒ 认领也能在无客户、无网络、
+    无许可的机器上端到端跑通（P4 离线冒烟 S3 的前置）。
+退出码：0 有认领（或 dry-run）；3 = 无票可认领；2 = 错误
+  ⚠️ 本脚本的退出码**不在** P0-A 的 verb 退出码表管辖内（改它会连带动 scripts/flow-trigger.sh 的
+  headless 分支）⇒ `argent flow claim` 由 **verb 适配层**把 3 翻成 `0 + empty:true`（见 core/lib/claim.mjs）。
+dry-run 零副作用（P0-A A3）：不建台账目录、不建锁文件、不落店铺清单缓存、不写 blocked 台账，
+  连源层的 case 落盘也改到临时目录 ⇒ 跑两次 dry-run 后数据目录**逐字节不变**。
+"""
+from __future__ import annotations
+import argparse, json, os, pathlib, re, subprocess, sys, tempfile, time
+from typing import Optional
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+from flow_config import load_config        # noqa: E402  （每流程运行时配置的唯一读取点）
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+# 跨平台文件锁**唯一真源**（POSIX `fcntl.flock` / Windows `msvcrt.locking`）：
+# 此前本文件顶层 `import fcntl` ⇒ Windows 上 `ModuleNotFoundError` ⇒ 认领整个不可用。
+from argent_filelock import FileLock, LockError, best_effort   # noqa: E402
+
+def _ziniao_stores(ttl_sec: int = 600, write: bool = True) -> set:
+    """紫鸟店铺清单（**逐字**匹配用，2026-09-23 用户口径 A）。带 TTL 缓存；
+    取不到返回空集 ⇒ 调用方跳过校验（宁可不拦，也不误杀干净票）。
+
+    `write=False`（dry-run）：**只读缓存**、不落盘 —— A3 要求 dry-run 零持久副作用，
+    而缓存落盘会改动数据目录（哪怕只是性能缓存）。判据不受影响（清单内容同一次调用内一致）。
+    """
+    cache = pathlib.Path(resolve_data_dir()['dir']) / 'ziniao-stores.json'
+    try:
+        doc = json.loads(cache.read_text(encoding='utf-8'))
+        if time.time() - float(doc.get('ts') or 0) < ttl_sec and doc.get('stores'):
+            return set(doc['stores'])
+    except Exception:
+        pass
+    try:
+        out = subprocess.run(['ziniao-cli', 'store', 'list'], capture_output=True, text=True, timeout=45).stdout
+        d = json.loads(out[out.find('{'):]) if '{' in out else {}
+        names = {str(it.get('storeName') or it.get('name') or '').strip()
+                 for it in ((d.get('data') or {}).get('items') or [])}
+        names.discard('')
+        if names and write:
+            cache.parent.mkdir(parents=True, exist_ok=True)
+            cache.write_text(json.dumps({'ts': time.time(), 'stores': sorted(names)}, ensure_ascii=False), encoding='utf-8')
+        return names
+    except Exception:
+        return set()
+
+
+def _ziniao_store_ips(ttl_sec: int = 600, write: bool = True) -> dict:
+    """店铺名 → 代理 IP（`ziniao-cli store list`，TTL 缓存）。取不到 ⇒ 空 dict。
+
+    B3（2026-09-24）为什么需要：**限流按代理 IP 判定**，而我们的并发限制一直是"按店铺名"——
+    实测本机 6 家店里有**两对主/子账号共用同一个代理**：
+      · `216.238.78.250` ← 墨西哥-1店-子账号 + 墨西哥-1店-主账号
+      · `158.23.227.110` ← 墨西哥-2店-子账号 + 墨西哥-2店-主账号
+    主/子账号是**两个不同的店名** ⇒ 旧口径允许它们并行 ⇒ 同一个 IP 上请求速率翻倍
+    （限流正是这样被触发的）。按 IP 计并发才是正确单位。
+
+    `write=False`（dry-run）：只读缓存、不落盘（A3 零副作用；判据不受影响）。
+    """
+    cache = pathlib.Path(resolve_data_dir()['dir']) / 'ziniao-store-ips.json'
+    try:
+        doc = json.loads(cache.read_text(encoding='utf-8'))
+        if time.time() - float(doc.get('ts') or 0) < ttl_sec and doc.get('ips'):
+            return {str(k): str(v) for k, v in doc['ips'].items()}
+    except Exception:
+        pass
+    try:
+        out = subprocess.run(['ziniao-cli', 'store', 'list'], capture_output=True, text=True, timeout=45).stdout
+        d = json.loads(out[out.find('{'):]) if '{' in out else {}
+        ips = {str(it.get('storeName') or it.get('name') or '').strip(): str(it.get('ip') or '').strip()
+               for it in ((d.get('data') or {}).get('items') or [])}
+        ips = {k: v for k, v in ips.items() if k}
+        if ips and write:
+            cache.parent.mkdir(parents=True, exist_ok=True)
+            cache.write_text(json.dumps({'ts': time.time(), 'ips': ips}, ensure_ascii=False), encoding='utf-8')
+        return ips
+    except Exception:
+        return {}
+
+
+TRIAGE = HERE / 'flow_triage.py'
+
+
+def append(path: pathlib.Path, rec: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, 'a', encoding='utf-8') as f:
+        # 台账**追加写**：策略 (b) 响亮降级（旧实现在 Windows 上是**静默**无锁写 —— 这里至少出声）。
+        # 「不阻断主流程」是台账自身的约定；真正防重复派发的是上面那把认领锁（策略 (a)）。
+        with best_effort(f, site='flow_claim.append', note='台账追加降级为无锁写'):
+            f.write(json.dumps(rec, ensure_ascii=False) + '\n'); f.flush(); os.fsync(f.fileno())
+
+
+def live_leases(ledger: pathlib.Path, now: float) -> dict:
+    """从台账取**未过期租约**的按店计数：{store: 数量}。
+
+    口径（2026-09-18 修，用户实测"同店两条 SKU 要等 10 分钟？"暴露）：
+      某 case 仍占租约 ⇔ **该 case 的最新事件是 `planned`** 且 `leaseUntil > now`。
+    为什么必须看"最新事件"：租约是"已认领、还没跑完"的标记，跑完写 `done`（或 `failed`/
+    `blocked`）后**租约就该释放**。旧实现只按 `planned + leaseUntil > now` 计数，**不看
+    收尾事件** ⇒ 跑完的票仍按租约占位（full 租约 30 分钟）⇒ 同店下一张要白等 30 分钟
+    （实测：墨西哥-1店 16:07:49 就跑完，16:1x 仍被算作"在飞 1"，租约到 16:30:37）。
+    与 flow_triage / 工作台的在飞口径一致（都是"按 case 最新事件"判定）。
+    """
+    last: dict = {}
+    try:
+        for line in ledger.read_text(encoding='utf-8').splitlines():
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except Exception:
+                continue
+            cid = e.get('caseId')
+            if cid:
+                last[cid] = e
+    except FileNotFoundError:
+        pass
+    by_store: dict = {}
+    for e in last.values():
+        if e.get('event') != 'planned':
+            continue                       # 已被 done/failed/blocked/phase 收尾 ⇒ 不再占租约
+        if float(e.get('leaseUntil') or 0) <= now:
+            continue
+        st = str(e.get('store') or '')
+        by_store[st] = by_store.get(st, 0) + 1
+    return by_store
+
+
+def select_candidates(cands: list, live_by_store: dict, max_n: int,
+                      per_store: int, batch_per_store: int = 1,
+                      per_ip: int = 0, store_ip: dict | None = None) -> list:
+    """按店选票（纯函数，便于离线回归）。
+
+    两种模式（同一套判据，`batch_per_store` 切换）：
+
+    · `batch_per_store <= 1`（缺省/旧行为）：同店**同时**最多 `per_store` 张 ——
+      "同店串行、跨店并行"。`per_store <= 0` ⇒ 不限制（不依赖店铺浏览器的流程，如发票）。
+
+    · `batch_per_store > 1`（**一店一批**，2026-09-18 用户口径）：一个店**一次带走一批**
+      （最多 `batch_per_store` 张），由**一个** subagent 跑
+      `orchestrator.py --records a,b,…`（KB-085：单 CDP 连接、多标签页、**顺序**执行）。
+      铁律：**该店已有活租约（上一批还在跑）⇒ 整店跳过，绝不追加** ——
+      追加 = 同店两批并行，而产物认领的兜底是"目录里新出现/最新的文件"
+      （`_snapshot_download_dir` 差值），同店并行会**把标签/箱唛记到错票**。
+
+    没有店铺信息的票（store 为空）按**同一个虚拟店**计数 —— 保守处理：宁少派，不抢资源。
+
+    · `per_ip > 0`（B3，2026-09-24）：在"按店"之上再加一层**按代理 IP** 的限制。
+      限流按 IP 判定，而主/子账号是**两个店名、同一个 IP**（本机实测两对）⇒ 只按店限并发
+      等于允许同一 IP 上翻倍打请求。IP 未知的店归入**同一个"未知"桶**（保守：也不许叠加）。
+    """
+    picked, take = [], {}
+    batch = int(batch_per_store or 1)
+    ip_used: dict = {}
+    if per_ip > 0:
+        for st, live_n in (live_by_store or {}).items():
+            ip = (store_ip or {}).get(st) or '__unknown__'
+            if live_n:
+                ip_used[ip] = ip_used.get(ip, 0) + int(live_n)
+    for c in cands:
+        if len(picked) >= max_n:
+            break
+        st = str(c.get('store') or '')
+        live = live_by_store.get(st, 0)
+        if batch > 1 and live > 0:
+            continue                      # 该店上一批还在跑 ⇒ 整店跳过（绝不追加）
+        used = live + take.get(st, 0)
+        cap = batch if batch > 1 else per_store
+        if cap > 0 and used >= cap:
+            continue
+        ip = ((store_ip or {}).get(st) or '__unknown__') if per_ip > 0 else None
+        if ip is not None and ip_used.get(ip, 0) >= per_ip:
+            continue                      # 同 IP 已达上限（含"其它店名共用一个代理"的情况）
+        take[st] = take.get(st, 0) + 1
+        if ip is not None:
+            ip_used[ip] = ip_used.get(ip, 0) + 1
+        picked.append(c)
+    return picked
+
+
+def planned_record(cid: str, store: str, now: int, lease_until: int, cand: dict | None = None) -> dict:
+    """认领记录（`planned`）。
+
+    2026-09-21（Rule R）：人工放行重跑（triage 给的候选带 `kind=release`）额外记
+    `release=true` + `releaseRetry=N` —— 分诊的「每票上限 / 冷却」就认这两个字段
+    （只数人工放行这条通道，与流程内部重试无关）。
+
+    2026-10-13（放行额度与上游变化）：
+      · `kind=external`（**外部时序**独立通道）记 `externalTiming=true`，⛔ **不写** `release`
+        ⇒ 既不占 `maxPerCase`、也不受它约束（分诊按 `externalRetry` 单独计数）；
+      · 任何派发都抄下 triage 给的 `upstreamFieldHash`（逐字段 8 位哈希，**不含值**）——
+        它是下一轮"上游相对**上次派发**变了吗"的基线（① 的判据）；`upstreamReset` 只作
+        诊断标记（说明这一次派发是"上游变了 ⇒ 额度重置"换来的）。
+    纯函数，便于离线回归。
+    """
+    rec = {'ts': now, 'caseId': cid, 'event': 'planned', 'store': store,
+           'leaseUntil': lease_until, 'by': 'flow-claim'}
+    kind = str((cand or {}).get('kind') or '')
+    if kind == 'release':
+        rec['release'] = True
+        rec['releaseRetry'] = int((cand or {}).get('releaseRetry') or 0)
+    elif kind == 'external':
+        rec['externalTiming'] = True
+        rec['externalRetry'] = int((cand or {}).get('externalRetry') or 0)
+    _h = (cand or {}).get('upstreamFieldHash')
+    if isinstance(_h, dict) and _h:
+        rec['upstreamFieldHash'] = {str(k): str(v) for k, v in _h.items()}
+    if (cand or {}).get('upstreamReset'):
+        rec['upstreamReset'] = True
+    return rec
+
+
+# ── 平台限流信号（店级退避的**唯一**判据表，分两类）──────────────────────
+# 【确定类】平台限流的"原样回法"——前端模块加载失败也在内。见到即退避。
+THROTTLE_PATTERNS = ('local_rate_limited', '429', '503', 'rate_limit', '限流',
+                     'fbm-shipment-planning-frontend', 'resolveProps')
+# 【可疑类】ML 的"整页错误页"形态——**它既可能是限流，也可能是别的原因**（2026-09-23 实测）：
+#   · 17:12 搜索页（步3，尚无货件号）收到「Hubo un error accediendo…／Error Code: 88WX9XT9M」；
+#   · 17:30 预约页（步4）整页「Algo salió mal／Estamos trabajando para solucionarlo」——
+#     但**改号后立刻正常**（77849070→77849071，⑰ 取号错位第 3 次），即这次根因是**错号**不是限流。
+# ⇒ 判据必须带**步位闸**：只有"还不涉及货件号的阶段"（无 phase / step1~3）出现的整页错误页
+#    才算平台限流证据；步4/6/7 的同类错误页先当成"可能是数据/号码问题"，不触发店级退避
+#    （否则一次错号会让整店白白停 30 分钟自动认领）。
+THROTTLE_AMBIGUOUS = ('platform_error_page', 'Hubo un error accediendo',
+                       'Algo salió mal', 'Estamos trabajando para solucionarlo')
+# 可疑类只在这些步位（含"无步位信息"）算证据：≤3 = 建单前后、还没有货件号可错
+THROTTLE_AMBIGUOUS_MAX_STEP = 3
+# 只有"处置类"事件才算限流证据：done（成功收口）的 detail 里也常复述错误弹窗自愈过程，
+# 拿它当证据会让一次**成功**的运行把同店白白退避 30 分钟。
+THROTTLE_EVENTS = ('failed', 'blocked', 'retry', 'requeued')
+
+
+def throttle_step_of(event: dict) -> Optional[int]:
+    """从台账事件里取步位（`phase="step4"` / 错误文本里的 `步骤4`/`step 4`）→ int 或 None。"""
+    m = re.search(r'step\s*(\d)', str(event.get('phase') or ''), re.I) \
+        or re.search(r'步骤\s*(\d)', str(event.get('error') or '') + str(event.get('detail') or ''))
+    return int(m.group(1)) if m else None
+
+
+def throttled_stores(ledger: pathlib.Path, now: float, cooldown_min: int,
+                     store_of: dict) -> dict:
+    """最近 cooldown_min 分钟内被平台限流过的店铺 → {store: 最近一次时间戳}（纯函数，便于离线回归）。
+
+    - 只看 `THROTTLE_EVENTS` 类事件；
+    - 确定类信号见到即算；可疑类（整页错误页）必须过**步位闸**（见 THROTTLE_AMBIGUOUS 注释）；
+    - 未识别出店铺的事件不计（宁少退避，不误伤别的店）。
+    """
+    hot: dict = {}
+    try:
+        for line in ledger.read_text(encoding='utf-8').splitlines()[-400:]:
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if str(e.get('event') or '') not in THROTTLE_EVENTS:
+                continue
+            ts = float(e.get('ts') or 0)
+            if now - ts > cooldown_min * 60:
+                continue
+            blob = str(e.get('detail') or '') + str(e.get('error') or '')
+            hit = any(k in blob for k in THROTTLE_PATTERNS)
+            if not hit and any(k in blob for k in THROTTLE_AMBIGUOUS):
+                step = throttle_step_of(e)
+                hit = step is None or step <= THROTTLE_AMBIGUOUS_MAX_STEP
+            if hit:
+                st = store_of.get(str(e.get('caseId'))) or str(e.get('store') or '')
+                if st:
+                    hot[st] = max(hot.get(st, 0), ts)
+    except OSError:
+        pass
+    return hot
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='原子认领待跑票（planned + 租约）')
+    ap.add_argument('--flow', required=True)
+    ap.add_argument('--max', type=int, default=None, help='本轮最多认领几张（默认取流程配置 concurrency.max）')
+    ap.add_argument('--lease-min', type=int, default=None, help='租约分钟（默认取流程配置 concurrency.leaseMin）')
+    ap.add_argument('--ledger', default=None, help='台账文件（默认取流程配置 paths.ledger）')
+    ap.add_argument('--lock', help='锁文件（默认按流程分文件 flow-claim-<flow>.lock）')
+    ap.add_argument('--batch', type=int, default=None,
+                    help='一店一批：同店单轮最多带走几张（默认取流程配置 concurrency.batchPerStore）')
+    ap.add_argument('--per-ip', dest='per_ip', type=int, default=None,
+                    help='按代理 IP 限并发（B3；默认取流程配置 concurrency.perIp，0=不限）')
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--dry-run', action='store_true')
+    ap.add_argument('--cases-from-dir', dest='cases_from_dir', default=None,
+                    help='离线/夹具：把该目录**原样透传**给分诊（跳过源读取）——无网络机器上也能跑认领')
+    a = ap.parse_args(argv)
+
+    cfg = load_config(a.flow)                       # 未知流程在此 exit 2（早失败，提示可用流程）
+    max_n = a.max if a.max is not None else cfg['concurrency']['max']
+    lease_min = a.lease_min if a.lease_min is not None else cfg['concurrency']['leaseMin']
+    batch_n = a.batch if a.batch is not None else int(cfg['concurrency'].get('batchPerStore') or 1)
+    lock = pathlib.Path(a.lock or cfg['paths']['lock'])
+    ledger = pathlib.Path(a.ledger or cfg['paths']['ledger'])
+
+    # 整个"读 triage → 选票 → 写认领"必须在**同一把锁**内完成，否则并发触发仍会重复选
+    # ── dry-run 零副作用（P0-A A3；2026-10-03）──────────────────────────────
+    # dry-run 不许在数据目录里**新建任何东西**：不建台账目录、不建锁文件。
+    #   · 台账目录：真跑才 mkdir（dry-run 只读台账，缺目录时按"无台账"读）。
+    #   · 锁：数据目录里**已有**锁文件（生产机器第一次真认领之后就有）⇒ 照用，与真跑互斥；
+    #     没有 ⇒ 退到临时目录，只与其它 dry-run 互斥（预演不该在生产目录留痕）。
+    if not a.dry_run:
+        ledger.parent.mkdir(parents=True, exist_ok=True)
+    elif not lock.exists():
+        lock = pathlib.Path(tempfile.gettempdir()) / f'argent-claim-dry-{lock.name}'
+    # ── 认领互斥锁：**策略 (a) fail-closed**（跨平台，见 scripts/lib/filelock.py）──────────
+    # 为什么这里绝不降级：整个「读 triage → 选票 → 写 planned」必须原子，丢了锁就会把同一张票
+    # 派两遍（重复跑同一票 = 重复写生产表）。所以拿不到/锁不可用 ⇒ **明确失败**（退出码 2），
+    # 而不是无锁继续；旧实现在 Windows 上连注释都执行不到（顶层 import fcntl 直接崩）。
+    # 语义与旧实现逐字等价：同一把锁文件、阻塞式排他锁、锁的生命周期 = fd（进程退出即释放）。
+    _claim_lock = FileLock(lock, blocking=True, site='flow_claim.claim')
+    try:
+        _claim_lock.acquire()
+    except LockError as exc:
+        print(f'认领互斥锁不可用：{exc} ⇒ 本轮放弃（无锁认领会把同一票派两遍）', file=sys.stderr)
+        return 2
+    try:
+        # ⚠️ 必须带超时（2026-09-22 事故）：飞书半开连接会让 triage 永不返回，而认领锁一直被占
+        # ⇒ 定时器每轮都卡在这里、整条发票流程静默冻结 4h51m（日志停在那一刻，无任何报错）。
+        _tri_timeout = int(os.environ.get('ARGENT_TRIAGE_TIMEOUT') or 300)
+        _tri_cmd = [sys.executable, str(TRIAGE), '--flow', a.flow, '--json', '--ledger', str(ledger)]
+        # 离线夹具：原样透传（P4 离线冒烟 S3 的前置）
+        if a.cases_from_dir:
+            _tri_cmd += ['--cases-from-dir', a.cases_from_dir]
+        elif a.dry_run:
+            # 连**源层的 case 落盘**也不落进数据目录（A3 零副作用）：换临时目录，
+            # 分诊仍从那里读回同一批 case ⇒ 判据路径不变，只是不留痕。
+            _tri_cmd += ['--out-dir', tempfile.mkdtemp(prefix='argent-claim-dry-cases-')]
+        try:
+            p = subprocess.run(_tri_cmd, capture_output=True, text=True, timeout=_tri_timeout)
+        except subprocess.TimeoutExpired:
+            print(f'triage 超时（{_tri_timeout}s）：读表未返回 ⇒ 本轮放弃（下一轮自愈）', file=sys.stderr)
+            return 2
+        if not p.stdout.strip().startswith('{'):
+            print(f'triage 失败：{(p.stderr or p.stdout).strip()[:200]}', file=sys.stderr); return 2
+        plan = json.loads(p.stdout)
+        now = time.time()
+        raw = list((plan.get('plan') or {}).get('to_dispatch', []))
+        # ── 账号硬校验（2026-09-23 用户口径 A）────────────────────────────
+        # lip 表的「店铺」字段**指定**该票用哪个账号（如"墨西哥-1店-子账号"）；实测匹配规则 =
+        # **逐字精确**（紫鸟清单与表内命名含相同的主/子后缀，无需归一化）。
+        # 不在清单里的票（实测：`巴西-1店` 5 张）**必须拒绝**：否则脚本只能猜账号 ⇒
+        # 货件建在 A 账号、后续步骤落到 B 账号 ⇒ 预约失败/孤儿货件。绝不回退默认账号。
+        _unknown = {}
+        # ⚠️ 只对**声明了店铺字段**的流程生效（2026-09-24 修，我自己引入的回归）：
+        # 这条闸门原意是"lip 表的「店铺」字段逐字必须在本机紫鸟清单里"（用户口径 A，针对 FULL），
+        # 但它被无条件套到了**所有**流程上 —— 而 daily-report 的源根本没有店铺字段
+        # （`source.kind=cases-json`）⇒ 每个候选项的 store 都是空 ⇒ 全量落进 '(空)' 桶被拒 ⇒
+        # **日报单元从 09-23 起再也认领不出来**（今天实测：`账号校验：拒绝 1 张（店铺 '(空)' …）`）。
+        # 现在：① 未声明店铺字段的流程 ⇒ 整条闸门跳过（并留一行日志说明）；
+        #       ② 声明了店铺字段的流程里，**空店铺的行按 need_fields 处理**（分诊已归桶），
+        #          不再写 `store-unbound__(空)` 这种噪音台账。
+        _store_field = str((((cfg.get('source') or {}).get('fields') or {}).get('store')) or '').strip()
+        if os.environ.get('ARGENT_SKIP_STORE_CHECK') == '1':
+            pass
+        elif not _store_field:
+            print('  · 账号校验：本流程未声明店铺字段 ⇒ 跳过紫鸟店铺闸门（该闸门只对按店派发的流程生效）',
+                  file=sys.stderr)
+        else:
+            _known = _ziniao_stores(write=not a.dry_run)      # dry-run：只读缓存、不落盘（A3）
+            if _known:
+                keep = []
+                _empty = 0
+                for r in raw:
+                    st = str(r.get('store') or '').strip()
+                    if not st:
+                        _empty += 1          # 空店铺 = 等运营补字段（分诊的 need_fields 桶会呈现）
+                        continue
+                    if st not in _known:
+                        _unknown[st] = _unknown.get(st, 0) + 1
+                        continue
+                    keep.append(r)
+                if _empty:
+                    print(f'  · 账号校验：跳过 {_empty} 张（店铺为空 ⇒ 等运营补字段，不是"未授权"）',
+                          file=sys.stderr)
+                if _unknown:
+                    for st, n in _unknown.items():
+                        print(f'  · 账号校验：拒绝 {n} 张（店铺 {st!r} 不在紫鸟清单里 ⇒ 无法确定用哪个账号）',
+                              file=sys.stderr)
+                        if a.dry_run:
+                            # dry-run 零副作用：这条 blocked 是**真写台账**，预演时不许落
+                            print(f'    [dry-run] 不写 blocked 台账（caseId=store-unbound__{st}）', file=sys.stderr)
+                            continue
+                        subprocess.run([sys.executable, str(HERE / 'flow_ledger.py'),
+                                        '--case-id', f'store-unbound__{st}', '--event', 'blocked',
+                                        '--by', 'flow-claim', '--detail',
+                                        f'店铺 {st!r} 未分配给本机紫鸟客户端：**不拾取该票**，等运营在紫鸟把该店铺分配给当前客户端后再跑（或核对 lip 表「店铺」字段写法）'],
+                                       capture_output=True, text=True)
+                raw = keep
+        # ── 店级限流退避（2026-09-23）──────────────────────────────
+        # 平台限流是按店铺代理 IP + 行为判定的；撞了 429/503 后**同店**立刻再派，只会继续撞。
+        # 做法：最近 throttleCooldownMin 分钟内被限流过的店铺 ⇒ 本轮整店跳过（并把原因写清楚）。
+        _throttle_min = int(cfg.get('concurrency', {}).get('throttleCooldownMin') or 30)
+        _store_of = {str(r.get('caseId')): str(r.get('store') or '')
+                     for r in ((plan.get('plan') or {}).get('to_dispatch') or [])
+                     + ((plan.get('plan') or {}).get('stale') or [])
+                     + ((plan.get('plan') or {}).get('in_flight') or [])}
+        _hot = throttled_stores(ledger, now, _throttle_min, _store_of)
+        if _hot:
+            _before = len(raw)
+            raw = [r for r in raw if str(r.get('store') or '') not in _hot]
+            if len(raw) != _before:
+                print(f'  · 店级限流退避：跳过 {_before - len(raw)} 张'
+                      f'（店铺 {", ".join(sorted(_hot))} 近 {_throttle_min} 分钟被平台限流）', file=sys.stderr)
+        per_store = int(cfg['concurrency'].get('perStore') or 0)
+        # ── B3：按代理 IP 限并发（主/子账号同 IP 是旧口径的漏网口）──────────────
+        per_ip = int(getattr(a, 'per_ip', None) if getattr(a, 'per_ip', None) is not None
+                     else (cfg['concurrency'].get('perIp') or 0))
+        store_ip = _ziniao_store_ips(write=not a.dry_run) if per_ip > 0 else {}   # dry-run：不落缓存
+        if per_ip > 0 and not store_ip:
+            print('  · 按 IP 限并发：取不到店铺 IP 清单 ⇒ 本轮所有票归入同一「未知」桶（保守少派一次）',
+                  file=sys.stderr)
+        _live = live_leases(ledger, now)
+        picked = select_candidates(raw, _live, max(0, max_n), per_store, batch_n, per_ip, store_ip)
+        if per_ip > 0 and len(picked) < len(raw):
+            # 说清楚"为什么少派"（否则看起来像分诊漏票）
+            _ips = {}
+            for r in raw:
+                st = str(r.get('store') or '')
+                _ips.setdefault(store_ip.get(st) or '__unknown__', []).append(st)
+            _busy_ip = [ip for ip, sts in _ips.items() if len(sts) > 1]
+            if _busy_ip:
+                print(f'  · 按 IP 限并发（perIp={per_ip}）：{len(_busy_ip)} 个 IP 上有多店共用'
+                      f'（{"; ".join(sorted(_busy_ip))[:120]}）⇒ 同 IP 不并行', file=sys.stderr)
+        cands = [r['caseId'] for r in picked]
+        if len(picked) < len(raw):
+            if batch_n > 1:
+                print(f'  · 一店一批（batchPerStore={batch_n}）：候选 {len(raw)} 张 → 本轮认领 {len(picked)} 张'
+                      f'（同店上一批仍在跑 ⇒ 整店跳过；同批上限 {batch_n} 张）', file=sys.stderr)
+            elif per_store > 0:
+                busy = {}
+                for r in raw:
+                    st = str(r.get('store') or '')
+                    busy[st] = busy.get(st, 0) + 1
+                print(f'  · 按店限并发（perStore={per_store}）：候选 {len(raw)} 张 → 本轮认领 {len(picked)} 张'
+                      f'（同店已在飞或本轮已选满的不再认领）', file=sys.stderr)
+        if not cands:
+            # 带上"为什么没有票"（源清单说明：已推送/未到点/窗口已过/等运营补字段）——
+            # 2026-09-18 用户实测：只有"无票可认领"时，日报静默停摆一整天无人察觉。
+            notes = [str(x) for x in ((plan.get('notes') or []))][:6]
+            summ = plan.get('summary') or {}
+            if not notes and summ:
+                parts = [f"可派发 {summ.get('to_dispatch', 0)}", f"待放行 {summ.get('await_release', 0)}",
+                         f"等人补字段 {summ.get('need_fields', 0)}", f"在飞 {summ.get('in_flight', 0)}",
+                         f"停滞 {summ.get('stale', 0)}", f"需人工 {summ.get('needs_human', 0)}"]
+                notes = ['本轮分诊：' + '｜'.join(parts)]
+            if a.json:
+                # 无票分支也回显**实际生效**的条件（max/leaseMin 可能来自流程配置、非命令行）——
+                # verb 适配层要按 A2 把生效值如实回显，宿主才分得清"真没票"与"被谁拦掉了"。
+                print(json.dumps({'claimed': [], 'flow': a.flow, 'reason': '；'.join(notes),
+                                  'max': max_n, 'leaseMin': lease_min, 'dryRun': bool(a.dry_run),
+                                  'lock': str(lock), 'ledger': str(ledger),
+                                  'casesFromDir': a.cases_from_dir or None}))
+            else:
+                print('  无票可认领' + (f"（{'；'.join(notes)}）" if notes else ''))
+            return 3
+        if a.dry_run:
+            if a.json: print(json.dumps({'claimed': cands, 'dryRun': True, 'flow': a.flow,
+                                         'max': max_n, 'leaseMin': lease_min, 'lock': str(lock),
+                                         'ledger': str(ledger)}))
+            else: print(f'  [dry-run] 将认领 {len(cands)} 张：{", ".join(cands)}')
+            return 0
+        now = int(time.time())
+        for cid in cands:
+            _cand = next((r for r in picked if r.get('caseId') == cid), {})
+            _st = str(_cand.get('store') or '')
+            append(ledger, planned_record(cid, _st, now, now + lease_min * 60, _cand))
+        if a.json:
+            print(json.dumps({'claimed': cands, 'flow': a.flow, 'max': max_n,
+                              'leaseMin': lease_min, 'lock': str(lock)}))
+        else:
+            print(f'  ✅ 已认领 {len(cands)} 张（租约 {lease_min} 分钟，锁 {lock.name}）：{", ".join(cands)}')
+        return 0
+    finally:
+        _claim_lock.release()
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())