receipt

用途

receipt 用于查看 AI 编码代理由实际消耗的 token 及对应美元成本，并将成本明细直接展示在每个拉取请求（PR）上，方便团队在合并代码前了解本次变更的 AI 开销。它追踪 Claude Code、Cursor、Copilot、Aider、Codex 以及任何兼容 OpenAI 或 Anthropic API 的工具。

主要能力

• PR 成本评论：在 PR 上生成一条粘性评论，显示总花费、token 数、调用次数、重试次数、预算消耗进度条、与中位 PR 的对比、历史消费趋势以及工具调用明细。
• 本地账本：使用只追加的本地账本（.receipt/ledger.jsonl）记录 token 数量、模型名称、成本、时间戳以及 git 分支或提交，不存储提示词或补全内容。
• 多种捕获方式：
  • 通过导入器：receipt import claude-code 读取 ~/.claude/projects 中的 Claude Code 会话日志；receipt import generic usage.json 标准化任意包含 prompt_tokens/completion_tokens 或 input_tokens/output_tokens 的 JSON/JSONL 导出文件。导入器基于提供商的请求 ID 去重。
  • 通过代理：代理位于工具与提供商之间，原样转发请求，从响应中读取 usage 块，计价并写入账本。支持 Anthropic（/v1/messages）和 OpenAI（/v1/chat/completions、/v1/responses）格式，包括流式响应。代理只记录 token 数量和耗时，不记录请求或响应正文。
• GitHub Action：通过示例 examples/github-workflow.yml 配置，Action 读取 .receipt/ledger.jsonl，自动发布或更新 PR 评论。也可在本地运行 receipt post 发布相同评论。
• 预算控制：设置预算上限，PR 评论会显示进度条。预算内显示绿色，超过 80% 变黄，超支显示红色并标出超支金额。
• 会话窗口追踪：针对 Claude 订阅，追踪 5 小时和每周滚动窗口的使用百分比，并转换为“还能做多少事”的直观描述。支持通过代理读取提供商速率限制头或使用 receipt calibrate 校准真实额度。
• 状态栏集成：在 Claude Code 状态栏中显示实时用量仪表，可通过 .receipt/config.json 中的 "usage": false 关闭。
• 优化建议：receipt advice 分析用量，指出纯粹浪费（如缓存重建、重试重复发送、用高价模型做机械读等），并按影响排序，给出可计算节省的美元金额。
• 会话健康度：receipt health 根据上下文填充率、会话长度、缓存复用、自动压缩、循环等信号评估会话质量下降风险，并在需要时建议 /compact、/clear、开启新会话或 /rewind。receipt guard 可作为 Claude Code 钩子自动化提醒。
• 仪表盘：receipt dashboard 提供本地视图，展示按时间、模型、分支的支出，以及最昂贵的调用，无外部网络请求。
• 库使用：可作为库集成到其他工具中。

使用方式

• Claude Code 用户：直接导入会话日志，无需重新配置：

  receipt import claude-code
  

• 其他工具：将工具指向日志代理（logging proxy）。
• 查看当前分支成本：receipt show。
• 发布 PR 评论：配置 GitHub Action，或本地运行 receipt post。
• 查看状态：receipt fuel 显示当前窗口使用情况。
• 校准限额：receipt calibrate（可加 --window week 校准每周窗口）。
• 查看帮助：任意命令加 --help。

适用场景

• 团队希望在代码审查阶段就了解每个 PR 的 AI 编码成本。
• 使用多个 AI 编码工具，需要统一追踪 token 和费用。
• 需要按分支、按作者、按模型细分 AI 开销。
• 希望在不牺牲代码质量的前提下，找出并减少 token 浪费。
• 需要监控会话健康度，避免上下文退化影响输出质量。

限制

• 价格基于公开列表价（USD/百万 token），随附 src/prices.json 标注检查月份，用户可覆盖；实际合同价格可能不同。
• 对于没有价格的模型，只统计 token 并标记为“未定价”，不虚构零成本。
• 代理不记录请求和响应正文，账本默认不纳入 git（见 .gitignore），只有希望 CI 读取时才提交。
• Anthropic 未发布确切 token 预算，receipt 提供的是按计划估算值，并标注为估算；可通过代理读取速率限制头或校准获得真实限额。
• Copilot 用量需通过通用导入器导入。
• 内置提供商支持 Anthropic、OpenAI 和 Google Gemini。

许可

MIT © Noah。详见 LICENSE。

其他信息

• 项目地址：https://github.com/noah-thing/receipt
• 欢迎提交 issues 和 PR，参见 CONTRIBUTING.md。
• 安全策略见仓库内文档。