令牌用量分析 YuLaiZ/token-usage

token-usage

本地 LLM 使用数据统计 CLI：采集你正在使用的 AI 客户端 token 数据，以每次模型调用为独立记录保存，在无需 SQL 的前提下生成可复用报表，并提供包含用量统计页和配置页的本地 Web 界面。

核心能力

- 内建可视化分析：按小时/星期分布、星期×小时热力矩阵、实时监视模式，以及本地 Web 服务（token-usage serve start，内嵌交互式 HTML 界面：预设与自定义日期区间、七项核心指标、四个内置维度与唯一尾部「其他」行、跟随区间的热力图（小时格/日期×小时/4 小时时段/GitHub 风格日历）、来自 query.subqueries 的自定义视图、保留原始标题的会话排行，以及经与 config set 同一锁内 revision 校验写入链路编辑完整用户配置的配置页——中英双语、五套主题配色与深浅主题；HTTP 面按回环同源使用，唯一写路径是配置保存）。页面与 HTTP 接口的完整说明见Web 界面指南。
- 把你真正想要的报表做出来，无需 SQL。 从 client、model、provider、project、day、month、hour、weekday 组合出具名多维视图，再把内置与自定义视图编排成可复用、按顺序输出的报表组合；设为默认、用 query list 查找、按名称运行，并统一选择表格型报表展示的指标列及其顺序。所有视图的维度分组不区分大小写：仅大小写不同的值合并为一行，行内显示请求数最多的拼写（model 行恒以大写显示）。
- 按消息/API 请求统计，准确处理跨日、多模型、分支与 rewind 的归因。
- 支持 Claude Code/Desktop、OpenCode、Codex、WorkBuddy、ZCode、Zhipu-AutoClaw、MiMo Code + MiMo Desktop（按会话版本标记从共用本地数据库区分两个客户端）与 DeepSeek Harness（DSH）。
- 支持 Claude 系列与 Codex 的 CC-Switch router 归因：通过代理日志回填实际 provider/model。
- 自动发现 CC Switch 的 Claude 多账号会话目录，无需额外配置；支持范围见架构文档。
- Claude / Codex 的每请求估算时长与输出速度：作为表格报表与用量统计页中可选的指标列展示（无估算值的行显示 —；仅 output ≥ 200 token 且时长 1s–1h 的请求参与统计）。
- 可单次执行，也可使用实时后台监控守护进程（token-usage daemon start）；支持 macOS launchd 与 Windows 注册表自启。
- 纯 Go 单二进制 CLI，支持 macOS 和 Windows。

以下截图为 v0.2.5 界面预览，使用演示数据。

token-usage v0.2.5 用量统计页（演示数据）

展开查看用量趋势、热力图与分享截图

内置截图分享可将概要指标、用量趋势和热力图合成一份 PNG，同时保留所选统计区间和版本号。

v0.2.5 用量趋势与热力图（演示数据）

快速开始

1. 安装与更新

官方安装脚本会下载最新稳定 Release，校验其 SHA256 校验和，将二进制安装到 ~/.token-usage/bin，并配置用户 PATH；不需要 sudo 或管理员权限。

复制给 AI Agent（它会安装并验证）：

在本机用与当前平台匹配的官方安装脚本安装 token-usage：

- macOS：curl -fsSL https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.sh | bash
- Windows PowerShell： irm https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.ps1 -OutFile "$env:TEMP\install.ps1" powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1"

新开终端后运行 token-usage --help 查看命令，再运行 token-usage version 验证安装。

macOS：

curl -fsSL https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.sh | bash

Windows PowerShell：

irm https://raw.githubusercontent.com/YuLaiZ/token-usage/main/scripts/install.ps1 -OutFile "$env:TEMP\install.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install.ps1"

新开终端后验证：

token-usage version

官方脚本安装或手动下载并通过 SHA256 校验的官方 Release 资产，都支持原地自更新：

token-usage update # 更新到最新稳定 Release token-usage update --check # 只检查，不修改本地文件 token-usage update --version vX.Y.Z # 更新指定 Release

update 会逐步输出过程——检查更新、当前/目标版本、下载、校验、安装、daemon 与 Web 服务切换；交互终端上下载还会显示单行实时进度（百分比、已传输/总字节数、平均速度），输出被重定向时只保留步骤行。更新前正在运行的 daemon 会自动停止并用新二进制重启；原本已停止的 daemon 保持停止（成功输出会提示 token-usage daemon start）。本地 Web 服务以同样方式保持：更新前 /api/meta 有应答的 Web 服务会被停止以完成替换，随后以原监听地址、用新二进制后台恢复（自动恢复绝不打开浏览器）；原本已停止的 Web 服务不会被启动。缺失、损坏或陈旧的 serve.json 一律按未运行处理且不被改动；Web 服务无法停止时更新会在替换二进制之前中止；任一步失败时更新回滚到旧二进制与更新前的 daemon/Web 服务运行态。

已重签的官方资产、源码构建产物（Version = dev）或通过 go install 安装的 Release tag 产物，需要先执行一次 token-usage update --force，将其替换为官方 Release 资产；之后即可正常更新。软链接副本和非官方 tag 不能通过这种方式转换。

update 成功升级首次跨过携带安装脚本补全自动配置功能的版本时，成功输出会追加一条一次性迁移提示并给出官方安装命令——重跑一次即可自动配置 Tab 补全（zsh 会交互确认）。确切触发条件见 CLI 参考。

手动安装、指定版本、源码构建、更新信任规则、卸载、迁移与平台差异见安装指南。

2. 用 TUI 配置并采集

所有客户端默认关闭。推荐使用引导式配置 TUI：首次运行会自动初始化，可在其中开启实际使用的客户端，也可配置 router、守护进程、日志和查询设置（视图定义、输出列与别名）。

token-usage config

在 TUI 保存配置后，采集已启用客户端的历史数据：

token-usage collect all

collect all 会扫描所有已启用客户端；配置了 router 时也会完成归因回填。它不使用 collection_log 的日期去重，消息按 (client, id) UPSERT，可安全重复执行。要持续更新数据，启动守护进程：

token-usage daemon start

3. 查询并创建专属报表

token-usage query # 今天的默认报表；未配置时按 client 汇总 token-usage query model # 按模型汇总 token-usage query day # 按天用量 token-usage query month # 按月用量 token-usage query hour # 按小时用量 token-usage query weekday # 按星期用量 token-usage query 20260701-20260721

日期使用位置参数：YYYYMMDD 表示单日，YYYYMM 表示单月，YYYY 表示单年（仅单独使用），区间端点为日或月（如 202607-202608）。任何形态展开上限 366 天（一个闰年），更长范围请拆分多次执行。

真正的价值在于围绕你反复关心的问题构建报表：在 TUI 中进入 查询（主菜单按 v），创建具名多维视图，组合成按顺序输出的报表组合，选择其默认项，并挑选所有表格共用的指标列。也可在 ~/.token-usage/config.toml 中定义可迁移的视图：

[query]
default = "daily_stack"

[query.subqueries]
model_provider_client = "model,provider,client"

[query.groups]
daily_stack = "client,model,provider,model_provider_client"

一份全局、有序的指标列布局，所有 query 表格共用（可选；缺省保持现有七列）。
[query.output]
columns = ["requests", "input", "output", "total", "cache_hit"]

token-usage query model_provider_client
token-usage query daily_stack 20260701-20260721
token-usage query list

query list 仅读取配置（配置文件必须存在——全新机器请先执行 config init）、不打开 usage 数据库，适合安全查看内置和已配置视图。可选的 [query.output] 布局决定每张 query 表格显示哪些指标列及其顺序（cache_create 可选但默认隐藏；query summary 保持完整摘要）。校验规则和完整命令契约见 CLI 参考。

命令速查

| 命令 | 用途 |
| config / config init | 打开配置 TUI / 创建初始配置和数据库。 |
| config set <key> <value> | 修改一项配置。 |
| collect [date] | 增量采集今天或指定日期范围。 |
| collect all | 全量采集历史数据，不使用 collection_log 日期去重；可安全重复执行。 |
| collect retry | 重试未解决的采集失败。 |
| query [date] | 运行默认报表。 |
| query client/model/provider/project/day/month/hour/weekday/heatmap/session/summary [date] | 运行内置报表。 |
| query <name> [date] | 运行已配置视图或报表组合。 |
| query list | 不打开 usage 数据库，列出视图。 |
| errors [日期] | 查看某日期或区间的采集失败（--format json 输出机器可读结果）。 |
| watch [日期] | 以固定间隔刷新 query 输出（--once 单帧；视图选择与 query 一致——--by 接受内置视图或已配置视图名，缺省跟随 query.default）。 |
| doctor | 运行只读健康检查。 |
| daemon start/status/stop/restart | 管理采集守护进程：后台启动、查看状态、停止、重启。 |
| serve start/status/stop/restart | 后台管理本地 Web 服务——用量数据只读，唯一写路径是配置保存（serve start --open 自动开浏览器；裸 serve 只显示帮助）。 |
| version / --version | 查看多行详细 / 单行简要的版本信息。 |
| completion <shell> | 输出 Bash、Zsh、Fish 或 PowerShell 的补全脚本。 |
| update | 对官方 Release 资产原地自更新；符合条件的已重签、源码构建或通过 go install 安装的二进制，可先用一次 update --force 转换。 |

从 v0.1.8 迁移

v0.1.9 是一次有意的破坏性 CLI 收敛（详见 CLI 参考）。chart、compare、export、forecast、report、top 六个命令已删除。终端查询继续用 query / watch；用量统计页中，最重会话排行由会话表延续，SVG 图表接口、用量预测与两期对比已随 v0.2.0 重做移除、无替代入口（见Web 界面指南）。机器可读的 CLI export 合同与离线 HTML 报告包已有意移除，没有完整直接替代。顶层 start/status/stop/restart 已移入 daemon 命令组，裸 serve 不再前台启动服务。

| v0.1.8 | 现在 |
| token-usage start / status / stop / restart | token-usage daemon start / daemon status / daemon stop / daemon restart |
| token-usage serve（前台） | token-usage serve start（后台） |
| token-usage top | token-usage serve start——用量统计页的会话排行（前 20 条、原始标题） |
| token-usage chart | token-usage serve start——用量统计页的趋势图与热力图覆盖可视化分析；逐图 SVG 导出已移除 |
| token-usage forecast / compare | 已随 v0.2.0 用量统计页重做移除——预测面板与两期对比面板无替代入口 |
| token-usage export / report | 终端查询继续用 query / watch。用量统计页的早期 CSV 导出已随 v0.2.0 重做移除；机器可读 CLI export 与离线报告包已移除，无完整直接替代 |

运行 token-usage --help 查看命令概览；标志、退出码、副作用边界、配置行为与两个服务的生命周期见 CLI 参考。

Shell 补全

completion 将 Shell 补全脚本写到标准输出。例如，当前 Zsh 会话可直接加载：

source <(token-usage completion zsh)

各 Shell 的前置条件：zsh 需先初始化补全系统（compinit）——未初始化时加载脚本会报 compdef: command not found，请先在 rc 文件中加入 autoload -U compinit; compinit 再加载（部分配置有意不启用 compinit，改动前先查看 rc 文件）。bash 依赖 bash-completion 包（macOS 系统 bash 3.2 不满足，需经 Homebrew 安装 bash 4+ 与 bash-completion@2）。fish 与 PowerShell 无前置条件。

zsh 上 compinit 可能报告不安全目录（insecure directories，即 group/其他用户可写的补全目录——老 Homebrew 安装最常见）并询问是否继续。三种处理方式：在提示出现时输入 y（每次新开 shell 会再次提示）、用 chmod go-w <目录> 一次性修复各目录（Homebrew 官方同样建议的做法）、或改用 compinit -u 永久跳过安全检查。

官方安装脚本可自动完成以上配置（zsh 会交互确认），见安装指南。持久化安装请运行 token-usage completion <bash|zsh|fish|powershell> --help。

文档导航

| 文档 | 内容 |
| 安装指南 | 全部安装方式、自更新、卸载与迁移、PATH 与平台差异。 |
| CLI 参考 | 命令树、参数、标志、示例、配置和守护进程行为。 |
| Web 界面指南 | 用量统计页与配置页的行为、隐私遮蔽与截图分享、HTTP 接口。 |
| 架构说明 | 数据流、存储、进程控制、更新设计与扩展点。 |
| 贡献指南 | 开发环境、测试、文档、提交与 PR 规范。 |

平台支持

| 平台 | 构建 | 守护进程 | 自启 |
| macOS | 支持 | 支持 | launchd |
| Windows | 支持 | 支持 | 注册表 Run key |

开发

make build
go test ./...
go test -race ./...

使用 make build-all 构建全部支持的 macOS 与 Windows 目标。完整开发流程见贡献指南。

许可证

本项目以 MIT License 发布。