@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_sources/feishu_base.py

@@ -0,0 +1,273 @@
+"""飞书 Base 数据面实现（P4，2026-09-29）：从 `flow_source.py` 原样搬出。
+
+接口：`KIND` + `pull(spec, args) -> [(record_id, fields), …]`。
+窄投影收窄把候选清空时，把说明写进 `common.LAST_NARROW` / `common.LAST_PICK_NOTES`
+（引擎的 JSON 输出与日志读它们 —— 迁移期两个模块引用的是**同一批对象**）。
+"""
+from __future__ import annotations
+
+import json, os, sys
+
+from flow_sources.common import (
+    LAST_NARROW,
+    LAST_PICK_NOTES,
+    _flat,
+    apply_pick,
+    required_projection,
+    run,
+    ticket_key,
+    wanted_pick_columns,
+    wanted_upstream_columns,
+)
+
+KIND = 'feishu-base'
+
+def _field_map(profile: str, base: str, table: str) -> dict:
+    """取 字段名 ↔ id 双向映射（实测形状：data.fields[{id,name,type}]）。"""
+    code, out, err = run(['lark-cli', '--profile', profile, 'base', '+field-list',
+                          '--base-token', base, '--table-id', table, '--as', 'bot', '--format', 'json'])
+    if code != 0:
+        print(f'字段清单读取失败（exit {code}）：{(err or out).strip()[:300]}', file=sys.stderr)
+        sys.exit(2)
+    try:
+        fields = (json.loads(out).get('data') or {}).get('fields') or []
+    except Exception as e:
+        print(f'字段清单不是 JSON（{e}）', file=sys.stderr)
+        sys.exit(2)
+    by_id = {f.get('id'): f.get('name') for f in fields if f.get('id')}
+    by_name = {f.get('name'): f.get('id') for f in fields if f.get('name')}
+    return {'by_id': by_id, 'by_name': by_name, 'count': len(fields)}
+
+def _resolved_source(flow_id: str, spec: dict) -> dict:
+    """把流程声明的源解析成**当前生效的一份**：变体选择 + `envFile`/`baseEnv`/`tableEnv`/`*Ref`。
+
+    复用 `flow_config`（唯一实现）—— 引擎里绝不再抄第二套解析逻辑。否则像 `full` 这种
+    "两套变体 + 表 id 来自 fulfillment.env"的流程在别处就会读不了表
+    （2026-09-17 实测：直接读 spec['source'] ⇒ 报"缺少 base/table/identity"）。
+    """
+    raw = dict((spec or {}).get('source') or {})
+    if flow_id:
+        try:
+            from flow_config import load_config
+            return {**raw, **dict((load_config(flow_id, strict=False).get('source') or {}))}
+        except Exception:
+            pass
+    # 兜底（flow_config 不可用时）：自己按声明里的 env 名解析
+    if raw.get('envFile'):
+        load_env_file(str(raw['envFile']))
+    out = dict(raw)
+    for key in ('base', 'table'):
+        if not out.get(key) and raw.get(f'{key}Env'):
+            out[key] = os.environ.get(str(raw[f'{key}Env']), '')
+    return out
+
+def pull(spec: dict, args) -> list[tuple[str, dict]]:
+    """只读拉取飞书表 → [(ticketKey, fields)]。
+
+    实测要点（2026-09-15，lip 表）：
+      · `+field-list` 形状 data.fields[{id,name}]；
+      · `+record-list --format json --field-id …` 返回**位置数组** data.data=[[值,…],…]，
+        **不带表头名** ⇒ 必须按传入 --field-id 的**顺序**映射回字段名；
+      · 不支持 --record-id/--page-size ⇒ 单条过滤与条数上限在客户端做。
+    """
+    # 源解析走 flow_config（变体/envFile/env 名/引用 全都在那里处理，这里不再抄一套）
+    src = _resolved_source(str(getattr(args, 'flow', '') or ''), spec)
+    base = args.base or src.get('base')
+    table = args.table or src.get('table')
+    profile = args.profile or src.get('identity')
+    if not (base and table and profile):
+        miss = [src[k] for k in src if str(k).endswith('Unresolved')]
+        tip = f"（未解析：{'、'.join(str(x) for x in miss)}）" if miss else ''
+        print(f'缺少 base/table/identity：请在流程声明里配置，或用 --base/--table/--profile 传入{tip}',
+              file=sys.stderr)
+        sys.exit(2)
+
+    fmap = _field_map(profile, base, table)
+
+    # 选投影列：显式 --field-ids（id 或名）优先；否则用流程必需字段里的**非系统字段**前 6 个
+    pick, seen = [], set()
+    if args.field_ids:
+        for raw in args.field_ids.split(','):
+            t = raw.strip()
+            name = fmap['by_id'].get(t) or t
+            fid = t if t in fmap['by_id'] else fmap['by_name'].get(t)
+            if not fid or fid in seen:
+                continue
+            seen.add(fid); pick.append((name, fid))
+    else:
+        unknown: list[str] = []
+        # 用**当前变体**的字段要求（flow_config 已合并；见 load_config 的 requiredSource）
+        # 判据与兜底逻辑统一在 required_projection()（可单测；见 scripts/tests/flow-required-role.test.mjs）
+        for name in required_projection(spec):
+            fid = fmap['by_name'].get(name)
+            if not fid:
+                # 2026-09-17 实测（FULL）：required 里写了表里不存在的列名（店铺/装箱数，真名是
+                # 店铺名称/箱数）⇒ 旧实现**静默跳过**，投影少列，最终"未取到任何行"，
+                # 排查成本极高。这里改为**大声失败**并列出可用列名。
+                unknown.append(str(name))
+                continue
+            if fid not in seen:              # 去重（required 里可能有多条指向同一列）
+                seen.add(fid); pick.append((name, fid))
+            # 2026-09-15 修正（文鳐实跑发现）：投影必须**覆盖 required 的全部非系统字段**，
+            # 否则缺口判断永远显示缺一堆。JSON 返回是**位置数组**（非 markdown），不存在
+            # AGENTS.md 说的宽投影错位问题 ⇒ 按需取全，但仍不取无关列。
+            if len(pick) >= 24:      # 上限保护
+                break
+        if unknown:
+            avail = '、'.join(sorted(fmap['by_name'])[:30])
+            print(f"❌ 流程声明的必需字段在表里不存在：{'、'.join(unknown)}\n"
+                  f"   表 {table}（{profile}）可用列（前 30）：{avail}\n"
+                  f"   ⇒ 列名不对会让投影失败并**静默返回 0 行**，请修正 flow-requirements.json 的 required",
+                  file=sys.stderr)
+            sys.exit(2)
+    # 2026-09-15：投影里**必须含路由列**（routeBy），否则无法按货代过滤候选行
+    rt = spec.get('routing') or {}
+    route_by = rt.get('routeBy')
+    if route_by and route_by in fmap['by_name'] and fmap['by_name'][route_by] not in seen:
+        seen.add(fmap['by_name'][route_by]); pick.append((route_by, fmap['by_name'][route_by]))
+    # 2026-09-17（FULL 实测）：投影里**必须含票号列**，否则位置数组里没有票号 ⇒ 每行票号为空
+    # ⇒ 全被跳过 ⇒ "未取到任何行"（静默）。与上面"必须含路由列"是同一类坑。
+    tf_name = args.ticket_field or src.get('ticketField') or '货件号'
+    if tf_name in fmap['by_name'] and fmap['by_name'][tf_name] not in seen:
+        seen.add(fmap['by_name'][tf_name]); pick.append((tf_name, fmap['by_name'][tf_name]))
+    # 2026-09-17（FULL 切到 lip 表时实测）：投影里**必须含 `pick` 用到的列**。
+    # 事故形态：lip 变体的 `pick.status=FULL状态`、`pick.ready=就绪`，这两列既不在 required 里、
+    # 也不是路由/票号列 ⇒ 没进投影 ⇒ 过滤时读到空值 ⇒ **候选静默收窄到 0 行**
+    # （日志只说"候选收窄 100 → 0 行"，看起来像"今天没活干"，实际 FULL状态=待执行 有 96 行）。
+    # 判据：`source.fields.*`（领域名 → 真列名）里被 pick 引用的那几个领域。
+    src_fields = src.get('fields') or {}
+    pick_rules = src.get('pick') or {}
+    for nm in wanted_pick_columns(src):
+        fid = fmap['by_name'].get(nm)
+        if fid and fid not in seen:
+            seen.add(fid); pick.append((nm, fid))
+    # 2026-10-13：**上游变化观察列**（`pick.releaseReDispatch.upstreamHash.watch`）也进投影 ——
+    # 「上游数据变了 ⇒ 放行额度重置」的判据只看得见投影到的列，而 case 里没有的列**永远
+    # 不会被算作"变"**（实测口径：发票流程的 `产品图` 就是这种列：运营补了它、流程也依赖它）。
+    # 与 pick 列的区别：表里没有这一列 ⇒ **静默跳过**（观察列可选；pick 列缺失才是硬故障）。
+    for nm in wanted_upstream_columns(src):
+        fid = fmap['by_name'].get(nm)
+        if fid and fid not in seen:
+            seen.add(fid); pick.append((nm, fid))
+    if not pick:
+        print('无法确定投影列：请传 --field-ids，或在流程 required 里声明字段名', file=sys.stderr)
+        sys.exit(2)
+
+    cmd = ['lark-cli', '--profile', profile, 'base', '+record-list',
+           '--base-token', base, '--table-id', table, '--as', 'bot', '--format', 'json']
+    for _, fid in pick:
+        cmd += ['--field-id', fid]
+    # 2026-09-15 修正 B（文鳐实跑发现）：`+record-list` 默认只返回 100 行 ⇒ 必须翻页，
+    # 否则 100 行以外的票看不见。
+    page_size = 100
+    data, rows_all, ids_all, offset, guard = {}, [], [], 0, 0
+    while True:
+        guard += 1
+        if guard > 50:                       # 保险丝：最多 5000 行
+            break
+        page = cmd + ['--limit', str(page_size)]
+        if offset:
+            page += ['--offset', str(offset)]
+        code, out, err = run(page)
+        if code != 0:
+            print(f'飞书表读取失败（exit {code}）：{(err or out).strip()[:300]}', file=sys.stderr)
+            sys.exit(2)
+        try:
+            data = (json.loads(out).get('data') or {})
+        except Exception as e:
+            print(f'飞书返回不是 JSON（{e}）', file=sys.stderr)
+            sys.exit(2)
+        got = data.get('data') or data.get('records') or data.get('items') or []
+        if not got:
+            break
+        rows_all.extend(got if isinstance(got, list) else [])
+        # 2026-09-17（FULL 实测）：位置数组形态**没有 record_id 字段**，但响应里有
+        # `data.record_id_list`（与 data.data 同序）⇒ 必须一起累积，否则拿不到"单元 id"，
+        # 而 FULL 的单元就是 record_id（货件号此时是空的、是流程产物）。
+        ids_all.extend(data.get('record_id_list') or [])
+        if len(got) < page_size:
+            break
+        offset += len(got)
+        if args.limit and len(rows_all) >= args.limit:
+            break
+        if args.record:                      # 单条查询无需翻页
+            break
+    data = {'data': rows_all} if isinstance(rows_all, list) and rows_all and isinstance(rows_all[0], list) else {'records': rows_all}
+
+    rows = []
+    positional = data.get('data')
+    if isinstance(positional, list):          # 位置数组形态
+        for idx, arr in enumerate(positional):
+            fields = {pick[i][0]: _flat(v) for i, v in enumerate(arr) if i < len(pick)}
+            if idx < len(ids_all):            # 补单元 id（见上：位置数组不含 record_id）
+                fields['_record_id'] = ids_all[idx]
+            rows.append(fields)
+    else:                                      # 对象形态（含 record_id）
+        for r in (data.get('records') or data.get('items') or []):
+            rec = r.get('record_id') or r.get('recordId') or ''
+            fields = {k: _flat(v) for k, v in (r.get('fields') or {}).items() if k != '_record_id'}
+            fields['_record_id'] = rec
+            rows.append(fields)
+
+    ticket_field = args.ticket_field or '货件号'
+    # 2026-09-15：**按 routing 收窄候选行** —— 实测教训：76135791/76163607 的「货代公司」
+    # 不是「上海文鳐」，被 wenyao_run 的 P1 守卫正确拒绝；此前 triage 却把它们列为"可派发"。
+    if (not getattr(args, 'no_route_filter', False)) and route_by and rt.get('match'):
+        before = len(rows)
+        rows = [r for r in rows if str(r.get(route_by) or '').strip() == str(rt['match']).strip()]
+        if before != len(rows):
+            print(f'  · 路由过滤（{route_by}=={rt["match"]}）：{before} → {len(rows)} 行', file=sys.stderr)
+
+    # ── 候选收窄（pick）：把"流程声明里写的该动哪些行"真正落到候选集上 ─────────────
+    # 2026-09-17（FULL 实测）：注册表早就声明了 pick（legacy: 状态∈{Pending,运行中} + 就绪；
+    # lip: FULL状态=待执行 + 就绪 + 货件号空），但引擎没应用 ⇒ 180 行**全部**被当成"可派发"
+    # （含已完成的行）。不应用 pick 就等于把整张表当待办。
+    pick = src.get('pick') or {}
+    rows, phases = apply_pick(rows, src, no_pick_filter=getattr(args, 'no_pick_filter', False))
+    # "已排除 N 张（人工/既往已完成）"要进 JSON 的 notes：分诊把它显示在摘要里、认领把它带进
+    # 触发器日志的 reason ⇒ 运维一眼能看出"没票"不等于"没数据"，而是历史数据被正确分辨掉了。
+    pick_notes = []
+    if phases.get('droppedDone'):
+        pick_notes.append(f'已排除 {phases["droppedDone"]} 张已完成（人工/既往，判据见 pick.exclude*）')
+    LAST_PICK_NOTES.clear()
+    LAST_PICK_NOTES.extend(pick_notes)
+    if pick and not getattr(args, 'no_pick_filter', False):
+        if phases.get('before') and not rows:
+            LAST_NARROW['emptied'] = True          # 收窄到 0 = 合法结论（当前没有该动的行）
+            LAST_NARROW['info'] = {k: v for k, v in phases.items() if k != 'rule'}
+        if phases.get('before') != len(rows):
+            print(f"  · 候选收窄（{phases['rule']}）：{phases['before']} → {len(rows)} 行"
+                  + (f"（{phases['detail']}）" if phases.get('detail') else ''), file=sys.stderr)
+        del phases['rule'], phases['before'], phases['detail']
+
+    out_rows = []
+    skipped_no_ticket = 0
+    # 2026-09-15：位置数组形态**没有 record_id** ⇒ `--record` 无法过滤；
+    # 此时要求用 `--ticket`（按票号过滤），避免"以为只取一条、实际拉全表"。
+    if args.record and rows and not any('_record_id' in r for r in rows):
+        if not args.ticket:
+            print('该表返回位置数组（无 record_id）⇒ --record 无法过滤；请改用 --ticket <货件号>', file=sys.stderr)
+            sys.exit(2)
+    for fields in rows:
+        rec = fields.get('_record_id') or ''
+        if args.record and rec and rec != args.record:
+            continue
+        if args.ticket and str(fields.get(ticket_field) or '') != str(args.ticket):
+            continue
+        # 身份走 ticket_key()，**模式逐流程来自注册表 source.ticketKey**（缺省=历史行为「票号列优先」）。
+        # 见 ticket_key() 注释：FULL 必须 record_id（货件号中途才有）；发票流程必须货件号（行天然已有）。
+        ticket = ticket_key(rec, fields, ticket_field, src.get('ticketKey'))
+        if not ticket:
+            skipped_no_ticket += 1
+            continue
+        fields.pop('_record_id', None)
+        out_rows.append((ticket, fields))
+        if args.limit and len(out_rows) >= args.limit:
+            break
+    if not out_rows and skipped_no_ticket:
+        print(f"❌ 取到 {skipped_no_ticket} 行但**都无法确定票号**（票号列「{tf_name}」为空、且位置数组无 record_id）\n"
+              f"   ⇒ 通常是：① 票号列没进投影（已自动补，若仍失败请检查列名）② 该流程的单元不是票号列\n"
+              f"   ⇒ 对策：把票号列加进 required，或声明 source.ticketField 指向真正的单元列",
+              file=sys.stderr)
+        sys.exit(2)
+    return out_rows

package/engine/scripts/flow_stale.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""flow_stale —— **停滞票自动回收**（认领租约到期、从未被派发 ⇒ 重排回候选）。
+
+## 为什么要有它（2026-09-23 实测）
+triage 把"最近事件是认领/派发但已超窗口"的 case 归为 `stale`，理由写的是
+**"认领租约到期未派发（可回收重派）"** —— 但**没有任何代码回收它**：
+  · `flow_claim.py` 只从 `plan.to_dispatch` 取票（停滞票不在其中）；
+  · `flow_retry.py` 没有回收选项；`flow-trigger.sh` 也没有相关动作。
+⇒ 环境故障（那天是紫鸟未登录）→ 角色 blocked → 租约过期变停滞 → **票静静躺着**，
+还占着同店铺的批次（"可派发 6 却连续 4 轮无票可认领"的直接原因）。
+
+## 语义（保守，可配）
+  · 只回收 `ageMin >= staleAfterMin`（默认 60 分钟）的停滞票
+  · 每轮最多 `maxPerRound` 张（默认 3），避免风暴
+  · `requireEnv=true` 时先跑环境预检（env_probe）：环境不可用 ⇒ **不回收**（否则回收了也白跑）
+  · 回收动作 = 写一条 `requeued` 台账事件（triage 认它 ⇒ 回到 to_dispatch）
+  · 幂等：同一 case 在 `cooldownMin` 内不重复回收（避免每 5 分钟刷一轮）
+
+用法：
+  python3 scripts/flow_stale.py --flow full                 # dry-run：只看会回收什么
+  python3 scripts/flow_stale.py --flow full --requeue       # 真写（trigger 用这个）
+退出码：0 正常（含无事可做）；2 配置/读取失败
+"""
+from __future__ import annotations
+import argparse, json, pathlib, subprocess, sys, time
+
+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  数据目录唯一判据（勿在此复制链）
+PY = sys.executable
+DEFAULTS = {'enabled': True, 'staleAfterMin': 60, 'maxPerRound': 3, 'requireEnv': True, 'cooldownMin': 30}
+
+
+def cfg(flow: str, key: str):
+    p = subprocess.run([PY, str(HERE / 'flow_config.py'), '--flow', flow, '--get', key],
+                       capture_output=True, text=True)
+    try:
+        return json.loads(p.stdout)
+    except Exception:                                            # noqa: BLE001
+        return None
+
+
+def spec_of(flow: str) -> dict:
+    raw = cfg(flow, 'staleReclaim') or {}
+    if isinstance(raw, dict) and raw.get('enabled') is False:
+        return {'enabled': False}
+    out = {**DEFAULTS, **(raw if isinstance(raw, dict) else {})}
+    return out
+
+
+def last_event_ts(ledger: pathlib.Path, case_id: str) -> float:
+    """该 case 最后一次事件的 ts（用于补算停滞时长）。"""
+    ts = 0.0
+    try:
+        for line in ledger.read_text(encoding='utf-8').splitlines():
+            if not line.strip() or case_id not in line:
+                continue
+            e = json.loads(line)
+            if e.get('caseId') == case_id:
+                ts = max(ts, float(e.get('ts') or 0))
+    except OSError:
+        pass
+    return ts
+
+
+def age_minutes(case: dict, ledger: pathlib.Path, now: float) -> float:
+    """停滞时长（分钟）。
+
+    ⚠️ 不能只看 `case['ageMin']`：triage 对"认领了但从未派发（租约到期）"这类停滞
+    **不带 ageMin**（只给 reason）—— 2026-09-23 实测：只读 ageMin 会把它们当 0 岁，
+    于是阈值判断永远不过、**回收形同虚设**。缺失时用台账里最后一次事件的时间补算。
+    """
+    raw = case.get('ageMin')
+    if raw is not None:
+        try:
+            return float(raw)
+        except (TypeError, ValueError):
+            pass
+    ts = last_event_ts(ledger, str(case.get('caseId') or ''))
+    return (now - ts) / 60 if ts else 1e9      # 台账里也查不到 ⇒ 视为很久（该回收）
+
+
+def last_requeue_ts(ledger: pathlib.Path, case_id: str) -> float:
+    ts = 0.0
+    try:
+        for line in ledger.read_text(encoding='utf-8').splitlines():
+            if not line.strip() or case_id not in line:
+                continue
+            e = json.loads(line)
+            if e.get('caseId') == case_id and e.get('event') == 'requeued':
+                ts = max(ts, float(e.get('ts') or 0))
+    except OSError:
+        pass
+    return ts
+
+
+def pick_stale(plan: dict, spec: dict, ledger: pathlib.Path, now: float = None) -> tuple:
+    """→ (要回收的 case 列表, 说明)。纯函数（便于回归），不写任何东西。"""
+    now = now or time.time()
+    stale = list(((plan.get('plan') or {}).get('stale')) or [])
+    why = []
+    if not stale:
+        return [], '无停滞票'
+    aged = [c for c in stale if age_minutes(c, ledger, now) >= float(spec['staleAfterMin'])]
+    why.append(f"停滞 {len(stale)} 张 → 超 {spec['staleAfterMin']} 分钟 {len(aged)} 张")
+    cool = float(spec.get('cooldownMin') or 0) * 60
+    fresh, held = [], 0
+    for c in aged:
+        ts = last_requeue_ts(ledger, str(c.get('caseId') or ''))
+        if cool and ts and (now - ts) < cool:
+            held += 1
+            continue
+        fresh.append(c)
+    if held:
+        why.append(f"{held} 张在冷却期内（{spec['cooldownMin']} 分钟）")
+    cap = int(spec.get('maxPerRound') or 3)
+    picked = fresh[:cap]
+    if len(fresh) > cap:
+        why.append(f"本轮上限 {cap} 张，其余 {len(fresh) - cap} 张下一轮")
+    return picked, '；'.join(why) or '无可回收'
+
+
+def env_ok(flow: str) -> tuple:
+    p = subprocess.run([PY, str(HERE / 'env_probe.py'), '--flow', flow, '--json'],
+                       capture_output=True, text=True, timeout=90)
+    try:
+        d = json.loads(p.stdout or '{}')
+    except Exception:                                            # noqa: BLE001
+        d = {}
+    if p.returncode == 3:                                        # 流程未声明探针 ⇒ 不拦
+        return True, '未声明环境探针'
+    return p.returncode == 0, d.get('detail') or (p.stderr or '')[:120]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='停滞票自动回收')
+    ap.add_argument('--flow', required=True)
+    ap.add_argument('--requeue', action='store_true', help='真写 requeued 事件（默认 dry-run）')
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+
+    spec = spec_of(a.flow)
+    if not spec.get('enabled'):
+        print(f"  · 流程 {a.flow} 未启用停滞回收（staleReclaim.enabled=false）")
+        return 0
+    ledger = pathlib.Path(cfg(a.flow, 'paths.ledger')
+                          or (pathlib.Path(resolve_data_dir()['dir']) / 'flow-ledger.jsonl'))
+    p = subprocess.run([PY, str(HERE / 'flow_triage.py'), '--flow', a.flow, '--json'],
+                       capture_output=True, text=True, timeout=600)
+    if not (p.stdout or '').strip().startswith('{'):
+        print(f"❌ 取分诊失败：{(p.stderr or p.stdout).strip()[:200]}", file=sys.stderr)
+        return 2
+    plan = json.loads(p.stdout)
+    picked, why = pick_stale(plan, spec, ledger)
+    if not picked:
+        print(f"  · 停滞回收：无需动作（{why}）")
+        return 0
+    if spec.get('requireEnv'):
+        ok, detail = env_ok(a.flow)
+        if not ok:
+            print(f"  ⏸ 停滞回收跳过：环境不可用（{detail}）——回收了也会再 blocked")
+            return 0
+    ids = [str(c.get('caseId')) for c in picked]
+    if not a.requeue:
+        print(f"  [dry-run] 将回收 {len(ids)} 张：{', '.join(ids)}（{why}）")
+        return 0
+    done = []
+    for cid in ids:
+        r = subprocess.run([PY, str(HERE / 'flow_ledger.py'), '--case-id', cid, '--event', 'requeued',
+                            '--by', 'flow-stale', '--detail', f"停滞回收：{why}"],
+                           capture_output=True, text=True)
+        if r.returncode == 0:
+            done.append(cid)
+        else:
+            print(f"  ⚠️ {cid} 回收失败：{(r.stderr or r.stdout).strip()[:120]}", file=sys.stderr)
+    if a.json:
+        print(json.dumps({'flow': a.flow, 'requeued': done, 'reason': why}, ensure_ascii=False))
+    else:
+        print(f"  ✅ 停滞回收 {len(done)} 张：{', '.join(done)}（{why}）")
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())