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のパッケージのみをデフォルトの API 高速パスとして使用します。- API 高速パスが失敗した場合、operator UI フローに戻り、同時にキャプチャしてパッケージを更新します。
- 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 自己駆動/レシピ実行
│ │
│ ├── 同時に CDP ネットワークキャプチャ
│ │
│ └── 分析 → 汎化 → packages/{task}.json 生成
│ └── 次回は API 高速パスへ
│
└── 完了
既存機能(pdd-merchant-operator 由来)
| コマンド | 用途 |
|---|---|
session start/stop/status | 永続ブラウザセッション |
session observe-light | ページ観察 |
session act | UI 操作実行 |
browser.script --mode read/act | 診断またはモデル承認済みのページネイティブフォールバック |
browser.network-record | キャプチャとアダプタ保存 |
run-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 パッケージのみを 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 自己完結型タスクパッケージです。任意のエージェント、任意の言語、スキル不要で JSON を解析して実行できます。
詳細は spec/package-spec.md を参照してください。
API パッケージの作成
方法 1: 自動探索(レシピがある場合)
node src/dispatch.mjs "商品を非表示" --operator-first --cdp-url http://127.0.0.1:9222
dispatch が自動的に: UI でレシピ実行 → 同時キャプチャ → 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が完全か
- フィールド分類が正しいか(特に
- 2 つ目の商品で検証 → 合格後
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 必須 | パッケージの自己記述。外部ドキュメント不要で任意のエージェントが実行可能 |
各ステップに verify 必須 | status + body 必須、extract は依存関係がある場合必須 |
| body 完全 | 手動で簡略化禁止、完全なペイロードを保持 |
フィールドに 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— 判断不能 → 手動確認が必要
複数店舗での検証は不要で、1 回のキャプチャで分類が完了します。