1Lany2a/token-usage-report

Token 用量报告

读取 Agent 的本地回放文件，打印最近一个对话分段的用量 以及 整个会话（两行）：

本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50

为什么需要两行？整个会话的数据由脚本本地计算（无需额外模型调用），因此报告它们只会在回复中增加几十个字符——Token 开销可以忽略不计，用户还可以对比当前轮次与会话总量。

何时运行

• 在 每次会话的最终回复之前 运行。
• 触发短语："token usage"、"用量"、"费用"、"cost"、"billing"、"多少 tokens"、"汇报"、"spent"。
• 原因：它为用户提供每轮的用量行，可用于与服务商的实际账单交叉核对。费用为 估算（基于定价快照），并非实际账单。

运行方式

脚本：scripts/usage_report.py — Python 3.9+，仅使用标准库（无需安装），可选 zstandard 包用于 DeepSeek Harness (dsh) 日志。

python3 <此技能目录>/scripts/usage_report.py --latest   # 最近的分段/会话（默认）
python3 <此技能目录>/scripts/usage_report.py --whole    # 整个最新会话
python3 <此技能目录>/scripts/usage_report.py --all      # 按会话列出
python3 <此技能目录>/scripts/usage_report.py --agent zcode|codex|claude|opencode|dsh
python3 <此技能目录>/scripts/usage_report.py --session <子串>   # 锁定某个会话

始终使用此技能目录的 绝对路径。不要先 cd 到其他目录。在 Agent 会话内运行时请显式传递 --agent（自动检测会读取最近修改的文件，可能属于其他并发运行的 Agent）；--session 用于锁定特定会话文件。

将脚本的输出 原样 追加到最终回复中——两行，每行独立（上方是本段会话，下方是整个会话）。如果回复是 Markdown 格式，单个换行符会渲染为空格并合并两行，因此请将它们放在代码块中（或在两行之间留一个空行）：

本段会话：输入 123456 / 缓存命中 98765 / 输出 4321 / 命中率 80.0% / 费用 ¥0.12
整个会话：输入 987654 / 缓存命中 876543 / 输出 43210 / 命中率 88.8% / 费用 ¥0.50

• 退出码 0 → 始终包含这两行，即使数字与之前的报告完全相同（用户希望每次都能看到）。
• Codex 报告 单行（整个会话）——没有分段数据。
• 退出码 1 / "No usage data found" → 静默跳过；不要询问用户。
• 任何其他错误 → 在回复前修复原因（缺少 Python、技能目录移动等）；不要静默跳过。

支持的 Agent

Agent	数据源	--latest 含义
ZCode	~/.zcode/cli/rollout/model-io-*.jsonl	最后一个 分段：自最新请求（其最后一条消息是用户提示）以来的记录（该轮次包含其工具调用）
Codex	~/.codex/sessions/**/rollout-*.jsonl	最后一个 会话（整体）——Codex 回放存储 累积 运行总量，因此只报告最终总量，单行；分段数据不可用
Claude	~/.claude/projects/**/*.jsonl	最后一个 分段：自最新 "type":"user" 记录以来的记录
OpenCode	<data>/opencode/opencode.db (SQLite；Windows 上为 %LOCALAPPDATA%，否则为 $XDG_DATA_HOME 或 ~/.local/share)	最近会话的最后一个 分段（从最新用户消息开始）
DSH	~/.dsh/sessions/**/session.jsonl[.zstd] (zstd 压缩；需要可选 zstandard)	最后一个 轮次（一次用户交换）+ 整个会话

所有四种 Agent 均从有文档记录、本地验证过或已知的格式中解析。DeepSeek Harness (dsh) 和其他 Agent 可以通过编写一个小解析器添加——参见 README.md 了解方法。

准确性与局限性

本报告是根据 本地回放数据 + 标价估算 得出，并非服务商账单。与实际官方用量页面的差异可能来自：

• Codex 总量是累积的：每个 total_token_usage 记录都是当前会话的运行总量，因此脚本使用最后一条记录（绝不求和）。Codex 无法获取单次请求或分段数据。
• 峰谷定价按会话开始时间计算，而服务商按每个请求的时间定价。跨峰谷边界（北京时间 09:00–12:00 / 14:00–18:00）的会话在跨越部分会存在定价偏差。
• 推理输出 Token 在 Codex 中包含在 output 中（按输出费率计费）；ZCode 回放不显示推理字段。
• 本地回放可能未捕获该密钥上的所有请求（中断的流、非交互式调用），因此总量可能低于完整密钥用量。
• 费率是一个快照；网关/聚合密钥或不同的模型 ID 可能按不同价格计费。

费用模型

DeepSeek 官方峰谷定价，生效时间 北京时间 2026-08-17 00:00（2026-08-13 公告）。高峰时段：北京时间 09:00–12:00 和 14:00–18:00；其他时段为非高峰，价格为 半价。2026-08-17 之前的会话使用旧的统一费率。

模型	时段	缓存命中输入	未命中输入	输出	(CNY / 1M tokens)
deepseek-v4-flash	非高峰	0.05	1.5	4.5
deepseek-v4-flash	高峰	0.10	3.0	9.0
deepseek-v4-pro	非高峰	0.15	4.5	13.5
deepseek-v4-pro	高峰	0.30	9.0	27.0

计费周期来自会话开始时间（机器本地时间）。如果官方费率发生变化，请更新 scripts/usage_report.py 中的 PRICES_* 表；权威来源是 platform.deepseek.com。

集成（自动报告每个会话）

将以下规则添加到 Agent 的用户级指令文件（~/.zcode/AGENTS.md、~/.codex/AGENTS.md、CLAUDE.md 或项目 AGENTS.md）：

在每次最终回复之前运行 python3 <技能目录>/scripts/usage_report.py --agent <你的Agent> --latest（始终传递 --agent——自动检测可能读取另一个并发运行 Agent 的数据），并原样追加两条输出行： 本段会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M 整个会话：输入 X / 缓存命中 Y / 输出 Z / 命中率 N% / 费用 ¥M。 仅当脚本输出 "No usage data found" 时跳过。

安全性

• 脚本 只读取 用户主目录下的本地回放 JSON 文件。它从不读取、打印或需要 API 密钥、.env 文件或凭据。
• 回放文件可能包含提示文本——切勿回显其内容。仅打印脚本输出的汇总数字。