Caveman 产品模型解析：两条本地采用路径、分层架构与证据标签体系

Caveman 是一个面向 AI 编码代理的 token 压缩工具集（项目口号：“why use many token when few token do trick”），它把“减少 token 消耗”这件事拆成了可独立安装的多个层次：从只改变模型输出风格的 response skill，到能压缩模型输入、记录本地用量并提供上下文恢复能力的本地运行时。本文基于仓库中的 产品模型文档 展开，结合 CCR 存储实现、token 计数模块、代理画像注册表 与 安全文档 等源码证据，完整讲解各层的职责、许可证边界、数据流差异以及“证据标签”这一数字溯源机制，帮助你在自己的工作负载上选择最小且可验证的采用路径。

两条本地采用路径

Caveman 提供两条可以独立运行的本地采用路径：

• 安装 response skill：如果你只想要更短的回答，安装 caveman skill 即可。它不压缩任何输入、文件或思考 token，只改变模型的输出风格。
• 安装本地运行时（runtime）：如果你希望减少实际发送给模型的上下文、保留本地用量度量、或给 agent 提供恢复工具，则安装 Engine + 本地 proxy 组成的本地运行时。

两条路径可以互不依赖地单独运行，也可以叠加使用。这种分层设计意味着你不必一次性引入全部组件——可以只装 skill，也可以只接 proxy，按需选择。

层次地图：职责、账号要求与许可证

产品模型文档给出的核心结构是一张层次地图，完整继承如下：

层	职责	需要账号	许可证
Skill、hooks 与 plugins	要求 agent 用更少废话回答，同时保留技术文本	否	MIT
CLI	安装组件、启动 agent、暴露本地命令、连接可选的托管命令	本地命令不需要	MIT
Engine	检测 payload 形状、应用匹配的变换、估算 token 数、存储恢复记录	否	BSL 1.1
本地 proxy	将 provider 请求经由 Engine 路由，写入本地用量记录	否	BSL 1.1
MCP、memory、browser、shrink 二进制	暴露恢复能力与专用本地上下文工具	否	混合，见 LICENSING.md
SDK 与 Agent SDK	为应用代码提供 tracing、上下文组装、工具、evals 与 provider 路由	本地使用不需要账号	MIT
连接命令（connected commands）	访问已认证的托管项目	是	CLI 本身保持 MIT

许可证边界：MIT 与 BSL 1.1 的分界

仓库采用分许可证模型，边界定义在 LICENSING.md：

• 根 LICENSE 是 MIT 许可，附带一段顶层说明，把 Engine 关联目录指向 LICENSE.BSL；
• LICENSE.BSL 是 Caveman Engine 关联代码的 BSL-1.1 正式文本；
• 按目录看，skills/、packages/cli/、packages/sdk/typescript/、packages/sdk/python/、packages/agent/、shared/provider-catalog/ 等采用面（adoption surface）是 MIT；而 engine/、proxy/、mcp/、shrink/、mem/（Go 核心）、shared/platform/ 等 Engine 关联代码是 BSL-1.1。

BSL 代码是 source-available（源码可见），并带有 Additional Use Grant：允许内部评估、本地开发、CI 测试以及第一方自托管生产使用。但若把 Caveman 或其功能作为托管、管理式或嵌入式服务提供给第三方，则需要商业许可。此外，BSL 版本在 2030-06-21 或该版本首次公开分发四周年（以先到者为准）转为 Apache 2.0。产品模型文档因此给出明确提示：在把 Engine 关联功能提供给第三方之前，先阅读 许可证说明。

响应压缩：caveman skill 的工作原理

caveman skill 只改变响应风格：去掉填充词、缩短常见措辞、在更高压缩级别下允许句子片段。同时它严格保护技术内容——代码块、精确错误信息、命令、标识符和技术细节保持原样。

该 skill 定义了六个强度级别，可切换：

/caveman lite|full|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off

默认级别是 full。各级别的变化范围：

级别	变化内容
lite	无填充词/无模糊措辞。保留冠词与完整句子，专业但紧凑
full	去冠词、允许片段、用短同义词。典型 caveman 风格，不做工具调用叙述
ultra	在因果不明确不致歧义时去掉连接词。一个词能表达就不写短语。禁用自造缩写与箭头（→）
wenyan-lite / full / ultra	文言文级别，从半文言到极简文言，压缩的是字符数而非 token 数

skill 的规则里有一些值得注意的细节：

• 禁止发明缩写（cfg/impl/req/res/fn）——tokenizer 会把它们切成和完整词一样的 token，零节省但增加解码成本；同样禁止因果箭头（→）。
• Auto-Clarity 规则：遇到安全警告、不可逆操作确认、多步序列、或压缩本身会造成技术歧义时，自动退出 caveman 风格，用正常语言写清楚，之后恢复。
• 语言保持：始终用用户的主语言回复，只压缩风格不切换语言；技术术语、代码、API 名、CLI 命令一律原样保留。

响应路径的诚实成本

这条路径影响的是模型输出，但它的指令文本本身也消耗输入 token。按 HONEST-NUMBERS.md 的实测口径：skill 规则（约 5 KB 的 SKILL.md）每轮注入上下文，约增加 1–1.5k 输入 token/轮；它对输入 token 的减少是 0%。也就是说，短任务开启 skill 后总 token 可能更高。文档给出的正确比较方式是：对等价任务比较 provider 报告的 usage，而不是只看输出长度。如果固定提示开销超过了输出节省，就该在这个工作负载上关闭 Caveman。

上下文压缩：CCR 恢复序列与本地 proxy

本地运行时改变的是模型输入。agent 往往会反复发送旧的工具结果、日志、文件、schema 和历史记录。Engine 对每个候选内容做分类，并应用内容专属的压缩器（JSON、日志、表格、工具 schema 等各有对应实现，见 engine/compressors/ 目录）。

有损结果的固定四步序列

每一个有损（lossy）压缩结果都遵循同一序列：

1. 把原始字节完整存入 Caveman Context Recovery（CCR）；
2. 返回一个更小的、模型可见的表示；
3. 附带一个可恢复原始内容的 handle；
4. 如果存储、解析或大小检查失败，则原样透传原始字节（pass-through）。

第 4 条是整个设计的底线：任何检查失败都不会破坏数据。CCR 存储的包注释 明确写道：CCR 保存每一次有损压缩的精确原始字节，以 handle 为键，retrieve(handle) 字节级返回原文，"nothing the engine compresses is ever destroyed"。从源码可以看到 handle 是内容寻址的——对原始字节做 sha256，这使得压缩具有幂等性：同一 payload 压缩两次得到同一个 handle 且只存一份。Store 还定义了 ErrBudgetExceeded：当本地存储的 payload 预算被超出时，新的恢复记录在发布有损字节之前就被拒绝，已有 handle 保持完整可检索，调用方必须回退到 pass-through。SECURITY.md 补充了具体数值：CCR 默认保留预算为 512 MiB，可用 CAVEMAN_CCR_MAX_BYTES 调整；CCR 的 SQLite 文件被强制为 0600 权限并拒绝不安全的符号链接路径；已有恢复 handle 永不被淘汰，预算耗尽时新的恢复写入失败、有损变换回退到透传。

本地 proxy：loopback、SQLite 与 inferred 度量

本地 proxy 监听 loopback 地址（caveman start 默认 127.0.0.1:8787），用调用者自己的 provider 凭证转发请求，并把用量写入本地 SQLite 数据库。SECURITY.md 说明：独立 proxy 之所以接受每一个入站请求，是因为“loopback + 单操作员隔离”本身就是安全边界——启动时会拒绝非 loopback 的 --host 和 CAVEMAN_LISTEN 取值。

本地 token 减少数的 basis 一律标记为 inferred。原因在于 engine/tokens/tokens.go 的包注释：Engine 的计数是本地估算，默认计数器是一个真实的离线 BPE tokenizer（OpenAI o200k_base），词表内嵌在二进制里，计数确定性且完全离线；而 provider 的计费计数在下游才是权威值。这也意味着本地度量与 provider 账单可能不一致，两者不能互相换算。

保留现有 agent：wrap 机制与声明式画像

CLI 通过改变子进程的 provider endpoint 来包装（wrap）一个已安装的编码 agent——它不替换 agent 自身的循环，只把子进程流量指到本地 gateway。

七个声明式启动目标

声明式画像（declarative profiles）描述了七个当前支持的启动目标：Claude Code、Codex、Gemini CLI、Aider、Hermes、OpenClaw 和 opencode。画像定义在 agents/profiles/ 下（每个 agent 一个 JSON 文件），由编译器 agents/compile.mjs 按 schema.json 校验后生成 agents/agents.json。从 agents.json 的实际内容可以看到这一“画像是数据而非代码”的设计：

• claude 画像：wire_protocol 为 anthropic-messages，injection.method 为 env，通过设置 ANTHROPIC_BASE_URL={{cave_base_url}} 和 ANTHROPIC_AUTH_TOKEN={{cave_api_key}} 两个环境变量把 Claude Code 指到 gateway；
• aider 画像：wire_protocol 为 openai-chat，注入 OPENAI_API_BASE={{cave_base_url}}/openai/v1；
• codex 画像：wire_protocol 为 openai-responses。

schema.json 中还有几个保证“诚实性”的机制值得留意：wire_protocol 是封闭枚举（anthropic-messages / openai-chat / openai-responses / gemini-generatecontent），未知值会让编译直接失败（“no guessed protocol”）；tested_agent_version 记录画像验证过的确切二进制版本，而 injection_completeness 标签（declarative / builder-assisted / code-only）会被编译器与 CLI 实际 builder 交叉核对，虚报 declarative 会 fail closed。新增一个 agent 支持，本质上只是新增一个 JSON 文件。

应用侧接入：SDK 配方

应用程序也可以通过修改 provider SDK 的 base URL 来使用同一个 proxy。仓库 integrations/recipes/ 下提供了可直接复制的配方，覆盖：Anthropic（Python/TS）、OpenAI（Python/TS）、Google Gen AI、Vercel AI SDK、LangChain、LiteLLM、CrewAI、Pydantic AI、OpenAI Agents SDK 以及 raw HTTP，例如 anthropic-ts.json、openai-py.json、curl.json 等。查看命令：

caveman tools sdk
caveman snippets
caveman snippets openai-ts --app my-service

本地边界与连接边界

本地压缩不需要 Caveman 账号。 登录（sign in）只是增加连接命令（connected commands），并可能持久化一个托管 gateway URL。命令发现（command discovery）刻意把这两个表面分开：

caveman help tools   # 本地命令
caveman help cloud   # 需要认证的命令

两种流量的数据流不同：

• 本地 wrap：请求内容发送给所选模型 provider，CCR 原始字节留在本地磁盘（~/.caveman/ccr.db，属于敏感文件，可能包含 prompt、内嵌凭证和工具结果）；
• 托管 gateway（managed traffic）：作为代理转发时，必然接收请求和响应内容，请求与响应会经 Caveman Cloud 和所选 provider 中转。

SECURITY.md 用一张数据流总结表列出了全部表面（skill/本地 proxy/SDK observe-only/managed gateway/匿名遥测/认证同步）的内容去向，并明确提示“不要把 managed 模式当作 local-only”。另外，匿名 CLI 遥测默认开启但可退出（caveman telemetry off 或 DO_NOT_TRACK=1），且不含 prompt/补全正文。

证据标签：数字是如何被产生的

Caveman 使用一组标签来标识每个数字的产生方式，避免不同来源的数字被混为一谈：

• inferred：本地估算，通常来自离线 o200k_base tokenizer 或目录列表价（即上文 engine/tokens/ 的离线 BPE 计数）；
• provider-reported：模型 provider 返回的 usage 计数器；
• benchmark_counterfactual：在固定方法下得到的配对基准结果；
• verified：一种连接态（connected）证据状态，本地工具永远不会签发它。

关键规则是：这些标签之间不能通过措辞互相转换。一个本地估算即使结果看起来再可信，也仍然是 inferred——它不会“升级”成 provider-reported 或 verified。这条规则保证了所有节省数字都可以追溯到其产生机制，也与 HONEST-NUMBERS.md 的立场一致：只有提交了可审查的原始配对数据并经过独立质量评审，才发布削减数字。

选择最小路径

产品模型文档给出的收尾决策表完整继承如下，建议从其中一层开始：

目标	命令或组件
更短的回答	安装 skill；运行 /caveman
字节级一致的本地计量	caveman wrap --off <agent>
可恢复的本地压缩	caveman <agent>
为支持的视觉模型渲染密集文本	caveman wrap --pixel <agent>
Provider SDK 集成	修改 base URL 或使用 @caveman-ai/sdk
持久化本地记忆	caveman tools mem
压缩的浏览器上下文	caveman tools browse
构建 TypeScript agent	npm create @caveman-ai/agent@latest

最后的建议只有一句话：从一个层次开始，只有当某一层在你工作负载上测得的结果超过其开销时，再加下一层（Start with one layer. Add another only when its measured result clears its overhead for your workload）。这正是整套产品模型的核心方法论——每一层独立可用、独立计量、独立验证，压缩收益必须用 provider 账单级别的 A/B 数据说话，而不是靠标签上的措辞。