Communitygithub.com

81211860/pdd-merchant-kit

PDD加盟店のUI自動化とAPIパッケージの定型化を行うCodexスキルです。

pdd-merchant-kit とは?

このスキルは、pdd-merchant-operatorのUI自己駆動能力をベースに、APIキャプチャ、分析、汎化、パッケージ化、高速パス実行を追加した機能拡張層(キット)です。デフォルトは「オペレーター・ファースト」戦略を採用し、信頼性が確認('verified')されたAPIパッケージのみを高速パスとして使用します。不明なタスクや未確認のタスクは、まずUIオペレーターでWebページを探索・操作し、成功した場合にネットワークキャプチャを解析してAPIパッケージ(packages/*.json)に固化します。このパッケージは任意のエージェントや言語で解釈可能な純粋JSON形式で、次回以降の高速実行を可能にします。高速パスが失敗した場合も、自動的にUIオペレーターにフォールバックして再学習します。pdd-merchant-operatorのすべての既存機能(セッション管理、UI操作、レシピ実行など)を継承しつつ、APIパッケージの作成・管理・実行のためのモジュール(dispatch, exec, analyze, generalize)を新たに提供します。

対応~Claude Code✓Codex CLI~Cursor
npx skills add 81211860/pdd-merchant-kit

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 のパッケージのみをデフォルトの API 高速パスとして使用します。
  4. API 高速パスが失敗した場合、operator UI フローに戻り、同時にキャプチャしてパッケージを更新します。
  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 自己駆動/レシピ実行
  │            │
  │            ├── 同時に CDP ネットワークキャプチャ
  │            │
  │            └── 分析 → 汎化 → packages/{task}.json 生成
  │                              └── 次回は API 高速パスへ
  │
  └── 完了

既存機能(pdd-merchant-operator 由来)

コマンド用途
session start/stop/status永続ブラウザセッション
session observe-lightページ観察
session actUI 操作実行
browser.script --mode read/act診断またはモデル承認済みのページネイティブフォールバック
browser.network-recordキャプチャとアダプタ保存
run-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 パッケージのみを 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: 手動キャプチャ → 分析 → 汎化

  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. 2 つ目の商品で検証 → 合格後 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 必須パッケージの自己記述。外部ドキュメント不要で任意のエージェントが実行可能
各ステップに 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 回のキャプチャで分類が完了します。

関連スキル