claude-usage-analyst

Claude Usage Analyst 是一个用于从本地 ccusage 数据生成基于证据的用量解释的技能。它的核心目标是把观测到的数字与主观解释分开，并用人类可理解的方式说明配额消耗情况。

用途 该技能适用于分析 Claude Code 和 Claude Desktop Code 的 token 用量、成本、配额消耗、模型组合、缓存读写以及 5 小时区块消耗。它基于 ccusage 提供的证据，帮助用户理解本地用量日志中反映出的消耗模式。

主要能力

• 验证 ccusage 是否可用，并在缺失时提供安装或更新方式。
• 运行内置分析脚本，针对指定时间窗口生成用量分析。
• 支持指定时区，默认 --since/--until 为所选时区的当天。
• 支持通过模型别名进行特定模型对比。
• 输出结构化的分析结果，包括结论、证据表、模型对比表、5 小时区块表、消耗原因解释以及置信度与注意事项。

使用方式 首先验证 ccusage 是否可用：

ccusage --version

如果缺失，可使用 npm install -g ccusage@latest 安装或更新，或使用 npx ccusage@latest 运行。

然后运行内置分析器，针对请求的时间窗口：

python3 /path/to/claude-usage-analyst/scripts/analyze_claude_usage.py
--since YYYY-MM-DD --until YYYY-MM-DD --timezone Asia/Shanghai

默认 --since/--until 为所选时区的当天。若需历史对比，可将 --since 设为更早日期，例如当月第一天；否则排名/中位数字段仅描述单个目标日。

如果用户询问特定模型对比，可传入别名：

python3 scripts/analyze_claude_usage.py --model-a fable --model-b opus-4-8

撰写最终答案时，可阅读 references/explanation-guide.md。

证据规则

• 数值声明应基于 ccusage 输出或内置分析器输出。
• 需说明范围：ccusage claude 测量的是本地 Claude Code 用量日志，包括 Claude Desktop 的 Claude Code 会话（当这些本地日志存在时）。它不是完整的普通 Claude.ai 聊天账单。
• 报告日期时需带时区。
• 清晰解释缓存：缓存读取 token 仍属于用量/配额压力，即使用户没有输入这些词。
• 除非用户提供套餐详情，否则不要从本地 token 数量推断 Anthropic 套餐配额规则。当确切套餐核算未知时，应说“类似配额的压力”或“ccusage 估算成本/token 消耗”。
• 比较模型时，需同时比较 token 量和估算成本。一个模型可能 token 量相近但成本更高。

输出结构 除非用户另有要求，使用以下结构：

1. 用通俗语言给出简短结论。
2. 证据表：总 token、成本、输入、输出、缓存创建、缓存读取。
3. 模型对比表。
4. 讨论配额耗尽时的 5 小时区块表。
5. 解释消耗发生的原因。
6. 置信度与注意事项。

保持答案对非技术用户可读。避免使用未解释的术语，如“缓存读取”应附一句通俗翻译。

适用场景 适合需要审计或解释 Claude 本地用量记录的用户，例如想了解 token 消耗来源、成本构成、模型使用分布或 5 小时区块配额压力的情况。

限制 该技能基于本地 ccusage 数据，不覆盖普通 Claude.ai 聊天账单。无法从本地 token 数量推断 Anthropic 套餐配额规则，除非用户提供套餐详情。部分功能依赖 ccusage 的可用性及本地日志的存在。