Caveman 共享契约层解析：用 JSON Schema 2020-12 固化租户策略、实践库与适配器一致性证据

本文以 packages/shared/contracts/AGENTS.md 为骨架，系统讲解 Caveman 项目中"共享线契约"（shared wire contracts）这一包的设计与实现：它如何用 JSON Schema 2020-12 定义跨服务、跨 SDK 的数据形状，如何用 AJV 编译校验与静态 fixture 交叉验证来守住契约边界，以及围绕 capabilities、runtime_mode、fail_policy 等关键字段的一系列"诚实性规则"（unknown 值 fail closed、派生而非输入、字节安全直通）。读完本文，你可以理解如何为一个多服务、多 SDK 的 LLM 优化系统建立单一事实源的线格式契约，并复用其"无编译产物、校验即测试"的工程模式。

契约包在 Caveman 中的定位

Caveman 是一个以"少 token"为核心理念的 LLM 上下文压缩与优化系统（项目描述即 "why use many token when few token do trick"）。在这样一个系统中，多个组件——网关、控制面、SDK、web 看板——都需要读写同一批线格式对象：租户策略（tenant policy）、实践库记录（practice record）、适配器一致性记录（adapter conformance record）。这些对象如果在各端各自用 Go struct、TypeScript interface 手写，版本漂移几乎是必然的。

packages/shared/contracts/AGENTS.md 开篇即给出该包的定位："Source-of-truth schemas for cross-service/SDK wire shapes"——跨服务/SDK 线形状的单一事实源。包内 @caveman/contracts（见 package.json）本身不发布任何可执行代码或生成物：build、lint、test 三个脚本全部指向同一条校验命令 node scripts/validate-schemas.mjs，且 devDependencies 只有一个依赖 ajv@8.20.0。也就是说，这个包的价值全部体现在"把契约写死、把漂移挡在 CI 之外"。

目录布局

AGENTS.md 的 Layout 小节列出的结构在仓库中完整存在（packages/shared/contracts 下）：

• schemas/policy.schema.json — 租户策略对象的 JSON Schema 2020-12 定义
• schemas/practice.schema.json — 单条实践库记录的严格 schema
• schemas/adapter-conformance.schema.json — 静态 Pi/Claude 契约记录形状
• scripts/validate-schemas.mjs — 用 AJV 编译所有 schema、校验适配器 fixture、比对共享静态契约字段
• package.json — build/lint/test 均运行 schema 校验（无编译产物）

实际仓库中 schemas/ 目录还包含更多契约（如 canonical-span.schema.json、agent-run-receipt.schema.json、continuous-improvement-report.schema.json、grader-registry.schema.json 等），CHANGELOG.md 记录了 1.1.0 版本新增 grader 注册表并把校验扩展为"解析 schemas/ 下每个文件、用同目录 schema 校验每个数据文件"的演进。本文按 AGENTS.md 的骨架聚焦三大核心 schema，其余文件作为演进事实提及。

policy.schema.json：租户策略的完整字段解剖

policy.schema.json 是契约包的核心。它声明 required: ["version", "runtime_mode", "fail_policy", "providers", "limits", "retention", "optimizers", "sdk", "telemetry"]，且顶层 additionalProperties: true——这是 AGENTS.md 特意强调的有意为之：服务与优化器可以扩展该对象。

capabilities：无序的能力集，而非阶段

capabilities 是 { compress?, cache_hints?, routing? } 三个布尔位，AGENTS.md 强调它是"An unordered SET, not a stage — the three compose"——三个能力相互组合，没有先后阶段含义。

关于 additionalProperties，这里有一个值得注意的细节：AGENTS.md 文字描述为 additionalProperties: false，但当前 schema 源码（policy.schema.json 第 11 行起的 description）写的是 additionalProperties: true，并附了一段完整的设计说明：这是前向兼容的授权集（forward-compatible grant set），因为控制面与网关独立部署——若设为 false，控制面一旦签发新能力键，它发布的每个策略都会让仍运行旧 schema 的网关校验失败；而"读者只授予自己认识的能力"，未知键永远不会扩大权限。schema 说明还诚实注明：本仓库中没有任何运行时用该 schema 校验策略，Go struct 解码本就忽略未知字段，validate-schemas.mjs 只检查 schema 本身是合法 JSON Schema；这个字段是发布给集成方的契约，所以改的是"告知集成方可以发什么"，而不是"放开了某个检查"。

pass_through 与 runtime_mode：派生字符串与兼容性窗口

两个字段共同构成策略文档"到底做什么变换"的判定逻辑：

• pass_through（boolean）：禁止一切变换，且优先级高于 capabilities。capabilities 之所以保留，是为了让操作员开关（operator toggles）保持其记忆中的位置——即关掉所有能力后，用户重新打开某个开关时不会丢失上下文。
• runtime_mode：枚举 record | recommend | shadow | canary | active | compress，但它是一个派生的展示字符串，不是输入。它仍在 required 中，是为了兼容性窗口（AGENTS.md 标注 removal 2026-10-01），因为 projects.runtime_mode 和 telemetry 写入校验器仍在读它。规则是双向的：
  • 文档带 capabilities 时以 capabilities 为权威，runtime_mode 从它派生；
  • 文档只带旧式 runtime_mode 时，能力集从 runtime_mode 派生。

AGENTS.md 的 Gotchas 小节给出了三条关于 runtime_mode 的强约束，是理解该字段的关键：

1. 六个值不是有序的。任何对其做大小比较的代码（mode >= "canary"）都是 bug；
2. 中间四个值行为上完全一致，shadow/canary 只是展示标签，不是流量切分；
3. 派生逻辑只允许存在于一处（文档指向 cloud/internal/capability，这是 AGENTS.md 引用的云端仓库路径，不在本开源仓库内），因为网关、控制面、worker 三者绝不能对同一份文档的含义产生分歧。

fail_policy 与诚实性规则

fail_policy 枚举 fail_open | fail_closed，AGENTS.md 明确：未知值 fail closed（honesty rule）——与整个仓库的诚实性规则对齐：未知枚举值必须失败关闭，而不是放行。这与 runtime_mode: record 永远是直通（byte-safe rule）、绝不应被当作优化器模式处理，共同构成"宁可不动、不可乱动"的安全基调。

providers 与 limits

从 policy.schema.json 源码看：

• providers 要求 allowed（枚举 openai | anthropic | gemini | azure_openai | openai_compatible 的数组）、allowed_models（字符串数组）、allowed_regions（字符串数组）三项齐备——租户策略显式约束允许触达的模型提供商、模型名与区域。
• limits 要求五个字段：max_request_bytes、max_artifact_bytes、requests_per_minute、concurrent_requests、monthly_usd。其中 limits.monthly_usd 就是 AGENTS.md 点名的每租户 { soft, hard } 双档支出上限。
• schema 中还包含 spend_rate_usd（咨询性速率配额）：其 description 写明计数器是"响应后滚动下界（post-response rolling lower bounds）"，Valkey 错误时 fail open，soft_block 不是原子化的账单硬顶；且 if/then/else 条件约束了"只要任一配额大于 0，窗口必须 ≥ 60 秒；否则窗口必须为 0 且 soft_block 必须为 false"——这种结构性互斥约束直接编码进 schema，而不是留给运行时约定。

telemetry 与可选扩展字段

• telemetry 要求 metadata_enabled、raw_payloads_enabled、sample_rate 三项；AGENTS.md 特别指出 sample_rate 是 0–1 的浮点数，由 schema 的 minimum/maximum 校验（源码中确为 "minimum": 0, "maximum": 1）。
• 可选的 compress 对象允许 method: auto | elision | toon 与 pixel_density: conservative | balanced | max，对应 Caveman 引擎的压缩方法与像素密度档位（与本仓库 engine/compressors 中的 toon/压缩实现相呼应）。
• task_profiles 为按任务族的优化约束（质量下限、级联参数、粘性策略、数据驻留等），runtime_policies 则是面向 SDK 调用方的可选运行期策略数组：其 guard 操作符是闭集（eq|ne|gt|gte|lt|lte|in，AND 语义），未知 op、缺失字段或类型不匹配一律使条件在客户端判为 FALSE（绝不为 true）；budget 是调用方自行执行的咨询性上限，"never measure, claim, or imply a saving"；结构性非法的条目在渲染时整条丢弃而不是剥掉坏 guard——因为任何局部剥离都会扩大策略的适用范围。

practice.schema.json：严格 fail-closed 的实践库记录

practice.schema.json 与 policy schema 的宽松取向恰好相反：顶层 additionalProperties: false，AGENTS.md 称之为"strict JSON Schema 2020-12 for one practice record; unknown fields and enums fail closed"。

一条实践记录要求 11 个必填字段，构成一个完整的"证据链"结构：

字段	约束要点（源自 schema 源码）
id	字符串，模式 ^[a-z0-9]+(?:-[a-z0-9]+)*$（kebab-case）
family	枚举：input_bloat, cache, reliability, routing, pixel_density, labeling
title	非空字符串
predicate	{ harness[], payload_shape, wire_protocol[] }；harness 枚举含 claude-code, codex, gemini, opencode, hermes, openclaw, any；wire_protocol 枚举 anthropic, openai, gemini, any
fix	{ prose, apply } 均非空
grader	{ type, fixture_template }；type 是 16 种评测器的闭集枚举（exact_match、token_threshold、cost_threshold、llm_judge 等）
experiment	{ method, metric }；method 枚举 trial, replay, shadow, canary, local_ab
evidence	status 为 const unmeasured——任何实践记录在入库时都必须诚实标注"未测量"
never_claim	非空字符串：明确写下这条实践"绝不允许声称"什么
skill_render	{ eligible, skill_name }，skill 名同为 kebab-case 模式
cave_agent	{ pr_shape, scope_hint }；pr_shape 枚举 config_change, code_change, instrumentation, none
sources	≥1 个非空、去重字符串

这套设计的意图非常清晰：evidence.status 被钉死为 unmeasured，加上必填的 never_claim 字段，意味着实践库在契约层面禁止任何"已验证的节省"声明——这与 AGENTS.md 反复出现的"honesty rule"一脉相承。可选字段 proposed_optimizer 甚至是一个 const: true，只允许显式出现。

adapter-conformance.schema.json：静态契约记录与"拒绝可执行证明"

adapter-conformance.schema.json 定义的是"静态 Pi/Claude 契约记录形状"。其最突出的设计是两个字段的 const 约束：

• evidence: "static_contract_only"——schema 描述原文："Shape agreement only. This record is not executable runtime-parity evidence." 即该记录显式否认自己是可执行的一致性证明，只证明形状一致；
• accounting_method: "provider_reported_public_catalog"——计价口径恒为"提供商报告的公开目录价"；
• failure_fallback: "original"——失败回退恒为保留原始字节，与 policy 侧的 byte-safe 规则呼应。

记录还包含 normalized_context_digest、plan_sha256、build_sha256、provider_visible_digest 四个 SHA-256 摘要（$defs.sha256 模式 ^[0-9a-f]{64}$）、有序的 ordered_transform_ids 数组与 recovery_handles 数组，以及 harness 枚举（pi, claude, vercel-ai-sdk, eve, mastra）。

静态 fixture 与交叉校验

fixtures/agent/claude-conformance.json 与 fixtures/agent/pi-conformance.json 是两条真实的契约记录。以 claude fixture 为例，它声明了有序的变换管线 caveman.cache-preserve.v1 → caveman.tool-search.v1 → caveman.ccr-results.v1，以及一个 cave_ccr_sha256:... 恢复句柄。

validate-schemas.mjs：校验即测试的工程闭环

scripts/validate-schemas.mjs 是整个包的执行核心，其逻辑可以完整走读：

1. 枚举并解析：读取 schemas/ 下所有 *.schema.json，要求每个文件的 $schema 必须是 https://json-schema.org/draft/2020-12/schema、且带非空 $id，否则直接抛错；
2. AJV 严格编译：new Ajv2020({ allErrors: true, strict: true })，把所有 schema addSchema 后逐一 getSchema 确认编译成功——strict 模式意味着任何未知关键字、非标准写法都会让编译失败；
3. fixture 数量断言：fixtures/agent/ 下必须恰好 2 个 JSON fixture，且必须分别覆盖 harness: "claude" 与 harness: "pi"；
4. 共享契约字段比对：逐字段 JSON 序列化比较两份 fixture 的 normalized_context_digest、plan_sha256、ordered_transform_ids、provider_visible_digest、recovery_handles、accounting_method、failure_fallback——任何一处不一致即抛错，从而在 CI 层面机械地强制"两个适配器对同一输入产生同一归一化结果"；
5. 特异性断言：build_sha256 必须不同（适配器各自的构建指纹不可互相抄），且 failure_fallback 必须为 "original"（未知适配器失败必须保留原始字节）。

脚本最后打印的日志也再次点题：validated N JSON schemas and 2 static agent contract fixtures (not executable parity)——"不是可执行一致性"。

package.json 把 build、lint、test 全部映射到这一条脚本，因此任何 CI 阶段触碰该包都会触发 schema 编译 + fixture 交叉校验，而没有编译产物可言。这正是 AGENTS.md 强调的 gotcha："Build script validates schemas and static fixtures; it emits no artifact and does not prove executable Pi/Claude parity"。

约定与升级规则（Conventions）

AGENTS.md 的 Conventions 小节给出了契约演进的三条纪律：

1. schema 版本是整数。policy.schema.json 中即 version: integer, minimum: 1。文档还指出控制面 API 的 policy_schema_version 字段（指向 cloud/control-api/internal/httpapi/server.go:372，此为 AGENTS.md 引用的云端仓库坐标）会向客户端回发该版本号。
2. 新增必填字段是破坏性变更——必须 bump version，并跨 control-api、SDK、web 三方协调。
3. 尚未从 schema 生成 TypeScript 类型；web 看板是手工镜像该形状。CLAUDE.md（同包的姊妹文档）补充了第四点：仓库根部的 scripts/check-contract-compat.mjs（经 make check-contract-compat 调用）是一个有边界的 2020-12 兼容性门——它能证明"共同收窄"类约束（类型、枚举/常量、边界、对象/数组适用器及支持的组合器/引用）不破坏旧版读者，把未知断言/适用器关键字或引用语义变化标记为需要大版本评审；它刻意不是完整的 JSON Schema 蕴含（subsumption）证明器，元数据注解变化保持非破坏。需要说明的是，该脚本与 cloud/ 目录均属于 AGENTS.md 所引用的仓库坐标，未在本开源子树中出现，引用时应以其在文档中的记载为准。

CHANGELOG.md 则提供了版本事实：1.0.0（2026-07-26）"记录了稳定的 JSON Schema 线契约基线"，并加入了对删除属性、新增必填字段、收窄枚举、删除 schema、变更 schema ID 的大版本门；1.1.0 同日追加 grader 注册表并将校验扩展为全目录数据文件校验，且明确"Additive only; no existing schema changed"。

对工程实践的启示

从源码结构与文档对照看，Caveman 契约包提供了几条可直接借鉴的模式：

• 校验即测试、无产物包：一个只含 schema + fixture + 校验脚本的 npm 包，让 build/lint/test 三态合一，契约漂移在 CI 中即失败，且不产生任何需要同步发布的生成物。
• 严格度分档：面向外部集成方、需要前向兼容的策略对象用 additionalProperties: true；面向内部、需要 fail-closed 的实践记录用 additionalProperties: false。严格度不是一刀切，而是按"读者是谁"设计。
• 诚实性编码进 schema：evidence: const "unmeasured"、never_claim 必填、evidence: "static_contract_only" 显式否认可执行证明——把"不许过度声称"从文化约定变成结构约束。
• 单点派生：像 runtime_mode 这类展示字段，其派生逻辑被强制集中在唯一一处，消除多服务间语义分歧的根源。
• fixture 交叉断言：不满足于"每个 fixture 各自合法"，还断言跨 fixture 的共享字段相等、特异性字段（build_sha256）不等——用 JSON 序列化的相等性比较实现"形状一致性"的机械验证。

这套契约层与 Caveman 的压缩引擎（engine 下的 compressor、toon 等实现）、代理网关（proxy）、SDK 包（packages/sdk）共同构成一个"契约定义形状、引擎负责执行、网关负责执行前校验"的分工结构。对于需要在多服务、多 SDK 场景下治理 LLM 流量与租户策略的系统，packages/shared/contracts 提供了一个以小体量 JSON Schema 为单一事实源、以 AJV strict 编译 + fixture 交叉校验为守门手段的完整参照实现。