@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/verticals/mercadolibre/preflight.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""美客多业务线 · 验收自检段（P2a 起接进 `customer-preflight.py`）。
+
+契约（与平台预检一致，见 `verticals/README.md`）：
+
+    checks(env: dict) -> list[(名称, 级别 ok|warn|fail, 说明, 修复建议)]
+
+规矩：**只读探测**、不写客户数据、缺凭据要能区分"没配"与"配了没权限"。
+本文件由 `customer-preflight.py#check_verticals` 调用（每台机器都会跑）。
+"""
+from __future__ import annotations
+
+import pathlib
+
+VERT = 'mercadolibre'
+FLOWS = ['full', 'wenyao-invoice', 'xzh-invoice', 'daily-report']
+# 该线用到的基础设施与凭据文件（env 规范位置优先、旧平铺兜底 —— 迁移期两种都存在）
+ENV_FILES = ['fulfillment.env', 'daily-report.env', 'wenyao.env', 'ziniao-webdriver.env']
+ADAPTERS = ['wenyao', 'xzh']
+SKILL_DIRS = ['ml-fulfillment-sop', 'ml-invoice', 'ml-invoice-xzh', 'ml-store-daily-report', 'ml-config-guide']
+
+
+def _resolve(paths: list[pathlib.Path]) -> pathlib.Path | None:
+    for p in paths:
+        if p.exists():
+            return p
+    return None
+
+
+def _load_registry(repo: pathlib.Path) -> dict:
+    import sys
+    sys.path.insert(0, str(repo / 'scripts'))
+    from flow_registry import load_doc          # noqa: PLC0415 —— 延迟导入：预检要在半坏机器上也能跑
+    return load_doc()
+
+
+def _resolved_data_dir(repo: pathlib.Path) -> pathlib.Path:
+    """数据目录：**唯一判据**在 `<repo>/scripts/lib/argent_datadir.py`（三级链，与 JS 内核同语义）。
+
+    ⛔ 不在这里写第二条链：取不到就抛，由 `checks()` 记成 **fail** —— 自检脚本绝不能
+    猜目录（猜错方向就是"自检绿灯、直跑却写生产"）。
+    """
+    import sys
+    sys.path.insert(0, str(repo / 'scripts' / 'lib'))
+    from argent_datadir import resolve_data_dir          # noqa: PLC0415 —— 延迟导入：半坏机器上也要能跑
+    return pathlib.Path(resolve_data_dir()['dir'])
+
+
+def checks(env: dict) -> list[tuple[str, str, str, str]]:
+    repo = pathlib.Path(env.get('repo') or pathlib.Path(__file__).resolve().parents[2])
+    out: list[tuple[str, str, str, str]] = []
+    # ⓪ 数据目录判据可用性（下面 ③④ 依赖它；缺判据 ⇒ 直接 fail，不猜目录）
+    data_dir = None
+    if env.get('data_dir'):
+        data_dir = pathlib.Path(env['data_dir'])
+    else:
+        try:
+            data_dir = _resolved_data_dir(repo)
+            out.append(('datadir', 'ok', f'{data_dir}', '—'))
+        except Exception as exc:                                        # noqa: BLE001
+            out.append(('datadir', 'fail', f'数据目录判据不可用：{exc}',
+                        '确认 <repo>/scripts/lib/argent_datadir.py 存在（git pull / 重装后重试）'))
+
+    # ① 注册表：本线流程能被合并出来（含别名解析）
+    doc: dict = {'flows': {}, 'capabilities': {}}
+    try:
+        doc = _load_registry(repo)
+        missing = [f'{VERT}.{f}' for f in FLOWS if f'{VERT}.{f}' not in (doc.get('flows') or {})]
+        if missing:
+            out.append(('registry', 'fail', f'注册表缺流程 {missing}',
+                        '跑 python3 scripts/flow_registry.py --check 看合并冲突'))
+        else:
+            out.append(('registry', 'ok', f'{len(FLOWS)} 条流程在注册表（{", ".join(FLOWS)}）', '—'))
+    except Exception as exc:                                            # noqa: BLE001
+        out.append(('registry', 'fail', f'注册表合并失败：{exc}', '跑 python3 scripts/flow_registry.py --check'))
+
+    # ② 提示词：注册表声明优先（业务线落位后在 verticals/<id>/prompts/）
+    for f in FLOWS:
+        rel = (((doc.get('flows') or {}).get(f'{VERT}.{f}') or {}).get('trigger') or {}).get('promptTemplate')
+        if not rel:
+            out.append((f'prompt.{f}', 'warn', '注册表未声明 trigger.promptTemplate', '补 verticals/<id>/flows.json'))
+            continue
+        if _resolve([repo / rel, repo / 'scripts' / rel]):
+            out.append((f'prompt.{f}', 'ok', f'提示词就位（{rel}）', '—'))
+        else:
+            out.append((f'prompt.{f}', 'fail', f'提示词缺失：{rel}', '确认能力包/仓库带上 verticals/<id>/prompts/'))
+
+    # ③ env 凭据：规范位置优先、旧平铺兜底（数据目录判据不可用时跳过 —— 已在 ⓪ 记 fail）
+    if data_dir is not None:
+        for name in ENV_FILES:
+            hit = _resolve([data_dir / 'verticals' / VERT / 'env' / name, data_dir / name])
+            if hit:
+                where = '规范位置' if 'verticals' in str(hit) else '旧平铺（退休待办）'
+                out.append((f'env.{name}', 'ok', f'{name} 可读（{where}）', '—'))
+            else:
+                out.append((f'env.{name}', 'warn', f'缺 {name}', f'放 {data_dir}/verticals/{VERT}/env/{name}（600）'))
+
+    # ④ 暂停开关：报告位置（新开关=规范；旧开关仍在=退休待办）
+    if data_dir is not None:
+        new_sw = sorted((data_dir / 'verticals' / VERT).glob('PAUSE.*'))
+        old_sw = [n for n in ('PAUSE_POLL', 'PAUSE_FLOW_TRIGGER', 'PAUSE_INVOICE', 'PAUSE_DAILY_REPORT') if (data_dir / n).exists()]
+        if len(new_sw) == len(FLOWS):
+            note = f'{len(new_sw)} 个新开关' + (f'；旧开关仍在（{len(old_sw)} 个，退休待办）' if old_sw else '')
+            out.append(('pauseSwitches', 'ok', note, '确认新开关生效后删旧开关'))
+        elif new_sw:
+            out.append(('pauseSwitches', 'warn', f'只找到 {len(new_sw)}/{len(FLOWS)} 个新开关',
+                        '跑 node scripts/migrate-verticals-ml.mjs --apply'))
+        else:
+            out.append(('pauseSwitches', 'info', f'未建新开关（旧开关 {len(old_sw)} 个）',
+                        '若该机器仍按旧开关控制，迁移时跑 migrate-verticals-ml.mjs'))
+
+    # ⑤ 货代适配器（P4 端口化前仍在引擎侧）
+    for name in ADAPTERS:
+        hit = _resolve([repo / 'verticals' / VERT / 'adapters' / name / 'adapter.py',
+                        repo / 'scripts' / 'integrations' / name / 'adapter.py'])
+        if hit:
+            out.append((f'adapter.{name}', 'ok', f'适配器就位（{hit.parent.name}）', '—'))
+        else:
+            out.append((f'adapter.{name}', 'fail', f'缺适配器 {name}', f'补 verticals/{VERT}/adapters/{name}/adapter.py'))
+
+    # ⑥ 技能：提示词里点名的技能要真的存在（仓库或已安装目录）
+    skill_root = pathlib.Path.home() / '.dsh' / 'skills'
+    for sk in SKILL_DIRS:
+        if (repo / 'skills' / sk / 'SKILL.md').exists() or (skill_root / sk / 'SKILL.md').exists():
+            out.append((f'skill.{sk}', 'ok', '技能就位', '—'))
+        else:
+            out.append((f'skill.{sk}', 'warn', f'技能未安装：{sk}',
+                        '跑安装器同步技能（或检查 frontmatter 是否合法）'))
+
+    # ⑦ 写路径白名单：发票能力必须声明（回写器按它拒绝一切白名单外的写入）
+    cap = ((doc.get('capabilities') or {}).get('invoice') or {})
+    if cap.get('writeFields'):
+        out.append(('writeFields.invoice', 'ok', f'写白名单 {len(cap["writeFields"])} 列', '—'))
+    else:
+        out.append(('writeFields.invoice', 'fail', '注册表未声明 capabilities.invoice.writeFields',
+                    '补注册表（白名单缺失会让回写器拒绝一切写入）'))
+
+    return out
+
+
+if __name__ == '__main__':
+    for name, level, msg, fix in checks({}):
+        print(f'[{level}] {name}: {msg} → {fix}')

package/engine/verticals/mercadolibre/prompts/daily-report.failure.md

@@ -0,0 +1,69 @@
+【失败交接 · 需要你判断】流程 **{{flowTitle}}**（`{{flow}}`）有一个单元（站点 × 日期）跑失败了，引擎交给你 —— 请**判断**，不要盲目重推。
+
+## 交接上下文
+
+- 单元：`{{case}}`（第 {{attempt}} 次失败）
+- 失败摘要：{{error}}
+- 台账：`{{ledger}}`（`{{py}} {{cloneScripts}}/flow_ledger.py --status --flow {{flow}}`）
+- 快照缓存：`~/.dsh/argent/daily-report-cache/<日期>-store-<id>.json`；推送标记：同目录 `.pushed-<日期>-store-<id>`
+
+## 你要做的（四步）
+
+1) `bash {{cloneScripts}}/sync-scripts.sh --no-pull`，然后
+   `{{py}} {{cloneScripts}}/flow_failure.py --scan --flow {{flow}} --json`；
+2) 取证：重跑影子命令看真实报错（**只生成不推送**）：
+   `node {{cloneScripts}}/daily-report.mjs --env ~/.dsh/argent/daily-report.env --force --json --date <日期>`
+3) **三选一**下结论并写台账：
+
+   | 失败性质 | 动作 | 台账事件 |
+   |---|---|---|
+   | **429 限流 / 网络超时**（可重试） | 说明现象，交由**下一轮**重试（脚本自身有退避；**不要**短时间连续重推） | `retry` |
+   | **OAuth token 失效/被撤销、店铺未授权**（需人） | 写清缺什么、需要谁去重授权（`ml-oauth-setup.mjs`） | `blocked` |
+   | **卡片构建/口径异常、站点未知**（需判断） | 说明证据，能绕过则重派影子；绕不过转人工 | `retry` 或 `blocked` |
+
+4) 结论必须带证据：退出码 / 报错原话片段 / 涉及站点与日期。**没有证据的结论视为无效**。
+
+## 红线（重要）
+
+- 本轮**只做影子**：`--force` 必须与 `--json` 同用（只生成卡片 JSON，**不推送、不写幂等标记**）；
+  **禁止**去掉 `--json` 的运行方式（那会真的推送到客户群）；
+- 不要改 `ml-api-stores.json`、不要删/建缓存与推送标记；
+- 同一单元同一原因重试超过 {{max}} 次即停手，转 `blocked`。
+
+## 需要人裁定的事（2026-09-17 用户口径）
+
+- 判为 `needs_human` / `blocked` 时，**由用户本人确认**（谁补字段、是否放行、是否重跑）：
+  直接在**会话里问用户**，或在飞书群里问（两条路都行）；
+- 问的时候把「缺什么 / 卡在哪一步 / 建议怎么办」写清楚，**不要自己替用户拍板**，
+  也不要因为等不到答复就反复重跑。
+
+## 告警也要用卡片（2026-09-17 用户口径）
+
+判为 `needs_human` / `blocked`（或你判断需要用户拍板）时，除台账外**发一张卡片**到内部群：
+
+```bash
+node {{cloneScripts}}/feishu-card.mjs --template need-human --flow {{flow}} --case '{{case}}' \
+  --reason '<卡在哪/缺什么>' --ask '<要用户定什么>' --to internal --send
+```
+
+`needs_agent` 类由引擎在唤醒时自动发 failure-alert 卡片（与你重复也没关系，卡片是给人看的）。
+
+## 处置前先查政策（P1，2026-09-17）
+
+判断"重跑 / 等人 / 升级 / 作废"之前，**先查政策库**（它是判据的唯一权威，见 `docs/Argent-宿主适配契约.md` §1「判断归属」/§2④）：
+
+```bash
+# 1) 查：命中就直接执行，并在台账记「依政策执行」
+{{py}} {{cloneScripts}}/flow_policy.py --match --flow {{flow}} --failure-kind <分类> --status <状态> --json
+# 2) 记：命中后（把 <政策id> 换成上一步返回的 id）
+{{py}} {{cloneScripts}}/flow_ledger.py --case-id '{{case}}' --event policy_apply --by <角色名> \
+  --detail '依政策 <政策id>（<decision>）执行'
+# 3) 未命中：按权限边界决定 —— 能自动就自动；不能自动（口径/授权/作废）就问用户；
+#    用户答复后**提议**一条政策（下次同类不再问）：
+{{py}} {{cloneScripts}}/flow_policy.py --add --decision <retry|hold|escalate|discard> \
+  --match-kv flow={{flow}} --match-kv failureKind=<分类> --authorizer 用户 \
+  --source-case '{{case}}' --why-ref 'skills/<技能>/references/pitfalls.md#<条目>'
+```
+
+权限边界：`{{py}} {{cloneScripts}}/flow_policy.py --authority --flow {{flow}}`
+（缺省：瞬时类重跑可自动≤2 次；等人/升级可自动；**作废与口径变更必须问用户**）。

package/engine/verticals/mercadolibre/prompts/daily-report.md

@@ -0,0 +1,47 @@
+【定时触发】流程 **{{flowTitle}}**（`{{flow}}`）本轮按规则跑（**到点即真推送**）：
+
+1) 先同步并看在飞：`bash {{cloneScripts}}/sync-scripts.sh --no-pull` → `{{py}} {{cloneScripts}}/flow_ledger.py --inflight --flow {{flow}}`；
+2) 分诊：`{{py}} {{cloneScripts}}/flow_triage.py --flow {{flow}} --json`；
+3) **本轮只处理这几张已认领的票**（认领脚本已写 `planned` 并带租约）：{{tickets}}；
+   每票 = **一个站点 × 一个日期**（票号形如 `MLM-2026-09-16-2216458475`）；
+4) **每票派一个 subagent**，指令（照抄，票号开头）：
+
+   > 你是美客多日报执行者。任务票号：<票号>（站点 <site>、日期 <date>、店铺 <store>）。
+   > ① **真推送**（单元出现在清单里 = 已到该店站点本地推送点，且当日尚未推送）：
+   >    `node {{cloneScripts}}/daily-report.mjs --env ~/.dsh/argent/daily-report.env`
+   >    说明：**不要加 `--force`、不要加 `--json`** —— 脚本自带时间门控与幂等标记
+   >    （`.pushed-<date>-<store>`）：未到点会自己跳过、已推过的不会重推 ⇒ 重跑安全。
+   >    期望输出：`✅ 日报已推送（lark-bot-card）：📊 美客多日报 · <date>（昨日数据）`。
+   > ② 若①失败（非 0 退出/采集报错），**再跑一次影子取证**（不推送，只为拿真实报错）：
+   >    `node {{cloneScripts}}/daily-report.mjs --env ~/.dsh/argent/daily-report.env --force --json --date <date>`
+   >    把 stderr 摘要与卡片 JSON（存 `~/.dsh/argent/daily-report-logs/shadow-<票号>.json`）一起回报；
+   > ③ 记台账：推送成功 `done`（附"已推送 + 关键数字"）；失败 `failed` 并附错误摘要；
+   > ④ **红线**：不改任何店铺数据、不动 `ml-api-stores.json` 与缓存标记、
+   >    不手工删 `.pushed-*` 标记（要重推必须用户明确批准）。
+
+5) 汇总：票号 / 命令 / 退出码 / 产物路径 / 台账状态。
+
+**红线（定时轮次）**：
+- **到点即真推送**（2026-09-18 用户口径变更：昨日口径是"只准备、不推送"，导致日报静默停摆）：
+  清单里出现单元 = 已到点且当日未推 ⇒ 直接跑真推送；脚本自带门控与幂等标记，**重复触发安全**；
+  失败才退回影子取证（见步骤②）并把问题暴露出来；
+- 认领最多 {{max}} 张；台账：`{{ledger}}`。
+
+## 收尾必做：发飞书**卡片**（2026-09-17 用户口径：流程/告警类一律卡片）
+
+本轮结束时，用共用构造器把结果发成卡片（**不要发纯文本长消息**）：
+
+```bash
+# 流程结果汇报（一票一行：<票号>=<状态>|<细节>；状态用 done / failed / blocked 等）
+node {{cloneScripts}}/feishu-card.mjs --template flow-result \
+  --flow {{flow}} --flow-title '{{flowTitle}}' \
+  --result '<票号>=done|<做了什么>' --note '本轮一句话小结' --to internal --send
+
+# 需要人确认时（needs_human / blocked）：用需人工卡，写清「卡在哪」与「要你定什么」
+node {{cloneScripts}}/feishu-card.mjs --template need-human \
+  --flow {{flow}} --case '<票号>' --reason '<卡在哪>' --ask '<要用户定什么>' --to internal --send
+```
+
+- 先 `--dry-run`（不带 `--send`）看一眼卡片 JSON 再发；发送失败**不要**反复重试，改把结论写进台账；
+- 落点固定内部群（`--to internal`，= `FULL_INTERNAL_CHAT_ID`）；日报类才用 `--to daily`；
+- 台账照旧记（卡片是给人看的，台账是给引擎看的，两者都要）。

package/engine/verticals/mercadolibre/prompts/daily-report.scheduled.md

@@ -0,0 +1,79 @@
+# 宿主排程轮次指令（**静态**）—— 美客多店铺日报
+
+> ⚠️ **本文件不是**认领期模板 `prompts/daily-report.md`（那份带**票号占位符**，由 `flow-trigger.sh`
+> 认领后投递）。宿主原生排程的 prompt **在创建任务那一刻就固定**（之后改不了）⇒
+> 本文件里 ⛔ **不允许出现任何模板占位符**（形如双花括号包住的名字），也不允许写"本轮这几张票"。
+> 两份 prompt 必须分开（上游设计《dsh-排程插件评估与迁移设计》§5.1 要点 3）。
+
+## 0. 现状（**先读这一节，它决定"本轮该做什么"**）
+
+- 本文件随 **P1-A**（2026-10-12）落地，作用是**把"排程该叫醒谁、叫醒后跑什么"写成静态指令**。
+- **P1-B（2026-10-14）已把「只认领、不唤醒」的 L1 入口落地**：`scripts/flow-trigger.sh` 现认
+  `--flow` / `--max` / `--dry-run` / **`--no-wake`**（语义与"谁用它"见
+  `docs/Argent-宿主适配契约.md` §⑥.2⑤；回归 `scripts/tests/flow-trigger-no-wake.test.mjs`）。
+  ⇒ §1 的那条命令**是现行形态**，可以直接照跑（⛔ 但本批不发布、不重启、不连机器：
+  **建宿主任务与切投递留给交付方**，见 §5）。
+- 为什么必须分开两份 prompt：宿主的 prompt **在创建任务那一刻就固定**（之后改不了）
+  ⇒ 本文件里 ⛔ **不允许出现任何模板占位符**，也不允许写"本轮这几张票"
+  （上游设计《dsh-排程插件评估与迁移设计》§5.1 要点 3）。
+
+## 1. 收到本指令时应当执行的**唯一** L1 命令
+
+```bash
+bash "$HOME/.argent-dsh/scripts/flow-trigger.sh" --flow daily-report --no-wake
+```
+
+说明：
+
+- `$HOME/.argent-dsh` = **装机克隆**（`deliver-customer.mjs` 的 `remoteDir`，每台装过的机器都在这个位置；
+  本文件是静态的，⛔ 不能写开发机上那个仓库路径）。
+- `--no-wake` 的语义：**只认领 + 只写台账，不唤起角色会话**（⛔ 不 spawn 会话、⛔ 不写 `wake` 事件）；
+  `planned` 事件与额度/租约语义**照常**，其余闸门（暂停开关 / 环境预检 / 停滞回收 / 自动重试 /
+  认领看门狗）与默认模式**逐字同序**。
+- 为什么只要这一条：排程只负责「到点叫醒」（L2 归位），判据与认领仍全部在 L1
+  （契约 §1；⛔ 排程不得替代并发闸/幂等/写守卫）。
+
+## 2. ⛔ 不要做什么
+
+1. ⛔ **不要**执行 `bash "$HOME/.argent-dsh/scripts/flow-trigger.sh" --flow daily-report`
+   （那是**认领 + 唤醒**的形态：与"宿主排程又叫醒一次"叠在一起 = **二次唤醒**/双轮）。
+2. ⛔ **不要**为本流程创建宿主排程任务 —— 那是**交付动作**（本批明令不做，见 §5）。
+3. ⛔ **不要**为了"留痕"去写这两处（都会把防线弄坏）：
+   · **轮次日志**（`verticals/mercadolibre/logs/flow-trigger-daily-report.log`）—— 执行闸（第 3 闸）看的
+     就是它的 mtime，"收到指令但没跑 L1"写进去 = **假绿**（闸会以为活干了）；
+   · **台账**用一个哨兵 caseId —— 台账是**业务 case 的**面，塞一条哨兵会污染
+     `flow_ledger --status` / 分诊 / Rule R 的判据。
+   这一条只需要**人看到**：写在回复里 + 由运维看 `node scripts/argent-schedule.mjs check` 的结论即可。
+
+## 3. 现行 vs 垫片（**垫片那条本轮不要动**）
+
+```bash
+bash "$HOME/.argent-dsh/scripts/flow-trigger.sh" --flow daily-report --no-wake   # ✅ 宿主排程用（只认领）
+bash "$HOME/.argent-dsh/scripts/flow-trigger.sh" --flow daily-report             # ⛔ 垫片路径（认领 + 唤醒）
+```
+
+两条命令对应**两条宿主线**：0.2 线（宿主原生排程）跑上面那条；0.1.7 线的激活垫片
+（`com.whyshu.flow-trigger-*` 计划任务，每 5 分钟一轮）跑下面那条。
+⛔ **单一调度者**：一条流程不许被两条线同时调度（冲突 ⇒ 响亮报，见契约 §⑥.2③）。
+
+## 4. 红线（照旧，一条都不放宽）
+
+- 日报流程**只读 + 推送**：⛔ 不改任何店铺数据、⛔ 不动 `ml-api-stores.json` 与缓存标记、
+  ⛔ 不手工删 `.pushed-*` 幂等标记（要重推必须用户明确批准）。
+- 派发与写路径的守卫**一条都不变**：票的派发、并发闸（`flow_claim.py` 租约）、
+  幂等键（`caseId`）、失败分类都在 L1，⛔ 排程**不得**替代它们。
+- ⛔ 不要为了"让定时看起来在跑"而放宽 `PAUSE_*` 开关：开关仍是**唯一真源**
+  （文件在 ⇒ 收敛为"停"，见 `node scripts/argent-schedule.mjs pause --apply` 与
+  `<数据目录>/schedule-audit.jsonl`）。
+- ⛔ 不要把本文件当"每轮可变"的模板用（它被宿主固定在任务里）。
+
+## 5. P1-B 状态：入口已落地；**建任务与切投递不做**（留给交付方）
+
+1. ✅ **（2026-10-14 已完成）** `scripts/flow-trigger.sh` 的 `--no-wake`：认领 + 写 `planned`/租约，
+   **不建会话、不投递**；并与计划任务形态串起来（`scheduleCatalogRows().promptCommand` 带该开关；
+   ⛔ 0.1.7 线垫片生成的 plist **不带** —— 它要唤醒会话）。
+2. ⬜ 激活 shim（按宿主版本分叉）：0.1.x 三行 `disabled:false` / 0.2.x 一行 `bundles`；装机 + 升级后**重断言**。
+3. ⬜ 建任务：由**绑定会话**调 `schedule_create`（`title` 必须逐字等于注册表 `taskTitle`，
+   prompt 用本文件的内容；`create` **没有**远端端点 ⇒ 只能由会话内工具做）。
+4. ⬜ 投递真跑一次并留四层证据（挂载/在册/回执/L1 台账），再按"先起后排"停掉该流程的计划任务。
+   ⚠️ 第 2–4 步都在**别人手上**（本批：⛔ 不发布、⛔ 不重启、⛔ 不连机器）。

package/engine/verticals/mercadolibre/prompts/full.failure.md

@@ -0,0 +1,125 @@
+【失败交接 · 需要你判断】流程 **{{flowTitle}}**（`{{flow}}`）有一张票跑失败了，引擎把它交给你 —— 请**判断**，不要盲目重跑。
+
+## 交接上下文
+
+- 票号：`{{case}}`（第 {{attempt}} 次失败）
+- 失败摘要：{{error}}
+- 台账：`{{ledger}}`（`python3 {{cloneScripts}}/flow_ledger.py --status --flow {{flow}}` 看全貌）
+- 运行日志：`~/.dsh/argent/fulfillment-logs/run-<日期>-<店>-<record>*.log`；失败索引 `~/.dsh/argent/fulfillment-logs/failures.jsonl`
+
+## 你要做的（四步）
+
+1) `bash {{cloneScripts}}/sync-scripts.sh --no-pull`，然后
+   `python3 {{cloneScripts}}/flow_failure.py --scan --flow {{flow}} --json` —— 看清**为什么**把它交给你；
+2) 取证：读失败阶段的日志尾部 + `failures.jsonl` 里该 record 的最近记录（**不要只看退出码**）；
+3) **三选一**下结论，并把理由写进台账：
+
+   | 失败性质 | 动作 | 台账事件 |
+   |---|---|---|
+   | **网络/超时/限流类**（可重试） | 重派**一个** subagent 重跑该票（同一时刻只有一个执行者） | `retry` → 重派后 `dispatched` |
+   | **页面/选择器类超时**（`pageFlaky`，引擎已按此分类并唤醒你：`等待选择器超时`/`选择器超时`/`wait_for_selector`/`locator…超时`/`input[readonly]`；⚠️ 裸 `Timeout Nms exceeded`（**门户导航**超时）仍归网络类 `retryable`，由脚本自重试，不会唤醒你）| 先只读复核（`read_image` 看截图 + 门户实况）；**保留货件号**重派续跑（引擎「已有货件号 ⇒ 跳过步骤3」不会新建）| `retry`（**不清号**）或 `blocked` |
+   | **业务/门户改版类**（需判断） | 说明现象与证据；能绕过则重派，绕不过则标记等待人工 | `retry` 或 `blocked` |
+   | **缺数据/需人放行**（等人） | **不要重跑**；写清缺什么、等谁 | `blocked` |
+
+4) 每条结论都带证据：退出码 / 日志原话片段 / 涉及字段或步骤号。**没有证据的结论视为无效**。
+
+## 与旧架构的对应（历史语义，别丢）
+
+旧 poll 的自动重跑口径：**只对网络类错误**自动重置重跑（`AUTO_RETRY_MAX=2`），
+**选择器/业务类错误绝不自动重置**（防重复写操作）。你现在接手的就是这个判断 ——
+所以"网络类 ⇒ 可以重试"是既定规则，"业务类 ⇒ 先判断再动"同样不可放宽。
+
+## 红线
+
+- 取证轮**只读**：禁止 `--allow-write`、禁止 `--mode full`、禁止改任何表字段；
+- 不要反复重跑：同一票同一原因重跑超过 {{max}} 次即停手，转为 `blocked`；
+- 不要改别人的票：只处理 `{{case}}`。
+
+## 预约铁律（2026-09-18 用户口径，逐字）
+
+> 「FULL流程如果失败了，**如果是已经预约了要取消预约的，否则会有违约金**；
+>   如果已经取消预约了，就可以从第一步开始重建货件号的。流程本该如此。」
+
+判定与动作：
+
+| 预约状态（证据） | 能否重建 | 依据 |
+|---|---|---|
+| `failed_step ≤ 4`（步骤4未完成） | ✅ 可重建 | 预约从未提交 ⇒ 无残留（引擎的失败分支本就不触发取消） |
+| 备注含「预约已自动取消 / 无超时罚款风险」 | ✅ 可重建 | 引擎失败分支已自动取消 |
+| 备注含「预约取消失败 / 请立即人工取消」 | ⛔ **禁止重建** | 先人工取消预约，否则违约金 |
+| `failed_step ≥ 5` 且无任何取消留痕 | ⛔ **禁止重建** | 异常终止 ⇒ 先人工核对门户预约 |
+
+**先分清四种页面状态**（2026-09-18 实证 77445732；**2026-10-09 按生产实测 79096447 重写**：旧表把
+"`div.day` 格子数 = 0"直接写成"门户当前没有可预约时段"，而 `div.day=0` 的真实含义只是
+**日历压根没渲染出来** —— 生产里角色照这句把失败记成「平台无预约时段(No contamos con citas,
+div.day=0/hour=0)」，而**同店同 SKU 的另一张票 4 分钟后 8/8 成功** ⇒ 那个结论当场被证伪、运维被误导）：
+
+| DOM 证据（看 `failures.jsonl` 的 `dom_summary` / 失败原因的「证据：」段） | 含义 | 动作 |
+|---|---|---|
+| `div.day 命中=0`（**日历没渲染**；`div.day=0 div.hour=0` 是它的旧写法） | **页面形态异常**（平台错误页 / 慢渲染 / 货件号可疑）；⛔ **没有任何证据**能支持"平台没放号" | **⛔ 不许**写"无预约时段/没放号"；按**页面形态**处置：先核对本行货件号与 ML 实际单号（⑰ 取号错位：实测 77849070→77849071 改号后预约页立即正常），再决定保留货件号续跑 |
+| `div.day 命中>0` 且 **可用=0**（例如 `可用=0`，`disabled=` 等于总数） | 日历**在**、格子**全不可选** ⇒ **才**允许说"当前无可预约时段" | **不清号重建**（重建同样约不到、还白扔货件号）；`blocked` 说明"门户无时段"**并附上** `div.day 可用=0/总数=N`；等放号后**保留货件号**续跑 |
+| `div.day 命中>0` 且 **可用>0**（如 `可用=3`） | 日历正常、**有可用日** ⇒ 失败点**不在**"有没有档期" | 按选择器/交互类排查（保留货件号重派续跑） |
+| 页面**还停在选配送方式**（文案含 `Elige la forma de envío`）就等 `input[readonly]` 超时 | 流程没推进到日历 ⇒ **交互/选择器类** | 保留货件号重派续跑；连续两次同一位置失败 ⇒ `blocked` 交人 |
+
+⚠️ 四种都会表现为"等待选择器超时"或"未找到 X 选项"，**必须用 DOM 证据区分**：
+**"日历没渲染"与"日历渲染了但没有可用日"是两件完全不同的事**，⛔ 不许一律当成"没时段"。
+
+### 口径统一（2026-10-09 硬要求）
+
+- **表备注 `FULL备注` 与账本 `blocked` 的原因必须同源同文**：引擎把原因写进台账 `failed.error`
+  与表备注（同一个字符串）；你要写 `blocked` 时**逐字**取它，不要自己复述：
+  ```bash
+  {{py}} {{cloneScripts}}/flow_failure.py --flow {{flow}} --case '{{case}}'    # 打印规范失败原因
+  ```
+  取不到（没有 failed 事件）就**照实说"取不到规范原因"**，⛔ **不要**用自己对页面的解读顶上。
+- 写账本时逐字带上它（可以截断尾部，但**不得改写/翻译/换词**）：
+  ```bash
+  {{py}} {{cloneScripts}}/flow_ledger.py --case-id '{{case}}' --event blocked --by <角色名> \
+    --detail "$({{py}} {{cloneScripts}}/flow_failure.py --flow {{flow}} --case '{{case}}')"
+  ```
+- ⛔ **预约类失败一律不许自动重跑**（步骤4 是**写**步：重跑可能重复建预约）：细分归属只能是
+  "落卡等人"或"叫醒你判断"，**永远不是** `retryable`。唯一例外是平台**自己**在页面上明说
+  「`ya no está disponible`」（该时段已被占）——它由引擎按 `defer` 处理（当日不重试、次日重置一次），
+  **不需要**你在台账里再加工。
+
+- **清号重建的唯一入口**是 `flow_retry.py`（已内置**分类闸门**＋**预约闸门**，任一不过即拒绝）；
+- **保留货件号**重派 = 续跑该货件（引擎跳过步骤3），**不会**新建货件 ⇒ 页面/选择器类失败优先走这条；
+- 你自己不能绕过闸门：需要人工放行时，请让用户用 `--override --reason '<核对说明>'`。
+
+## 需要人裁定的事（2026-09-17 用户口径）
+
+- 判为 `needs_human` / `blocked` 时，**由用户本人确认**（谁补字段、是否放行、是否重跑）：
+  直接在**会话里问用户**，或在飞书群里问（两条路都行）；
+- 问的时候把「缺什么 / 卡在哪一步 / 建议怎么办」写清楚，**不要自己替用户拍板**，
+  也不要因为等不到答复就反复重跑。
+
+## 告警也要用卡片（2026-09-17 用户口径）
+
+判为 `needs_human` / `blocked`（或你判断需要用户拍板）时，除台账外**发一张卡片**到内部群：
+
+```bash
+node {{cloneScripts}}/feishu-card.mjs --template need-human --flow {{flow}} --case '{{case}}' \
+  --reason '<卡在哪/缺什么>' --ask '<要用户定什么>' --to internal --send
+```
+
+`needs_agent` 类由引擎在唤醒时自动发 failure-alert 卡片（与你重复也没关系，卡片是给人看的）。
+
+## 处置前先查政策（P1，2026-09-17）
+
+判断"重跑 / 等人 / 升级 / 作废"之前，**先查政策库**（它是判据的唯一权威，见 `docs/Argent-宿主适配契约.md` §1「判断归属」/§2④）：
+
+```bash
+# 1) 查：命中就直接执行，并在台账记「依政策执行」
+{{py}} {{cloneScripts}}/flow_policy.py --match --flow {{flow}} --failure-kind <分类> --status <状态> --json
+# 2) 记：命中后（把 <政策id> 换成上一步返回的 id）
+{{py}} {{cloneScripts}}/flow_ledger.py --case-id '{{case}}' --event policy_apply --by <角色名> \
+  --detail '依政策 <政策id>（<decision>）执行'
+# 3) 未命中：按权限边界决定 —— 能自动就自动；不能自动（口径/授权/作废）就问用户；
+#    用户答复后**提议**一条政策（下次同类不再问）：
+{{py}} {{cloneScripts}}/flow_policy.py --add --decision <retry|hold|escalate|discard> \
+  --match-kv flow={{flow}} --match-kv failureKind=<分类> --authorizer 用户 \
+  --source-case '{{case}}' --why-ref 'skills/<技能>/references/pitfalls.md#<条目>'
+```
+
+权限边界：`{{py}} {{cloneScripts}}/flow_policy.py --authority --flow {{flow}}`
+（缺省：瞬时类重跑可自动≤2 次；等人/升级可自动；**作废与口径变更必须问用户**）。

package/engine/verticals/mercadolibre/prompts/full.md

@@ -0,0 +1,91 @@
+【定时触发】流程 **{{flowTitle}}**（`{{flow}}`）本轮按**相位**执行（`identify` 只读；`execute`/`retry` **走真实写路径**，守卫生效）：
+
+1) 先同步并看在飞：`bash {{cloneScripts}}/sync-scripts.sh --no-pull` → `{{py}} {{cloneScripts}}/flow_ledger.py --inflight --flow {{flow}}`；
+2) 分诊：`{{py}} {{cloneScripts}}/flow_triage.py --flow {{flow}} --json`（**候选已按流程声明的 pick 收窄**，
+   且每票带一个**阶段** `phase`；收窄为空 / 只剩 `await_release` 即本轮无事可做）：
+   - `identify`  —— **识别相**：该行状态为空（新行）⇒ 本轮**只做识别**（见 ⑤）；
+   - `execute`   —— **执行相**：已识别且运营已勾「就绪」放行 ⇒ 正常作业；
+   - `await_release` —— 已识别但尚未勾放行 ⇒ **不派发、不落卡**（分诊只报数，等人放行）；
+   - `retry`     —— **瞬时类失败重跑**（用户口径 A，2026-09-17）：该票原失败被分类为网络/浏览器瞬时类
+     （如 `Target page, context or browser has been closed`）⇒ 本轮**允许走写路径**：
+     `{{py}} {{cloneScripts}}/orchestrator.py --mode full --allow-write --record-id <record_id> --store-name <store>`
+     （守卫照旧生效：字段白名单 / 写前整行备份 / 审计 / 写后读回；禁止 `--force` 之类绕过）；
+   - `needs_human` —— 业务/门户状态类失败（如 `Reserva cancelada`、缺字段）⇒ **只读取证 + 发卡片交人**，
+     **禁止重跑**（写也解决不了，只会把状态搅乱）；
+3) **本轮只处理这几张已认领的票**（认领脚本已写 `planned` 并带租约）：{{tickets}}；
+   每张票 = FULL 表的一行 **record_id**（票号形如 `full__<record_id>`）；
+4) **按店铺分组派 subagent —— 一店一个（不要一票一个）**：
+
+   本轮的票先按 `store` 分组；**同一个店的多张票合给一个 subagent**，用批量入口一次跑完
+   （2026-09-18 用户口径 B，理由见文末「为什么一店一批」）。
+   **票 → 店铺的映射**取第 2 步的分诊输出（每条候选都带 `store`；若只认票号形如
+   `full__<record_id>`，可按 `store` 字段分组，不要凭猜）。指令（照抄，店铺开头）：
+
+   > 你是 FULL 货件流程执行者。本轮负责店铺：<store>，共 <n> 张票：
+   >   <票号1> record_id=<rec1>（phase=<p1>）｜<票号2> record_id=<rec2>（phase=<p2>）｜…
+   > ① **按相位执行**（用户口径 2026-09-17：不再只跑影子；execute/retry 相就是真实作业）：
+   >    · 全是 `identify` 相 ⇒ 逐票只读取证（`--mode dry-run`），或按下面 ⑤ 做识别；
+   >    · 有 `execute` / `retry` 相 ⇒ **真实执行**，用**批量入口**（一次 CDP 连接、多标签页、顺序执行）：
+   >      `{{py}} {{cloneScripts}}/orchestrator.py --mode full --allow-write --records <rec1>,<rec2>,… --store-name <store>`
+   >      （守卫照旧生效：字段白名单 / 写前整行备份 / 审计 / 写后读回；禁止任何绕过守卫的写法）
+   >      · 单票时也走同一命令（`--records <rec>` 等价于 `--record-id <rec>`）；
+   >      · 混合相位（既有 identify 又有 execute）⇒ **分两批**：先按上面跑 execute/retry 的票，
+   >        再按 ⑤ 处理 identify 的票（识别是只读+标记，不要混进写批次）。
+   > ② 取证：记录**每张票**的退出码、货件号、`当前步骤`、日志尾部、截图路径（若有）；
+   >    批量结果 JSON 里每张票一行 `status`，逐票核对，不要只看总体退出码；
+   > ②b **看图判读（2026-09-18 起：模型已支持识图，必须用）**：凡是日志里出现
+   >    `📸 失败现场截图:` / `📸 重试现场截图`（`/tmp/fulfillment-screenshots/step*.png`），
+   >    或步骤 7（打印箱唛）出现过重试/失败 —— **必须 `read_image` 打开那张截图**再下结论，不要只读文字日志。
+   >    判读口径：
+   >    · 页面已出现「Etiquetas para bultos N」+ 可点的「Descarga todas las etiquetas」⇒ 箱唛**其实已生成**
+   >      （KB-135 两次生产实证：脚本却以 business 收口、转人工，步骤 8 还把预约取消了）；
+   >    · 页面仍有红字「Declara al menos」且下载按钮**不可点** ⇒ 平台侧声明未通过，属业务失败；
+   >    结论写进台账 detail（附截图路径）——"脚本缺陷"与"业务失败"必须分清，前者要落工单而不是重跑。
+   > ③ 记台账：**每张票各自记**（`{{py}} {{cloneScripts}}/flow_ledger.py --case-id <票号> …`）：
+   >    `--event phase --phase <阶段> --detail <产物>`；有产物才 `done`，否则 `failed`（附错误摘要）；
+   > ④ **红线**：不点「就绪」（那是运营的放行动作）、不碰守卫白名单以外的字段；
+   >    `identify` 相只读；`execute`/`retry` 相按上面 ① 真实执行（守卫会拦越界写入）；
+   > ⑤ **识别相（该票 phase=identify 时唯一要做的事）**：逐票校验「店铺是否在紫鸟授权内 / SKU、数量、箱数是否齐」
+   >    → 齐 ⇒ 只把该行 `FULL状态` 置「待执行」（**不要勾「就绪」**，那是运营的放行动作）；
+   >      不齐或店铺未授权 ⇒ 置「跳过」，并在 `FULL备注` 写清原因（缺哪个字段 / 哪个店铺未授权）；
+   >    识别相**不做货件作业**（不碰 orchestrator 的写路径、不碰门户）；放行由运营勾「就绪」后，
+   >    下一轮以 phase=execute 正常作业。
+
+   **为什么一店一批**：同店多票一次跑 = 只付一次固定开销（起进程/连 CDP/前置检查 ≈1~2.5 分钟），
+   且 KB-085 的批量模式是**顺序**执行 ⇒ 产物认领（"目录里新出现/最新的文件"兜底）不会串票。
+   **红线**：同一店铺**同时只能有一批在跑**（认领层已保证：该店有活租约就整店跳过）；
+   不要为了"快"给同一个店派两个 subagent —— 那会让两个批次抢同一个下载目录，把标签/箱唛传错票。
+5) 汇总：票号 / 命令 / 退出码 / 产物路径 / 台账状态。
+
+**脚本缺陷怎么办（2026-09-18 用户口径）**：定时轮里**不要现场改生产脚本**（自改引擎、无回归、会波及
+其他流程与客户机）。你要做的是：用上面的截图/日志**判定"这是脚本判据缺陷"** → 把工单交给 **ml-dev**
+（专职 ML 业务开发者：在 `~/Code/argent-dsh` 改 + commit + push + 跑回归）→ 下一轮生效。
+工单里必须带：症状、截图路径、日志行、复现命令、以及"为什么这不是业务失败"的证据。
+
+**红线（定时轮次）**：
+- **按相位执行**（2026-09-17 用户口径）：`identify` 只读；`execute`/`retry` 相**允许真实写**，
+  但必须走守卫（白名单/写前整行备份/审计/写后读回，见 `docs/argent-architecture.md` §7.3）；
+  `needs_human` 相只读取证 + 发卡片交人，禁止重跑；
+- 认领最多 {{max}} 张（**同店一批最多 3 张**，一起交给该店的一个 subagent）；台账：`{{ledger}}`；
+
+## 收尾：飞书卡片怎么发（2026-09-18 用户口径：**步骤级推送收起来，只留最终成功卡**）
+
+**成功的票：引擎已经替你发了。**
+每张票 8/8 走完时，`orchestrator.py` 自己会往内部群发一张绿色完成卡
+（`🎉 FULL 货件完成！` + SKU / 货件号 / 数量 / 箱数 / 文件已上传；`FULL_NOTIFY_MODE` 缺省 `final`
+＝ 步骤消息一律不发、只放行这张完成卡）⇒ **成功轮次不要再发第二张卡**，避免同一个结果刷两条。
+你要做的只是：把结果记进台账（`done`）并在会话里给小结果。
+
+**需要人 / 失败的票：照旧发卡片**（这才是给人行动的信号）：
+
+```bash
+# 需人工确认（needs_human / blocked）：写清「卡在哪」与「要你定什么」
+node {{cloneScripts}}/feishu-card.mjs --template need-human \
+  --flow {{flow}} --case '<票号>' --reason '<卡在哪>' --ask '<要用户定什么>' --to internal --send
+```
+
+- 只有当一轮里**全部票都失败/被阻塞**（没有任何成功票）时，才补一张流程结果卡：
+  `--template flow-result --result '<票号>=failed|<原因>' --note '本轮无成功票' --to internal --send`；
+- 先 `--dry-run`（不带 `--send`）看一眼卡片 JSON 再发；发送失败**不要**反复重试，改把结论写进台账；
+- 落点固定内部群（`--to internal`，= `FULL_INTERNAL_CHAT_ID`）；日报类才用 `--to daily`；
+- 台账照旧记（卡片是给人看的，台账是给引擎看的，两者都要），**不要发纯文本长消息**。