JuliusBrussee/caveman

Caveman – AI 編碼助手令牌節省包裝器

概述 – Caveman 是一個輕量級「技能」（規則檔案）和可選的本地代理，位於 AI 編碼助手（Claude Code、Codex、Gemini、Cursor 等）與底層 LLM 提供者之間。其唯一目的是減少模型讀寫文字量，從而降低計費令牌數。

運作原理

• 技能（小石頭） – 一個簡單的提示風格規則，將模型回覆的散文部分改寫為簡潔的「原始人」風格（例如：將 69 個令牌的解釋縮減為 19 個）。程式碼片段、檔案路徑和精確錯誤訊息保持不變。
• 代理（大石頭） – 一個本地 Node.js 程序，攔截從代理到 LLM 提供者的所有請求。它偵測負載類型（JSON、日誌、程式碼、搜尋結果等），並應用自訂壓縮器，保留關鍵資訊（鍵、錯誤行、函式簽名等），同時丟棄重複或雜訊部分。原始負載儲存在 SQLite 快取中，可按需檢索全文。
• 包裝任意代理 – 一個薄包裝器，在啟用代理的情況下啟動目標代理，無需修改代理的設定檔。支援的代理：Claude Code、OpenAI Codex CLI、Gemini CLI、Aider、Kilo Code、Qwen Code、opencode、Hermes、OpenClaw、Pi。

關鍵數字（來自 README）

• 寫入側節省 – 在 10 個典型提示中，技能將輸出令牌從平均 1,214 減少到 294，減少 65%。
• 讀取側節省 – 在 54 次 Claude Code 基準測試中，代理將輸入令牌從 885,793 減少到 591,673，整體減少 33%（某些情況，如純 HTML 頁面，略有增加）。
• 壓縮率 – JSON 負載縮小 70-90%，日誌 85-95%，程式碼 40-70%，差異 60-80%。

安裝

1. 僅技能 – 透過 skills CLI 的一行命令：

   npx skills add JuliusBrussee/caveman
   

   然後在代理內呼叫 /caveman（如果代理未自動載入，則輸入 /caveman）。
2. 代理 – 全域 npm 安裝和設定：

   npm install -g @caveman-ai/cli && caveman setup --install
   caveman claude   # 或 codex、gemini 等
   

   還提供了 macOS/Linux 的完整安裝腳本（install.sh）和 Windows PowerShell 的（install.ps1）。

典型工作流程

1. 執行 caveman <agent>（或 caveman wrap <agent>）以啟用代理啟動所選編碼助手。
2. 當代理向 LLM 請求幫助時，代理會在上游傳送前壓縮大型上下文（日誌、差異、JSON）。
3. LLM 的回覆由技能後處理，將冗長解釋轉換為簡潔句子（程式碼保持不變）。
4. 使用以下輔助命令：
   • /caveman-commit – 產生簡潔的 Conventional Commit 訊息
   • /caveman-review – 產生單行程式碼審查評論
   • caveman compress <file> – 在本地壓縮大型 Markdown 檔案
   • caveman stats – 檢視目前會話的令牌使用統計
   • caveman learn – 分析磁碟上的過去會話，並建議令牌浪費發生的位置

為什麼使用

• 成本降低 – 如果按令牌計費（例如 Anthropic、OpenAI），減少輸入和輸出可以顯著降低帳單，尤其是在處理大型日誌或差異的長時間偵錯會話中。
• 速度 – 負載更小意味著傳輸資料更少，回應時間更快。
• 隱私 – 代理將原始資料儲存在本地；僅壓縮版本傳送給提供者。

注意事項和限制

• 技能僅縮短散文；它不會減少模型推理或代理無法壓縮的輸入上下文所花費的令牌。
• 壓縮會增加自身開銷（每輪約 1-1.5k 輸入令牌），這可能會抵消已經簡潔互動的節省。
• 某些負載類型（例如純 HTML）可能因壓縮器可減少的部分很少而出現淨增加。
• 該工具是一個「包裝器」，不會修改底層代理的程式碼，但每個支援的代理需要 Node.js 22+ 和相容的 CLI。
• README 指出，令牌節省聲明基於基準測試，實際節省可能有所不同。建議使用 caveman stats 或自訂 A/B 測試進行測量。

授權 – 技能元件採用 MIT 授權，永久免費。代理執行時採用雙重授權（MIT + BSL-1.1）。

---

以上所有細節均直接來自倉庫的 README；未推斷任何額外功能。