caveman cacheengine独立式提示词缓存规划器与 Provider 原生 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/cavemancaveman 仓库中的cacheengine是一个零运行时依赖的提示词前缀缓存引擎它不启动任何网关进程不访问网络、数据库或控制面仅以纯函数方式接受 provider 请求的 wire 字节规划“正收益”的缓存断点并直接改写请求体使其命中 Anthropic、OpenAI、Bedrock、Gemini 的原生 prompt cache 机制。读完本文你将理解它的 capability-driven 规划器如何计算 break-even盈亏平衡复用次数、如何用 Scope/Epoch 守护前缀漂移、如何为 OpenAI 风格亲和键做租户不透明分片以及它“绝不猜测、绝不铸美元、不确定就回传原字节”的整套正确性不变式与验证手段。设计定位零运行时依赖的缓存引擎模块文档 cacheengine/CLAUDE.md 开宗明义cacheengine 是“capability-driven planner plus provider-native wire compiler”能力驱动规划器 provider 原生 wire 编译器。运行时不需要网关进程、网络、数据库或控制面。engine.go保持 provider/model 无关独立的 wire 编译器与profiles.go负责绑定当前各 provider 的契约通过Driver/profile resolver 两个接缝可以新增 provider而无需改动规划器本身。可选的 live replay I/O 只属于cachebench子包。模块导入路径为github.com/JuliusBrussee/caveman/cacheengine见 cacheengine/README.md源码以 Business Source License 1.1 发布源码可见Change Date 之前不属于 OSI 开源第一方自托管生产允许第三方托管/托管式/嵌入式服务使用需要商业授权见 cacheengine/LICENSE 与 LICENSING.md。一个关键保证是Optimize全程不做任何 provider 调用。它接受并返回 wire 字节因此代理、SDK、sidecar 或本地进程都能直接内嵌这个引擎。从源码结构看核心生产依赖图只复用了仓库内的 JSON splice、cache guard、catalog/cost 与 YAML 几个平台包README 称共六个非标准库包Anthropic 与 Bedrock 的行为由 parity 测试与既有网关转换逻辑锁定但生产路径不导入任何网关运行时。模块布局CLAUDE.md 的 Layout 一节给出了完整的文件级地图逐条继承如下文件/目录职责types.go公开的 capability、plan、result、driver、observation 契约engine.gostable-prefix 边界、break-even 数学、volatile/drift 守护、按 Scope 分片的 affinity keynative.go、openai.go、wire_anthropic_bedrock.go严格的内建 JSON 抽取与 wire 编辑生产图不导入任何网关适配器parity 测试将独立版 Anthropic/Bedrock 行为与那些适配器对比profiles.go内建模型阈值、TTL、经济学参数、归因raw_usage.goprovider 缓存计数器归一化不做美元换算cmd/cache-experiment仅离线转换/经济学 fixture零 provider 调用cachebench/ cmd/cachebench严格 97% 请求/token 门槛、语义等价检查、有界公共语料导入、trace 导出、provider 观测回放cmd/cache-replay可选 live 回放精确 trace 重建、provider HTTP 鉴权/SigV4、发送前全 trace 等价、绝对时间有界并发、任务验证器协议、私有留存证据、不重试cachebench/scripts/哈希钉住的 LMCache 下载与 parquet 转 JSONL 流式辅助脚本PyArrow 只是可选基准工具绝非运行时代码核心契约从 Capability 到 Plan规划器认识的是“能力数据”而不是 provider 名字。核心类型全部定义在 cacheengine/types.go四种缓存控制语义Mode见 types.go#L11-L16ModeUnsupportedprovider 无缓存能力直接放行ModeImplicitprovider 隐式管理缓存引擎只观测不干预ModeAffinity引擎通过亲和路由键affinity key提升同一前缀落在同一缓存条目上的概率ModeExplicit引擎可以向请求体写入显式断点/缓存控制字段。四级归因Attributionnone/organic/affinity/causal。它回答的是“一次 provider 确认的命中能证明什么”。例如 Gemini 的隐式缓存命中是organic——它提升了缓存表现但永远不能归因为引擎因果所致只有显式写入断点且 provider 确认命中的场景才是causal。四种决策Decisionapply已改写 wire 体、observe_only仅观测、pass_through放行原字节、new_epoch显式开启新的冻结前纪元。Profile结构types.go#L68-L85携带ID、Provider、Mode、Attribution、MinPrefixTokens、MaxBreakpoints、EconomicsKnown、WriteMultiplier、ReadMultiplier、TTL、Rolling、RoutingKey、MaxRPMPerKey、OptimizerID等字段。Segment表示有序 prompt 前缀的一个组成部分其中Stable是调用方拥有的事实——在一个 epoch 内可能变化的内容绝不允许被标记为 stable。通用规划器示例README 给出的最小嵌入方式完整继承可直接编译运行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}, }, })ExpectedCalls的语义必须精确理解它指“在 provider 缓存条目保持温热TTL 内预计共享该前缀的调用次数”不要把跨越缓存过期间隙的终身总调用数填进来。经济学字段使用输入费率单位一次单位 一个按全输入费率计费 token从不猜测美元。token 数未知时安全转换仍可用但经济学标记为 unavailable。NativeRequest面向 provider 原生请求types.go#L187-L209除上述字段外还有Provider、Model、Region、Endpoint、Body、RuntimeMode、AuthMode、PrefixTokens应优先来自 provider 计数为零时转换仍可行但阈值/经济学资格未知、StableSegments自定义 provider 绕过内建 envelope 抽取与Profile仅对注册了自定义 Driver 的 provider 允许按请求覆盖内建编译器拒绝 per-request 能力覆盖。官方示例见 cacheengine/example_test.goresult, err : engine.Optimize(context.Background(), 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 // 所有不安全/不支持路径返回原始字节Break-even 数学只选正收益断点规划器核心在 cacheengine/engine.go。Plan的入口校验、前缀抽取、波动检测、经济学计算见 engine.go#L102-L221。断点候选的逐段递推逻辑在breakpointCandidatesengine.go#L359-L416按序对 stable 段做 length-prefixed 帧化appendFramename 与 content 各 4 字节大端长度前缀累计 token 数每个位置要求ExpectedCalls 2少于两次复用没有意义且累计 token 数达到profile.MinPrefixTokens下限否则记录belowMinimum并跳过经济学已知时计算净收益输入费率单位net cumulativeTokens * (calls - WriteMultiplier - (calls-1) * ReadMultiplier)直觉是写一次缓存多付WriteMultiplier倍费率之后每次读取只付ReadMultiplier倍费率。若net 0则记为negativeEconomics并跳过更长的前缀不允许拥有更高的预期复用次数longer prefix cannot have higher expected reuse违反即报错净收益为正的段生成带PrefixSHA256的候选断点连续相同ExpectedCalls的候选只保留最深处一个。盈亏平衡调用数由breakEvenCallsengine.go#L418-L428线性搜索最小的calls2 起上限 10000使calls - WriteMultiplier - (calls-1)*ReadMultiplier 0。以 Anthropic 典型 1.25/0.10 倍率为例第 2 次调用即净收益转正所以断点几乎总能入选经济学未知时breakEvenCalls返回 0绝不猜测。候选超过MaxBreakpoints时limitBreakpointsengine.go#L430-L444按净收益降序选前 N 个再按原始顺序排序保证选中的是“最赚钱”的边界且 wire 顺序不乱。对ModeImplicit如 GeminiPlan会把所有断点的净收益清零、EconomicsBasis置为provider_managed_unattributed并把决策改为observe_only——引擎从不把 provider 自主管理的缓存算作自己的功劳。Stable Prefix、Epoch 与漂移守护CLAUDE.md 的不变式规定“Epoch意味着一个冻结的 stable 前缀字节变化必须走StartEpoch静默前缀漂移直接放行。”实现上stablePrefixengine.go#L323-L348只接受开头连续的Stable Cacheable段遇到第一个非 stable 段即止段名唯一、非空、长度受限且帧化总字节数必须低于MaxStablePrefixBytes默认 64 MiB超限在复制/拼接之前拒绝。前缀摘要SHA-256连同Scope/Epoch/ProfileID组成的 epoch key 交给cacheguard来自 shared/platform/cacheguard做漂移检查如果同一 epoch 下前缀字节与冻结记录不一致返回WarningPrefixDrift规划器将其翻译成ReasonPrefixDrift并放行原始字节不尝试“追着漂移走”。显式开启新纪元用StartEpochengine.go#L224-L266它拒绝波动内容进入稳定纪元volatile content cannot start stable epoch并返回DecisionNewEpoch。cacheguard.DetectVolatile检测前缀中的易变内容时间戳之类引擎另有一个 LRU 式prefixSafetyCacheengine.go#L498-L533缓存“已知安全”前缀摘要容量 8192避免对同一稳定前缀反复跑波动检测。StartEpoch也用于 compaction 场景agent 历史每 64 轮压缩一次时开启新纪元其冷写入计入分母见下文 cachebench。Scope 与亲和键分片不变式要求“Scope必填且在生成 provider 可见路由键之前被哈希”内建 profile 显式绑定唯一 provider。分片与路由键生成在 engine.go#L446-L472keyShard当ExpectedRequestsPerMinute超过profile.MaxRPMPerKey内建 OpenAI profile 为 15时分片数count 1 (RPM-1)/MaxRPMPerKey再被MaxKeyShards默认 64可配 1..1,000,000见 types.go#L143-L163封顶触顶时警告routing_key_shard_cap_reached。分片号由PartitionKey缺省回退Epoch的 SHA-256 取模得到同一 partition/epoch 内路由键保持稳定。routingKey对scope 0x00 profileID 0x00 prefixSHA256 0x00 shard做 SHA-256取前 16 字节十六进制。tenant 名称、epoch、前缀内容都不出现在键中只以摘要形式参与哈希——这就是“租户不透明、按负载分片”的 affinity key。请求身份、段名、profile ID、路由元数据全部有长度上限并拒绝控制字符validIdentity见 cacheengine/validation.go 与 engine.go#L268-L302 的校验调用。Provider 原生 Wire 编译Optimize 全流程Optimizenative.go#L18-L185是引擎的总入口按序执行一串 fail-closed 闸门任何一关不通过都返回拷贝后的原始字节并给出明确原因原因常量见 types.go#L38-L55字节上限Body超过MaxRequestBytes直接报错身份校验validNativeIdentity失败记malformed_requestRuntimeMode record→record_mode放行AuthMode非空且非payg→non_payg放行内建 provideranthropic/openai/bedrock/gemini必须提供Model与Endpoint且端点在白名单内native.go#L187-L200Anthropic/v1/messagesOpenAI/v1/chat/completions、/v1/responsesBedrockconverse/converse-stream/invoke/invoke-with-response-streamGeminigenerateContent请求体必须是唯一键JSON 对象严格流式解析器inspectUniqueJSONObject深度上限 512重复键、非对象根、尾随字节全部判 malformedbody 内model字段与request.Model不一致 →profile_mismatchcaller-managed 检测cacheMarkerAtnative.go#L395-L409识别各 provider 的既有缓存控制标记——Anthropic 的cache_controltools/system/messages content 路径下、OpenAI 的顶层prompt_cache_key/prompt_cache_options与内容块上的prompt_cache_breakpoint、Bedrock 的cachePoint/cache_control、Gemini 的顶层cachedContent。只要发现调用方已自行管理缓存引擎即让路caller_managed。CLAUDE.md 的不变式“调用方缓存字段永远优先”由此落地profile 解析内建 provider 不允许按请求注入Profile否则profile_mismatch由defaultProfile解析后经builtinProfileCompatiblenative.go#L238-L258逐字段核对模式、归因、断点数、TTL、Rolling、RoutingKey、OptimizerID任何一项偏离即拒未提供StableSegments时用nativeStablePrefixnative.go#L339-L393从请求体抽取稳定前缀provider、model 加各 provider 的稳定字段Anthropic 的toolssystem、OpenAI 的tools/instructions、Bedrock 的toolConfigsystem、Gemini 的systemInstructiontools再拼接对话序列开头的连续 system/developer 消息交给Plan决策非apply即止步按 provider 编译 wire 体输出为空、超限、优化器 ID 非法或与原体完全相同都回退为transform_unavailable放行。各 provider 的内建行为完整继承自 README 表格表面行为归因上限Anthropic复用既有 stable tool/system 断点新增滚动顶层 automatic caching因果级 provider 观测独立版美元保持为零OpenAI GPT-5.6 家族作用域亲和键 1 个稳定断点与最近 3 个显式断点body 中无安全可标记块时退化为仅亲和因果级 provider 观测仓库内已验证账本扩展尚未构建早期 OpenAIprovider automatic caching 之上的作用域亲和键仅亲和Bedrock Anthropic Claude复用 catalog 门禁的 stable 点并追加滚动 message 检查点因果级 provider 观测独立版美元保持为零Gemini观测 provider 隐式管理缓存不改写 bodyorganic永不归因引擎未知 provider精确放行不可用OpenAI 断点标记策略值得细看openai.go#L41-L106显式模式保留“1 个稳定锚点 最近 3 个可缓存消息块”共最多 4 个prompt_cache_breakpoint: {mode:explicit}标记。GPT-5.6 显式模式不做“无法标记前缀就回退自动缓存”——保留上一轮滚动标记能让第 N1 次请求读取第 N 次写入的前缀同时最多只新增一次滚动写入。字符串 content 会被转成 content block 数组再加标记这一步是 wire 等价的CLAUDE.md 不变式OpenAI 的 string-to-content-block 转换仅当显式断点语法要求时才使用。标记按索引降序执行插入确保每次替换都不使更早 span 失效。Anthropic的applyAnthropicnative.go#L260-L272先复用既有稳定断点再用jsonsplice.AppendObjectFields在顶层追加cache_control: {type:ephemeral}字段已存在则不动返回两个优化器 IDanthropic-cache-breakpoints与cave-cache-anthropic-rolling-v1。Bedrock的appendBedrockRollingnative.go#L290-L337按端点区分converse 系在最后一条消息 content 追加{cachePoint:{type:default}}invoke 系把最后一条消息的文本内容块加上cache_control: {type:ephemeral}字符串 content 先等价转为 block。若 OpenAI 显式模式未能写入任何断点结果会把归因从 causal 降级为 affinity 并记affinity_fallbacknative.go#L179-L183。成功应用时ClaimBasis inferredVerifiedSavingsUSD恒为 0——CLAUDE.md 不变式“managed gateway 拥有唯一经核验的记账方法”由此体现。内建 Profile 与模型阈值defaultProfileprofiles.go#L12-L70按 provider 分发阈值数据全部落在profiles.goProvider判定条件模式/归因最小前缀最大断点TTL其他Anthropiccatalog 具备prompt_cache能力explicit / causal按模型 512–4096anthropicMinimumprofiles.go#L181-L19345 分钟Rolling无路由键OpenAI GPT-5.6 家族模型名gpt-5.6/gpt-5.6-*前缀profiles.go#L176-L179explicit / causal1024430 分钟Rolling 路由键15 RPM/key其他 OpenAIcatalog 具备prompt_cache_key能力affinity / affinity204815 分钟Rolling 路由键Bedrockcatalog 中anthropic.claude-*模型具prompt_cache能力且端点为 converse/invoke 系profiles.go#L105-L138explicit / causal按模型 1024–4096bedrockMinimum45 分钟RollingGeminicatalog 具备explicit_cache能力implicit / organicgemini-2.5: 2048gemini-3: 4096其余 0profiles.go#L207-L2171—Rolling经济学未知其他—无 profile返回 false → 放行注意openAIExplicitModel刻意保持狭窄旧模型拒绝显式缓存字段官方契约只点名 GPT-5.6 家族未来家族需要 profile 数据或显式调用方覆盖而不是猜测请求。经济学倍率不是写死的cacheMultipliersprofiles.go#L149-L171优先从 catalog 价格数据推导CacheWritePerMillion / InputPerMillion、CacheReadPerMillion / InputPerMillion支持按 Region 取价无定价数据时回退到保守默认1.25/0.10OpenAI 亲和路径写倍率为 1。模型能力数据来自 shared/platform/catalog价格来自 shared/platform/cost。缓存计数器归一化永不“铸美元”响应侧证据由 cacheengine/raw_usage.go 负责对应 CLAUDE.md 布局中“provider cache-counter normalization; no dollar minting”。NormalizeRawCacheUsageraw_usage.go#L166-L268将各 provider 官方计数器映射为统一的UsageObservationProvider读取字段OpenAIinput_tokens_details或prompt_tokens_details二者必有且仅有一个中的cached_tokens与cache_write_tokensAnthropiccache_read_input_tokens、cache_creation_input_tokens并与cache_creation.ephemeral_5m/1h_input_tokens明细交叉核对矛盾即失败BedrockcacheReadInputTokens、cacheWriteInputTokensGeminicachedContentTokenCount回退total_cached_tokens未知 provider、重复键、负数/小数计数器、OpenAI 双字段歧义、Anthropic 总额矛盾一律 fail-closed 返回不可用。Observetypes.go#L257-L280把归一化结果与NativeResult组合成Observation区分 hit/write/miss/unavailableAttributedToEngine仅在“引擎确实应用了优化器且 profile 归因为 causal”时为真。ObserveRawCacheUsage额外覆盖 OpenAI GPT-5.6 的cache_write_tokens——旧版共享响应归一化器可能不暴露它。ExtractProviderUsageraw_usage.go#L25-L120更进一步从完整非流式响应抽取 usage 对象并绑定 provider 计数的输入 token 分母Anthropic/Bedrock 的总量 未缓存 缓存读 缓存写溢出、重复键、缺失总量全部失败关闭。CacheObserved字段专门区分“观测到零/未命中”与“响应里根本没有缓存计数器”避免把缺失当未命中。扩展新 ProviderDriver 与 Profile ResolverCLAUDE.md 与 README 给出同一契约提供能力 profile 加Driver规划器保持不变内建 profile 必须显式绑定ProviderDriver 收到选定的断点无法安全编译时必须返回原字节且不带任何优化器 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, }, })Config的完整语义types.go#L143-L163MaxKeyShards默认 64有效显式值 1..1,000,000MaxRequestBytes与MaxStablePrefixBytes默认各 64 MiB显式值 1 字节..1 GiB二者都在复制/拼接之前拒绝超限ResolveProfile非 nil 时替换内建查找Drivers的键经小写/去空格归一化后必须唯一。生产构造应使用NewCheckedengine.go#L54-L56在构造期暴露配置错误遗留的New保留单返回值 API但同样保存配置错误并使所有操作失败关闭。Resolver 与 Driver 回调可能并发执行必须自身并发安全。自定义请求必须提供StableSegments否则no_stable_prefix自定义 Driver 输出不得超过配置的请求体上限优化器 ID 接受与身份字段同样严格的校验native.go#L224-L236。正确性不变式汇总CLAUDE.md 的 Correctness invariants 一节是理解这个模块设计哲学的总纲逐条列出并给出源码落点原始字节存活malformed、unsupported、caller-managed、record、non-PAYG、volatile、drifting 或不可转换的请求一律原样放行native.go#L49-L91 的闸门链永不重排或改写语义内容只追加 provider 原生缓存控制字段OpenAI 的 string-to-content-block 转换是 wire 等价的且仅当显式断点语法需要时使用openai.go#L136-L167Scope 必填并先哈希provider 可见路由键只包含摘要内建 profile 显式绑定唯一 providerbuiltinProfileCompatibleEpoch 一个冻结 stable 前缀字节变化要求显式StartEpoch静默前缀漂移放行ExpectedCalls TTL 内复用未知 token 数或缓存经济学保持 zero/unavailable绝不猜测独立版结果分级应用后的结果为inferred放行/仅观测结果为noneVerifiedSavingsUSD恒为零已核验记账方法归 managed gateway 所有自定义 Driver 在不确定时返回原字节与零优化器 ID公开边界永不导入cloud/...。“总能命中缓存”不可能是字面保证provider 最小前缀、TTL、并发、容量、精确前缀变化、不支持的模型与有机缓存都可能导致未命中。引擎的职责是最大化合格的稳定前缀并且在无法行动时返回明确原因——15 个Reason*常量types.go#L38-L55就是这个承诺的词汇表。产品边界上READMEcacheengine 是“provider 提示词前缀规划器”只做元数据级请求转换provider 仍然运行模型并报告缓存计数器。它不存储/回放模型响应也不管理自托管 KV 内存——后者属于 exact/semantic response cache 与 self-hosted KV cache 两类完全不同的产品正确性边界不同。README 明确拒绝“市场最佳”类声明因为那需要同人群 live 计数器、任务质量验证、延迟与竞品对比。验证测试、Fuzz 与 cachebenchCLAUDE.md 的 Proof 一节给出完整验证命令原文含cd public对应原单仓目录本仓库布局中 Go module 位于仓库根含 go.mod在根目录直接执行即可go test -race ./cacheengine/... go vet ./cacheengine/... go test ./cacheengine -run ^$ -fuzz ^FuzzOptimizeMalformedBuiltinsPassThrough$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzAgentCorpusJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzObservationJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzTraceJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzVerificationCommandOutputFailClosed$ -fuzztime5s go test -run ^$ -bench BenchmarkOptimizeOpenAIExplicit -benchmem ./cacheengine go run ./cacheengine/cmd/cache-experiment go run ./cacheengine/cmd/cachebench go run ./cacheengine/cmd/cache-replay -helpFuzz 目标的名字本身就说明立场FuzzOptimizeMalformedBuiltinsPassThrough验证畸形输入必须穿过引擎而字节不变四个 cachebench fuzz 目标验证所有外部 JSONL 解码器 fail-closed。cachebench 子包回答一个具体问题cacheengine 能否在一个持续使用工具的 agent 上维持至少 97% 缓存命中同时不掩盖冷启动、compaction、语义变更、非法 usage 或不支持的 provider 行为零参数运行 128 请求/provider × Anthropic/OpenAI/Bedrock/Gemini负载携带 8,192 个声明稳定 system/tool token、增长的 user/assistant 工具调用与工具结果历史每 64 轮做一次计划内 compaction开新纪元冷写入留在分母里。主门槛完整指标契约见 cacheengine/cachebench/README.mdrequest_hit_rate cache_read_tokens 0 的请求 / 所有合格请求 token_hit_rate sum(cache_read_tokens) / sum(合格 prompt 前缀 token)两者均 ≥ 目标值、每 provider 最小样本数达标、质量通过率 100%、模型可见等价失败为零、非法样本为零速率绝不排除计划内冷启动、TTL 过期、compaction 或前缀失效。低于 provider 最小前缀的请求记inelig而非 missGemini 隐式命中保持 organic进入attributed_token_hit_rate之外的通道。失败演练期望 FAIL退出码 1go run ./cacheengine/cmd/cachebench \ -providers anthropic -turns 128 -step 6m -target 0.97每个 Anthropic 请求间隔超过 5 分钟 TTL所有后续请求冷启动。程序门控失败退出 1非法输入/配置退出 2全部 provider 过门才退出 0。公共语料方面cachebench 导入 CC-BY-4.0 的 LMCache Agentic Traces钉住 revision 与 LFS 哈希有界留存内存解码上限默认各 1 GiB 且超 16 GiB 失败关闭。钉住的保守模拟结果存档于 cacheengine/cachebench/results/lmcache-agentic-traces-2026-08-10.json24,880 请求、24,706 个 OpenAI 缓存合格请求96.89% 请求命中率、95.76% 估算 token 命中率严格 97% 门槛整体 FAIL——README 如实记录这一失败因为每会话一次冷纪元在数学上就把请求命中上限压到 96.92%。这就是该模块“不掺假证据”文化的缩影模拟报告与 provider 观测报告永不混同simulation 与 live 证据是两份独立报告。cmd/cache-replay提供可选 live 回放精确 v3 trace 重建、opt-in 鉴权调用provider HTTP 鉴权/SigV4、首次真实调用前完成全 trace 优化与模型可见等价、绝对时间有界的并发 worker调度漂移过大即失败、外部任务验证器协议、私有留存证据、自动重试为零。零网络 preflight 示例go run ./cacheengine/cmd/cache-replay \ -trace /tmp/cachebench-openai.jsonl \ -max-requests 128 \ -max-declared-billed-tokens 5000000 \ -allow-ungrounded-timing \ -allow-estimated-token-budget生产 trace 省略降级开关live 执行另需-execute -accept-live-cost -output 新私有目录 -verifier-command 路径。provider 计数的计费基准由调用方自证计费 token 上限是预检约束而非实际 token/美元保证。完整凭证、评分器 wire 契约、失败语义与留存产物布局见 cacheengine/cachebench/REPLAY_PROTOCOL.md。小结cacheengine 展示了一种与“AI 网关”截然不同的缓存工程路径把缓存收益问题分解为能力建模Profile、收益计算break-even 输入费率单位、字节级安全严格唯一键 JSON、wire 等价编辑、全路径原字节存活与证据分层inferred/none、organic/affinity/causal、verified 美元恒零四个正交层再用 fuzz、parity 测试、严格 97% 门槛基准与钉住语料的诚实 FAIL 报告逐层验证。对需要在代理、SDK 或本地进程中直接内嵌 prompt 缓存优化的开发者它提供的是可审计的机制与可复制的验证命令而不是一个需要整条控制面基础设施的“黑盒网关”。进一步阅读可从 cacheengine/README.md、cacheengine/CLAUDE.md 与测试文件 engine/planner 相关的 planner_test.go、wire_parity_test.go 入手。【免费下载链接】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），仅供参考
caveman cacheengine：独立式提示词缓存规划器与 Provider 原生 Wire 编译引擎详解
caveman cacheengine独立式提示词缓存规划器与 Provider 原生 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/cavemancaveman 仓库中的cacheengine是一个零运行时依赖的提示词前缀缓存引擎它不启动任何网关进程不访问网络、数据库或控制面仅以纯函数方式接受 provider 请求的 wire 字节规划“正收益”的缓存断点并直接改写请求体使其命中 Anthropic、OpenAI、Bedrock、Gemini 的原生 prompt cache 机制。读完本文你将理解它的 capability-driven 规划器如何计算 break-even盈亏平衡复用次数、如何用 Scope/Epoch 守护前缀漂移、如何为 OpenAI 风格亲和键做租户不透明分片以及它“绝不猜测、绝不铸美元、不确定就回传原字节”的整套正确性不变式与验证手段。设计定位零运行时依赖的缓存引擎模块文档 cacheengine/CLAUDE.md 开宗明义cacheengine 是“capability-driven planner plus provider-native wire compiler”能力驱动规划器 provider 原生 wire 编译器。运行时不需要网关进程、网络、数据库或控制面。engine.go保持 provider/model 无关独立的 wire 编译器与profiles.go负责绑定当前各 provider 的契约通过Driver/profile resolver 两个接缝可以新增 provider而无需改动规划器本身。可选的 live replay I/O 只属于cachebench子包。模块导入路径为github.com/JuliusBrussee/caveman/cacheengine见 cacheengine/README.md源码以 Business Source License 1.1 发布源码可见Change Date 之前不属于 OSI 开源第一方自托管生产允许第三方托管/托管式/嵌入式服务使用需要商业授权见 cacheengine/LICENSE 与 LICENSING.md。一个关键保证是Optimize全程不做任何 provider 调用。它接受并返回 wire 字节因此代理、SDK、sidecar 或本地进程都能直接内嵌这个引擎。从源码结构看核心生产依赖图只复用了仓库内的 JSON splice、cache guard、catalog/cost 与 YAML 几个平台包README 称共六个非标准库包Anthropic 与 Bedrock 的行为由 parity 测试与既有网关转换逻辑锁定但生产路径不导入任何网关运行时。模块布局CLAUDE.md 的 Layout 一节给出了完整的文件级地图逐条继承如下文件/目录职责types.go公开的 capability、plan、result、driver、observation 契约engine.gostable-prefix 边界、break-even 数学、volatile/drift 守护、按 Scope 分片的 affinity keynative.go、openai.go、wire_anthropic_bedrock.go严格的内建 JSON 抽取与 wire 编辑生产图不导入任何网关适配器parity 测试将独立版 Anthropic/Bedrock 行为与那些适配器对比profiles.go内建模型阈值、TTL、经济学参数、归因raw_usage.goprovider 缓存计数器归一化不做美元换算cmd/cache-experiment仅离线转换/经济学 fixture零 provider 调用cachebench/ cmd/cachebench严格 97% 请求/token 门槛、语义等价检查、有界公共语料导入、trace 导出、provider 观测回放cmd/cache-replay可选 live 回放精确 trace 重建、provider HTTP 鉴权/SigV4、发送前全 trace 等价、绝对时间有界并发、任务验证器协议、私有留存证据、不重试cachebench/scripts/哈希钉住的 LMCache 下载与 parquet 转 JSONL 流式辅助脚本PyArrow 只是可选基准工具绝非运行时代码核心契约从 Capability 到 Plan规划器认识的是“能力数据”而不是 provider 名字。核心类型全部定义在 cacheengine/types.go四种缓存控制语义Mode见 types.go#L11-L16ModeUnsupportedprovider 无缓存能力直接放行ModeImplicitprovider 隐式管理缓存引擎只观测不干预ModeAffinity引擎通过亲和路由键affinity key提升同一前缀落在同一缓存条目上的概率ModeExplicit引擎可以向请求体写入显式断点/缓存控制字段。四级归因Attributionnone/organic/affinity/causal。它回答的是“一次 provider 确认的命中能证明什么”。例如 Gemini 的隐式缓存命中是organic——它提升了缓存表现但永远不能归因为引擎因果所致只有显式写入断点且 provider 确认命中的场景才是causal。四种决策Decisionapply已改写 wire 体、observe_only仅观测、pass_through放行原字节、new_epoch显式开启新的冻结前纪元。Profile结构types.go#L68-L85携带ID、Provider、Mode、Attribution、MinPrefixTokens、MaxBreakpoints、EconomicsKnown、WriteMultiplier、ReadMultiplier、TTL、Rolling、RoutingKey、MaxRPMPerKey、OptimizerID等字段。Segment表示有序 prompt 前缀的一个组成部分其中Stable是调用方拥有的事实——在一个 epoch 内可能变化的内容绝不允许被标记为 stable。通用规划器示例README 给出的最小嵌入方式完整继承可直接编译运行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}, }, })ExpectedCalls的语义必须精确理解它指“在 provider 缓存条目保持温热TTL 内预计共享该前缀的调用次数”不要把跨越缓存过期间隙的终身总调用数填进来。经济学字段使用输入费率单位一次单位 一个按全输入费率计费 token从不猜测美元。token 数未知时安全转换仍可用但经济学标记为 unavailable。NativeRequest面向 provider 原生请求types.go#L187-L209除上述字段外还有Provider、Model、Region、Endpoint、Body、RuntimeMode、AuthMode、PrefixTokens应优先来自 provider 计数为零时转换仍可行但阈值/经济学资格未知、StableSegments自定义 provider 绕过内建 envelope 抽取与Profile仅对注册了自定义 Driver 的 provider 允许按请求覆盖内建编译器拒绝 per-request 能力覆盖。官方示例见 cacheengine/example_test.goresult, err : engine.Optimize(context.Background(), 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 // 所有不安全/不支持路径返回原始字节Break-even 数学只选正收益断点规划器核心在 cacheengine/engine.go。Plan的入口校验、前缀抽取、波动检测、经济学计算见 engine.go#L102-L221。断点候选的逐段递推逻辑在breakpointCandidatesengine.go#L359-L416按序对 stable 段做 length-prefixed 帧化appendFramename 与 content 各 4 字节大端长度前缀累计 token 数每个位置要求ExpectedCalls 2少于两次复用没有意义且累计 token 数达到profile.MinPrefixTokens下限否则记录belowMinimum并跳过经济学已知时计算净收益输入费率单位net cumulativeTokens * (calls - WriteMultiplier - (calls-1) * ReadMultiplier)直觉是写一次缓存多付WriteMultiplier倍费率之后每次读取只付ReadMultiplier倍费率。若net 0则记为negativeEconomics并跳过更长的前缀不允许拥有更高的预期复用次数longer prefix cannot have higher expected reuse违反即报错净收益为正的段生成带PrefixSHA256的候选断点连续相同ExpectedCalls的候选只保留最深处一个。盈亏平衡调用数由breakEvenCallsengine.go#L418-L428线性搜索最小的calls2 起上限 10000使calls - WriteMultiplier - (calls-1)*ReadMultiplier 0。以 Anthropic 典型 1.25/0.10 倍率为例第 2 次调用即净收益转正所以断点几乎总能入选经济学未知时breakEvenCalls返回 0绝不猜测。候选超过MaxBreakpoints时limitBreakpointsengine.go#L430-L444按净收益降序选前 N 个再按原始顺序排序保证选中的是“最赚钱”的边界且 wire 顺序不乱。对ModeImplicit如 GeminiPlan会把所有断点的净收益清零、EconomicsBasis置为provider_managed_unattributed并把决策改为observe_only——引擎从不把 provider 自主管理的缓存算作自己的功劳。Stable Prefix、Epoch 与漂移守护CLAUDE.md 的不变式规定“Epoch意味着一个冻结的 stable 前缀字节变化必须走StartEpoch静默前缀漂移直接放行。”实现上stablePrefixengine.go#L323-L348只接受开头连续的Stable Cacheable段遇到第一个非 stable 段即止段名唯一、非空、长度受限且帧化总字节数必须低于MaxStablePrefixBytes默认 64 MiB超限在复制/拼接之前拒绝。前缀摘要SHA-256连同Scope/Epoch/ProfileID组成的 epoch key 交给cacheguard来自 shared/platform/cacheguard做漂移检查如果同一 epoch 下前缀字节与冻结记录不一致返回WarningPrefixDrift规划器将其翻译成ReasonPrefixDrift并放行原始字节不尝试“追着漂移走”。显式开启新纪元用StartEpochengine.go#L224-L266它拒绝波动内容进入稳定纪元volatile content cannot start stable epoch并返回DecisionNewEpoch。cacheguard.DetectVolatile检测前缀中的易变内容时间戳之类引擎另有一个 LRU 式prefixSafetyCacheengine.go#L498-L533缓存“已知安全”前缀摘要容量 8192避免对同一稳定前缀反复跑波动检测。StartEpoch也用于 compaction 场景agent 历史每 64 轮压缩一次时开启新纪元其冷写入计入分母见下文 cachebench。Scope 与亲和键分片不变式要求“Scope必填且在生成 provider 可见路由键之前被哈希”内建 profile 显式绑定唯一 provider。分片与路由键生成在 engine.go#L446-L472keyShard当ExpectedRequestsPerMinute超过profile.MaxRPMPerKey内建 OpenAI profile 为 15时分片数count 1 (RPM-1)/MaxRPMPerKey再被MaxKeyShards默认 64可配 1..1,000,000见 types.go#L143-L163封顶触顶时警告routing_key_shard_cap_reached。分片号由PartitionKey缺省回退Epoch的 SHA-256 取模得到同一 partition/epoch 内路由键保持稳定。routingKey对scope 0x00 profileID 0x00 prefixSHA256 0x00 shard做 SHA-256取前 16 字节十六进制。tenant 名称、epoch、前缀内容都不出现在键中只以摘要形式参与哈希——这就是“租户不透明、按负载分片”的 affinity key。请求身份、段名、profile ID、路由元数据全部有长度上限并拒绝控制字符validIdentity见 cacheengine/validation.go 与 engine.go#L268-L302 的校验调用。Provider 原生 Wire 编译Optimize 全流程Optimizenative.go#L18-L185是引擎的总入口按序执行一串 fail-closed 闸门任何一关不通过都返回拷贝后的原始字节并给出明确原因原因常量见 types.go#L38-L55字节上限Body超过MaxRequestBytes直接报错身份校验validNativeIdentity失败记malformed_requestRuntimeMode record→record_mode放行AuthMode非空且非payg→non_payg放行内建 provideranthropic/openai/bedrock/gemini必须提供Model与Endpoint且端点在白名单内native.go#L187-L200Anthropic/v1/messagesOpenAI/v1/chat/completions、/v1/responsesBedrockconverse/converse-stream/invoke/invoke-with-response-streamGeminigenerateContent请求体必须是唯一键JSON 对象严格流式解析器inspectUniqueJSONObject深度上限 512重复键、非对象根、尾随字节全部判 malformedbody 内model字段与request.Model不一致 →profile_mismatchcaller-managed 检测cacheMarkerAtnative.go#L395-L409识别各 provider 的既有缓存控制标记——Anthropic 的cache_controltools/system/messages content 路径下、OpenAI 的顶层prompt_cache_key/prompt_cache_options与内容块上的prompt_cache_breakpoint、Bedrock 的cachePoint/cache_control、Gemini 的顶层cachedContent。只要发现调用方已自行管理缓存引擎即让路caller_managed。CLAUDE.md 的不变式“调用方缓存字段永远优先”由此落地profile 解析内建 provider 不允许按请求注入Profile否则profile_mismatch由defaultProfile解析后经builtinProfileCompatiblenative.go#L238-L258逐字段核对模式、归因、断点数、TTL、Rolling、RoutingKey、OptimizerID任何一项偏离即拒未提供StableSegments时用nativeStablePrefixnative.go#L339-L393从请求体抽取稳定前缀provider、model 加各 provider 的稳定字段Anthropic 的toolssystem、OpenAI 的tools/instructions、Bedrock 的toolConfigsystem、Gemini 的systemInstructiontools再拼接对话序列开头的连续 system/developer 消息交给Plan决策非apply即止步按 provider 编译 wire 体输出为空、超限、优化器 ID 非法或与原体完全相同都回退为transform_unavailable放行。各 provider 的内建行为完整继承自 README 表格表面行为归因上限Anthropic复用既有 stable tool/system 断点新增滚动顶层 automatic caching因果级 provider 观测独立版美元保持为零OpenAI GPT-5.6 家族作用域亲和键 1 个稳定断点与最近 3 个显式断点body 中无安全可标记块时退化为仅亲和因果级 provider 观测仓库内已验证账本扩展尚未构建早期 OpenAIprovider automatic caching 之上的作用域亲和键仅亲和Bedrock Anthropic Claude复用 catalog 门禁的 stable 点并追加滚动 message 检查点因果级 provider 观测独立版美元保持为零Gemini观测 provider 隐式管理缓存不改写 bodyorganic永不归因引擎未知 provider精确放行不可用OpenAI 断点标记策略值得细看openai.go#L41-L106显式模式保留“1 个稳定锚点 最近 3 个可缓存消息块”共最多 4 个prompt_cache_breakpoint: {mode:explicit}标记。GPT-5.6 显式模式不做“无法标记前缀就回退自动缓存”——保留上一轮滚动标记能让第 N1 次请求读取第 N 次写入的前缀同时最多只新增一次滚动写入。字符串 content 会被转成 content block 数组再加标记这一步是 wire 等价的CLAUDE.md 不变式OpenAI 的 string-to-content-block 转换仅当显式断点语法要求时才使用。标记按索引降序执行插入确保每次替换都不使更早 span 失效。Anthropic的applyAnthropicnative.go#L260-L272先复用既有稳定断点再用jsonsplice.AppendObjectFields在顶层追加cache_control: {type:ephemeral}字段已存在则不动返回两个优化器 IDanthropic-cache-breakpoints与cave-cache-anthropic-rolling-v1。Bedrock的appendBedrockRollingnative.go#L290-L337按端点区分converse 系在最后一条消息 content 追加{cachePoint:{type:default}}invoke 系把最后一条消息的文本内容块加上cache_control: {type:ephemeral}字符串 content 先等价转为 block。若 OpenAI 显式模式未能写入任何断点结果会把归因从 causal 降级为 affinity 并记affinity_fallbacknative.go#L179-L183。成功应用时ClaimBasis inferredVerifiedSavingsUSD恒为 0——CLAUDE.md 不变式“managed gateway 拥有唯一经核验的记账方法”由此体现。内建 Profile 与模型阈值defaultProfileprofiles.go#L12-L70按 provider 分发阈值数据全部落在profiles.goProvider判定条件模式/归因最小前缀最大断点TTL其他Anthropiccatalog 具备prompt_cache能力explicit / causal按模型 512–4096anthropicMinimumprofiles.go#L181-L19345 分钟Rolling无路由键OpenAI GPT-5.6 家族模型名gpt-5.6/gpt-5.6-*前缀profiles.go#L176-L179explicit / causal1024430 分钟Rolling 路由键15 RPM/key其他 OpenAIcatalog 具备prompt_cache_key能力affinity / affinity204815 分钟Rolling 路由键Bedrockcatalog 中anthropic.claude-*模型具prompt_cache能力且端点为 converse/invoke 系profiles.go#L105-L138explicit / causal按模型 1024–4096bedrockMinimum45 分钟RollingGeminicatalog 具备explicit_cache能力implicit / organicgemini-2.5: 2048gemini-3: 4096其余 0profiles.go#L207-L2171—Rolling经济学未知其他—无 profile返回 false → 放行注意openAIExplicitModel刻意保持狭窄旧模型拒绝显式缓存字段官方契约只点名 GPT-5.6 家族未来家族需要 profile 数据或显式调用方覆盖而不是猜测请求。经济学倍率不是写死的cacheMultipliersprofiles.go#L149-L171优先从 catalog 价格数据推导CacheWritePerMillion / InputPerMillion、CacheReadPerMillion / InputPerMillion支持按 Region 取价无定价数据时回退到保守默认1.25/0.10OpenAI 亲和路径写倍率为 1。模型能力数据来自 shared/platform/catalog价格来自 shared/platform/cost。缓存计数器归一化永不“铸美元”响应侧证据由 cacheengine/raw_usage.go 负责对应 CLAUDE.md 布局中“provider cache-counter normalization; no dollar minting”。NormalizeRawCacheUsageraw_usage.go#L166-L268将各 provider 官方计数器映射为统一的UsageObservationProvider读取字段OpenAIinput_tokens_details或prompt_tokens_details二者必有且仅有一个中的cached_tokens与cache_write_tokensAnthropiccache_read_input_tokens、cache_creation_input_tokens并与cache_creation.ephemeral_5m/1h_input_tokens明细交叉核对矛盾即失败BedrockcacheReadInputTokens、cacheWriteInputTokensGeminicachedContentTokenCount回退total_cached_tokens未知 provider、重复键、负数/小数计数器、OpenAI 双字段歧义、Anthropic 总额矛盾一律 fail-closed 返回不可用。Observetypes.go#L257-L280把归一化结果与NativeResult组合成Observation区分 hit/write/miss/unavailableAttributedToEngine仅在“引擎确实应用了优化器且 profile 归因为 causal”时为真。ObserveRawCacheUsage额外覆盖 OpenAI GPT-5.6 的cache_write_tokens——旧版共享响应归一化器可能不暴露它。ExtractProviderUsageraw_usage.go#L25-L120更进一步从完整非流式响应抽取 usage 对象并绑定 provider 计数的输入 token 分母Anthropic/Bedrock 的总量 未缓存 缓存读 缓存写溢出、重复键、缺失总量全部失败关闭。CacheObserved字段专门区分“观测到零/未命中”与“响应里根本没有缓存计数器”避免把缺失当未命中。扩展新 ProviderDriver 与 Profile ResolverCLAUDE.md 与 README 给出同一契约提供能力 profile 加Driver规划器保持不变内建 profile 必须显式绑定ProviderDriver 收到选定的断点无法安全编译时必须返回原字节且不带任何优化器 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, }, })Config的完整语义types.go#L143-L163MaxKeyShards默认 64有效显式值 1..1,000,000MaxRequestBytes与MaxStablePrefixBytes默认各 64 MiB显式值 1 字节..1 GiB二者都在复制/拼接之前拒绝超限ResolveProfile非 nil 时替换内建查找Drivers的键经小写/去空格归一化后必须唯一。生产构造应使用NewCheckedengine.go#L54-L56在构造期暴露配置错误遗留的New保留单返回值 API但同样保存配置错误并使所有操作失败关闭。Resolver 与 Driver 回调可能并发执行必须自身并发安全。自定义请求必须提供StableSegments否则no_stable_prefix自定义 Driver 输出不得超过配置的请求体上限优化器 ID 接受与身份字段同样严格的校验native.go#L224-L236。正确性不变式汇总CLAUDE.md 的 Correctness invariants 一节是理解这个模块设计哲学的总纲逐条列出并给出源码落点原始字节存活malformed、unsupported、caller-managed、record、non-PAYG、volatile、drifting 或不可转换的请求一律原样放行native.go#L49-L91 的闸门链永不重排或改写语义内容只追加 provider 原生缓存控制字段OpenAI 的 string-to-content-block 转换是 wire 等价的且仅当显式断点语法需要时使用openai.go#L136-L167Scope 必填并先哈希provider 可见路由键只包含摘要内建 profile 显式绑定唯一 providerbuiltinProfileCompatibleEpoch 一个冻结 stable 前缀字节变化要求显式StartEpoch静默前缀漂移放行ExpectedCalls TTL 内复用未知 token 数或缓存经济学保持 zero/unavailable绝不猜测独立版结果分级应用后的结果为inferred放行/仅观测结果为noneVerifiedSavingsUSD恒为零已核验记账方法归 managed gateway 所有自定义 Driver 在不确定时返回原字节与零优化器 ID公开边界永不导入cloud/...。“总能命中缓存”不可能是字面保证provider 最小前缀、TTL、并发、容量、精确前缀变化、不支持的模型与有机缓存都可能导致未命中。引擎的职责是最大化合格的稳定前缀并且在无法行动时返回明确原因——15 个Reason*常量types.go#L38-L55就是这个承诺的词汇表。产品边界上READMEcacheengine 是“provider 提示词前缀规划器”只做元数据级请求转换provider 仍然运行模型并报告缓存计数器。它不存储/回放模型响应也不管理自托管 KV 内存——后者属于 exact/semantic response cache 与 self-hosted KV cache 两类完全不同的产品正确性边界不同。README 明确拒绝“市场最佳”类声明因为那需要同人群 live 计数器、任务质量验证、延迟与竞品对比。验证测试、Fuzz 与 cachebenchCLAUDE.md 的 Proof 一节给出完整验证命令原文含cd public对应原单仓目录本仓库布局中 Go module 位于仓库根含 go.mod在根目录直接执行即可go test -race ./cacheengine/... go vet ./cacheengine/... go test ./cacheengine -run ^$ -fuzz ^FuzzOptimizeMalformedBuiltinsPassThrough$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzAgentCorpusJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzObservationJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzTraceJSONLFailClosed$ -fuzztime5s go test ./cacheengine/cachebench -run ^$ -fuzz ^FuzzVerificationCommandOutputFailClosed$ -fuzztime5s go test -run ^$ -bench BenchmarkOptimizeOpenAIExplicit -benchmem ./cacheengine go run ./cacheengine/cmd/cache-experiment go run ./cacheengine/cmd/cachebench go run ./cacheengine/cmd/cache-replay -helpFuzz 目标的名字本身就说明立场FuzzOptimizeMalformedBuiltinsPassThrough验证畸形输入必须穿过引擎而字节不变四个 cachebench fuzz 目标验证所有外部 JSONL 解码器 fail-closed。cachebench 子包回答一个具体问题cacheengine 能否在一个持续使用工具的 agent 上维持至少 97% 缓存命中同时不掩盖冷启动、compaction、语义变更、非法 usage 或不支持的 provider 行为零参数运行 128 请求/provider × Anthropic/OpenAI/Bedrock/Gemini负载携带 8,192 个声明稳定 system/tool token、增长的 user/assistant 工具调用与工具结果历史每 64 轮做一次计划内 compaction开新纪元冷写入留在分母里。主门槛完整指标契约见 cacheengine/cachebench/README.mdrequest_hit_rate cache_read_tokens 0 的请求 / 所有合格请求 token_hit_rate sum(cache_read_tokens) / sum(合格 prompt 前缀 token)两者均 ≥ 目标值、每 provider 最小样本数达标、质量通过率 100%、模型可见等价失败为零、非法样本为零速率绝不排除计划内冷启动、TTL 过期、compaction 或前缀失效。低于 provider 最小前缀的请求记inelig而非 missGemini 隐式命中保持 organic进入attributed_token_hit_rate之外的通道。失败演练期望 FAIL退出码 1go run ./cacheengine/cmd/cachebench \ -providers anthropic -turns 128 -step 6m -target 0.97每个 Anthropic 请求间隔超过 5 分钟 TTL所有后续请求冷启动。程序门控失败退出 1非法输入/配置退出 2全部 provider 过门才退出 0。公共语料方面cachebench 导入 CC-BY-4.0 的 LMCache Agentic Traces钉住 revision 与 LFS 哈希有界留存内存解码上限默认各 1 GiB 且超 16 GiB 失败关闭。钉住的保守模拟结果存档于 cacheengine/cachebench/results/lmcache-agentic-traces-2026-08-10.json24,880 请求、24,706 个 OpenAI 缓存合格请求96.89% 请求命中率、95.76% 估算 token 命中率严格 97% 门槛整体 FAIL——README 如实记录这一失败因为每会话一次冷纪元在数学上就把请求命中上限压到 96.92%。这就是该模块“不掺假证据”文化的缩影模拟报告与 provider 观测报告永不混同simulation 与 live 证据是两份独立报告。cmd/cache-replay提供可选 live 回放精确 v3 trace 重建、opt-in 鉴权调用provider HTTP 鉴权/SigV4、首次真实调用前完成全 trace 优化与模型可见等价、绝对时间有界的并发 worker调度漂移过大即失败、外部任务验证器协议、私有留存证据、自动重试为零。零网络 preflight 示例go run ./cacheengine/cmd/cache-replay \ -trace /tmp/cachebench-openai.jsonl \ -max-requests 128 \ -max-declared-billed-tokens 5000000 \ -allow-ungrounded-timing \ -allow-estimated-token-budget生产 trace 省略降级开关live 执行另需-execute -accept-live-cost -output 新私有目录 -verifier-command 路径。provider 计数的计费基准由调用方自证计费 token 上限是预检约束而非实际 token/美元保证。完整凭证、评分器 wire 契约、失败语义与留存产物布局见 cacheengine/cachebench/REPLAY_PROTOCOL.md。小结cacheengine 展示了一种与“AI 网关”截然不同的缓存工程路径把缓存收益问题分解为能力建模Profile、收益计算break-even 输入费率单位、字节级安全严格唯一键 JSON、wire 等价编辑、全路径原字节存活与证据分层inferred/none、organic/affinity/causal、verified 美元恒零四个正交层再用 fuzz、parity 测试、严格 97% 门槛基准与钉住语料的诚实 FAIL 报告逐层验证。对需要在代理、SDK 或本地进程中直接内嵌 prompt 缓存优化的开发者它提供的是可审计的机制与可复制的验证命令而不是一个需要整条控制面基础设施的“黑盒网关”。进一步阅读可从 cacheengine/README.md、cacheengine/CLAUDE.md 与测试文件 engine/planner 相关的 planner_test.go、wire_parity_test.go 入手。【免费下载链接】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），仅供参考