@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/skills/ml-fulfillment-sop/references/pitfalls.md

@@ -0,0 +1,77 @@
+# 已知陷阱与修复（踩坑清单）
+
+按出现频率排序的经验教训。改动脚本或排障时先对照本清单，避免重复踩坑。
+
+## 导航栏误触
+
+- 现象：checkbox 选择器命中顶部导航栏的用户切换组件（`#nav-header-user-switch`），勾选错误元素
+- 修复：checkbox 限定到 `main` 容器内查找；`_scope` 参数只对 checkbox 生效
+
+## 货件号 ≠ URL 编号
+
+- 现象：从 URL（inbound 编号）提取货件号，与实际货件号不一致
+- 修复：货件号从 DOM 标题元素提取，不使用 URL inbound 编号
+
+## React 动态 ID 大小写
+
+- 现象：动态 ID 大小写不稳定（`_r_` vs `_R_`），选择器漏匹配
+- 修复：CSS `[id^="_r_"]` 区分大小写，需同时覆盖两种写法；数量输入框不是 `type="number"`
+
+## 产品标 PDF 前缀
+
+- 现象：下载的产品标文件名带 `Envio-` 前缀，按 `*Etiquetas-de-productos.pdf` 匹配时漏掉
+- 修复：文件名模式用 `Envio-*-Etiquetas-de-productos.pdf`
+
+## 下载目录
+
+- 下载目录为 `ziniaobrowserdatas/{店铺名}/`，多店铺时按店铺名区分，勿混用
+
+## PDF 命名规则
+
+- 产品标：`产品标 + SKU + ML码 + 品名 + 店名`
+- 箱唛：`货件号 + {箱数}箱 + 品名`（用户 2026-09-15 明确口径；此前误写"店名"，已更正）
+
+## 排除无关 PDF
+
+- 排除 listado / Descargar / preparation 产品列表等非目标 PDF 文件
+
+## 货件终态跳过
+
+- 货件终态 `Reserva cancelada` 应跳过，不再继续处理
+
+## wait_for_url 时序
+
+- `wait_for_url` 在 hub-v2 之后提取，避免过早读取旧页面内容
+
+## 页面切换等待
+
+- 页面切换用旋转蒙层（spinner）等待替代固定 sleep，避免竞态与超时
+
+## ⛔ 步骤7「未见 Agrupa tu stock」被误判成「门户改版」（2026-10-12 事故：同一票连错 5 次）
+
+- **现场**：货件 `79301358` / SKU `HW-MX-162` / 1 店，步骤7 **连续 5 次**失败，文案一律
+  「页面未到箱数填写页：2 轮自愈+重导航后仍未见「Agrupa tu stock」」。
+- **错在哪**：这句话**只说"没看到什么"，不说"页面到底是什么样"**。角色据此把它刻度成
+  「**脚本缺陷/门户改版**（`Agrupa tu stock` 入口缺失）⇒ 需 ml-dev 修复选择器」——
+  **误导**：ml-dev 无从下手（元素一个都没变），票还一直占着槽位。
+- **真因**：商品被判**超大件**（units 页 `size-dimensions-tag` = `EXTRAGRANDE`、
+  `volume-pill` = `11,712 cm 3`），而该货件空间**只收中小件**（原文「Pequeños y medianos —
+  Este espacio incluye a los productos Pequeños y medianos.」）⇒ 库存输入框
+  （`aria-label="Stock a enviar"`，值 200）被平台渲染成 **disabled** ⇒ 到不了箱数填写页。
+  hub 第 5 项「Prepara bultos y/o pallets con tus productos e identifícalos」恒 `done=False`，
+  紧随其后「Debes completar las tareas anteriores para preparar e identificar.」。
+- **⛔ 脚本侧无解**：运营实测把那个 disabled 输入框**强制启用 + 重输 + 点 Guardar**
+  （units 页 `Guardar`）**没有任何效果**（hub 项不变）。正确动作只有运营侧两个：
+  **修正商品包装尺寸**（改到该空间接受的分级）**或改走其他渠道/货件**。
+- **已修**（判据缺失 ⇒ 报错误导）：步骤7 失败路径先做一次**只读归因探测**
+  （hub-v2 + units 页，只 `navigate` + `evaluate`），命中即改抛**可执行结论**：
+  ① 尺寸分级阻塞（带 tag/体积/空间原文）② 前置未完成（列未完成项原文）③ 都不是 ⇒
+  保留旧文案 + 补证据（`Agrupa tu stock` 缺失 / 当时 URL / 自愈轮数，供 ml-dev 排查真正的改版）。
+  判据是**纯函数** `scripts/ml_hub_status.py#step7_block_verdict`（离线可回归）。
+  观察点登记见 `references/selectors.md` §「商品尺寸页（units）与尺寸分级阻塞」。
+- **教训（可推广）**：**"没看到预期元素"不是结论，是问题**。凡失败文案只说"未见 X"，
+  下一个人（或下一个角色）就只能**猜**页面长什么样 —— 猜出来的"门户改版/脚本缺陷"
+  会把票推给**根本修不了它的人**。失败文案必须**先读页面、再写结论**，并且带**原文**。
+- **口径变化（有意）**：新文案含「需运营…」⇒ 分类从 `needs_agent`（唤醒角色去猜）
+  变为 `needs_human`（落卡等人、运营改商品）。⛔ 这是本事故要的结果，不是副作用。
+

package/engine/skills/ml-fulfillment-sop/references/selectors.md

@@ -0,0 +1,243 @@
+# MercadoLibre FULL 页面 CSS 选择器映射
+
+## 维护说明
+- 美客多后台使用 **Andes** 设计系统（`andes-table`、`andes-button`、`andes-card` 等）
+- 原生 `querySelectorAll` **不支持** `:contains()` / `:has-text()` 伪类——这些是 jQuery/Sizzle 扩展
+- 数据提取策略：CSS 选择器定位结构容器 → JavaScript 遍历 textContent 匹配内容
+- 每次 UI 变更后更新「最后验证日期」
+- 关键页面：`https://myaccount.mercadolibre.com.mx/shipping/inbounds`
+
+## 当前有效选择器（Playwright CDP，2026-08-05）
+
+| 元素 | 选择器 / 提取方式 | 说明 |
+|------|------------------|------|
+| 数量输入框 | `input[id^="_r_"], input[id^="_R_"]` | ⚠️ 不是 `type="number"`，用 ID 前缀匹配 |
+| Checkbox | 限定到 `main` 容器 | 排除 `#nav-header-user-switch`，防导航栏误触 |
+| 产品标 PDF | 文件名模式 `Envio-*-Etiquetas-de-productos.pdf` | `Envio-` 前缀容易漏 |
+| 货件号 | 从 DOM 标题元素提取 | 不是 URL inbound 编号 |
+| ML 码 | `match(/[A-Z]{4}[0-9]+/)` 搜子串 | 用正则扫文本 |
+| 预约确认按钮 | 双 Confirmar | 日历确认 top<700 + 主确认 top≈800 |
+| 教程蒙层 | `aria-label=Close` + `andes-coach-marks` | 关闭新手引导浮层 |
+| Enviar productos | `<a>` 标签 + force=True | 链接型按钮需强制点击 |
+| 大货件地址 MXCD05 | card footer Continuar force=True | 特殊地址流程的确认按钮 |
+
+## 已验证信息（2026-07-27）
+
+| 项目 | 值 |
+|------|-----|
+| 表格类名 | `andes-table` |
+| 表格列（th） | Envío / Declaradas-Aptas / Cita reservada / Cargo aplicado / Estado / Acciones |
+| 按钮组件 | `andes-button`（A 标签或 BUTTON 标签） |
+| 状态文本容器 | `TD.andes-table__column` → `DIV.andes-typography` |
+| 操作列容器 | `TD.andes-table__column` → `DIV.table-actions-column` |
+| 卡片容器 | `andes-card` |
+| 已验证货件状态值 | Vencido, En preparación, Pendiente de recepción, Procesamiento finalizado |
+
+---
+
+## 步骤 1：前期准备 [已验证 ✅]
+
+### 选择器（CSS 结构定位）
+
+| 元素 | CSS 选择器 | 验证状态 | 说明 |
+|------|-----------|----------|------|
+| 货件列表表格 | `table.andes-table` | ✅ 已验证 | 页面唯一表格 |
+| 货件行 | `table.andes-table tbody tr` | ✅ 已验证 | 每行一个货件 |
+| 状态列单元格 | `td.andes-table__column` (第 5 列, 0-indexed) | ✅ 已验证 | 表头第 5 列 = "Estado" |
+| 操作列单元格 | `td.andes-table__column` (第 6 列) | ✅ 已验证 | 表头第 6 列 = "Acciones" |
+| 库容警告容器 | `.andes-card`（含 "liberar espacio" 文本） | ✅ 已验证 | 出现在页面顶部 |
+
+### 库容警告的**严格阻断形态**（2026-10-12 判据收紧，⛔ 别只看关键词）
+
+⚠️ 库容警告的**关键词本身不是判据**：`ml_capacity_probe` 要求「关键词 ∧ 阻断形态」同时成立才算仓容满
+（只出现提示文案、主按钮仍可点 ⇒ 不算）。判据是**纯函数**，可离线回归。
+
+### 数据提取方式（JavaScript）
+
+由于 Andes 组件 class 名不包含业务语义，数据提取**必须用 textContent 匹配**：
+
+```javascript
+// 检查过期货件
+const rows = document.querySelectorAll('table.andes-table tbody tr');
+const vencidos = Array.from(rows).filter(row => 
+  row.textContent.includes('Vencido')
+);
+
+// 统计各状态数量
+const statuses = {};
+rows.forEach(row => {
+  const cells = row.querySelectorAll('td');
+  const status = cells[4]?.textContent?.trim(); // 第 5 列 = Estado
+  if (status) statuses[status] = (statuses[status] || 0) + 1;
+});
+
+// 检测库容警告
+const warning = Array.from(document.querySelectorAll('.andes-card'))
+  .find(card => card.textContent.includes('liberar espacio'));
+```
+
+---
+
+## 步骤 2：进入创建入口 [已验证 ✅]
+
+| 元素 | 定位方式 | 验证状态 | 说明 |
+|------|----------|----------|------|
+| "Enviar productos" 按钮 | `a.andes-button` 且 textContent === "Enviar productos" | ✅ 已确认组件类型 | ⚠️ 库容满时此按钮不显示/禁用，页面显示"Para enviar productos, primero deberás liberar espacio..." |
+
+```javascript
+const enviarBtn = Array.from(document.querySelectorAll('a.andes-button'))
+  .find(btn => btn.textContent.trim() === 'Enviar productos');
+```
+
+---
+
+## 步骤 3-5：创建货件表单
+
+### 步骤 3：选择产品与数量 [✅ 已部分验证]
+
+> 已验证：配送计划页面的 SKU 搜索、数量填写、继续按钮。
+
+| 元素 | 定位方式 | 验证状态 |
+|------|----------|----------|
+| SKU 搜索框 | `input[placeholder*="搜索产品"]` | ✅ 已验证 |
+| 数量输入 | `input.andes-form-control__field`（搜索结果行的可见 input） | ✅ 已验证 |
+| "继续" 按钮 | `button.andes-button` + textContent === "继续" | ✅ 已验证 |
+| 明星产品弹窗 "维持现有方案" | textContent 匹配 → click 关闭 | ✅ 已验证 |
+
+### 步骤 4：预约时间 [✅ 已验证]
+
+> 已验证：配送方式下拉、focus-ui-calendar 日期选择、时间槽、确认按钮。
+> 页面：`/shipping/inbounds/{id}/appointment-v2`
+
+| 子步骤 | 元素 | 定位方式 | 验证状态 |
+|--------|------|----------|----------|
+| 配送方式下拉 | `[id*=shipment-type-selection]` | id 前缀匹配 | ✅ |
+| "Vehículo particular" | 叶子 SPAN，textContent === "Vehículo particular" | textContent 精确匹配 | ✅ |
+| 日期输入框 | `input[readonly][id^="_R_"]` | 只读，动态 ID 以 `_R_` 开头 | ✅ |
+| 当前月份 | `.focus-ui-datepicker__content__month-year` | 如 "julio 2026" | ✅ |
+| 下月按钮 | `.focus-ui-datepicker__content__next_month_selector` | aria-label="next month" | ✅ |
+| 上月按钮 | `.focus-ui-datepicker__content__back_month_selector` | aria-label="back month" | ✅ |
+| 可选日期 | `div.day:not(.day--disabled)` | 排除 `day--disabled` 的格子 | ✅ |
+| 已选日期 | `div.day--selected` | 已选日期（可能同时 disabled） | ✅ |
+| 时间槽 | `.date-time-card-content` 内 textContent 匹配 `/\d{1,2}:\d{2}/` 的叶子元素 | 动态渲染 | ✅ |
+| 确认按钮 | `button:not([disabled])` + textContent === "Confirmar" | 需等时间槽选定后才启用 | ✅ |
+
+**自动化算法（⚠️ 2026-07-27 更新：robustClick 模式）**：
+```javascript
+// robustClick: 攻克 Andes React 组件的鼠标事件序列
+function rc(el){ el.scrollIntoView();el.focus();
+  el.dispatchEvent(new MouseEvent("mousedown",{bubbles:true}));
+  el.dispatchEvent(new MouseEvent("mouseup",{bubbles:true}));
+  el.dispatchEvent(new MouseEvent("click",{bubbles:true,cancelable:true,view:window})); }
+
+// 1. 选配送方式
+rc(document.querySelector("[role=combobox]")); // 打开下拉
+// 在 [role=option] 中找 textContent 含 "Vehículo particular" → rc()
+
+// 2. 选日期
+rc(document.getElementById("_r_j_")); // 打开日历
+// 翻月: rc(document.querySelector("[aria-label=\"next month\"]"));
+// ⚠️ 日历格子点击: rc() 无法触发 React onChange
+// → **此步目前需人工点击**，其余 7 步全自动
+
+// 3. 选时间
+// 在 date-time-card-content 内找 textContent 匹配 /\d{1,2}:\d{2}/ → rc()
+
+// 4. 确认
+// 先点日历 Confirmar (top<700 的), 再点主 Confirmar (_r_k_)
+```
+
+### 步骤 5：包装确认 [⚠️ 待验证]
+
+| 元素 | 定位方式 | 验证状态 |
+|------|----------|----------|
+| 包装确认复选框 | 待确认 | ⚠️ 待验证 |
+
+---
+
+## 步骤 6-8：标签/箱唛/取消
+
+### 步骤 6：标签下载 [✅ 已验证]
+
+> 已验证：通过 Hub 页「Revisar」链接进入标签页、复选框（Andes 组件需 MouseEvent）、下载弹窗、确认。
+
+| 元素 | 定位方式 | 验证状态 | 备注 |
+|------|----------|----------|------|
+| Hub 页入口（初始） | `[data-testid="link-identifiers"]`（卡片本身 `role="button"`） | ✅ | 首次进入，右侧 SVG 箭头是卡片视觉元素，整个卡片可点击 |
+| Hub 页入口（二次） | `a[href*="labeling"]` + textContent === "Revisar" | ✅ | 进入过一次后出现 |
+| 产品展开按钮 | `button` + textContent === "Producto" | ✅ | 展开产品列表 |
+| 复选框 | `input[type=checkbox]` 在 `.andes-checkbox__checkbox` 内 | ✅ | **必须用 MouseEvent 而非 .click()** |
+| Descargar etiquetas | `button` + textContent === "Descargar etiquetas" + `!disabled` | ✅ | 复选框勾选后启用 |
+| 弹窗 PDF 选项 | `button` + textContent === "PDF" + `inModal` | ✅ | 默认已选中 |
+| 弹窗 Descargar | `button` + textContent === "Descargar" + `inModal` | ✅ | 触发下载 |
+| Confirmar | `button` + textContent === "Confirmar" | ✅ | 完成标签步骤 |
+
+**关键 Pitfall**：Andes 复选框是 React 受控组件，`cb.click()` **不会触发 React onChange**——必须用：
+```javascript
+cb.dispatchEvent(new MouseEvent("click", {bubbles: true, cancelable: true, view: window}));
+```
+复选框 DOM `checked` 属性不会更新，但 React 内部状态会正确更新。
+
+---
+
+## 从页面内容提取数据的完整模式
+
+`ziniao-cli page content --content-format text` 返回的纯文本已包含所有业务数据，正则提取比 CSS 选择器更可靠：
+
+```javascript
+// 从 page content 文本中提取货件列表
+const text = pageContent; // ziniao-cli page content 返回的纯文本
+
+// 匹配货件行：货件号 + 声明数/合格数 + 日期(可选) + 状态 + 操作
+const shipmentPattern = /#(\d{8})\s+(\d+)\s*\/\s*(\S+)\s+([\d\/]+\s+\S+(?:\s+\d+:\d+)?\s*(?:hs)?\s+[^VEPC]*)?\s+(Vencido|En preparación|Pendiente de recepción|Procesamiento finalizado)\s+(Revisar detalle|Completar envío)/g;
+
+let match;
+while ((match = shipmentPattern.exec(text)) !== null) {
+  // match[1] = 货件号, match[2] = 声明数, match[3] = 合格数
+  // match[5] = 状态, match[6] = 操作
+}
+```
+
+**优势**：纯文本提取不依赖 CSS 选择器，UI 改版后仍可工作（只要文本内容不变）。
+
+---
+
+## 注意
+- `:has-text()` 和 `:contains()` **不可用**——这是 jQuery 扩展，标准 CSS / `querySelectorAll` 不支持
+- Andes 组件 class 名（`andes-button__content`、`andes-typography`）是内部实现细节，可能随版本变更
+- **推荐策略**：结构定位用 CSS（`table.andes-table`），内容匹配用 textContent
+- 纯文本正则提取（`page content`）是最稳定的数据采集方式，优先使用
+
+---
+
+## 商品尺寸页（units）与「⛔ 尺寸分级阻塞」（2026-10-12 实测登记）
+
+### 两个页面的分工（⛔ 别只看 hub）
+
+| 页面 | URL | 能看到什么 |
+|------|-----|-----------|
+| hub-v2 | `/shipping/inbounds/<货件号>/hub-v2` | 逐项任务卡（`done` 状态）+「Tienes N producto para revisar」+「Debes completar las tareas anteriores para preparar e identificar.」｜**看不到商品尺寸分级** |
+| units | `/shipping/inbounds/<货件号>/units?from=hub` | 商品尺寸分级 / 体积 / 空间口径 / 库存输入框渲染态｜= hub 上「Tienes N producto para revisar」右侧【**Editar**】的 href |
+
+### units 页新观察点（2026-10-12 现场，货件 79301358 / SKU HW-MX-162 / 1 店）
+
+| 元素 | 定位方式 | 现场实测值 | 说明 |
+|------|----------|-----------|------|
+| 尺寸分级标签 | `[data-testid="size-dimensions-tag"]` | **`EXTRAGRANDE`** | ⚠️ 取值是**西语原文**（`PEQUEÑO`/`MEDIANO`/`GRANDE`/`EXTRAGRANDE`…），大小写/重音需归一化后再比 |
+| 体积胶囊 | `[data-testid="volume-pill"]` | **`11,712 cm 3`** | 原文带千分位与空格，**照抄原文**留痕（别自己格式化） |
+| 空间口径原文 | 正文文本 | 「**Pequeños y medianos** — Este espacio incluye a los productos Pequeños y medianos. Revisa el tamaño de cada uno junto a su nombre.」 | 描述的是**空间**（这个空间只收中小件），⛔ **不是**"这个商品有问题"的判据 |
+| 尺寸规则入口 | 链接文本 | 「Revisar dimensiones permitidas」｜「Cómo clasifican los productos por tamaño」 | 同上，只作佐证 |
+| 库存输入框 | `[aria-label="Stock a enviar"]`（`[data-testid^="input-textfield"]`） | 值 `200`，**被平台渲染为 `disabled`**：外层 `andes-form-control--disabled` + `data-andes-state="disabled"`，位于 `.andes-tooltip__trigger` 内 | 运营实测：**强制启用 + 重输 + 点 Guardar 没有任何效果**（hub 项不变）⇒ ⛔ 别写"自动启用它"的补丁 |
+
+### ⛔ 尺寸分级阻塞 = **运营侧**，脚本侧无解
+
+**判据（唯一实现 `scripts/ml_hub_status.py#step7_block_verdict`，纯函数、可离线回归）：**
+出现 `size-dimensions-tag` **且值 ∉ 中小件允许集**（`PEQUEÑO`/`MEDIANO` 族）⇒
+**该商品被平台判为超大件，而本货件空间只收中小件** ⇒ 步骤7 **进不了箱数页**（hub 第 5 项
+「Prepara bultos y/o pallets…」恒 `done=False`）。
+
+- **正确动作（运营）**：修正商品包装尺寸（改小到该空间接受的分级）**或**改走其他渠道/货件。
+- **⛔ 不是门户改版、⛔ 不是选择器缺陷、⛔ 无需 ml-dev 改脚本** —— 页面元素一个都没变，
+  是平台按尺寸**合规性**把库存输入框锁成 disabled。
+- ⚠️ **判别力**：空间文案「Pequeños y medianos…」在**任何一个**中小件货件的 units 页都会出现
+  ⇒ 单凭它判"尺寸阻塞"会把正常票全判错。判据必须是**商品自己的尺寸标签**。