Caveman 术语表技术解读：CCR、安全等级、证据基准与 TOON 等核心概念全解

本文基于仓库内的官方术语表 docs/technical/glossary.md，系统解读 Caveman（一个以"用更少 token 完成同样任务"为目标的 Claude Code 技能与代理压缩系统）中约 30 个核心术语。读完后你将理解：Caveman 如何通过内容寻址的 CCR 存储实现"有损但可恢复"的压缩、S0–S4 安全等级如何约束每一种变换、TOON/Pixel/Accessibility tree 三种紧凑编码的适用边界，以及 inferred/observed/verified 等证据基准如何保证项目发布数字的诚实性。

术语体系总览

Caveman 的术语表并不是一份普通名词解释，而是整个系统的"诚实契约"。它覆盖了五个层面：

1. 压缩与恢复管线：Compressor、Safety class、Byte-safe、CCR、Recovery handle、Fail closed、Record mode；
2. 数据编码形态：TOON、Pixel、Accessibility tree；
3. 代理与传输：Wire protocol、MCP、SSRF；
4. Agent 集成：Agent profile、Hook、Skill、Context pack；
5. 证据与数字：Basis、Inferred、Observed、Provider-reported、Verified、Headroom、List-price subtotal、Unpriced，以及产品侧的 Cave Plan、Cave Score、Caveman Cloud。

这套术语与 docs/technical/accounting-and-evidence.md 中的证据规范一脉相承：Caveman 要求任何数字都必须标注"它是如何产生的"，术语表正是这条纪律的词汇基础。

压缩管线：Compressor、Safety class 与 Byte-safe

Compressor（压缩器）

术语表定义：将一种被识别的输入形态变换为更小的模型可见表示的 Engine 组件，且必须在声明的策略下执行。在仓库中，压缩器集中在 engine/compressors/ 目录，按输入形态划分：json.go（结构化 JSON）、html.go（HTML）、log.go（日志）、terminal.go（终端输出）、searchresult.go（搜索结果）、tabular.go（表格）、code_cgo.go/code_nocgo.go（代码）、toolschema.go（工具 schema）等，每种形态对应一个独立的压缩策略文件。

Safety class（安全等级）

术语表指出：安全等级描述变换的风险类别，当前 Engine 的压缩器均使用 S4——"有损但可恢复"（lossy with recovery）。这一概念在源码 engine/safety/safety.go 中有完整实现：引擎维护一条 S0–S4 的安全阶梯，每个压缩器必须声明自己的等级，且等级是压缩方法固有的，不是用户可选项。

从源码的注册表可以看到每一级的诚实契约（engine/safety/safety.go#L43-L49）：

等级	含义	ByteSafe（不改模型可见字节）	RequiresCCR（必须先落 CCR 存储）	Reversible（无丢失可逆）
S0	字节安全行为（元数据、记账）	是	否	是
S1	Provider 原生提示（缓存、路由）	是	否	是
S2	需要 SDK 配合的结构变更	否	否	是
S3	行为变更（路由、推理）；Cloud 中受 eval 门控	否	否	否
S4	有损结构压缩：修改模型可见字节，必须 opt-in、可恢复（CCR）、并披露丢弃了什么	否	是	否

Info 结构体中的三个布尔字段正是术语表三个词条的落地：ByteSafe 对应 Byte-safe、RequiresCCR 与 S4 的关系对应 CCR、等级本身对应 Safety class。注册表对未知等级采取 Fail closed 策略：Lookup 对未登记等级返回 false，调用方将未知等级视为"不可安全运行"（engine/safety/safety.go#L51-L56）。

Fail closed（失败关闭）

术语表定义：未知或无效状态拒绝操作，或产生安全的非成功结果；对变换而言，安全结果通常是原始输入。这条原则贯穿仓库，例如 CCR 存储对未知句柄"从不猜测恢复"，而是返回显式的 ErrNotFound（engine/ccr/store.go#L27-L29）。

Byte-safe 与 Record mode

• Byte-safe：模型可见字节保持不变，例如 Record mode 下。压缩、TOON、Pixel、改写都不是字节安全的。
• Record mode（记录模式）：只观察本地流量、不修改模型可见请求字节的透传模式。

Proxy 文档 proxy/doc.go 明确"record mode 永远是 pass-through"，且 proxy/internal/config/config.go#L63 注释说明：record 模式下保持字节安全透传、savings_usd 保持 0。测试 proxy/internal/gateway/auth_fallback_test.go#L234-L238 直接验证了这一点：记录模式下请求体必须与原始请求逐字节一致，且原始请求与"变换后"请求的 SHA256 哈希必须相同——这是"字节安全"最直接的自动化证据。

CCR 与 Recovery handle：可恢复压缩的实现

CCR（Caveman Context Recovery）

术语表定义：内容寻址存储，把紧凑引用映射到精确的原始字节或类型化对象。其实现位于 engine/ccr/，包注释（engine/ccr/store.go#L1-L14）说明了设计要点：

• 字节精确：保存每一次 S4 有损压缩的原始字节，retrieve(handle) 逐字节返回原文，"引擎压缩过的任何东西都永不被销毁"；
• 内容寻址：句柄是原始内容 SHA256 的编码，压缩同一 payload 两次得到同一句柄、只存储一次，天然幂等；
• 平台分治：主机平台使用本地 SQLite（engine/ccr/store_sqlite.go），js/wasm 环境退化为纯 Go 内存 map（engine/ccr/store_wasm.go），两者暴露相同接口，引擎对差异无感知。

CCR 除了裸字节 blob 之外还管理类型化对象，ObjectType 是一个封闭枚举，包含 FileObservation、SearchResult、CommandResult、TestResult、BuildResult、DiffSnapshot、TaskContract、TaskDecision、ExecutionState、DocumentationExcerpt、BrowserSnapshot、RepositoryMap、EvidenceBundle 共 13 种（engine/ccr/store.go#L41-L55）。未知类型直接报错，不发明检索语义——这同样是 fail-closed 的体现。对象还带有 currentness（current/stale/archived）与 lifecycle（hot/warm/cold/archived）状态字段。

Recovery handle（恢复句柄）

术语表定义：形如 ccr_... 的内容派生标识符，用于取回精确的原始字节。源码中生成为 "ccr_" + sha256 前 16 字节十六进制（engine/ccr/store.go#L216），类型化对象则是 ccr_obj_ 前缀（engine/ccr/store.go#L144）。句柄未知时返回 ErrNotFound，存储"从不猜测恢复"。

此外还有防御性约束：ErrBudgetExceeded 表示在发布有损字节之前因本地存储预算超限而拒绝新的恢复记录，已有句柄保持可取回，调用方必须透传原文（engine/ccr/store.go#L31-L34）——即"存不下恢复记录时，宁可不压缩"，从机制上保证 S4 的"可恢复"承诺不被破坏。

三种紧凑编码：TOON、Pixel 与 Accessibility tree

TOON（Token-Oriented Object Notation）

术语表定义：面向 token 的对象表示法，一种针对合适结构化数据的紧凑文本编码。它会改变模型可见字节，且绝不用在工具调用参数上。TOON 压缩器实现在 engine/compressors/toon.go：它把 JSON 解析为 v 后编码为以逗号分隔的紧凑文本，解析失败直接返回 false（fail closed，交回原文）。值得注意的是它声明的安全等级是 S4，同时通过元数据标注 LosslessToModel: true（engine/compressors/toon.go#L26-L28）——即"字节层面有损、模型语义无损"的重编码。注释还说明 TOON 只能由显式指定 Options.Type = "toon" 时触发，自动检测（Detect）从不路由到它。

Pixel

术语表定义：面向明确允许使用视觉能力模型的、有损的"文本转 PNG"上下文编码。对应实现位于 engine/pixel/ 目录，包含渲染（render.go、png.go）、不同 provider 的变换（transform_anthropic.go、transform_openai.go、transform_gemini.go）、适用性判断（applicability.go、gpt_profiles.go）与定价核算（pricing.go）等。由于它是术语表中的"explicitly allowed vision-capable models"这一前提，源码中专门设有 gate（gate.go、gate_test.go）与适用性检查来确保只在允许的模型画像上启用。

Accessibility tree（可访问性树）

术语表定义：浏览器提供的页面角色、名称、状态与关系的语义表示。当无需视觉像素时，Caveman 浏览器桥接将其用作完整页面标记的紧凑替代。该能力的证据链横跨两个包：浏览器桥接在 browse/ 目录（cdp.go 经 CDP 读取真实 Chrome 可访问性树），压缩策略在 engine/compressors/axtree.go。browse/BENCHMARK.md 记录了以 Playwright ariaSnapshot() 为基线的对比测量，显示可访问性树快照相比完整页面标记可减少 96% 以上的文本量（该文件给出的实测基线数据，仅对所述 fixture 有效）。

代理、传输与集成概念

Wire protocol（线路协议）

术语表定义：Agent 与代理之间使用的 Provider 请求/响应形态，例如 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions、Gemini GenerateContent。仓库中 proxy/providers/ 目录按协议组织适配器：anthropic/、openai/（含 Chat Completions 与 Responses 形态）、gemini/、bedrock/、vertex/、azureopenai/、openaicompat/，并配有 adapter_contract_test.go 等契约测试保证各协议适配行为一致。理解"wire protocol"是理解 Caveman 在哪里插入压缩/改写的关键：所有变换都发生在这一层请求形态之上，且受安全等级约束。

MCP（Model Context Protocol）

术语表定义：Caveman 使用本地标准 I/O（stdio）服务器，把压缩、恢复、统计和 TOON 操作暴露给兼容 Agent。实现位于 mcp/：mcp/server.go#L1-L6 说明它是一个 stdio JSON-RPC 适配器，独占 stdout 承载协议（日志只能走注入的 logger），且"不打开任何网络连接"。两处设计细节值得注意：

• 入站行与单条结果各有 16 MiB 上限，超限以 fail-closed 错误 cave_payload_too_large 拒绝，而不是无限缓冲（mcp/server.go#L24-L32）；
• ExemptResultCap 标记：恢复路径（caveman_retrieve）返回的是精确原始字节，绝不允许被结果上限截断——因为 CCR 存储与网关共享，原文可能合法地超过上限，若 fail-closed 截断会导致"被省略的内容永远无法恢复"（mcp/server.go#L40-L47）。这与 Recovery handle 词条首尾呼应。

SSRF（Server-Side Request Forgery）

术语表定义：服务端请求伪造。风险在于可配置的外发 URL 让调用方触达非预期的本地或私有服务。仓库在 shared/platform/ssrf/ 提供对应防护实现，属于平台层公共依赖。

Agent 集成三件套：Agent profile、Hook、Skill、Context pack

Agent profile（Agent 档案）

术语表定义：声明式描述 CLI 如何启动和配置受支持的 Agent，包括线路协议与端点注入，以及任何 hook、skill 或插件。档案文件位于 agents/profiles/，包含 claude.json、codex.json、gemini.json、aider.json、hermes.json、opencode.json、pi.json、openclaw.json 等具体档案，以及约束其结构的 schema.json。相关设计见 docs/technical/agent-profile-registry.md。

Hook（钩子）

术语表定义：由 Agent 生命周期事件触发的代码，例如会话开始、prompt 提交、工具执行前。仓库的 hook 实现集中在 src/hooks/：caveman-activate.js（激活）、caveman-mode-tracker.js（模式跟踪）、caveman-stats.js（统计）、状态行脚本 caveman-statusline.sh/.ps1 及安装/卸载脚本。

Skill（技能）

术语表定义：改变模型行为或响应风格的指令包；除非附带单独评审过的 hook 或工具，它本身不是可执行运行时。skills/ 目录即是一组这样的指令包：caveman/、caveman-commit/、caveman-compress/、caveman-explore/、caveman-review/ 等，各含 SKILL.md。仓库根部的技能 caveman 正是项目名"以穴居人说话方式减少 65% token"这一核心体验的载体；注意术语表特意划出的边界——Skill 是行为指令而非运行时，这与 Hook（生命周期代码）和 MCP 工具（真实执行）形成清晰分工。

Context pack（上下文包）

术语表定义：用于组装带来源（provenance）与策略的、有界上下文部分的 SDK 结构。从源码结构看，engine/contextwindow/ 目录实现了确定性的 BM25 上下文打包器，带 recency/error/priority 信号与 token 预算核算（engine/CLAUDE.md 中的目录说明），打包器使用固定参数的 BM25（k1=1.5, b=0.75）、无嵌入、无网络依赖（engine/contextwindow/contextwindow.go#L174）。SDK 侧的 context pack 用法见 docs/technical/sdks-and-packages.md。

证据与数字：Basis 体系

术语表用七个词条构建了一套"数字必须自证出身"的词汇系统，与 docs/technical/accounting-and-evidence.md 的基准表一一对应：

术语表词条	含义	不是什么
Basis	解释数字如何产生的标签（inferred、provider-reported、benchmark counterfactual、verified 等）	——
Inferred	由本地模型、tokenizer 或假设估算，而非 Provider 或验证方法确认	不等于 Provider 确认用量
Provider-reported	模型 Provider 响应返回的用量或事件数据	不等于独立账单核对
Observed	记录了 before/after 关系，但控制不足以确立因果	不等于"变更导致了差异"
Verified	保留给满足具名、强制执行的验证方法的值	不等于普适质量或未来节省
Headroom	被建模的上下文/成本削减机会，在更强证据出现前都是 inferred	不是承诺节省
List-price subtotal	用量单位 × 带日期的公开目录价	不是 Provider 发票
Unpriced	标记目录中没有受支持的公开价；数值回退为 0 以避免虚构成本，但不代表资源免费	不等于零真实成本

几个关键细节值得展开：

• Verified 的排他性：术语表强调"本地压缩估算本身不算 verified"。配套文档进一步列出：公共本地运行时不应把 Engine 估算、skill 输出、pixel 转换、TOON 输出、缓存计划或合并后的代码自行标记为 verified（docs/technical/accounting-and-evidence.md#L73-L78）。
• Unpriced 的双重保护：零值防止"虚构成本进入合计"，unpriced 标签防止"零被误认为免费使用"——一个标记同时完成两件防误读工作。
• 发布前检查单：文档给出七步清单，包括指明证据基准、链接已提交的 fixture、披露计数方式与定价日期、区分目录价与发票、以及"无支持时发布 0 或 unpriced"（docs/technical/accounting-and-evidence.md#L89-L99）。项目当前受支持的公开声明汇总于 docs/HONEST-NUMBERS.md。

产品侧术语：Cave Plan、Cave Score 与 Caveman Cloud

• Cave Plan：连接型产品的报告，按可能效率提升排序。计划项是提案，不建立已验证的节省——这条限定词与 Verified 词条互为支撑，防止"计划中的节省"被误读为"已实现的节省"。
• Cave Score：连接型产品在其已发布契约下总结实测效率信号的分数。它与本地 Engine 的 token 削减是不同概念——本地压缩率（inferred 基准）与产品分数不可混用。
• Caveman Cloud：可选的连接型账号、证据与治理服务。本地压缩不依赖它——这一条划定了本地能力与云服务的能力边界：整套 Engine、CCR、MCP、record 模式都是本地运行的。

小结：术语背后的设计纪律

回看整份术语表，所有词条共同服务于三条可验证的工程纪律：

1. 变换必须分级：每个 Compressor 声明 S0–S4 安全等级（engine/safety/safety.go），S4 有损压缩强制绑定 CCR 恢复记录，存不下就不压缩（engine/ccr/store.go）；
2. 字节安全是默认真相：Record mode 逐字节透传并有哈希相等的测试保障（proxy/internal/gateway/auth_fallback_test.go），TOON/Pixel/压缩则显式声明自己不是字节安全的；
3. 数字必须带出身：任何统计值都标注 Basis（inferred/observed/provider-reported/verified/unpriced），0 值必须伴随 unpriced 标记而非静默消失。

对开发者而言，掌握这套术语意味着能准确回答三个高频问题：压缩会不会弄丢我的数据（S4 + CCR：不会，可逐字节取回）？本地模式会不会上传流量（Caveman Cloud 是可选的，record mode 逐字节透传）？项目宣称的百分比节省是怎么算出来的（Basis 体系 + docs/HONEST-NUMBERS.md 的公开声明边界）。