PDD Merchant Kit
Basé sur la capacité d'auto-contrôle UI de pdd-merchant-operator, ce kit ajoute l'interception, l'analyse, la généralisation, le packaging et l'exécution rapide des API. Le kit est une couche d'amélioration de l'opérateur, pas une couche de remplacement.
Priorité absolue : Opérateur en premier
La stratégie par défaut est operator-first :
- Pour les tâches non vérifiées ou inconnues, utiliser d'abord l'opérateur pour explorer la page web :
session observe-light -> model decides -> session act -> read pageChange -> next decision. - Une fois le chemin UI réussi et la tâche validée métier, analyser l'interception réseau et la solidifier dans
packages/{platform}/*.json. - Seuls les packages avec
confidence: verifiedsont utilisés comme voie rapide API par défaut. - En cas d'échec de la voie rapide API, revenir au processus UI de l'opérateur, intercepter simultanément et rafraîchir le package.
- Ne pas écrire par défaut de scripts Playwright, DOM ou JS intra-page pour contrôler le navigateur.
browser.script --mode rawn'est utilisé que pour un diagnostic explicitement autorisé ou une validation API.
Même après compression du contexte, cette ligne directrice doit être maintenue : l'opérateur contrôle le navigateur, l'API ne fait que mettre en cache les expériences réussies. Voir le protocole court dans references/operator-first-protocol.md.
Architecture double mode
Tâche "Supprimer les produits rejetés"
│
▼
dispatch
│
├── packages/ a-t-il un package verified ?
│ │
│ OUI ──→ exec (page.evaluate fetch, ~2s)
│ │ │
│ │ ❌ Échec API ? ──→ retour UI opérateur + interception rafraîchissement
│ │
│ NON ──→ Exécution UI auto-pilotée / recipe
│ │
│ ├── interception réseau CDP simultanée
│ │
│ └── Analyse → Généralisation → Génération packages/{task}.json
│ └── Prochaine fois utilise la voie rapide API
│
└── Terminé
Capacités existantes (de pdd-merchant-operator)
| Commande | Utilisation |
|---|---|
session start/stop/status | Session navigateur persistante |
session observe-light | Observer la page |
session act | Exécuter une action UI |
browser.script --mode read/act | Fallback natif de page pour diagnostic ou approbation du modèle |
browser.network-record | Intercepter et sauvegarder en adaptateur |
run-recipe | Exécuter un fichier recipe |
product.* | Série de raccourcis d'opérations |
browser.script --mode raw n'est pas une capacité par défaut ; seul un utilisateur explicitement autorisé ou la commande avec --allow-raw-script peut l'utiliser.
Nouvelles capacités
| Module | Utilisation |
|---|---|
src/dispatch.mjs | Point d'entrée d'ordonnancement : chercher package → API/explorer |
src/exec.mjs | Exécution de la voie rapide API |
src/analyze.mjs | Interception réseau → découverte des étapes + dépendances des paramètres |
src/generalize.mjs | Classification des risques des champs + génération de package |
packages/*.json | Packages autonomes au format JSON pur |
Commandes
Ordonnancement
node src/dispatch.mjs "Supprimer les produits rejetés" --cdp-url http://127.0.0.1:9222
Par défaut, seul un package verified passe par l'API. Pour forcer l'apprentissage/rafraîchissement depuis l'UI :
node src/dispatch.mjs "Supprimer les produits rejetés" --operator-first --cdp-url http://127.0.0.1:9222
Voie rapide API
node src/exec.mjs packages/delete-rejected-product.json \
--params '{"goods_id":"970107750738"}' --cdp-url http://127.0.0.1:9222
Analyser l'interception
node src/analyze.mjs captures/session-xxx.json
Format du package
packages/*.json sont des packages autonomes au format JSON pur. N'importe quel agent, n'importe quel langage, sans aucun skill, peut les analyser et les exécuter.
Voir spec/package-spec.md.
Créer un package API
Méthode 1 : Exploration automatique (avec recipe)
node src/dispatch.mjs "Désactiver un produit" --operator-first --cdp-url http://127.0.0.1:9222
dispatch automatise : UI exécute recipe → interception simultanée → analyze analyse les étapes → generalize généralise les champs → sauvegarde packages/xxx.json. Aucune intervention manuelle nécessaire.
Méthode 2 : Interception manuelle → Analyse → Généralisation
- Utiliser l'opérateur pour effectuer la tâche cible, sans écrire de script de contrôle navigateur :
session observe-light -> session act -> pageChange -> session act ... - Sauvegarder sous
captures/session-xxx.json - Analyse automatique pour générer le package :
node src/analyze.mjs captures/session-xxx.json - Vérifier
packages/auto-xxx.json, ajuster manuellement :- Classification correcte des champs (en particulier les champs
unknownnécessitent confirmation humaine) - Chemin
verify.extractcorrect known_issuescomplet
- Classification correcte des champs (en particulier les champs
- Valider avec un deuxième produit → une fois validé, modifier
confidenceenverified
Méthode 3 : Rédaction entièrement manuelle
Uniquement lorsque la sémantique de l'API est déjà comprise et validée, écrire directement le JSON, étapes :
- Observer les requêtes API cibles dans le panneau DevTools Network du navigateur
- Écrire un tableau d'étapes selon le format
spec/package-spec.md - Chaque étape doit contenir
verify(status + body + extract) - Les champs non
user_input/product_specificdoivent être paramétrés en$input.xxx - Identifier les dépendances inter-étapes
$steps.id.yyy - Ajouter
fields_analysispour annoter le niveau de risque de chaque champ - Ajouter
instructionspour l'auto-description - Valider avec
node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...
Règles de création de package (à respecter impérativement)
| Règle | Description |
|---|---|
instructions obligatoire | Auto-description du package ; tout agent peut l'exécuter sans documentation externe |
Chaque étape doit avoir verify | status + body obligatoires, extract obligatoire en cas de dépendance |
| body complet | Interdiction de simplifier manuellement ; conserver le payload complet |
| Chaque champ doit avoir un risque | fields_analysis : chaque champ annoté avec un niveau de risque |
known_issues obligatoire | Au moins déclarer les limitations connues |
execution_hints obligatoire | Expliquer le mode d'appel API, l'authentification, l'anti-scraping |
| Paramétrer les champs multi-boutiques | Les champs store_specific doivent être définis en $input.xxx |
| Honnêteté de la confiance | Non vérifié = proposed, vérifié = verified |
Classification automatique des champs
analyze/generalize annotent automatiquement le risque de chaque champ :
safe— Booléen, petite constante numérique → universel entre boutiquesstore_specific— ID de modèle, configuration boutique → différent selon la boutiqueproduct_specific— ID produit, SKU, catégorie → universel entre boutiquesuser_input— Nom, prix → entrée utilisateurunknown— Impossible à déterminer → nécessite intervention humaine
Pas besoin de validation multi-boutiques ; une seule interception suffit pour la classification.