Caveman 本地工具集：MCP 压缩服务、Cavemem 记忆、浏览器桥接与双路 Shrink 压缩器

2026-09-04 14:04:25作者：尤峻淳Whitney

Caveman 内置一组本地工具，覆盖「上下文压缩恢复、项目记忆持久化、浏览器语义快照、超大命令输出压缩」四个高频场景，全部可在无 Caveman 账号的纯本地环境运行。本文以 docs/technical/local-tools.md 为核心，结合 mcp、mem、browse、shrink 四个模块的源码与 README，逐项说明工具用途、命令参数、容量上限与可恢复性边界，帮助你把 Caveman 的压缩能力接入现有 Agent 工作流并理解其底层保障机制。

一、MCP Server：五类压缩工具接入任意 Agent

Caveman 的 MCP 服务器 caveman-mcp 通过标准输入输出（stdio）传输，链接 Caveman Engine 进程内实现，本地-only（不发起任何网络连接）且inferred-only（从不声明 verified 节省量）。注册方式：

caveman tools mcp install        # 向已检测到的 Agent 注册恢复服务器
caveman tools mcp uninstall      # 移除注册

直接服务器二进制 caveman-mcp 与任意 MCP 主机通信，Claude Code 侧配置示例（见 mcp/README.md）：

// .mcp.json / claude mcp config
{
  "mcpServers": {
    "caveman": { "command": "npx", "args": ["-y", "caveman-mcp"] }
  }
}

MIT 许可的 npm 启动器首次运行会下载匹配的 BSL-1.1 二进制，验证签名校验和清单及工件 SHA-256，缓存至 ~/.caveman/bin，无需 Go 工具链或全局安装。已有审阅过的二进制可通过 CAVEMAN_MCP_BIN=/path/to/caveman-mcp npx caveman-mcp 直接指定。

五类工具及其契约

工具	输入	返回
`caveman_compress`	`input` (string)	压缩文本、推断 `ratio`、`recovery_handle`（直通时为 null）
`caveman_retrieve`	`recovery_handle` (string)	字节精确的原始内容；未知句柄返回错误
`caveman_stats`	—	会话合计：压缩前后 token、`ratio`、`basis:"inferred"`、`scope:"session"`
`caveman_toon_encode`	`input` (JSON 字符串)	显式 JSON→TOON 结果含大小；不可编码时直通并附注
`caveman_toon_decode`	`input` (TOON 字符串)	解码后的 JSON；非法 TOON 返回错误

关键保证：压缩是有损但可逆的（S4 级别）——每一次丢弃都可经 caveman_retrieve 恢复；不可压缩或格式错误的输入以 ratio:0 原样直通，从不报错。MCP 传输为本地进程 I/O，由宿主 Agent 决定何时允许调用工具，应将其工具权限配置得尽可能窄。

二、Cavemem：基于 SQLite + BM25 的持久化项目记忆

Cavemem 把持久项目事实存入 SQLite，用本地 BM25 文本排序召回。它解决的是「跨会话记住关键事实、且召回结果可压缩、可恢复」的问题。

核心操作

caveman tools mem remember "fact"     # 写入一条事实
caveman tools mem recall "query"      # 按查询召回（默认返回当前有效事实）
caveman tools mem supersede <id> "replacement"  # 用新值取代旧事实
caveman tools mem history <id>        # 查看某事实的取代历史
caveman tools mem forget <id>         # 删除

独立构建：go build -o cavemem ./mem/cmd/cavemem。裸二进制无参数运行时直接在 stdio 上跑 MCP 服务器。

参数与预算语义

默认召回预算 2000 推断 token：源码见 mem/store.go 的 const DefaultTokenBudget = 2000。召回打包最多消耗 2000 推断 token。
0 表示无限制：CLI、MCP、JS、Python 调用方可显式请求 token_budget: 0 关闭上限；省略该参数绝不会解除上限。例如 ./cavemem recall "full migration context" 5 0。
默认排除已被取代事实：召回默认只返回当前事实；history 保留本地、可审计的完整取代链。
每次压缩召回命中都携带 recovery_handle：被压掉的细节保持可恢复。

保证与实现事实

字节安全写入：原始文本在任何处理前先行落库，记忆永不丢失。
离题查询宁可召回空也不猜测（保守阈值，见 mem/bm25.go 的 BM25 排序）。
记忆是本地持久化，不是模型训练；记住的陈述可能错误或过时，来源与取代元数据帮助调用方判断其时效。
计数均为推断（inferred），组件从不声明 verified 节省。
Go 核心与二进制为 BSL 1.1；薄 JS/Python 客户端（mem/js/index.mjs、mem/py/cavemem.py）为 MIT，把文本经 stdin 送入二进制（规避 OS 参数长度限制）；超大的 remember 以退出码 65 结束，两个客户端都导出 MEMORY_TOO_LARGE_EXIT_CODE 便于调用方无需解析 stderr 即可分支。

import { remember, recall, supersede, history, forget } from "cavemem"; // js/index.mjs
await remember("…"); await recall("…", 5, 2000); await recall("…", 5, 0); // 0 = unlimited

import cavemem                                            # py/cavemem.py
cavemem.remember("…"); cavemem.recall("…", limit=5, token_budget=2000)

三、Browser Bridge：CDP 语义快照替代截图

浏览器桥接 caveman-browse 通过 Chrome DevTools Protocol 附着到 Chrome，读取 Accessibility.getFullAXTree，经 Caveman 引擎的强制-only a11y 压缩器压缩 AX 负载，返回可操作的元素引用。它暴露四个工具：browser_snapshot、browser_act、browser_eval、browser_recover。

caveman tools browse https://example.com "pricing"  # 带 query 过滤的快照
caveman tools browse act '<reference>' click         # 对元素执行动作
caveman tools browse eval 'document.title'          # 求值 JavaScript
caveman tools browse recover '<handle>'             # 恢复字节精确原始 AX 负载
caveman tools browse close                          # 关闭隔离 Chrome

构建：go build ./browse/cmd/caveman-browse；直接 CLI 助手：

caveman-browse snapshot http://127.0.0.1:3000
caveman-browse snapshot http://127.0.0.1:3000 "save settings"
caveman-browse act <uid> click
caveman-browse recover <handle>
caveman-browse close

要点：

browser_snapshot.query 是大型页面的 token 高效路径：保留最佳匹配的无障碍节点及其祖先，同时 CCR 保留完整原始树；紧凑输出使用 [uid] role "name" 行，UID token 仅保留给可操作或未知自定义角色。
节省永远是 inferred：tokens_after 统计精确的 Agent 可见 JSON 结果，view_tokens 单独隔离紧凑树的成本。
恢复由 CCR 支撑：browser_recover 返回快照句柄对应的字节精确原始 AX 负载。
直接命令共享一个脱离的、隔离的 Chrome 直到 close：首次使用创建 profile 与 CCR 目录。
导航策略：允许 http(s)、about:blank 及受限的 data:text/html，拒绝本地文件与特权协议。
状态确认：动作在另一次聚焦快照证明状态前报告 settled:false。
安全边界：快照在语义结构足够时避免截图；恢复保留精确捕获源。浏览器动作与 JS 求值可能改变页面或账号状态，宿主权限策略应区分读/写操作。Source 与二进制为 BSL 1.1。

四、Output Shrinker：命令与工具输出压缩

输出压缩器解析大型命令与工具结果，保留高信号结构，把完整源存入 CCR。适用于编译器日志、测试输出、diff、搜索结果与终端转录。

some-command | caveman tools shrink      # 管道输入
caveman tools shrink -- go test ./...    # 捕获并压缩一个命令

容量与语义：

结构化 shrink 输入上限 32 MiB；CLI 命令捕获使用独立的有界上限，默认 8 MiB。超限输入被拒绝或由调用方策略处理，绝不静默当作完整处理。
安全替换的前提：shrinker 必须保留错误类别、退出状态、相关路径与恢复句柄。缺少这些字段的简短摘要不是调试输出的安全替代。

概念区分：caveman tools shrink 是命令输出压缩；而专门的工具目录压缩二进制是 caveman-shrink（见下一节）。caveman tools compress catalog 会委托给 caveman-shrink 二进制，caveman tools shrink 保持为命令输出压缩（见 packages/cli/AGENTS.md）。

五、Tool-catalog Shrinker：`caveman-shrink` 压缩工具目录

caveman-shrink 专注于 MCP 与 OpenAI 风格工具目录，让一大串工具定义消耗更少 token。它删除注释膨胀（examples、titles、comments、schema markers），压缩长描述但保留识别到的约束句，同时逐字节保留结构选择面（工具名、参数、枚举、required 字段、默认值、常量、$ref 目标）。

cat tools.json | caveman-shrink > tools.min.json    # stdin→stdout，推断比例报告走 stderr
caveman-shrink lint tools.json                        # 查看每个工具的缩减，不落地提交
caveman-shrink recover <handle> > tools.original.json # 从 stderr 报告的句柄恢复精确原始字节
npx -y caveman-shrink lint tools.json                 # 无 Go 工具链即可运行

保证（见 shrink/README.md）：

结构选择面：压缩后的目录暴露与原始完全相同的名/参/枚举/required。同一工具行为仍需模型评测，结构检查本身不能证明模型会选中相同工具。
参数构造保留：短描述整体保留；长描述保留开头加识别到的约束句；默认、常量、内部引用目标存活。
Fail-open：成功压缩是 S4 且模型可见；格式错误或不可压缩输入原样直通。
有界输入：stdin 上限 32 MiB（shrink/cmd/caveman-shrink/main.go 以 io.LimitReader(r, maxBytes+1) 实现），更大目录以 cave_input_too_large 失败，无限制缓冲。
可逆：一次压缩型 shrink 在返回句柄前，先把精确原始字节提交到 CAVEMAN_CCR_DB（或 ~/.caveman/ccr.db），之后任何进程都能用 caveman-shrink recover 解析。
描述缩减是模型可见且有损的：结构保留不保证模型会选中同一工具。所有数字均为 inferred。

六、本地存储布局与备份边界

本地代理与工具通常使用以下文件（相对用户主目录）：

~/.caveman/caveman.db        # 主代理数据库
~/.caveman/ccr.db            # CCR 恢复存储（命令/工具输出、shrink 原始源）
~/.caveman/mem/mem.db        # Cavemem 记忆 SQLite
~/.caveman/mem/ccr.db        # 记忆召回的 CCR 恢复存储
~/.caveman/caveman.yaml      # 配置
~/.caveman-cloud/config.json # 云端（可选）配置

项目级 overlay 使用 ./.caveman/config.json。

备份与删除须知：这些文件承载恢复句柄（recovery handle）、学到的观测与本地记忆。若删除 ccr.db，先前 caveman_compress、browser_snapshot、caveman-shrink 产出的句柄将无法再解析；若删除 mem/mem.db，Cavemem 记住的事实与取代历史一并丢失。因此在清理前须明确知道这些句柄与记忆将停止解析。

七、使用边界与安全小结

账号无关：以上本地工具均无需 Caveman 账号即可运行，数据全部留在本地磁盘。
inferred-only 诚实性：MCP、Cavemem、browse、shrink 全部只报告推断（inferred）节省，从不声明 verified；这使 token 成本统计可信、可审计。
可恢复性是核心契约：所有有损压缩路径（compress、browse snapshot、shrink、mem recall 命中）都产出 recovery_handle，对应字节精确原始源保存在 CCR，跨进程可解析。
权限最小化：MCP 由宿主 Agent 决定工具何时可调用，应把工具权限配置到最窄；浏览器动作与 JS 求值有写状态风险，宿主策略应区分读写。
失败不静默：超限输入被显式拒绝（cave_input_too_large、退出码 65），不可压缩输入以 ratio:0 直通而非报错，避免误导下游。