dev-trace은(는) 무엇을 하나요?
이메일을 공개 출처의 고정된 워터폴을 실행하여 구조화된 공개 프로필로 변환합니다. 각 계층은 해당 API 키가 있을 때만 활성화됩니다. 공개 데이터만 사용하며, 신뢰 임계값 이하일 때는 추측 없이 후보를 반환합니다. 의존성 없음 (Node 18+); 자신의 API 키를 가져와 사용하세요.
실행 방법
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 (사용자에게 보여줄 때 사용).--json <path>— 객체를 stdout 대신 파일에 기록.--max-depth N— 빠른 계층에 대해 깊이 N(0–4)에서 중단. 기본값 4.--deep— 깊이 5(SixtyFour)도 실행. 느리며(몇 분) 비용이 큼;SIXTYFOUR_API_KEY필요.--tier low|medium|high— SixtyFour 연구 깊이 (기본low). 높을수록 더 철저하고 느리며 더 많은 크레딧 사용.--no-bio— Tabstack/research바이오 단계 생략 (이름이 확인되고TABSTACK_API_KEY가 설정된 경우 기본으로 실행).--bio-mode fast|balanced|deep|max— 바이오 연구 깊이 (기본fast).
워터폴
| 깊이 | 계층 | 출처 | 키 | 실행 조건 |
|---|---|---|---|---|
| 0 | validate | 구문 + MX + 일회용 이메일 확인 | 없음 | 항상, 무료 |
| 1 | surface | Gravatar + 도메인 스크래핑 | 없음 | 항상, 무료 |
| 1 | verify | Hunter 이메일 검증 | HUNTER_API_KEY | 키가 있을 때 |
| 2 | profile | GitHub 신원 + ICP 기본 정보 | GITHUB_TOKEN (권장) | 항상, 무료 |
| 3 | enriched | Tabstack 웹/회사 | TABSTACK_API_KEY | 키가 있을 때 |
| 4 | deep | Hunter 개인 정보 보강 | HUNTER_API_KEY | 키가 있을 때 |
| 5 | deepest | SixtyFour 사람 인텔리전스 (LinkedIn 검색) | SIXTYFOUR_API_KEY | --deep 있을 때만 |
HUNTER_API_KEY는 검증(깊이 1, 0.5 크레딧/호출)과 개인 정보 보강(깊이 4, 0.2 크레딧/호출)을 모두 잠금 해제합니다. 참고: 검증이 보강보다 더 비쌉니다. 깊이 5(SixtyFour)는 선택적 심층 분석입니다. --deep이 있을 때만 실행되며, 몇 분이 걸리고(비동기 웹 연구), 이메일 자체와 상위에서 찾은 이름/회사/LinkedIn을 기준으로 합니다. 일회용 또는 배달 불가 이메일인 경우 건너뜁니다 (meta에 기록).
키
.env.example을 이 스킬 디렉토리의 .env로 복사하고 가지고 있는 키를 추가하세요 (엔진은 스킬 루트 또는 scripts/에서 .env를 읽습니다). 모든 키는 선택 사항입니다. validate, surface, GitHub 계층은 키 없이 실행됩니다. 키가 없는 계층은 자동으로 건너뜁니다. 키는 스킬에 번들되지 않습니다 (.env는 gitignored 됩니다).
비용 및 사용 정책 (에이전트용)
이 스킬은 무료로 유용한 프로필을 얻을 수 있도록 설계되었으며, 각 유료 제공자는 옵트인 방식입니다. 리드가 가치 있을 때만 비용을 지출하세요.
비용 계층, 가장 저렴한 순:
- 🟢 무료, 계정 불필요 — validate, surface (Gravatar + 도메인), GitHub 신원. 키 없이 실행.
- 🟢 무료 키, 선택 사항 —
GITHUB_TOKEN(무료 생성)은 GitHub의 속도 제한과 안정성만 높임. - 🟢 무료 계정, 넉넉히 사용 가능 — Tabstack (
TABSTACK_API_KEY): 회사 정보 보강 (깊이 3) + 인용된/research바이오. 무료 Tabstack 계정으로 지불 전에 많이 사용 가능. - 🟡 측정 크레딧, 무료 티어 후 유료 — Hunter (
HUNTER_API_KEY): 이메일 검증 (0.5 크레딧) + 개인 정보 보강 (0.2 크레딧). - 🔴 프리미엄, 실제 $$$$ — SixtyFour (
SIXTYFOUR_API_KEY,--deep): 가장 깊은 사람 + LinkedIn 검색. 높은 가치의 타겟을 위한 비상 계층.
계층별 세부 정보:
| 계층 | 비용 | 실행 조건 |
|---|---|---|
| 1 verify (Hunter) | 0.5 Hunter 크레딧 | HUNTER_API_KEY가 있을 때 |
| 3 Tabstack 회사 | Tabstack 크레딧 | TABSTACK_API_KEY가 있을 때 |
| 4 Hunter 개인 | 0.2 Hunter 크레딧 | HUNTER_API_KEY가 있을 때 |
바이오 (Tabstack /research) | Tabstack 크레딧 (fast가 가장 저렴) | 이름이 확인되었을 때 |
| 5 SixtyFour | 비용 큼 — 아래 참조 | --deep 있을 때만 |
정책: 기본값은 무료 + 저렴한 계층. 빠른 무료 조회를 원한다면 --max-depth 2로 비용 없는 계층만 실행.
SixtyFour (--deep)는 비용이 많이 들고 속도 제한이 있습니다. 정확한 비용은 SixtyFour 요금제에 따라 다릅니다. 입문 요금제(100 크레딧/월, 크레딧당 $0.24)에서 $4.80, ~2.5분)이 소모되어, 월 약 5회 풀 가능합니다. 모든 medium 사람 인텔리전스 풀은 약 20 크레딧(--deep 실행을 희소 자원으로 취급하세요:
- "철저함을 위해"
--deep을 실행하지 마세요. 진정으로 높은 가치의 타겟에만 사용. - 저렴한 계층(Hunter 개인 정보 보강,
/research바이오)이 부족할 때만 실행. - SixtyFour 풀을 사용하기 전에 사용자와 확인하세요. 기본
--tier low로 설정하고, 요청 없이 티어를 올리지 마세요. - 권고 사항이 아닌 강제 사항:
--deep은 환경에DEV_TRACE_ALLOW_DEEP=1이 설정되거나 대화형 확인을 통해 인간이 비용을 승인하지 않으면 실행을 거부합니다. 자율적으로 실행할 수 없습니다.DEV_TRACE_MAX_DEPTH=N은 헤드리스 사용 시 깊이를 제한합니다. README의 "헤드리스 / 자율 에이전트" 섹션을 참조하세요.
--bio-mode를 fast 이상으로 올리거나 깊이 3/4는 일반 크레딧을 사용합니다. 관련 있을 때는 괜찮지만, 요청 없이 --bio-mode를 올리지 마세요.
바이오 (Tabstack /research)
신원 계층 이후, 이름이 확인되고 TABSTACK_API_KEY가 설정된 경우, Tabstack /research 호출이 인용된 전문 **bio**를 프로필에 합성하며, 출처 URL은 meta.bio_sources에 포함됩니다. 기본 모드는 fast(가장 저렴); --bio-mode로 올리거나 --no-bio로 건너뜁니다. 이름이 필요하므로 Hunter/GitHub 일치 없이 --deep(SixtyFour가 이름 제공)이 있을 때만 실행됩니다.
결과를 전달할 때: 어떤 깊이가 실행되었는지(meta.depths_run)와 더 많은 정보를 얻을 수 있는 키가 무엇인지 보고하세요. trace가 반환하지 않은 필드를 임의로 만들지 마세요.
출력
{
"meta": { "email": "...", "depths_run": [0,1,2], "match_status": "probable", "generated_at": "..." },
"profile": { "<field>": { "value": "...", "confidence": 0.85, "sources": ["github"], "conflict": null } }
}
- 모든 필드는
value,confidence(0–1),sources,conflict(null, 또는 계층 간 충돌 시 경쟁 값)로 감싸집니다. meta.match_status:verified(확인된 신원 + 배달 가능),probable(신원 발견, 미확인),unverified_candidates(임계값 미만).- 실패하거나 속도 제한에 걸린 계층은
meta.errors/meta.rate_limited에 기록됩니다. 워터폴은 한 계층에서 중단되지 않습니다.
참고 사항
- 프로필만 생성합니다. CRM 레코드, 브리핑 또는 다른 전달물로 변환하는 것은 별도의 후속 단계입니다.
- 독립 실행형 및 배포 가능: 의존성 없음 (Node 18+), 외부 클론이나 빌드 불필요.
- 공개 데이터만 사용합니다. 가상의 프로필을 만들지 않습니다. 신뢰 임계값 이하일 때는 값을 주장하지 않고 후보를 반환합니다.