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

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

【免费下载链接】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

本文以 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的强约束，是理解该字段的关键：

六个值不是有序的。任何对其做大小比较的代码（mode >= "canary"）都是 bug；
中间四个值行为上完全一致，shadow/canary只是展示标签，不是流量切分；
派生逻辑只允许存在于一处（文档指向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 是整个包的执行核心，其逻辑可以完整走读：

枚举并解析：读取schemas/下所有*.schema.json，要求每个文件的$schema必须是https://json-schema.org/draft/2020-12/schema、且带非空$id，否则直接抛错；
AJV 严格编译：new Ajv2020({ allErrors: true, strict: true })，把所有 schemaaddSchema后逐一getSchema确认编译成功——strict 模式意味着任何未知关键字、非标准写法都会让编译失败；
fixture 数量断言：fixtures/agent/下必须恰好 2 个JSON fixture，且必须分别覆盖harness: "claude"与harness: "pi"；
共享契约字段比对：逐字段 JSON 序列化比较两份 fixture 的normalized_context_digest、plan_sha256、ordered_transform_ids、provider_visible_digest、recovery_handles、accounting_method、failure_fallback——任何一处不一致即抛错，从而在 CI 层面机械地强制"两个适配器对同一输入产生同一归一化结果"；
特异性断言：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 小节给出了契约演进的三条纪律：

schema 版本是整数。policy.schema.json中即version: integer, minimum: 1。文档还指出控制面 API 的policy_schema_version字段（指向cloud/control-api/internal/httpapi/server.go:372，此为 AGENTS.md 引用的云端仓库坐标）会向客户端回发该版本号。
新增必填字段是破坏性变更——必须 bumpversion，并跨 control-api、SDK、web 三方协调。
尚未从 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 交叉校验为守门手段的完整参照实现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析