GETTING STARTED

从日志到第一份报告

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

运行要求

默认行为未传 --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
tokens doctor
tokens demo --open
tokens serve --open

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

首次运行

./run doctor
./run day

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

先体验合成 Demo

还没安装?可先打开在线合成 Demo。它在浏览器中运行真实 Dashboard,只使用生成记录,无需账号、本地日志或上传。

克隆后可在本机生成同样的私密体验:

./run demo --open

命令通过真实 Dashboard 管线,仅使用生成的示例数据写入 out/dashboard-demo.html,不会读取本机 Claude Code、Gemini CLI 或 Codex 日志。

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

./run day --source claude
./run week --source gemini
./run month --source codex
./run all --source claude --source gemini --source codex

生成报告

单期静态 HTML

./run month --html

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

本机实时 Dashboard

./run serve --open

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

离线 Dashboard 快照

./run dashboard --open

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

筛选数据

./run --since 2026-07-01 --until 2026-07-25
./run week --source gemini --source codex
./run dashboard --since 2026-01-01 --source claude
./run 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 功能。