ZCF 中的 ccusage 用量分析：Claude Code / Codex 的 Token 与成本监控实战指南

ccusage 是 ZCF（Zero-Config Code Flow for Claude Code & Codex）内置集成的用量分析工具，用于从本地 JSONL 日志文件中快速解析 Claude Code / Codex CLI 的 Token 消耗与费用数据，为 AI 辅助开发的成本优化提供数据支撑。本文将从 ZCF 的命令接入、分析维度、输出格式到源码实现，完整讲解如何通过 zcf ccu 掌握模型用量、会话趋势与缓存开销。

什么是 ccusage

ccusage 是一款针对 Claude Code 与 Codex CLI 的本地用量分析工具，它读取本机日志文件中累积的会话记录，在不依赖云端 API 统计的情况下，以极高的解析速度输出 Token 用量与费用分析报告。ZCF 项目将其作为"Other Tools"模块中的一等公民接入：既可以通过独立子命令 zcf ccu 直接调用，也可以在主菜单中通过 U. Usage Analysis 选项进入交互式分析流程，帮助开发者理解并优化 AI 辅助开发的成本结构。

从 ZCF 的仓库结构看，ccusage 相关的功能由三部分组成：

• 命令入口：src/commands/ccu.ts 负责构造并执行底层命令；
• 交互入口：src/utils/tools.ts 提供主菜单中的模式选择与自定义参数解析；
• CLI 注册：src/cli-setup.ts 将 ccu 命令挂载到 zcf 命令行工具。

核心能力

ccusage 的能力围绕"多维统计"展开，ZCF 的 功能文档 与 CLI 文档 共同归纳出以下要点：

• 📊 多维报告：支持日、周、月维度的用量报告，覆盖 Token 消耗与费用统计；
• 💰 成本分析：精确计算 Token 消耗量及对应的美元成本；
• 🤖 模型拆分：按模型（如 Claude Opus / Sonnet / Haiku）分别统计用量占比；
• 📈 趋势分析：可视化展示用量随时间的变化趋势；
• 📅 灵活周期：daily、weekly、monthly 三种统计周期；
• 📱 实时监控：实时面板展示进行中会话的进度、Token 消耗速率与成本预测；
• 💬 会话分析：按对话会话分组查看用量；
• 🔄 缓存统计：分别追踪 cache creation（缓存写入）与 cache read（缓存读取）两类 Token；
• 🔌 易集成：支持 JSON / CSV 导出，方便接入脚本与外部分析工具；
• 🚀 状态栏支持：与 CCometixLine 集成，可在状态栏中实时展示用量摘要。

统计数据的来源

ccusage 直接读取 Claude Code 官方使用数据库 usage.db，其中包含：

• 调用次数（Call Count）：AI 请求的总次数；
• 使用时长（Usage Duration）：AI 使用的累计时长；
• 时间范围（Time Range)：指定统计周期内的数据；
• Token 明细（Token Details)：输入、输出与缓存 Token 的计数。

这意味着统计口径与 Claude Code 自身的记录完全一致，数据准确性取决于 Claude Code 的记录情况。

使用方式一：通过 CLI 子命令 zcf ccu

ZCF 将 ccusage 封装为 zcf ccu（Claude Code Usage）子命令。命令定义于 src/cli-setup.ts，支持 --lang/-l 与 --all-lang/-g 语言选项，并通过 .allowUnknownOptions() 将剩余参数透传给 ccusage 本体：

# 基础用法（显示默认统计）
npx zcf ccu

# 指定统计周期
npx zcf ccu --period daily
npx zcf ccu --period weekly
npx zcf ccu --period monthly

# JSON 格式输出（供脚本处理）
npx zcf ccu --json

# CSV 格式输出（供 Excel 分析）
npx zcf ccu --csv

参数说明

参数	说明	可选值	默认值
--period	统计周期	daily、weekly、monthly	daily
--json	JSON 格式输出	无	否
--csv	CSV 格式输出	无	否

底层执行原理

zcf ccu 的核心执行逻辑位于 src/commands/ccu.ts，它并不在本地维护任何统计逻辑，而是通过 tinyexec 以子进程方式调用 npx ccusage@latest，将参数原样透传：

const command = 'npx'
const commandArgs = ['ccusage@latest', ...(args || [])]

console.log(ansis.cyan(i18n.t('tools:runningCcusage')))
console.log(ansis.gray(`$ npx ccusage@latest ${(args || []).join(' ')}`))

await x(command, commandArgs, {
  nodeOptions: {
    stdio: 'inherit', // 继承标准输入输出，实现实时输出
  },
})

几个值得注意的实现细节：

• 实时输出：stdio: 'inherit' 让 ccusage 的输出直接流入终端，保证监控面板等动态界面能够实时渲染；
• 失败兜底：捕获异常后提示检查网络连接（tools:checkNetworkConnection），因为在没有本地安装 ccusage 时需要联网通过 npx 拉取；
• 可调试：设置 DEBUG 环境变量时，会打印完整错误堆栈（tools:errorDetails）；
• 测试保护：当 NODE_ENV === 'test' 时不执行 process.exit(1)，以保证单元测试中模拟失败场景的正常退出。

对应的测试见 tests/commands/ccu.test.ts 与 tests/commands/ccu.edge.test.ts，覆盖了默认执行、参数透传（如 --json --output report.json）、超长参数、空参数与特殊字符等多种边界情况。

使用方式二：通过主菜单交互式分析

运行 npx zcf 进入主菜单后，在 Other Tools 区域选择 U. Usage Analysis 即可。这一交互流程由 src/utils/tools.ts 的 runCcusageFeature() 实现，菜单项定义见 src/commands/menu.ts。

与 CLI 直传参数不同，菜单模式提供了一组面向常用场景的快捷分析模式（中英文文案见 src/i18n/locales/zh-CN/tools.json 与 src/i18n/locales/en/tools.json）：

菜单选项	内部值	说明
日统计（Daily usage）	daily	按天汇总用量
月统计（Monthly usage）	monthly	按月汇总用量
会话统计（Session statistics）	session	按会话分析
分析代码块（Analyze code blocks）	blocks	分析代码块粒度数据
自定义模式（Custom parameters）	custom	输入任意 ccusage 参数

其中自定义模式对输入做了智能解析：通过 "(<a href="https://link.gitcode.com/i/3abaf8e4c0c52a6b0433d3cdbb6c08d5" target="_blank">^"]*)"|'([^']*)'|(\S+) 正则拆分参数，既支持以空格分隔的多个参数，也能正确保留被引号包裹的含空格字符串（例如 --period "this week"），解析后再交由 executeCcusage() 透传执行。测试见 [tests/unit/commands/ccu.edge.test.ts。

统计周期详解

ccusage 按周期粒度输出结构化的用量表格，便于纵向对比趋势。

日统计（daily）

适合日常监控，逐日展示请求数与耗时：

📊 Claude Code Usage Statistics
Period: Daily

Date       | Requests | Duration
-----------|----------|----------
2025-01-15 | 45       | 2h 30m
2025-01-14 | 38       | 2h 15m

周统计（weekly）

适合周期性分析，观察一周内的工作强度与成本波动：

📊 Claude Code Usage Statistics
Period: Weekly

Week       | Requests | Duration
-----------|----------|----------
Week 3     | 315      | 18h 20m
Week 2     | 298      | 17h 45m

月统计（monthly）

适合长期趋势分析与成本预算，如按月度做费用估算：

📊 Claude Code Usage Statistics
Period: Monthly

Month      | Requests | Duration
-----------|----------|----------
2025-01    | 1250     | 72h 15m
2024-12    | 1180     | 68h 30m

输出格式

默认格式（表格）

适合终端直接查看，表格布局会根据终端宽度自动适配（支持紧凑模式）。

JSON 格式

适合脚本处理与自动化流水线，例如每周生成结构化报告：

npx zcf ccu --json --period weekly

输出示例：

{
  "period": "weekly",
  "data": [
    {
      "date": "2025-01-15",
      "requests": 45,
      "duration": "2h 30m"
    }
  ],
  "total": {
    "requests": 315,
    "duration": "18h 20m"
  }
}

CSV 格式

适合导入 Excel 或其他分析工具做二次处理：

npx zcf ccu --csv --period monthly > usage.csv

输出示例：

Date,Requests,Duration
2025-01-15,45,2h 30m
2025-01-14,38,2h 15m

典型应用场景

1. 日常用量监控

快速查看今天的用量与耗时：

npx zcf ccu --period daily

2. 团队用量统计

定期汇总成员用量，生成周报并归档：

npx zcf ccu --period weekly --json > weekly-usage.json

3. 成本分析

按月导出用量，再结合 API 定价在 Excel 中计算成本：

npx zcf ccu --period monthly --csv > monthly-usage.csv

4. 自动化定时采集

配合 cron 每天定时收集数据，实现无人值守的成本监控：

# 添加到 crontab（每天执行）
0 23 * * * cd /path/to/project && npx zcf ccu --json --period daily >> usage.log

与 CCometixLine 状态栏集成

除了命令行统计，CCometixLine 状态栏也能展示用量摘要，实现"打开编辑器即可见"的实时监控：

1. 安装 CCometixLine：运行 npx zcf 并选择对应选项；
2. 在状态栏中查看实时用量；
3. 点击状态栏查看详细统计。

关于状态栏的完整配置，可参考 CCometixLine 状态栏文档。

常见问题

Q：没有统计数据？

A：

1. 确认 Claude Code 已安装并正常使用；
2. 检查 usage.db 文件是否存在（通常位于 Claude Code 配置目录下）；
3. 确认存在实际使用记录。

Q：统计数据不准确？

A：ccusage 直接读取 Claude Code 官方使用数据库，数据准确性取决于 Claude Code 自身的记录，属于读取方而非计算方。

Q：如何清空统计数据？

A：统计数据由 Claude Code 管理，不建议手动删除。若确需重置，只能删除 Claude Code 的 usage.db 文件，但这会丢失全部历史记录。

相关文档

• ccusage 功能概览 — 了解该功能的定位与核心能力；
• ccu 命令详解 — 命令参数、输出格式与使用场景的完整说明；
• CCometixLine 状态栏 — 在状态栏中实时查看用量；
• 仓库源码：命令实现 src/commands/ccu.ts、交互实现 src/utils/tools.ts、测试用例 tests/commands/ccu.test.ts。