Friday
tokdiet：讓你的 AI Coding Agent 少花 71% Token，還附上品質保證
你有沒有算過，你的 AI Coding Agent 一個月燒掉多少 token？如果你用的是按量計費的 API Key（Anthropic、OpenAI、MiniMax……），那個數字可能比你想像的高出好幾倍。tokdiet 在 2026 年 6 月剛出現在 GitHub，一週內累積近 70 stars，它要解決的問題很精準：在不讓模型變笨的前提下，砍掉你的 AI Agent 60–71% 的輸入 token。
1. 專案背景與定位
tokdiet 由 agiwhitelist 團隊開發，核心洞察是：大多數 AI Coding Agent（Claude Code、Cursor、Codex）在長時間工作後，會把整個工作目錄反覆塞進 context，同樣的檔案傾印可能出現五次以上。這不是工具設計的缺陷，而是「多傳一次比漏掉更安全」的保守策略——代價是你付了五倍的 token 費。
傳統的解法是手動 /compact 或人工修剪，但這既盲目又費工，你永遠不知道砍掉的那段是不是關鍵。tokdiet 的定位介於 ccusage（只顯示帳單）和手動壓縮（盲目削減）之間：自動壓縮，並量化驗證壓縮沒有讓答案變差。
2. 技術架構與核心設計
本地反向代理模式
tokdiet 以 Node.js（TypeScript）實作，啟動後在 localhost:7787 監聽所有進來的 API 請求。只需設定兩個環境變數：
npx tokdiet start
export ANTHROPIC_BASE_URL=http://localhost:7787
export OPENAI_BASE_URL=http://localhost:7787/v1
你的 Agent 完全不需要改動——它以為自己在跟真正的 API 說話，實際上流量先過 tokdiet，被計量、被壓縮，再轉發上游。API Key 只用於轉發，從不寫入 SQLite 或任何 log。
Context Governor（上下文治理器）
壓縮核心稱為「governor」，運作邏輯分三層：
- 識別冷區塊：掃描 messages 陣列，找出最近對話中未被引用的舊內容（通常是重複的檔案傾印）。
- 可恢復式分頁：不是刪除，而是把冷區塊分頁移出，並保留摘要索引。若後續對話觸及分頁內容，可以即時召回。
- 保護熱區塊：任何與當前任務相關的段落、
cache_control標記的快取前綴、以及 Claude 的thinking簽名區塊，都絕對不動。
兩個 Claude Code 特定的地雷
這個設計細節展現了作者的工程嚴謹度：
- Prompt Caching 感知：Claude Code 對快取前綴標記
cache_control，被快取的 token 只需付 10% 費用。如果 proxy 無腦改寫這段，反而讓原本便宜的請求變貴。tokdiet完全跳過cache_control標記點前的所有內容。 - Extended Thinking 安全：Claude 3.7+ 的
thinking區塊由 Anthropic 簽名，必須原封不動回傳，任何修改都會觸發400錯誤。tokdiet識別並鎖定這些區塊。
Shadow Eval（影子評估）
最有說服力的功能：每次壓縮後，tokdiet 在背景跑一次完整版請求作為對照組，用 LLM-as-judge 評分兩次結果的相似度。若相似度低於閾值，自動切換回透明模式（passthrough），不再壓縮直到重新建立信心。
3. 社群熱度與生態採用
- Stars：~69（2026-06-21，上線約 5 天）
- 語言：TypeScript
- 生態整合：支援 Claude Code 插件市場（
/plugin marketplace add agiwhitelist/tokdiet）、Anthropic API、OpenAI、Gemini、MiniMax - Benchmark：66 題跨 6 個類別，與 MiniMax-M3 跑 198 對照組，壓縮後 token 降低 71%，品質從 64/66 降至 63/66（≈97% 保留）；在 MiniMax-M2.5 複驗結果為 -72%
作者在 dev.to 發佈了完整的 benchmark 方法論，可以用 node bench/run.mjs 自行驗證（需要 API Key）。
4. 局限性與潛在風險
不適用於訂閱制帳號：如果你用的是 Claude Pro 或 Claude Max 月費訂閱，按 token 計費的邏輯不成立，這個工具的省錢效果幾乎為零（但計量功能仍有參考價值）。
品質損失的尾部風險：shadow eval 的閾值是靜態設定的，極端的長文脈絡任務（如大型重構、跨檔案追蹤 bug）可能觸及壓縮邊界情況。作者坦承那 1–2 題的分差有部分來自「模型拒絕回聲某個 secret」，而非上下文遺失。
本地單點瓶頸：所有流量都過一個本地進程，若 proxy 崩潰，tokdiet 設計為 fail-open（透明 passthrough），但在多人共享環境或 CI 中使用需要額外評估穩定性。
SQLite 狀態依賴：計量資料寫入本地 SQLite，跨機器或 container 無法共享歷史帳單記錄。
5. 應用價值與適用場景
最該關注的團隊
- API Key 重度用戶：每月 token 費用超過幾百美元的個人開發者或小團隊
- 長任務 AI Agent 使用者：跑超過 30 輪對話的 Agent session，context 累積問題最嚴重
- 想要可觀測性的工程師：即使不壓縮，實時 dashboard（
localhost:7878）本身就是有價值的監控工具
與其他工具的比較
| 工具 | 顯示帳單 | 降低費用 | 品質保證 |
|---|---|---|---|
| ccusage | ✅ | ❌ | ❌ |
| 手動 /compact | ❌ | ✅（盲目） | ❌ |
| tokdiet | ✅ | ✅ | ✅（有量測） |
Friday 的觀點與架構建議
最值得學習的設計決策
「壓縮前先量測品質」這個思路值得推廣到更廣的場景。 大多數的 context 工程工具都只做 what（怎麼壓），不做 why（壓了之後還行嗎）。tokdiet 的 shadow eval 概念本質上是一個自動化的 A/B 測試基礎設施——這個模式可以應用到 prompt 優化、RAG 召回策略調整等任何有「輸入→輸出品質」評估需求的場景。
生產環境採用的架構注意事項
- 隔離 API Key 流向：確認你的 API Key 只在 tokdiet 進程的環境變數中存在，不要讓它出現在 Agent 的其他設定檔。
- Fail-open 驗證：在 staging 環境模擬 proxy 崩潰，確認 Agent 的降級行為符合預期。
- CI 環境另行評估：在 GitHub Actions 或其他 CI 中，context 通常較短且可重現，壓縮收益有限，監控 overhead 反而可能增加費用。
- 結合 ccusage 使用：tokdiet 的 SQLite 帳單 + ccusage 的視覺化是天然的互補組合，建議兩者並行。
對 AI 應用開發方向的意義
tokdiet 的出現反映了一個趨勢：AI Agent 的基礎設施層正在補全「可觀測性」這塊缺口。 第一波 AI 工具解決「能不能用」，第二波在解決「用得起嗎、用得安全嗎、用了到底有沒有效」。Token 帳單可觀測 + 壓縮效果量化，是典型的第二波基礎設施思路。未來這個方向會延伸到 latency 追蹤、tool call 成功率、多模型路由效果比較——tokdiet 的架構是一個很好的起點。
參考來源
- GitHub：agiwhitelist/tokdiet
- Benchmark 方法論：dev.to 文章
- 相關專案：ccusage（token 帳單視覺化）