caveman cacheengine独立运行的 Provider 原生 Prompt Cache 规划器与 Wire 引擎深度解析【免费下载链接】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本文围绕 caveman 仓库中的cacheengine模块展开讲解它如何在不依赖网关、网络、数据库或控制面的前提下为一组有序稳定前缀计算正收益的缓存断点并针对 Anthropic、OpenAI、Bedrock、Gemini 等 provider 生成原生 wire 变换。读完本文你将理解其能力驱动capability-driven的规划模型、盈亏平衡经济学计算、pass-through 安全边界以及如何通过ProfileDriver两个扩展点接入新的 provider。一、模块定位独立、纯本地的缓存元数据引擎cacheengine是一个独立的 prompt-cache 规划器与 provider 原生 wire 引擎导入路径为github.com/JuliusBrussee/caveman/cacheengine它的职责边界非常明确见 cacheengine/doc.go只规划并应用 provider 原生的 prompt 缓存元数据不存储或回放模型响应也不管理自托管 KV 缓存内存。它接受 wire bytes 并返回 wire bytes不做任何 provider 调用因此 proxy、SDK、sidecar 或本地进程都可以直接内嵌。从源码结构看核心生产路径只复用 6 个非标准库包Caveman JSON splice、cache guard、catalog/cost 与 YAML 相关包cacheengine/native.go 中可见对jsonsplice与cacheguard的依赖。Parity 测试cacheengine/wire_parity_test.go将 Anthropic 与 Bedrock 行为锁定到既有网关变换但生产代码不导入网关运行时。许可说明源码采用 Business Source License 1.1BSL-1.1属于 source-available在 Change Date 之前不算 OSI 开源。第一方自托管生产使用被允许第三方托管、托管服务或嵌入式服务使用需要商业许可。详见 cacheengine/LICENSE 与 LICENSING.md。二、通用规划器认识能力而非 provider 名称Engine.Plan是纯规划入口它不编辑任何 wire bytes只返回一份Plan。设计核心是Profile结构体cacheengine/types.go——一段与 provider 名称解耦的能力数据字段含义Modeexplicit/affinity/implicit/unsupported四种 provider 缓存控制语义Attribution一次命中证明什么causal可归因引擎、affinity仅亲和、organic自然发生、noneMinPrefixTokensprovider 最小可缓存前缀 token 数MaxBreakpoints允许的断点数上限WriteMultiplier/ReadMultiplier以输入费率单位为基准的写入/读取缓存倍率EconomicsKnown经济学参数是否可信TTL/Rolling/RoutingKey/MaxRPMPerKeyTTL、滚动边界、路由键与每键 RPM 上限规划调用示例来自 cacheengine/README.md 的完整示例engine : cacheengine.New(cacheengine.Config{}) plan, err : engine.Plan(cacheengine.PlanRequest{ Scope: org/project, Epoch: conversation-42, ExpectedCalls: 8, Profile: cacheengine.Profile{ ID: provider-cache-v1, Mode: cacheengine.ModeExplicit, MinPrefixTokens: 1024, MaxBreakpoints: 4, EconomicsKnown: true, WriteMultiplier: 1.25, ReadMultiplier: 0.10, RoutingKey: true, }, Segments: []cacheengine.Segment{ {Name: tools, Content: toolBytes, Tokens: 1800, Stable: true, Cacheable: true}, {Name: live, Content: userBytes, Stable: false}, }, })两个关键语义README 与types.go注释一致强调ExpectedCalls指在 provider 缓存条目保持热身的 TTL 窗口内、预期共享该前缀的调用次数不要灌入跨越缓存过期缝隙的终身总调用数。Segment.ExpectedCalls为零时继承PlanRequest.ExpectedCallsPlanRequest.ExpectedCalls为零时按保守的一次写入/一次读取处理实现见 cacheengine/engine.go零值被规整为 2。经济学使用输入费率单位input-rate units绝不猜测美元。1 个单位 1 个按全价输入费率计费的 token调用方只能用有据可依的 provider 目录数据自行定价。盈亏平衡与断点选择规划器在 engine.go 的breakpointCandidates中逐段累积前缀对每个候选边界计算净收益net prefix_tokens × (calls − WriteMultiplier − (calls−1)×ReadMultiplier)以 Anthropic 类 1.25/0.10 的倍率为例calls2时 net tokens × (2 − 1.25 − 0.10) 0即两次调用即回本breakEvenCalls则通过 2..10000 的线性搜索给出正收益的最小调用数。候选还需满足MinPrefixTokens门槛不满足记below_minimum且更长前缀不能拥有更高预期复用次数违反即报错。当候选数超过MaxBreakpoints时limitBreakpoints按ExpectedNetInputRateUnits降序保留前 N 个再恢复原始顺序engine.go。路由键与负载分片对RoutingKey: true的 profile如 OpenAIkeyShard依据ExpectedRequestsPerMinute与MaxRPMPerKey默认 15计算分片数count 1 (rpm−1)/maxRPM上限为Config.MaxKeyShards默认 64显式值 1..1,000,000。分片号由PartitionKey缺省回退到Epoch的 SHA-256 取模得到routingKey最终是scope\0profileID\0prefixSHA\0shard的 SHA-256 前 16 字节 hex。从源码结构看这些键是**租户不透明tenant-opaque**的——不含任何业务身份信息只用于 provider 侧的缓存亲和路由。前缀安全drift 与 volatile 检测规划前引擎把稳定段按 8 字节长度帧name 长度 content 长度大端序见appendFrame拼装成 epoch 字节交给两个安全检查volatile 检测cacheguard.DetectVolatile识别标称 stable 但内容实际波动的段命中则返回volatile_prefix并附volatile_stable_slot警告。引擎内部还有一个 8192 容量 LRU 的prefixSafetyCache缓存已确认安全的前缀摘要避免重复扫描。前缀漂移drift检测cacheguard.Inspect以sha256(scope\0epoch\0profileID)为 epoch key 追踪历史前缀摘要若同一 epoch 内前缀摘要发生变化返回prefix_drift直接 pass-through。StartEpoch则允许调用方显式冻结新前缀要求前缀不含 volatile 内容返回new_epoch决策。三、Optimize一条不改字节的调用链Engine.Optimize是面向 wire 的主入口cacheengine/native.goREADME 中的用法result, err : engine.Optimize(ctx, cacheengine.NativeRequest{ Scope: org/project, Epoch: conversation-42, Provider: openai, Model: gpt-5.6, Endpoint: /v1/responses, Body: requestBody, PrefixTokens: providerCount, ExpectedCalls: 8, RuntimeMode: optimize, AuthMode: payg, }) upstreamBody : result.Body // original bytes on every unsafe/unsupported path它不做任何 provider 调用且在任何不安全/不支持路径上都原样返回拷贝后的原始字节。NativeRequest的关键字段PrefixTokens应来自 provider 计数为零时变换仍可进行但阈值/经济学资格未知StableSegments供自定义 provider 绕过内建信封提取Profile仅对注册了自定义Driver的 provider 生效内建编译器拒绝逐请求的能力覆盖reason: profile_mismatch。内建稳定前缀的提取规则nativeStablePrefixnative.go按 provider 从请求体中抽取稳定字段并加帧Provider稳定字段序列字段anthropictools、systemmessages仅 system/developer 前导项openaitools、instructionsresponses端点为input否则messagesbedrocktoolConfig、systemmessagesgeminisystemInstruction、toolscontentsmodel字段也会加入前缀帧因为换模型即换缓存语义。必须 pass-through 的完整条件清单以下任一情况发生Optimize保留原始字节并给出显式reasonNativeResult.Reason取值来自 types.go畸形或歧义 JSON包括重复键由inspectUniqueJSONValue的 token 级扫描强制深度上限 512不支持的内置模型/端点内建端点白名单anthropic/v1/messagesopenai/v1/chat/completions、/v1/responsesbedrockconverse/converse-stream/invoke/invoke-with-response-streamgeminigenerateContent请求元数据模型与 body 中model字段不匹配profile_mismatch请求体已含调用方自管的缓存字段caller_managed如cache_control、prompt_cache_key等cacheMarkerAt按 provider 识别标记路径record 模式record_mode、非 PAYG 认证模式non_paygvolatile 稳定段volatile_prefix、前缀漂移prefix_drift、低于 provider 最小前缀below_minimum、无预期复用no_expected_reuse、负经济学negative_economics。此外配置层还有一道资源上限provider 原生 body 上限与加帧稳定前缀上限默认各自 64 MiB通过Config.MaxRequestBytes与Config.MaxStablePrefixBytes配置显式值必须在 1 字节到 1 GiB 之间两者都在拷贝或拼接之前拒绝超限stablePrefix在 engine.go 中按帧逐段检查。请求标识、段名、profile ID 与路由元数据都有长度上限并拒绝控制字符自定义 driver 输出不得超过配置的 body 上限。四、Provider 原生桥接各家的落地编译策略README 给出了一张内置策略表下面结合源码逐一印证表面行为归因上限Anthropic复用既有稳定 tool/system 断点追加顶层滚动自动缓存因果 provider 观测独立美元保持为零OpenAI GPT-5.6 家族范围化 affinity key 1 个稳定断点与最近 3 个显式断点body 无安全可标记块时回退为纯 affinity因果 provider 观测仓库验证账本扩展尚未构建早期 OpenAI在 provider 自动缓存之上使用范围化 affinity key仅 affinityBedrock Anthropic Claude复用目录门控的稳定点追加滚动消息检查点因果 provider 观测独立美元保持为零Gemini观测 provider 隐式管理的缓存不改写 body自然发生绝不归因于引擎未知精确 pass-through不可用Anthropic / Bedrock稳定点 滚动点applyAnthropicnative.go先由applyAnthropicStable落一个稳定的 tool/system 断点optimizer idanthropic-cache-breakpoints再用jsonsplice.AppendObjectFields在顶层追加cache_control: {type:ephemeral}作为滚动点optimizer idcave-cache-anthropic-rolling-v1——追加前检查字段是否已存在已存在则不动。Bedrock 类似稳定点bedrock-cache-pointsappendBedrockRolling按端点区分——converse系列往最后一条消息content追加{cachePoint:{type:default}}invoke系列则把字符串 content 包装成带cache_control的 block 或在最后 block 上追加cache_control。内置 profile 的兼容条件是硬编码的builtinProfileCompatiblenative.goAnthropic/Bedrock 要求ModeExplicitTTL 5minMaxBreakpoints 4Rolling 指定 OptimizerIDOpenAI explicit 要求TTL 30min且RoutingKeyGemini 要求ModeImplicitAttributionOrganic。能力数据本身由 profiles.go 从 provider 目录catalog 包的prompt_cache/prompt_cache_key/explicit_cache能力位解析并叠加模型级最小前缀如 Anthropic haiku-4-5/opus-4-5/4-6 为 4096fable-5/mythos-5 为 512其余默认 1024Bedrock opus-4-5/4-6、sonnet-4-5、haiku-4-5 为 4096claude-3-5-haiku 为 2048。缓存写/读倍率优先取自目录价格CacheWritePerMillion / InputPerMillion无价时回退 1.25/0.10OpenAI 无写价时回退 1.0。OpenAIaffinity key 与 GPT-5.6 显式断点applyOpenAIcacheengine/openai.go先插prompt_cache_keyroutingKey再视显式模式决定是否插prompt_cache_options: {mode:explicit}。核心在markOpenAIBreakpoints扫描messageschat或inputresponses序列中可标记项chat 端支持text/image_url/input_audio/file/refusalblockresponses 端支持input_text/input_image/input_file且 role 限定responses 端不含tool选出1 个稳定锚点 最近 3 个可缓存块按索引降序逐一写入prompt_cache_breakpoint: {mode:explicit}——降序保证每次插入不破坏后续目标的原始 span 有效性若 body 找不到任何安全可标记块则整体回退为纯 affinity结果reason: affinity_fallbackAttribution被降级为affinity见 native.go。源码注释点明了滚动语义的意图GPT-5.6 显式模式不向未标记前缀回退——保留 N 请求写入的滚动标记使 N1 请求能读到 N 写下的前缀同时至多新增一个滚动写入。而哪些模型走 explicit被刻意收窄openAIExplicitModel只认gpt-5.6及gpt-5.6-前缀因为旧模型会拒绝显式缓存字段。Gemini只观测不改写Gemini 的 profile 是ModeImplicitAttributionOrganicEconomicsKnown: false。Plan对 implicit 模式直接把所有净收益清零、EconomicsBasis置为provider_managed_unattributed决策为observe_onlyengine.go——引擎不插入任何字段只承认 provider 自己管理的缓存是自然发生的永不归因于引擎。五、观测与记账绝不铸造已验证美元README 强调两条观测路径都不铸造已验证节省verified savingsVerifiedSavingsUSD恒为零更强的美元声明只属于受管网关账本。Observe(result, usage)接受归一化的 provider 用量区分hit/write/miss/unavailable四种状态仅当result.Applied且 profile 为AttributionCausal时才置AttributedToEnginetypes.go。ObserveRawCacheUsage/NormalizeRawCacheUsagecacheengine/raw_usage.go直接映射各家官方原始计数器覆盖 OpenAIinput_tokens_details/prompt_tokens_details下的cached_tokens与cache_write_tokens旧版共享归一器可能不暴露该字段、Anthropic 的cache_read_input_tokens/cache_creation_input_tokens并校验cache_creation.ephemeral_5m/1h明细之和、Bedrock 的cacheReadInputTokens/cacheWriteInputTokens、Gemini 的cachedContentTokenCount。重复键、负数/小数、OpenAI 双形状歧义input_tokens_details与prompt_tokens_details同时出现一律 fail closed。ExtractProviderUsage从完整非流式响应中提取用量对象并绑定 provider 计数的总输入 token 分母Anthropic/Bedrock 的总量按 provider 契约等于未缓存 缓存读 缓存写之和任何不一致都拒绝。六、接入新 ProviderProfile Driver规划器不变README 的扩展契约提供能力 profile 加一个Driver规划器保持不动。内建 profile 必须显式绑定ProviderDriver 收到选中的断点且当安全编译不可能时必须返回原始字节且不携带任何 optimizer ID。engine : cacheengine.New(cacheengine.Config{ ResolveProfile: func(r cacheengine.NativeRequest) (cacheengine.Profile, bool) { return acmeProfile, r.Provider acme }, Drivers: map[string]cacheengine.Driver{ acme: acmeWireDriver, }, })约束细节Driver 的 key 是归一化trim 小写的 provider 名归一化后必须唯一否则NewChecked直接报错自定义请求需提供StableSegments缺失时返回no_stable_prefixResolveProfile与Driver回调可能并发执行必须自行保证并发安全。Engine构造后并发安全New/NewChecked见 engine.go生产构造器应使用NewChecked遗留New也把配置错误存起来使所有操作 fail closed。DriverFunc适配器让函数式 driver 实现接口。七、验证体系97% 门禁与诚实数字README 的 Proof 部分给出零 provider 调用的本地验证命令注意其假设仓库源码位于public目录下的布局当前仓库中对应路径为cacheengine/go test -race ./cacheengine/... go vet ./cacheengine/... go test -run ^$ -bench BenchmarkOptimizeOpenAIExplicit -benchmem ./cacheengine go run ./cacheengine/cmd/cache-experiment go run ./cacheengine/cmd/cachebench go run ./cacheengine/cmd/cache-replay -helpcache-experiment的 fixture token 计数与盈亏平衡输出是模型化证据不是活缓存命中证据。cachebench可复现的 97% 门禁cacheengine/cachebench/README.md 回答了核心问题cacheengine 能否在一个工具型 agent 上维持 ≥97% 缓存命中同时不隐藏冷启动、压缩、语义变更、非法用量或不支持的 provider 行为默认运行go run ./cacheengine/cmd/cachebench零 flag每 provider 128 请求覆盖 4 家 provider负载含 8192 声明稳定 system/tool token、增长的用户/assistant 工具调用/工具结果历史、每 64 轮一次计划内压缩压缩开启新 epoch其冷写入留在分母内。预期输出为CACHEBENCH agent-cache evaluation: PASS四家 provider 请求命中 99.22%、token 命中 97.79%gemini 归因为 0.00%因其命中永远是 organic。指标契约request_hit_rate 有 cache_read_tokens0 的请求 / 全部合格请求token_hit_rate Σcache_read_tokens / Σ合格前缀 token。两者都计入冷启动、TTL 过期、压缩与前缀失效inelig低于 provider 最小值不算 miss 也不算无效样本未知 provider、畸形 body、静默漂移、不安全变换、缺失 usage 则记 invalid 并使门禁失败。公开语料导入 CC-BY-4.0 的 LMCache Agentic TracesSWE-bench/GAIA/WildClaw agent 请求历史固定源码 hash 并限制留存内存。README 明确记录当前公开语料结果是保守模拟且未通过严格 97% 门禁完整训练集24,880 请求96.89% 请求命中 / 95.76% 估算 token 命中门禁 FAIL单 shard 跨 provider 回放四家请求命中 97.01%~97.63%token 命中均 97%机器可读结果见 results/lmcache-agentic-traces-2026-08-10.json。内置能力行为已于 2026-08-10 对照各 provider 官方缓存文档校验Anthropic、OpenAI、Gemini、AWS Bedrock。cache-replay不削弱证据的外部 runner 胶水cache-replaycacheengine/cmd/cache-replay提供精确 v3 trace 重建、opt-in 认证调用、无自动重试、provider 计数用量、外部任务打分、私有留存产物与 exact-population 观测 v3。全部 trace 的优化与模型可见等价性在第一次调用之前完成有界并发 worker 使用绝对 trace 计时调度漂移超限即失败。调用方声明的优化后 wire 输入上限加 provider 原生最大输出字段构成 preflight 计费 token 上限——provider 计数基准仍是调用方自证上限不保证实际 token 或美元封顶。合成/会话本地计时与估算 token 预算在 live 默认下直接失败。详见 cacheengine/cachebench/REPLAY_PROTOCOL.md。八、产品边界与响应缓存、KV 缓存的区分README 用一张表划清边界避免概念混淆类别代表差异Provider prompt 前缀规划器cacheengine纯元数据请求变换provider 仍运行模型并上报缓存计数器精确/语义响应缓存Helicone、Portkey、GPTCache 等网关产品回放存储的输出语义模式引入答案等价风险自托管 KV 缓存vLLM APC、LMCache控制推理内存需要服务基础设施README 同时明确目前不存在任何市场上最优的声明——那需要同一人群的活 provider 计数器、任务质量验证、延迟与竞品对比当前公开语料产物仍是保守模拟。永远缓存作为字面保证不可能成立provider 最小值、TTL、并发、容量、精确前缀变更、不支持的模型与自然缓存都仍可能 miss。引擎的职责是最大化合格稳定前缀并在无法行动时返回显式原因调用方的缓存字段永远优先。小结cacheengine的价值主张可以概括为三点其一规划器与 provider 解耦——能力数据Profile驱动断点选择与经济学判定wire 差异被隔离在Driver/内建编译器之后其二全程 fail closed——从重复 JSON 键、前缀漂移、volatile 段到超限字节任何不确定都退回原始字节并给出机器可读 reason其三证据分层严格——模拟、provider 观测、可归因、已验证美元是四个不同强度模块只承诺到它有能力证明的层面。对需要在 proxy、SDK 或 sidecar 中嵌入原生 prompt 缓存优化的工程它的Optimize单入口 零外部依赖的特性使其可以直接内嵌使用。【免费下载链接】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），仅供参考