Communitygithub.com

81211860/pdd-merchant-kit

Skill para la automatización de UI de comerciantes de PDD y la consolidación de paquetes API

¿Qué es pdd-merchant-kit?

Este skill para Codex, denominado PDD Merchant Kit, es una capa de mejora sobre `pdd-merchant-operator` que añade la capacidad de interceptar, analizar, generalizar, empaquetar y ejecutar rápidamente llamadas API. Sigue una arquitectura de doble modo: siempre intenta primero la ruta rápida de API (usando paquetes predefinidos con `confidence: verified`) y, si falla o no hay paquete disponible, recurre al operador UI para explorar la página web de forma autónoma. Durante la ejecución por UI, captura automáticamente el tráfico de red, lo analiza y genera paquetes JSON autocontenidos que pueden usarse en el futuro sin necesidad de volver a navegar. Está diseñado para trabajar exclusivamente en el contexto de PDD (Pinduoduo) y su ecosistema de comerciantes, utilizando un navegador persistente. El skill prioriza el uso del operador UI sobre scripts de Playwright o DOM, y solo permite scripts raw bajo autorización explícita. Su salida principal son paquetes en `packages/*.json`, que cualquier agente (independientemente del lenguaje o skill) puede consumir directamente.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

PDD Merchant Kit

Basado en la capacidad de autoconducción de UI de pdd-merchant-operator, agrega captura, análisis, generalización, empaquetado y ejecución rápida de API. kit es una capa de mejora sobre operator, no un reemplazo.

Prioridad Máxima: Operator First

La estrategia predeterminada es operator-first:

  1. Para tareas no verificadas o desconocidas, primero explora la página web con operator: session observe-light -> model decides -> session act -> read pageChange -> next decision.
  2. Una vez que la ruta UI tiene éxito y se completa la verificación del negocio, analiza la captura de red de esta sesión y la consolida en packages/{platform}/*.json.
  3. Solo los paquetes con confidence: verified se usan como ruta rápida de API por defecto.
  4. Si la ruta rápida de API falla, se vuelve al flujo UI de operator, capturando simultáneamente la red y actualizando el paquete.
  5. No escribir scripts de Playwright, DOM o JavaScript dentro de la página para controlar el navegador por defecto. browser.script --mode raw solo se usa para diagnósticos explícitamente autorizados o verificación de API.

Incluso al comprimir el contexto, se debe mantener esta línea principal: operator controla el navegador, API solo almacena en caché experiencias exitosas. Ver el protocolo corto en references/operator-first-protocol.md.

Arquitectura de Doble Modo

Tarea "Eliminar producto rechazado"
       │
       ▼
dispatch
  │
  ├── ¿Hay un paquete verificado en packages/?
  │   │
  │   SÍ ──→ exec (page.evaluate fetch, ~2s)
  │   │         │
  │   │         ❌ ¿Fallo de API? ──→ Retroceso a operator UI + actualización de captura
  │   │
  │   NO ──→ Ejecución autoconducida de operator UI / recipe
  │            │
  │            ├── Captura de red CDP simultánea
  │            │
  │            └── Análisis → Generalización → Generar packages/{tarea}.json
  │                              └── La próxima vez usará la ruta rápida de API
  │
  └── Completado

Capacidades Existentes (de pdd-merchant-operator)

ComandoPropósito
session start/stop/statusSesión persistente del navegador
session observe-lightObservar la página
session actEjecutar acción UI
browser.script --mode read/actFallback nativo de página para diagnóstico o aprobado por modelo
browser.network-recordCapturar red y guardar adaptador
run-recipeEjecutar archivo de recipe
product.*Serie de operaciones rápidas

browser.script --mode raw no es una capacidad predeterminada; solo se puede usar con autorización explícita del usuario o pasando --allow-raw-script en el comando.

Capacidades Nuevas

MóduloPropósito
src/dispatch.mjsPunto de entrada de despacho: buscar paquete → API / explorar
src/exec.mjsEjecución de ruta rápida de API
src/analyze.mjsCaptura de red → descubrimiento de pasos + dependencias de parámetros
src/generalize.mjsClasificación de riesgo de campos + generación de paquete
packages/*.jsonPaquete de tarea autocontenido en JSON puro

Comandos

Despacho

node src/dispatch.mjs "Eliminar producto rechazado" --cdp-url http://127.0.0.1:9222

Por defecto solo usa API para paquetes verificados. Para forzar aprendizaje / actualización de paquete desde UI:

node src/dispatch.mjs "Eliminar producto rechazado" --operator-first --cdp-url http://127.0.0.1:9222

Ruta Rápida de API

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

Analizar Captura

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

Formato de Paquete

packages/*.json son paquetes de tarea autocontenidos en JSON puro. Cualquier agente, cualquier lenguaje, sin necesidad de ningún skill, puede analizar el JSON y ejecutarlo.

Ver detalles en spec/package-spec.md.

Crear Paquete API

Método 1: Exploración Automática (cuando hay recipe)

node src/dispatch.mjs "Dar de baja producto" --operator-first --cdp-url http://127.0.0.1:9222

dispatch automáticamente: UI ejecuta recipe → captura simultánea → analyze descubre pasos → generalize generaliza campos → guarda packages/xxx.json. Sin intervención manual.

Método 2: Captura Manual → Análisis → Generalización

  1. Usa operator para operar la tarea objetivo, sin escribir scripts de control del navegador manualmente: session observe-light -> session act -> pageChange -> session act ...
  2. Guarda como captures/session-xxx.json
  3. Analiza y genera paquete automáticamente:
    node src/analyze.mjs captures/session-xxx.json
    
  4. Revisa packages/auto-xxx.json, ajusta manualmente:
    • Si la clasificación de campos es correcta (especialmente los campos unknown necesitan confirmación humana)
    • Si la ruta verify.extract es correcta
    • Si known_issues está completo
  5. Verificar con un segundo producto → después de pasar, cambiar confidence a verified

Método 3: Escritura Puramente Manual

Solo usar cuando ya se comprende y verifica la semántica de la API, escribir JSON directamente. Pasos:

  1. En el panel Network de DevTools del navegador, observar la solicitud API objetivo
  2. Escribir el array de pasos según el formato de spec/package-spec.md
  3. Cada paso debe incluir verify (status + body + extract)
  4. Los campos que no sean user_input / product_specific deben parametrizarse como $input.xxx
  5. Identificar dependencias entre pasos con $steps.id.yyy
  6. Agregar fields_analysis etiquetando el nivel de riesgo de cada campo
  7. Agregar instructions autodescriptivo
  8. Verificar con node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...

Normas de Creación de Paquetes (Obligatorias)

ReglaDescripción
instructions obligatorioAutodescripción del paquete, cualquier agente puede ejecutar sin documentación externa
Cada paso debe tener verifystatus + body obligatorios, extract obligatorio si hay dependencias
body completoNo simplificar manualmente, mantener el payload completo
Cada campo debe tener riskEn fields_analysis, cada campo etiquetado con nivel de riesgo
known_issues obligatorioAl menos declarar limitaciones conocidas
execution_hints obligatorioIndicar modo de llamada API, autenticación, anti-scraping
Parametrizar campos no específicos de tiendaLos campos store_specific deben ser $input.xxx
Honestidad en la confianzaNo verificado: proposed, después de verificar: verified

Clasificación Automática de Campos

analyze/generalize etiqueta automáticamente el riesgo de cada campo:

  • safe — Booleanos, constantes de valor pequeño → universal entre tiendas
  • store_specific — ID de plantilla, configuración de tienda → diferente entre tiendas
  • product_specific — ID de producto, SKU, categoría → universal entre tiendas
  • user_input — Nombres, precios → entrada del usuario
  • unknown — No se puede determinar → requiere revisión humana

No es necesaria verificación multi-tienda; con una sola captura se completa la clasificación.

Skills relacionados