Caveman：AI 代理程式的 Token 壓縮工具

1. 專案概覽

Caveman 是一個開源工具組——包含類似 Claude Code 的技能以及本機代理程式——透過壓縮 AI 程式設計代理程式讀取的內容（輸入）與輸出的內容（輸出），來降低其 Token 消耗，同時不會遺失精確的程式碼、錯誤訊息或關鍵上下文。

2. 背景與定位

核心使命：隨著代理式程式設計工作階段越來越長，上下文視窗很快就會被填滿，API 費用也隨之攀升。Caveman 的理念——「能用少量 Token 解決時，何必浪費大量 Token」——旨在即時壓縮冗長的工具輸出、日誌、JSON 和差異比對結果，讓代理程式能在相同預算內完成更多工作，同時保證原始位元組始終可以完整恢復。
兩款互補產品：原始的 Caveman 技能會讓代理程式自身的回應更為簡潔（基準測試顯示輸出 Token 約減少 65%），代價是每輪對話會有少許額外開銷。Caveman 2 是較新的本機代理程式，會攔截傳送至服務供應商的流量，並在輸入離開本機前進行壓縮（一項固定基準測試報告指出，供應商回報的輸入 Token 減少了 33.2%）。
與類似專案的差異：Caveman 並非嘗試摘要或改寫內容（這可能會導致精確程式碼或堆疊追蹤遺失），而是採用感知內容類型且安全的無損壓縮——僅在測量結果確定更小時才傳送轉換後的資料，並保留以內容定址的原始副本以供位元組級別的精確恢復；其文件（「誠實數據」）也明確區分哪些節省量是本機推論得出的，哪些是經由獨立基準測試驗證的。

3. 功能分類

🗜️ 壓縮引擎
針對代理程式最常處理的內容提供類型感知壓縮器：

JSON 結構壓縮（鍵值/結構/錯誤樹狀圖）——典型減少幅度為 70–90%
日誌壓縮（錯誤、追蹤、邊界）——85–95%
程式碼壓縮（匯入、簽章、型別）——40–70%
差異比對壓縮（標頭、變更行）——60–80%
搜尋結果與文字/HTML 壓縮——50–95%
目的：在這些最雜亂、重複性最高的內容類型消耗上下文 Token 之前先將其縮小。

🖼️ 像素模式
將密集文字（打包的工具目錄、長日誌）渲染為 PNG 影像供具備視覺能力的模型使用；根據一份記錄案例，此舉可將約 5.5 萬個文字 Token 降至約 1.1 萬個影像 Token（減少 79%）。
目的：當模型讀取影像的成本低於原始文字時，以影像 Token 取代文字 Token。

🧠 學習與分析
caveman learn 指令會掃描代理程式的本機歷史記錄，找出 Token 消耗熱點並分類修復方式。
目的：在不向外傳送任何資料或向使用者收費的情況下，呈現具體且可量化的節省機會。

🔌 代理程式整合
原生支援包裝 Claude Code、OpenAI Codex CLI、Gemini CLI、Aider、opencode、Hermes Agent 及 OpenClaw，並透過 baseURL 層級相容於 Vercel AI SDK、LangChain、LiteLLM、CrewAI 和 PydanticAI 等框架——總計支援超過 30 種代理程式。
目的：讓任何現有的代理程式設定都能透過壓縮代理程式路由流量，且幾乎或完全無需修改程式碼。

🧰 CLI 工具
獨立指令如 caveman shrink、caveman browse、caveman mem remember|recall 及 caveman toon encode|decode。
目的：讓開發人員在代理程式工作階段之外，也能直接透過程式腳本存取相同的壓縮基本單元。

4. 主要亮點

位元組級精確恢復：每個壓縮負載在傳送壓縮資料前，都會將其原始位元組儲存於以內容定址的儲存空間中，因此不會有任何實質遺失。
僅在變小時才壓縮的保證：只有在測量結果確定能減少大小時才會執行轉換；若拒絕壓縮，系統會記錄原因，而非默默降低內容品質。
輸入/輸出分離壓縮：技能（輸出）與代理程式（輸入）可獨立採用，團隊可優先選用對自身價值較高的項目。
透明基準測試：「誠實數據」文件區分了本機推論的節省量與獨立測量的基準測試結果，避免誇大不實的宣稱。
可選強度等級：代理程式內的 /caveman 技能支援多種壓縮強度（lite、full、ultra 及「文言」變體），以符合不同的詳細程度需求。
廣泛的代理程式支援：透過原生包裝或簡單的 baseURL 設定即可相容於超過 30 種代理程式與框架，而非將使用者鎖定在單一代理程式產品上。

5. 依角色劃分的使用情境

一般開發人員：在日常代理式程式設計工作階段（Claude Code、Codex、Gemini CLI、Aider 等）中減少 Token 花費與上下文膨脹，且無需改變提示詞撰寫方式。
DevOps/SRE：壓縮冗長的 CI 日誌、指令輸出與診斷資訊（caveman shrink -- [command]），讓代理程式能在較小的上下文視窗內對事件進行初步分類。
資料/研究科學家：使用 caveman learn 分析代理程式工作階段歷史，量化 Token（即成本）實際消耗的位置，為工作流程調整提供依據。
專案經理：參考基準測試與「誠實數據」文件，在團隊全面部署 Caveman 前評估切合實際的成本降低預期。

6. 快速入門

尋找所需資源
從 docs README.md 開始瀏覽 docs/ 目錄，查閱架構說明、CLI 參考手冊、安全/隱私注意事項及基準測試方法。

安裝 / 整合

# 代理程式 (Caveman 2) — 壓縮輸入
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude   # 或：codex, gemini, aider, hermes, openclaw

# 技能 — 壓縮輸出，安裝至代理程式的技能目錄
npx skills add JuliusBrussee/caveman

貢獻

git commit -s -m "your message"   # 每次提交皆需 DCO 簽署

針對您修改的套件執行相關測試套件（go test ./...、pnpm test 或 pytest），保持 PR 精簡聚焦，並向主儲存庫發起。如有疑問，請寄信至 [email protected] 或在 GitHub 討論區提問。

7. 專案結構

caveman/
├── agents/profiles/       # 代理程式包裝定義（Claude Code、Codex、Gemini CLI 等）
├── integrations/recipes/  # 供應商 SDK 整合範例（LangChain、LiteLLM 等）
├── engine/                # 壓縮引擎與像素模式渲染
├── browse/                # 瀏覽器內容壓縮實作
└── docs/                  # 架構、CLI 參考手冊、基準測試、安全性文件

8. 相關生態系

上游代理程式/平台：Claude Code (Anthropic)、OpenAI Codex CLI、Gemini CLI (Google)、Aider、opencode、Hermes Agent (Nous Research)、OpenClaw —— Caveman 是對這些工具進行包裝，而非取而代之。
互補框架：Vercel AI SDK、LangChain、LiteLLM、CrewAI 及 PydanticAI 均可透過標準 baseURL 設定指向 Caveman 代理程式。
內建第三方元件：內部使用了 pxpipe (MIT)、Spleen 字型 (BSD-2-Clause) 及 GNU Unifont (OFL-1.1 / GPLv2-with-font-exception)，特別是用於像素模式渲染。

9. 授權條款

Caveman 依目錄採用分割授權。

✅ 可在 MIT 授權下自由使用、修改及重新發佈技能、代理程式 SDK、CLI、用戶端 SDK 及應用層面工具。
✅ 可在 BSL-1.1 授權下免費為自有的第一方流量自行託管引擎、代理程式、快取引擎、重寫器、瀏覽功能及 MCP 伺服器。
❌ 未經專案商業授權，不得將 BSL-1.1 涵蓋的元件（引擎/代理程式/MCP 伺服器）作為第三方託管或嵌入式服務提供。
ℹ️ BSL-1.1 涵蓋的程式碼將於 2030 年 6 月 21 日，或各版本發佈後四年（以較早者為準）自動轉換為 Apache-2.0 授權。
ℹ️ GitHub 自身的詮釋資料將授權列為 "NOASSERTION"，因為 MIT/BSL-1.1 分割模式無法對應到單一 SPDX 識別碼——請檢查各目錄中的 LICENSE 檔案以確認實際適用的條款。

10. 常見問題

問：Caveman 是否曾默默損毀或遺失資料？
答：沒有——每個壓縮負載都保留了以內容定址的原始位元組副本，且僅在測量結果確定小於輸入時才會傳送轉換後的資料；否則系統會記錄拒絕原因。

問：我可以只使用壓縮輸出的技能而不使用代理程式，或是反過來嗎？
答：可以。技能（npx skills add JuliusBrussee/caveman）與代理程式（npm install -g @caveman-ai/cli）是獨立的產品，可分別採用。

問：Caveman 支援哪些程式設計代理程式？
答：原生包裝涵蓋 Claude Code、OpenAI Codex CLI、Gemini CLI、Aider、opencode、Hermes Agent 及 OpenClaw，總計可觸及超過 30 種代理程式，包括可透過 baseURL 設定的框架。

問：我可以為自己的團隊自行託管代理程式/引擎嗎？
答：可以，根據 BSL-1.1，為第一方流量自行託管是免費的；僅在將其作為託管或嵌入式服務提供給第三方時才需要商業授權。

問：基準測試數據（65%、33.2%）從何而來？
答：請參閱 docs/HONEST-NUMBERS.md 與 docs/WRAP-BENCHMARK.md，其中區分了本機推論的估算值與獨立固定的基準測試結果。

11. 快速連結

儲存庫：https://github.com/JuliusBrussee/caveman
文件：https://github.com/JuliusBrussee/caveman/tree/main/docs
貢獻指南：https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md
討論 / 聯絡：儲存庫上的 GitHub Discussions，或 [email protected]

12. 總結

Caveman 為 AI 程式設計代理程式提供了一種實用的方法，使其能在不遺失任何重要資訊的前提下減少讀寫量——結合了使輸出更簡潔的技能與壓縮輸入的本機代理程式，兩者皆有位元組級精確恢復的保證。對於使用 Claude Code、Codex、Gemini CLI 或類似工具進行長時間代理式程式設計工作階段的開發人員與團隊而言，它最具價值，能在不犧牲精確程式碼、錯誤訊息或日誌的情況下，顯著降低 Token 花費。