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

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

【免费下载链接】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

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 引擎的强制-onlya11y压缩器压缩 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直通而非报错，避免误导下游。

以上能力共同构成 Caveman「少 token 也能干活」的本地底座：压缩有损但处处可逆，记忆有界但保守可信，浏览器与命令输出都在可控上限内安全降级。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析