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:
- 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. - Nach erfolgreicher UI-Pfad-Ausführung und fachlicher Verifikation wird der Netzwerkmitführungsvorgang analysiert und als
packages/{platform}/*.jsonverfestigt. - Nur Pakete mit
confidence: verifiedwerden als Standard-API-Schnellpfad verwendet. - Wenn der API-Schnellpfad fehlschlägt, wird zum Operator-UI-Prozess zurückgekehrt, währenddessen der Netzwerkverkehr synchron mitgeführt und das Paket aktualisiert.
- Schreibe nicht standardmäßig Playwright-, DOM- oder JS-Skripte im Seitenkontext, um den Browser zu steuern.
browser.script --mode rawwird 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)
| Befehl | Verwendung |
|---|---|
session start/stop/status | Persistenten Browser-Session verwalten |
session observe-light | Seite beobachten |
session act | UI-Aktion ausführen |
browser.script --mode read/act | Diagnose oder vom Modell genehmigter seiteninterner Fallback |
browser.network-record | Netzwerkverkehr mitführen und Adapter speichern |
run-recipe | Rezeptdatei 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
| Modul | Verwendung |
|---|---|
src/dispatch.mjs | Dispatch-Einstieg: Paketprüfung, dann API/Erkundung |
src/exec.mjs | API-Schnellpfadausführung |
src/analyze.mjs | Netzwerkmitführung → Schrittfindung + Parameterabhängigkeiten |
src/generalize.mjs | Feldrisikoklassifikation + Paketerzeugung |
packages/*.json | Reine 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
- Führe die Zielaufgabe mit dem Operator aus, schreibe kein Browsersteuerungsskript von Hand:
session observe-light -> session act -> pageChange -> session act ... - Speichere als
captures/session-xxx.json - Automatische Analyse und Paketerstellung:
node src/analyze.mjs captures/session-xxx.json - Überprüfe
packages/auto-xxx.jsonund passe manuell an:- Korrekte Feldklassifikation (insbesondere
unknown-Felder müssen manuell bestätigt werden) - Korrektheit von
verify.extract-Pfaden - Vollständigkeit von
known_issues
- Korrekte Feldklassifikation (insbesondere
- Verifiziere mit einem zweiten Produkt → nach Bestehen
confidenceaufverifiedsetzen
Methode 3: Reine Handarbeit
Nur wenn die API-Semantik bereits verstanden und verifiziert ist, direkt JSON schreiben. Schritte:
- API-Anfragen im Browser-Netzwerkpanel (DevTools) beobachten
- Schritte im Format von
spec/package-spec.mdaufschreiben - Jeder Schritt muss
verifyenthalten (status + body + extract) - Nicht
user_input/product_specific-Felder müssen als$input.xxxparametrisiert werden $steps.id.yyyfür schrittübergreifende Abhängigkeiten identifizierenfields_analysishinzufügen, um jedes Feld mit einem Risikograd zu verseheninstructionszur Selbstbeschreibung hinzufügen- Mit
node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...verifizieren
Paketerstellungsregeln (zwingend)
| Regel | Erklärung |
|---|---|
instructions erforderlich | Selbstbeschreibung, jeder Agent kann ohne externe Dokumentation ausführen |
Jeder Schritt muss verify haben | status + body zwingend, extract erforderlich bei Abhängigkeiten |
| body vollständig | Payload nicht manuell vereinfachen, vollständigen Body beibehalten |
Felder müssen risk haben | In fields_analysis für jedes Feld Risikograd angeben |
known_issues erforderlich | Mindestens bekannte Einschränkungen deklarieren |
execution_hints erforderlich | API-Aufrufmethode, Authentifizierung, Anti-Scraping beschreiben |
| Shopübergreifende Felder parametrisieren | store_specific-Felder auf $input.xxx setzen |
| Ehrliches Vertrauensniveau | Unverifiziert 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 generischstore_specific— Vorlagen-IDs, Shop-Konfigurationen → je Shop unterschiedlichproduct_specific— Produkt-IDs, SKUs, Kategorien → shopübergreifend generischuser_input— Namen, Preise → Benutzereingabeunknown— Nicht bestimmbar → manuelle Überprüfung erforderlich
Keine Multi-Shop-Verifikation nötig, Klassifikation mit einem einzigen Mitführungsvorgang möglich.