PDD Merchant Kit
基於 pdd-merchant-operator 的 UI 自驅動能力,增加 API 抓包、分析、泛化、打包和快路徑執行。kit 是 operator 的增強層,不是替代層。
最高優先級:Operator First
預設策略是 operator-first:
- 未驗證或未知任務先用 operator 探索網頁:
session observe-light -> model decides -> session act -> read pageChange -> next decision。 - UI 路徑成功並完成業務驗證後,分析本次網路抓包並固化為
packages/{platform}/*.json。 - 只有
confidence: verified的 package 才作為預設 API 快路徑。 - API 快路徑失敗時,回到 operator UI 流程,同步抓包並刷新 package。
- 不要預設編寫 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:手動抓包 → 分析 → 泛化
- 用 operator 操作目標任務,不要手寫瀏覽器控制腳本:
session observe-light -> session act -> pageChange -> session act ... - 儲存為
captures/session-xxx.json - 自動分析生成包:
node src/analyze.mjs captures/session-xxx.json - 檢查
packages/auto-xxx.json,手動調整:- 欄位分類是否正確(特別是
unknown的欄位需人工確認) verify.extract路徑是否正確known_issues是否完整
- 欄位分類是否正確(特別是
- 用第二商品驗證 → 通過後改
confidence為verified
方式 3:純手工編寫
僅在已經理解並驗證 API 語義時直接寫 JSON,步驟:
- 在瀏覽器 DevTools Network 面板觀察目標 API 請求
- 按
spec/package-spec.md格式編寫步驟陣列 - 每步必須包含
verify(status + body + extract) - 非
user_input/product_specific欄位必須參數化為$input.xxx - 識別
$steps.id.yyy跨步驟依賴 - 添加
fields_analysis標註每個欄位風險等級 - 添加
instructions自描述 - 用
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— 無法確定 → 需人工
無需多店鋪驗證,單次抓包即可完成分類。