iron-edge 2.11.0 → 2.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -2
- package/bin/iron-edge.js +4 -3
- package/installer/office.js +69 -5
- package/installer/update.js +8 -0
- package/package.json +2 -2
- package/skills/anuncios/SKILL.md +114 -0
- package/skills/rastreamento-pixel/SKILL.md +2 -0
- package/skills/trilha/steps/nome.md +2 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Iron Edge — Ecossistema de Agentes para Claude Code
|
|
2
2
|
|
|
3
|
-
**44 agentes de topo, 18 squads,
|
|
3
|
+
**44 agentes de topo, 18 squads, 20 skills e memória entre sessões.**
|
|
4
4
|
|
|
5
5
|
Uma equipe completa de IA para marketing, vendas, conteúdo, Shopify, vídeo e crescimento — tudo dentro do Claude Code.
|
|
6
6
|
|
|
@@ -31,7 +31,7 @@ São arquivos `.md` comuns — abrem no Obsidian, no VS Code ou em qualquer edit
|
|
|
31
31
|
Existem **duas coisas diferentes** aqui, e elas se chamam de jeitos diferentes. Confundir as duas
|
|
32
32
|
é o erro mais comum de quem acabou de instalar.
|
|
33
33
|
|
|
34
|
-
**Skills — essas viram comando de barra.** São
|
|
34
|
+
**Skills — essas viram comando de barra.** São 20, e o Claude Code as reconhece por `/nome`:
|
|
35
35
|
|
|
36
36
|
```
|
|
37
37
|
/gate → auditoria de qualidade antes de entregar
|
|
@@ -42,6 +42,7 @@ Existem **duas coisas diferentes** aqui, e elas se chamam de jeitos diferentes.
|
|
|
42
42
|
/loja → a ficha da sua loja no cofre (lê a Shopify)
|
|
43
43
|
/trilha → a próxima etapa da sua loja, medida (no Iron Office: botão "Pedir ao Iron")
|
|
44
44
|
/rastreamento-pixel → a Meta recebendo as vendas da loja, sem contar em dobro
|
|
45
|
+
/anuncios → o retrato dos seus anúncios da Meta e o que corrigir hoje (no Iron Office: aba Anúncios)
|
|
45
46
|
```
|
|
46
47
|
(As outras: `navegador` (regras do Iron no seu Chrome), `anotar`, `faxina`, `conectar-mcp`, `roteiro-video`, `lp-cinematico`, `clone-site`,
|
|
47
48
|
`clone-inventory`, `clone-distill`, `clone-organize`, `clone-transplant`.)
|
|
@@ -247,6 +248,10 @@ O que esperar:
|
|
|
247
248
|
4. Abra a página **Iron** do dashboard. Em até 1 minuto aparece "Iron online". Escreva ali e o Iron responde ali.
|
|
248
249
|
5. **Ficha da loja** (skill `loja`, desde a 2.8.0): no site, "Começar com a loja X" (ou diga "monta a ficha"). O Iron lê a Shopify da loja, aponta o que está errado, pergunta só o que falta e grava `Projetos/<loja>/PROJETO.md` e `brand.json` no seu cofre; pro site vai só um resumo de até 600 caracteres (sem sócio, fornecedor, conta de anúncio nem pedido). Daí em diante todo pedido daquela loja chega com a ficha. Desde a 2.9.0, no site as perguntas vêm uma por vez, com botões.
|
|
249
250
|
**Trilha da loja** (skill `trilha`, desde a 2.9.0): no chat, o botão da loja mostra "4/13 etapas" e o atalho **Trilha** (o primeiro, acima da caixa de mensagem) abre a lista (marca, idioma, imagens, velocidade, página de obrigado, pixel, WhatsApp, Instagram, conta de anúncio, compra teste…). "Pedir ao Iron" manda a etapa; o Iron mede na loja e na Meta, faz o que dá e grava a prova que mediu. Etapa que só você pode fazer (login, cartão, configuração no admin) vira um passo no AGORA VOCÊ. Desde a 2.10.0 o Iron conduz todas as etapas de quem já tem loja (skills `rastreamento-pixel` e `navegador`). Desde a 2.11.0 conduz também o caminho de quem ainda não tem loja: produto e nicho (com 3 concorrentes que anunciam agora) e nome com domínio e @ livres (medidos); a ficha do projeto nasce no cofre.
|
|
251
|
+
|
|
252
|
+
**Atualização sozinha** (desde a 2.13.0): antes de abrir, o `ironoffice` compara a versão instalada (`~/.iron/install-manifest.json`) com a do pacote e, se estiver atrás, roda o mesmo `npx iron-edge update` (sem mexer no atalho do shell): troca só o arquivo do pacote que você não editou, avisa antes (`Atualizando o Iron 2.12.0 -> 2.13.0 (alguns segundos, nao feche)...`) e imprime 1 linha no fim (`Iron atualizado 2.12.0 -> 2.13.0: N arquivo(s) trocado(s), M ficaram como estavam (voce mexeu neles)`). Sem internet ou com erro, abre com a versão que está e avisa. `npx iron-edge office --sem-update` pula.
|
|
253
|
+
|
|
254
|
+
**Anúncios** (skill `anuncios`, desde a 2.12.0): na aba Anúncios do site, o botão **Atualizar agora** (ou no chat "como estão meus anúncios") faz o Iron medir os últimos 7 dias da sua conta da Meta e mostrar gasto, resultados, custo por resultado e o que corrigir hoje (desde a 2.13.0 sem sair da aba; campanha no ar com todos os grupos pausados aparece como "parada"): peça nova que não aparece há mais de 48 h, data vencida ainda no ar, dinheiro indo pra peça vencida e peça recusada. O Iron só lê; pausar uma peça ele pergunta antes. A Meta tem que estar ligada no seu Iron (`/mcp` → `meta-ads` → Authenticate).
|
|
250
255
|
6. **Deixe essa aba do terminal aberta.** É ela que faz o Iron responder no site.
|
|
251
256
|
7. **Pra fechar:** Ctrl+C duas vezes ou `/exit`, e o escritório anoitece em 1 a 2 segundos. No **Warp**, fechar a aba pelo X demora cerca de 1 minuto: o Warp guarda a aba fechada pra poder reabrir, e nesse tempo o canal ainda está vivo. Feche com Ctrl+C antes do X, ou desligue a reabertura de abas fechadas nas configurações do Warp.
|
|
252
257
|
|
package/bin/iron-edge.js
CHANGED
|
@@ -14,8 +14,9 @@
|
|
|
14
14
|
* arquivos cujo hash bate com o manifesto — os que
|
|
15
15
|
* ninguem alterou — e preserva o resto
|
|
16
16
|
*
|
|
17
|
-
* office [--safe] [--sem-feed|--com-feed] liga o Iron Office: instala o plugin de
|
|
18
|
-
*
|
|
17
|
+
* office [--safe] [--sem-feed|--com-feed] [--sem-update] liga o Iron Office: instala o plugin de
|
|
18
|
+
* canal, atualiza as skills e agentes do Iron (o mesmo `update`;
|
|
19
|
+
* --sem-update pula) e abre o Claude Code conversando com o chat
|
|
19
20
|
*
|
|
20
21
|
* doctor [--json] mede a maquina (Node, git, Claude Code, Iron Edge, chave,
|
|
21
22
|
* plugin, cofre, atalho) e, com a chave aceita, manda o resultado
|
|
@@ -174,6 +175,6 @@ if (cmd === 'install') {
|
|
|
174
175
|
process.exit(r.status ?? 1);
|
|
175
176
|
|
|
176
177
|
} else {
|
|
177
|
-
console.log('uso: iron-edge <install|update|verify|office|doctor|uninstall> [--dry-run] [--source <dir>] [--cofre|--sem-cofre] [--safe] [--sem-feed|--com-feed] [--json]');
|
|
178
|
+
console.log('uso: iron-edge <install|update|verify|office|doctor|uninstall> [--dry-run] [--source <dir>] [--cofre|--sem-cofre] [--safe] [--sem-feed|--com-feed] [--sem-update] [--json]');
|
|
178
179
|
process.exit(cmd && cmd !== '--help' && cmd !== '-h' ? 1 : 0);
|
|
179
180
|
}
|
package/installer/office.js
CHANGED
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
* faz o Iron responder no site.
|
|
9
9
|
*
|
|
10
10
|
* Flags: --safe tira o `--permission-mode bypassPermissions` (o Claude pede licenca a cada
|
|
11
|
-
* ferramenta). --sem-
|
|
11
|
+
* ferramenta). --sem-update nao atualiza as skills e agentes do Iron antes de abrir (onda 28 rev1).
|
|
12
|
+
* --sem-feed / --com-feed gravam `office_feed: off|on` no ~/.iron/config.yaml (onda 21).
|
|
12
13
|
* Qualquer outro argumento vai direto pro `claude`.
|
|
13
14
|
*
|
|
14
15
|
* Consentimento (onda 21): na primeira abertura (ou quando o texto muda de versao) mostra o que o canal
|
|
@@ -39,7 +40,7 @@ const { perguntaSN } = require('./pergunta');
|
|
|
39
40
|
const { setFeed } = require('./feed');
|
|
40
41
|
|
|
41
42
|
// Muda a versao quando o texto do consentimento mudar de sentido: todo mundo ve de novo.
|
|
42
|
-
const CONSENT_VERSION = '2026-10-
|
|
43
|
+
const CONSENT_VERSION = '2026-10-30'; // rev1 da 28: as skills tambem se atualizam sozinhas
|
|
43
44
|
const CONSENT_TEXT = [
|
|
44
45
|
'Antes de ligar o canal do Iron Office:',
|
|
45
46
|
' - o que voce escrever no site vira pedido nesta sessao do Claude Code,',
|
|
@@ -48,7 +49,8 @@ const CONSENT_TEXT = [
|
|
|
48
49
|
' dos arquivos criados ou editados, o comeco de cada comando, buscas,',
|
|
49
50
|
' a pasta e os nomes dos conectores; o chat e as entregas ficam no site;',
|
|
50
51
|
' - apagamos padroes conhecidos de senha, chave e token (nem sempre todos);',
|
|
51
|
-
' - a cada abertura o plugin se atualiza
|
|
52
|
+
' - a cada abertura o plugin se atualiza, o conector da Meta e instalado',
|
|
53
|
+
' e as skills do Iron tambem (o que voce editou fica; pular: --sem-update);',
|
|
52
54
|
' - politica: ' + OFFICE_URL + '/termos',
|
|
53
55
|
];
|
|
54
56
|
|
|
@@ -102,7 +104,67 @@ function aplicarFlagsFeed(argv, home) {
|
|
|
102
104
|
return '';
|
|
103
105
|
}
|
|
104
106
|
|
|
105
|
-
const NOSSAS_FLAGS = new Set(['--safe', '--sem-feed', '--com-feed']);
|
|
107
|
+
const NOSSAS_FLAGS = new Set(['--safe', '--sem-feed', '--com-feed', '--sem-update']);
|
|
108
|
+
|
|
109
|
+
// Onda 28 rev1: o pacote instalado em ~/.claude (skills, agentes, steps) so' mudava com `npx iron-edge update`, e
|
|
110
|
+
// nenhum aviso dizia que havia versao nova. Agora o `ironoffice` compara a versao do manifesto com a deste pacote e,
|
|
111
|
+
// se estiver atras, roda o MESMO update.js em processo filho (troca so' o que bate com o hash do manifesto; o que o
|
|
112
|
+
// aluno editou fica). Melhor-esforco, igual ao plugin: falhou, segue com a versao instalada. --sem-update pula.
|
|
113
|
+
const UPDATE_TIMEOUT_MS = 180000;
|
|
114
|
+
|
|
115
|
+
function versaoNum(v) {
|
|
116
|
+
const m = String(v || '').replace(/^iron-edge-/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
|
|
117
|
+
return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
// -1 a < b · 0 iguais · 1 a > b (versao ilegivel conta como a mais antiga)
|
|
121
|
+
function compararVersao(a, b) {
|
|
122
|
+
const x = versaoNum(a), y = versaoNum(b);
|
|
123
|
+
if (!x || !y) return !x && !y ? 0 : (!x ? -1 : 1);
|
|
124
|
+
for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
|
|
125
|
+
return 0;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function versaoDoPacote() {
|
|
129
|
+
try { return require(path.join(__dirname, '..', 'package.json')).version || ''; } catch (_) { return ''; }
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// Devolve a linha que o office imprime (sempre uma; nunca lanca). o.spawn e o.updateScript existem pro teste.
|
|
133
|
+
function atualizarPacote(home, o) {
|
|
134
|
+
const opts = o || {};
|
|
135
|
+
const h = home || os.homedir();
|
|
136
|
+
const pacote = opts.pkgVersion || versaoDoPacote();
|
|
137
|
+
const man = path.join(h, '.iron', 'install-manifest.json');
|
|
138
|
+
let instalada;
|
|
139
|
+
try { instalada = JSON.parse(fs.readFileSync(man, 'utf8')).version || ''; }
|
|
140
|
+
catch (e) {
|
|
141
|
+
if (e && e.code === 'ENOENT') return ' [aviso] nao achei o registro da instalacao do Iron: as skills nao se atualizam sozinhas (rode npx iron-edge update)';
|
|
142
|
+
return ' [aviso] o registro da instalacao do Iron esta ilegivel: seguindo com o que esta instalado (rode npx iron-edge update)';
|
|
143
|
+
}
|
|
144
|
+
const antes = String(instalada).replace(/^iron-edge-/, '') || '?';
|
|
145
|
+
if (!pacote || compararVersao(instalada, pacote) >= 0) return ' [ok] Iron ja esta na ' + antes;
|
|
146
|
+
// a saida do filho e' capturada: sem esta linha o aluno ficava ate 3 min olhando o terminal parado (gate r1)
|
|
147
|
+
if (opts.antes) opts.antes(' Atualizando o Iron ' + antes + ' -> ' + pacote + ' (alguns segundos, nao feche)...');
|
|
148
|
+
const spawn = opts.spawn || spawnSync;
|
|
149
|
+
// --sem-atalho: o update automatico nunca cria o alias no ~/.zshrc (o install pergunta antes; aqui nao ha
|
|
150
|
+
// pergunta). gate r1 do aluno-zero: sem ela, quem recusou o atalho ganhava o alias sem saber
|
|
151
|
+
const r = spawn(process.execPath, [opts.updateScript || path.join(__dirname, 'update.js'), '--sem-atalho'], {
|
|
152
|
+
encoding: 'utf8',
|
|
153
|
+
timeout: UPDATE_TIMEOUT_MS,
|
|
154
|
+
maxBuffer: 32 * 1024 * 1024, // a saida estourando 1 MiB matava o filho no meio da troca (gate r1, ENOBUFS)
|
|
155
|
+
env: { ...process.env, HOME: h, USERPROFILE: h, IRON_EDGE_VERSION: pacote, IRON_EDGE_RESUMO: '1' },
|
|
156
|
+
});
|
|
157
|
+
const out = (r && (r.stdout || '') + (r.stderr || '')) || '';
|
|
158
|
+
const m = out.match(/IRON_UPDATE_RESUMO (\{.*\})/);
|
|
159
|
+
if (!r || r.error || r.status !== 0 || !m) {
|
|
160
|
+
const motivo = r && r.error ? (r.error.code || r.error.message) : (out.trim().split('\n').pop() || 'sem detalhe');
|
|
161
|
+
return ' [aviso] nao deu pra atualizar o Iron agora (' + String(motivo).slice(0, 120) + '): seguindo com a ' + antes + '. Pra tentar de novo: npx iron-edge update';
|
|
162
|
+
}
|
|
163
|
+
let res = { trocados: 0, preservados: 0 };
|
|
164
|
+
try { res = JSON.parse(m[1]); } catch (_) { /* conta zero */ }
|
|
165
|
+
return ' [ok] Iron atualizado ' + antes + ' -> ' + pacote + ': ' + res.trocados + ' arquivo(s) trocado(s)'
|
|
166
|
+
+ (res.preservados ? ', ' + res.preservados + ' ficaram como estavam (voce mexeu neles)' : '');
|
|
167
|
+
}
|
|
106
168
|
|
|
107
169
|
function keyPath(home) {
|
|
108
170
|
return path.join(home || os.homedir(), '.claude', 'iron-office-api-key');
|
|
@@ -318,6 +380,8 @@ async function main(argv) {
|
|
|
318
380
|
step(claude, 'atualizacao do plugin', ['plugin', 'update', PLUGIN], [/already|up.to.date|latest/i]);
|
|
319
381
|
metaAds(claude);
|
|
320
382
|
avisoPluginNovo(claude);
|
|
383
|
+
if (argv.includes('--sem-update')) console.log(' [ok] atualizacao do Iron pulada (--sem-update)');
|
|
384
|
+
else console.log(atualizarPacote(undefined, { antes: (l) => console.log(l) }));
|
|
321
385
|
|
|
322
386
|
const safe = argv.includes('--safe');
|
|
323
387
|
console.log('');
|
|
@@ -350,7 +414,7 @@ async function main(argv) {
|
|
|
350
414
|
return r.status ?? 1;
|
|
351
415
|
}
|
|
352
416
|
|
|
353
|
-
module.exports = { resolveCwd, campoYaml, CONSENT_VERSION, CONSENT_TEXT, consentPath, consentimentoOk, pedirConsentimento, aplicarFlagsFeed, metaAds, META_ADS_MCP, avisoPluginNovo, pluginVersion, buildClaudeArgs, keyPath, readKey, keyFileExists, isValidKey, ping, resolveClaude, CHANNEL, PLUGIN, MARKETPLACE_REPO, KEY_RE };
|
|
417
|
+
module.exports = { atualizarPacote, compararVersao, resolveCwd, campoYaml, CONSENT_VERSION, CONSENT_TEXT, consentPath, consentimentoOk, pedirConsentimento, aplicarFlagsFeed, metaAds, META_ADS_MCP, avisoPluginNovo, pluginVersion, buildClaudeArgs, keyPath, readKey, keyFileExists, isValidKey, ping, resolveClaude, CHANNEL, PLUGIN, MARKETPLACE_REPO, KEY_RE };
|
|
354
418
|
|
|
355
419
|
if (require.main === module) {
|
|
356
420
|
main(process.argv.slice(2)).then(code => process.exit(code), err => {
|
package/installer/update.js
CHANGED
|
@@ -388,9 +388,16 @@ const versaoDesatualizada = Boolean(versaoDoPacote) && versaoRegistrada !== vers
|
|
|
388
388
|
if (!plano.trocar.length && !plano.adicionar.length && !plano.restaurar.length && !plano.remover.length && !plano.gerar.length && !plano.preservar.length && !versaoDesatualizada && !metadataReparado) {
|
|
389
389
|
log(''); log('Nada a fazer: sua instalacao ja esta na versao deste pacote.');
|
|
390
390
|
log(atalho(false));
|
|
391
|
+
resumo(0);
|
|
391
392
|
process.exit(0);
|
|
392
393
|
}
|
|
393
394
|
|
|
395
|
+
// Onda 28 rev1: o `ironoffice` roda este update em processo filho e imprime 1 linha so'. Com IRON_EDGE_RESUMO=1
|
|
396
|
+
// a ultima linha da saida diz quantos arquivos trocaram e quantos ficaram porque a pessoa editou.
|
|
397
|
+
function resumo(trocados) {
|
|
398
|
+
if (process.env.IRON_EDGE_RESUMO === '1') log('IRON_UPDATE_RESUMO ' + JSON.stringify({ trocados, preservados: plano.preservar.length }));
|
|
399
|
+
}
|
|
400
|
+
|
|
394
401
|
// ---------------------------------------------------------------- FASE 1: escrever ao lado
|
|
395
402
|
log('');
|
|
396
403
|
log('--- FASE 1: escrevendo ao lado (nada em uso muda ainda) ---');
|
|
@@ -523,6 +530,7 @@ log('================================');
|
|
|
523
530
|
log(' Atualizado com sucesso');
|
|
524
531
|
log('================================');
|
|
525
532
|
log(atalho(false));
|
|
533
|
+
resumo(feitos.length);
|
|
526
534
|
log('Confira quando quiser: npx iron-edge verify');
|
|
527
535
|
log('Reabra o Claude Code para carregar o que mudou.');
|
|
528
536
|
log('');
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "iron-edge",
|
|
3
|
-
"version": "2.
|
|
4
|
-
"description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e
|
|
3
|
+
"version": "2.13.0",
|
|
4
|
+
"description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e 20 skills, com quality gate, memoria, instalador que nunca sobrescreve o comando office (chat do Iron Office no dashboard; confere a chave com o site antes de abrir o Claude) e o doctor (mede a maquina e acende o Setup do site).",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
|
7
7
|
"claude-code",
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: anuncios
|
|
3
|
+
description: Fotografa a conta de anúncios da Meta do projeto (últimos 7 dias), acha os 3 problemas que a Meta não avisa (peça nova que não aparece, data vencida no ar, dinheiro na peça errada) e mais a peça recusada, e grava o retrato na aba Anúncios do Iron Office. Use quando chegar `anúncios: atualizar` (botão do site) ou o aluno disser "como estão meus anúncios", "meus anúncios", "quanto gastei", "o anúncio parou", "por que meu anúncio não roda".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# anuncios — o retrato da conta da Meta, com o que fazer hoje
|
|
7
|
+
|
|
8
|
+
O aluno abre a aba Anúncios do projeto e vê gasto, resultados, custo por resultado e os alertas. Quem tira esse retrato é você, com a conta dele, no computador dele. O site só guarda o que você mediu (ferramenta `ads_status`): nunca token, nunca login, nunca nome de pessoa nem telefone.
|
|
9
|
+
|
|
10
|
+
**Regras que não mudam:**
|
|
11
|
+
- Nunca invente número. Todo número da resposta e do retrato saiu de uma chamada desta vez.
|
|
12
|
+
- Só lê. Pausar peça é UMA pergunta pela `ask` antes, e só no "Sim". Criar campanha, mudar verba ou público não é desta skill: diga que é pelo chat, com aprovação, e pare.
|
|
13
|
+
- **Zero alerta é resultado válido.** Diga em 1 linha e grave o retrato do mesmo jeito.
|
|
14
|
+
|
|
15
|
+
Palavras de aluno: "conjunto de anúncios" vira **grupo**; "CPA" vira **custo por resultado**; "impressões" vira **vezes que apareceu**; status técnico (`effective_status`, `ACTIVE`) nunca aparece: diga "no ar" ou "pausada".
|
|
16
|
+
|
|
17
|
+
## 0. Antes
|
|
18
|
+
|
|
19
|
+
Leia a ficha do projeto (o `PROJETO.md` da linha `[loja: …]`): a linha **Anúncios** (conta de anúncio), país e moeda, e se houver, a data que vale agora (turma, promoção, "vagas preenchidas").
|
|
20
|
+
|
|
21
|
+
## 1. Sem a Meta nesta sessão
|
|
22
|
+
|
|
23
|
+
Se as ferramentas `mcp__meta-ads__*` não existem: não diga "não dá". Uma linha ("pra eu ler os seus anúncios, o Iron precisa estar ligado na sua conta do Facebook; é uma vez só") e os 3 passos, os mesmos da skill `rastreamento-pixel`:
|
|
24
|
+
|
|
25
|
+
AGORA VOCÊ
|
|
26
|
+
1. No terminal onde o Iron roda, digite `/mcp` e aperte Enter.
|
|
27
|
+
2. Com as setas, vá até `meta-ads` e aperte Enter; escolha **Authenticate**. Abre uma página no navegador: entre com o Facebook que anuncia a loja e autorize.
|
|
28
|
+
3. Feche o Iron (Ctrl+C duas vezes), abra de novo com `ironoffice` e peça "anúncios: atualizar".
|
|
29
|
+
|
|
30
|
+
Pare aqui. **Não grave retrato** (a aba já mostra esses passos sozinha).
|
|
31
|
+
|
|
32
|
+
## 2. Qual conta
|
|
33
|
+
|
|
34
|
+
`ads_get_ad_accounts` (a lista vem em páginas de 50: com `next_cursor`, chame de novo com ele até acabar). Só servem as com `is_ads_mcp_enabled: true` **e** `is_queryable: true`; conta do projeto com `is_queryable: false`: diga em 1 linha o `not_queryable_reason` (é a Meta explicando: conta desativada, pagamento pendente…) e pare.
|
|
35
|
+
- A conta da linha Anúncios da ficha, se está na lista: é ela.
|
|
36
|
+
- Sem ficha e uma conta só: é ela. Várias: `ask` "Qual conta anuncia este projeto?" (opções = os nomes, até 6; `skip: true`) e grave a escolha na linha **Anúncios** da tabela da ficha (bloco `<!-- iron:ficha -->`, mesclando, como na skill `loja`).
|
|
37
|
+
- A conta do projeto veio com `is_ads_mcp_enabled: false`: diga em 1 linha que a Meta ainda não liberou a leitura dessa conta pro Iron (está liberando aos poucos) e pare. Nunca troque por outra conta em silêncio.
|
|
38
|
+
- Moeda da conta diferente da moeda da loja: diga em 1 linha (a etapa `conta_anuncio` da trilha trata) e siga medindo.
|
|
39
|
+
|
|
40
|
+
Nas ferramentas, `ad_account_id` é só o número (sem `act_`).
|
|
41
|
+
|
|
42
|
+
**Fuso e "hoje":** `ads_get_ad_entities` com `level: "ad_account"` e `fields: ["timezone_name"]`. "Hoje" é a data **nesse fuso** (calcule no terminal, vale no Mac e no Windows; devolve hoje, hoje − 6 e hoje − 2, em AAAA-MM-DD, sem conta de cabeça na virada do mês: `node -e "const z='<timezone_name>',d=n=>new Date(Date.now()-n*864e5).toLocaleDateString('sv',{timeZone:z});console.log(d(0),d(6),d(2))"`), e todas as janelas abaixo partem dele. Hora pro aluno, sempre nesse fuso e com "há N h".
|
|
43
|
+
|
|
44
|
+
## 3. Medir (7 dias, com hoje)
|
|
45
|
+
|
|
46
|
+
⛔ **Nunca `date_preset: "last_7d"` nem `last_3d`.** Eles deixam o dia de hoje de fora: a peça ligada ontem aparece com zero enquanto já está aparecendo, e você acusaria uma peça boa. Sempre `time_range` explícito, como texto JSON: `'{"since":"<hoje − 6 dias>","until":"<hoje>"}'`.
|
|
47
|
+
|
|
48
|
+
Antes de passar um campo novo em `fields`, confira com `ads_get_field_context` (a ferramenta recusa campo que não existe naquele nível). Os desta skill, conferidos em 30/10/2026.
|
|
49
|
+
|
|
50
|
+
**Como os números chegam (medido):** `amount_spent` vem como `{"value": "152.40", "unit": "BRL"}`: texto, já na moeda da conta (não é centavo). `results` vem como `{"indicator": "...", "value": "6"}` e, sem resultado, `"value": "Not available"`. `cost_per_result` igual, às vezes com o texto do tipo entre parênteses. Regra: converta `value` pra número; `"Not available"`, vazio ou campo ausente = **0**. O `indicator` diz o tipo de resultado (ex.: `reach` = alcance, `...messaging_conversation_started...` = conversa iniciada, `...purchase...` = compra).
|
|
51
|
+
|
|
52
|
+
a) **Por peça, 7 dias:** `ads_get_ad_entities` com `level: "ad"`, `time_range` dos 7 dias, `fields: ["name","campaign_name","adset_name","adset_id","effective_status","amount_spent","impressions","clicks","results","updated_time","created_time","creative_id"]`. Siga `pagination.next_cursor` até o fim (repetindo todos os outros parâmetros). **Campo ausente = 0**: peça sem gasto volta sem `amount_spent` e sem `impressions`, não com zero. O **gasto de cada grupo nos 7 dias** é a soma das peças dele (junte por `adset_id`, nunca pelo nome).
|
|
53
|
+
b) **Por campanha, 7 dias:** a mesma chamada com `level: "campaign"` e `fields: ["name","effective_status","objective","amount_spent","impressions","clicks","results","cost_per_result"]`, até a última página. **Os totais do retrato (`spend`, `impressions`, `clicks`, `results`) são a soma de TODAS as campanhas lidas**, não só das 10 que vão pro retrato.
|
|
54
|
+
c) **Por peça, 3 dias** (só pro alerta C): `level: "ad"`, `time_range` `'{"since":"<hoje − 2>","until":"<hoje>"}'`, `fields: ["name","campaign_name","adset_id","effective_status","amount_spent"]`, até a última página. O gasto do grupo nos 3 dias = soma das peças dele por `adset_id`. **Grupos, 7 dias:** `level: "adset"` com `fields: ["name","campaign_id","effective_status","optimization_goal"]`, até a última página. Serve pro rótulo do resultado e pra contar, **por campanha** (junte pelo `campaign_id` do grupo = o `id` da campanha, nunca pelo nome), quantos grupos ela tem (`adsets_total`) e quantos estão no ar (`adsets_active`: `effective_status` `ACTIVE`, `WITH_ISSUES`, `IN_PROCESS`, `PENDING_REVIEW` ou `PREAPPROVED`). Campanha `ACTIVE` com todos os grupos pausados não gasta: a aba mostra "parada: grupos pausados" com esses dois números.
|
|
55
|
+
d) **Erros:** `ads_get_errors` com `entity_ids: ["<número da conta>"]` (traz os erros das peças dela).
|
|
56
|
+
e) **Texto das peças:** `ads_get_creatives` com `creative_ids` (os do passo a, em lotes) e `fields: ["body","title"]`.
|
|
57
|
+
|
|
58
|
+
**Resultado** = o que a campanha busca (compra, conversa, cadastro): leia o `indicator` do `results`, o `objective` da campanha e o `optimization_goal` do grupo e escreva o rótulo em palavra de aluno ("compras", "conversas no WhatsApp", "cadastros"). Campanhas com tipos de resultado diferentes: some `results` mesmo assim e use "resultados" no rótulo, dizendo na resposta quais tipos entraram. Em dúvida, "resultados".
|
|
59
|
+
|
|
60
|
+
## 4. Os alertas
|
|
61
|
+
|
|
62
|
+
A, B e C só olham peça no ar (`effective_status` `ACTIVE`). A **recusada** olha qualquer situação: peça recusada aparece como `DISAPPROVED` ou `WITH_ISSUES`, nunca como `ACTIVE`.
|
|
63
|
+
|
|
64
|
+
**A · nova_em_zero (peça nova sem aparecer).** Impressões = 0 nos 7 dias **e** passaram mais de 48 h desde `updated_time` **e** o grupo dela gastou mais que 0 nos 7 dias (a soma do passo 3a). Conta-se do `updated_time`, não do `created_time`: a peça que foi editada volta pra fila de entrega da Meta, então a rampa recomeça na edição. No `detail`, escreva "desde a última mudança, em <data e hora>". Com menos de 48 h a peça está **em rampa**: não é alerta, vai pra lista `ramp` com `until` = `updated_time` + 48 h ("reconferir em"). A Meta leva horas pra distribuir entre peças novas; acusar antes disso ensina o aluno a ignorar o alerta.
|
|
65
|
+
- **recusada:** peça com erro no `ads_get_errors` (reprovação, revisão, texto ou imagem recusados) ou com `effective_status` `DISAPPROVED` entra como `recusada` **com qualquer idade e qualquer situação**: não é rampa, é peça que nunca vai entregar. Rode `ads_get_errors` justamente pra separar as duas.
|
|
66
|
+
|
|
67
|
+
**B · data_vencida (data vencida no ar).** Data no nome da peça ou no texto (`body`/`title`) anterior a hoje. Formatos: `DD/MM`, `DD e DD/MM`, `até DD/MM`, "dia 25 de outubro", e `turma MM/AA` (mês inteiro: só vence depois do último dia do mês). Só conta como data o que é data de verdade: dia de 1 a 31 e mês de 1 a 12, perto de palavra de data ("dia", "até", "turma", "em", um mês por extenso) ou no formato da convenção do nome; "24/7", "50/50", "3/4" e proporção não são data. Com mais de uma data, vale a **última** (se a última ainda não passou, não é alerta). Ano: o corrente; se a data no ano corrente ficou mais de 6 meses pra trás, é do ano seguinte. Em dúvida se é data, não acuse: diga na resposta "a peça X tem '<trecho>', não sei se é data". Antes de acusar, leia `campaign_name`: a mesma data pode ser de turma futura numa campanha e de atendimento passado em outra. Se a ficha tem a data que vale agora ou "vagas preenchidas", cruze com ela. Peça sem data não entra no B (só no A).
|
|
68
|
+
|
|
69
|
+
**C · gasto_na_peca_errada (dinheiro na peça errada).** Nos últimos 3 dias, mais de 80 % do gasto de um grupo foi em peças com data vencida (B). O `detail` diz a porcentagem e o valor.
|
|
70
|
+
|
|
71
|
+
**O que não dá pra ler:** a arte (texto dentro da imagem ou do vídeo) e a mensagem de boas-vindas do WhatsApp. No retrato `checked.art` é sempre `false`, e a resposta diz "conferi o texto de N peças; a arte não".
|
|
72
|
+
|
|
73
|
+
Cada alerta leva a peça, a campanha, o número que o sustenta (`detail`, até 160 caracteres) e o que fazer (`action`, até 160): ex. `detail` "no ar desde 27/10 14h, 0 vezes que apareceu, grupo gastou R$ 48 no período"; `action` "confira se o público do grupo é grande o bastante ou pause e suba a peça num grupo próprio". Nada de nome de pessoa, telefone ou e-mail nesses textos.
|
|
74
|
+
|
|
75
|
+
## 5. Gravar
|
|
76
|
+
|
|
77
|
+
`ads_status` com o `project_id` (o `id:` da linha `[loja: …]`) e o `snapshot`:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{ "v": 1, "at": "<agora, ISO com fuso>", "account_id": "<número da conta>", "account_name": "<nome da conta, até 60>",
|
|
81
|
+
"currency": "<moeda da conta, 3 letras>", "window_days": 7,
|
|
82
|
+
"spend": 0, "impressions": 0, "clicks": 0, "results": 0, "result_label": "compras", "cpa": null,
|
|
83
|
+
"campaigns": [{ "name": "…", "status": "ACTIVE", "spend": 0, "results": 0, "adsets_active": 0, "adsets_total": 0 }],
|
|
84
|
+
"top_ads": [{ "name": "…", "campaign": "…", "spend": 0, "impressions": 0, "results": 0 }],
|
|
85
|
+
"alerts": [{ "kind": "data_vencida", "ad": "…", "campaign": "…", "since": "<ISO, opcional>", "detail": "…", "action": "…" }],
|
|
86
|
+
"checked": { "ads": 0, "copy": 0, "art": false },
|
|
87
|
+
"ramp": [{ "ad": "…", "until": "<ISO>" }] }
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- `campaigns`: até 10, as que gastaram mais primeiro. `status` = o `effective_status` como veio (`ACTIVE`, `PAUSED`, `ARCHIVED`, `CAMPAIGN_PAUSED`…): o site mostra `ACTIVE` como "no ar" (ou "parada: grupos pausados" / "no ar · N de M grupos", pela contagem abaixo) e o resto como "pausada". `adsets_active` e `adsets_total` = a contagem de grupos do passo (c) (campanha sem grupo lido: mande os dois em 0). `top_ads`: as 5 peças que mais gastaram. `alerts` e `ramp`: até 10 cada. `cpa` = gasto ÷ resultados (`null` sem resultado). `checked.ads` = peças medidas; `checked.copy` = peças com texto lido.
|
|
91
|
+
- Até 8 kB: nomes longos, encurte. Nome com telefone, e-mail ou `@perfil` chega no site como `[removido]` (o filtro protege o aluno); é esperado.
|
|
92
|
+
- A ferramenta recusou (`O site recusou o retrato: …`)? Corrija o que ela disse e mande de novo uma vez. Recusou de novo: responda os números no chat e diga que o retrato não foi gravado.
|
|
93
|
+
|
|
94
|
+
Na ficha: a linha Anúncios com a conta (se faltava) e 1 linha no Histórico: `AAAA-MM-DD: anúncios medidos pelo Iron: gasto <valor>, <N> alertas`.
|
|
95
|
+
|
|
96
|
+
## 6. Responder
|
|
97
|
+
|
|
98
|
+
Até 4 linhas:
|
|
99
|
+
1. "Últimos 7 dias: <gasto> e <N> <rótulo> (custo por resultado <valor>)."
|
|
100
|
+
2. "<N> alertas" ou "Nada pra corrigir hoje."
|
|
101
|
+
3. "Conferi o texto de <N> peças; a arte não."
|
|
102
|
+
4. "O retrato está na aba Anúncios."
|
|
103
|
+
|
|
104
|
+
Com alerta, termine com o AGORA VOCÊ: o clique certo (no Gerenciador de Anúncios, a peça X → desligar) ou a oferta de pausar:
|
|
105
|
+
- `ask` "Quer que eu pause a peça <nome>?" (opções Sim / Não). Só no **Sim**: `ads_update_entity` com `entity_type: "ad"`, `entity_id` da peça, `fields: '{"status":"PAUSED"}'`. Não chame `ads_activate_entity` depois. Confira lendo de volta (`ads_get_ad_entities` `level: "ad"` com `object_ids` = a peça): só diga "pausada" se o `effective_status` voltou pausado. Depois do sim, tire o retrato de novo (passos 3 a 5) pra aba ficar certa.
|
|
106
|
+
- Uma pergunta por mensagem; uma peça por vez.
|
|
107
|
+
|
|
108
|
+
## Teste do instrumento (pra quem for mexer nesta skill)
|
|
109
|
+
|
|
110
|
+
Os dois lados, sempre:
|
|
111
|
+
- **Acusa:** peça no ar há mais de 48 h (por `updated_time`), zero vezes que apareceu, grupo gastando → `nova_em_zero`. Peça com data `25/10` no nome, no ar em 30/10 → `data_vencida`.
|
|
112
|
+
- **Não acusa:** peça de 27 h com zero (vai pra `ramp`); peça pausada com data vencida; peça com `— 11 e 12/12` em 30/10 (data futura); `turma 10/26` em 30/10/2026 (o mês ainda não acabou); "atendimento 24/7"; peça ligada ontem que já apareceu hoje (é o caso que o `last_7d` erra: por isso ele é proibido).
|
|
113
|
+
- **Recusada com qualquer situação:** peça `DISAPPROVED` com data futura → `recusada` (o filtro "só no ar" não vale pra ela).
|
|
114
|
+
Mudou uma regra e um dos dois lados deixou de bater? A skill quebrou, não a conta.
|
|
@@ -20,6 +20,8 @@ AGORA VOCÊ
|
|
|
20
20
|
2. Com as setas, vá até `meta-ads` e aperte Enter; escolha **Authenticate** (ou "Entrar"). Abre uma página no navegador: entre com o Facebook que anuncia a loja e autorize.
|
|
21
21
|
3. Volte ao terminal, feche o Iron (Ctrl+C duas vezes) e abra de novo com `ironoffice`. Enquanto ele estiver fechado, o chat do site fica sem resposta.
|
|
22
22
|
|
|
23
|
+
O retrato dos anúncios (gasto, resultados e alertas na aba Anúncios do site) é a skill `anuncios`; esta cuida só do pixel.
|
|
24
|
+
|
|
23
25
|
Se `meta-ads` nem aparece na lista do `/mcp`: "rode `npx iron-edge office` no terminal (ele instala a ligação com a Meta) e depois faça os passos acima" (a skill `conectar-mcp` tem o detalhe). Grave a etapa da trilha como `em_andamento` e pare.
|
|
24
26
|
|
|
25
27
|
## Ato 1 · Medir
|
|
@@ -26,7 +26,8 @@ curl -sL -o /dev/null -w '%{http_code}' "<endereço da tabela>"
|
|
|
26
26
|
|
|
27
27
|
1. **Controle primeiro**, uma vez por terminação: o mesmo comando com `google<terminação>` tem que dar `200`. Não deu `200`: esse registro não está medindo; essa terminação fica "não consegui medir".
|
|
28
28
|
2. Depois o nome: `404` = livre · `200` = ocupado · `429` = espere 5 segundos e tente uma vez de novo · outro código = "não consegui medir esse".
|
|
29
|
-
3.
|
|
29
|
+
3. **Meça as duas terminações do mercado** (BR: `.com.br` E `.com`; CO: `.com.co` E `.com`) antes de dizer "livre". Só diga livre quando as duas foram medidas; uma ocupada = diga qual ("o .com.co está livre, o .com já é de outra empresa") e deixe o aluno escolher, ou proponha outro nome.
|
|
30
|
+
4. Terminação fora da tabela (MX e outras): não tem registro medido; não diga livre nem ocupado. Fica "não consegui medir": o aluno confere no registrador quando for comprar.
|
|
30
31
|
|
|
31
32
|
Sem nenhum domínio livre medido: `ask` "Não consegui conferir o <domínio> daqui. Confira no site onde você vai registrar: ele está livre?" (`Livre` / `Ocupado`), `domain_source: "aluno"`.
|
|
32
33
|
Nunca abra registrador nem a Shopify pra "testar" nome.
|