尧图网站建设 
Caveman Engine 深度解析内容感知压缩、S0–S4 安全分级与 CCR 无损恢复【免费下载链接】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 Engine 是 caveman 项目一个以“用更少 token 完成同样的事”为目标的 Claude Code skill 生态的核心压缩引擎它检测一段载荷的内容类型路由到按安全等级划分的压缩器统计 token 缩减比例并把原始字节存入 CCR 存储以备恢复。本文基于仓库文档 engine/CLAUDE.md 与对应源码完整拆解其稳定四调用 APICompress/Retrieve/Detect/Stats的工作方式、S0–S4 安全分级的含义、15 个默认压缩器的注册机制以及“fail-closed、只报 inferred、绝不宣称 verified”这套诚实性不变量背后的工程实现。引擎核心detect → route → compress → 计数 → CCR引擎的入口类型是 engine.go 中的Engine结构体由三部分构成压缩器注册表compressors.Registry、token 计数器tokens.Counter和 CCR 存储*ccr.Store。New(store, counter)构造时若传入 nil counter 会使用默认离线 BPE 计数器store 允许为 nil——但此时引擎仍然能检测和无损压缩只是永远不运行有损压缩器因为有损结果若无法恢复就违背了可逆性契约见 engine.go#L31-L41。Compress(input, opts)的完整流水线与文档描述完全一致且五个直通pass-through条件都能在源码中逐条对应record 模式直通record模式下输出与输入逐字节相同不做任何转换也不存储恢复记录无匹配压缩器直通内容类型在注册表中找不到对应压缩器时原样返回解析失败直通压缩器报 parse 问题okfalse时转发原始字节结果不更小直通after before || bytes.Equal(out, input)时原样放行、不声称任何缩减见 engine.go#L110-L112有损但不可恢复直通S4有损压缩器只有在原始字节能先存入 CCR 后才可运行没有 store 时 fail closed 到直通。只有 CCRPut成功之后res.Output才会被替换为压缩结果——这意味着调用方绝不可能收到“没有持久化 handle 的转换后字节”见 engine.go#L116-L139。Result结构result.go还带有Basis字段token 数字的计量基础永远是inferred本地估算因为压缩发生在计费前拿不到 provider 的 usage。PassedThrough()用“无 handle、无 method、ratio 为 0”三条件判定本次是否直通。Simulate是 API 之外的一个补充与Compress完全同管道但不做任何存储、不发起网络调用。它有意与Compress保留一处差异——S4 压缩器在无 store 时Compress直通而Simulate会照报“将会实现的缩减”并标记Recoverablefalse让调用方知道需要先配好 CCR 才能真正发出这个转换。Mode 与 Options未知值一律 fail closedresult.go 中只有两个模式ModeRecord默认直通和ModeCompress运行路由到的压缩器。Mode.normalized()对空值和任何未知模式都回落到record——文档里“unknown mode fails closed to record”在实现里就是一行default: return ModeRecord。Options的其余三个字段各有明确边界Type强制指定内容类型留空则自动检测Query非空时让实现了QueryAwareCompressor的压缩器用确定性 BM25无 embedding偏向保留相关内容不实现该接口的压缩器完全忽略它且查询永远不会让输出比无查询结果更大ExternalRecovery允许嵌入式网关在引擎本地 CCR 之外提供字节级恢复前提是调用方在转发压缩字节前已自行存好原始字节。另外engine.go#L55-L61 显示环境变量CAVE_ENGINE_TOONbest-of会向注册表额外注册JSONStrategy压缩器——这是默认 15 个之外唯一的注册表变动入口。内容路由器12 种类型低置信度一律落到 textdetect.go 定义了引擎的内容类型常量json、log、code、diff、search-result、text、toon、html、a11y、terminal、tabular、config。Detect是纯确定性函数判断顺序与源码一致严格 JSON → 终端 → diff → HTML → 表格 → 代码 → 日志 → 搜索结果 → 配置 → text任何低置信度情形都开放到下一个检测器最终兜底为text对应“low confidence → text”的文档声明。源码中有几处值得注意的误路由防护终端检测放在 diff/code/log 之前因为裸 ANSI/CSI 转义序列是唯一性信号——只有真实终端输出才会携带它不会抢走任何 log/code/JSON 流量次要信号是密集裸\r进度条原地重绘且排除了普通 CRLFlooksLikeCode先问“是不是日志”由日志级别/时间戳行主导的载荷即使消息里含return、class等关键词也路由到日志压缩器。注释称之为“最高价值的误路由修复”见 detect.go#L106-L112HTML 检测会让位给源码JSX/TSX 组件或内嵌标记字符串字面量的源文件因为有、className、import等代码结构信号会路由到代码压缩器而不是被按 HTML 抽成文本代码判定要求“至少 3 个关键词 一个结构性信号”避免一段恰好用了class一词的散文被误判。行号边栏listing剥离agent 发来的是“文件清单”不是文件listing.go 解决一个很具体的问题编码 agent 交给引擎的不是文件本身而是其 read 工具打印的结果——每行都带行号边栏1\t{、2\t unit。这层边栏是展示格式会直接击穿DetectJSON 文档不再以{开头json.Valid失败源码变得不可解析。两者统统落到text压缩率约 0%。因此解包放在引擎层而不是压缩器内部——边栏与内容类型正交它可能包裹 JSON、源码、日志、CSV、配置中的任何一种每种都必须按其真实类型路由。恢复规则有两条讲究保留每行原始的编号压缩后存活的行仍带它在原文件中的行号编号继续指向 agent 读到的那份文件对“重构式”转换整体放弃恢复重编码的 JSON如 TOON 输出没有任何一行能被原编号所描述此时直接返回裸压缩体。源码注释说得很直白“描述不了任何东西的行号比没有行号更糟。”S0–S4 安全分级类的固有属性不是用户选项safety/safety.go 是分级注册表是一个无 engine 依赖的叶子包让引擎核心和压缩器都能引用而不产生循环依赖。每个压缩器声明自己的类注册表是回答两个诚实性问题的唯一地点这个类是否改动模型可见字节它是否必须先有 CCR 恢复记录才可运行级别ByteSafeRequiresCCRReversible含义S0truefalsetrue字节安全行为元数据、计量模型可见字节不变S1truefalsetrueprovider 原生提示缓存、路由模型可见字节不变S2falsefalsetrue需要 SDK 配合的结构性改动S3falsefalsefalse行为性改动路由、推理Cloud 侧由 eval 门控S4falsetruefalse有损结构性压缩改动模型可见字节必须可逆CCR且披露丢了什么Lookup对未知类返回okfalse调用方 fail closed——文档中“Unknown class → fail closed”正对应 engine.go#L96-L99。文档特别提示只把byte-safe一词留给safety.Info.ByteSafe true的类即 S0/S1其余不要误称。压缩器注册表Default() 注册 15 个forced-only 不进 Detectcompressors/compressor.go 的Compressor接口只有三个方法ContentType()、SafetyClass()、Compress()。接口的包注释定义了核心纪律压缩器是纯字节转换——它永远不数 token、不触碰 CCR、不访问网络引擎核心在周围做这些事。这正是每个压缩器可以保持自包含、可单测、加一个压缩器只需“新文件 测试”的原因。Default()注册的 15 个压缩器为JSON、log、code、diff、search-result、text、HTML、tabular、config、tool-schema、tool-schema-annotations、TOON、accessibility-treea11y、repetition、terminal。其中后五个tool-schema、tool-schema-annotations、TOON、a11y、repetition从不被自动检测只能通过Options.Type强制到达——这与文档“forced-only … must not be added to Detect”的约定一致。两个可选能力接口值得了解MetadataCompressor压缩器可报告本次实际使用的方法Method与LosslessToModel等元数据QueryAwareCompressor实现CompressQuery的压缩器支持查询导向压缩引擎仅在Options.Query非空时类型断言并调用。为什么 toolschema-annotations 被刻意排除在能力清单之外manifestExcludedcompressors/compressor.go#L139-L148把toolschema-annotations排除在 Cave Compiler 消费的 transform-capability ABI 之外。原因是advertise 一个压缩器会旋转RegistrySHA256而每个已构建的 Cave Build lock 都钉着旧值失配的 lock 会在运行时让 agent 失败。既然没有编译后的计划会路由到它把它加进 ABI 换来的只是一行永远用不到的能力代价却是使所有现场 lock 失效。toolschema 转换目前是纯客户端侧的文档专门用一段约定说明了这一点值得逐条消化注册它只是让引擎调用方可以 force并不让它从托管网关流量可达provider 适配器刻意把 tool 数组保留在冻结的 prompt-cache 前缀里没有任何计费路由调用这个压缩器引擎 API/CLI 调用方可以在本地 force 它caveman-shrink是它专门的产品面这些缩减保持本地且inferred托管网关另有一条独立的 S2 tool-search/deferral 路径不要把它与压缩混为一谈未来若要为它开通网关路由需要先做缓存对 schema 的成本算术、保证字节级稳定的前缀输出、并通过 eval 门。重复剔除的正确性护栏keepNonRedundantcompressors/redundancy.go 实现了文档“elide repetition, never a document”这条正确性规则。所有会丢单元的压缩器text、log、json、tabular、config、searchresult、terminal在输出前都调用keepNonRedundant一个即将被丢的单元若没有已存活的单元与它相似则被保留其后的副本再对它折叠。实现细节上有几个精心设计的常量词汇画像 数字掩码unitVocabulary把单元降为词汇集合数字串折叠为#——这让只差时间戳的两行日志互相认得同时保留原词使只共享字段名的两条书目条目不会被误判为同类无词单元不掩码redundancyMinWordTokens 1。像6 [1973., 251]这样的单元掩码后只剩#会让整张数据表看起来全同并整体被剔除——所以带至少一个词的单元才掩码否则按原数字比较因为那里的数字本身就是内容掩码与未掩码画像不可互比representedBy中class.masked ! dropped.masked直接跳过防止“形状相同、数字不同”被读成“文本相同、数字相同”90% 包含阈值单个存活单元必须已携带待丢单元 90% 的词汇才算“已被代表”宁严勿松——漏剔除损失的是缩减错剔除改变的是答案128 次晋升上限一个载荷里“首次出现即保留”的单元超过 128 个说明它不是重复流而是文档其余单元全部保留最终由“输出不更小”检查让它整体直通、不声称任何缩减。注释特意提到计数陷阱若把种子和晋升一起计数任何超过 64 个存活单元的大数组都会静默变成直通。文档引用了一个实测代价若 agent 必须枚举的文档被剔除agent bench 上会花掉基线 5.5 倍的开销2026-08-06。这条规则被明确定位为“正确性规则不是调参旋钮”。省略标记只陈述它验证过的事实invariantscompressors/invariants.go全文 806 行为 log/tabular/JSON 的省略标记附加从被替换单元精确计算出的事实且只陈述验证过的内容。源码头部注释与文档的 Gotchas 段落逐条对应可归纳为标记可携带的三类事实常量某字段在被省略的每一个单元中字节级相同记为namevalue如all statecharged枚举可变字段在少量短值上变化时完整列出并带精确计数各桶之和恒等于被省略数缺失该字段的单元进absent×N桶如status: fulfilled×15 shipped×3 processing×2数值范围用原始极值字符串打印range amount5.00..199.99从不做重格式化或舍入因此边界绝不可能比实际更宽。整体扣留的条件永不截断因为部分清单会被读成完整清单凭证形状的字段名含空格或超过 24 字节的值源码常量invariantMaxValueBytes 40用于更长的单值拒绝标记预算则另有上限;超过 5 个不同取值任何单元解析不出字段的 run——整个 run 的摘要禁用标记退化为与裸… N rows elided (caveman) …字节级相同。标识符列表的 coverage 表达每个桶恰好一个单元的枚举不是类不变量而是标识符列表标记改为陈述其覆盖度——order_id: 25 distinct, ord-1000..ord-1024精确不同计数 按字节序最小/最大原始值串不声称中间无缺口。这是唯一能回答“ord-1043 是在被省略的行里还是根本不在账本中”这一事实。若 run 恰好稠密共享前缀、定宽数字、max-min1等于计数值则改说wh-5000..wh-5059 all 60 present——一个经核实的成员性答案稠密是数出来的绝不从端点推断混合后缀宽度、两个前缀或单个缺口都退回计数形式。预算与裁剪顺序摘要上限 160 字节且不超过其替换字节数的四分之一下限 64永不超过一半超预算时按顺序整体丢弃条目标识符式枚举 → 范围 → 有界 coverage → 常量 → 稠密 coverage类枚举最后每条载荷最多追加一行尾部契约行且仅当实际丢掉的字节 ≥4 KB 时。小于 3 个单元的 run 根本不省略除非折叠后既能摘要又使自身字节减半——单个单元标记加恢复 handle 的成本约等于单元本身且读起来像个洞。文档给出的代价是刻意为之的这套机制在 toolwork 语料上让 ratio 降了约 4 个点0.83 → 0.79。换来的是什么2026-08-08 一次 bench 中无法分辨被省略内容的 agent 连发 46 次caveman_retrieve开销是无压缩对照组的 3.3 倍只陈述常量和范围的第一版修复让风暴停在 11–27 次因为它对任务真正依赖的那个混合值字段保持沉默第二轮仍在标识符枚举、无事实小类和{__caveman_elided__:1}单例上漏恢复调用。恢复视图由完整单元构成retrieve_queryengine/retrieve_query.go 把 CCR 恢复收窄到匹配查询的单元而“单元”是自定界的整体完整 JSON 记录绝不是字段行——status: unfulfilled,是片段、从原始字节切出的完整 CSV 记录表头只显示一次、完整 log/NDJSON 行、或非 JSON 散文的完整段落。关键规则JSON 字段名从不是出处证据messages[].content、text、system永远附着在其完整对象记录上因为工具输出可以与 provider 请求使用相同字段名独立 JSON 数组之间有显式 gap 哨兵被省略的信封/标量字节有首尾标记无法分解的内容没有记录数组的 JSON整体返回而非按行切开收窄视图若不更小也返回完整原文——过度返回是安全的片段不是视图中的任何间隙两个返回单元之间、首单元之前、末单元之后都打印… [caveman: non-adjacent] …保证视图中的相邻性从不暗示原始中的相邻性。这段代码注释里的事故记录与文档一致2026-08-08query 模式返回了某 pretty-printed orders 页的 BM25 排序行agent 把status: unfulfilled属于 ord-1043读成了紧邻其下的order_id: ord-1047的字段报告了 5 个未履约订单而实际只有 3 个——12 任务 bench 中答错两道。查询收窄本身有界BM25 打分复用 contextwindow 的确定性 packer 所用的打分器top-k 上限maxRetrieveSections 20命中后按原始顺序重排。一个恢复面、两个 id 空间这是文档中最反直觉的 Gotcha源码注释engine.go#L235-L266给出了完整解释CCR 存储同时保存压缩 blob handleccr_…走store.Get和原生运行时的类型化对象store.GetObject而运行时在遮蔽整段工具输出时向 agent 展示的是ccr://objectID。Engine.Retrieve因此先查 blob 表、未命中再落 object 表、两者都未命中才失败MCP 侧的normalizeRecoveryHandle接受ccr_…、ccr:…、ccr:…、ccr://…四种形式。动机是循环agent 只会复制它被展示的那个引用一个无法解析的形式不会“降级”而是循环——失败的工具结果本身又会被遮蔽成新的指针“一个指向另一个指针的指针无限循环”。文档引用的实测2026-08-08inventory-mismatch 与 webhook-delivery-gaps 两个任务拿到ccr://objectID后每次 retrieve 都回答cave_unknown_handle发生 27–97 次恢复调用、未写出任何答案、两任务 0/6同构建下 rate-limit-forensics 却以约便宜 35% 的成本拿了 3/3。CCR 存储SQLite、单序列化连接、生命周期ccr/ 目录提供~/.caveman/ccr.dbSQLite恢复存储加原生会话存储内容寻址 handle、字节级精确的Get、会话作用域、依赖、current/stale 状态以及 Hot/Warm/Cold/Archived 生命周期。文档强调的实现事实嵌入式 SQLite 使用单条序列化连接使并发 hook/仓库写入既不会撕裂内存中的 schema也不会与SQLITE_BUSY竞态store_sqlite.go 注释补充了为什么需要journal_mode(WAL)——否则读者在写者持锁期间被完全锁出。JS/WASM 构建则使用 store_wasm.go 的内存存储。引擎层面的 CCR 联动规则在 engine.go#L94-L102info.RequiresCCR e.store nil !opts.ExternalRecovery时直通——这就是“CCR-or-pass-through”的实现本体。token 计数离线 BPE永远是 inferredtokens/ 定义Counter接口默认实现是词表内嵌的离线 BPE 分词器OpenAI o200k_base 词表Default()返回共享实例见 tokens.go#L87-L92。所有 ratio 都是带inferred标签的本地估算绝不是verified也绝不重新投影为 provider usage——因为压缩发生在请求计费之前provider 侧数字在此时不可得。这也是 Result 中TokenCountBasis字段存在的理由它标明前后两个数字用的是同一个估算器。目录布局与构建约定文档给出的完整布局与仓库一一对应engine.goEngine 核心含 record/miss/parse-fail/not-smaller/no-store 五路直通result.goResult/Options/Modedetect.go内容路由器listing.go行号边栏剥离与恢复safety/S0–S4 注册表tokens/Counter 接口与默认 o200k_base BPEcontextwindow/确定性 BM25 上下文打包器带 recency/error/priority 信号与 token 预算计量compressors/接口 注册表Default()注册 15 个ccr/SQLite 恢复 原生会话存储pixel/pxpipe 移植MIT见其 NOTICE文本→PNG 请求压缩内嵌字形图集 渲染器 盈利门 按 wire 格式的变换Anthropic/OpenAI/Gemini。它是 S4 有损、白名单门控CAVE_PIXEL_MODELS、由 proxy 的 pixel 模式消费从不接入 Detect也从不被 WASM 构建导入约 4 MB 资源。applicability.go 验证了文档声明CAVE_PIXEL_MODELS缺省时默认白名单就是claude-fable-5,gpt-5.6evals/本地 eval 框架 fail-closed grader 内嵌 fixturesRun()是质量门未知 grader 返回passed:falsecmd/caveman-engine/CLI shell 出来的二进制子命令为compress | detect | retrieve | stats | registry | toon encode|decode | evals run | pixel render|simulate。toon是无状态无 CCR的 JSON⇄TOON 转换器双向都 fail closed。retrieve handle [query]带 query 时只返回最相关 sectionBM25与RetrieveQuery对应。构建/测试约定为make product-build PRODUCTengine/make product-test PRODUCTengine。新增压缩器是“compressors/ 下一个自包含文件 测试 在Default()中注册”toolschema、toon这类 forced-only 压缩器不得加入Detect。其余诚实性不变量速览cgo完整代码压缩Python/JS/TS需要 tree-sitter 构建无 cgo 构建只压缩 Go。内嵌 eval fixtures 在 cgo 下覆盖这三种语言对应 compressors/code_cgo.go 与 code_nocgo.go 的构建期选择fail-closed 三件套未知模式 →record未知内容类型 →text未知 grader →passed:falseboundaryengine 处于public/区绝不导入cloud/…由make check-boundaries强制确定性要求贯穿始终invariants 的渲染路径刻意保持顺序保留、无 map 迭代序依赖——因为压缩块必须在后续每个 turn 以相同方式重新序列化否则 provider 前缀缓存会失效。小结Caveman Engine 的设计可以用 engine/CLAUDE.md 的一句话概括“Everything it reports is inferred; it never says verified”。围绕这句话仓库实现了完整的不变量体系五个直通条件、S0–S4 分级与 RequiresCCR 门控、keepNonRedundant 的“剔除重复但不剔除文档”、invariants 标记“只陈述验证过的事实”、恢复视图“完整单元 非相邻哨兵 双 id 空间解析”以及 CCR-or-pass-through 的存储前置。理解这套机制的实用价值在于当你通过 CLIcaveman-engine compress/retrieve/stats或 SDK 调用引擎时每一个inferredratio、每一个ccr_…handle、每一个省略标记里的计数背后都有上面这些可定位到具体文件的护栏在支撑——而所有护栏的失效方向都一致宁可不压缩不压缩错。【免费下载链接】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），仅供参考 Caveman Engine 深度解析：内容感知压缩、S0–S4 安全分级与 CCR 无损恢复
Caveman Engine 深度解析内容感知压缩、S0–S4 安全分级与 CCR 无损恢复【免费下载链接】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 Engine 是 caveman 项目一个以“用更少 token 完成同样的事”为目标的 Claude Code skill 生态的核心压缩引擎它检测一段载荷的内容类型路由到按安全等级划分的压缩器统计 token 缩减比例并把原始字节存入 CCR 存储以备恢复。本文基于仓库文档 engine/CLAUDE.md 与对应源码完整拆解其稳定四调用 APICompress/Retrieve/Detect/Stats的工作方式、S0–S4 安全分级的含义、15 个默认压缩器的注册机制以及“fail-closed、只报 inferred、绝不宣称 verified”这套诚实性不变量背后的工程实现。引擎核心detect → route → compress → 计数 → CCR引擎的入口类型是 engine.go 中的Engine结构体由三部分构成压缩器注册表compressors.Registry、token 计数器tokens.Counter和 CCR 存储*ccr.Store。New(store, counter)构造时若传入 nil counter 会使用默认离线 BPE 计数器store 允许为 nil——但此时引擎仍然能检测和无损压缩只是永远不运行有损压缩器因为有损结果若无法恢复就违背了可逆性契约见 engine.go#L31-L41。Compress(input, opts)的完整流水线与文档描述完全一致且五个直通pass-through条件都能在源码中逐条对应record 模式直通record模式下输出与输入逐字节相同不做任何转换也不存储恢复记录无匹配压缩器直通内容类型在注册表中找不到对应压缩器时原样返回解析失败直通压缩器报 parse 问题okfalse时转发原始字节结果不更小直通after before || bytes.Equal(out, input)时原样放行、不声称任何缩减见 engine.go#L110-L112有损但不可恢复直通S4有损压缩器只有在原始字节能先存入 CCR 后才可运行没有 store 时 fail closed 到直通。只有 CCRPut成功之后res.Output才会被替换为压缩结果——这意味着调用方绝不可能收到“没有持久化 handle 的转换后字节”见 engine.go#L116-L139。Result结构result.go还带有Basis字段token 数字的计量基础永远是inferred本地估算因为压缩发生在计费前拿不到 provider 的 usage。PassedThrough()用“无 handle、无 method、ratio 为 0”三条件判定本次是否直通。Simulate是 API 之外的一个补充与Compress完全同管道但不做任何存储、不发起网络调用。它有意与Compress保留一处差异——S4 压缩器在无 store 时Compress直通而Simulate会照报“将会实现的缩减”并标记Recoverablefalse让调用方知道需要先配好 CCR 才能真正发出这个转换。Mode 与 Options未知值一律 fail closedresult.go 中只有两个模式ModeRecord默认直通和ModeCompress运行路由到的压缩器。Mode.normalized()对空值和任何未知模式都回落到record——文档里“unknown mode fails closed to record”在实现里就是一行default: return ModeRecord。Options的其余三个字段各有明确边界Type强制指定内容类型留空则自动检测Query非空时让实现了QueryAwareCompressor的压缩器用确定性 BM25无 embedding偏向保留相关内容不实现该接口的压缩器完全忽略它且查询永远不会让输出比无查询结果更大ExternalRecovery允许嵌入式网关在引擎本地 CCR 之外提供字节级恢复前提是调用方在转发压缩字节前已自行存好原始字节。另外engine.go#L55-L61 显示环境变量CAVE_ENGINE_TOONbest-of会向注册表额外注册JSONStrategy压缩器——这是默认 15 个之外唯一的注册表变动入口。内容路由器12 种类型低置信度一律落到 textdetect.go 定义了引擎的内容类型常量json、log、code、diff、search-result、text、toon、html、a11y、terminal、tabular、config。Detect是纯确定性函数判断顺序与源码一致严格 JSON → 终端 → diff → HTML → 表格 → 代码 → 日志 → 搜索结果 → 配置 → text任何低置信度情形都开放到下一个检测器最终兜底为text对应“low confidence → text”的文档声明。源码中有几处值得注意的误路由防护终端检测放在 diff/code/log 之前因为裸 ANSI/CSI 转义序列是唯一性信号——只有真实终端输出才会携带它不会抢走任何 log/code/JSON 流量次要信号是密集裸\r进度条原地重绘且排除了普通 CRLFlooksLikeCode先问“是不是日志”由日志级别/时间戳行主导的载荷即使消息里含return、class等关键词也路由到日志压缩器。注释称之为“最高价值的误路由修复”见 detect.go#L106-L112HTML 检测会让位给源码JSX/TSX 组件或内嵌标记字符串字面量的源文件因为有、className、import等代码结构信号会路由到代码压缩器而不是被按 HTML 抽成文本代码判定要求“至少 3 个关键词 一个结构性信号”避免一段恰好用了class一词的散文被误判。行号边栏listing剥离agent 发来的是“文件清单”不是文件listing.go 解决一个很具体的问题编码 agent 交给引擎的不是文件本身而是其 read 工具打印的结果——每行都带行号边栏1\t{、2\t unit。这层边栏是展示格式会直接击穿DetectJSON 文档不再以{开头json.Valid失败源码变得不可解析。两者统统落到text压缩率约 0%。因此解包放在引擎层而不是压缩器内部——边栏与内容类型正交它可能包裹 JSON、源码、日志、CSV、配置中的任何一种每种都必须按其真实类型路由。恢复规则有两条讲究保留每行原始的编号压缩后存活的行仍带它在原文件中的行号编号继续指向 agent 读到的那份文件对“重构式”转换整体放弃恢复重编码的 JSON如 TOON 输出没有任何一行能被原编号所描述此时直接返回裸压缩体。源码注释说得很直白“描述不了任何东西的行号比没有行号更糟。”S0–S4 安全分级类的固有属性不是用户选项safety/safety.go 是分级注册表是一个无 engine 依赖的叶子包让引擎核心和压缩器都能引用而不产生循环依赖。每个压缩器声明自己的类注册表是回答两个诚实性问题的唯一地点这个类是否改动模型可见字节它是否必须先有 CCR 恢复记录才可运行级别ByteSafeRequiresCCRReversible含义S0truefalsetrue字节安全行为元数据、计量模型可见字节不变S1truefalsetrueprovider 原生提示缓存、路由模型可见字节不变S2falsefalsetrue需要 SDK 配合的结构性改动S3falsefalsefalse行为性改动路由、推理Cloud 侧由 eval 门控S4falsetruefalse有损结构性压缩改动模型可见字节必须可逆CCR且披露丢了什么Lookup对未知类返回okfalse调用方 fail closed——文档中“Unknown class → fail closed”正对应 engine.go#L96-L99。文档特别提示只把byte-safe一词留给safety.Info.ByteSafe true的类即 S0/S1其余不要误称。压缩器注册表Default() 注册 15 个forced-only 不进 Detectcompressors/compressor.go 的Compressor接口只有三个方法ContentType()、SafetyClass()、Compress()。接口的包注释定义了核心纪律压缩器是纯字节转换——它永远不数 token、不触碰 CCR、不访问网络引擎核心在周围做这些事。这正是每个压缩器可以保持自包含、可单测、加一个压缩器只需“新文件 测试”的原因。Default()注册的 15 个压缩器为JSON、log、code、diff、search-result、text、HTML、tabular、config、tool-schema、tool-schema-annotations、TOON、accessibility-treea11y、repetition、terminal。其中后五个tool-schema、tool-schema-annotations、TOON、a11y、repetition从不被自动检测只能通过Options.Type强制到达——这与文档“forced-only … must not be added to Detect”的约定一致。两个可选能力接口值得了解MetadataCompressor压缩器可报告本次实际使用的方法Method与LosslessToModel等元数据QueryAwareCompressor实现CompressQuery的压缩器支持查询导向压缩引擎仅在Options.Query非空时类型断言并调用。为什么 toolschema-annotations 被刻意排除在能力清单之外manifestExcludedcompressors/compressor.go#L139-L148把toolschema-annotations排除在 Cave Compiler 消费的 transform-capability ABI 之外。原因是advertise 一个压缩器会旋转RegistrySHA256而每个已构建的 Cave Build lock 都钉着旧值失配的 lock 会在运行时让 agent 失败。既然没有编译后的计划会路由到它把它加进 ABI 换来的只是一行永远用不到的能力代价却是使所有现场 lock 失效。toolschema 转换目前是纯客户端侧的文档专门用一段约定说明了这一点值得逐条消化注册它只是让引擎调用方可以 force并不让它从托管网关流量可达provider 适配器刻意把 tool 数组保留在冻结的 prompt-cache 前缀里没有任何计费路由调用这个压缩器引擎 API/CLI 调用方可以在本地 force 它caveman-shrink是它专门的产品面这些缩减保持本地且inferred托管网关另有一条独立的 S2 tool-search/deferral 路径不要把它与压缩混为一谈未来若要为它开通网关路由需要先做缓存对 schema 的成本算术、保证字节级稳定的前缀输出、并通过 eval 门。重复剔除的正确性护栏keepNonRedundantcompressors/redundancy.go 实现了文档“elide repetition, never a document”这条正确性规则。所有会丢单元的压缩器text、log、json、tabular、config、searchresult、terminal在输出前都调用keepNonRedundant一个即将被丢的单元若没有已存活的单元与它相似则被保留其后的副本再对它折叠。实现细节上有几个精心设计的常量词汇画像 数字掩码unitVocabulary把单元降为词汇集合数字串折叠为#——这让只差时间戳的两行日志互相认得同时保留原词使只共享字段名的两条书目条目不会被误判为同类无词单元不掩码redundancyMinWordTokens 1。像6 [1973., 251]这样的单元掩码后只剩#会让整张数据表看起来全同并整体被剔除——所以带至少一个词的单元才掩码否则按原数字比较因为那里的数字本身就是内容掩码与未掩码画像不可互比representedBy中class.masked ! dropped.masked直接跳过防止“形状相同、数字不同”被读成“文本相同、数字相同”90% 包含阈值单个存活单元必须已携带待丢单元 90% 的词汇才算“已被代表”宁严勿松——漏剔除损失的是缩减错剔除改变的是答案128 次晋升上限一个载荷里“首次出现即保留”的单元超过 128 个说明它不是重复流而是文档其余单元全部保留最终由“输出不更小”检查让它整体直通、不声称任何缩减。注释特意提到计数陷阱若把种子和晋升一起计数任何超过 64 个存活单元的大数组都会静默变成直通。文档引用了一个实测代价若 agent 必须枚举的文档被剔除agent bench 上会花掉基线 5.5 倍的开销2026-08-06。这条规则被明确定位为“正确性规则不是调参旋钮”。省略标记只陈述它验证过的事实invariantscompressors/invariants.go全文 806 行为 log/tabular/JSON 的省略标记附加从被替换单元精确计算出的事实且只陈述验证过的内容。源码头部注释与文档的 Gotchas 段落逐条对应可归纳为标记可携带的三类事实常量某字段在被省略的每一个单元中字节级相同记为namevalue如all statecharged枚举可变字段在少量短值上变化时完整列出并带精确计数各桶之和恒等于被省略数缺失该字段的单元进absent×N桶如status: fulfilled×15 shipped×3 processing×2数值范围用原始极值字符串打印range amount5.00..199.99从不做重格式化或舍入因此边界绝不可能比实际更宽。整体扣留的条件永不截断因为部分清单会被读成完整清单凭证形状的字段名含空格或超过 24 字节的值源码常量invariantMaxValueBytes 40用于更长的单值拒绝标记预算则另有上限;超过 5 个不同取值任何单元解析不出字段的 run——整个 run 的摘要禁用标记退化为与裸… N rows elided (caveman) …字节级相同。标识符列表的 coverage 表达每个桶恰好一个单元的枚举不是类不变量而是标识符列表标记改为陈述其覆盖度——order_id: 25 distinct, ord-1000..ord-1024精确不同计数 按字节序最小/最大原始值串不声称中间无缺口。这是唯一能回答“ord-1043 是在被省略的行里还是根本不在账本中”这一事实。若 run 恰好稠密共享前缀、定宽数字、max-min1等于计数值则改说wh-5000..wh-5059 all 60 present——一个经核实的成员性答案稠密是数出来的绝不从端点推断混合后缀宽度、两个前缀或单个缺口都退回计数形式。预算与裁剪顺序摘要上限 160 字节且不超过其替换字节数的四分之一下限 64永不超过一半超预算时按顺序整体丢弃条目标识符式枚举 → 范围 → 有界 coverage → 常量 → 稠密 coverage类枚举最后每条载荷最多追加一行尾部契约行且仅当实际丢掉的字节 ≥4 KB 时。小于 3 个单元的 run 根本不省略除非折叠后既能摘要又使自身字节减半——单个单元标记加恢复 handle 的成本约等于单元本身且读起来像个洞。文档给出的代价是刻意为之的这套机制在 toolwork 语料上让 ratio 降了约 4 个点0.83 → 0.79。换来的是什么2026-08-08 一次 bench 中无法分辨被省略内容的 agent 连发 46 次caveman_retrieve开销是无压缩对照组的 3.3 倍只陈述常量和范围的第一版修复让风暴停在 11–27 次因为它对任务真正依赖的那个混合值字段保持沉默第二轮仍在标识符枚举、无事实小类和{__caveman_elided__:1}单例上漏恢复调用。恢复视图由完整单元构成retrieve_queryengine/retrieve_query.go 把 CCR 恢复收窄到匹配查询的单元而“单元”是自定界的整体完整 JSON 记录绝不是字段行——status: unfulfilled,是片段、从原始字节切出的完整 CSV 记录表头只显示一次、完整 log/NDJSON 行、或非 JSON 散文的完整段落。关键规则JSON 字段名从不是出处证据messages[].content、text、system永远附着在其完整对象记录上因为工具输出可以与 provider 请求使用相同字段名独立 JSON 数组之间有显式 gap 哨兵被省略的信封/标量字节有首尾标记无法分解的内容没有记录数组的 JSON整体返回而非按行切开收窄视图若不更小也返回完整原文——过度返回是安全的片段不是视图中的任何间隙两个返回单元之间、首单元之前、末单元之后都打印… [caveman: non-adjacent] …保证视图中的相邻性从不暗示原始中的相邻性。这段代码注释里的事故记录与文档一致2026-08-08query 模式返回了某 pretty-printed orders 页的 BM25 排序行agent 把status: unfulfilled属于 ord-1043读成了紧邻其下的order_id: ord-1047的字段报告了 5 个未履约订单而实际只有 3 个——12 任务 bench 中答错两道。查询收窄本身有界BM25 打分复用 contextwindow 的确定性 packer 所用的打分器top-k 上限maxRetrieveSections 20命中后按原始顺序重排。一个恢复面、两个 id 空间这是文档中最反直觉的 Gotcha源码注释engine.go#L235-L266给出了完整解释CCR 存储同时保存压缩 blob handleccr_…走store.Get和原生运行时的类型化对象store.GetObject而运行时在遮蔽整段工具输出时向 agent 展示的是ccr://objectID。Engine.Retrieve因此先查 blob 表、未命中再落 object 表、两者都未命中才失败MCP 侧的normalizeRecoveryHandle接受ccr_…、ccr:…、ccr:…、ccr://…四种形式。动机是循环agent 只会复制它被展示的那个引用一个无法解析的形式不会“降级”而是循环——失败的工具结果本身又会被遮蔽成新的指针“一个指向另一个指针的指针无限循环”。文档引用的实测2026-08-08inventory-mismatch 与 webhook-delivery-gaps 两个任务拿到ccr://objectID后每次 retrieve 都回答cave_unknown_handle发生 27–97 次恢复调用、未写出任何答案、两任务 0/6同构建下 rate-limit-forensics 却以约便宜 35% 的成本拿了 3/3。CCR 存储SQLite、单序列化连接、生命周期ccr/ 目录提供~/.caveman/ccr.dbSQLite恢复存储加原生会话存储内容寻址 handle、字节级精确的Get、会话作用域、依赖、current/stale 状态以及 Hot/Warm/Cold/Archived 生命周期。文档强调的实现事实嵌入式 SQLite 使用单条序列化连接使并发 hook/仓库写入既不会撕裂内存中的 schema也不会与SQLITE_BUSY竞态store_sqlite.go 注释补充了为什么需要journal_mode(WAL)——否则读者在写者持锁期间被完全锁出。JS/WASM 构建则使用 store_wasm.go 的内存存储。引擎层面的 CCR 联动规则在 engine.go#L94-L102info.RequiresCCR e.store nil !opts.ExternalRecovery时直通——这就是“CCR-or-pass-through”的实现本体。token 计数离线 BPE永远是 inferredtokens/ 定义Counter接口默认实现是词表内嵌的离线 BPE 分词器OpenAI o200k_base 词表Default()返回共享实例见 tokens.go#L87-L92。所有 ratio 都是带inferred标签的本地估算绝不是verified也绝不重新投影为 provider usage——因为压缩发生在请求计费之前provider 侧数字在此时不可得。这也是 Result 中TokenCountBasis字段存在的理由它标明前后两个数字用的是同一个估算器。目录布局与构建约定文档给出的完整布局与仓库一一对应engine.goEngine 核心含 record/miss/parse-fail/not-smaller/no-store 五路直通result.goResult/Options/Modedetect.go内容路由器listing.go行号边栏剥离与恢复safety/S0–S4 注册表tokens/Counter 接口与默认 o200k_base BPEcontextwindow/确定性 BM25 上下文打包器带 recency/error/priority 信号与 token 预算计量compressors/接口 注册表Default()注册 15 个ccr/SQLite 恢复 原生会话存储pixel/pxpipe 移植MIT见其 NOTICE文本→PNG 请求压缩内嵌字形图集 渲染器 盈利门 按 wire 格式的变换Anthropic/OpenAI/Gemini。它是 S4 有损、白名单门控CAVE_PIXEL_MODELS、由 proxy 的 pixel 模式消费从不接入 Detect也从不被 WASM 构建导入约 4 MB 资源。applicability.go 验证了文档声明CAVE_PIXEL_MODELS缺省时默认白名单就是claude-fable-5,gpt-5.6evals/本地 eval 框架 fail-closed grader 内嵌 fixturesRun()是质量门未知 grader 返回passed:falsecmd/caveman-engine/CLI shell 出来的二进制子命令为compress | detect | retrieve | stats | registry | toon encode|decode | evals run | pixel render|simulate。toon是无状态无 CCR的 JSON⇄TOON 转换器双向都 fail closed。retrieve handle [query]带 query 时只返回最相关 sectionBM25与RetrieveQuery对应。构建/测试约定为make product-build PRODUCTengine/make product-test PRODUCTengine。新增压缩器是“compressors/ 下一个自包含文件 测试 在Default()中注册”toolschema、toon这类 forced-only 压缩器不得加入Detect。其余诚实性不变量速览cgo完整代码压缩Python/JS/TS需要 tree-sitter 构建无 cgo 构建只压缩 Go。内嵌 eval fixtures 在 cgo 下覆盖这三种语言对应 compressors/code_cgo.go 与 code_nocgo.go 的构建期选择fail-closed 三件套未知模式 →record未知内容类型 →text未知 grader →passed:falseboundaryengine 处于public/区绝不导入cloud/…由make check-boundaries强制确定性要求贯穿始终invariants 的渲染路径刻意保持顺序保留、无 map 迭代序依赖——因为压缩块必须在后续每个 turn 以相同方式重新序列化否则 provider 前缀缓存会失效。小结Caveman Engine 的设计可以用 engine/CLAUDE.md 的一句话概括“Everything it reports is inferred; it never says verified”。围绕这句话仓库实现了完整的不变量体系五个直通条件、S0–S4 分级与 RequiresCCR 门控、keepNonRedundant 的“剔除重复但不剔除文档”、invariants 标记“只陈述验证过的事实”、恢复视图“完整单元 非相邻哨兵 双 id 空间解析”以及 CCR-or-pass-through 的存储前置。理解这套机制的实用价值在于当你通过 CLIcaveman-engine compress/retrieve/stats或 SDK 调用引擎时每一个inferredratio、每一个ccr_…handle、每一个省略标记里的计数背后都有上面这些可定位到具体文件的护栏在支撑——而所有护栏的失效方向都一致宁可不压缩不压缩错。【免费下载链接】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），仅供参考