用途：分析本地 ~/.claude/projects/ 下 Claude Code 会话的 token 消耗并估算成本，回答用户已用多少 token、费用估算、API 定价与订阅方案价值对比、跨项目或时间段的使用模式等问题。
数据来源：会话以 JSONL 文件存储，主会话为 <project-dir>/.jsonl，子智能体为 <project-dir>//subagents/*.jsonl。每行一个 JSON 对象，token 用量位于 message.usage，含 input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens；模型位于 message.model（含 opus、sonnet、haiku），时间戳位于 timestamp（ISO 8601）。
定价：所有模型 token 成本与订阅方案数据存于 scripts/pricing.json，为脚本唯一数据源，含更新日期字段。缓存写入分 5 分钟（基础输入 1.25 倍）与 1 小时（2 倍）两档，缓存读取为基础输入 0.1 倍；脚本按 5 分钟档估算，因 Claude Code 使用临时缓存。更新定价可运行 python3 <skill-path>/scripts/usage_report.py --update-pricing 显示当前值并更新核对日期，再用网络工具抓取 https://docs.anthropic.com/en/docs/about-claude/pricing 比对并编辑 pricing.json。
使用方式：先确定范围（日期区间、项目过滤），未指定时询问用户，仅给日期则默认全部项目。然后运行脚本：python3 <skill-path>/scripts/usage_report.py [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--project PROJECT_NAME] [--output PATH] [--update-pricing]。脚本仅用 Python 标准库，无需安装依赖，输出到 stdout 并保存至输出文件（默认 ~/claude-code-usage-report.txt）。报告含全局摘要、方案 ROI 对比、模型明细、按类型成本拆分、每日用量、按项目拆分。最后补充关键洞察：成本前五项目、峰值日、ROI 与显著模式。
限制与边界：缺少时间戳的消息在筛选报告中跳过；未知模型归入 other 并按 Sonnet 定价回退；零 token 项目跳过；Claude Code 可能清理旧会话文件，旧时段数据可能不完整；期间切换方案需询问切换日期并分段计算。应使用内置脚本而非从零生成，避免硬编码价格或逐文件调用。