dev-trace

¿Qué hace dev-trace?

Convierte un correo electrónico en un perfil público estructurado ejecutando una cascada fija de fuentes públicas. Cada capa se activa solo si su clave API está presente. Solo datos públicos; por debajo del umbral de confianza devuelve candidatos en lugar de adivinar. Sin dependencias (Node 18+); trae tus propias claves API.

Cómo ejecutar

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 legible para humanos (úsalo al mostrar al usuario).
• --json <path>—escribe el objeto crudo en un archivo en lugar de stdout.
• --max-depth N—detiene después de la profundidad N (0–4) para las capas rápidas. Por defecto 4.
• --deep—también ejecuta la profundidad 5 (SixtyFour). Lento (minutos) y costoso; requiere SIXTYFOUR_API_KEY.
• --tier low|medium|high—profundidad de investigación de SixtyFour (por defecto low). Más alto = más minucioso, más lento, más créditos.
• --no-bio—salta el paso de biografía de Tabstack /research (activado por defecto cuando se resuelve un nombre y se configura TABSTACK_API_KEY).
• --bio-mode fast|balanced|deep|max—profundidad de investigación para la biografía (por defecto fast).

La cascada

Profundidad	Capa	Fuente	Clave	Se ejecuta
0	validar	sintaxis + MX + desechables	ninguna	siempre, gratis
1	superficial	Gravatar + scraping de dominio	ninguna	siempre, gratis
1	verificar	Hunter verificación de email	HUNTER_API_KEY	si tiene clave
2	perfil	identidad GitHub + conceptos básicos ICP	GITHUB_TOKEN (recomendado)	siempre, gratis
3	enriquecido	Tabstack web/empresa	TABSTACK_API_KEY	si tiene clave
4	profundo	Hunter enriquecimiento de persona	HUNTER_API_KEY	si tiene clave
5	más profundo	SixtyFour inteligencia de persona (búsqueda LinkedIn)	SIXTYFOUR_API_KEY	solo con --deep

HUNTER_API_KEY desbloquea tanto la verificación (profundidad 1, 0.5 créditos/llamada) como el enriquecimiento de persona (profundidad 4, 0.2 créditos/llamada); nota que verificar cuesta más que enriquecer. La profundidad 5 (SixtyFour) es la inmersión profunda opcional: se ejecuta solo con --deep, tarda minutos (investigación web asíncrona) y se ancla en el correo mismo más cualquier nombre/empresa/LinkedIn encontrado aguas arriba. Solo omite correos desechables o no entregables (registrado en meta).

Claves

Copia .env.example a .env en este directorio de skill y agrega las claves que tengas (el motor lee .env desde la raíz de la skill o scripts/). Todas son opcionales; las capas de validación, superficial y GitHub se ejecutan sin ninguna. Una capa cuya clave esté ausente se omite silenciosamente. Las claves nunca se incluyen con la skill (.env está en gitignore).

Costo y política de uso (para el agente)

La skill está diseñada para que obtengas un perfil útil de forma gratuita, y cada proveedor de pago es opcional: gasta solo cuando un lead lo vale.

Niveles de costo, del más barato primero:

• 🟢 Gratis, sin cuenta—validar, superficial (Gravatar + dominio), identidad GitHub. Ejecuta con cero claves.
• 🟢 Clave gratis, opcional—GITHUB_TOKEN (gratis de generar) solo aumenta el límite de tasa y la fiabilidad de GitHub.
• 🟢 Cuenta gratis, rinde mucho—Tabstack (TABSTACK_API_KEY): enriquecimiento de empresa (profundidad 3) + la biografía /research con citas. Una cuenta gratis de Tabstack cubre mucho antes de que pagues.
• 🟡 Créditos medidos, nivel gratis luego pago—Hunter (HUNTER_API_KEY): verificación de email (0.5 cr) + enriquecimiento de persona (0.2 cr).
• 🔴 Premium, $$$$ reales—SixtyFour (SIXTYFOUR_API_KEY, --deep): búsqueda más profunda de persona + LinkedIn. La capa de último recurso para objetivos de alto valor.

Detalle por capa:

Capa	Costo	Se ejecuta
1 verificar (Hunter)	0.5 créditos Hunter	si HUNTER_API_KEY está presente
3 Tabstack empresa	créditos Tabstack	si TABSTACK_API_KEY está presente
4 Hunter persona	0.2 créditos Hunter	si HUNTER_API_KEY está presente
bio (Tabstack /research)	créditos Tabstack (fast más barato)	si se resolvió un nombre
5 SixtyFour	costoso—ver abajo	solo con --deep

Política: por defecto, capas gratis y baratas. Para una consulta rápida gratuita, --max-depth 2 ejecuta solo las capas sin costo.

SixtyFour (--deep) es costoso y tiene límite de tasa. El costo exacto depende de tu plan de SixtyFour; en el plan de entrada (~100 créditos/mes, $0.24/crédito) una extracción de inteligencia de persona medium midió 20 créditos ($4.80, ~2.5 min), es decir, aproximadamente 5 extracciones/mes. Trata cada ejecución --deep como un recurso escaso:

• Nunca ejecutes --deep para "ser minucioso". Solo en un objetivo genuinamente de alto valor.
• Solo después de que las capas más baratas (enriquecimiento de persona de Hunter, la biografía /research) hayan dado resultados insuficientes.
• Confirma con el usuario antes de gastar una extracción de SixtyFour, y por defecto --tier low—nunca subas el nivel sin que te lo pidan.
• Obligatorio, no solo recomendado: --deep se niega a ejecutarse a menos que un humano acepte el costo, mediante DEV_TRACE_ALLOW_DEEP=1 en el entorno o una confirmación interactiva. No puede dispararse de forma autónoma. DEV_TRACE_MAX_DEPTH=N limita la profundidad para uso sin supervisión. Consulta la sección "Agentes autónomos / sin supervisión" del README.

--bio-mode por encima de fast y las profundidades 3/4 gastan créditos ordinarios: está bien cuando es relevante, pero no subas --bio-mode sin que te lo pidan.

Biografía (Tabstack /research)

Después de las capas de identidad, si se resolvió un nombre y se configuró TABSTACK_API_KEY, una llamada a Tabstack /research sintetiza una bio profesional con citas en el perfil, con URL de origen en meta.bio_sources. El modo por defecto fast (el más barato); sube con --bio-mode, o salta con --no-bio. Necesita un nombre, así que sin una coincidencia de Hunter/GitHub solo se ejecuta junto con --deep (que proporciona el nombre a través de SixtyFour).

Al informar resultados: reporta qué profundidades se ejecutaron (meta.depths_run) y qué claves desbloquearían más. No inventes campos que el rastreo no devolvió.

Salida

{
  "meta": { "email": "...", "depths_run": [0,1,2], "match_status": "probable", "generated_at": "..." },
  "profile": { "<campo>": { "value": "...", "confidence": 0.85, "sources": ["github"], "conflict": null } }
}

• Cada campo está envuelto con value, confidence (0–1), sources y conflict (null, o el valor competidor cuando las capas discrepan).
• meta.match_status: verified (identidad confirmada + entregable), probable (identidad encontrada, sin confirmar), unverified_candidates (por debajo del umbral).
• Las capas fallidas o con límite de tasa se registran en meta.errors / meta.rate_limited; la cascada nunca aborta por una capa.

Notas

• Produce solo el perfil. Darle forma a un registro CRM, informe u otro entregable es un paso posterior separado.
• Independiente y distribuible: sin dependencias (Node 18+), sin necesidad de clonar o compilar externamente.
• Solo datos públicos; sin perfiles inventados. Por debajo del umbral de confianza devuelve candidatos en lugar de afirmar un valor.