Communitygithub.com

81211860/pdd-merchant-kit

Codex-Skill für die PDD-Merchant-UI-Automatisierung und API-Paket-Verfestigung.

Was ist pdd-merchant-kit?

Dieser Skill, basierend auf dem pdd-merchant-operator, erweitert die UI-Automatisierung um API-Paketerstellung, -Analyse und -Ausführung auf schnellen Pfaden. Er fungiert als verstärkende Schicht, die den Operator nicht ersetzt, sondern durch API-Caching erfolgreicher UI-Aktionen optimiert. Die Standardstrategie ist Operator-First: Zuerst wird die UI erkundet, nach erfolgreicher Ausführung werden Netzwerkanfragen analysiert und in selbstbeschreibenden JSON-Paketen (`packages/*.json`) verfestigt. Nur als 'verified' markierte Pakete werden automatisch auf dem schnellen API-Pfad ausgeführt. Unterstützt werden Codex und ähnliche KI-Agenten, die den Operator und die neuen Module (`dispatch.mjs`, `exec.mjs`, `analyze.mjs`, `generalize.mjs`) nutzen. Die Architektur ist zweigleisig: Bei einer Aufgabe wird zuerst geprüft, ob ein verifiziertes API-Paket existiert – falls ja, schnelle Ausführung per `page.evaluate` (~2s); falls nicht oder bei Fehlschlag, wird auf die Operator-UI zurückgegriffen und gleichzeitig der Netzwerkverkehr zur Paketerstellung aufgezeichnet.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

PDD Merchant Kit

Basiert auf der UI-Selbststeuerung von pdd-merchant-operator und erweitert diese um API-Mitführung, Analyse, Verallgemeinerung, Paketierung und schnelle Pfade. Kit ist die verstärkende Schicht des Operators, kein Ersatz.

Höchste Priorität: Operator zuerst

Die Standardstrategie ist Operator-First:

  1. Für nicht verifizierte oder unbekannte Aufgaben wird zuerst die Webseite mit dem Operator erkundet: session observe-light -> model decides -> session act -> read pageChange -> next decision.
  2. Nach erfolgreicher UI-Pfad-Ausführung und fachlicher Verifikation wird der Netzwerkmitführungsvorgang analysiert und als packages/{platform}/*.json verfestigt.
  3. Nur Pakete mit confidence: verified werden als Standard-API-Schnellpfad verwendet.
  4. Wenn der API-Schnellpfad fehlschlägt, wird zum Operator-UI-Prozess zurückgekehrt, währenddessen der Netzwerkverkehr synchron mitgeführt und das Paket aktualisiert.
  5. Schreibe nicht standardmäßig Playwright-, DOM- oder JS-Skripte im Seitenkontext, um den Browser zu steuern. browser.script --mode raw wird nur für ausdrücklich genehmigte Diagnose oder API-Verifikation verwendet.

Auch nach der Komprimierung des Kontexts muss dieser Kern erhalten bleiben: Operator steuert den Browser, API speichert nur erfolgreiche Erfahrungen zwischen. Kurzprotokoll siehe references/operator-first-protocol.md.

Dual-Mode-Architektur

Aufgabe "Abgelehntes Produkt löschen"
       │
       ▼
dispatch
  │
  ├── Gibt es in packages/ ein verified Paket?
  │   │
  │   JA ──→ exec (page.evaluate fetch, ~2s)
  │   │         │
  │   │         ❌ API-Fehler? ─→ Operator UI Rückfall + Paketaktualisierung durch Mitführung
  │   │
  │   NEIN ──→ Operator UI Selbststeuerung / Rezeptausführung
  │            │
  │            ├── Gleichzeitig CDP Netzwerkmitführung
  │            │
  │            └── Analyse → Verallgemeinerung → Erzeugung packages/{task}.json
  │                              └── Nächstes Mal direkt API-Schnellpfad
  │
  └── Fertig

Bestehende Fähigkeiten (von pdd-merchant-operator)

BefehlVerwendung
session start/stop/statusPersistenten Browser-Session verwalten
session observe-lightSeite beobachten
session actUI-Aktion ausführen
browser.script --mode read/actDiagnose oder vom Modell genehmigter seiteninterner Fallback
browser.network-recordNetzwerkverkehr mitführen und Adapter speichern
run-recipeRezeptdatei ausführen
product.*Reihe von Schnellaktionen

browser.script --mode raw ist keine Standardfähigkeit; sie kann nur mit ausdrücklicher Benutzerermächtigung oder dem Befehl --allow-raw-script verwendet werden.

Neue Fähigkeiten

ModulVerwendung
src/dispatch.mjsDispatch-Einstieg: Paketprüfung, dann API/Erkundung
src/exec.mjsAPI-Schnellpfadausführung
src/analyze.mjsNetzwerkmitführung → Schrittfindung + Parameterabhängigkeiten
src/generalize.mjsFeldrisikoklassifikation + Paketerzeugung
packages/*.jsonReine JSON-Selbstbeschreibungspakete

Befehle

Dispatch

node src/dispatch.mjs "Abgelehntes Produkt löschen" --cdp-url http://127.0.0.1:9222

Standardmäßig wird nur für verified Pakete der API-Pfad verwendet. Um die UI-Erkundung und Paketaktualisierung zu erzwingen:

node src/dispatch.mjs "Abgelehntes Produkt löschen" --operator-first --cdp-url http://127.0.0.1:9222

API-Schnellpfad

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

Mitführung analysieren

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

Paketformat

packages/*.json sind reine JSON-Selbstbeschreibungspakete. Jeder Agent, jede Sprache, ohne Skill – das JSON parsen reicht zur Ausführung.

Details siehe spec/package-spec.md.

Erstellen eines API-Pakets

Methode 1: Automatische Erkundung (mit Rezept)

node src/dispatch.mjs "Produkt auslisten" --operator-first --cdp-url http://127.0.0.1:9222

Dispatch automatisiert: UI führt Rezept aus → gleichzeitige Mitführung → analyze analysiert Schritte → generalize verallgemeinert Felder → speichert packages/xxx.json. Kein manueller Eingriff nötig.

Methode 2: Manuelle Mitführung → Analyse → Verallgemeinerung

  1. Führe die Zielaufgabe mit dem Operator aus, schreibe kein Browsersteuerungsskript von Hand: session observe-light -> session act -> pageChange -> session act ...
  2. Speichere als captures/session-xxx.json
  3. Automatische Analyse und Paketerstellung:
    node src/analyze.mjs captures/session-xxx.json
    
  4. Überprüfe packages/auto-xxx.json und passe manuell an:
    • Korrekte Feldklassifikation (insbesondere unknown-Felder müssen manuell bestätigt werden)
    • Korrektheit von verify.extract-Pfaden
    • Vollständigkeit von known_issues
  5. Verifiziere mit einem zweiten Produkt → nach Bestehen confidence auf verified setzen

Methode 3: Reine Handarbeit

Nur wenn die API-Semantik bereits verstanden und verifiziert ist, direkt JSON schreiben. Schritte:

  1. API-Anfragen im Browser-Netzwerkpanel (DevTools) beobachten
  2. Schritte im Format von spec/package-spec.md aufschreiben
  3. Jeder Schritt muss verify enthalten (status + body + extract)
  4. Nicht user_input / product_specific-Felder müssen als $input.xxx parametrisiert werden
  5. $steps.id.yyy für schrittübergreifende Abhängigkeiten identifizieren
  6. fields_analysis hinzufügen, um jedes Feld mit einem Risikograd zu versehen
  7. instructions zur Selbstbeschreibung hinzufügen
  8. Mit node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ... verifizieren

Paketerstellungsregeln (zwingend)

RegelErklärung
instructions erforderlichSelbstbeschreibung, jeder Agent kann ohne externe Dokumentation ausführen
Jeder Schritt muss verify habenstatus + body zwingend, extract erforderlich bei Abhängigkeiten
body vollständigPayload nicht manuell vereinfachen, vollständigen Body beibehalten
Felder müssen risk habenIn fields_analysis für jedes Feld Risikograd angeben
known_issues erforderlichMindestens bekannte Einschränkungen deklarieren
execution_hints erforderlichAPI-Aufrufmethode, Authentifizierung, Anti-Scraping beschreiben
Shopübergreifende Felder parametrisierenstore_specific-Felder auf $input.xxx setzen
Ehrliches VertrauensniveauUnverifiziert auf proposed, nach Verifikation auf verified setzen

Automatische Feldklassifikation

Analyze/generalize kennzeichnet jedes Feld automatisch mit einem Risikograd:

  • safe — Boolesche Werte, kleine Konstanten → shopübergreifend generisch
  • store_specific — Vorlagen-IDs, Shop-Konfigurationen → je Shop unterschiedlich
  • product_specific — Produkt-IDs, SKUs, Kategorien → shopübergreifend generisch
  • user_input — Namen, Preise → Benutzereingabe
  • unknown — Nicht bestimmbar → manuelle Überprüfung erforderlich

Keine Multi-Shop-Verifikation nötig, Klassifikation mit einem einzigen Mitführungsvorgang möglich.

Verwandte Skills