1实现原理 · 为什么它能做到

数据源是本地 ccusage：analyze_claude_usage.py 不自己解析日志，而是 subprocess 调 `ccusage claude daily/blocks --json` 取 JSON 再提炼——技能的价值在‘读 ccusage 数字并用人话解释’。

daymade-claude-code/claude-usage-analyst/scripts/analyze_claude_usage.py

proc = subprocess.run( ["ccusage", "claude", *args, "--json"],

run_ccusage 先 shutil.which('ccusage')，缺失即报错并提示 npm install -g ccusage@latest。

窗口语义：默认 --since/--until 为所选时区（默认 Asia/Shanghai）的今天；历史对比需显式给 --since，否则 rank/median 只描述单日。

daymade-claude-code/claude-usage-analyst/SKILL.md

Default `--since/--until` is today in the selected timezone.

summarize() 里 daily[-1]/按 date==until 取 target 日，before 列表用于‘目标日前历史中位数’对比。

模型对比支持别名：--model-a/--model-b 在目标日 modelBreakdowns 里做子串匹配（默认 fable vs opus-4-8），输出 token 比与成本比，纠正‘token 多≠贵’。

daymade-claude-code/claude-usage-analyst/SKILL.md

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

find_model 用 needle.lower() in name.lower()；SKILL 明言‘token 量相近但成本更高’要指出单价差异。

5 小时 block 由 ccusage blocks 命令提供（近似配额窗口分组），脚本跳过 isGap、只留目标日 block，输出起止/模型数/entries/token/成本/cache 占比。

daymade-claude-code/claude-usage-analyst/SKILL.md

4. 5-hour block table when quota exhaustion is discussed.

explanation-guide.md 强调 5-hour block 是 ccusage 分组近似，不是订阅配额契约。

解释层与证据层分离：SKILL 规定数字结论必须基于 ccusage/analyzer 输出，cache 要解释（read 也算用量压力），不知计划规则时用‘quota-like pressure/ccusage estimated’措辞，最终答案按 explanation-guide.md 的结构写。

daymade-claude-code/claude-usage-analyst/SKILL.md

Explain cache clearly: cache read tokens are still usage/quota pressure even though the user did not type those words.

evidence rules 全部指向‘别把本地 token 数外推成官方计费’。

2核心能力

01单日/区间用量统计：total tokens、estimated cost、input/output/cache create/cache read + 成本/用量在窗口内排名

02模型混合明细与双模型对比（token 比 + 成本比，别名子串匹配）

035 小时 block 视角解释配额烧尽（起止/模型/entries/tokens/cost）

04时区正确性：--timezone（zoneinfo 全名）作用于日期窗口与 block 起止时间换算

05输出双形态：人读 Markdown 表 / --json 结构化数据

06面向非技术用户的人话解释（explanation-guide：cache read>80% 意味着 agent 反复读上下文而非用户打字多）

3外部依赖

Kind	Dependency / Endpoint
cli	ccusage（第三方 npm CLI，用量统计）
package	ccusage@latest（npm 全局安装）
cli	python3（zoneinfo 需系统 tz 数据）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: scripts/analyze_claude_usage.py
网络端点: 声明外部网络访问: （仅当 ccusage 缺失时）npm install -g ccusage@latest / npx ccusage@latest —— 从 npm

审计说明： 。技能自身脚本只 subprocess 调本地 ccusage 并解析公开用量指标（token 数/估算成本/模型名/时间块），零网络、零凭证读取、零写文件——不触碰 ~/.claude/settings/.claude.json 等含密钥文件。黄色来自两层：① 依赖第三方 npm 包 ccusage（供应链：安装自 registry.npmjs.org，其包内行为不在本仓可审计，建议固定版本再装）；② 读取对象是本地会话 usage 记录（隐私面，但非凭证面）。若使用中 ccusage 出现向网络上传或读 key 的行为（本仓无法验证），应按橙色处理。

5第二遍独立确认

[ok] 无网络外发（脚本自身） — 无 urllib/requests/socket；唯一外部动作是 npm install ccusage 的安装提示（用户/agent 执行）
[ok] 无凭证读取 — 无 environ/getenv/settings/.claude.json 读取；ccusage 侧读取范围不可在本仓审计（已在 reason 注明）
[ok] 无写文件 — 脚本只 print（stdout），无文件写入
[ok] 数字字段映射准确 — cacheCreationTokens/cacheReadTokens/cost 等字段名与 ccusage JSON 语义一致；model_total 明确含 cache 系 token
[ok] ‘ccusage 不是官方账单’边界 — SKILL evidence rules 与 explanation-guide caveats 双重声明 estimated/quota-like 措辞要求

6结论

证据驱动：所有数字来自 ccusage JSON，脚本不猜不造，且把解释层单独成文

对 cache 与配额语义的诚实处理（cache read 也是压力；未知规则用限定措辞）

覆盖日常最痛问题：为什么配额烧完、哪个模型贵、5 小时 block 视角

零写零凭证的轻量只读工具，带时区与双模型对比

适合： 适合 Claude Code 用户自查‘今天 token/钱花哪了、是不是某模型特别贵、5 小时配额怎么烧完的’；ccusage 已装的用户开箱即用，分析结果可直接用于调模型路由/缓存策略。

不适合： 不适合需要官方账单级精度的财务场景（应查 Anthropic console）；不适合未装 ccusage 且不允许装 npm 包的受限环境；不适合分析 Claude.ai 网页聊天（不在本地日志内）或非 Claude 系的用量。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload claude-usage-analyst.tar.gz

sha256: 009defcb5a1b30df…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.