常见问题

提示“未找到任何日志”怎么办？

先运行 tokens doctor 查看各来源的根目录、候选文件数与可读性。默认只读 Claude；若你只有 Gemini 或 Codex 日志，必须添加来源：

tokens day --source gemini
tokens day --source codex

仍失败时，可检查当前用户主目录是否与日志所在用户一致。

为什么默认没有合并三种来源？

默认只扫描 Claude，以减少意外扫描范围。需要 Gemini 或 Codex 时重复传入 --source；不同来源的 Token 口径并不完全相同。

日志已经变化，统计数字为何没有更新？

如果打开的是 out/dashboard.html，它是生成时快照，浏览器刷新不会重新运行 Python。长期查看请使用：

tokens serve --open

实时模式默认每 5 分钟检查文件修改时间和大小，页面可选择其他预设间隔或暂停。若上游日志时间戳或文件元数据异常，可用 --no-cache 在检测到变化后强制重读；离线报告则重新执行生成命令。

一天的边界按什么时区？

默认使用系统本地时区。可通过 tokens day --timezone Asia/Shanghai 等 IANA 时区名称显式覆盖；无效名称会在读取日志前报错。

“离线可用”是否意味着可以公开分享？

不是。离线快照运行时不发网络请求；实时模式也只访问同机 127.0.0.1，不上传数据。但两种模式的 Dashboard 都可能处理完整 cwd、会话标识、自然语言摘要和大量行为统计。请查看隐私清单。

--open 在 Linux / Windows 上可用吗？

可用。tokens 通过 Python 标准库请求系统默认浏览器打开本地文件。若系统拒绝自动打开，报告仍会生成，并在终端显示文件路径。

报告与文档如何切换主题？

单期 HTML 报告自动跟随系统主题。Dashboard 和本站提供自动 / 亮色 / 暗色三态，并通过 localStorage 记忆。禁用 JavaScript 后，本站仍会按系统主题显示，正文与链接保持可读。

Dashboard 为什么可能比较大？

它是自包含文件：聚合数据、日级细节、会话序列、样式和交互脚本都在同一个 HTML 中。较长时间范围、更多模型和更多项目会增加文件大小。可通过 --since / --until 缩小范围。

Dashboard 会包含完整会话正文吗？

payload 的逐轮回放只保存 token 序列，不保存完整逐轮正文。但会话标题可能来自本地摘要 sidecar，或从会话内容提取出的标题，因此仍可能包含自然语言信息。

文档网站需要构建吗？如何发布？

不需要。docs/ 是普通 HTML、CSS、JavaScript 与 SVG。GitHub Actions 工作流将该目录作为 artifact 发布到 GitHub Pages。本地可运行：

python3 -m http.server 8000 --directory docs

Python 版本和依赖是什么？

项目要求 Python 3.9 或更高版本。核心运行管线使用标准库；Windows 另外安装纯数据包 tzdata，用于一致的 IANA 时区支持。安装构建使用 setuptools；文档站运行时不依赖第三方资源。