Token Receipt

Token Receipt

把本次 AI 对话的 Token 消耗做成一张可截图传播的 monospace 热敏纸小票。视觉优先级高于报表完整性，但数据口径必须诚实：真实日志优先，官方价格估算其次，缺失信息要明确标注。

用户怎么触发

下面这些说法默认应该直接触发：

• token receipt
• token 小票
• 对话发票
• AI 用量账单
• 把这次对话打成小票
• 看看这轮 token 消耗
• 查看本次对话 Token 消耗

Claude Code 如果装了自动触发，SessionEnd 结束时也会自动出票。

当前产品方向

• 主输出面仍然是聊天对话框里的文本小票，HTML 是跟随它一起返回的打印出口，不反过来抢主位。
• 不做二维码；底部继续保留当前的条形码 / receipt id 结构。
• 触发策略按宿主能力分层：
  • Claude Code：使用 SessionEnd auto trigger + 触发词。
  • Codex：使用触发词。
  • Kimi Code：使用 --agent-tool kimi-code（可读 context.jsonl 里 _usage 累计）。
  • OpenCode：使用 --agent-tool opencode（读默认数据目录下 opencode*.db SQLite，或 --session <db> --opencode-session-id ses_...）。
  • Trae：使用触发词。
• 不要假设所有宿主都有 Claude Code 那种 lifecycle hook。只有验证过支持 SessionEnd hook 的宿主，才做自动触发安装。

快速执行

优先运行脚本生成小票：

python3 scripts/token_receipt.py

如果是在任何支持的聊天宿主里手动触发，不要让 receipt 只停在 Bash stdout。 优先统一走聊天回复模式：

python3 scripts/token_receipt.py --agent-tool codex --chat-reply
python3 scripts/token_receipt.py --agent-tool claude-code --session ~/.claude/usage-data/session-meta/${CLAUDE_CODE_SESSION_ID:-$CLAUDE_SESSION_ID}.json --chat-reply
python3 scripts/token_receipt.py --agent-tool kimi-code --chat-reply
python3 scripts/token_receipt.py --agent-tool opencode --chat-reply

这会同时做三件事：

• 把完整 receipt 作为聊天回复主体打印出来
• 自动落一份 /tmp/token-receipt.html
• 在回复底部附上 [Printable HTML](file:///tmp/token-receipt.html)

不要先跑一遍默认命令，再 grep 会话文件后重跑第二遍；那样只会在工具输出里刷出多张 logo。

常用参数：

python3 scripts/token_receipt.py --agent-tool codex --model gpt-5.4 --width 48 --stream
python3 scripts/token_receipt.py --agent-tool kimi-code
python3 scripts/token_receipt.py --agent-tool opencode
python3 scripts/token_receipt.py --provider anthropic --agent-tool claude-code --model claude-sonnet-4-5 --input-tokens 12487 --cached-input-tokens 8742 --output-tokens 3215
python3 scripts/token_receipt.py --provider openai --agent-tool trae --model gpt-5.4 --input-tokens 12487 --output-tokens 3215
python3 scripts/token_receipt.py --provider alibaba --agent-tool trae --model qwen3.6-plus --input-tokens 1000000 --output-tokens 1000000
python3 scripts/token_receipt.py --footer-tone snarky --conversation-summary "用户正在反复打磨 Claude Code 小票的传播视觉"
python3 scripts/token_receipt.py --show-fields
python3 scripts/install_claude_auto_trigger.py
python3 scripts/uninstall_claude_auto_trigger.py

脚本在交互式终端里默认会逐行打印；如果当前 stdout 不是 TTY，则会一次性输出完整小票。要强制逐行打印用 --stream，要强制整块输出用 --no-stream。若是在聊天框里回复，则把输出包在 Markdown 代码块里返回给用户，保持 monospace 视觉。

调用模式

• 默认目标是：让用户在对话框里直接看到完整 receipt 本体，而不是只看到 RECEIPT # / TOTAL / USD ESTIMATE 这种摘要。
• 只要 skill 是在聊天里被调用，优先返回完整 receipt 代码块；不要只汇报“已打印到终端”。
• 所有适配软件默认都走统一的聊天回复模式：--chat-reply。
• --chat-reply 会自动写出 /tmp/token-receipt.html，然后把 receipt 代码块和本地文件链接一起回出来。
• 终端 PTY 打印只是附加演示路径，不是默认主路径。只有用户明确说“打印到终端”“去 terminal 跑”时，才把终端当主输出面。
• 如果宿主支持 token streaming，回复内容尽量只放 receipt 本体，少写解释，让它在对话框里自然流出来。
• 如果宿主不支持把工具 stdout 增量渲染进聊天气泡，skill 也不能强行让 UI 逐行冒字；这时仍然应该把完整 receipt 贴回对话框，而不是退回成摘要。

聊天回复契约

• 默认回复必须是聊天友好的完整产物：receipt fenced code block + [Printable HTML](file:///tmp/token-receipt.html)。
• 代码块前后不要再加解释、总结、状态汇报、字段摘录、项目符号。
• 不要只返回 RECEIPT #、TOTAL、USD ESTIMATE 这种摘要。
• 在 Claude Code 里，如果需要用 Bash 跑脚本，优先直接用 --chat-reply；不要再手动拼 --write /tmp/token-receipt.txt + --write-html ... 的双步流。
• 只有在生成失败、字段缺失到无法出票、或用户明确要求解释时，才允许跳出这套默认回复格式；即便如此，也先给最短说明，再给 receipt 或错误原因。
• 推荐形态如下：

```text
<full receipt here>
```

[Printable HTML](file:///tmp/token-receipt.html)

数据口径

1. 默认行为应该是“按当前软件取数”：
   • 在 Codex 里运行，就读 Codex 会话。
   • 在 Claude Code 的 hook 或会话里运行，就读 Claude Code usage log / transcript。
   • Kimi Code（Kimi CLI）：--agent-tool kimi-code，读 context.jsonl 里 _usage.token_count，为上下文累计而非 API 分项，美元估价会显示 UNMAPPED。
   • OpenCode：~/.local/share/opencode/opencode*.db（或 OPENCODE_DATA_DIR / %LOCALAPPDATA%\\opencode）里 assistant 消息的 tokens.input / cache.read / cache.write / output / reasoning 与 modelID（provider/model）；--scope latest-turn 取最后一条有 token/cost 的 assistant；session 对会话内多条 assistant 求和。根会话来自 session 表不含 parent_id 的行（归档列缺失时降级查询）。
   • 不允许因为别的软件日志更新得更晚，就跨软件偷读。
2. 如果当前运行环境识别不出软件，而且本机同时存在多套日志，必须显式传 --agent-tool codex、--agent-tool claude-code、--agent-tool kimi-code 或 --agent-tool opencode；不要猜。
3. 默认使用最新 token_count 事件里的 last_token_usage，即“最新一轮小票”。
4. 如果用户要求累计账单，使用 --scope session 读取 total_token_usage。
5. 供应商优先读 session_meta.payload.model_provider；模型名先读 session_meta.payload.model*，若没有再回退读 turn_context.model；都没有时再要求调用者传 --model，否则小票显示 MODEL: UNRECORDED。
6. 价格只按 references/pricing.json 的官方价格表估算。匹配不到模型时显示 PRICE: UNMAPPED，不要自己编金额。
7. 价格表按模型条目保留币种；美元模型显示 USD ESTIMATE，人民币模型显示 CNY ESTIMATE。GLM 使用已标注的百炼 CNY 公开价格，MiMo 使用 OpenRouter 路由价格；不要把平台价伪装成厂商直连账单。
8. 主标题使用 THANK YOU FOR CODING WITH ...，让它更像真实品牌小票；不要在票面再放 DATA: SNAPSHOT。
9. 顶部 logo 按软件决定：Codex、Claude Code、Trae、Kimi Code、OpenCode 各有对应块标；感谢语仍按模型/供应商（Claude/GPT/Qwen…），不要把宿主 logo 当成模型名。
10. 用户切换语言时：

• 英文：--language en
• 中文：--language zh-CN
• 如果用户直接说“中文版小票 / English receipt”，调用时就要带对这个参数。

11. 运行 --show-fields 可以查看当前日志里真实可读的字段。更详细说明见 references/available-fields.md。

架构

• token_receipt/data.py
  • 负责读取 Codex JSONL、Claude usage-data、Claude transcript model、Kimi Code context.jsonl、OpenCode SQLite、价格表和字段能力报告。
• token_receipt/render.py
  • 负责品牌头图、票面排版、footer、条形码和最终 receipt 文本。
• token_receipt/hooks.py
  • 负责 Claude Code SessionEnd hook 的 payload、安装和卸载。
• scripts/token_receipt.py
  • 只是 CLI 薄入口，不再堆所有业务逻辑。

触发策略

1. Claude Code
   • 对标 claude-receipts 的 SessionEnd hook。
   • 已提供安装器：python3 scripts/install_claude_auto_trigger.py
   • 已提供卸载器：python3 scripts/uninstall_claude_auto_trigger.py
   • 会话结束自动出 receipt；用户在会话中主动说“token receipt / token 小票 / 对话发票 / AI 用量账单”时也能触发。
2. Codex
   • 当前按触发词调用，不假设存在 SessionEnd hook。
3. Kimi Code（Moonshot kimi-cli）
   • --agent-tool kimi-code；可用环境变量 KIMI_SESSION_ID 指明会话，KIMI_SHARE_DIR 覆盖数据目录；或 --session ~/.kimi/sessions/<hash>/<id>/context.jsonl。
4. OpenCode
   • --agent-tool opencode；OPENCODE_SESSION_ID；--session <opencode*.db> --opencode-session-id ses_...；可选 OPENCODE_DATA_DIR。
5. Trae
   • 当前按触发词调用，不假设存在生命周期 hook。

Kimi Code 一键示例

python3 scripts/token_receipt.py --agent-tool kimi-code
python3 scripts/token_receipt.py --session ~/.kimi/sessions/<hash>/<session-id>/context.jsonl

更细的触发词设计见 references/trigger-phrases.md。

OpenCode 一键示例

python3 scripts/token_receipt.py --agent-tool opencode
python3 scripts/token_receipt.py --session ~/.local/share/opencode/opencode.db --opencode-session-id ses_xxx --scope session

视觉原则

• 默认宽度 48 字符；Logo 区可使用 █░▒▓▐▛▜▌▘▝ 像素字符，金额区允许人民币符号 ¥，其他票面尽量使用 ASCII。
• 顶部要像品牌小票，而不是普通表格：
  • Codex：使用用户指定的半色调像素标志 + CODEX。
  • Claude Code：使用参考图的像素螃蟹轮廓等比缩小版 + CLAUDE CODE。
  • Trae：使用用户指定的像素块标志 + TRAE。
  • Kimi Code：方块组成的标志 + KIMI CODE。
  • OpenCode：块状标志 + OPENCODE。
  • 未识别供应商：AI CHECKOUT。
• 中段用真实小票结构：ITEM / TOKENS 两列、横线分隔、数字右对齐。
• 三个工具通用的稳定票面字段固定为：Input Tokens、Output Tokens、Cache Read Tokens、TOTAL。这些字段只有能从日志或手动参数中查到时才打印；不要把未确认字段写上小票。
• 可选字段固定为：Reasoning Tokens、Cache Write Tokens。有真实字段就显示，没有就省略；其中 Cache Write Tokens 在 Codex 日志中通常没有，Anthropic cache 相关数据或手动参数提供时才显示。
• 当前 Codex 日志常见可读字段包括 input_tokens、cached_input_tokens、output_tokens、reasoning_output_tokens、total_tokens、model_context_window。
• 不再输出 SCOPE LATEST-TURN；改为 CONTEXT USED，展示本轮上下文输入量，若有上下文窗口则显示 used/window。
• TOTAL 要有视觉重量，底部必须有短口号、ASCII 条形码、receipt id。默认 footer 不是固定句库抽签，也不是 subject/resource/artifact 这类槽位拼句；它应该更像模型对这次对话的短吐槽或短鼓励。调用时优先用 --conversation-summary 传入当前对话一句话总结，也可以用自定义 --footer。
• 更详细的布局规则见 references/receipt-style.md。

验证

完成或修改 Skill 后至少运行：

python3 scripts/validate_receipt.py

它会检查行宽、必备字段、Claude block logo、条形码、未知价格降级，以及未固定字段不会被打印。