Caveman CLI 参考：caveman 命令族、tools 本地工具与 cloud 命名空间的完整使用指南

本文以仓库中的 CLI reference 文档为主体，系统讲解 Caveman 命令行工具（caveman / cave）的命令分组、参数传递规则、本地工具命名空间（tools）、运行时命令（start、setup、wrap）、学习命令（learn）以及云命名空间（cloud），并结合 CLI 入口源码 packages/cli/src/index.ts 和代理入口 proxy/cmd/caveman-proxy/main.go 说明各命令的底层实现。读完后你可以直接复制使用文中命令，并理解每个命令背后的调用链与失败回退策略。

命令体系总览：caveman 与 cave 是同一个程序

caveman 和 cave 两个命令名指向同一个可执行文件——npm 包 @caveman-ai/cli 中 bin 字段同时注册了 "caveman": "dist/index.js" 与 "cave": "dist/index.js"。短别名 cave 适合交互式终端；编写脚本时建议优先使用 caveman，语义更清晰。

查看某个命令在已安装版本上的精确帮助：

caveman help <command>

CLI 参考文档强调：本文解释命令分组与重要行为，而 命令帮助输出才是接受哪些 flag 的最终权威来源。

从源码结构看，命令解析入口是 resolveInvocation：

1. 第一个 token 是 tools 或 cloud 时，进入对应命名空间并在分组内查 handler；
2. 否则在 LEGACY_HANDLERS 中查找顶层命令（wrap、run、start、learn、status、login 等）；
3. 仍未命中且不在保留动词表中时，按 agent 档案（id 或 binary 名）匹配，命中则走 agentShortcut 路径。

因此 caveman claude 与 caveman run -- claude ... 本质上是同一条 wrap/run 调用链，只是入口不同。

主要命令

命令	用途	是否需要账号
caveman <agent>	持久化启用原生集成，然后运行受支持的 agent	否
caveman wrap <agent>	运行一个不持久化宿主配置的一次性包裹会话	否
caveman run -- <command>	通过本地层运行任意命令	否
caveman learn	对本地观察到的改进点进行排序	否
caveman status	显示本地运行时、模式与连接状态	否
caveman login	将安装连接到 Caveman Cloud	是
caveman tools	打开本地工具命名空间	否
caveman cloud	打开已连接服务命名空间	是

受支持的 agent 快捷方式包括：aider、claude、codex、gemini、hermes、openclaw、opencode。

caveman claude
caveman codex --full-auto
caveman run -- my-agent --project .

参数传递规则：agent 名之后的参数原样传给该 agent（例如 codex --full-auto）；caveman run -- 中 -- 之后的参数传给所选命令。

源码佐证：findAgent 先按 id 再按 binary_names 匹配 agent 档案；agent 档案数据编译自 agents/profiles/ 下的 JSON（如 claude.json、codex.json）。wrap 函数 中有几个关键行为：

• 找不到 agent 可执行文件时以退出码 127 结束（与 shell 找不到命令的约定一致），并打印安装提示；
• --pixel 模式对 codex 订阅（subscription）会话暂不支持，会直接报错退出；
• wrap 是“零提交”的试验路径：原生 hooks/MCP/配置只存在于本次子进程的临时宿主包中，持久化集成必须通过显式安装完成。

本地工具命名空间 caveman tools

caveman tools 把使用频率较低的本地命令按“工作类别”分组。分组定义见 TOOL_DISCOVERY：

分组	命令
Think	compress、shrink、toon、convert
Remember	mem、retrieve
Execute	mcp、hooks、browse、skills、sdk
Inspect	stats、trial、evals、config

单独运行 caveman tools 会打印这份分组发现清单（printDiscovery），caveman help tools --all 可显示包含隐藏命令的完整列表。

compress：本地压缩

压缩来自标准输入或文件的内容，压缩在本地完成；有损输出在恢复存储可用时会附带一个 recovery handle。

caveman tools compress < long-context.txt
caveman tools retrieve ccr_0123456789abcdef0123456789abcdef

实现上，compress 先把整个 stdin 读入，然后 spawn caveman-engine compress 子进程，可选 --type <content-type> 指定内容类型，--toon 强制 TOON 压缩（等价于 --type toon）；--type auto 会被归一化为自动探测。如果引擎二进制缺失，compressFallback 会把原始输入原样输出，并向 stderr 打印一份结构化 JSON 报告：ratio: 0、engine: "missing"，明确告知“0% 压缩、直通”，避免把直通误当成压缩成功——这是全文反复出现的 byte-safe（字节安全）原则。

当应用需要一个 HTTP 代理而不是一次性命令时，应改用 caveman start。

compress catalog 子命令是另一个专门的桥接：它把参数原样转发给 caveman-shrink 二进制，用于工具 schema（tool catalog）压缩、lint 与恢复，与命令输出的 shrink 是两条独立路径。

shrink：可恢复的命令输出缩减

shrink 运行一条命令（或读取 --file / stdin 的既有输出），在模型读取之前压缩其 stdout+stderr 合并输出，并保留结构信息与恢复引用。

caveman tools shrink -- my-command --verbose
caveman tools shrink --file output.log
cat output.log | caveman tools shrink --stdin

shrink 实现 支持这些 flag：

• --：其后为要包裹的命令；
• --raw：直通原始输出；
• --stdin：从标准输入读取；
• --type <type>：强制内容类型，默认 terminal；
• --file <path>：压缩一个已捕获的文件。

emitShrunk 的关键约束：输入超过命令上限（默认 8 MiB，可用环境变量 CAVE_MAX_SHRINK_BYTES 调整）时整体拒绝处理、原样直通，而不是部分压缩；引擎不可用或失败时也直通原始输出并输出 ratio: 0 的说明。成功压缩时，输出末尾会附加一行 recovery footer（携带 handle），仅在确实铸造了 handle 时才会打印，绝不输出“伪节省”信息。

toon：结构化数据的紧凑编解码

使用 TOON 对 JSON 进行编解码：

caveman tools toon encode < data.json
caveman tools toon decode < data.toon

toonConvert 转发到 caveman-engine toon encode|decode——引擎是 JSON⇄TOON 转换的唯一权威实现，CLI 不内置 JS 解析器。两个方向在引擎缺失时的降级策略不同：

• encode 降级为字节安全直通：输出仍是合法 JSON，只是没被压缩，并打印警告；
• decode 拒绝执行：无法伪造解码结果，把未转换的 TOON 当 JSON 输出会给下游一个坏负载，因此显式失败。

注意：TOON 编码只在合适数据上才“赢”，最常见的是同质对象数组；它不是字节保持的转换，且转换结果不应再喂回产出另一格式的同一个 agent，否则会使其看到的 token 翻倍。

convert：技能像素化打包

把已安装的受支持 skill 打包为 pixel（像素）形式，供选定 agent 或项目使用。Flag 包括 --agent、--project、--skill、--dir、--density、--dry-run、--revert、--force。在改动大型 skill 树之前，先跑一次 dry run。

mem：本地持久记忆

管理本地持久记忆，操作包括 remember、recall、supersede、history、forget。实现 mem 依赖 cavemem 二进制（Go 实现的 BM25 + 存储，见 mem/bm25.go、mem/store.go）。更完整的用法见 Local tools。

retrieve：按 handle 精确恢复

retrieve 用法为 retrieve <handle> [query]，转发给 caveman-engine retrieve，用于按压缩时铸造的 ccr_* handle 逐字节恢复被压缩内容。

mcp：本地 MCP 注册管理

为检测到的 agent 安装/移除本地 Model Context Protocol 注册。服务器选项包括 recovery、browser、已连接只读 evidence，以及 opt-in 委派工具。

caveman tools mcp install claude --server caveman
caveman tools mcp uninstall claude --server caveman

handler 实现见 index.ts#L217-L227：install/uninstall 从剩余参数中解析目标 agent 与 --server（默认 caveman）。

caveman-mcp 二进制本身通过 stdin/stdout 提供压缩、恢复、统计与 TOON 工具（MCP 协议服务器，见 mcp/README.md 与 mcp/server.go）。

hooks：agent 钩子

安装或检查受支持 agent 的 hooks。hooks 给 agent 原生事件系统附加本地上下文与压缩输出行为，详见 Skills, hooks, and plugins。

browse：通过本地浏览器桥控制 Chrome

caveman tools browse https://example.com "main article"
caveman tools browse act '<element-reference>' click
caveman tools browse eval 'document.title'
caveman tools browse recover '<recovery-handle>'
caveman tools browse close

安全须知：browse eval 在已附加页面中执行 JavaScript，请把表达式当代码对待，只在信任的页面上使用。

skills：技能列表/预览/安装

caveman tools skills list
caveman tools skills preview owner/repository
caveman tools skills install owner/repository

安装外部 skill 前先 preview。

sdk：集成配方

打印或应用受支持 SDK 与 agent 框架的集成配方。配方覆盖 Anthropic、OpenAI、Google Gen AI、Vercel AI SDK、LangChain、LiteLLM、CrewAI、Pydantic AI、OpenAI Agents SDK 以及直接 curl 用法；配方源文件位于 integrations/recipes/（如 anthropic-py.json）。

caveman tools sdk snippet
caveman tools sdk snippet anthropic-py

stats、trial 与 evals

• stats：报告本地压缩与用量记录。实现 stats 本身不依赖数据库，而是委托 caveman-proxy stats 读取 ~/.caveman/ 下的 SQLite 存储，支持 --json。
• trial：用 fixtures 或已配置 provider 演练本地功能。
• evals：运行已安装构建中可用的评测命令。evalsRun 转发到 caveman-engine evals run [--fixtures <dir>]，CLI 自身不携带 fixtures，并透传引擎退出码以便 CI 门禁。

注意：本地观察值不是经过验证的节省。计量与证据规则见 Accounting and evidence。

config：本地功能配置

读取或修改本地功能配置：

caveman tools config path
caveman tools config get think.mode
caveman tools config set think.mode compress

常用键（详见 Configuration）：think.mode（compress/record/pixel）、think.core、execute.mcp（auto/marker-only/true/false）等，且存在环境变量到配置键的映射（如 CAVEMAN_WRAP_MODE → think.mode）。

运行时命令

start：本地回环 HTTP 代理

启动本地 HTTP 代理，默认地址 127.0.0.1:8787：

caveman start

行为细节（start 实现）：

• 目标端口已被监听时不重复启动，直接打印“已有代理在运行”面板并提示 caveman wrap claude 与 caveman stats；
• 找不到 caveman-proxy 二进制时打印安装引导面板（caveman setup --install 或 export CAVEMAN_PROXY_BIN=/path/to/caveman-proxy）并以非零码退出，方便脚本分支判断；
• 解析出的运行模式通过 CAVEMAN_MODE 等环境变量传给子进程，caveman start 始终拥有独立的本地监听器。

代理读取 ~/.caveman/caveman.yaml，除非 CAVEMAN_CONFIG 环境变量指定其他文件；本地运行数据存储在 ~/.caveman/caveman.db（SQLite）。这一点在 Go 侧得到确认：proxy/cmd/caveman-proxy/main.go#L166 执行 config.Load(env.String("CAVEMAN_CONFIG", filepath.Join(home, "caveman.yaml")))，同文件 L806 处 DB 路径可由 CAVEMAN_DB 覆盖，默认 caveman.db；模块头注释明确“在 127.0.0.1:8787 上提供字节安全生命周期，零云端依赖”。

setup：检查或安装本地运行时组件

caveman setup
caveman setup --install
caveman setup --json
caveman setup --agent-native claude
caveman setup --agent-native codex

在 --agent-native 命令上追加 --remove 可移除该集成。

setup 实现 检查六个 Go 二进制（GO_BINARIES）：

二进制	环境变量覆盖	必需	缺失时的降级
caveman-proxy	CAVEMAN_PROXY_BIN	是	wrap 仍能启动 agent，但 LLM 流量不被压缩、不被计量
caveman-engine	CAVEMAN_ENGINE_BIN	是	compress/shrink 直通输入（报告 0%）；toon decode 拒绝执行
caveman-mcp	CAVEMAN_MCP_BIN	是	流式请求直通不压缩
cavemem	CAVEMEM_BIN	是	记忆与自动召回关闭
caveman-browse	CAVEMAN_BROWSE_BIN	否	agent 侧压缩浏览 MCP 工具不可用
caveman-shrink	CAVEMAN_SHRINK_BIN	否	工具 catalog 压缩不可用；命令输出 shrink 不受影响

普通 setup 在必需二进制缺失时以非零码退出，便于脚本门禁；setup --install 只下载带签名、经校验和验证的发行二进制；setup --agent-native <claude|codex> 安装“完整 agent 原生 bundle”（原生集成 + 云 MCP + skill），并写入回滚日志，失败时自动回滚。

wrap：一次性包裹会话

wrap 是 agent 快捷方式的显式形式：

caveman wrap claude
caveman wrap --off codex
caveman wrap --pixel gemini
caveman wrap --workflow review opencode

模式语义：

• 默认模式启用受支持的本地压缩、结构化数据编码（TOON）、恢复与输出缩减；
• --off：运行字节安全的直通记录（byte-safe pass-through recording）；
• --pixel：对配置中列出的模型启用有损的文本转图像上下文传输；
• --workflow：当已安装 profile 支持时选择命名工作流（源码中通过导出 CAVE_WORKFLOW 环境变量传递给子进程与 overlay，见 wrap 函数）。

记录模式（record）从不改变模型可见的请求字节。

学习命令 learn

caveman learn 读取本地观察并排序可能的改进点：

caveman learn
caveman learn --since 7d --sources claude,codex,gemini,opencode,aider
caveman learn --all
caveman learn --repo my-project
caveman learn --json
caveman learn implement codex --prompt "focus on config fixes"
caveman learn apply claude_md_weight:project --dry-run
caveman learn simulate claude_md_weight:project recurring_context:abc
caveman learn applied claude_md_weight:project --fix-kind config_trim --note "approved and re-measured"

行为要点（learn 实现）：

• 输出格式支持纯文本、JSON（--json）与 Markdown（--md）；
• --all 追加所有 sink、已确认结果、按仓库的观察与高级命令提示；
• --repo 在分析前过滤会话；
• apply 准备一个候选项（可加 --dry-run）；simulate 对扫描历史求反事实规模；applied 把已完成且重新测量的修复记入结果存储；
• 子命令还包括 implement、export、reconcile、experiment、savings、scan、report，多数转发到本地 proxy 的 learn 路径；
• 在更强的证据出现之前，一条推荐始终只是“推断的机会”；
• Aider 的扫描因历史是仓库本地的，保持 opt-in：通过 CAVEMAN_AIDER_ROOT 环境变量开启。

云命名空间 caveman cloud

caveman cloud 是账号与网络命名空间，其命令分组（CLOUD_DISCOVERY）覆盖：

• account：whoami、projects、keys、providers、billing；
• evidence：score、costs、plan、traces、experiments、receipts；
• governance：audit、sync、agent。

这些命令要求已连接的安装（caveman login），并可能依赖套餐或组织策略。从源码结构看，云命令都是对控制面 REST 路径（如 /api/v1/reports/cave-score、/api/v1/optimization-proposals）的薄封装，见 CLOUD_HANDLERS。本仓库记录的是客户端行为与公开契约，而非托管端实现细节。

退出码与失败行为

• 命令对非法参数、被拒绝的配置、缺失依赖与操作失败使用非零退出状态；
• setup 在必需二进制缺失时退出码 1；用法错误（commandUsage）以退出码 2 结束；wrap 找不到 agent 二进制时退出码 127；
• 破坏性或语义模糊的本地转换在提供 --dry-run 时应当先跑 dry run（如 convert --dry-run、learn apply --dry-run）；
• 压缩路径在输出不安全或不完整时优先保留原始输入：compress、shrink、toon decode 各自的降级策略（直通、拒绝、报 0%）都在源码注释中作为“honesty rule: byte-safe / no-fake-savings”明确约束，直通结果必然自我说明，0% 永远不会被误读为“压缩生效”。

延伸阅读

• 配置键与优先级：Configuration
• 本地工具（mem/retrieve 等）：Local tools
• 计量与证据规则：Accounting and evidence
• 技能、hooks 与插件：Skills, hooks, and plugins
• 代理与 provider：Proxy and providers
• CLI 包说明与测试：packages/cli/README.md、packages/cli/tests/