O que PDD Merchant Kit faz?
Baseado na capacidade de automação de UI do pdd-merchant-operator, este kit adiciona captura de API, análise, generalização, empacotamento e execução de caminho rápido. O kit é uma camada de aprimoramento do operator, não uma camada de substituição.
Prioridade Máxima: Operator First
A estratégia padrão é operator-first:
- Para tarefas não verificadas ou desconhecidas, primeiro explore a página usando o operator:
session observe-light -> model decides -> session act -> read pageChange -> next decision. - Após o sucesso do caminho de UI e a validação da tarefa, analise a captura de rede desta sessão e solidifique-a como
packages/{platform}/*.json. - Apenas pacotes com
confidence: verifiedsão usados como caminho rápido de API padrão. - Se o caminho rápido de API falhar, retorne ao fluxo de UI do operator, capture pacotes simultaneamente e atualize o pacote.
- Não escreva scripts Playwright, DOM ou JavaScript inline por padrão para controlar o navegador. Use
browser.script --mode rawapenas para diagnóstico explicitamente autorizado ou validação de API.
Após compactar o contexto, a linha principal deve ser preservada: operator controla o navegador, API apenas armazena em cache experiências bem-sucedidas. Para o protocolo curto, veja references/operator-first-protocol.md.
Arquitetura de Modo Duplo
Tarefa "Excluir produto rejeitado"
│
▼
expedir
│
├── packages/ tem pacote verified?
│ │
│ SIM ──→ executar (page.evaluate fetch, ~2s)
│ │ │
│ │ ❌ Falha na API? ──→ Fallback para UI do operator + atualização de pacote
│ │
│ NÃO ──→ Execução via UI autônoma/recipe do operator
│ │
│ ├── Simultaneamente: captura de rede via CDP
│ │
│ └── Analisar → Generalizar → Gerar packages/{tarefa}.json
│ └── Próxima vez: caminho rápido de API
│
└── Concluído
Capacidades Existentes (do pdd-merchant-operator)
| Comando | Uso |
|---|---|
session start/stop/status | Sessão de navegador persistente |
session observe-light | Observar página |
session act | Executar ação de UI |
browser.script --mode read/act | Fallback de página nativa para diagnóstico ou aprovado pelo modelo |
browser.network-record | Capturar rede e salvar adaptador |
run-recipe | Executar arquivo de recipe |
product.* | Conjunto de operações rápidas |
browser.script --mode raw não é capacidade padrão; só pode ser usado com autorização explícita do usuário ou com o argumento --allow-raw-script.
Capacidades Novas
| Módulo | Uso |
|---|---|
src/dispatch.mjs | Ponto de entrada de expedição: Verificar pacote → API/Exploração |
src/exec.mjs | Execução de caminho rápido de API |
src/analyze.mjs | Captura de rede → Descoberta de etapas + dependências de parâmetros |
src/generalize.mjs | Classificação de risco de campo + Geração de pacote |
packages/*.json | Pacotes de tarefa JSON autocontidos |
Comandos
Expedição
node src/dispatch.mjs "Excluir produto rejeitado" --cdp-url http://127.0.0.1:9222
Por padrão, apenas pacotes verified usam API. Para forçar aprendizado/atualização via UI:
node src/dispatch.mjs "Excluir produto rejeitado" --operator-first --cdp-url http://127.0.0.1:9222
Caminho Rápido de API
node src/exec.mjs packages/delete-rejected-product.json \
--params '{"goods_id":"970107750738"}' --cdp-url http://127.0.0.1:9222
Analisar Captura
node src/analyze.mjs captures/session-xxx.json
Formato do Pacote
packages/*.json são pacotes de tarefa JSON autocontidos. Qualquer agente, qualquer linguagem, sem necessidade de skill, pode executar analisando o JSON.
Veja spec/package-spec.md para detalhes.
Criando Pacotes de API
Método 1: Exploração Automática (com recipe)
node src/dispatch.mjs "Remover produto do ar" --operator-first --cdp-url http://127.0.0.1:9222
dispatch faz automaticamente: UI executa recipe → captura pacotes simultaneamente → analyze analisa etapas → generaliza campos → salva packages/xxx.json. Sem intervenção manual.
Método 2: Captura Manual → Análise → Generalização
- Use o operator para executar a tarefa alvo, não escreva scripts de controle de navegador manualmente:
session observe-light -> session act -> pageChange -> session act ... - Salve como
captures/session-xxx.json - Analise automaticamente para gerar pacote:
node src/analyze.mjs captures/session-xxx.json - Verifique
packages/auto-xxx.json, ajuste manualmente:- Classificação de campos correta (especialmente campos
unknownque precisam de confirmação manual) - Caminho
verify.extractcorreto known_issuescompleto
- Classificação de campos correta (especialmente campos
- Valide com um segundo produto → Após sucesso, altere
confidenceparaverified
Método 3: Escrita Manual Pura
Apenas quando a semântica da API já é compreendida e validada, escreva JSON diretamente. Etapas:
- No painel DevTools do navegador, observe as requisições de API alvo
- Escreva o array de etapas conforme o formato em
spec/package-spec.md - Cada etapa deve conter
verify(status + body + extract) - Campos que não são
user_input/product_specificdevem ser parametrizados como$input.xxx - Identifique dependências entre etapas via
$steps.id.yyy - Adicione
fields_analysismarcando o nível de risco de cada campo - Adicione
instructionsautodescritivas - Valide com
node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...
Especificações de Criação de Pacotes (Devem Ser Seguidas)
| Regra | Descrição |
|---|---|
instructions obrigatório | Autodescrição do pacote, qualquer agente pode executar sem documentação externa |
Toda etapa deve ter verify | status + body obrigatórios, extract obrigatório se houver dependências |
| body completo | Proibido simplificar manualmente, preservar payload completo |
Campos devem ter risk | Em fields_analysis, cada campo deve ter nível de risco |
known_issues obrigatório | Pelo menos declarar limitações conhecidas |
execution_hints obrigatório | Explicar modo de chamada de API, autenticação, anti-raspagem |
| Campos não específicos da loja parametrizados | Campos store_specific devem ser definidos como $input.xxx |
| Confiança honesta | Não verificado: proposed, verificado: verified |
Classificação Automática de Campos
analyze/generalize marca automaticamente o risco de cada campo:
safe— Valores booleanos, constantes numéricas pequenas → universal entre lojasstore_specific— IDs de template, configurações de loja → diferentes entre lojasproduct_specific— IDs de produto, SKU, categorias → universal entre lojasuser_input— Nomes, preços → entrada do usuáriounknown— Não determinado → requer verificação manual
Não é necessário validação com múltiplas lojas; uma única captura já permite a classificação.