Caveman 中的数字治理：accounting-and-evidence 文档解读与仓库源码实证

Caveman 中的数字治理accounting-and-evidence 文档解读与仓库源码实证【免费下载链接】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 用穴居人说话的方式压缩 token但压缩省了多少、花了多少本身也需要一套可审计的记账纪律。本篇基于仓库文档 docs/technical/accounting-and-evidence.md 展开讲解证据基础evidence basis这一核心概念如何落地到 token 计数、成本计算、基准测试和结果发布中并结合 engine/tokens/tokens.go、shared/platform/cost/cost.go、shared/provider-catalog/catalog/current.yaml 等源码实现说明每个数字标签背后的机制与边界。读完后你可以判断任何一个 Caveman 报告里的数字是怎么产生的、能支持什么结论、不能支持什么结论。核心思想按产生方式给数字打标签文档的开篇定下了整篇的基调Caveman labels numbers by how they were produced. Token estimate and provider usage record answer different questions from benchmark comparison or verified savings record; they must not share one label.也就是说Caveman 不把估出来的数和量出来的数混用同一个标签。token 估算、provider 用量记录、基准对比、已验证节省回答的是四个不同的问题不能共用一个名字。这是整份文档的骨架先声明证据基础再谈数字本身。七种证据基础Evidence bases文档给出了完整的七种证据基础定义表这是理解 Caveman 所有报表数字的前提Basis含义它不代表什么measured由具名的本地或 provider 机制直接计数自动可计费或因果成立inferred由本地模型、tokenizer 或假设估算provider 确认的用量provider_reportedprovider 用量字段直接返回独立发票对账benchmark_counterfactual受控 fixture 变体之间的差值生产环境节省observed真实观测中的前后相关性该变更导致了差异verified满足某条具名且被强制执行的验证方法普遍质量或未来节省unpriced没有已知的受支持公开价格真实世界零成本两张它不代表什么列是关键设计每个标签都自带否定边界。文档同时要求UI 和报告应把 basis 显示在数值旁边且一个数值在聚合过程中不能悄悄更换 basis。这一要求在仓库的契约层有对应物agent 运行收据 schema packages/shared/contracts/schemas/agent-run-receipt.schema.json 把basis与claimBasis列为必填字段且成本口径被固化为常量estimated_list_price_subtotal即估算的公开价小计从数据契约层面保证聚合值必须声明自己是怎么来的。Token 计数o200k_base 离线计数与字符估算回退文档Token counts一节写道Engine uses offlineo200k_basecounting where available and character estimate fallback. Those counts are inferred for provider billing purposes. Providers may tokenize same text differently and may count cache or image inputs under separate units.这段描述在 engine/tokens/tokens.go 中有逐句对应的实现默认计数器是内嵌词表的 BPE tokenizer。包注释明确写道Default returns the engines shared default counter: the o200k_base BPE tokenizer (the GPT-4o-family encoding)词表随二进制嵌入计数完全离线、确定性engine/tokens/tokens.go 的Default()函数用sync.Once保证单例。字符估算回退NewApproxCounter()返回的approxCounter使用约 4 字符/token的经验法则Name()返回approx-chars/4。它既是 BPE 计数出错时的回退路径Count中codec.Count失败则return approxTokens(b)也用于不需要 BPE 的场景engine/tokens/tokens.go。计数错误绝不破坏压缩源码注释强调 counting error 会落到确定性近似值而非 panic——这解释了为什么文档要求把引擎计数标记为inferred它服务于压缩比与本地显示不是计费依据。文档后半句Provider-reported token fields keep provider basis. Do not replace them with a local estimate when field is missing也对应了包级注释provider usage is authoritative downstream——本地估算和 provider 用量是两个口径provider 字段缺失时禁止用本地估算填补只能承认没有。成本计算公开目录价 × token 数且失败关闭文档Cost calculation一节定义了本地成本显示的算法provider-reported or explicitly selected token units × dated public catalog rate list-price subtotal并明确这不是发票。它可能因谈判条款、订阅、区域定价、批处理折扣、缓存规则、抵扣、税费或 provider 计费调整而与账单不同。带日期的公开价目录dated public catalog在仓库里是 shared/provider-catalog/catalog/ 目录下一组按日期命名的 YAML 文件如 2026-08-10.yaml加上一个 current.yaml。以current.yaml中 OpenAI 条目为例每行包含- provider: openai model: gpt-5.6 region: global currency: USD pricing: input_per_million: 5.00 output_per_million: 30.00 cache_read_input_per_million: 0.50 cache_write_input_per_million: 6.25 cache_write_1h_input_per_million: null reasoning_output_per_million: null batch_discount_fraction: null long_context_threshold_tokens: 272000 long_context_input_multiplier: 2.0 long_context_output_multiplier: 1.5 sources: # 公开价格来源 verified_at: 2026-08-10T00:00:00Z # dated即体现于此verified_at时间戳就是文档中dated public list prices的落地形式null字段如cache_write_1h_input_per_million: null表示该模型不适用该价格维度而不是漏填。定价算术的失败关闭实现shared/platform/cost/cost.go 实现了上式的算术部分。其EstimateUSD按互不重叠的计费桶累加未缓存输入、缓存读、缓存写、1 小时缓存写、输出、推理注释明确Invalid inputs fail closed per component负 token 数、负或非有限费率、溢出、NaN、无穷大全部贡献零而不是貌似合理但错误的数字。ValidPrice则负责拒绝目录行中的非法数值零费率仍合法用于不适用维度。这直接支撑文档的两条规则未知 provider 或模型价格 → 零 unpricedZero prevents invented cost from entering totals;unpricedprevents zero from being mistaken for free use. 零阻止虚构成本进入总计unpriced标签阻止零被误读为免费使用。代理层同样贯彻这一纪律proxy/providers/adapter.go 中PricingUnsupportedReason字段注明请求使用了目录未建模的计费维度例如音频 token 桶时下游花费必须失败关闭到显式声明 unpriced 的零。订阅与 OAuth 流量不参与列表价从源码结构看proxy/providers/adapter.go 的ListPriceEligible把认证安全与支付语义分离只有payg/api_key认证以及 Vertex 的 OAuth因为 Google Cloud 项目仍被计费才被视为可挂列表价的流量订阅制/会话制流量never receive a guessed marginal price。这与 docs/HONEST-NUMBERS.md 中按请求/积分计费的 agent如 Copilot无法靠 Caveman 省钱的结论是同一套语义计费模式决定了列表价估算是否适用。推断的 headroom时间口径不可变文档Inferred headroom一节规定本地压缩和学习报告可以在声明的假设下估算可避免的上下文headroom但时间口径必须保持不变——a per-day estimate must not become a monthly claim unless method measures each day and states that result is a projection.即按天估算的 headroom 不能直接变成月度宣称除非方法逐天测量并明确声明结果是外推projection。这条规则防止了最常见的数字膨胀方式把一个日均值悄悄乘 30。基准证据一份合格的 benchmark 报告必须写什么文档benchmark evidence一节给出了合格基准报告的七要素清单精确的 fixture 及其哈希或版本命令与代码修订版本code revision;计数器来源或 provider 用量来源基线与变体的定义质量或不变量检查失败与被排除的案例结论的适用范围。并给出两条边界结论一个 fixture 的结果只支持那个 fixture 与方法本身平均降幅不证明任务质量相等recovery 检查证明的是源可用性而非模型理解力。仓库中的实践与该文档互为印证。docs/HONEST-NUMBERS.md 是这份纪律的公开执行案例它逐条标注每个数字的测量方式例如response skill 的输入减少 0%因为它只是输出风格指令/caveman-compress对记忆文件 ≈46% 平均输入减少限定于五个列出的 fixturetoken 计数加结构检查不作普遍质量等价宣称并且明确token 计数运行只测输出长度不证明语义或技术等价。基准工具链位于 benchmarks/run.py需 Anthropic key与 evals/measure.py使用离线提交快照文档在 docs/technical/testing-and-benchmarks.md 中有更完整的运行说明。Verified 标签最严格的保留词文档Verified values一节把verified保留给前提被强制执行、且记录能标识方法的场景并列出了公共本地运行时不得仅凭自身标记为 verified 的东西Engine 估算skill 输出pixel 转换TOON 输出缓存计划合并的代码。也就是说压缩成功、转换成功都不自动等于已验证。文档的收束原则是当证据不完整时使用inferred、observed、provider-reported或诚实的零。契约层的实现与此一致packages/agent/src/budget.ts 中用量字段声明usageBasis: provider_reported | unavailable——只有provider 报告或不可用两种状态本地估算不能冒充 provider 用量而claimBasis被固定为inferred即本地代理预算声明始终自报为推断口径。保留负结果与失败项Negative and failed results一节的规则很直接Keep negative deltas and failed transformations. Dropping regressions biases a result. A rejected optimization can still incur provider usage; account for that usage even though compact output was not served.保留负 delta 和失败的转换——剔除回退会使结果产生偏差。一条被拒绝的优化同样消耗了 provider 用量哪怕最终没有服务压缩输出这些用量必须入账。这与 docs/HONEST-NUMBERS.md 中When caveman loses (net-negative)章节的写法是同一种态度文档同时发布赢的场景和输的场景如按请求计费的 Copilot、固定提示词开销超过输出节省的简短问答并给出如果你的 A/B 净亏损就关掉的操作建议。发布前检查清单Publication checklist文档最后给出发布任何数字前的七步清单命名精确的证据基础name exact evidence basis;链接已提交的 fixture 或源记录link committed fixture or source record;披露计数器与定价日期disclose counter and pricing date;说明质量测试与失败数量state quality test and failure count;区分列表价与发票distinguish list price from invoice;避免跨模型、跨 provider、跨任务、跨时间外推avoid extrapolating across model, provider, task, or time;支持缺失时发布零或unpricedpublish zero orunpricedwhen support is absent.这七步与前文的七种证据基础构成闭环清单第 1 步要求选 basis第 3 步对应目录的verified_at与 fixture 提交第 7 步对应成本层的失败关闭设计。当前受支持的公开数字声明汇总在 docs/HONEST-NUMBERS.md。小结一套诚实数字的工程实现把 docs/technical/accounting-and-evidence.md 放回仓库看它不是纯风格指南而是一套有代码背书的记账规范文档规则仓库中的实现证据数字必须带证据基础标签agent-run-receipt.schema.json 中basis/claimBasis为必填字段口径固化为estimated_list_price_subtotal本地 token 计数是inferredengine/tokens/tokens.goo200k_base 离线 BPE approx-chars/4回退包注释声明 provider 用量才是下游权威成本 provider 计量 × 带日期目录价shared/provider-catalog/catalog/current.yaml 的verified_at日期行 shared/platform/cost/cost.go 的分桶计价未知价格 → 零 unpricedcost.go 的 fail-closed 算术 proxy/providers/adapter.go 的PricingUnsupportedReason保留负结果docs/HONEST-NUMBERS.md 同时发布胜负场景并指导净亏损时关闭功能对使用者的实用结论是看到 Caveman 报告里的任何数字先看它旁边的 basis——provider_reported才能对账账单inferred只适合比较相对变化benchmark_counterfactual只在其 fixture 与方法范围内有效verified意味着有被强制执行的方法存在。理解了这一层仓库中的每个报表数字都是自解释的。【免费下载链接】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），仅供参考