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:
- 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. - 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. - Solo los paquetes con
confidence: verifiedse usan como ruta rápida de API por defecto. - Si la ruta rápida de API falla, se vuelve al flujo UI de operator, capturando simultáneamente la red y actualizando el paquete.
- No escribir scripts de Playwright, DOM o JavaScript dentro de la página para controlar el navegador por defecto.
browser.script --mode rawsolo 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)
| Comando | Propósito |
|---|---|
session start/stop/status | Sesión persistente del navegador |
session observe-light | Observar la página |
session act | Ejecutar acción UI |
browser.script --mode read/act | Fallback nativo de página para diagnóstico o aprobado por modelo |
browser.network-record | Capturar red y guardar adaptador |
run-recipe | Ejecutar 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ódulo | Propósito |
|---|---|
src/dispatch.mjs | Punto de entrada de despacho: buscar paquete → API / explorar |
src/exec.mjs | Ejecución de ruta rápida de API |
src/analyze.mjs | Captura de red → descubrimiento de pasos + dependencias de parámetros |
src/generalize.mjs | Clasificación de riesgo de campos + generación de paquete |
packages/*.json | Paquete 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
- Usa operator para operar la tarea objetivo, sin escribir scripts de control del navegador manualmente:
session observe-light -> session act -> pageChange -> session act ... - Guarda como
captures/session-xxx.json - Analiza y genera paquete automáticamente:
node src/analyze.mjs captures/session-xxx.json - Revisa
packages/auto-xxx.json, ajusta manualmente:- Si la clasificación de campos es correcta (especialmente los campos
unknownnecesitan confirmación humana) - Si la ruta
verify.extractes correcta - Si
known_issuesestá completo
- Si la clasificación de campos es correcta (especialmente los campos
- Verificar con un segundo producto → después de pasar, cambiar
confidenceaverified
Método 3: Escritura Puramente Manual
Solo usar cuando ya se comprende y verifica la semántica de la API, escribir JSON directamente. Pasos:
- En el panel Network de DevTools del navegador, observar la solicitud API objetivo
- Escribir el array de pasos según el formato de
spec/package-spec.md - Cada paso debe incluir
verify(status + body + extract) - Los campos que no sean
user_input/product_specificdeben parametrizarse como$input.xxx - Identificar dependencias entre pasos con
$steps.id.yyy - Agregar
fields_analysisetiquetando el nivel de riesgo de cada campo - Agregar
instructionsautodescriptivo - Verificar con
node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...
Normas de Creación de Paquetes (Obligatorias)
| Regla | Descripción |
|---|---|
instructions obligatorio | Autodescripción del paquete, cualquier agente puede ejecutar sin documentación externa |
Cada paso debe tener verify | status + body obligatorios, extract obligatorio si hay dependencias |
body completo | No simplificar manualmente, mantener el payload completo |
Cada campo debe tener risk | En fields_analysis, cada campo etiquetado con nivel de riesgo |
known_issues obligatorio | Al menos declarar limitaciones conocidas |
execution_hints obligatorio | Indicar modo de llamada API, autenticación, anti-scraping |
| Parametrizar campos no específicos de tienda | Los campos store_specific deben ser $input.xxx |
| Honestidad en la confianza | No 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 tiendasstore_specific— ID de plantilla, configuración de tienda → diferente entre tiendasproduct_specific— ID de producto, SKU, categoría → universal entre tiendasuser_input— Nombres, precios → entrada del usuariounknown— No se puede determinar → requiere revisión humana
No es necesaria verificación multi-tienda; con una sola captura se completa la clasificación.