81211860/pdd-merchant-kit

PDD Merchant Kit

基于 pdd-merchant-operator 的 UI 自驱动能力，增加 API 抓包、分析、泛化、打包和快路径执行。kit 是 operator 的增强层，不是替代层。

Highest Priority: Operator First

默认策略是 operator-first：

1. 未验证或未知任务先用 operator 探索网页：session observe-light -> model decides -> session act -> read pageChange -> next decision。
2. UI 路径成功并完成业务验证后，分析本次网络抓包并固化为 packages/{platform}/*.json。
3. 只有 confidence: verified 的 package 才作为默认 API 快路径。
4. API 快路径失败时，回到 operator UI 流程，同步抓包并刷新 package。
5. 不要默认编写 Playwright、DOM、页面内 JS 脚本来控制浏览器。browser.script --mode raw 仅用于明确授权的诊断或 API 验证。

压缩上下文后也必须保留这条主线：operator 控制浏览器，API 只缓存成功经验。短协议见 references/operator-first-protocol.md。

双模式架构

任务 "删除驳回商品"
       │
       ▼
dispatch
  │
  ├── packages/ 有 verified 包？
  │   │
  │   YES ──→ exec (page.evaluate fetch, ~2s)
  │   │         │
  │   │         ❌ API 失败？─→ operator UI 回退 + 抓包刷新
  │   │
  │   NO ──→ operator UI 自驱动/recipe 执行
  │            │
  │            ├── 同时 CDP 网络抓包
  │            │
  │            └── 分析 → 泛化 → 生成 packages/{task}.json
  │                              └── 下次就走 API 快路径
  │
  └── 完成

现有能力（from pdd-merchant-operator）

命令	用途
session start/stop/status	持久浏览器 session
session observe-light	观察页面
session act	执行 UI 操作
browser.script --mode read/act	诊断或模型批准的页面原生 fallback
browser.network-record	抓包并保存适配器
run-recipe	执行 recipe 文件
product.*	一系列快捷操作

browser.script --mode raw 不是默认能力；只有用户明确授权或命令传 --allow-raw-script 时才能使用。

新增能力

模块	用途
src/dispatch.mjs	调度入口：查包→API/探索
src/exec.mjs	API 快路径执行
src/analyze.mjs	网络抓包→步骤发现+参数依赖
src/generalize.mjs	字段风险分类+包生成
packages/*.json	纯 JSON 自包含任务包

命令

调度

node src/dispatch.mjs "删除已驳回商品" --cdp-url http://127.0.0.1:9222

默认只对 verified package 走 API。要强制从 UI 学习/刷新包：

node src/dispatch.mjs "删除已驳回商品" --operator-first --cdp-url http://127.0.0.1:9222

API 快路径

node src/exec.mjs packages/delete-rejected-product.json \
  --params '{"goods_id":"970107750738"}' --cdp-url http://127.0.0.1:9222

分析抓包

node src/analyze.mjs captures/session-xxx.json

包格式

packages/*.json 是纯 JSON 自包含任务包。任何 agent、任何语言、无需任何 skill，解析 JSON 即可执行。

详见 spec/package-spec.md。

创建 API 包

方式 1：自动探索（有 recipe 时）

node src/dispatch.mjs "下架商品" --operator-first --cdp-url http://127.0.0.1:9222

dispatch 自动：UI 执行 recipe → 同时抓包 → analyze 分析步骤 → generalize 泛化字段 → 保存 packages/xxx.json。无需手动干预。

方式 2：手动抓包 → 分析 → 泛化

1. 用 operator 操作目标任务，不要手写浏览器控制脚本： session observe-light -> session act -> pageChange -> session act ...
2. 保存为 captures/session-xxx.json
3. 自动分析生成包：

   node src/analyze.mjs captures/session-xxx.json
   

4. 检查 packages/auto-xxx.json，手动调整：
   • 字段分类是否正确（特别是 unknown 的字段需人工确认）
   • verify.extract 路径是否正确
   • known_issues 是否完整
5. 用第二商品验证 → 通过后改 confidence 为 verified

方式 3：纯手工编写

仅在已经理解并验证 API 语义时直接写 JSON，步骤：

1. 在浏览器 DevTools Network 面板观察目标 API 请求
2. 按 spec/package-spec.md 格式编写步骤数组
3. 每步必须包含 verify（status + body + extract）
4. 非 user_input / product_specific 字段必须参数化为 $input.xxx
5. 识别 $steps.id.yyy 跨步骤依赖
6. 添加 fields_analysis 标注每个字段风险等级
7. 添加 instructions 自描述
8. 用 node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ... 验证

包创建规范（必须遵守）

规则	说明
instructions 必填	包自描述，任何 agent 无需外部文档即可执行
每步必有 verify	status + body 必填，extract 有依赖时必填
body 完整	禁止手动简化，保留完整 payload
字段必有 risk	fields_analysis 中每个字段标注风险等级
known_issues 必填	至少声明已知限制
execution_hints 必填	说明 API 调用方式、认证、反爬
跨店无关字段参数化	store_specific 字段必须设为 $input.xxx
置信度诚实	未验证设为 proposed，验证后设为 verified

字段自动分类

analyze/generalize 对每个字段自动标注风险：

• safe — 布尔值、小数值常量 → 跨店铺通用
• store_specific — 模板ID、店铺配置 → 不同店铺不同
• product_specific — 商品ID、SKU、类目 → 跨店铺通用
• user_input — 名称、价格 → 用户输入
• unknown — 无法确定 → 需人工

无需多店铺验证，单次抓包即可完成分类。