Communitygithub.com

PDD Merchant Kit

Skill para automação de UI do PDD Merchant e solidificação de pacotes de API.

O que é PDD Merchant Kit?

O PDD Merchant Kit é uma skill de agente de IA projetada para automatizar tarefas do painel de comerciantes do Pinduoduo (PDD). Ele combina a condução autônoma de UI do pdd-merchant-operator com a capacidade de capturar, analisar, generalizar e executar chamadas de API como caminhos rápidos. A skill prioriza o uso do operador para explorar e executar tarefas desconhecidas, e somente após a validação bem-sucedida via UI, as requisições de rede são analisadas e solidificadas em pacotes JSON autocontidos. Esses pacotes, com nível de confiança 'verified', são então usados como padrão para execução rápida de API, reduzindo o tempo de tarefas rotineiras para cerca de 2 segundos. Se uma chamada de API falhar, o sistema automaticamente volta para o fluxo da UI, captura novos pacotes e atualiza o pacote existente. A skill suporta múltiplos modos de operação, incluindo exploração automática, criação manual de pacotes e um modo híbrido, garantindo robustez e eficiência para desenvolvedores que trabalham com automação de comércio eletrônico.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. 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.
  2. 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.
  3. Apenas pacotes com confidence: verified são usados como caminho rápido de API padrão.
  4. Se o caminho rápido de API falhar, retorne ao fluxo de UI do operator, capture pacotes simultaneamente e atualize o pacote.
  5. Não escreva scripts Playwright, DOM ou JavaScript inline por padrão para controlar o navegador. Use browser.script --mode raw apenas 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)

ComandoUso
session start/stop/statusSessão de navegador persistente
session observe-lightObservar página
session actExecutar ação de UI
browser.script --mode read/actFallback de página nativa para diagnóstico ou aprovado pelo modelo
browser.network-recordCapturar rede e salvar adaptador
run-recipeExecutar 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óduloUso
src/dispatch.mjsPonto de entrada de expedição: Verificar pacote → API/Exploração
src/exec.mjsExecução de caminho rápido de API
src/analyze.mjsCaptura de rede → Descoberta de etapas + dependências de parâmetros
src/generalize.mjsClassificação de risco de campo + Geração de pacote
packages/*.jsonPacotes 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

  1. 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 ...
  2. Salve como captures/session-xxx.json
  3. Analise automaticamente para gerar pacote:
    node src/analyze.mjs captures/session-xxx.json
    
  4. Verifique packages/auto-xxx.json, ajuste manualmente:
    • Classificação de campos correta (especialmente campos unknown que precisam de confirmação manual)
    • Caminho verify.extract correto
    • known_issues completo
  5. Valide com um segundo produto → Após sucesso, altere confidence para verified

Método 3: Escrita Manual Pura

Apenas quando a semântica da API já é compreendida e validada, escreva JSON diretamente. Etapas:

  1. No painel DevTools do navegador, observe as requisições de API alvo
  2. Escreva o array de etapas conforme o formato em spec/package-spec.md
  3. Cada etapa deve conter verify (status + body + extract)
  4. Campos que não são user_input / product_specific devem ser parametrizados como $input.xxx
  5. Identifique dependências entre etapas via $steps.id.yyy
  6. Adicione fields_analysis marcando o nível de risco de cada campo
  7. Adicione instructions autodescritivas
  8. Valide com node src/exec.mjs packages/xxx.json --params '{}' --cdp-url ...

Especificações de Criação de Pacotes (Devem Ser Seguidas)

RegraDescrição
instructions obrigatórioAutodescrição do pacote, qualquer agente pode executar sem documentação externa
Toda etapa deve ter verifystatus + body obrigatórios, extract obrigatório se houver dependências
body completoProibido simplificar manualmente, preservar payload completo
Campos devem ter riskEm fields_analysis, cada campo deve ter nível de risco
known_issues obrigatórioPelo menos declarar limitações conhecidas
execution_hints obrigatórioExplicar modo de chamada de API, autenticação, anti-raspagem
Campos não específicos da loja parametrizadosCampos store_specific devem ser definidos como $input.xxx
Confiança honestaNã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 lojas
  • store_specific — IDs de template, configurações de loja → diferentes entre lojas
  • product_specific — IDs de produto, SKU, categorias → universal entre lojas
  • user_input — Nomes, preços → entrada do usuário
  • unknown — 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.

Habilidades Relacionadas