@whyshu/argent-engine 0.7.8 → 0.8.0-rc.2

package/engine/skills/ml-fulfillment-sop/SKILL.md

@@ -138,6 +138,35 @@ description: "美客多美客多 FULL 货件管理技能（Argent on DSH）—
 
 ---
 
+## 失败评估（2026-10-24 起）
+
+FULL 一轮约 10 分钟，且包含建单/预约/上传等写操作；**失败后默认不自动重跑**。
+
+先只读取证：
+
+- `failures.jsonl` 的 `page_url` / `hub_status` / `dom_summary` / `screenshot`；
+- 失败现场截图（用 `read_image` 看）；
+- 预约、产品标签、箱唛当前状态。
+
+再输出结构化判断：
+
+```json
+{
+  "verdict": "complete | retry | repair_script | needs_human",
+  "confidence": 0.0,
+  "reason": "...",
+  "evidence": ["..."],
+  "safe_to_retry": false
+}
+```
+
+- `complete`：门户已完成 ⇒ 不重跑、不取消预约；
+- `retry`：仅瞬时故障且没有写坏状态，最多受控重跑 1 次；
+- `repair_script`：页面改版/选择器失效 ⇒ 建开发工单，不直接改生产；
+- `needs_human`：缺数据/业务状态/预约需人工核对 ⇒ 落卡等人。
+
+禁止：无评估直接 `--allow-write`、失败分支自动取消预约、为“试试看”重跑、自动修改生产脚本。
+
 ## 异常处理
 
 | 异常问题 | 核心原因 | 解决方案 |

package/engine/skills/ml-fulfillment-sop/references/agentic-runtime-v3.md

@@ -0,0 +1,39 @@
+# Agentic Runtime v3（FULL）
+
+> 适用：Argent 0.8.0+；与 `docs/agentic-tools-contract-v1.md` 配套。
+> 本文件是 Agent 会话的行为规则；确定性 SOP 仍在 SKILL.md / pitfalls.md。
+
+## 会话启动
+
+1. 读取本文件 + `ml-fulfillment-sop/SKILL.md` 的 8 步流程；
+2. 读取 ERP 下发 `AgentTask.context`（货件号、店铺、SKU、数量、箱数、约束、预算）；
+3. 先调用 `ml_probe_hub` 确认整票状态，再决定是否需要执行。
+
+## 只允许使用工具
+
+- 工具清单见 `docs/agentic-tools-contract-v1.md`；
+- **禁止**编写/执行临时 Python/JS 脚本、禁止直接调用浏览器点击、禁止直接写飞书表；
+- 工具不满足需求时：停止并在结果中说明「缺工具 X」，不要现场发明脚本。
+
+## 执行循环
+
+```text
+probe → 判断 → 调用工具 → 读回验证 → 继续 / 信号 ERP / 结束
+```
+
+- 每个写工具调用后必须立即读回验证；
+- 同一动作最多 3 次；不得连续重试同一失败页面；
+- 平台选项不可用/前置未完成 → 立即 `needs_decision`，附截图/选项；
+- 数量/费用/运输方式冲突 → 必须人工决策，不得自行选择。
+
+## 异常信号
+
+按契约 §5 发送 `AgentSignal`，字段：
+`phase / kind / evidence / observed / options / suggestedAction / requiresApproval`。
+发送后进入等待，不重复提交写操作。
+
+## 完成条件
+
+- `ml_probe_hub` 五项/整票状态与任务目标一致；
+- 需要回写的文件已通过 `ml_writeback_lip` 读回验证；
+- 输出 `done` + 证据 + 耗时/成本摘要。

package/engine/version.mjs

@@ -1 +1 @@
-export const VERSION = "0.7.8"
+export const VERSION = "0.8.0-rc.2"

package/engine/verticals/mercadolibre/brazil-full-sop.json

@@ -0,0 +1,47 @@
+{
+  "_note": "来源：巴西约仓流程.xlsx（巴西1店SKU / 巴西海外仓地址 / 1店海外仓产品 / 约仓流程）。仅巴西 FULL 分支使用。",
+  "site": "MLB",
+  "warehouses": [
+    {
+      "name": "安兔",
+      "code": "BR02",
+      "address": "Estrada Municipal, 233 - Jardim Santo Afonso, Galpão 200 - Modulo B14 - CEP 07215-040",
+      "contact": "Bia",
+      "city": "Guarulhos",
+      "state": "圣保罗",
+      "phone": "WhatsApp +55 11 96307-0685",
+      "addressNote": "ANTU+客户代码，如 ANTU A001"
+    },
+    {
+      "name": "复礼",
+      "code": "Cy Log Guarulhos",
+      "address": "Estr. Velha Guarulhos São Miguel, 1814 - Cumbica Guarulhos - SP, 07210-250；Rua 21 de abril 160；堆口56/57/58",
+      "contact": "Qifan Hu",
+      "phone": "WhatsApp 41989001001"
+    },
+    {
+      "name": "鸿泰信",
+      "code": "Alphaville",
+      "address": "Av. Fernando Cerqueira César Coimbra, 210 galpão A - Alphaville Industrial, Barueri - SP, CEP 06465-090",
+      "contact": "Ruipan Tan / Sr. Zhang",
+      "phone": "11915200175 / +55 11960335773",
+      "zoneB": "Av fernando cerqueira cesar coinbra 210-B-alphaville CEP 06465-090"
+    }
+  ],
+  "defaultWarehouse": "安兔",
+  "sop": {
+    "entry": "官方仓货件管理 → 发送商品",
+    "steps": [
+      "输入 SKU 与数量",
+      "点击发送",
+      "如出现方案选择，选择『维持现有方案』",
+      "点击『选择你运送产品的方式和时间』",
+      "选择上门取件；平台没有时间则停止",
+      "点击『选择其他地址』",
+      "按仓库选择『巴西海外仓地址』中的地址",
+      "点击选择，再点击确认",
+      "创建新货件并预约",
+      "在预约时间前取消预约"
+    ]
+  }
+}

package/engine/verticals/mercadolibre/flows.json

@@ -140,7 +140,8 @@
         "promptTemplate": "verticals/mercadolibre/prompts/full.md",
         "dispatch": {
           "sessionIdFile": "verticals/mercadolibre/flow-dispatch-full.json",
-          "freshSession": true
+          "freshSession": true,
+          "failurePreset": "argent-ml-failure-assessor"
         }
       },
       "concurrency": {
@@ -194,14 +195,14 @@
       ],
       "failures": {
         "enabled": true,
-        "_note": "FULL 失败进统一台账 + 可自动唤醒角色判断（wake=session）；告警轮只读影子（模板 flow-prompts/full.failure.md 写死禁 --allow-write）"
+        "_note": "FULL 失败先取证（截图/hub/DOM），再交给只读评估器；默认不自动重跑、不自动取消预约。"
       },
       "_requiredNote": "2026-09-17 实测修正：原写 店铺/装箱数 在真实表里不存在（真名 店铺名称/箱数），导致投影失败且**静默 0 行**。修列名的同时给 flow_source 加了大声失败。",
       "authority": {
         "_note": "角色（=用户替身）的权限边界：auto=可自行决定；ask=必须问用户。见 docs/Argent-宿主适配契约.md §1「判断归属」",
         "retry": {
-          "auto": true,
-          "maxAttempts": 2
+          "auto": false,
+          "maxAttempts": 1
         },
         "discard": {
           "auto": false
@@ -234,6 +235,13 @@
           "{ticket}"
         ],
         "_note": "0.7.0 W2：FULL 走编排器（--mode full）"
+      },
+      "autoRetry": {
+        "enabled": false,
+        "max": 1,
+        "cooldownMin": 60,
+        "perCycle": 1,
+        "_note": "2026-10-24 用户口径：FULL 一轮 ~10 分钟且含写操作；无失败评估不得自动重跑。评估通过后才允许受控重跑。"
       }
     },
     "wenyao-invoice": {

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

@@ -1,5 +1,41 @@
 【失败交接 · 需要你判断】流程 **{{flowTitle}}**（`{{flow}}`）有一张票跑失败了，引擎把它交给你 —— 请**判断**，不要盲目重跑。
 
+## ⛔ 先评估，再决定是否重跑（2026-10-24）
+
+FULL 一轮通常 ~10 分钟，且步骤3/4/5/7/8 都有真实写操作；**没有失败评估，禁止自动/手工重跑**。
+
+先做只读取证，再给出结构化结论：
+
+```json
+{
+  "verdict": "complete | retry | repair_script | needs_human",
+  "confidence": 0.0,
+  "reason": "一句话说明真实原因",
+  "evidence": ["hub/截图/日志里的证据"],
+  "safe_to_retry": false,
+  "recommended_action": "下一步具体动作"
+}
+```
+
+评估顺序：
+
+1. **先看真实页面状态**：`failures.jsonl` 的 `page_url`、`hub_status`、`screenshot`；
+   用 `read_image` 看失败截图；不要只看退出码/摘要。
+2. **先判是否已经完成**：hub 显示包装确认/产品标签/箱唛已完成 ⇒ `verdict=complete`；
+   **不要重跑**，不要取消预约。
+3. **再看是否脚本/页面改版**：URL 形态、选择器、DOM 文案变化 ⇒ `repair_script`，
+   先建开发工单，不直接改生产脚本。
+4. **只有确证瞬时故障且没有写坏状态**，才允许 `retry`，并写 `safe_to_retry=true`；
+   FULL 默认最多受控重跑 1 次。
+
+`safe_to_retry=false` 的典型情况：
+
+- hub 显示已经完成；
+- 预约已取消/已产生货件号/已有产品标签或箱唛；
+- 同 SKU 同店已有重复货件；
+- 错误是业务/数据/平台状态类，而不是瞬时网络类；
+- 当前脚本版本还没修复对应问题。
+
 ## 交接上下文
 
 - 票号：`{{case}}`（第 {{attempt}} 次失败）
@@ -45,7 +81,7 @@
 | 预约状态（证据） | 能否重建 | 依据 |
 |---|---|---|
 | `failed_step ≤ 4`（步骤4未完成） | ✅ 可重建 | 预约从未提交 ⇒ 无残留（引擎的失败分支本就不触发取消） |
-| 备注含「预约已自动取消 / 无超时罚款风险」 | ✅ 可重建 | 引擎失败分支已自动取消 |
+| 备注含「预约已自动取消 / 无超时罚款风险」 | ✅ 可重建 | 仅步骤8明确取消后才会出现；失败分支不再自动取消 |
 | 备注含「预约取消失败 / 请立即人工取消」 | ⛔ **禁止重建** | 先人工取消预约，否则违约金 |
 | `failed_step ≥ 5` 且无任何取消留痕 | ⛔ **禁止重建** | 异常终止 ⇒ 先人工核对门户预约 |
 
@@ -82,6 +118,8 @@ div.day=0/hour=0)」，而**同店同 SKU 的另一张票 4 分钟后 8/8 成功
   「`ya no está disponible`」（该时段已被占）——它由引擎按 `defer` 处理（当日不重试、次日重置一次），
   **不需要**你在台账里再加工。
 
+- **失败分支不再自动取消预约**（2026-10-24）：失败后先核实 hub/门户状态；确认需要取消才走步骤8，避免假失败误取消。
+- **无评估不重跑**：`verdict != retry` 或 `safe_to_retry=false` 时，禁止派发 `--allow-write` 重跑。
 - **清号重建的唯一入口**是 `flow_retry.py`（已内置**分类闸门**＋**预约闸门**，任一不过即拒绝）；
 - **保留货件号**重派 = 续跑该货件（引擎跳过步骤3），**不会**新建货件 ⇒ 页面/选择器类失败优先走这条；
 - 你自己不能绕过闸门：需要人工放行时，请让用户用 `--override --reason '<核对说明>'`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyshu/argent-engine",
-  "version": "0.7.8",
+  "version": "0.8.0-rc.2",
   "description": "Argent 引擎（L1）：流程/台账/重试/守卫/审计/浏览器自动化 —— 逐字节来自 argent-dsh 仓库",
   "type": "module",
   "engines": {