O que dev-trace faz?
Transforma um e-mail em um perfil público estruturado executando uma cascata fixa de fontes públicas, cada camada ativada pela presença de sua chave de API. Apenas dados públicos—abaixo do limite de confiança, retorna candidatos em vez de adivinhar. Zero dependências (Node 18+); traga suas próprias chaves de API.
Como executar
node scripts/dev-trace.mjs <email> [--pretty] [--json <path>] [--max-depth N] [--deep] [--tier low|medium|high] [--no-bio] [--bio-mode fast|balanced|deep|max]
--pretty—JSON legível para humanos (use ao mostrar para o usuário).--json <path>—escreve o objeto bruto em um arquivo em vez do stdout.--max-depth N—para após a profundidade N (0–4) para as camadas rápidas. Padrão 4.--deep—também executa a profundidade 5 (SixtyFour). Lento (minutos) e caro; requerSIXTYFOUR_API_KEY.--tier low|medium|high—profundidade de pesquisa do SixtyFour (padrãolow). Maior = mais completo, mais lento, mais créditos.--no-bio—pula a etapa de biografia/researchdo Tabstack (ativada por padrão quando um nome é resolvido eTABSTACK_API_KEYestá definida).--bio-mode fast|balanced|deep|max—profundidade de pesquisa para a biografia (padrãofast).
A cascata
| Profundidade | Camada | Fonte | Chave | Executa |
|---|---|---|---|---|
| 0 | validar | sintaxe + MX + descartável | nenhuma | sempre, gratuito |
| 1 | superfície | Gravatar + raspagem de domínio | nenhuma | sempre, gratuito |
| 1 | verificar | Verificação de e-mail Hunter | HUNTER_API_KEY | se chave |
| 2 | perfil | Identidade GitHub + princípios ICP | GITHUB_TOKEN (recomendado) | sempre, gratuito |
| 3 | enriquecido | Tabstack web/empresa | TABSTACK_API_KEY | se chave |
| 4 | profundo | Enriquecimento de pessoa Hunter | HUNTER_API_KEY | se chave |
| 5 | mais profundo | Inteligência de pessoas SixtyFour (pesquisa LinkedIn) | SIXTYFOUR_API_KEY | apenas com --deep |
HUNTER_API_KEY desbloqueia tanto a verificação (profundidade 1, 0,5 créditos/chamada) quanto o enriquecimento de pessoa (profundidade 4, 0,2 créditos/chamada)—observe que verificar custa mais que enriquecer. A profundidade 5 (SixtyFour) é a imersão profunda opcional: executa somente com --deep, leva minutos (pesquisa web assíncrona) e ancora no próprio e-mail mais qualquer nome/empresa/LinkedIn encontrado upstream. Pula apenas para e-mails descartáveis ou não entregáveis (registrado em meta).
Chaves
Copie .env.example para .env neste diretório da skill e adicione as chaves que você tiver (o motor lê .env da raiz da skill ou de scripts/). Todas são opcionais; as camadas de validação, superfície e GitHub funcionam sem nenhuma. Uma camada cuja chave está ausente é silenciosamente ignorada. As chaves nunca são empacotadas com a skill (.env está no gitignore).
Política de custo e uso (para o agente)
A skill foi construída para que você obtenha um perfil útil gratuitamente, e cada provedor pago é opcional—gaste apenas quando um lead valer a pena.
Níveis de custo, do mais barato primeiro:
- 🟢 Gratuito, sem conta—validar, superfície (Gravatar + domínio), identidade GitHub. Execute sem chaves.
- 🟢 Chave gratuita, opcional—
GITHUB_TOKEN(gratuito para gerar) apenas aumenta o limite de taxa e a confiabilidade do GitHub. - 🟢 Conta gratuita, rende muito—Tabstack (
TABSTACK_API_KEY): enriquecimento de empresa (profundidade 3) + a biografia/researchcitada. Uma conta gratuita do Tabstack cobre bastante antes de você precisar pagar. - 🟡 Créditos medidos, nível gratuito depois pago—Hunter (
HUNTER_API_KEY): verificação de e-mail (0,5 cr) + enriquecimento de pessoa (0,2 cr). - 🔴 Premium, $$$$ real—SixtyFour (
SIXTYFOUR_API_KEY,--deep): pesquisa mais profunda de pessoa + LinkedIn. A camada de último recurso para alvos de alto valor.
Detalhe por camada:
| Camada | Custo | Executa |
|---|---|---|
| 1 verificar (Hunter) | 0,5 créditos Hunter | se HUNTER_API_KEY presente |
| 3 Tabstack empresa | créditos Tabstack | se TABSTACK_API_KEY presente |
| 4 Hunter pessoa | 0,2 créditos Hunter | se HUNTER_API_KEY presente |
bio (Tabstack /research) | créditos Tabstack (fast mais barato) | se um nome foi resolvido |
| 5 SixtyFour | caro—veja abaixo | apenas com --deep |
Política: padrão para camadas gratuitas + baratas. Para uma consulta gratuita rápida, --max-depth 2 executa apenas as camadas sem custo.
SixtyFour (--deep) é caro e com limite de taxa. O custo exato depende do seu plano SixtyFour; no plano inicial (~100 créditos/mês, $0,24/crédito) uma coleta de inteligência de pessoa medium mediu 20 créditos ($4,80, ~2,5 min), ou seja, aproximadamente 5 coletas/mês. Trate cada execução --deep como um recurso escasso:
- Nunca execute
--deeppara "ser completo". Apenas para um alvo genuinamente de alto valor. - Somente depois que as camadas mais baratas (enriquecimento de pessoa Hunter, a biografia
/research) não derem resultado. - Confirme com o usuário antes de gastar uma coleta SixtyFour, e use o padrão
--tier low—nunca aumente o nível sem solicitação. - Imposto, não apenas aconselhado:
--deepse recusa a executar a menos que um humano tenha aceitado o custo, viaDEV_TRACE_ALLOW_DEEP=1no ambiente ou uma confirmação interativa. Ele não pode disparar autonomamente.DEV_TRACE_MAX_DEPTH=Nlimita a profundidade para uso headless. Veja a seção "Agentes headless / autônomos" do README.
--bio-mode acima de fast e profundidades 3/4 gastam créditos comuns—tudo bem quando relevante, mas não aumente --bio-mode sem solicitação.
Biografia (Tabstack /research)
Após as camadas de identidade, se um nome foi resolvido e TABSTACK_API_KEY está definida, uma chamada Tabstack /research sintetiza uma bio profissional citada no perfil, com URLs de fonte em meta.bio_sources. Modo padrão fast (mais barato); aumente com --bio-mode, ou pule com --no-bio. Precisa de um nome, então sem uma correspondência Hunter/GitHub, executa apenas junto com --deep (que fornece o nome via SixtyFour).
Ao relatar resultados: informe quais profundidades foram executadas (meta.depths_run) e quais chaves desbloqueariam mais. Não invente campos que o rastreamento não retornou.
Saída
{
"meta": { "email": "...", "depths_run": [0,1,2], "match_status": "probable", "generated_at": "..." },
"profile": { "<campo>": { "value": "...", "confidence": 0.85, "sources": ["github"], "conflict": null } }
}
- Cada campo é encapsulado com
value,confidence(0–1),sourceseconflict(null, ou o valor concorrente quando as camadas discordam). meta.match_status:verified(identidade confirmada + entregável),probable(identidade encontrada, não confirmada),unverified_candidates(abaixo do limite).- Camadas com falha ou limitadas por taxa são registradas em
meta.errors/meta.rate_limited; a cascata nunca aborta por causa de uma camada.
Observações
- Produz apenas o perfil. Moldá-lo em um registro de CRM, resumo ou outro entregável é uma etapa separada posterior.
- Independente e distribuível: zero dependências (Node 18+), sem necessidade de clonagem externa ou construção.
- Apenas dados públicos; nenhum perfil inventado. Abaixo do limite de confiança, retorna candidatos em vez de afirmar um valor.