Caveman Engine 深度解析：内容感知压缩的 detect → route → compress → CCR 流水线与 S0–S4 安全分级

本篇围绕 engine/AGENTS.md 所定义的 Caveman Engine（内容感知压缩引擎）展开：它如何检测一段载荷的内容类型、路由到对应安全分级的压缩器、统计本地 token 缩减比例，并在丢失性（S4）变换前先把原始字节存入可恢复存储（CCR）。读完本文，你将完整掌握 Engine 的四段式流水线、15 个内置压缩器的注册与边界、S0–S4 安全类契约、fail-closed 诚实性不变量，以及 caveman-engine CLI 的每个子命令和仓库内的构建/测试方式。

一句话总览：四段式流水线

Engine 的核心工作循环可以概括为一句话（源自 engine/AGENTS.md）：

Detect a payload's type → route to a safety-classed compressor → count the token reduction → store the original for recovery.

即：检测类型 → 路由到安全分级的压缩器 → 计算 token 缩减 → 存储原文用于恢复。

围绕这条流水线，Engine 对外暴露稳定的四调用 API：Compress / Retrieve / Detect / Stats。engine/engine.go 的包注释明确写道，这四个调用是 proxy、SDK、CLI、MCP server 和浏览器（WASM）构建共享的稳定契约；此外还有一个 Simulate 网络无关的 dry-run，报告“如果真实压缩会缩减多少”而不改变任何存储状态。所有它上报的数字都是 inferred（本地估算），Engine 从不声称 verified。

模块布局（Layout）逐一拆解

engine/AGENTS.md 的 Layout 一节列出了 Engine 的完整目录结构，下面逐条结合源码说明。

engine.go：Engine 核心

engine/engine.go 实现了 Engine 结构体（registry + counter + store 三件套）与 Compress 全流程。Compress 内部的 pass-through（原样透传）条件在 engine/engine.go#L84-L112 中集中体现，对应 AGENTS.md 所说的“record mode + miss + parse-fail + not-smaller + no-store all pass through”：

• record 模式：opts.Mode.normalized() == ModeRecord 时直接返回原文，永远不转换；
• 未命中压缩器：registry.For(ct) 找不到对应类型的压缩器 → 透传；
• 未知安全类：safety.Lookup 返回 known=false → fail closed 透传；
• 无恢复存储：S4（lossy）压缩器需要 CCR 存储（info.RequiresCCR），若 store == nil 且未启用 ExternalRecovery → 透传；
• 解析失败：压缩器 ok=false 或输出为 nil → 透传；
• 没有变小：after >= before || bytes.Equal(out, input) → 透传并“claim nothing”（不声称任何缩减）。

只有当 CCR 的 Put 成功后，res.Output 才被替换为压缩结果——注释（engine/engine.go#L126-L134）强调“调用方绝不能拿到没有持久化 handle 的变换字节”。

Simulate（engine/engine.go#L142-L202）镜像了 Compress 的全部透传条件，唯一刻意差异：对没有 store 的 S4 压缩器，Compress 会 fail closed 到透传，而 Simulate 仍然报告“本可实现的缩减”并置 Recoverable=false，明确告诉调用方“需要先配置 CCR 才能发布该变换”。

Retrieve（engine/engine.go#L247-L266）值得注意的设计：CCR 存储维护两个 id 空间——压缩产生的 blob handle（ccr_…，走 store.Get）和 native runtime 工具输出掩码产生的类型化 OBJECT id（显示为 ccr://<id>，走 store.GetObject）。一个查不到 blob 表的 handle 会 fall through 到 object 表再判定失败，因为“一个无法解析的 handle 会诱发反复的检索尝试，而失败的检索结果本身又是可被掩码的对象”——恢复路径绝不能指向另一个死指针。

result.go：Result / Options / Mode

engine/result.go 定义了单次调用的配置与结果类型：

• Mode：只有 record 与 compress 两个合法值。normalized()（engine/result.go#L36-L44）中，空值或任何未知 mode 一律归一化为 record——这就是“unknown mode fails closed to record”的实现。record 是默认模式，输出与输入字节完全一致且不存储任何恢复记录。
• Options 还有三个字段：Type（强制内容类型，空则自动检测）、Query（非空时让实现了 QueryAwareCompressor 的压缩器按相关性偏向保留内容，确定性 BM25、无 embeddings；未实现该接口的压缩器完全忽略它）、ExternalRecovery（允许嵌入网关在 Engine 本地 CCR 之外提供字节级恢复，仅当调用方在转发压缩字节前已自行存好原文时才可使用）。
• Result 的关键字段：ContentType、TokensBefore/TokensAfter（本地估算）、TokenCountBasis（估计器名称）、Ratio（0..1，透传时为 0）、Basis（恒为 inferred）、RecoveryHandle（透传时为空）、Method（压缩器选定的具体变换）、LosslessToModel（模型可见输出是否未丢弃任何数据）。PassedThrough() 用三个条件联合判定：RecoveryHandle == "" && Method == "" && Ratio == 0。

detect.go：内容路由器

engine/detect.go 是确定性的内容分类器，注释明确其策略是 fail-open：任何没有把握的输入都归为 text，路由到保守压缩器。检测顺序为：严格 JSON（以 { 或 [ 开头且 json.Valid）→ terminal → diff → HTML → tabular → code → log → search-result → config，兜底 text。

源码中可见的具体信号（engine/detect.go#L27-L38）：

• terminal：原始 ANSI/CSI 转义序列是“结论性”信号（只有终端输出会合法地携带它），因此 terminal 判定先于 diff/code/log 执行；次要信号是连续的裸 \r（进度条原地重绘，CRLF 文本被排除）；
• diff：至少 4 处 ^(diff --git |@@ |--- |\+\+\+ |[+-][^+-]) 匹配，且含 \n@@ 、diff --git 或成对的 --- / +++ 之一；
• code：若输入被判定为 log（日志行以 level 词或时间戳为主导），即使消息里含 return/class 等关键字也路由到 log 压缩器——注释称这是“最有价值的 misroute 修复”；
• 此外还有 #!/ shebang 前缀、代码关键字/符号计数等辅助信号。

Detect 之前会先调用 unwrapInput 剥掉 agent 文件标签与行号 gutter（见下节），注释解释得很直白：“分类文件是什么，而不是 agent 怎么打印它”。

listing.go：行号 gutter 的剥离与还原

engine/listing.go 解决了 Agent 场景下的一个隐蔽问题：Agent 递给 Engine 的不是文件本身，而是它的 read 工具打印出来的“带行号清单”（如 1\t{、2\t "unit"）。行号 gutter 是表现层（presentation）而非内容，但若不剥离，JSON 文档因不再以 { 开头而无法通过 json.Valid，源码因不可解析而无法进入 code 压缩器——两类载荷统统落入 text，压缩率约 0%。

• unwrapListing（engine/listing.go#L25-L31）在 Detect 和压缩器之前剥掉 gutter；不是清单输入时返回原输入和 no-op wrapper，调用方无需分支。
• rewrap（engine/listing.go#L40-L49）在压缩后按每行幸存的原始行号还原 gutter，保证行号仍指向 Agent 读到的那个文件。
• 关键决策：对于重构型（restructure）而非省略型（elide）变换（如重新编码的 JSON），还原被整体拒绝，返回裸的压缩体。注释给出的理由值得品味：“描述什么都没有的行号，还不如没有行号”（numbers that describe nothing are worse than none），且载荷本身已携带 CCR 标记表明它被变换过。

safety/：S0–S4 安全分级注册表

engine/safety/safety.go 是 Engine 的“诚实契约”所在：每个压缩器声明自己的安全类，且类别是压缩方法固有属性，不是用户选项。注册表集中回答两个问题：这个类是否改变模型可见字节？运行前是否需要一份可恢复记录？

源码中的完整登记表（engine/safety/safety.go#L43-L49）：

类	含义	ByteSafe	RequiresCCR	Reversible
S0	字节安全行为（元数据、记账），模型可见字节零变化	true	false	true
S1	provider 原生提示（缓存、路由），模型可见字节零变化	true	false	true
S2	需要 SDK 配合的结构变化	false	false	true
S3	行为变化（路由、推理），Cloud 中 eval-gated	false	false	false
S4	lossy 结构压缩，改变模型可见字节：opt-in、必须可恢复（CCR）、并披露丢弃了什么	false	true	false（方法元数据可覆盖，如 lossless-to-model 的 TOON）

safety 是一个叶子包（不依赖 engine 核心），所以 engine core 与 compressors 都能引用它而不产生导入循环。Lookup 对未知类返回 ok=false，调用方一律 fail closed——这正是 AGENTS.md 中“Unknown class → fail closed”的实现。

tokens/：离线 BPE 计数

engine/tokens/tokens.go 的包注释说明：默认计数器是真正的 BPE tokenizer（OpenAI o200k_base），词表内嵌在二进制中，因此计数确定且完全离线。Counter 接口只有 Count(b []byte) int 与 Name() string 两个方法，未来可为不同 provider 换装 tokenizer 而不触碰任何压缩器。Count 出错时回退到确定性的 ~chars/4 近似而非 panic（engine/tokens/tokens.go#L45-L56）。所有计数结果在 Result 中都标注 Basis: "inferred"。

contextwindow/：确定性 BM25 上下文打包器

engine/contextwindow/ 实现确定性 BM25 上下文打包，携带 recency / error / priority 信号并做 token 预算记账。Options.Query 触发的相关性偏置（如 caveman-engine retrieve <handle> [query] 只输出最相关片段）就建立在这一层之上——全程 BM25，无 embeddings。

compressors/：压缩器接口与注册表

engine/compressors/compressor.go 的包注释定义了压缩器的纪律：“压缩器是纯字节变换：它从不数 token、从不触碰 CCR、从不联网——这些都是 engine 核心围绕它做的事”。这使得每个压缩器都是自包含、可独立测试的模块，新增一个压缩器 = 新文件 + 测试。

核心接口（engine/compressors/compressor.go#L22-L31）：

type Compressor interface {
    ContentType() string
    SafetyClass() safety.Class
    // 任何解析问题返回 (nil-or-input, false)，调用方必须原样转发
    Compress(input []byte) (out []byte, ok bool)
}

可选能力接口有两个：MetadataCompressor（CompressWithMetadata(input, query) 报告逐结果的方法元数据）与 QueryAwareCompressor（CompressQuery(input, query)，空 query 必须与 Compress 行为完全一致，且 query 版输出永不允许比无 query 版更大）。engine 侧在 engine/engine.go#L204-L219 的 compressWith 中做类型断言分发，这是 Compress 与 Simulate 保持行为同步的单点。

默认注册表 Default()（engine/compressors/compressor.go#L90-L108）实际注册 15 个压缩器：JSON、log、code、diff、search-result、text、HTML、tabular、config、tool-schema、tool-schema annotations、TOON、accessibility-tree、repetition、terminal——engine/README.md 与源码一致地写的是 15（AGENTS.md 中“registers 14”的表述相对当前源码已偏旧）。其中：

• HTML 与 terminal 会被 Detect 自动检测命中；
• tool-schema、tool-schema annotations、TOON、accessibility-tree、repetition 是 forced-only（仅当调用方显式 Options.Type 强制时才可达），永远不会被 Detect 自动路由——这也是 Conventions 一节强调“forced-only 压缩器不得加入 Detect”的原因；
• code 压缩器在构建期二选一：cgo 启用时是 tree-sitter 版（Python/JS/TS 全量代码压缩），无 cgo 时是纯 Go go/ast 版（仅 Go）。

注册表还导出 CapabilityRegistry ABI（engine/compressors/compressor.go#L110-L200）：Capabilities() 以稳定 transform-ID 顺序输出确定性变换清单，CapabilityManifest() 生成规范化 JSON 并附 RegistrySHA256。未知安全类在此 fail closed——直接返回“无 capability”。

ccr/：SQLite 恢复存储

engine/ccr/store.go 的包注释给出 CCR 的定位：保存每一个 lossy（S4）压缩的精确原始字节，使 retrieve(handle) 字节级一致地返回原文——“引擎压缩的东西永远不会被销毁”。

• handle 是内容寻址的（原文的 sha256），使引擎幂等：同一载荷压缩两次得到同一 handle、只存一份；
• 平台分裂实现：宿主平台用本地 SQLite 库（store_sqlite.go，路径 ~/.caveman/ccr.db），js/wasm 下用纯 Go 内存 map（store_wasm.go，因为 modernc.org/sqlite 不支持 js/wasm 构建）。两者暴露相同类型与方法，engine 对此无感知；
• 未知 handle 是显式 miss（ErrNotFound），存储从不猜测恢复；
• ErrBudgetExceeded（engine/ccr/store.go#L31-L34）：新恢复在发布 lossy 字节之前被拒绝，因为本地库的 payload 预算会被超出；既有 handle 保持完整可检索，调用方必须透传。预算默认 512 MiB，可通过启动前设置 CAVEMAN_CCR_MAX_BYTES 为正字节数调整（见 engine/README.md）。

pixel/：文本 → PNG 请求压缩（S4-lossy，白名单门控）

engine/pixel/ 是 pxpipe 的移植（MIT 许可，见其 NOTICE）：text → PNG 的请求压缩，包含内嵌字形图集 + 渲染器 + 盈利性门控（profitability gate）+ 按 wire 格式的变换（Anthropic/OpenAI/Gemini）。其边界纪律在 AGENTS.md 中写得很严格：

• S4-lossy，且白名单门控：环境变量 CAVE_PIXEL_MODELS，默认 claude-fable-5,gpt-5.6；
• 由 proxy 的 pixel 模式消费；
• 从不接入 Detect，也从不被 WASM 构建导入（约 4 MB 资产）。

evals/：本地 eval 框架 + fail-closed 评分器

engine/evals/ 是本地 eval harness，Run() 是质量门。engine/evals/harness.go#L19-L34 显示 fixtures 通过 //go:embed fixtures 内嵌进二进制，manifest 中每个 fixture 由 payload 文件 + probes（保留度探针）+ graders + quality_graders 构成；支持强制内容类型（type）、模式（compress/record）与相关性 query。评分器同样是 fail-closed 的：未知 grader 返回 passed: false。另有 TransformRunner 接口，允许非 Caveman 系统走同一套 fixture、质量与报告路径。内嵌 fixtures 在 cgo 下覆盖全部三种代码语言（Python/JS/TS）——呼应 cgo gotcha。

cmd/caveman-engine/：CLI 二进制

engine/cmd/caveman-engine/main.go 是 CLI shell out 的二进制，子命令与 AGENTS.md 一一对应：

caveman-engine compress < input            # stdin → stdout，JSON 报告走 stderr
caveman-engine detect < input
caveman-engine retrieve <handle> [query]   # 带 query 时仅输出最相关段（BM25）
caveman-engine stats
caveman-engine registry                    # transform capability 注册表 JSON
caveman-engine toon encode | decode        # 无状态（no-CCR）JSON⇄TOON，双向 fail closed
caveman-engine pixel render | simulate
caveman-engine evals run [--fixtures DIR]

CLI 边界上继承的几条纪律（engine/cmd/caveman-engine/main.go）：

• 读取 stdin 的子命令强制 64 MiB 输入上限（maxStdinBytes，main.go#L40），超限以 cave_input_too_large 失败；
• compress 的 JSON 报告输出到 stderr，保持 stdout 是干净的有效载荷字节；CCR 失败时（cave_ccr_unavailable / cave_ccr_budget_exceeded）stdout 仍必须拿到原文字节，若引擎返回了任何与 pass-through 矛盾的 Result 则直接报错（main.go#L117-L144）；
• 调用方提供的 eval fixtures 被限制在 DIR 内，路径穿越与逃逸符号链接 fail closed。

开发约定（Conventions）

AGENTS.md 的 Conventions 一节规定了 Engine 的日常开发纪律，逐条都有源码对应：

1. 构建与测试。 在仓库内统一使用：

make product-build PRODUCT=engine
make product-test PRODUCT=engine

2. 新增压缩器的完整流程。 一个新压缩器是 compressors/ 下的一个自包含文件 + 配套测试，并在 Default()（engine/compressors/compressor.go#L90-L108）中注册。forced-only 压缩器（如 toolschema、toon）不得加入 Detect——detect.go 的分类顺序里也确实只有 JSON/diff/terminal/HTML/tabular/code/log/search/config 这些可自动检测类型。

3. 压缩器三不原则。 压缩器从不数 token、不碰 CCR、不联网——engine 核心在它们外面做这些（compressWith 只在压缩前后调用 counter.Count 与 store.Put）。

4. toolschema 变换目前是 client-side-only。 注册只是让 engine 调用方可以强制它，并不意味着它从 managed-gateway 流量可达：provider 适配器刻意把 tool 数组留在冻结的 prompt-cache 前缀中，没有任何计费路由调用该压缩器。Engine API/CLI 调用方可在本地强制它（caveman-shrink 是它的专属产品面），其缩减仍属本地且 inferred。managed gateway 另有独立的 S2 tool-search/deferral 路径，不得与压缩混为一谈。任何未来网关路由启用该变换前，需要 cache-versus-schema 成本算术、字节级稳定的前缀输出、以及一道 eval 门。

Gotchas：诚实性不变量（correctness, not style）

AGENTS.md 用“honesty invariants”命名这些 gotchas，强调它们是正确性要求而非风格偏好。每一条都可在源码中定位：

1. fail-closed transforms（字节安全）。 每个压缩器在任何解析问题上原样通过输入；engine 在结果 token 数不小时也原样通过。byte-safe 一词保留给 safety.Info.ByteSafe 为 true 的类（S0/S1）——不是每个通过透传纪律的压缩器都能自称 byte-safe。

2. CCR-or-pass-through。 lossy（S4）结果只有在原文已被存储时才会发布；没有 store 时 engine fail closed 到透传。实现见 engine/engine.go#L100-L102 与 engine/engine.go#L116-L131：CCR Put 失败时保留所有 pass-through 字段并返回错误，绝不让调用方拿到没有持久 handle 的变换字节。

3. inferred-only。 ratio 是标注 inferred 的 token 估算，永不 verified、永不再投射（re-project）到计费口径。Result.Basis 常量 BasisInferred = "inferred" 是唯一的取值。

4. 全链路 fail-closed 三件套。 未知 mode → record；未知内容类型 → text（fail-open 到保守压缩器）；未知 grader → passed: false。

5. cgo 边界。 完整的代码压缩（Python/JS/TS）需要 tree-sitter 构建；无 cgo 构建只压 Go。内嵌 eval fixtures 在 cgo 下覆盖三种语言（对应 engine/evals/cgo_on_test.go / engine/evals/cgo_off_test.go）。

6. 目录边界。 engine 位于 public/ 之下——永不 import cloud/…，由 make check-boundaries 强制执行。

使用与适配前提

• Engine 本地运行、无需 Caveman 账户；token 缩减是本地 o200k_base 估算、标注 inferred，不是 provider 账单或已验证的节省（engine/README.md）。
• 终端用户安装薄 CLI 后经本地运行时启动受支持的 Agent（Claude Code、Codex、Gemini、Aider、Hermes、OpenClaw、opencode 均有注册 profile）；当安全压缩路径不可用时，运行会收窄变换或以显式警告直连启动。
• 另有 CAVE_ENGINE_TOON=best-of 环境变量会向注册表额外注册 JSON 策略压缩器（engine/engine.go#L55-L61），属于默认注册表之外的实验开关。
• 许可：Engine 源码在 BSL 1.1 下发布，source-available 而非 OSI 开源（2030-06-21 Change Date 之前），允许第一方自托管生产使用；Agent SDK、薄 CLI、contracts、evals 等采用面是 MIT。

小结

Caveman Engine 的设计哲学在 engine/AGENTS.md 与各源码注释中反复出现：宁可透传也不冒进，宁可声明 inferred 也不宣称 verified。detect → route → compress → CCR 的四段流水线、S0–S4 分级对“是否改变模型可见字节 / 是否需要可恢复记录”的集中回答、15 个纯字节变换压缩器的注册纪律、以及 eval 质量门，共同构成了一个可本地验证、可恢复、边界清晰的上下文压缩核心。要深入，建议从 engine/engine.go 的 Compress 开始，沿 engine/compressors/compressor.go、engine/safety/safety.go、engine/ccr/store.go 逐层读下去，并用 make product-test PRODUCT=engine 与 caveman-engine evals run 验证每一处不变量。