caveman 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

caveman 是 JuliusBrussee 开发的面向编码代理的上下文压缩工具，项目主要使用 Go 实现，并提供技能（Skill）、本地代理（Proxy）、压缩引擎（Engine）、浏览工具和代理开发套件等多个独立安装路径。仓库描述为“why use many token when few do trick”，核心目标不是更换现有代理，而是减少代理输出以及发送给模型提供方的输入内容。

根据提供的 GitHub 仓库元信息，项目拥有 98,516 个 Star、5,699 个 Fork，默认分支为 main，仓库语言标记为 Go，仓库元信息中的许可证字段为 NOASSERTION。README 同时说明仓库存在 MIT 与 BSL-1.1 的许可边界，因此实际使用和分发时不能只依据 GitHub 元信息中的单一许可证字段。

“Original skill made agents say less. Caveman 2 makes them read less too.”
来源：README

定位与目标用户

本项目定位在已有编码代理之下，承担提示词风格控制和上下文输入压缩职责。它不是一个独立的通用模型服务，也不是要求用户重写代理逻辑的框架；README 明确描述了“Keep your agent. Brain big. Context small.”这一使用方向。

目标用户首先是已经使用 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline、Copilot 或其他兼容技能安装机制的开发者。对于只关心回复更短的用户，技能安装路径不要求账户、代理、Go 工具链或代码修改；对于还希望压缩工具模式、文件、日志、历史和技能正文等输入的用户，则需要进一步使用 Caveman Proxy。

• 希望减少编码代理回复中的解释性冗余，但保留代码、命令和错误信息精确性的个人开发者。
• 需要控制上下文输入规模，并愿意在本机运行代理、引擎和相关工具的工程团队。
• 准备基于 Caveman 原生运行时创建 TypeScript 代理项目的开发者。
• 需要通过本地 Chrome 驱动把浏览能力以 MCP 工具形式提供给代理的用户。

核心功能

核心能力分为“减少输出”和“减少输入”两层。两层可以独立安装，因此用户可以先启用技能，再根据上下文成本和本地工具需求选择 Proxy、Browse 或 Agent SDK。

代理回复压缩：Caveman Skill

技能通过提示词和命令改变代理的表达方式，使回复更简洁。README 给出的 React 示例中，普通代理示例为 69 个 token，Caveman 示例为 19 个 token；示例保留了“使用 useMemo 包裹对象”的具体修复建议。

技能的触发方式包括自动激活和显式命令。用户可以输入 /caveman，也可以使用 /caveman lite、/caveman full、/caveman ultra、/caveman wenyan-lite、/caveman wenyan-full 或 /caveman wenyan-ultra 选择强度；输入 /caveman off 或 normal mode 可关闭该模式。

输入压缩：Caveman Proxy 与 Engine

Caveman 2 的新增方向是减少代理向模型提供方发送的输入。README 列举的输入范围包括工具模式、文件、日志、历史和技能正文；Proxy 位于已有代理之下，在提供方调用前处理输入，Engine 负责压缩，并保存被移动的字节以支持精确恢复。

从资料可以确认的调用链是“现有代理 → Caveman Proxy → 提供方调用”，但仓库资料没有给出完整通信协议、默认监听端口、配置文件格式或每一种输入类型的具体压缩算法。部署这些组件时，应以最新 README、安装器输出和仓库对应文档为准。

子代理和命令工具

技能安装还提供 cavecrew-investigator、cavecrew-builder 和 cavecrew-reviewer 三种压缩后的子代理预设。根据命名和 README 说明，它们分别面向定位代码、编辑代码和审查代码的工作环节；资料没有进一步披露其完整提示词、输入输出协议或权限模型。

/caveman-commit 用于生成简洁的 Conventional Commit 消息，/caveman-review 用于生成单行、可执行的审查发现，/caveman-compress <file> 用于压缩 Markdown 记忆文件并备份原文件，/caveman-stats 用于在 Claude Code 中查看本地会话 token 使用量和估算节省量。

浏览压缩与 Agent SDK

Caveman Browse 是随 caveman setup --install 提供的本地 Chrome 驱动，代理通过 MCP 工具访问它。README 明确指出该能力需要 Chrome，命令形式为 caveman browse <url>；资料没有给出浏览器配置字段、登录态存储方式或网络访问白名单。

Agent SDK 提供一个基于原生 Caveman 运行时的 TypeScript 代理项目创建入口。项目资料给出的客户端安装方式是 npm i @caveman-ai/sdk 和 pip install caveman-sdk，但没有提供 SDK 的接口签名、认证配置或示例业务代码。

系统架构与关键模块

从 README、package.json 和 go.mod 可以确认，项目同时包含 Node.js 安装器生态和 Go 运行时模块。安装器负责发现本机代理并部署技能；Go 模块承载 Proxy、Engine、浏览、MCP、压缩、记忆等与运行时相关的目录，许可证文件则对这些目录作了单独划分。

安装与代理接入层

根目录的 package.json 将包名定义为 caveman-installer，命令入口为 ./bin/install.js，依赖 @caveman-ai/cli。安装器要求 Node.js 18 或更高版本，会查找已经安装在本机的受支持代理，跳过未发现的代理，并允许重复运行；这些行为均来自 README 的安装说明。

运行时压缩层

go.mod 的模块路径为 github.com/JuliusBrussee/caveman，并声明 Go 版本为 1.26.5。依赖中包含压缩库、tokenizer、树结构解析、SQLite、PostgreSQL 驱动、MinIO 客户端以及 Chrome 控制相关库，但资料没有将每个依赖明确映射到具体目录或功能，因此不能据此推断完整模块边界。

许可证中的 Engine-linked 目录包括 engine/、proxy/、cacheengine/、rewriter/、browse/、mcp/、shrink/、cavemem Go 核心以及 shared/platform/。这份目录清单同时是许可审查和源码集成时的重要边界。

恢复与精确性设计

README 将 Engine 描述为“stores every moved byte for exact recovery”，即保存被移动的字节，以便精确恢复。该表述说明设计重点是压缩后仍能还原原始内容，而不是简单删除文件、日志或工具参数；资料没有说明保存介质、生命周期、索引方式和失败恢复策略。

依赖与运行环境

最小技能路径只需要 Node.js 18 或更高版本，并通过 npx 安装技能。Proxy 安装路径由 @caveman-ai/cli 提供，并会安装签名的本地二进制；README 没有给出这些二进制的单独版本号、校验命令或平台支持矩阵的具体内容。

如果使用 Go 源码模块，需要以 go.mod 声明的 Go 1.26.5 为依据。浏览功能另外需要 Chrome。README 还指出 Windows 技能安装命令要求 PowerShell 5.1 或更高版本。

快速开始

只需要较短回复时，先安装 MIT 许可的技能即可完成最小闭环。该路径不要求账户、Proxy、Go 工具链或改动业务代码，适合先验证代理表达方式是否符合团队习惯。

安装

npx skills add JuliusBrussee/caveman

安装器要求 Node.js 18 或更高版本，并会检测本机已经存在的受支持代理。若只使用 Claude Code，也可以按照 README 给出的插件方式安装；资料中还提供了 Gemini CLI、Codex、Cursor、Windsurf 和 Cline 等路径。

运行

在已安装技能的编码代理会话中输入以下命令，显式启用 Caveman 模式：

/caveman

这里的命令由代理解释，不是操作系统 shell 命令。需要控制压缩强度时，可以将其替换为 /caveman lite 或 README 列出的其他模式。

验证

在 Claude Code 中可以执行 README 提供的统计命令，查看本地会话 token 使用量和估算节省量：

/caveman-stats

该统计功能的资料范围仅覆盖“本地会话 token 使用量和估算节省量”，并不等同于提供方账单、全链路成本报表或服务级别指标。验证结果应结合实际任务和代理会话观察，不应将示例基准直接视为所有项目的固定收益。

安装 Proxy 的可选闭环

如果目标是压缩代理读取的输入，而不仅是缩短回复，可以安装 CLI 和本地运行时。README 将该路径标为 BSL-1.1 runtime、MIT CLI，并给出以下命令：

npm install -g @caveman-ai/cli
caveman setup --install
caveman claude

caveman claude 用于包装 Claude Code。资料没有说明该命令的默认端口、进程管理方式、日志目录或代理地址，因此不应在部署脚本中自行假设这些参数。

配置说明

仓库资料没有提供独立的 .env.example、YAML 配置样例、端口配置或 Proxy 参数表。下表列出 package.json 中真实存在的包元数据字段，作用是帮助维护者理解安装器包，而不是把它们误认为运行时可调配置。

Proxy、Engine、Browse 和 MCP 的运行时字段、环境变量、端口、缓存位置及日志级别，官方仓库未提供该信息，建议以最新 README 为准。不要将 package.json 中的包元数据直接当作生产环境配置。

进阶用法

进阶使用的关键是按需求组合安装路径，而不是一次性启用全部组件。技能、Proxy、Browse 和 Agent SDK 均有独立说明，用户可以根据是否需要输入压缩、浏览能力或自建代理来选择。

• 只需简短回复时，使用 npx skills add JuliusBrussee/caveman，并通过 /caveman lite|full|ultra 选择强度。
• 需要减少工具模式、文件、日志、历史和技能正文等输入时，使用 npm install -g @caveman-ai/cli 与 caveman setup --install。
• 需要让代理访问网页时，在已安装 Chrome 的本机执行 caveman browse <url>，并使用 README 所述的 MCP 工具接入方式。
• 需要创建新代理项目时，执行 npm create @caveman-ai/agent@latest my-agent，再按 SDK 文档补充项目代码。
• 需要单独安装某个代理配置时，使用 README 中的 agent profile 参数，例如 -a codex --yes，其中具体代理名称必须替换为本机实际使用的配置。

技能安装器支持重复运行，并会跳过未检测到的代理。README 提供了完整的 30+ agent 矩阵、dry run、参数、验证和卸载说明，但本资料没有展开这些选项的具体命令，因此不在此补写未给出的参数。

性能数据与评测口径

README 中的旧技能基准表统计的是输出 token，十项任务的平均值为普通代理 1,214、Caveman 294，表内给出的平均节省为 65%。该数据属于 README 提供的示例基准，不能直接推导到任意模型、任务、代理版本或完整会话成本。

README 的“Honest number warning”明确指出，技能只缩短输出 token，输入和推理 token 不受影响，而且技能本身每轮会增加约 1–1.5k 的输入 token。因此，只启用技能时，完整会话节省量会小于输出表中的数字。

README 还给出一项 pinned Claude Code benchmark：Caveman 2 的 provider-reported input tokens 减少 33.2%，标识为 benchmark_counterfactual，并链接到仓库内的 docs/WRAP-BENCHMARK.md。该指标与 65% 输出 token 数据衡量的是不同对象，不能混用或相加。

可观测性与运维

项目提供的直接观测入口是 /caveman-stats，它面向 Claude Code 的本地会话，展示 token 使用量和估算节省量。资料没有说明统计数据的保存时长、导出格式、数据清理命令或多用户汇总方式。

Proxy 侧的 Engine 会保存被移动的字节以支持精确恢复，这意味着运维人员需要把缓存或恢复数据视为运行时数据处理范围的一部分。资料未提供默认存储位置、磁盘配额、轮转策略、监控指标、健康检查端点或 SLA；这些内容官方仓库未提供该信息，建议以最新 README 为准。

1. 先在本地测试任务中比较代理原始回复、压缩后回复和实际输入规模。
2. 使用 /caveman-stats 记录会话级观察结果，不将估算值当作账单数据。
3. 启用 Proxy 后确认被压缩内容能够恢复，尤其是代码、命令、错误日志和工具参数。
4. 在团队环境中明确缓存、日志和历史内容的保存责任，资料没有给出集中化运维方案。

安全与合规边界

项目会处理代理上下文中的工具模式、文件、日志、历史和技能正文，并且 Engine 会保存被移动的字节。因此，使用前应把这些内容视为可能包含源代码、内部日志、路径、凭据引用或个人数据的输入边界；资料没有声明自动脱敏、加密存储或数据不出本机的完整保证。

Caveman Browse 使用本地 Chrome 驱动并通过 MCP 工具向代理提供浏览能力。浏览目标、登录态、Cookie、页面内容和网络访问授权应由使用者明确控制；本文只讨论已获授权的本地或测试环境，不提供针对未授权目标的访问、绕过检测或攻击方法。

• 在包含生产密钥、个人信息或受监管数据的项目中，先核对组织的数据处理政策和代理提供方政策。
• 不要把未经授权的网页、账号、内部系统或第三方数据交给 Browse 或代理处理。
• 对 Proxy、Engine 产生的缓存和恢复数据设置与源数据相同的访问控制要求；具体配置项以仓库文档为准。
• 对压缩结果做完整性验证，避免把“更短”误认为“可以删除语义或安全上下文”。

许可证与商用条款

仓库根目录的 LICENSE 文件说明，MIT 许可证覆盖仓库内容，但不包括 LICENSING.md 列出的 Engine-linked 目录。README 将技能、Agent SDK、CLI、客户端 SDK、扩展外壳、contracts、catalog、graders 和 kit 列为 MIT 范围。

LICENSE 文件将 engine/、proxy/、cacheengine/、rewriter/、browse/、mcp/、shrink/、cavemem Go 核心和 shared/platform/ 列为 BSL-1.1 范围。README 进一步说明，BSL 是 source-available，在 Change Date 之前不属于 OSI Open Source。

MIT 部分允许在遵守许可证条件的前提下使用、复制、修改、合并、发布、分发、再许可和销售软件；分发全部或实质性部分时必须保留版权声明和 MIT 许可条件，且软件按“现状”提供。是否可以将具体组件用于商业产品、是否触发 BSL 的额外限制以及 Change Date 如何适用，应按仓库中的 LICENSE、LICENSE.BSL 和 LICENSING.md 判断，以仓库许可证文件为准。

仓库的 LICENSE 版权年份为 2026，版权持有人为 Julius Brussee。GitHub 元信息显示的许可证为 NOASSERTION，与仓库内的分层许可证说明并不矛盾：前者是平台元数据，后者才是本地源码和分发审查应优先阅读的文件。

局限性与已知限制

项目的 token 节省数据存在明确口径限制。65% 是输出 token 基准表的平均值，33.2% 是 pinned Claude Code benchmark 中的 provider-reported input token 指标，技能还会增加每轮约 1–1.5k 输入 token；这些数据不能作为固定成本承诺。

• 技能不减少输入 token 和推理 token，单独启用技能时，完整会话收益会低于输出 token 表的结果。
• 技能可能改变表达长度，但资料没有承诺所有任务都得到相同程度的压缩。
• Proxy 的默认端口、配置文件、缓存路径、日志格式和资源消耗未在所给资料中说明。
• Browse 需要 Chrome，资料没有给出无浏览器环境下的替代实现。
• SDK 的认证、接口签名、版本兼容矩阵和部署拓扑未提供。
• 许可证按目录分层，不能把整个仓库简单视为单一 MIT 项目。

根据本文作者的经验判断，压缩工具在代码、命令、日志和错误信息混合的长上下文任务中，最需要关注的不是字符数量本身，而是压缩后恢复和引用定位是否仍然可靠；该判断属于使用建议，不是仓库声明的基准结论。

适合谁

以下信号同时满足较多时，项目的安装路径与需求匹配度较高。判断应以团队已有代理和数据边界为基础，而不是只看 Star 数量。

• 团队已经使用 README 列出的 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline、Copilot 或其他技能兼容代理，不希望更换代理。
• 主要痛点是代理回复过长，能够接受通过技能命令切换输出风格。
• 代理会反复读取工具模式、文件、日志、历史或技能正文，并且团队愿意在本机运行 Proxy 和 Engine。
• 开发环境具备 Node.js 18 或更高版本；若使用 Browse，还具备 Chrome。
• 项目能够接受 MIT 与 BSL-1.1 的目录级许可审查，并能区分 CLI、技能和 Engine-linked runtime 的使用范围。

不适合谁

以下情况说明直接采用项目需要谨慎评估，或者应先停留在技能路径。资料没有提供面向这些场景的专门保证，因此不应自行补充承诺。

• 要求输入、推理和输出 token 全部同时减少，并把 README 的 65% 当作完整账单节省承诺的团队。
• 无法允许本地缓存、恢复数据或浏览会话接触源代码、日志、历史和网页内容的组织。
• 必须使用单一 OSI 开源许可证覆盖全部运行时目录，不能接受 BSL-1.1 边界的项目。
• 运行环境没有 Node.js 18 或更高版本，且不准备安装或升级运行时。
• 需要官方提供固定端口、SLA、集中监控、认证方案或完整企业支持，而当前资料未提供这些内容的团队。

常见问题与排查（FAQ / Troubleshooting）

排查时先区分“技能没有生效”和“Proxy 没有压缩输入”这两类问题。两者安装命令、运行位置和验证方式不同，混用会导致错误判断。

为什么安装后代理仍然输出很长

先在代理会话中显式输入 /caveman，确认技能是否被启用；README 也提供了 /caveman lite、/caveman full 和 /caveman ultra 等模式。如果仍无变化，应检查安装器是否发现了当前代理，并参考仓库的 INSTALL.md 完成对应代理的验证和卸载检查。

技能是否会减少发送给模型的输入

不会。README 的限制说明明确指出，原始技能只缩短输出 token，输入和推理 token 不受影响；需要输入压缩时，应使用 Caveman Proxy 和 Engine 路径。

为什么完整会话节省量低于 65%

65% 是输出 token 基准表中的平均节省值，且技能本身每轮增加约 1–1.5k 输入 token。完整会话还涉及输入和推理 token，所以不能用输出表直接计算整段会话的实际节省。

Windows 如何安装技能

README 给出的 Windows 命令如下，要求 PowerShell 5.1 或更高版本：

irm https://raw.githubusercontent.com/JuliusBrussee/caveman/v1.10.0/install.ps1 | iex

该命令来自 README 的 Windows 安装说明。若企业环境禁止执行远程脚本，应先按组织安全流程审查脚本内容；资料没有提供离线安装包或内部镜像方案。

Browse 为什么无法运行

README 明确要求 Chrome。可以先确认本机已安装 Chrome，再执行 caveman browse <url>；如果仍失败，默认端口、驱动路径和浏览器启动参数未在所给资料中提供，建议以最新 README 为准。

如何确认使用的是哪种许可证

检查目标文件是否属于 LICENSE 中列出的 Engine-linked 目录。技能、CLI、Agent SDK 和客户端 SDK 等资料列明为 MIT；Engine、Proxy、Browse、MCP、Shrink 与 Cavemem 等目录属于 BSL-1.1 范围，最终以 LICENSE、LICENSE.BSL 和 LICENSING.md 为准。

项目地址与资源

以下链接仅列出项目资料中出现的仓库、官网或相关项目页面，适合用于源码、安装说明和产品文档核查。

• caveman GitHub 仓库
• Caveman 官网与文档
• INSTALL.md 安装说明
• WRAP-BENCHMARK.md 基准文档
• Caveman 技能目录页面
• Caveman Product Hunt 页面