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 | 驗證 | 語法 + MX + 一次性信箱 | 無 | 總是執行，免費 |
| 1 | 表面 | Gravatar + 網域爬取 | 無 | 總是執行，免費 |
| 1 | 驗證 | Hunter 電子郵件驗證 | HUNTER_API_KEY | 若有金鑰 |
| 2 | 個人檔案 | GitHub 身份 + ICP 基礎資訊 | GITHUB_TOKEN（建議） | 總是執行，免費 |
| 3 | 豐富化 | Tabstack 網路/公司 | TABSTACK_API_KEY | 若有金鑰 |
| 4 | 深入 | Hunter 人物豐富化 | HUNTER_API_KEY | 若有金鑰 |
| 5 | 最深 | 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）。所有金鑰皆為選填；驗證、表面與 GitHub 層級無需任何金鑰即可執行。缺少金鑰的層級會被靜默跳過。金鑰絕不會與技能綑綁（.env 已在 .gitignore 中）。
成本與使用政策（給代理）
此技能的設計讓你可以在免費情況下獲得有用的個人檔案，而每個付費提供商皆為選擇加入——只有在潛在客戶值得時才花費。
成本層級，由最便宜排列：
- 🟢 免費，無需帳戶——驗證、表面（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 驗證（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）下，一次 medium 人物情報拉取約耗費 20 點數（約 $4.80，約 2.5 分鐘），也就是每月約 5 次。請將每次 --deep 執行視為稀有資源：
- 切勿為了「求完整」而執行
--deep。僅在真正高價值目標時才使用。 - 僅在較便宜的層級（Hunter 人物豐富化、
/research個人簡介）已經不足時才考慮。 - 在使用 SixtyFour 拉取前，先確認使用者同意，並預設
--tier low——絕不未經提示就提高層級。 - 強制執行，而非僅建議： 除非使用者已接受成本（透過環境變數
DEV_TRACE_ALLOW_DEEP=1或互動式確認），否則--deep拒絕執行。它不能自主觸發。DEV_TRACE_MAX_DEPTH=N可在無頭模式下限制深度。請參閱 README 中的「無頭 / 自主代理」章節。
高於 --bio-mode 的 fast 模式以及深度 3/4 會耗費一般點數——在相關時使用沒問題，但請勿未經提示就提高 --bio-mode。
個人簡介（Tabstack /research）
在身份層級之後，如果已解析出名稱且設定了 TABSTACK_API_KEY，Tabstack /research 呼叫會合成一份附有引用的專業個人簡介到個人檔案中，並附上來源 URL 在 meta.bio_sources。預設模式為 fast（最便宜）；可使用 --bio-mode 提高，或使用 --no-bio 跳過。需要名稱，因此在沒有 Hunter/GitHub 匹配的情況下，它僅會在 --deep（透過 SixtyFour 提供名稱）時一併執行。
轉達結果時：請回報哪些深度已執行（meta.depths_run）以及哪些金鑰可以解鎖更多資料。請勿發明追蹤未回傳的欄位。
輸出
{
"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+），無需外部 clone 或建置。
- 僅使用公開資料；不發明個人檔案。低於信心門檻時，會返回候選清單而非斷言某個值。