caveman CLI 深度解析caveman-ai/cli 如何把编码 Agent 接入可恢复压缩与诚实计量【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman本文以packages/cli/README.md为主体系统讲解caveman-ai/cli提供的caveman别名cave命令行它如何包裹wrapClaude Code、Codex 等编码 Agent使其 LLM 流量经过本地计量与可恢复的上下文压缩如何区分「npm 只装 JS 前端、重活交给配套 Go 二进制」的架构以及 Bedrock/Mantle 两条传输通道、诚实性规则honesty rules和 Agent 原生集成的完整用法。读完后你将能独立完成安装、wrap、诊断doctor/setup、Bedrock 环境配置与 Agent 原生集成的全部操作并理解每条命令背后的实现证据。一句话定位wrap不是插件cavemanCLI 的核心动作只有一个词wrap包裹。它不改写 Agent 本身而是把受支持编码 Agent 的模型流量重定向到 caveman 的本地/托管网关从而获得两件事——本地用量计量metering与可恢复的上下文压缩recoverable context compression。README 给出的四个核心入口caveman claude # shorthand for caveman wrap claude; bootstraps signed runtime on first TTY run caveman learn # interactive local Setup Score grouped top moves caveman setup # show which companion binaries are installed caveman stats # local spend, savings labeled inferredcaveman claude是caveman wrap claude的简写形式在首次交互式TTY运行时它会自动引导bootstrap签名后的运行时二进制然后继续同一条命令启动 Agent。caveman learn是一个交互式体检命令显示动画进度、紧凑结果卡片并提供键盘菜单在「查看实现」「完整详情」「可视化报告」之间切换。常用变体--plain稳定的紧凑纯文本输出适合 diff 和脚本日志--all列出所有 sink 与 detector id而不只是 Top 项--json面向自动化的 JSON 输出caveman learn implement [claude|codex] --prompt focus直接打开一个 Agent让它逐条one by one审查并落地修复建议。Agent 路径在 learn guide 缺失时会先安装现成的 guide绝不编辑 load-bearing承重性结论且每次编辑前都会先询问。caveman setup展示已安装哪些配套二进制caveman stats展示本地开销与节省——注意 README 特意强调 savings 一律标记为inferred推断值这是下文「诚实性规则」的一贯立场。架构本质npm 包只装 JS 前端重活在 Go 二进制里这是理解整个 CLI 设计的关键一节。README 明确声明原文见 packages/cli/README.mdThis npm package shipsonly the JavaScript front-end— one CLI entrypoint plus a lazy 25 KB interactive-learn chunk, with zero runtime dependencies.这一点可以直接从 package.json 得到源码级印证bin字段同时注册caveman与cave两个命令都指向dist/index.jsdependencies: {}——运行时零依赖devDependencies 仅有clack/prompts、esbuild、typescript等构建/开发工具engines要求node 22.13构建脚本build由scripts/gen-binaries.mjs、gen-wedge-installer.mjs、compile-registries.mjs等生成器驱动产物dist是唯一发布内容files字段。真正的重活——压缩、计量、流式恢复、浏览——由六个配套 Go 二进制承担二进制驱动的命令面caveman-proxystart·wrap·stats—— 本地压缩 诚实计量caveman-enginecompress·shrink·retrieve·toon·evalscaveman-mcpAgent 侧恢复使流式请求也能被压缩cavemem本地 remember · recall · learned-context 卸载caveman-browse压缩后的页面快照可选caveman-shrinktools compress catalog—— 工具 schema 压缩、lint 与恢复可选这些 Go 源在仓库内各成模块例如 proxy/README.md 对应的网关实现、engine/ 下的压缩器、mcp/ 下的 MCP 服务器、mem/ 下的本地记忆库、browse/README.md 与 shrink/README.md。npm 包与 Go 二进制是「前端 后端」的分离架构CLI 负责交互、配置注入与环境编排二进制负责数据面。二进制缺失时的降级契约README 定义了一条重要的行为契约首次交互式本地 wrap 时caveman agent会安装签名后的运行时 bundle 并继续同一条命令显式的CAVEMAN_*_BIN覆盖与非交互运行保持原样不自动安装若二进制缺失受影响命令显式降级为 pass-through直通什么都不压缩、savings 报 0并给出解释原因的警告。caveman setup用来查看什么能工作、如何修复缺失部件。唯一的例外是wrap本身它把 Agent 的ANTHROPIC_BASE_URL/OPENAI_BASE_URL指向 proxy所以没有 proxy 在监听时Agent 请求会直接路由失败而不是直通。交互式 wrap 会捕获这种情况并提供「直接启动 Agent」的选项非交互式 wrap 打印警告后仍然启动——因此脚本/CI 调用者必须自己确保 proxy 已启动或使用--no-proxy。这条「fail loud大声失败而非静默直通」的设计与 pass-through 降级形成互补数据面宁缺毋滥控制面不阻塞。获取二进制签名下载的原子安装常规安装只有两步npm i -g caveman-ai/cli caveman claude首次交互式 wrap 会下载带密钥签名的 release 产物校验 checksum manifest 以及每一个 SHA-256原子化安装到~/.caveman/bin然后启动 Agent。手动安装/修复用caveman setup --install。签名材料在仓库中可以直接查证BINARY_SIGNING_PUBKEY.pub是发布校验使用的公钥BINARY_RELEASE描述二进制发布约定均位于 packages/cli/BINARY_SIGNING_PUBKEY.pub、packages/cli/BINARY_RELEASE。贡献者也可以从源码构建macOS/Linux 用./scripts/install-local-cli.shWindows 用pwsh -File scripts/install-local-cli.ps1见 scripts/install-local-cli.sh 与 scripts/install-local-cli.ps1。二进制查找顺序为CAVEMAN_*_BIN 环境变量覆盖 → PATH → ~/.caveman/bin这一查找链有专门的回归测试tests/caveman-bin-resolution.runtime.mjs 与 tests/agent-binary-probe.runtime.mjs 分别覆盖解析与探测逻辑。Bedrock 传输显式选择 Claude Code 的原生 Runtime 通道当 Claude Code 配置为走 Bedrock 时caveman 提供一条显式的原生 Runtime 通道而非模拟 Anthropic 协议CAVEMAN_WRAP_PROVIDERbedrock \ AWS_REGIONus-east-1 \ AWS_BEARER_TOKEN_BEDROCK… \ caveman wrap claude也支持 IAM 凭据形式AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY及可选AWS_SESSION_TOKEN。Mantle 保持 opt-in通过CAVEMAN_BEDROCK_ENDPOINTmantle开启——README 特别强调它是独立的 Bedrock endpoint 契约不是普通 Anthropic 流量的别名。两者的 URL 差异Runtime 使用带归因的/bedrock基址Mantle 使用/bedrock/anthropic因为 Claude Code 会向 Mantle 覆盖值原样追加/v1/messages。源码实现applyClaudeBedrockWrap这一节的全部行为在 packages/cli/src/index.ts 中有对应的实现函数applyClaudeBedrockWrap约 L8584-L8634可以直接核对显式触发只有agent.id claude且CAVEMAN_WRAP_PROVIDER归一化后为bedrock才生效默认 Claude profile 仍走 Anthropic 线协议endpoint 校验CAVEMAN_BEDROCK_ENDPOINT只接受runtime默认或mantle其他值直接抛错CAVEMAN_BEDROCK_ENDPOINT must be runtime or mantle通道互斥先删除继承自 shell 的各类旧路由变量ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_USE_BEDROCK、ANTHROPIC_BEDROCK_BASE_URL、CLAUDE_CODE_USE_MANTLE等保证恰好一个 Claude Code provider 通道处于活动状态Mantle 分支设置CLAUDE_CODE_USE_MANTLE1与CLAUDE_CODE_SKIP_MANTLE_AUTH1并把ANTHROPIC_BEDROCK_MANTLE_BASE_URL指向gateway/…/bedrock/anthropic——源码注释明确解释「Claude Code 会向该覆盖值原样追加 /v1/messages而 Caveman 的 Mantle 适配器路由是 /bedrock/anthropic/v1/messages」Runtime 分支设置CLAUDE_CODE_USE_BEDROCK1与ANTHROPIC_BEDROCK_BASE_URL指向带归因的/bedrock路径。托管模式下的自定义头合并当网关 URL 由 Caveman 托管managed时wrap 会向 Claude Code 文档化的ANTHROPIC_CUSTOM_HEADERS中恰好合并一条x-cave-api-key: CAVE_API_KEY保留无关的自定义头并替换任何大小写变体过时的同名头。上游凭据的注入规则若存在AWS_BEARER_TOKEN_BEDROCK同时以x-cave-upstream-key合并进去否则完整的 IAM 三元组编码为AWS_ACCESS_KEY_ID:AWS_SECRET_ACCESS_KEY[:AWS_SESSION_TOKEN]两者同时存在时 Bearer 优先过时的x-cave-upstream-key变体被移除使其无法覆盖 stored 凭据换行符或不完整的 IAM 二元组会在启动前失败——对应实现中bedrockUpstreamCredentialFromEnvpackages/cli/src/index.ts 约 L8570-L8575在缺AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY之一时直接抛错managed 路径对CAVE_API_KEY同样做了/[\r\n]/换行校验约 L8618。一个关键限制值得记住Runtime 通道仍然使用 Claude Code 文档化的 AWS 凭据链没有受支持的CLAUDE_CODE_SKIP_MANTLE_AUTH对应物。对于「凭据仅由服务端注入stored-only」的托管网关场景应选择 opt-in 的 Mantle 通道其网关鉴权绕过gateway auth bypass是有文档记载的。本地非托管Bedrock wrap 则不添加任何 Caveman 网关头保持继承的 AWS 环境。README 还诚实标注了验证边界这条基于自定义头的接缝header-backed seam已有仓库级测试而「真实 Claude Code → AWS 的冒烟」仍是发布门禁release gate。测试即 tests/bedrock-wrap.runtime.mjs其中可验证Runtime 通道设置CLAUDE_CODE_USE_BEDROCK1且ANTHROPIC_BEDROCK_BASE_URL渲染为http://127.0.0.1:8787/w/claude/bedrock带 agent 归因前缀/w/claude/bedrock同时AWS_REGION、AWS_BEARER_TOKEN_BEDROCK原样继承ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN被清除managed Runtime 场景下CAVE_API_KEY经ANTHROPIC_CUSTOM_HEADERS传递且既有的X-Trace-Id等无关头被保留。诚实性规则Honesty rules数字如何标注README 用一小节专门规定了计量口径这是 caveman 与「省钱宣传型工具」的分界线本地节省永远标记为inferredverified_savings在优化器optimizer以 active 模式处理真实流量之前保持 0可恢复压缩有损变换lossy transforms在替换前保存原始内容缺失安全恢复路径、解析失败、或输出不比原文更小时原样直通且不计任何节省record模式是字节保持byte-preserving的需要联网的动词login、plan、score、costs等通过 HTTP 与 Caveman Cloud 通信不需要任何本地二进制。遥测导入的治理边界联网遥测的导入归在既有的cloud audit治理动词之下caveman cloud audit import --format langfuse traces.json caveman cloud audit eval-import evidence.jsonl --dry-run caveman cloud audit eval-import evidence.jsonlEval JSONL 每行接受一个规范的外部证据external-evidence对象单批上限 1,000 条 / 4 MiB。服务端盖上 org/project、observedbasis、external_observedauthority 三个戳导入的证据不能批准 rollout也不能铸造 verified savings——再次体现「证据只进不出权限」的边界。Agent 原生安装一次写入完整集成setup --agent-native把完整的原生集成写入 Codex 或 Claude Code本地路由、生命周期 hooks、architecture-first Core、恢复 MCP、项目级只读工具以及 setup/discovery/review/optimization/management 技能caveman setup --agent-native codex # or caveman setup --agent-native claude安全模型的关键点写入 Agent 配置的是 MCP 命令不是访问令牌。运行时请求复用caveman login的凭据存储并仍经过 control-api 鉴权、项目 scope、RBAC、审计与租户隔离。只读工具read tools暴露结构化报告、Cave Plan、trace 元数据/spans 与实验证据Agent MCP故意不暴露任何生命周期变更能力——control-api 需要服务端权威的状态迁移与证据门禁同理面向 Agent 的 CLI 实验命令也是只读的。Core可独立开关的行为层Core 改变编码行为但可独立控制关掉 Core 后压缩、恢复、遥测继续进行caveman tools config get think.core caveman tools config set think.core off caveman tools config set think.core oncaveman doctor codex/caveman doctor claude可查看当前 Core 状态、来源、profile 与 pack 版本。注意两点行为边界配置变更影响之后的 hook 事件要清除已送入模型上下文的 Core需开新的 Agent 会话Aider 的浅层、静态 Core 读取无法应用think.corecaveman disable aider会将其移除。caveman disable agent移除原生路由/hooks但保留无关的宿主配置编辑。安装的可恢复性journal 与回滚Agent 原生安装在写入前会预检宿主/运行时要求用 journal日志账本记录 bundle 所有权校验已装组件失败时回滚。重复运行会收敛 journal 所持有的漂移。彻底移除只删 bundle 自有部件并还原先前 skill/MCP 的原始字节caveman setup --agent-native codex --remove安装前可以先检查caveman tools skills list --json caveman tools skills preview caveman-evidence-review caveman tools skills install --suite agent-native --agent codex --no-pixel caveman tools mcp install codex --server caveman-cloud第三方 Skill 的像素化Pixel转换tools skills add可以安装任意第三方 skill经由官方 Skills CLI然后自动将其指令正文存储为 profitable pixel pagescaveman tools skills add mattpocock/skills --skill tdd --agent codex -y caveman tools skills add https://github.com/vercel-labs/agent-skills --agent claude-code --global -y行为契约GitHub 简写、Git/GitLab URL、直接 skill URL、本地路径以及上游--skill/--agent/--global/--list/--all标志原样透传像素化时 Caveman 强制上游 copy 模式只转换新增或变更的 Claude Code/Codex skill保留SKILL.orig.md以便字节级精确还原每次调用报告按inferred标注的估计 token 降幅--no-pixel保持上游纯文本行为第三方指令与资源按提供状态安装Caveman 不做安全审查官方 Skills CLI 的遥测行为同样适用可用DISABLE_TELEMETRY1在上游关闭遥测。README 附了一条带日期的本地冒烟数据并刻意限定了其解释边界在 Matt Pocock 的 35-skill 仓库上27 个 skill 被转换、8 个安全保留为纯文本对每个被转换 skill 各调用一次的总和为 32,314 → 9,537 估计 token−70%inferred。README 明确声明这是估算器输出不是 provider 报告的账单也不是 skill 质量基准。小结caveman-ai/cli的设计可以用三条主线概括且每一线都有仓库内证据可查薄前端 重后端的分工npm 包运行时零依赖package.json 的dependencies: {}压缩/计量/恢复全部落在caveman-proxy、caveman-engine、caveman-mcp、cavemem、caveman-browse、caveman-shrink六个 Go 二进制上二进制查找遵循CAVEMAN_*_BIN→PATH→~/.caveman/bin可验证的传输契约Bedrock Runtime/Mantle 双通道在 packages/cli/src/index.ts 的applyClaudeBedrockWrap中显式实现并互斥托管模式经ANTHROPIC_CUSTOM_HEADERS传递网关与上游凭据全部行为由 packages/cli/tests/bedrock-wrap.runtime.mjs 回归诚实口径本地节省永远inferred有损压缩必须可恢复、否则原样直通不计节省外部证据导入不能铸造 verified savings——数字的每一个标签都有明确边界。如果你是脚本/CI 用户记住wrap的失败语义proxy 未启动时路由直接失败非交互模式仍会启动并只打印警告如果你是 Agent 集成用户从caveman doctor agent与caveman tools skills list --json的预检入口开始是风险最低的验证路径。【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考