ARCHITECTURE

标准包、透明管线、纯 stdlib

运行时代码位于 src/tokens_cli。命令层协调配置与诊断，读取器统一来源记录，聚合层保持语义稳定，报告层生成本地输出。

概览

本地日志
JSON / JSONL

readers.py
统一 record

aggregate.py
筛选与聚合

report_*.py
三类输出

./out
本地报告

cli.py 解析参数并在读取日志前应用 --output 与 --timezone。doctor.py 只检查来源元数据、候选文件数和目录可写性，不调用记录解析器。

模块职责

模块	职责
`config.py`	日志根目录、平台用户缓存目录、当前工作目录下的输出、系统本地时区与运行时覆盖。
`readers.py`	安全扫描与解析 Claude / Gemini / Codex 日志，标准化记录，并以原子私有写入维护派生缓存。
`aggregate.py`	日期过滤、日 / 周 / 月分组、模型与来源汇总。
`dashboard_payload.py`	构建 Dashboard 所需的项目、会话、复用、来源和成就聚合；在序列化前完成假名化。
`dashboard_wire.py`	压缩自包含报告中的重复字符串；不提供加密或隐私保护。
`report_term.py` / `report_html.py`	终端表格与单期静态 HTML。
`report_dashboard.py`	从包内资源加载模板、CSS 与 JavaScript，注入紧凑 payload；同一渲染入口同时用于离线快照和实时页面。
`live_dashboard.py`	仅绑定回环地址的标准库 HTTP 服务；负责文件签名、ETag 快照、刷新锁和泛化错误边界。
`opener.py`	通过标准库和系统默认浏览器跨平台打开本地文件或回环 URL。

数据流

1. 读取

readers.read_all() 按来源扫描日志，拒绝符号链接、非普通文件、过大文件和过长 JSONL 行。缓存根据文件修改时间和大小复用解析结果；--no-cache 强制重读。

2. 窗口与筛选

CLI 为 day、week、month 计算默认窗口，验证显式日期与正整数参数，并使用系统本地或 --timezone 指定的 IANA 时区。

3. 聚合

普通报告按选定粒度聚合。Dashboard 同时生成日 / 周 / 月、小时、项目、会话与 Token 组成。启用 --anonymize 时，项目与会话 identity 会在写入任何 Top、flow 或 replay bucket 前转换为报告级别名，并跳过自然语言标题读取。

4. 渲染与实时刷新

终端报告直接打印；静态 HTML 由 Python 预渲染；tokens dashboard 将数据与包内静态资源组装成单个离线文件。tokens serve 复用同一页面渲染入口，只绑定 127.0.0.1：先比较安全文件签名，变化后复用逐文件解析缓存，并仅在报告 snapshot ID 改变时发布新的 ETag payload。

输出与缓存分离

可分享报告

默认写入当前工作目录的 ./out，也可用 --output 指定。报告仍可能敏感，不能因为位置可控就假定适合公开。

派生缓存

写入平台用户缓存目录：macOS 使用 ~/Library/Caches，Linux 遵循 XDG，Windows 使用 LOCALAPPDATA。缓存不再混入报告目录。

设计约束

依赖边界：核心运行逻辑使用 Python 标准库；Windows 安装附带纯数据包 tzdata，用于 IANA 时区支持。
本地优先：日志读取、缓存和报告均在本机完成；不访问外部服务。实时模式只使用同机 127.0.0.1，不绑定局域网。
标准包布局：setuptools 从 src/ 发现 tokens_cli，Dashboard 静态文件作为 package data 分发。
跨平台：目标为 Python 3.9+ 的 macOS、Linux 与 Windows。
隐私边界：本地优先不等于可公开；假名化不等于保证匿名。

扩展入口

新增日志源通常需要：在 config.py 增加默认路径，在 readers.py 输出统一 record，在 CLI 注册来源，并覆盖解析、缓存、聚合、诊断和隐私测试。新增报告视图应消费聚合输出，而不是重新解析原始日志。

保持边界展示层若需要 cwd、会话标识或自然语言摘要，应明确记录隐私影响，而不是假设“聚合”天然等于匿名。