caveman Provider CatalogToken 价格单一事实源、双日期溯源与不可变快照钉住机制【免费下载链接】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本文以shared/provider-catalog/CLAUDE.md为核心系统讲解 caveman 仓库中 provider model 定价目录provider catalog的完整设计它如何作为网关gateway与优化器optimizer做成本核算与省钱计算的唯一数据来源如何区分verified_at价格溯源与capabilities_verified_at能力溯源两类日期如何用不可变带日期快照immutable dated snapshot把每一行价格钉在被真实核对过的证据上以及为什么capabilities里藏着三个穿着能力外衣的价格。读完本文你可以完整理解并复用这套价格即数据、数据可审计的目录治理方案。目录定位数据 Schema没有运行时代码shared/provider-catalog在 caveman 中的角色非常明确它是 input、output、cache-read、cache-write、reasoning、batch 六类 token 价格的单一事实源single source of truth被网关与优化器消费用于成本核算cost accounting与省钱数学savings math。这个模块本身不含任何运行时代码——只有数据和 schema读取逻辑放在平台侧的 Go 包里。模块的目录结构由三部分构成对应 CLAUDE.md 的 Layout 一节catalog/current.yaml — 线上生效目录覆盖 OpenAI、Anthropic、Gemini、Bedrock、Vertex 五家 provider 的精确 provider/model/region 行。CLAUDE.md 写作时为 44 行本仓库当前检出的文件中是 50 行说明文档数字随目录增长存在滞后以文件实际内容为准。catalog/YYYY-MM-DD.yaml— 按日期命名的历史快照与 current 并排保存。凡是当前某行verified_at指向的快照永远不能删除唯一的窄例外是由错误 re-attest 铸造、且无任何行引用、也从未发布的快照如2026-07-30.yaml已于 2026-08-01 删除因为它保留着一次没人做过的价格复核的虚假背书。schemas/provider-catalog.schema.json — JSON Schemadraft 2020-12每个 catalog 文件都必须满足它。需要特别注意的是文档在 Gotchas 中强调的一点package.json里的build/lint/test脚本并不会把 catalog YAML 按这份 schema 做校验。schema 文件是发布出去的 OSS 镜像和社区价格 PR 所阅读的契约而真正强制执行的门禁是 validate_catalog.py 与 Go 侧的 catalog 测试见后文。行结构一行目录数据长什么样每个条目必须包含 8 个字段provider、model、region、currency、pricing、capabilities、sources、verified_atcapabilities_verified_at是可选的早期快照没有它但当前每行都应当携带。下面用 current.yaml 中的两条真实行来说明。一个字段齐全的 Anthropic 行含限时定价注释L278-L311- provider: anthropic model: claude-sonnet-5 region: global currency: USD # Introductory pricing through 2026-08-31; standard pricing from 2026-09-01 is # 3.00/15.00 with cache read 0.30, cache write 3.75 (5m) / 6.00 (1h). The # models.dev drift detector must roll this entry forward at the changeover. pricing: input_per_million: 2.00 output_per_million: 10.00 cache_read_input_per_million: 0.20 cache_write_input_per_million: 2.50 cache_write_1h_input_per_million: 4.00 reasoning_output_per_million: null batch_discount_fraction: 0.50 capabilities: messages_api: true effort_levels: [low, medium, high, max, xhigh] prompt_cache: true inference_geo_us_multiplier: 1.10 # 注意这是价格不是能力见后文 context_window_tokens: 1000000 tools: true vision: true json_mode: true sources: - https://platform.claude.com/docs/en/about-claude/pricing verified_at: 2026-08-05T00:00:00Z capabilities_verified_at: 2026-08-09T00:00:00Z一个诚实未知的 Bedrock 行tools/vision/json_mode 写null并附注释L743-L776- provider: bedrock model: global.amazon.nova-2-lite-v1:0 region: us-east-1 currency: USD pricing: input_per_million: 0.30 output_per_million: 2.50 cache_read_input_per_million: 0.075 cache_write_input_per_million: 0.00 cache_write_1h_input_per_million: null reasoning_output_per_million: null batch_discount_fraction: null capabilities: invoke_model: true converse: true global_inference_profile: true context_window_tokens: 1000000 # tools / vision / json_mode: NOT verified against this models AWS model # card. ... Explicit null is the honest state: the router already treats # it exactly like absent (fail-closed). Fill these in with a citation. tools: null vision: null json_mode: null sources: - https://aws.amazon.com/bedrock/pricing/ verified_at: 2026-07-23T00:00:00Z capabilities_verified_at: 2026-07-30T00:00:00Zpricing 字段全集对照 provider-catalog.schema.json 和 validate_catalog.pyL58-L71 的PRICING_KEYSpricing下共 11 个可选字段其中只有input_per_million与output_per_million必填其余不适用的字段必须显式写null而不是省略schema 允许[number,null]字段含义备注input_per_million输入单价美元/百万 token必填output_per_million输出单价必填cache_read_input_per_million缓存读取价OpenAI、Gemini 收读价Anthropic 读写都收cache_write_input_per_million缓存写入价5 分钟档OpenAI 与 Gemini 为null——它们不单独收写入费cache_write_1h_input_per_million缓存写入价1 小时档仅部分 Anthropic 行使用reasoning_output_per_million推理输出价如 Gemini 2.5 系列batch_discount_fraction批量折扣比例0.50表示打 5 折不是按标价 50% 收费之外的第三种读法保持解释一致cache_storage_per_million_tokens_hour缓存存储费美元/百万 token/小时Gemini 行使用long_context_threshold_tokens长上下文阈值超过后启用下面的乘数long_context_threshold_inclusive阈值是否含边界布尔或 nulllong_context_input_multiplier/long_context_output_multiplier长上下文输入/输出乘数如 gpt-5.6 的 2.0 / 1.5另外currency只允许USDsources必须是非空的 HTTPS 链接列表vendor 官方定价页/模型文档这两点在 Python 与 Go 两侧都被强制。核心设计两个日期是两种溯源永不混用这是整个目录最有辨识度的规则。verified_at与capabilities_verified_at是两种完全不同种类的证据provenanceverified_at只有一层含义本行价格最后一次对照 vendor 公开定价页核对的日期。它是catalogVersion()catalog.go的唯一输入而catalogVersion()会被嵌入成本报告和签名收据signed receipts作为价格溯源背书price-provenance attestation。因此只在真正重新核对价格时才 bump 它绝不能因为顺手改了能力或来源而带动它。capabilities_verified_at是本行所断言ASSERTS的能力数据最后一次对照 vendor 模型文档核对的日期。它不被任何成本/收据路径读取不嵌入任何与钱相关的东西。这里 asserts 一词是承重墙一个值为显式null的 key没有断言任何东西因此落在该日期的覆盖范围之外。正是这一点让capabilities_verified_at在那 20 行tools/vision/json_mode从未被核对过的 Bedrock 行上依然诚实——该日期仍然真实地覆盖着这些行确实在断言的context_window_tokens等 key。任何携带null路由能力的行必须附带一条指名未验证 key 的注释catalog_test.go 中的TestNullCapabilitiesCarryAnUnverifiedNote直接读 YAML 源码强制这个配对当前恰好锁定 20 行使这个收窄不会变成漏洞。由此推出的编辑规则CLAUDE.md Conventions 原意只改能力增改tools/vision/json_mode/context_window_tokens/能力类sources→ bumpcapabilities_verified_atverified_at不动只改价格 → 反向操作只有同一天真的对着两家 vendor 页面都复核了才两个都 bump撤回一条断言不是验证把一个未验证的值改成null是移除断言而非核对断言capabilities_verified_at保持原位不动——bump 它等于犯下verified_at规则要防的同一类错误日期背书了没人做过的工作只是隔了一个字段。仓库里有真实案例佐证这套纪律的必要性catalog_test.go 的注释记录了一次 2026-07-30 的能力核对误把 21 行的verified_at一并推进五个 Bedrock 行在内而 diff 中没有一个价格字节变化2026-07-31 的评审把 21 行全部回滚到真实的价格溯源日期capabilities_verified_at保留在真正挣得的 2026-07-30。TestCurrentBedrockCatalogUsesExactModelAndSourceRegionPrices则把每行的verified_at逐行钉死在期望值上wantVersion是每行各自的日期有意不是全目录统一常量。不可变日期快照把价格改动钉在证据上快照机制是整个溯源体系的地基规则如下新增模型同时写进current.yaml并复制进一个新的带日期快照例如2026-07-01.yaml。钉住什么go test ./shared/platform/catalog要求每行当前的价格相关字段——provider、model、region、currency、pricing、verified_at加上catalog.PriceAffectingCapabilities里的每个 key——必须与verified_at所指名的那份不可变快照字节语义一致byte-identical。价格真的变了却复用旧的verified_at日期测试直接失败。刻意排除什么capabilities的其余部分、capabilities_verified_at、sources被有意排除在比较之外它们允许与归档快照不同——这正是只改能力的编辑不用铸造新的价格快照的原因。sources 的半开放规则来源可以从快照中增长加一条能力引用的 URL 没问题但快照里的定价引用不能悄悄被替换或删除validate_catalog.py 做子集检查快照的 sources 必须是当前行 sources 的子集。当前检出的快照序列为2026-06-02.yaml、2026-06-14.yaml、2026-06-18.yaml、2026-07-10.yaml、2026-07-23.yaml、2026-08-05.yaml、2026-08-07.yaml、2026-08-10.yaml与各行verified_at一一对应——例如 current.yaml 中 mistral Bedrock 行全部钉在2026-07-23而 gpt-5.6 钉在2026-08-10。穿着能力外衣的价格PriceAffectingCapabilities这是目录里最反直觉、也最关键的规则某些capabilitieskey 不是能力而是价格。权威清单是 catalog.go 中的catalog.PriceAffectingCapabilitiesregional_processing_multiplier与inference_geo_us_multiplier—— 二者会乘上本行的 token 费率经PricingMultiplier→ 网关里的scaleStandaloneTokenRates。current.yaml 中 OpenAI 行普遍带regional_processing_multiplier: 1.10Anthropic 行带inference_geo_us_multiplier: 1.10Vertex 行则是region_agnostic_pricing: true。region_agnostic_pricing—— 决定一个global行的价格能否回答区域性查询PriceForRegionOrAgnosticcatalog.go。删掉某行这一个布尔可能让整个 region 的支出统计掉到零。编辑其中任何一个等同于改价格必须像改pricing一样 bumpverified_at并铸造日期快照因为不可变快照把这三个 key 与pricing一起钉住。仓库用真实事故解释了为什么TestTamperedPriceCapabilityBreaksTheSnapshotPin位于 shared/platform/catalog/catalog_test.go复现了旧排除规则造成的损失——一次1.10 → 1.95的乘数编辑让所有 OpenAI us/eu 费率虚高 77%删掉一行region_agnostic_pricing则让整个 Vertex 区域的支出归零两者当时都能通过包括快照钉住在内的所有门禁包括签名收据的catalog_version所依赖的那一个。由此确立的注册原则要新增一个影响价格的 capability注册它否则它什么都不做。PricingMultipliercatalog.go对清单外的任何 key 返回(0, false)priceAffectingBool 是定价函数读取布尔能力的唯一入口对未注册 key 一律返回 false使请求落到诚实的unpriced:零值上。测试套件还会直接解析 Go 源文件断言 validate_catalog.py 中的 Python 镜像PRICE_AFFECTING_CAPABILITY_KEYS与 Go 切片逐项相等并用TestPricingFunctionsReadNoUnregisteredCapabilityLiteral扫描源文件、禁止重新引入裸的Capabilities[...]直读。正如 catalog.go 注释所总结让未来的作者记得同步另一张表的散文正是当年让region_agnostic_pricing逃出钉住的元凶一张没人能忘记的表替代了它。诚实未知fail-closedUnknown is not false路由三布尔tools/vision/json_mode被 schema 显式声明为可空[boolean,null]。规则是vendor 自己的模型文档没写答案时写null并附注释说明查过什么绝不写猜测值。路由器candidateSupports→boolCap把null与字段缺席同等对待fail-closed诚实的未知只让你损失一个路由候选而猜true会把流量路由到可能不支持该功能的模型猜false会悄悄删掉一个本可用的候选。当前正是这条规则让 20 个 Bedrock 行带着null存在current.yaml 中每行都有 NOT verified against this models AWS model card 注释块。TestEveryCatalogEntryHasRoutingCapabilityFieldscatalog_test.go钉住的是显式值或文档化的未知而非永远得是布尔——key 必须存在新模型忘了写会在这里响亮地失败值必须是 bool 或显式 null。这条测试还记录了一个背景事实在此之前 41 个条目里只有 3 个带context_window_tokens导致路由器自己候选池里的 38/41 被拒。价格查询侧同样 fail-closed。catalog.go 的Price只对region: global的显式行放行通用查询借用第一条区域性行是顺序依赖的、会伪造支出PriceForRegion只认精确的 providermodelregion 三元组查不到时返回零价格加unpriced:provider/model版本串——未知模型产生的是可见地打了标记的诚实零而不是一个貌似合理的错误数字。TestBedrockCatalogDoesNotBorrowSourceRegionOrInventedModelPrices验证了这一点global.amazon.nova-2-lite-v1:0在eu-west-1、带后缀的伪造版本号v1:1都查不到价格。这与 current.yaml 里的注释互为印证Bedrock 的 global/geo 推理配置档不是无区域的AWS 按源区域收费所以us-east-1的行不能被其他区域借用。运行时读取与目录加载Go 侧的读取实现集中在 shared/platform/catalog/catalog.goEntry结构体L19-L46的注释完整复述了VerifiedAt与CapabilitiesVerifiedAt的溯源纪律是理解 CLAUDE.md 规则的代码级原文DecodeAndValidateL302-L363严格解析未知字段、重复 provider/model/region 行、非法 URL、未来时间戳、非 USD、空目录——任何一条都拒绝整个文件运行时永远不该加载一个貌似合理的部分目录catalogCandidatesL370-L398按序尝试候选路径环境变量CAVE_CATALOG_PATH显式覆盖具有权威性坏覆盖 fail-closed 而不是悄悄换目录、部署镜像与 CWD 相对位置、再沿工作目录向上回溯 8 级同时兼容 monorepo 布局public/shared/provider-catalog/...与发布仓库布局shared/provider-catalog/...。门禁与验证怎么检查一个 catalog 改动目录有两道强制门禁外加一道契约Python 门禁cd shared/provider-catalog python3 validate_catalog.py。validate_catalog.py 校验必需字段齐全、无未知字段currency必须 USDpricing 数值有限、非负、batch_discount_fraction 1verified_at必须是带时区的 RFC3339 且不得早于 120 天L165保证目录保鲜sources 全部 HTTPSprovider/model/region 不重复每行与其verified_at快照做pricing_identity比对identity 六个价格身份字段 该行实际携带的价格影响型 capability快照 sources 必须是当前 sources 的子集。它还有一个读原始文本的检查check_review_markersL170-L189文件里若残留# proposed-by:标记——自动同步脚本提议改价时留下的注释——则整个 catalog 判为无效因为带着标记合并等于背书没人做过的价格核对删除标记就是评审人确认过数字的声明。测试见 tests/test_validate_catalog.py。Go 门禁从 provider-catalog 目录运行go test .package.json 的build/lint/test脚本即go test ../platform/catalog ...及go test .执行前文提到的快照钉住、effort 级别钉住、null 注释配对、能力字段完整性等测试。JSON Schema 契约schemas/provider-catalog.schema.json 是发布 OSS 镜像与社区价格 PR 的契约。schema 的capabilities描述里明确写着本仓库没有任何东西把 catalog YAML 按此 schema 做校验强制门禁是上面两道三者schema、validate_catalog.py、Go 测试必须保持同步。另外两个工程细节值得记住List()返回深拷贝防止调用方改坏全局缓存的目录catalog.goContextWindowTokens要求同一 providermodel 的所有区域行取值一致缺失、非正数或冲突一律 fail-closed且对 provider 名做了google→gemini的归一化L59-L85。实战要点与坑Gotchas 汇总no-fake-savings这里的数字直接喂给 Cave Plan 的省钱头条——价格错推断的节省额就错。提交任何价格改动前对照引用的 provider 定价页验证。claude-sonnet-5行的注释是活教材限时价至 2026-08-31与标准价的切换点被写在行内注释里交由 drift 检测器在切换日滚动条目——这正是价格是版本化数据的体现CHANGELOG.md 亦声明价格行可以随数据变动而不 bump 包版本只有 schema 破坏才需要 major。cache_write_input_per_million在 OpenAI 与 Gemini 行为null不收单独写入费Anthropic 读写都收写 catalog 时不要为了填满而编一个数。batch_discount_fraction: 0.50的统一读法是打 5 折全库保持这一解释。Bedrock 行以精确的调用 model/profile ID 源区域为键global.*与us.*前缀的推理配置档各自按区域出账绝不跨区域借用。更多背景见根目录 CLAUDE.mdprovider-catalog 的 CLAUDE.md 末尾即以 See root CLAUDE.md 收束。小结caveman 的 provider catalog 用一行数据两个日期 一份不可变快照 三道语言级门禁回答了一个看似简单的问题如何保证成本报告里每一个美元数字背后都站着一张可以指认的、由人核对过的证据。verified_at/capabilities_verified_at的分立、PriceAffectingCapabilities的注册制、null 即未知且必须留注释、unpriced:诚实零、120 天保鲜期与# proposed-by:评审标记——这些规则共同构成了一套可审计、可回归测试的价格数据治理范式对任何需要在网关层做成本核算的 LLM 多 provider 系统都有直接的参考价值。【免费下载链接】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），仅供参考