GETTING STARTED

从日志到第一份报告

不需要数据库、账号或前端构建。准备好 Python 后，可以启动仅限本机的实时 Dashboard，也可以生成完全离线的单文件快照。

运行要求

Python 3.9 或更高版本。
macOS、Linux 或 Windows。
至少安装并使用过一个受支持的 CLI，使本地存在日志。

默认行为未传 --source 时仅扫描 Claude 日志。Gemini 与 Codex 需要显式开启。

克隆并运行

git clone https://github.com/LingXi-fur/tokens.git
cd tokens
./run doctor
./run serve --open

这是当前已验证的公共使用入口，不依赖软件包注册表发布版本。

可选：安装本地命令

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
tokens --version

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活。本地安装也会自动解析 Windows 专用的 tzdata 依赖。

首次运行

tokens doctor
tokens day

doctor 只检查日志位置、候选文件数、时区、输出和缓存目录，不解析消息正文。day 默认聚合最近 14 天并将今天作为焦点。

如果没有读到日志，请按实际来源添加参数：

tokens day --source claude
tokens week --source gemini
tokens month --source codex
tokens all --source claude --source gemini --source codex

生成报告

单期静态 HTML

tokens month --html

文件默认写入当前目录下的 out/report-month-<焦点日期>.html；可用 --output DIR 改变位置。

本机实时 Dashboard

tokens serve --open

服务只绑定 127.0.0.1，默认每 5 分钟检查一次本地日志。页面可选择 1、5、15、30 分钟或暂停；日志未变化时不会重复解析或传输，有变化时当前页面会热更新。按 Ctrl+C 停止服务。

离线 Dashboard 快照

tokens dashboard --open

也可写成 tokens --dashboard。输出为 out/dashboard.html，数据、CSS、JavaScript 与 SVG 渲染逻辑均内嵌，离线可用。它是生成时快照，后来新增的日志不会自动进入该文件。

筛选数据

tokens --since 2026-07-01 --until 2026-07-25
tokens week --source gemini --source codex
tokens dashboard --since 2026-01-01 --source claude
tokens day --no-cache

--since 与 --until 接受 YYYY-MM-DD。Dashboard 会遵守日期和来源筛选；日/周/月切换在生成文件内进行。

本地预览文档

本站是零构建静态文件。可以直接打开 docs/index.html，也可用 Python 启动本地 HTTP 服务：

python3 -m http.server 8000 --directory docs

然后访问 http://localhost:8000/。下一步可查看完整 CLI 参考或Dashboard 功能。