把 AI 编程代理的 token 消耗变成客户账单：agent 原生 skill 形态 + 按项目出账 + 成本/报价双轨导出，AI 时代 Vibe coding 的商业助手
已在 Zcode Kimi-work Reasonix中实测，更适合国内agent体质！
多数 token 统计工具回答"我烧了多少"，token-bill 回答"我该向客户收多少"。
在你的 agent 项目里：
- 用
/token-bill显示这个项目的消耗 - 用
/token-bill-cost显示这个项目的成本 - 用
/token-bill-all显示所有项目的消耗和成本 - 用
/token-bill-export导出本项目的成本和报价（xlsx 格式或 csv 格式）
- 按项目出账——按项目目录聚合，不按天不按模型
- 成本/报价双轨——自用成本视图 + 对客报价视图（报价 = 成本 × 可配置系数），导出时分离成不同 sheet/文件
- agent 原生——五个 skill 直接进 "/" 菜单（带用法提示），同时也是任何 agent 都能调用的通用 CLI
- 数据源可插拔——fetcher 接口把各家 agent 的逐请求 usage 归一成统一记录
- 宿主自动识别——无需手动指定数据源：自动检测当前宿主是 ZCode / Reasonix / Kimi Work（环境变量 → 工作目录 → 进程树三层探测），并只列出本机真实存在的数据源
- 聊天界面原生可读——账单用框线字符排版，SKILL 约定 agent 以等宽代码块展示，在 Reasonix / Kimi Work 等 Markdown 聊天界面里不错位
- 跨平台——Windows / Linux / macOS，零硬编码路径
- 中文账单输出——¥ 千分位，Excel 打开零乱码（CSV 降级带 BOM）
| ccusage（18k★） | codeburn（10.9k★） | token-bill | |
|---|---|---|---|
| 用途 | 自用监控 | 覆盖 37 种工具的自用监控 | 对客户出账 |
| 聚合维度 | 天 / 月 / 模型 | 模型 / 项目 / 任务 | 项目 → 账单 |
| 价格模型 | 厂商成本 | 厂商成本 | 成本 + 报价系数（可配置利润） |
| 输出 | CLI 表格 | CLI + 报告 | xlsx 原生图表 + 对客 sheet（无公式/无单价/无系数） |
| 形态 | 独立 CLI | 独立 CLI | agent skill + CLI |
它们监控自己，token-bill 为您向客户出账。
所有价格都在 token-bill/prices.json 里：unit_prices 是四项计费单价（非缓存输入 / 缓存写 / 缓存读 / 输出，元/百万 Token），quote_factor 是报价系数（对客价 = 成本 × 系数，默认 3）。直接编辑文件即可，下次执行命令时生效；_ 开头的键是注释。也可以用 /token-bill-set 命令改，例如 /token-bill-set 缓存读 0.5。校验规则：单价 ≥ 0（填 0 表示该项免费），系数 ≥ 1。
不用手动装——把仓库链接甩给您的 agent，附这段指令：
克隆 https://github.com/<owner>/token-bill 并读 README.md，然后：
1. 把五个 skill 目录（token-bill、token-bill-cost、token-bill-export、
token-bill-all、token-bill-set）复制到我的 agent 的 skills 目录
（ZCode：~/.agents/skills；Claude Code：~/.claude/skills）。
如果我的 agent 没有 skills 机制，跳过这步——直接用 CLI 就够了。
2. 冒烟测试：python token-bill/scripts/bill.py --all（不带 --source，自动检测宿主数据源）
3. 汇报本机有哪些数据源可用
（检查 ~/.zcode、~/.config/reasonix 或 %APPDATA%\reasonix、~/.kimi）。
关于 Reasonix 的说明：因官方接口暂未提供项目归属字段，该源目前只能出全量账并标注"未归类 ⚠"；分模型、按天统计不受影响。等官方在用量记录里补上 session_id/topic_id 字段后，fetcher 十行内即可支持按项目出账。
给另一家 agent 出账 = 在 token-bill/scripts/fetchers/ 里新增一个文件，聚合、计费、导出层一律不动。
一个 fetcher 必须满足：
- 产出
UsageRecord记录：source, project（项目绝对路径）, date（YYYY-MM-DD 本地）, model, non_cached_input, cache_write, cache_read, output, request_count - 用
@register_fetcher("源名")注册，实现fetch(project=None, since=None, until=None) - 激活前过验收清单：
- 存储位置与文件格式确认（含压缩格式）
- 四项计费字段完备且独立——否则诚实降级为两项（输入合计/输出），并在输出中显著标注"无缓存拆分口径，价格为估算"
- 输入/缓存包含关系在全量数据上验证非负
- 项目归因键存在（不存在则归入
未归类 ⚠，禁止猜测） - 时间戳在 Python 层转换（单位 + 本地时区）
- 子代理/子会话用量计入且只计一次
- 参考实现：读
fetchers/base.py和任意现有 fetcher（如zcode.py）
您的 agent 拿着这一节 + fetchers/ 目录就能自己写出新 fetcher，欢迎 PR 回来。
v2.0.1（2026-09-10）
- 新增宿主自动识别：
--source缺省时自动检测当前 agent（环境变量 → 工作目录 → 进程树三层探测），只列出本机真实可用的数据源 - 新增无项目归因源的友好降级：该源无项目归属字段时自动给全量账并标注"未归类 ⚠"，不再报错或出空账单
- 修复纯 Kimi Work / 纯 Reasonix 环境下误报 zcode 可用、误落 zcode 兜底的问题
- 修复表头框线在部分终端右边框错位（歧义宽度字符根因，改为无右边框横幅）
- 明确聊天界面展示约定：账单以等宽代码块展示，框线不错位（写入 SKILL.md 供 agent 遵守）
- 移除 DeepSeek Harness 数据源（未实测不发布，待实装验证后按 fetcher 契约接回）
- 修复 SKILL.md 执行示例的代码围栏嵌套错误，参数提示同步移除 dsh 选项
v2.0.0（2026-09-09）首发
- 五命令（bill/cost/all/export/set）、三数据源（ZCode/Reasonix/Kimi Work）、成本报价双轨导出（xlsx 原生图表/CSV 降级）、跨平台
感谢以下同类工具的启发：ccusage、codeburn、TokenTracker、splitrail。它们监控自己的消耗，token-bill 为您向客户出账。