📈 Neuro Ads Manager — Gestor de Tráfego Pago (v0.2.0)

imageversion imageLicense: MIT imageMeta Marketing API imageClaude Code imageNeuro Harness

Um gestor de tráfego pago para agentes de IA. Ele audita a conta, planeja campanhas, gera relatórios, prepara criativos e copy dentro das regras do segmento e confere se a conversão está chegando à Meta, seguindo as boas práticas de mercado e padrões validados em projetos reais.

• Plataforma: Meta Ads (Facebook, Instagram, WhatsApp/CTWA, Lead Ads), com CRM (GoHighLevel) no funil.
• Segmentos com compliance: advocacia (OAB), educação (ECA/LGPD), saúde, crédito, estética e as políticas da Meta.
• Seguro por padrão: só lê a conta. Mudanças viram um plano com hash e aprovação humana; tudo nasce PAUSED; nada de .env, IDs ou dados pessoais nos entregáveis.

Sumário:

• Primeiros passos: Início rápido · Instalação · Ambiente
• Uso: Claude Code · Neuro Harness · Outros agentes · Um ciclo completo
• Recursos: CLI · Perfis · Compliance · Mensuração · Mudanças na conta
• Manutenção: Atualização · Desinstalação · Problemas · Estrutura · Releases · Privacidade · Autor

Todos os comandos e opções estão em docs/COMANDOS.md.

Início rápido

1. Instale no Claude Code:

claude plugin marketplace add monrars1995/oneuros-ads-manager#v0.2.0

claude plugin install neuro-ads-manager@neuro-ads-manager --scope user

2. Exporte o token da Meta no seu terminal (token de usuário do sistema com ads_read; o plugin nunca lê .env):

export META_ACCESS_TOKEN=... META_AD_ACCOUNT_ID=act_...

3. Abra uma sessão nova e rode:

/neuro-ads-manager:perfil novo
/neuro-ads-manager:auditar acme 30d
/neuro-ads-manager:relatorio acme 7d

• perfil cria o perfil do cliente (aqui, um cliente fictício acme) a partir do modelo, com perguntas no chat. O perfil fica só na sua máquina.
• auditar tira o retrato da conta pela API, levanta os achados e devolve a auditoria priorizada. Não muda nada.
• relatorio gera o relatório do período com comparação e espaço para a leitura.

Instalação

Requisitos

Não há dependências npm.

Claude Code

Para testar a partir de um clone, sem instalar: claude --plugin-dir ~/Code/neuro-ads-manager.

Neuro Harness

Com o Neuro Harness instalado (~/.neuro-harness), a partir de um clone:

git clone https://github.com/monrars1995/oneuros-ads-manager.git ~/Code/neuro-ads-manager

node ~/Code/neuro-ads-manager/cli/cli.js harness instalar

neuro-harness restart

O harness instalar roda dsh plugin --profile neuro add link:<clone>: o gerenciador de plugins do Harness instala o pacote, acrescenta o bundle ao perfil e valida o cordis.patch.yml. Detalhes em Usando no Neuro Harness.

Outros agentes

Copie (ou ligue) a pasta skills/neuro-ads-manager para a pasta de skills do agente (~/.agents/skills, ~/.codex/skills, .claude/skills de um projeto…). O CLI roda com node <clone>/cli/cli.js.

Ambiente e tokens

• O token nunca é lido de arquivo. O CLI recusa abrir .env, .env.*, credenciais e chaves, e nunca imprime o token (erros passam por um filtro).
• O perfil pode dizer em que variável está o token (ambiente.token_env). Nomes com hífen (como CRM-TOKEN) não podem ser exportados no shell: use letras, números e _.
• Use um token de usuário do sistema do Business Manager do cliente. Para escrever na conta (fora do plugin), ads_management.

Usando no Claude Code

O plugin traz:

• a skill neuro-ads-manager;
• 6 comandos;
• 3 subagentes;
• o comando neuro-ads-manager no PATH das sessões.

Comandos

• A skill sozinha: /neuro-ads-manager:neuro-ads-manager. Ela também é ativada quando o pedido é de tráfego pago.
• Nenhum comando escreve na conta. O que precisa mudar vira plano de mudança, e o comando para para você aprovar.

Subagentes

Os três só leem.

Exemplo de sessão

você  › /neuro-ads-manager:auditar acme 30d
agente› Token ok, conta ativa, limite de gasto em 62%. Snapshot em relatorios/snapshot-2026-10-09_2026-11-07.json.
        12 achados automáticos; o auditor confirmou 10 e descartou 2 (disclaimer lido como promessa; conjunto criado há 2 dias).
        P0: 2 anúncios com "análise gratuita" (OAB); conjunto otimizando para clique numa conta de leads.
        Auditoria em relatorios/auditoria-acme-2026-11-08.md. Quer que eu monte o plano de mudança dos P0?
você  › sim, pode montar
agente› Plano em operacoes/2026-11-08-p0-acme/ (3 operações, validado, sha256 4be1…). Aprova?
você  › aprovado, pode pausar os dois anúncios e trocar a otimização
agente› Aprovação registrada com a sua mensagem. A execução fica com a ferramenta do projeto; registro cada passo no ledger.

Usando no Neuro Harness

O pacote é um plugin do DeepSeek Harness (package.json → dsh.bundle.patch → harness/cordis.patch.yml). O módulo harness/index.mjs:

• registra no serviço skills do Harness a skill neuro-ads-manager e um comando por arquivo de commands/: neuro-ads-auditar, neuro-ads-planejar, neuro-ads-relatorio, neuro-ads-criativos, neuro-ads-conversao, neuro-ads-perfil (o modelo vê só a skill; os comandos são para você chamar);
• põe o bin/ do pacote no PATH enquanto o plugin estiver ativo, então o comando neuro-ads-manager funciona nas sessões.

Depois de instalar ou remover: neuro-harness restart. Os subagentes do Claude Code ficam em agents/*.md: no Harness, peça ao agente para seguir o arquivo ou passá-lo como instrução de um subagente.

Usando em outros agentes

Peça em linguagem natural ("audite a conta do cliente Acme nos últimos 30 dias com a skill neuro-ads-manager"). O agente lê a skill e usa o CLI com node <clone>/cli/cli.js <comando>.

Um ciclo completo

perfil  →  meta conferir  →  meta snapshot  →  auditar / alertas / relatorio  →  operacao nova
        →  operacao validar  →  aprovação no chat  →  operacao aprovar  →  execução (ferramenta do projeto)
        →  operacao registrar  →  leitura D+3 / D+7  →  relatório

neuro-ads-manager meta conferir --perfil acme

neuro-ads-manager meta snapshot --perfil acme --periodo 30d --comparar

neuro-ads-manager auditar relatorios/snapshot-2026-10-09_2026-11-07.json --perfil acme --saida relatorios/auditoria-acme.md

neuro-ads-manager alertas relatorios/snapshot-2026-10-09_2026-11-07.json --perfil acme

neuro-ads-manager operacao nova pausar-anuncios-sem-resultado --perfil acme

Referência rápida do CLI

Períodos: 7d, 30d, ontem, mes, mes-passado ou AAAA-MM-DD:AAAA-MM-DD. Detalhes de cada opção em docs/COMANDOS.md.

Perfis de cliente

A skill traz um único perfil, o modelo (segmento geral, compliance meta_politicas e lgpd), ponto de partida para os seus clientes. Perfis de cliente são configuração de campanha e não vão para o repositório: ficam só na sua máquina.

Cada perfil traz segmento, metas (kpi), regras de decisão (pausar, congelar, escalar), limites, públicos, orçamento, criativos, mensuração, compliance, nomenclatura, cadência e aprovação. Nenhum guarda ID de conta, pixel, página, token ou dado pessoal: só o nome das variáveis de ambiente. O validador recusa o resto.

Os perfis do usuário ficam em ~/.neuro-ads-manager/perfis/<id>.json (ou $NEURO_ADS_HOME/perfis), valem por cima do modelo e sobrevivem às atualizações.

neuro-ads-manager perfil novo --json acme.json --base modelo

Compliance por segmento

neuro-ads-manager compliance copy.txt --perfil acme

neuro-ads-manager compliance regras eca_lgpd

O lint é a primeira passada; o subagente revisor-compliance faz a leitura de contexto. Nenhum dos dois substitui o jurídico do cliente.

Mensuração e conversão

• Pixel + CAPI com o mesmo event_id; action_source real (system_generated no CRM, physical_store presencial, business_messaging com ctwa_clid no WhatsApp).
• Hash SHA-256 de e-mail, telefone (DDI 55), nome, cidade, UF, CEP, país e external_id; lead_id, ctwa_clid, fbc, fbp sem hash.
• event_id estável e lista de enviados (--excluir-ids) para não reenviar.
• Janela da CAPI: até 7 dias; só physical_store até 62. O resto fica retido.
• Teste antes da carga: conversao payload --teste <TEST_EVENT_CODE>.

neuro-ads-manager conversao validar conversoes.csv --evento Purchase --origem system_generated --crm GoHighLevel

neuro-ads-manager conversao payload conversoes.csv --saida payload.json --teste TEST12345

O CSV aceita colunas em português ou inglês (email, telefone, nome, cidade, uf, cep, id_cliente, lead_id, ctwa_clid, evento, data, valor…); o modelo está em skills/neuro-ads-manager/templates/conversao-offline.csv. O dado cru nunca vai para a saída.

Mudanças na conta

O plugin não escreve na conta nesta versão. Ele monta, valida e registra; a escrita fica com a ferramenta do projeto do cliente ou com o Gerenciador, depois da aprovação.

operacoes/AAAA-MM-DD-<escopo>/
  README.md        o que muda, como executar, verificar e reverter
  plano.json       operações com antes, depois e rollback
  aprovacao.json   aprovador, mensagem literal e SHA-256 do plano
  ledger.jsonl     andamento de cada operação

• O operacao validar bloqueia DELETE, objeto novo ACTIVE, aumento de orçamento acima do limite (padrão +20%), redução depois de aumento e operação sem rollback.
• A aprovação é do hash: se o plano mudar, ela deixa de valer.
• Escrita incerta nunca é repetida: lê-se o estado e registra-se outcome_unknown ou verified.

Atualização

Claude Code:

claude plugin marketplace add monrars1995/oneuros-ads-manager#vX.Y.Z

claude plugin update neuro-ads-manager@neuro-ads-manager

Neuro Harness (instalado com link ao clone): git -C ~/Code/neuro-ads-manager pull e neuro-harness restart. Com --copiar, rode harness instalar --copiar de novo.

Seus perfis em ~/.neuro-ads-manager/ não mudam. Depois de atualizar, abra uma sessão nova.

Desinstalação

Solução de problemas

Estrutura do repositório

.claude-plugin/        plugin.json, marketplace.json e ícone do Claude Code
agents/                subagentes: auditor, revisor-compliance, analista-conversao
bin/neuro-ads-manager  comando do PATH (Claude Code e Neuro Harness)
cli/                   CLI sem dependências (Node 20+)
  cli.js               entrada e subcomandos
  meta.js              cliente da Graph API (só GET) e snapshot
  auditoria.js         achados por área
  alertas.js           regras de decisão do perfil
  relatorio.js         relatório em Markdown
  metricas.js          métricas, resultado por perfil, CSV do Gerenciador
  conversao.js         normalização, SHA-256, retenção e payload da CAPI
  compliance.js        lint de copy por conjunto de regras
  nomes.js             nomenclatura
  operacao.js          plano de mudança, aprovação e ledger
  perfis.js            perfis da skill e do usuário
  harness.js           instalação no Neuro Harness
  version.js           versão única em todos os manifestos
commands/              comandos do plugin (auditar, planejar, relatorio, criativos, conversao, perfil)
docs/                  COMANDOS.md
harness/               plugin do DeepSeek Harness (index.mjs + cordis.patch.yml)
skills/neuro-ads-manager/
  SKILL.md             a skill
  references/          estrutura e públicos, criativos e copy, orçamento e testes, mensuração,
                       compliance, relatórios, Marketing API, mudanças na conta
  presets/             perfis.json (só o modelo), compliance.json, nomenclatura.json
  templates/           auditoria, plano de campanha, relatório, briefing de criativo, CSV de conversão
tests/                 testes (node --test) com dados sintéticos
plugin.json            manifesto Agent Plugins
package.json           pacote npm, bin e manifesto `dsh` do Harness

Desenvolvimento e releases

Para testar a partir de um clone:

• npm test roda os testes (só dados sintéticos; nenhum chama a API).
• node cli/cli.js <comando> roda o CLI.
• claude --plugin-dir . abre uma sessão com o plugin do clone.
• claude plugin validate . confere os manifestos.

O projeto segue o Versionamento Semântico: MAJOR quebra compatibilidade (comandos, formato de perfil ou de plano), MINOR traz recurso novo, PATCH corrige. O histórico está no CHANGELOG.md.

Como publicar uma versão:

1. Grave a versão em todos os marcadores e confira:

   npm run version:set X.Y.Z
   

   npm run version:check
   

2. Descreva as mudanças no topo do CHANGELOG.md, abra o PR e faça o merge na main.
3. Crie a tag e a release:

   git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
   

🔒 Privacidade

• O plugin não coleta nem envia dados. Snapshots, relatórios, planos e perfis ficam no seu computador: na pasta do projeto e em ~/.neuro-ads-manager/.
• Rede: só a Graph API da Meta, com o token que você exporta, e só para leitura (GET).
• Segredos: o CLI não abre .env, credenciais nem chaves, e oculta o token em mensagens de erro. URLs de paginação com token não são guardadas.
• Dados pessoais: arquivos de conversão são normalizados e viram SHA-256; o dado cru não vai para a saída. Snapshots e arquivos com hash são gravados com permissão 600. Relatórios e perfis não levam IDs nem contatos.

Autor e licença

Desenvolvido por Ramon Ribeiro para a GoldNeuron.

• GitHub: @monrars1995
• Instagram: @monrars e @goldneuron.io

Licença MIT.