Caveman 旨在大幅减少 AI 代理（如 Claude Code、Codex）Token 消耗的工具 | 极客的赛博空间

🧭 核心概念与功能

Caveman 的核心思想是“用更少的 Token 做同样的事”，它提供两种主要产品：

Caveman Proxy（输入压缩）：一个本地代理，在你 AI 代理的请求到达提供商（如 Anthropic、OpenAI）之前，压缩其读取的内容（如 JSON、日志、代码、搜索结果），平均可减少 33.2% 的输入 Token（基于 Claude Code 基准测试）。压缩是可逆的（CCR 机制），原始内容可按需恢复。
Caveman Skill（输出压缩）：一个 AI 代理技能，让代理的回答更简洁（“像原始人一样说话”），同时保持代码、命令和错误信息准确。在示例中，回答 Token 可减少 65%。

两者结合，能在输入和输出两端同时节省成本。此外，它还提供其他工具：

caveman learn：分析你本地的代理历史记录，找出 Token 消耗的“重灾区”并给出优化建议。
Pixel 模式：将繁重的 SKILL.md 提示词文档转换为 PNG 图片，让模型通过视觉读取，减少 token 消耗（实测减少 61%）。
Browse 功能：通过压缩的浏览器可访问性（a11y）树来浏览网页，比 Playwright 的 ARIA 基线节省 129 倍 token。

📦 安装与部署

Caveman 提供了两种主要安装路径，可以任选或组合使用。

方式一：安装 Caveman Proxy（压缩输入，推荐）

这个命令行工具（CLI）会包装你的 AI 代理，并通过本地代理路由流量。

快速安装（推荐）：

1	npm install -g @caveman-ai/cli && caveman setup --install

然后包装你的代理：

caveman claude        # 包装 Claude Code
caveman codex         # 包装 OpenAI Codex
caveman gemini        # 包装 Gemini CLI
caveman aider         # 包装 Aider
caveman opencode      # 包装 OpenCode
caveman hermes        # 包装 Hermes Agent
caveman openclaw      # 包装 OpenClaw

包装过程不会修改你的配置文件，而是通过环境变量或临时配置生效。

一键安装全系列（也包含 Skill）：

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.3.1/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v2.3.1/install.ps1 | iex

方式二：安装 Caveman Skill（压缩输出）

这让你已有的代理回答更简洁。

1	npx skills add JuliusBrussee/caveman

安装后，在你的 AI 代理会话中，可以通过 /caveman 命令切换模式（如 /caveman lite、/caveman ultra），或使用 /caveman off 关闭。

🚀 使用与配置

1. 基本使用

安装并包装代理后，正常使用你的 AI 代理即可。Caveman Proxy 会自动压缩输入，Caveman Skill 会促使代理输出更简练的回答。

2. 分析与优化 (`caveman learn`)

这是理解并优化 Token 消耗的关键命令：

# 分析本地代理历史，生成 Token 消耗报告和优化建议
caveman learn

# 让代理根据建议自动实施优化（需逐项确认）
caveman learn implement

learn implement 会打开你的 AI 代理，并提供优化计划，每项更改需你同意后才会应用。

3. 其他实用命令

查看统计数据：caveman stats 显示 Caveman 对各类内容的压缩效果。
压缩命令输出：caveman shrink -- pnpm test 压缩并测试命令输出（可恢复）。
压缩 Skills：caveman convert 将已安装的 SKILL.md 转换为 PNG 图片（Pixel 模式），减少加载 Token。
试用与对比：caveman trial -- claude 运行一个真实会话的 A/B 测试，然后 caveman trial report 查看对比报告。

⚙️ 高级配置与注意事项

数据隐私：Caveman CLI 会发送匿名使用统计（如运行了哪些命令和 Token 数量），但绝不包含你的提示词、代码或文件路径。可通过 caveman telemetry off 或设置 DO_NOT_TRACK=1 永久关闭。
许可证：请注意项目采用分叉许可证：
- Skill 和表面层：MIT 许可证（宽松开源）。
- 核心引擎、代理、MCP 服务器等：采用 BSL-1.1（Business Source License），这是非 OSI 批准的开源许可证。允许在 2030-06-21 后自动转为 Apache-2.0。自行使用（包括生产环境）免费，但第三方托管或嵌入服务需商业许可。
诚实评估：项目文档特别指出，Skill 主要节省输出 Token。考虑到 Skill 本身会增加约 1-1.5k 输入 Token，在已经简洁的工作负载上可能“净消耗”更多。实际收益需结合场景评估，具体方法见 docs/HONEST-NUMBERS.md。

❓ 常见问题

Caveman 会改变我的答案质量吗？ Proxy 通过可逆压缩保留关键信息；Skill 通过改变表达方式（更精炼）来节省输出，但代码和关键命令保持准确。建议根据任务需要调整压缩强度。
代理包装失败怎么办？ 确保你有对应代理的 CLI 工具（如 claude、codex）并在 PATH 中。检查是否安装了 Node.js 18+。运行 caveman setup 可修复多数环境问题。
Pixel 模式（技能转图片）如何工作？ 该功能需要本地图形库支持，且仅当图片估算的 Token 少于文本时才会应用。可用 caveman convert --dry-run 预览效果。

总结

Caveman 为重度使用 AI 编程代理、希望降低 Token 成本的用户提供了一套实用工具。推荐同时安装 Proxy（节省输入）和 Skill（节省输出）。对于普通用户，通过一键安装脚本或 npx skills add 安装 Skill 是快速体验的方式。对于希望获得更大节省的用户，可以深入使用 Proxy 和 caveman learn 分析优化。部署时请留意其 BSL 许可证，并知悉其节省效果需要在实际工作负载中评估。项目文档详尽，特别推荐阅读其“诚实数字”部分。

项目地址：https://github.com/JuliusBrussee/caveman