Token用量報告是做什麼的？

讀取Agent的本地rollout檔案，並印出最近一段對話以及整個會話的用量統計（兩行）：

本段會話：輸入 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+，僅需標準函式庫（無需安裝），但DeepSeek Harness（DSH）日誌需要選用的zstandard套件。

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格式，單一換行會被渲染成空格而導致兩行合併，因此請將它們放在程式碼區塊中（或在兩行之間留一個空行）：

```text
本段會話：輸入 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的rollout儲存的是累積運行總數，因此只回報最終總數，一行；無區段資料可用
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`套件）	最後一次往返（一次使用者交換）+ 整個會話

以上四種都是從有文件說明、本地驗證過或廣為人知的格式進行解析。DeepSeek Harness（dsh）及其他Agent可以透過小型解析器擴充——請參閱README.md了解方式。

準確性與限制

本報告是來自本地rollout資料加上牌價的預估值，並非供應商的帳單。與官方用量頁面之間的差異可能來自：

Codex總數是累積的：每筆total_token_usage紀錄都是持續累積的會話總數，因此腳本只取最後一筆（絕不加總）。Codex無法提供每次請求或每個區段的數值。
尖峰/離峰是根據會話開始時間套用的，但供應商是根據每次請求的時間來計價。一個跨越尖峰時段（北京時間09:00–12:00 / 14:00–18:00）的會話，跨越部分的價格會估算錯誤。
Codex的推理輸出Token已包含在output中（按輸出費率計價）；ZCode的rollout沒有揭露推理欄位。
本地rollout可能無法擷取該金鑰上的所有請求（中斷的串流、非互動式呼叫），因此總數可能低於完整金鑰用量。
費率為快照值；閘道/聚合金鑰或不同的模型ID可能以不同的價格計費。

成本模型

DeepSeek官方尖峰/離峰定價，自2026年8月17日北京時間00:00起生效（2026年8月13日公告）。尖峰時段：北京時間09:00–12:00與14:00–18:00；其他時間為離峰，價格為半價。2026年8月17日之前的會話使用舊的統一費率。

模型	時段	快取命中-輸入	未命中-輸入	輸出
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」時才跳過。

安全性

此腳本只會讀取使用者家目錄下的本地rollout JSON檔案。它絕不會讀取、印出或要求API金鑰、.env檔案或憑證。
Rollout檔案可能包含提示文字——切勿將其內容原樣輸出。只印出腳本彙總後的數字。

Token用量報告