如何为Caveman添加新的Compressor：压缩器注册与开发完全指南

如何为Caveman添加新的Compressor压缩器注册与开发完全指南【免费下载链接】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/cavemanCaveman 是一款面向 AI Agent 的 Token 压缩引擎核心卖点是用最少的 token 把事办成——通过压缩器Compressor把 JSON、日志、代码等上下文缩减最多 65%。当你想支持一种新内容类型比如 Markdown 表格、SVG、数据库查询结果就需要为 Caveman 注册一个新的 Compressor。本文用通俗的方式讲清楚压缩器注册机制、开发步骤、安全等级声明和测试要求帮助你从零到提交 PR。一、先搞懂Caveman 的压缩器注册机制Caveman 的引擎采用「检测 → 查注册表 → 压缩 → 门禁校验」的流水线。所有 Compressor 都集中在engine/compressors/目录下由一张**注册表Registry**统一路由Compressor 接口每个压缩器只需实现 3 个方法见 compressor.goContentType()返回它负责的内容类型名如json、logSafetyClass()声明自身在 S0–S4 安全阶梯上的等级Compress(input)纯字节变换成功返回压缩结果任何解析失败都返回okfalse引擎会把原始字节原样透传fail-closed 设计Registry一张「内容类型 → Compressor」的映射表。Default()函数一次性注册全部 15 个内置压缩器你的新压缩器也在这里上岗。type Compressor interface { ContentType() string SafetyClass() safety.Class Compress(input []byte) (out []byte, ok bool) }内置 Compressor 一览内容类型压缩器选择方式jsonJSON 数组折叠保留错误项、首尾元素自动检测log日志降噪保留 ERROR/FATAL 行自动检测code源码精简tree-sitter / go-ast 双实现自动检测diff/search-result/text/html/tabular/config/terminal对应专用压缩器自动检测toon/a11y/toolschema/repetition等高级变换仅显式指定Options.Type几个设计要点值得新手特别注意纯字节变换Compressor 不数 token、不存恢复记录、不碰网络——这些由引擎核心负责所以每个压缩器都是自包含、可独立测试的模块。确定性 幂等相同输入永远得到相同输出且压缩结果再压缩不会变化。更小的门禁压缩结果必须比原文小否则引擎丢弃结果、回退原文。有损可恢复声明为 S4有损的压缩器原始字节必须先存入 CCR 恢复存储engine/ccr/模型后续可按 handle 取回原文。二、开发新 Compressor 的 5 个步骤步骤 1新建一个压缩器文件在engine/compressors/下新建文件如markdown.go参照 json.go 或 config.go 的写法定义一个结构体持有可调参数如保留行数、阈值并提供NewXxx() Compressor构造函数。以 config 压缩器为例它用一组正则识别 YAML/TOML/INI结构体里只有minLines、keepHead、keepTail等几个参数非常轻量。步骤 2声明安全等级安全等级由压缩方法本身决定写在 engine/safety/safety.go 的阶梯里等级含义是否可改模型可见字节是否需要 CCR 恢复S0 / S1元数据、缓存提示类否否S2 / S3结构性 / 行为性变更是否S4有损压缩绝大多数压缩器是是且必须披露丢弃了什么如果你做的压缩会删减模型可见内容折叠数组、省略行就老老实实声明 S4。步骤 3实现 fail-closed 的 Compress三条铁律可对照 compressor.go 顶部注释有界解析不要无限制地递归解析避免内存爆炸任何疑问都放弃解析失败、结构不支持、没有把握 → 返回(nil, false)绝不输出看起来差不多的结果省略要留标记像日志压缩器那样用... N lines elided (caveman)标记折叠区域让模型知道内容被省略且可恢复。步骤 4在 Default 注册表中注册打开 compressor.go 的Default()函数加一行r.Register(NewMarkdown())。这里有个进阶细节如果自动检测可能误判比如 Markdown 和纯文本很难区分学 TOON 和 a11y 的做法——注册但只允许显式指定类型到达不进自动检测链如果你的压缩器编译产物永远路由不到把它加进manifestExcluded白名单。否则它会进入能力清单导致RegistrySHA256变化让所有已发布的 Cave Build 锁在运行期失效——这是注册时最容易踩的坑。步骤 5接入内容检测如需自动选择自动检测逻辑在 engine/detect.go顺序是严格 JSON → 终端输出 → diff → HTML → 表格 → 代码 → 日志 → 搜索结果 → 配置 → 兜底text。新增检测信号时注意信号必须是确定性、可证的参考 ANSI 转义序列作为终端判定依据的做法——只有终端输出才合法携带它低置信度内容一律落入text交给保守压缩器兜底。三、Compressor 测试怎么写参考 log_test.go 的测试套路一个好压缩器的测试至少覆盖 4 类用例用例验证点核心行为错误/关键行被保留噪音被折叠输出出现省略标记体积门禁输出严格小于输入幂等性压缩结果二次压缩保持不变失败回退畸形输入返回okfalse原样透传测试 fixture 放在engine/compressors/testdata/边界用例空输入、恰好阈值长度、超大输入用真实数据支撑发布任何性能声明前必须有 fixture 背书要求见 extending.md。四、提交前检查清单 ✅ 无歧义的内容类型名 已声明的安全等级✅ 有界解析、确定性输出、幂等✅ 非法输入回退原始字节fail-closed✅ S4 输出已接入 CCR 恢复存储✅ 明确选择方式自动检测 or 仅显式指定✅ 覆盖有效/无效/输出变大/边界的 fixture 测试✅ 更新Default()注册表及 engine.md 中的注册器数量与文档五、关键文件路径速查路径说明engine/compressors/compressor.goCompressor 接口、Registry 与 Default 注册表engine/compressors/json.goJSON 压缩器省略标记、BM25 相关性选取engine/compressors/config.goYAML/TOML/INI 压缩器engine/compressors/html.goHTML 正文提取纯 Go 可读性启发式engine/detect.go内容类型自动检测路由engine/safety/safety.goS0–S4 安全等级注册表engine/ccr/有损压缩的原始字节恢复存储docs/technical/engine.md压缩引擎官方文档含流水线图docs/technical/extending.md扩展指南新增压缩器要求清单掌握「接口三方法 注册表 安全等级 fail-closed 测试」这四件套你就能像维护者一样为 Caveman 贡献一个稳健的新 Compressor 了。【免费下载链接】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），仅供参考