用途：从 Codex 的 state_*.sqlite 状态数据库生成本机历史 Token 消耗报告，面向普通用户阅读，默认采用 html-doc 风格，同时输出 .html 和 .md。报告含总览、月度仪表盘、月份选择器、SVG 曲线图、来源与模型环形饼图、峰值日期柱形图、可搜索筛选排序的明细表格，以及可复制的 SQLite 查询。数字统一使用万、亿等中文单位。
主要能力：统计 threads.tokens_used，按会话汇总，展示累计 Token、会话数、平均值、最大会话、未归档占比、子 Agent 占比；支持月度趋势、来源拆分、模型/提供方拆分和高消耗会话。来源字段转为可读名称，如 vscode 显示为“Codex 桌面端”、exec 显示为“自动执行”、cli 显示为“命令行”。
使用方式：确认数据库路径，优先用 --db；未传入时依次尝试 $CODEX_USAGE_DB、$CODEX_SQLITE_HOME/state_5.sqlite、config.toml 的 sqlite_home、$CODEX_HOME/state_5.sqlite、~/.codex/state_5.sqlite。最短命令：
python3 /path/to/codex-usage/scripts/generate_codex_usage_report.py
--db "$HOME/.codex/state_5.sqlite"
--out ./codex-usage-report.html
常用参数包括 --json-out、--snapshot、--no-snapshot、--since、--until、--top、--title、--renderer html-doc|standalone|md|data、--html-doc-dir、--md-out。自定义分析为两步：先用 --renderer data --json-out 生成数据 JSON，再让 Agent 写只含 analyze(report) 逻辑的脚本，最后用 render_token_analysis.py 渲染成 HTML；analyze 可返回 title、summary、tags、metrics、findings、sections、tables、actions、blocks。
适用场景：用户要求分析本机 Codex 历史 Token 用量、月度趋势、来源与模型分布或高消耗会话时使用。
限制：仅做本地累计统计，不能替代账户用量接口，不用于查询账户剩余额度、订阅账单、实时速率限制或重置时间。必需字段为 threads.created_at 和 threads.tokens_used；若缺少 model、model_provider、source、title、archived、rollout_path、cwd 等字段，部分维度无法展示。默认在 HTML 旁创建 SQLite 快照以保持数字一致。其他未在资料中说明的功能、收费与平台信息暂未提供。