@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/fix-skill-frontmatter.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""修复/校验仓库技能的 frontmatter（2026-09-11）
+
+**这不是格式洁癖——不合法就是技能根本不生效。** 三处硬性要求都来自
+`dsh-skill-filesystem` → `parseSkillFile()`（0.1.5-rc.1 `lib/index.js:664-695`）：
+
+  ① **首行 `---` + 必须有闭合 `---`**（`parseFrontmatter()`，`:772-798`）。
+     找不到闭合 ⇒ `return undefined` ⇒ 整文件丢弃，只 warn
+     `skill file ... ignored: missing YAML frontmatter`。
+     ⚠️ 隐蔽形态：正文里的水平线 `---` 会被**当成闭合**，中间几十~上百行正文被当 YAML 解析 → 失败 → 同样丢弃。
+
+  ② **`name` 必须是严格小写 kebab-case**（`:685` 调 `isSkillName()`，
+     `@deepseek-ai/dsh-skill` 的 `SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/`）。
+     不合法 ⇒ warn `invalid skill name "…"` ⇒ 丢弃。
+     ⚠️ **中文名（如 `name: 美客多账户健康诊断`）一律非法**；技能目录里显示、`skill` 工具要调用的
+     就是这个名字 ⇒ 人读的标题应放 `description`，或保留在自定义 `title` 字段（加载器不读它）。
+     本脚本把 `name` 归一为**目录名**（与现有可加载技能一致），原标题搬到 `title:`。
+  ③ 另要求 frontmatter **同时含 `name` 与 `description`**（`:679-684`）。
+
+用法：
+  python3 scripts/fix-skill-frontmatter.py --check   # 只报告（门禁/CI 用），有问题 exit 1
+  python3 scripts/fix-skill-frontmatter.py --write    # 就地修复（补闭合 + name 归一为目录名）
+  python3 scripts/fix-skill-frontmatter.py --list     # 列出全部技能状态
+"""
+import pathlib
+import re
+import sys
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'scripts' / 'lib'))
+from stdio_utf8 import use_utf8_stdio  # noqa: E402  出口编码钉 UTF-8（中文 Windows 的 GBK 管道下非 ASCII 会崩）
+SKILLS = ROOT / 'skills'
+REQUIRED = ('name', 'description')
+# 与 @deepseek-ai/dsh-skill 的 SKILL_NAME 完全一致
+NAME_RE = re.compile(r'^[a-z0-9]+(?:-[a-z0-9]+)*$')
+
+
+def closing_line(lines):
+    for i, line in enumerate(lines[1:], start=2):
+        if line.rstrip('\r') == '---':
+            return i
+    return None
+
+
+def first_heading(lines):
+    for i, line in enumerate(lines[1:], start=2):
+        if line.startswith('#'):
+            return i
+    return None
+
+
+def split_frontmatter(text):
+    """返回 (yaml_text, close_line, body)；闭合位置不可信时 yaml_text=None。"""
+    lines = text.split('\n')
+    if not lines or lines[0].rstrip('\r') != '---':
+        return None, None, text
+    close = closing_line(lines)
+    head = first_heading(lines)
+    if close is None or (head is not None and close > head):
+        return None, close, text
+    return '\n'.join(lines[1:close - 1]), close, '\n'.join(lines[close:])
+
+
+def raw_state(text):
+    lines = text.split('\n')
+    close = closing_line(lines)
+    head = first_heading(lines)
+    if close is None or (head is not None and close > head):
+        return {'reason': 'missing-closing-delimiter', 'head': head, 'stray': close}
+    return {'reason': 'ok'}
+
+
+def diagnose(text, expect_name=None):
+    lines = text.split('\n')
+    if not lines or lines[0].rstrip('\r') != '---':
+        return {'ok': False, 'reason': 'no-leading-delimiter'}
+    state = raw_state(text)
+    if state['reason'] != 'ok':
+        head = state['head']
+        return {'ok': False, 'reason': 'missing-closing-delimiter',
+                'head': head, 'stray': state['stray'],
+                'insert_after': (head - 2) if head else None}
+    fm, close, _ = split_frontmatter(text)
+    if yaml is not None:
+        try:
+            data = yaml.safe_load(fm)
+        except Exception as e:
+            return {'ok': False, 'reason': f'invalid-yaml: {e}'}
+        if not isinstance(data, dict):
+            return {'ok': False, 'reason': 'frontmatter-not-a-mapping'}
+        missing = [k for k in REQUIRED if not data.get(k)]
+        if missing:
+            return {'ok': False, 'reason': f'missing-required: {",".join(missing)}'}
+        name = str(data.get('name', ''))
+        if not NAME_RE.match(name):
+            return {'ok': False, 'reason': 'invalid-skill-name', 'name': name}
+        if expect_name is not None and name != expect_name:
+            return {'ok': False, 'reason': 'name-dir-mismatch', 'name': name, 'expect': expect_name}
+        return {'ok': True, 'close': close, 'name': name}
+    return {'ok': True, 'close': close, 'name': None}
+
+
+def fix(text, dir_id):
+    """返回 (新文本, [修复说明])。"""
+    notes = []
+    # ① 先补闭合
+    state = raw_state(text)
+    if state['reason'] == 'missing-closing-delimiter':
+        lines = text.split('\n')
+        head = state['head']
+        j = head - 2
+        while j >= 1 and lines[j].strip() == '':
+            j -= 1
+        lines = lines[:j + 1] + ['---'] + lines[j + 1:]
+        text = '\n'.join(lines)
+        notes.append('补闭合 `---`（原先命中的是正文水平线）' if state['stray'] is not None else '补闭合 `---`')
+    # ② 再归一 name
+    fm, close, _ = split_frontmatter(text)
+    if fm is None:
+        return text, notes + ['⚠️ 仍无法定位 frontmatter，需人工处理']
+    lines = text.split('\n')
+    name_idx = old_name = title_idx = None
+    for i in range(1, close - 1):
+        m = re.match(r'^name:\s*(.*)$', lines[i])
+        if m:
+            name_idx, old_name = i, m.group(1).strip().strip('"').strip("'")
+        if re.match(r'^title:\s*', lines[i]):
+            title_idx = i
+    if name_idx is None:
+        anchor = 1
+        while anchor < close - 1 and not re.match(r'^id:\s*', lines[anchor]):
+            anchor += 1
+        if anchor >= close - 1:
+            anchor = 1
+        lines.insert(anchor + 1, f'name: {dir_id}')
+        notes.append(f'补 `name: {dir_id}`')
+    elif old_name != dir_id:
+        lines[name_idx] = f'name: {dir_id}'
+        notes.append(f'`name: {old_name}` → `name: {dir_id}`')
+        if title_idx is None and old_name:
+            lines.insert(name_idx + 1, f'title: {old_name}')
+            notes.append(f'原标题保留为 `title: {old_name}`')
+    return '\n'.join(lines), notes
+
+
+def iter_skills():
+    if not SKILLS.is_dir():
+        return
+    for d in sorted(SKILLS.iterdir()):
+        f = d / 'SKILL.md'
+        if d.is_dir() and f.is_file():
+            yield d.name, f
+
+
+def main():
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    mode = '--list' if '--list' in sys.argv else ('--write' if '--write' in sys.argv else '--check')
+    bad, fixed, total = [], [], 0
+    for name, path in iter_skills():
+        total += 1
+        text = path.read_text()
+        d = diagnose(text, expect_name=name)
+        if d['ok']:
+            if mode == '--list':
+                print(f'  ✅ {name}')
+            continue
+        bad.append((name, d))
+        if mode == '--write':
+            new, notes = fix(text, name)
+            path.write_text(new)
+            again = diagnose(new, expect_name=name)
+            if again['ok']:
+                fixed.append((name, notes))
+            else:
+                print(f'  ❌ {name}: 修复后仍不合法（{again["reason"]}）')
+        elif mode == '--list':
+            print(f'  ❌ {name}: {d["reason"]}' + (f'（name={d.get("name")!r}）' if d.get('name') else ''))
+            if d.get('insert_after'):
+                print(f'       应插在第 {d["insert_after"]} 行后')
+
+    if mode == '--write':
+        for name, notes in fixed:
+            print(f'  ✅ {name}: ' + '；'.join(notes))
+        print(f'修复 {len(fixed)}/{len(bad)} 个')
+        return 0 if len(fixed) == len(bad) else 1
+
+    if mode == '--list':
+        return 0
+
+    if bad:
+        print(f'❌ {len(bad)} 个技能 frontmatter 不合法（这些技能**不会被加载**）：')
+        for name, d in bad:
+            extra = f'（name={d.get("name")!r}）' if d.get('name') else ''
+            if d.get('insert_after'):
+                extra += f'（应插在第 {d["insert_after"]} 行后）'
+            print(f'  - {name}: {d["reason"]}{extra}')
+        print('\n修法：python3 scripts/fix-skill-frontmatter.py --write')
+        return 1
+    print(f'✅ 全部 {total} 个技能 frontmatter 合法（闭合 + name 为 kebab-case 且等于目录名 + description）')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/engine/scripts/flow-auto-retry.py

@@ -0,0 +1,454 @@
+#!/usr/bin/env python3
+"""flow-auto-retry —— 流程失败「可用性类」的**受守卫自动重试**（用户口径方案 a；2026-10-13）。
+
+背景（真实现场）：可用性类失败（网络/限流/浏览器瞬时类）会落到台账 `failed` → `blocked`，
+此后触发器只报"需人工"，**不再自动跑**（现场两条票是人工手跑回来的）。用户拍板方案 (a)：
+这类失败在**上限 + 冷却**约束下自动重试，而不是等人工。
+
+⛔ 本脚本**不写表**：真正"重置后重建"的动作全部委托 `scripts/flow_retry.py`
+（走它的**全部**守卫：分类闸门 / 预约闸门 / 次数上限 / 写前整行备份 + 写后读回 + 审计 + 台账 `retry`）。
+本脚本只做**候选筛选 + 每轮限流 + 冷却 + 可见性**。
+
+候选（缺任一条 ⇒ **跳过并说明原因**，绝不"差不多就重试"）：
+  ① 台账末条**状态性**事件 ∈ {failed, blocked}（已重试过的票末条是 retry ⇒ 不再筛进来，天然防重入）；
+     末条若是 `phase`/`wake` 这类**信息性**事件，回退到最近一条状态性事件（与 `flow_triage` 同一口径）；
+  ② 唯一分类器 `scripts/flow_failure.py#classify` 判 **retryable**（⛔ 无 override：
+     业务类/门户状态类一律跳过、保持需人工）；
+  ③ 预约闸门 `scripts/flow_retry.py#appointment_gate` 放行（无预约残留 / 无"预约取消失败"留痕）；
+  ④ **尝试**次数 < 上限（台账 `retry` 事件数 + 被委托侧拒绝的次数 —— 后者也要算，
+     否则一张"每轮都会被拒"的票会永远每轮白占名额/白刷卡片）；
+  ⑤ 距末条 failed/blocked ≥ 冷却分钟数；
+  ⑥ 每轮最多处理 N 票（避免风暴）。
+四个量（上限/冷却/每轮上限/开关）全部来自 `scripts/flow_config.py#autoRetry`（唯一读取点），
+可用 `--max` / `--cooldown-min` / `--per-cycle` 覆盖（运维/夹具用）。
+
+可见性：审计 JSONL（`<台账同目录>/flow-auto-retry-audit.jsonl`，每**真做**的一次重试一行）
+  + 台账（由 `flow_retry` 写的那条 `retry`，其 `detail` 带 `by=flow-auto-retry`）
+  + **一条**内部群卡片（复用既有通知路径 `scripts/feishu-card.mjs`；按轮汇总，⛔ 一票一条 = 噪音）。
+
+⚠️ **为什么本脚本不自己另写一条 `retry` 台账事件**（口径说明，⛔ 勿"顺手改回"）：
+  `scripts/flow_triage.py` 的"人工放行重跑"闸门（Rule R）把**末条 `retry` 事件的 `by`**
+  当作判据之一（必须是 `flow_retry`）。若自动重试再追加一条 `by=flow-auto-retry` 的 retry 事件，
+  它就成为**末条** ⇒ 该票下一轮**既进不了 `to_dispatch`**、又落进"分诊未归类"兜底（需人工）
+  = 自动重试白做。⇒ 一次重试**只**由 `flow_retry` 记**恰好一条**；本脚本的署名落在
+  它的 `--reason`（进台账 `detail`）与自己的审计 JSONL / 卡片 / 日志里。
+
+用法：
+  python3 scripts/flow-auto-retry.py --flow full                     # **dry-run**（默认；只打印将重试谁与原因）
+  python3 scripts/flow-auto-retry.py --flow full --yes               # 真做（走 flow_retry 全部守卫）
+  … --max 2 --cooldown-min 20 --per-cycle 2 --only full__<rec> --no-notify --json
+退出码：0 正常（含"无候选 / 全部跳过 / 已关闭"）；2 前置不可用（配置或判据实现取不到 ⇒ 绝不猜）。
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import pathlib
+import shutil
+import subprocess
+import sys
+import time
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+
+import flow_config  # noqa: E402  唯一配置读取点（四个量的默认值只在它里面）
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+# 信息性事件（只带说明、不改变票据工作状态）⇒ 判据要回退到最近一条**状态性**事件。
+# 逐条口径与 `scripts/flow_triage.py#INFO_EVENTS` 一致（2026-10-09 P0：末条 `phase` 曾让票静默消失）。
+INFO_EVENTS = ('phase', 'wake', 'policy_apply', 'policy_new')
+FAIL_EVENTS = ('failed', 'blocked')
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 判据实现：**只**从既有模块取（⛔ 本脚本不自写第二套分类/闸门规则）
+# ══════════════════════════════════════════════════════════════════════════
+def load_judges() -> tuple:
+    """取（分类器, 规范原因, 预约闸门, 失败步骤）。任一取不到 ⇒ 抛错（调用方停住）。"""
+    try:
+        from flow_failure import classify, canonical_reason      # noqa: PLC0415
+    except Exception as exc:                                     # noqa: BLE001
+        raise RuntimeError(f'失败分类器不可用（{exc}）—— 判据只能有一份，⛔ 本脚本不自写第二套')
+    try:
+        from flow_retry import appointment_gate, last_failed_step  # noqa: PLC0415
+    except Exception as exc:                                     # noqa: BLE001
+        raise RuntimeError(f'预约闸门不可用（{exc}）—— 有违约金风险，⛔ 缺闸门时绝不自动重试')
+    return classify, canonical_reason, appointment_gate, last_failed_step
+
+
+def load_auto_retry_cfg(flow_id: str):
+    """四个量的**唯一读取点** = `flow_config.load_config(...)['autoRetry']`；读不到 ⇒ None（响亮）。"""
+    try:
+        cfg = flow_config.load_config(flow_id, strict=False)
+    except Exception as exc:                                     # noqa: BLE001
+        print(f'❌ 读不到流程配置（{exc}）⇒ 不猜默认值，本轮不做', file=sys.stderr)
+        return None
+    ar = cfg.get('autoRetry')
+    if not isinstance(ar, dict) or 'enabled' not in ar:
+        print('❌ 配置读取点里没有 autoRetry 段（flow_config.py 版本过旧或投递不完整）'
+              '⇒ 本轮不做（⛔ 不自带第二份默认值）', file=sys.stderr)
+        return None
+    return ar, str(cfg.get('flowId') or flow_id)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 台账读取（只读）
+# ══════════════════════════════════════════════════════════════════════════
+def read_events(path: pathlib.Path) -> list:
+    """读 JSONL 台账（坏行跳过）。读失败 ⇒ 抛 OSError（由 main 收口成 exit 2，⛔ 不当作"无候选"）。"""
+    out = []
+    if not path.exists():
+        return out
+    for ln in path.read_text(encoding='utf-8').splitlines():
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            e = json.loads(ln)
+        except Exception:                                        # noqa: BLE001
+            continue
+        if isinstance(e, dict) and e.get('caseId'):
+            out.append(e)
+    return out
+
+
+def case_prefixes(flow_id: str, canonical: str) -> tuple:
+    """该流程在台账里可能出现的**全部** caseId 前缀（规范 id 优先 + 旧短名）。
+
+    台账里写的是"当时那条流程叫什么"：落位前的短名与落位后的规范 id 并存 ⇒ 只认一个会让
+    另一半 case **集体消失**。首选引擎的规范实现（`flow_failure.case_prefixes`，它同时覆盖别名），
+    取不到时**保守**用调用方给的两个名字（老克隆兜底）。
+    """
+    names = [n for n in (canonical, flow_id) if n]
+    try:
+        from flow_failure import case_prefixes as _engine_prefixes  # noqa: PLC0415
+        names.extend(_engine_prefixes(canonical or flow_id))
+    except Exception:                                            # noqa: BLE001
+        pass
+    return tuple(sorted({f'{n}__' for n in names}, key=len, reverse=True))
+
+
+def effective_last(evs: list) -> tuple:
+    """(有效末条事件, 回退掉的信息性事件名)。信息性事件不改变票据状态 ⇒ 判定回退到状态性事件。"""
+    last_state, tail = None, ''
+    for e in evs:
+        ev = str(e.get('event') or '')
+        if ev in INFO_EVENTS:
+            tail = ev
+            continue
+        last_state, tail = e, ''
+    return last_state, tail
+
+
+def retry_count(events: list, case_id: str) -> int:
+    """该 case 的 `retry` 事件数（= **成功重建过几次**）。
+
+    ⚠️ 判据必须与 `flow_retry.retry_count()` **逐字同口径**（同一条 `event == 'retry'`）：
+    本脚本先筛、`flow_retry` 再守 —— 两处口径若不同，就会出现"我说该重试、它拒绝"的空转。
+    """
+    return sum(1 for e in events
+               if str(e.get('caseId') or '') == case_id and str(e.get('event') or '') == 'retry')
+
+
+def refused_count(audit_path: pathlib.Path, case_id: str) -> int:
+    """该 case **被委托侧拒绝过几次**（读本脚本自己的审计：`ok:false` 的那些行）。
+
+    为什么上限要把它算进去：委托侧拒绝时**不会**写台账 `retry` 事件 ⇒ 只看台账事件数的话，
+    一张"每轮都会被拒"的票（表里状态已不是失败 / 表备注分类不是可用性类 / 表备注的预约留痕
+    与台账不一致…）会**每轮**白占一个每轮名额、白刷一条卡片与一行审计，直到永远。
+    把"拒绝"也算作一次尝试 ⇒ 最多 `max` 次之后就明确交人工（日志点名原因）。
+    """
+    if not audit_path.exists():
+        return 0
+    n = 0
+    try:
+        for ln in audit_path.read_text(encoding='utf-8').splitlines():
+            ln = ln.strip()
+            if not ln:
+                continue
+            try:
+                e = json.loads(ln)
+            except Exception:                                    # noqa: BLE001
+                continue
+            if str(e.get('caseId') or '') == case_id and e.get('ok') is False:
+                n += 1
+    except OSError:
+        return 0
+    return n
+
+
+def plain_text(last: dict, canonical_reason) -> str:
+    """候选的失败文本（给分类器与预约闸门）：`reason`（规范原因）→ `error` → `detail`，全并起来。"""
+    parts = [str(last.get('reason') or '').strip()]
+    err = str(last.get('error') or '').strip()
+    if err:
+        try:
+            err = canonical_reason(err)                          # 剥身份前缀，与表备注同源同文
+        except Exception:                                        # noqa: BLE001
+            pass
+        parts.append(err)
+    parts.append(str(last.get('detail') or '').strip())
+    return ' '.join([p for p in parts if p]).strip()
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 四道闸门（逐个独立函数：既便于读，也便于门禁做"**去掉它就必须判红**"的有牙自证）
+# ══════════════════════════════════════════════════════════════════════════
+def check_classification(ctx: dict):
+    """② 可用性类判据：**只**认唯一分类器的 `retryable`（⛔ 无 override）。"""
+    kind = str((ctx.get('kind') or {}).get('kind') or '')
+    if kind != 'retryable':
+        return f"分类={kind}（{(ctx.get('kind') or {}).get('reason') or ''}）⇒ 非可用性类（业务/门户状态类），保持需人工"
+    return None
+
+
+def check_appointment(ctx: dict):
+    """③ 预约闸门：无残留才允许重建（有预约未取消 ⇒ 违约金）。"""
+    gate = ctx.get('gate') or {}
+    if not gate.get('ok'):
+        return f"预约闸门拒绝（{gate.get('why') or '证据不足'}）"
+    return None
+
+
+def check_upper_bound(ctx: dict):
+    """④ 次数上限：**尝试**次数（台账 `retry` 事件 + 被委托侧拒绝的次数）< 上限。"""
+    n = int(ctx.get('retryCount') or 0) + int(ctx.get('refusedCount') or 0)
+    mx = int(ctx['cfg']['max'])
+    if n >= mx:
+        r = int(ctx.get('refusedCount') or 0)
+        return f'已达上限（{n}/{mx}{f"，其中 {r} 次被委托侧拒绝" if r else ""}）⇒ 交人工'
+    return None
+
+
+def check_cooldown(ctx: dict):
+    """⑤ 冷却：距末条 failed/blocked 必须 ≥ 冷却分钟数。"""
+    left = float(ctx.get('cooldownLeftSec') or 0)
+    if left > 0:
+        return f'冷却未到（还需约 {int((left + 59) // 60)} 分钟）⇒ 交人工'
+    return None
+
+
+# ⛔ `CHECKS` 是**四道闸门的唯一清单**（门禁 `scripts/tests/flow-auto-retry.test.mjs` 靠替换它
+# 做"去掉某道闸门 ⇒ 夹具必须判红"的有牙自证 —— 改这个元组等于改判据强度，必须同时改用例）。
+CHECKS = (check_classification, check_appointment, check_upper_bound, check_cooldown)
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 动作：委托 flow_retry（**不自己写表**）+ 审计 + 通知
+# ══════════════════════════════════════════════════════════════════════════
+def do_retry(flow_id: str, ctx: dict, cfg: dict) -> dict:
+    """委托 `flow_retry.py --yes`（走它全部守卫），返回 `{exit, ok, cmd, out}`。"""
+    n = int(ctx.get('retryCount') or 0)
+    reason = (f"自动重试（by=flow-auto-retry）第 {n + 1}/{cfg['max']} 次："
+              f"{(ctx.get('kind') or {}).get('reason') or ''}")
+    cmd = [sys.executable, str(HERE / 'flow_retry.py'), '--flow', flow_id, '--case', ctx['caseId'],
+           '--yes', '--max', str(cfg['max']), '--reason', reason]
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    out = f"{p.stdout or ''}{p.stderr or ''}".strip()
+    return {'exit': int(p.returncode), 'ok': int(p.returncode) == 0, 'cmd': cmd, 'out': out}
+
+
+def audit(audit_path: pathlib.Path, rec: dict) -> None:
+    """追加一行审计（0600 由目录/文件默认权限决定；⛔ 不写业务值以外的敏感内容）。"""
+    try:
+        audit_path.parent.mkdir(parents=True, exist_ok=True)
+        with audit_path.open('a', encoding='utf-8') as fh:
+            fh.write(json.dumps(rec, ensure_ascii=False) + '\n')
+    except Exception as exc:                                     # noqa: BLE001
+        print(f'  ⚠️ 审计未落盘（{exc}）', file=sys.stderr)
+
+
+def notify_card(flow_id: str, rows: list, cfg: dict) -> bool:
+    """**一条**内部群卡片（按轮汇总）。返回是否真发出。⛔ 通知失败不影响已做的重试（只告警）。"""
+    if not rows:
+        return False
+    script = HERE / 'feishu-card.mjs'
+    if not script.exists():
+        print('  ⚠️ 通知未发：缺少 scripts/feishu-card.mjs（旧版本）——见日志里的重试记录')
+        return False
+    node = shutil.which('node') or 'node'
+    cases = '、'.join(str(r['caseId']) for r in rows)[:200]
+    errs = '；'.join(f"{r['caseId']}：{str(r.get('why') or '')[:60]}" for r in rows)[:300]
+    args = [node, str(script), '--template', 'failure-alert', '--to', 'internal',
+            '--flow', flow_id, '--level', 'retryable', '--case', cases,
+            '--attempt', str(max(int(r.get('attempt') or 1) for r in rows)), '--max', str(cfg['max']),
+            '--error', errs or '可用性类失败（分类 retryable）',
+            '--action', '已自动重置重建（走 flow_retry 全部守卫）；下一轮认领会自动跑，无需人工介入',
+            '--send']
+    try:
+        p = subprocess.run(args, capture_output=True, text=True, timeout=90)
+    except Exception as exc:                                     # noqa: BLE001
+        print(f'  ⚠️ 通知未发（{exc}）——已做的重试不受影响')
+        return False
+    if p.returncode != 0:
+        print(f"  ⚠️ 通知未发（exit={p.returncode}）：{(p.stderr or p.stdout or '').strip()[:200]}")
+        return False
+    print(f"  🔔 已发一条内部群卡片（本轮自动重试 {len(rows)} 票）")
+    return True
+
+
+# ══════════════════════════════════════════════════════════════════════════
+# 主流程
+# ══════════════════════════════════════════════════════════════════════════
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='失败自动重试（可用性类；受守卫、默认 dry-run）')
+    ap.add_argument('--flow', default='full', help='流程 id（缺省 full）')
+    ap.add_argument('--ledger', default=str(DATA_DIR / 'flow-ledger.jsonl'), help='台账路径（缺省=数据目录）')
+    ap.add_argument('--yes', '--apply', dest='yes', action='store_true', help='真做（缺省 dry-run）')
+    ap.add_argument('--max', type=int, help='每票上限（覆盖 flow_config autoRetry.max）')
+    ap.add_argument('--cooldown-min', type=int, help='冷却分钟（覆盖 autoRetry.cooldownMin）')
+    ap.add_argument('--per-cycle', type=int, help='每轮最多处理几票（覆盖 autoRetry.perCycle）')
+    ap.add_argument('--only', help='只处理这一个 case（精确匹配 caseId）')
+    ap.add_argument('--no-notify', action='store_true', help='不发通知（日志与审计照旧）')
+    ap.add_argument('--now', type=float, help='覆盖"当前时间"（epoch 秒；仅测试/排障）')
+    ap.add_argument('--json', action='store_true', help='机器可读输出（夹具/巡检用）')
+    a = ap.parse_args(argv)
+
+    try:
+        classify, canonical_reason, appointment_gate, last_failed_step = load_judges()
+    except RuntimeError as exc:
+        print(f'❌ {exc}', file=sys.stderr)
+        return 2
+
+    loaded = load_auto_retry_cfg(a.flow)
+    if loaded is None:
+        return 2
+    ar, canonical = loaded
+    cfg = {
+        'enabled': bool(ar.get('enabled')),
+        'max': int(a.max if a.max is not None else ar.get('max')),
+        'cooldownMin': int(a.cooldown_min if a.cooldown_min is not None else ar.get('cooldownMin')),
+        'perCycle': int(a.per_cycle if a.per_cycle is not None else ar.get('perCycle')),
+    }
+    if cfg['max'] < 1 or cfg['perCycle'] < 1 or cfg['cooldownMin'] < 0:
+        print(f'❌ 取值非法: {cfg}（max/perCycle ≥ 1、cooldownMin ≥ 0）', file=sys.stderr)
+        return 2
+
+    ledger = pathlib.Path(a.ledger)
+    audit_path = ledger.parent / 'flow-auto-retry-audit.jsonl'
+    now = float(a.now if a.now is not None else time.time())
+    dry = not a.yes
+
+    result = {'flow': a.flow, 'canonical': canonical, 'dryRun': bool(dry), 'enabled': cfg['enabled'],
+              'limits': {k: cfg[k] for k in ('max', 'cooldownMin', 'perCycle')},
+              'ledger': str(ledger), 'audit': str(audit_path),
+              'candidates': [], 'retried': [], 'notified': False}
+
+    if not cfg['enabled']:
+        print(f"  流程 {a.flow}：自动重试**已关闭**（flow_config autoRetry.enabled=false）⇒ 本轮不做")
+        if a.json:
+            print(json.dumps(result, ensure_ascii=False))
+        return 0
+
+    print(f"  流程 {a.flow}（规范 id={canonical}）｜自动重试：开｜每票上限 {cfg['max']}"
+          f"｜冷却 {cfg['cooldownMin']} 分｜每轮上限 {cfg['perCycle']}｜台账 {ledger}")
+    if ledger.parent != DATA_DIR:
+        print(f"  ⚠️ 台账父目录({ledger.parent}) ≠ 数据目录({DATA_DIR})：委托的 flow_retry 仍写数据目录那份")
+
+    try:
+        events = read_events(ledger)
+    except OSError as exc:
+        print(f'❌ 台账读不到（{exc}）⇒ 本轮不做（⛔ 不把"读不到"当作"无候选"）', file=sys.stderr)
+        return 2
+
+    prefixes = case_prefixes(a.flow, canonical)
+    by_case: dict = {}
+    for e in events:
+        cid = str(e.get('caseId') or '')
+        if any(cid.startswith(p) for p in prefixes):
+            by_case.setdefault(cid, []).append(e)
+
+    # ── 候选筛选（末条**状态性**事件 ∈ {failed, blocked}）──────────────────────
+    cands = []
+    for cid, evs in by_case.items():
+        evs.sort(key=lambda e: (e.get('ts') or 0))
+        last, tail = effective_last(evs)
+        if last is None or str(last.get('event') or '') not in FAIL_EVENTS:
+            continue
+        if a.only and cid != a.only:
+            continue
+        cands.append((cid, last, tail))
+    # 先到先处理（最久没被处置的排在前面）：与"每轮上限"配合时不会让某张票永远排不上
+    cands.sort(key=lambda x: float(x[1].get('ts') or 0))
+    n_tail = len([c for c in cands if c[2]])
+    if n_tail:
+        print(f"  （其中 {n_tail} 张的末条是信息性事件，已按上一状态性事件判定）")
+    print(f"  候选 {len(cands)} 张（末条 failed/blocked）")
+
+    retried_rows = []
+    for cid, last, _tail in cands:
+        if len(retried_rows) >= cfg['perCycle']:
+            break
+        ts = float(last.get('ts') or 0)
+        text = plain_text(last, canonical_reason)
+        kind = classify(text)
+        record = cid.split('__', 1)[1] if '__' in cid else cid
+        gate = appointment_gate(text, last_failed_step(record))
+        ctx = {
+            'caseId': cid, 'cfg': cfg, 'kind': kind, 'gate': gate, 'text': text,
+            'retryCount': retry_count(events, cid),
+            'refusedCount': refused_count(audit_path, cid),
+            'cooldownLeftSec': max(0.0, cfg['cooldownMin'] * 60 - (now - ts)) if ts else 0.0,
+        }
+        skip = None
+        for check in CHECKS:
+            skip = check(ctx)
+            if skip:
+                break
+        tried = ctx['retryCount'] + ctx['refusedCount']
+        row = {'caseId': cid, 'attempt': tried + 1, 'retryCount': ctx['retryCount'],
+               'refusedCount': ctx['refusedCount'],
+               'kind': str(kind.get('kind') or ''), 'ts': int(ts),
+               'cooldownLeftSec': int(ctx['cooldownLeftSec']), 'gate': str(gate.get('why') or '')}
+        if skip:
+            row.update({'decision': 'skip', 'why': skip})
+            print(f"    · {cid}  ⏭ 跳过：{skip}")
+            result['candidates'].append(row)
+            continue
+        refused_note = f"（其中 {ctx['refusedCount']} 次被委托侧拒绝）" if ctx['refusedCount'] else ''
+        row.update({'decision': 'retry',
+                    'why': f"分类=retryable｜预约闸门放行（{gate.get('why')}）"
+                           f"｜已尝试 {tried}/{cfg['max']} 次{refused_note}｜冷却已过"})
+        result['candidates'].append(row)
+        if dry:
+            print(f"    · {cid}  ▶ [dry-run] 将自动重试（第 {row['attempt']}/{cfg['max']} 次）：{row['why']}")
+            continue
+        print(f"    · {cid}  ▶ 自动重试（第 {row['attempt']}/{cfg['max']} 次）：{row['why']}")
+        got = do_retry(a.flow, ctx, cfg)
+        for line in (got['out'] or '').splitlines():
+            print(f'        {line}')
+        row['exit'] = got['exit']
+        row['ok'] = got['ok']
+        retried_rows.append(row)
+        audit(audit_path, {
+            'at': datetime.datetime.now().isoformat(timespec='seconds'),
+            'flow': a.flow, 'canonical': canonical, 'caseId': cid, 'action': 'auto-retry',
+            'by': 'flow-auto-retry', 'attempt': row['attempt'], 'max': cfg['max'],
+            'classification': row['kind'], 'appointmentGate': row['gate'],
+            'reason': text[:200], 'delegated': 'flow_retry.py', 'exit': got['exit'], 'ok': got['ok'],
+            'auditFile': str(audit_path), 'ledger': str(ledger),
+        })
+        if not got['ok']:
+            print(f"      ⚠️ 本次未成功（exit={got['exit']}）⇒ 该票保持原状，等人工/下一轮（不重试本次）")
+
+    result['retried'] = retried_rows
+    ok_n = len([r for r in retried_rows if r.get('ok')])
+    if dry:
+        will = len([r for r in result['candidates'] if r['decision'] == 'retry'])
+        print(f"  [dry-run] 未写入：将自动重试 {will} 票（上限 {cfg['perCycle']}）；加 --yes 才落库"
+              if will else f"  [dry-run] 无票可自动重试（跳过 {len(result['candidates'])} 张，原因见上）")
+    else:
+        print(f"  完成：自动重试 {len(retried_rows)} 票（成功 {ok_n}）｜审计 {audit_path}")
+        if retried_rows and not a.no_notify:
+            result['notified'] = bool(notify_card(a.flow, retried_rows, cfg))
+    if a.json:
+        print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())