Agent Cost Ledger：不把缺失 usage 当成 0 元的 AI 编程成本账本

统计 AI 编程成本看起来只是“Token 数乘以单价”，但真实数据经常不完整：有的 Provider 没有返回 usage，有的模型缺少价格，有的缓存 Token 有数量却没有单价。

如果把这些情况直接显示成 0 元，报表虽然整齐，却会给出错误结论。

agent-cost-ledger 是我做的一个独立 Token 与费用账本。它不会代理或截获模型请求，也不是 Claude Code 插件；它负责读取明确的使用事件，并把“已知费用”和“数据缺失”区分开。

项目地址：https://github.com/Wanbinyu/agent-cost-ledger

当前版本为 v0.3.2，支持 Python 3.11 及以上版本。

费用如何计算

当 Token 数和单价都存在时，账本按每百万 Token 价格计算输入、输出以及可选的缓存费用。

遇到不完整数据时，它不会伪装成精确结果：

• Provider 没有返回 usage：标记为 usage_missing
• cache Token 有数量但没有价格：计算已知部分并标记 partial
• 没有单价但事件提供 cost_usd：保留 Provider 给出的费用
• 模型缺少价格：明确保留未定价状态，而不是显示为免费

安装和体验

推荐通过 pipx 安装：

pipx install git+https://github.com/Wanbinyu/agent-cost-ledger.git@v0.3.2
cost-ledger --version

不需要 API Key 就能运行内置演示：

cost-ledger demo

手动记录一条使用量：

cost-ledger add -p openai -m gpt-4o-mini -i 100 -o 50 \
  --input-price-per-1m 0.15 --output-price-per-1m 0.6
cost-ledger report

如果使用 Claude Code，可以读取其项目会话中的 message.usage：

cost-ledger ingest-cc
cost-ledger report --json

本地优先

账本默认保存在当前项目的 .cost-ledger/，没有遥测，也不会自动上传数据。项目还提供一个可选的本机调试聊天 UI，默认只监听 127.0.0.1:8765，但它只是旁路调试界面，不会变成 Claude Code 的请求路由器。

这个工具适合希望按项目核对 AI 使用成本、保留原始事件，并对缺失数据保持诚实的开发者。它只回答“用了多少、已知费用是多少”；任务是否真正完成，应交给独立的验收和审计流程判断。