Communitygithub.com

81211860/pdd-merchant-kit

Skill Codex pour l'automatisation de l'interface utilisateur marchand PDD et la solidification des paquets API.

Qu'est-ce que pdd-merchant-kit ?

Ce kit étend le module pdd-merchant-operator en ajoutant des capacités d'interception, d'analyse, de généralisation, de packaging et d'exécution rapide des API pour la plateforme PDD (Pinduoduo). Il fonctionne comme une couche d'amélioration (enhancement layer) et non de remplacement. L'architecture privilégie par défaut l'opérateur UI (operator-first) pour explorer les pages inconnues, automatiser les flux de travail réussis sous forme de paquets API, puis basculer vers une voie rapide API (API fast path) pour les tâches déjà validées. En cas d'échec de l'API, le système revient automatiquement à l'opérateur UI pour rafraîchir le paquet. Le kit supporte les agents Codex, Claude Code ou similaires, et fournit des commandes pour la gestion de session, l'exécution de recettes, la création manuelle ou automatique de paquets, le tout piloté par des fichiers JSON autonomes. Ce workflow garantit une exécution fiable sans nécessiter de scripts Playwright, DOM ou JS intra-page non autorisés.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. 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.
  2. 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.
  3. Seuls les packages avec confidence: verified sont utilisés comme voie rapide API par défaut.
  4. 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.
  5. Ne pas écrire par défaut de scripts Playwright, DOM ou JS intra-page pour contrôler le navigateur. browser.script --mode raw n'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)

CommandeUtilisation
session start/stop/statusSession navigateur persistante
session observe-lightObserver la page
session actExécuter une action UI
browser.script --mode read/actFallback natif de page pour diagnostic ou approbation du modèle
browser.network-recordIntercepter et sauvegarder en adaptateur
run-recipeExé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

ModuleUtilisation
src/dispatch.mjsPoint d'entrée d'ordonnancement : chercher package → API/explorer
src/exec.mjsExécution de la voie rapide API
src/analyze.mjsInterception réseau → découverte des étapes + dépendances des paramètres
src/generalize.mjsClassification des risques des champs + génération de package
packages/*.jsonPackages 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

  1. 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 ...
  2. Sauvegarder sous captures/session-xxx.json
  3. Analyse automatique pour générer le package :
    node src/analyze.mjs captures/session-xxx.json
    
  4. Vérifier packages/auto-xxx.json, ajuster manuellement :
    • Classification correcte des champs (en particulier les champs unknown nécessitent confirmation humaine)
    • Chemin verify.extract correct
    • known_issues complet
  5. Valider avec un deuxième produit → une fois validé, modifier confidence en verified

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 :

  1. Observer les requêtes API cibles dans le panneau DevTools Network du navigateur
  2. Écrire un tableau d'étapes selon le format spec/package-spec.md
  3. Chaque étape doit contenir verify (status + body + extract)
  4. Les champs non user_input / product_specific doivent être paramétrés en $input.xxx
  5. Identifier les dépendances inter-étapes $steps.id.yyy
  6. Ajouter fields_analysis pour annoter le niveau de risque de chaque champ
  7. Ajouter instructions pour l'auto-description
  8. Valider avec node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...

Règles de création de package (à respecter impérativement)

RègleDescription
instructions obligatoireAuto-description du package ; tout agent peut l'exécuter sans documentation externe
Chaque étape doit avoir verifystatus + body obligatoires, extract obligatoire en cas de dépendance
body completInterdiction de simplifier manuellement ; conserver le payload complet
Chaque champ doit avoir un risquefields_analysis : chaque champ annoté avec un niveau de risque
known_issues obligatoireAu moins déclarer les limitations connues
execution_hints obligatoireExpliquer le mode d'appel API, l'authentification, l'anti-scraping
Paramétrer les champs multi-boutiquesLes champs store_specific doivent être définis en $input.xxx
Honnêteté de la confianceNon 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 boutiques
  • store_specific — ID de modèle, configuration boutique → différent selon la boutique
  • product_specific — ID produit, SKU, catégorie → universel entre boutiques
  • user_input — Nom, prix → entrée utilisateur
  • unknown — Impossible à déterminer → nécessite intervention humaine

Pas besoin de validation multi-boutiques ; une seule interception suffit pour la classification.

Skills associés