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；未推断任何额外功能。