Communitygithub.com

81211860/pdd-merchant-kit

Codex 技能,用於拼多多商家 UI 自動化與 API 封裝強化。

pdd-merchant-kit 是什麼?

這個技能是 pdd-merchant-operator 的增強層,專門為 Codex 等 AI 代理設計,用於拼多多(PDD)商家後台的自動化操作。它的核心原則是「operator-first」:預設透過 UI 流程探索網頁,只有在任務成功驗證後,才會將經驗固化為 API 套件,並在下次執行時走快速 API 路徑。技能支援雙模式架構,透過「dispatcher」模組自動判斷是否有驗證過的 API 套件,若有則直接執行 API 請求(約 2 秒),若失敗則回退到 UI 流程並同步抓包刷新。它還內建抓包分析、字段泛化與風險分類能力,能自動從單次操作中產生可重複使用的任務套件。這個技能主要與瀏覽器 session 管理結合運作,不建議直接使用 Playwright 或 DOM 腳本控制瀏覽器,而是讓 AI 代理先觀察、再行動,最後將成功的操作路徑封裝成純 JSON 套件,供後續快速呼叫。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add 81211860/pdd-merchant-kit

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

PDD Merchant Kit

基於 pdd-merchant-operator 的 UI 自驅動能力,增加 API 抓包、分析、泛化、打包和快路徑執行。kit 是 operator 的增強層,不是替代層。

最高優先級: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.mjsAPI 快路徑執行
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 無需外部文件即可執行
每步必有 verifystatus + body 必填,extract 有依賴時必填
body 完整禁止手動簡化,保留完整 payload
欄位必有 riskfields_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 — 無法確定 → 需人工

無需多店鋪驗證,單次抓包即可完成分類。

相關技能