@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/verticals/mercadolibre/prompts/wenyao-invoice.failure.md

@@ -0,0 +1,88 @@
+【失败交接 · 需要你判断】流程 **{{flowTitle}}**（`{{flow}}`）有一张票跑失败了，引擎把它交给你 —— 请**判断**，不要盲目重跑。
+
+## 交接上下文
+
+- 票号：`{{case}}`（第 {{attempt}} 次失败）
+- 失败摘要：{{error}}
+- 台账：`{{ledger}}`（`--status --flow {{flow}}` 看全貌）
+- 运行日志：`~/.dsh/argent/wenyao-logs/run-<票号>-*.jsonl`（最近一次）
+
+## 你要做的（四步，别跳）
+
+1. `bash {{cloneScripts}}/sync-scripts.sh --no-pull`，然后
+   `{{py}} {{cloneScripts}}/flow_failure.py --scan --flow {{flow}} --json` —— 看清**为什么**把它交给你（`kind`/`reason`）；
+2. 取证：读失败阶段的日志尾部（**不要**只看退出码），必要时读 case 文件
+   `~/.dsh/argent/flow-cases/{{case}}.json` 的字段与来源；
+3. **三选一**下结论，并把理由写进台账：
+   - `retry` —— 你判断可重试（临时故障/瞬时状态）⇒ 记 `--event retry`，再派**一个** subagent 重跑该票（同一时刻只有一个执行者）；
+   - `blocked` —— 需要人或运营（缺字段/需过验证/需放行）⇒ 记 `--event blocked` 并把**缺什么**写清（表字段 + 会话里说明）；
+   - 判断不了 → **升级**：记 `--event blocked` + 在会话里明确写「需要人看」的理由，别猜；
+4. 每条结论都带证据：退出码 / 日志原话片段 / 涉及字段名。**没有证据的结论视为无效**。
+
+## 写表口径统一（2026-10-09 硬要求 · 缺陷 B）
+
+**失败原因 + 续跑方式必须写进表**（用户口径；客户机生产实测 `recvvgPQgoUOwx`：跑失败后表里
+「发票就绪」被取消、而「发票错误信息」**是空的** ⇒ 运营看到"勾没了 + 没有任何说明"，
+以为脚本坏了、也不知道怎么处理）。**唯一入口**（它同时写表与台账，两处**同一串**）：
+
+```bash
+{{py}} {{cloneScripts}}/invoice_fail_closeout.py --flow {{flow}} --case '{{case}}' \
+  --missing <逗号分隔的缺口列> [--clear-ready] [--yes]      # 默认 dry-run，先看计划
+```
+
+- `--error` 不传时自动取台账里的**规范失败原因**（`flow_failure.py --case` 同一套）；**两处都取不到
+  ⇒ 命令拒绝执行**（⛔ 宁可响亮停下，也不写一条空说明）；
+- 文案由 `flow_failure.ops_message()` 产出：`结论：<业务类|系统类|我方缺陷类>｜<原因>｜动作：<怎么续跑>`；
+  ⛔ **不要自己改写/翻译/加解读**，也**不要**把裸异常栈或英文报错塞进表（命令已内置归类）；
+- **运营类缺口**才带 `--clear-ready`（取消勾选「发票就绪」；运营补齐后自己重勾 ⇒ 下一轮自动重跑）；
+- 成功收尾（P14 走完）已在 `wenyao_run.py` 里清空该列；**手工补终态**时用同一条命令的成功侧：
+
+```bash
+{{py}} {{cloneScripts}}/invoice_fail_closeout.py --flow {{flow}} --case '{{case}}' --outcome success [--clear-ready] --yes
+```
+
+⛔ **禁止**只写台账不写表，也**禁止**绕开本命令用 `--error-message` 手写文案（那正是"两处各写一套"的来源）。
+
+## 红线
+
+- 本轮**只读**：禁止 `--yes`、禁止写 lip/生产表、禁止访问门户；
+- 不要因为失败就**反复重跑**：同一票同一原因重跑超过 {{max}} 次即停手，转为 `blocked`；
+- 不要改别人的票：只处理 `{{case}}`。
+
+## 需要人裁定的事（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/wenyao-invoice.md

@@ -0,0 +1,64 @@
+【定时触发】流程 **{{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` 并带 {{leaseMin}} 分钟租约）：{{tickets}}；
+   · 每票派**一个 subagent**（prompt 以票号开头、照抄 SKILL §6.1 模板）；
+   · 派发前记台账 `dispatched`（覆盖 `planned`），派发后按 §6.2：**有产物才 `done`**，否则 `failed`/`blocked`；
+4) 汇总：票号 / 命令 / 退出码 / 产物路径 / 台账状态。
+
+**本轮口径（2026-09-18 用户变更：真跑已获授权）**
+
+两个发票流程在旧脚本时期都已成功跑通 ⇒ 用户授权定时轮**真实执行**（原"只跑影子、
+真跑须人工批准"的红线**撤销**）。subagent 按 `skills/ml-invoice` 的阶段链执行：
+
+- **第 0 步（必做）：读本流程的集成适配器** —— 货代专属事实（门户、人工闸门、错误词表、
+  **本票要跑的命令**）一律以它为准，不要凭记忆或旧文档拼命令：
+  ```bash
+  {{py}} {{cloneScripts}}/integration_contract.py --describe {{integration}}          # 人工闸门 / 错误词表 / 入口
+  {{py}} {{cloneScripts}}/integration_contract.py --plan {{integration}} --record <record_id>   # 本票的可执行命令（照抄）
+  ```
+  · `manual_gates` 里每一条都是**硬闸门**（如"门户登录需人工过滑块""每次门户访问先经用户确认"）
+    ⇒ 遇到就**停下发卡片交人**，不要反复试；
+  · `error_classes` 是失败分类的判据（与台账 `failed --error` 的文案对应）；
+  · 英文品名按 `skills/ml-invoice` 的口径产出/确认；断了可按计划的阶段参数续跑。
+- **守卫（引擎内置，禁止绕过）**：写表只经 `argent writeback`（字段白名单/记录白名单/终态闸门全在守卫里，
+  字段名与判据见 `core/contracts/` 与写手脚本）—— **本篇刻意不复述字段名**、
+  记录白名单必填、写前整行备份、写后读回验收、审计 JSONL、终态需 `--force`、
+  附件按 `field_id` 上传、同名同大小幂等跳过；
+- **HS 编码（海关编码）由运营人工维护**：系统不预填、不写候选、不自动确认（红线，别动）；
+  ⚠️ **这条只管 HS 编码** —— **材质英文（`S` 列）不在红线内**：按 `skills/ml-invoice`
+  §「材质英文（`S` 列）三级解析」走（① per-SKU 字典 → ② 通用小词典 → ③ `--material-en`，
+  政策A 允许 LLM 译）。三级都没命中时填报阶段（P3）会**阻断并指路**
+  「请翻译成英文后用 --material-en 重跑」——**照做**（译成英文后加该参数重跑），
+  ⛔ 不要当成"报关敏感字段不能预填"而停下；
+- **门户是对方生产系统**（地址见适配器 `--describe` 的 `runners`/`manual_gates`）：本轮已获授权可访问，
+  但**只做本流程必需动作**；
+- **门户阶段串行（2026-10-12 事故固化，用户口径）**：一票一个 subagent、但**门户阶段必须串行**——
+  `wenyao_run.py` 已内置：① 每条票用**自己的一个标签页**（用完即关，别动用户自己开着的页）；
+  ② `P6→P14` 走**每门户一把 flock + 有界等待**（默认 300s），抢锁期间打印
+  `⏳ 等待其他发票跑批释放门户（已等 Ns）`；超时按标准文案**明确失败**
+  （「门户被占用/等待超时，避免并发踩踏；请稍后重跑或提高超时」）⇒ **不要**绕过锁、**不要**改成无限等、
+  也**不要**因为"等了一会儿"就另起一票；③ 三条票同抢一个门户页 = 死循环（本次事故），⛔ 不许回退成复用同一 page；
+- **缺口回填（用户口径）**：**只有"需要运营填"的字段缺口**才写「发票错误信息」并**取消勾选「发票就绪」**
+  （运营补齐后自己重勾）；系统/我方类缺口只写错误信息、**不取消勾选**。
+- 认领最多 {{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/xzh-invoice.failure.md

@@ -0,0 +1,91 @@
+【失败交接 · 需要你判断】流程 **{{flowTitle}}**（`{{flow}}`）有一张票跑失败了，引擎交给你 —— 请**判断**，不要盲目重跑。
+
+## 交接上下文
+
+- 票号：`{{case}}`（第 {{attempt}} 次失败）
+- 失败摘要：{{error}}
+- 台账：`{{ledger}}`（`{{py}} {{cloneScripts}}/flow_ledger.py --status --flow {{flow}}`）
+- 日志：`~/.dsh/argent/invoice-logs/run-<日期>-stage{A,B}.log`；产物落 `~/.dsh/argent/invoice-output/`、`invoice-labels/`
+
+## 你要做的（四步）
+
+1) `bash {{cloneScripts}}/sync-scripts.sh --no-pull`，然后
+   `{{py}} {{cloneScripts}}/flow_failure.py --scan --flow {{flow}} --json` —— 看清交办原因；
+2) 取证：读失败阶段日志尾部（**不要只看退出码**）；门户类失败看是否有截图/页面 URL；
+3) **三选一**下结论并写台账：
+
+   | 失败性质 | 动作 | 台账事件 |
+   |---|---|---|
+   | **网络/超时/门户瞬时不可用**（可重试） | 说明现象（带日志原话），交下一轮重试；**不要短时间连打门户** | `retry` |
+   | **缺数据**（SKU 字典/HS/材质/数量 缺） | 写清缺哪几列、等谁补；**不重跑** | `blocked` |
+   | **门户改版/选择器失效、凭据失效**（需判断/需人） | 附证据（报错原话 + 页面状态）；需要重授权或改选择器 ⇒ `blocked` 并说明找谁 | `retry` 或 `blocked` |
+
+4) 结论必须带证据（退出码 / 日志片段 / 涉及字段或步骤）。**没有证据的结论视为无效**。
+
+## 写表口径统一（2026-10-09 硬要求 · 缺陷 B）
+
+**失败原因 + 续跑方式必须写进表**（用户口径；客户机生产实测 `recvvgPQgoUOwx`：跑失败后表里
+「发票就绪」被取消、而「发票错误信息」**是空的** ⇒ 运营看到"勾没了 + 没有任何说明"，
+以为脚本坏了、也不知道怎么处理）。**唯一入口**（它同时写表与台账，两处**同一串**）：
+
+```bash
+{{py}} {{cloneScripts}}/invoice_fail_closeout.py --flow {{flow}} --case '{{case}}' \
+  --missing <逗号分隔的缺口列> [--clear-ready] [--yes]      # 默认 dry-run，先看计划
+```
+
+- `--error` 不传时自动取台账里的**规范失败原因**（`flow_failure.py --case` 同一套）；**两处都取不到
+  ⇒ 命令拒绝执行**（⛔ 宁可响亮停下，也不写一条空说明）；
+- 文案由 `flow_failure.ops_message()` 产出：`结论：<业务类|系统类|我方缺陷类>｜<原因>｜动作：<怎么续跑>`；
+  ⛔ **不要自己改写/翻译/加解读**，也**不要**把裸异常栈或英文报错塞进表（命令已内置归类）；
+- **运营类缺口**才带 `--clear-ready`（取消勾选「发票就绪」；运营补齐后自己重勾 ⇒ 下一轮自动重跑）；
+- 成功收尾（走完 `已完成`）用同一条命令的**成功侧**，把过时错误信息清掉：
+
+```bash
+{{py}} {{cloneScripts}}/invoice_fail_closeout.py --flow {{flow}} --case '{{case}}' --outcome success [--clear-ready] --yes
+```
+
+⛔ **禁止**只写台账不写表，也**禁止**绕开本命令用 `--error-message` 手写文案（那正是"两处各写一套"的来源）。
+
+## 红线
+
+- 本轮**只读**：禁止写任何表字段、禁止门户写操作（上传/导出/改名）、禁止 `--stageb`；
+- 同一票同一原因重试超过 {{max}} 次即停手，转 `blocked`；
+- 不要改别人的票：只处理 `{{case}}`。
+
+## 需要人裁定的事（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/xzh-invoice.md

@@ -0,0 +1,46 @@
+【定时触发】流程 **{{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}}；
+   每张票 = FULL任务表一行 **record_id**（票号形如 `xzh-invoice__<record_id>`）；
+4) **每票派一个 subagent**，指令（照抄，票号开头）：
+
+   > 你是鑫中航发票流程执行者。任务票号：<票号>（record_id=<record_id>，货件号见票面）。
+   > ① **第 0 步（必做）：读本流程的集成适配器**（货代事实的唯一出处，别凭记忆拼命令）：
+   >    `{{py}} {{cloneScripts}}/integration_contract.py --describe {{integration}}`
+   >    `{{py}} {{cloneScripts}}/integration_contract.py --plan {{integration}} --record <record_id>` ⇒ **照抄命令**
+   >    · `manual_gates` 每条都是硬闸门（门户账号/人工确认）⇒ 遇到**停下发卡片交人**；
+   >    · **真跑**（默认动作，2026-09-18 用户授权）：按 `--plan` 的第 2 步（先在 `--generate-only` 核对再上传回写）
+   > ② 记台账：`{{py}} {{cloneScripts}}/flow_ledger.py --case-id <票号> --event phase --phase <阶段> --detail <结论>`；
+   >    有产物才 `done`，否则 `failed`（附错误摘要）或 `blocked`（缺数据/等人）；
+   > ③ **守卫（禁止绕过）**：写表只经 `argent writeback`（字段/记录白名单、终态闸门由守卫执行；
+   >    字段名与判据见 `core/contracts/`，**本篇不复述**）、
+   >    写前整行备份 + 写后读回验收 + 审计 JSONL；附件按 `field_id` 上传；
+   > ④ **HS 编码/材质由运营人工维护**：字典未确认的 HS 只写「候选 + 待勾选提示」，**不要自己拍板**；
+   > ⑤ **缺口回填（用户口径）**：只有"需要运营填"的字段缺口才写「发票错误信息」并**取消勾选「发票就绪」**
+   >    （运营补齐后自己重勾）；系统/我方类缺口只写错误信息、**不取消勾选**。
+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/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@whyshu/argent-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Argent 引擎（L1）：流程/台账/重试/守卫/审计/浏览器自动化 —— 逐字节来自 argent-dsh 仓库",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "engine/",
+    "MANIFEST.json"
+  ],
+  "exports": {
+    "./version": "./engine/version.mjs",
+    "./registry": "./engine/scripts/lib/registry.mjs",
+    "./datadir-scope": "./engine/scripts/lib/dsh-scope.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.