ZCF 使用分析命令 zcf ccu 完全指南：基于 ccusage 的 Claude Code 用量与成本监控

本文面向使用 Zero-Config Code Flow（ZCF）管理 Claude Code 的开发者，系统讲解 zcf ccu（Claude Code Usage）使用分析命令的完整用法：从命令格式、统计周期与输出格式，到 JSON/CSV 导出、CCometixLine 状态栏集成，并结合当前仓库源码说明其底层执行机制与数据来源。读完本文，你将掌握如何在日常开发、团队统计、成本分析与自动化监控中熟练使用该命令。

命令概览与两种入口

zcf ccu 是 ZCF 提供的 Claude Code 使用分析命令，其底层驱动的是 ccusage 工具（见 功能概览），用于查看和分析 Claude Code 的使用统计信息，帮助开发者了解 AI 助手的使用情况和成本。

直接调用

# 基本使用（显示默认统计）
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

通过主菜单访问

npx zcf
# 然后选择 U. 使用分析

从源码看，主菜单的 U. 选项位于“其他工具”分区（menu.ts），对应选项描述为“Claude Code 用量分析”（zh-CN/menu.json）。选择后会进入一个交互式模式选择界面（见下文“交互式模式选择”小节）。

参数说明

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

参数透传机制（源码级说明）

zcf ccu 的一大特点是参数透传：它本身不解析这些参数，而是将 ccu 之后的所有参数原样转发给 ccusage。其命令注册位于 cli-setup.ts：

cli
  .command('ccu [...args]', 'Run Claude Code usage analysis tool')
  .option('--lang, -l <lang>', 'ZCF display language (zh-CN, en)')
  .option('--all-lang, -g <lang>', 'Set all language parameters to this value')
  .allowUnknownOptions()
  .action(await withLanguageResolution(async (args) => {
    await executeCcusage(args)
  }))

关键点：

• [...args] 表示捕获 ccu 之后的所有命令行参数；
• .allowUnknownOptions() 允许传入 ccusage 定义而 ZCF 未声明的任意选项（如 --output、--path 等），因此除了本文表格列出的三个常用参数外，ccusage 本身的全部能力都可以通过 zcf ccu 直接使用；
• 真正执行的是 executeCcusage 函数。

executeCcusage 的实现位于 src/commands/ccu.ts，核心逻辑是通过 tinyexec 的 x() 执行 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(' ')}`))

// Execute ccusage with inherited stdio for real-time output
await x(command, commandArgs, {
  nodeOptions: {
    stdio: 'inherit',
  },
})

这意味着：

• 每次运行都会拉取 ccusage@latest（npx 会自动缓存，已有版本时不会重复下载）；
• 采用 stdio: 'inherit'，ccusage 的实时输出会原样流入你的终端，交互体验与直接运行 ccusage 一致；
• 命令执行前会先打印一条“正在运行 Claude Code 用量分析工具...”的提示（zh-CN/tools.json），并根据 ZCF 配置的语言显示。

功能详解

ccusage 是一个强大的使用分析工具，主要功能包括：

• 📊 多维度报告：支持日度、周度、月度 token 使用量和成本报告
• 📅 灵活周期：支持 daily、weekly、monthly 等多种统计周期
• 📈 实时监控：实时仪表板显示活动会话进度、token 消耗率和成本预测
• 💬 会话分析：按对话会话分组的使用情况分析
• 🤖 模型细分：查看每个模型（Opus、Sonnet 等）的具体使用成本
• 💰 成本跟踪：显示每天/每月的美元成本
• 🔄 缓存统计：分别跟踪缓存创建和缓存读取的 token
• 📱 智能显示：根据终端宽度自动调整表格布局（支持紧凑模式）
• 🔌 多格式导出：支持 JSON 和 CSV 格式导出，方便二次分析
• 🚀 状态栏集成：支持与 CCometixLine 状态栏集成显示摘要

统计数据来源

ccusage 工具会读取 Claude Code 的官方使用数据库 usage.db，其中包含：

• 调用次数：AI 请求的总次数
• 使用时长：累计的 AI 使用时间
• 时间范围：按指定周期统计的数据
• Token 详情：输入/输出/缓存 Token 数量

需要说明的是，usage.db 通常位于 Claude Code 的配置目录下，数据本身由 Claude Code 官方记录维护。ccusage 与 zcf ccu 均不修改该数据库，只做读取与聚合展示（相关说明见 ccusage 功能概览）。

交互式模式选择（菜单入口的行为细节）

当通过 npx zcf → 选择 U 进入时，会先经过 runCcusageFeature 弹出模式选择，可选项来自 zh-CN/tools.json：

• 日统计（对应 daily）
• 月统计（对应 monthly）
• 会话统计（对应 session）
• 分析代码块（对应 blocks）
• 自定义模式：允许你手动输入任意参数，会按照“保留引号内容”的方式解析参数串再透传（例如输入 --name "John Doe" --age 25 会被解析为 --name、John Doe、--age、25），执行完按 Enter 返回主菜单。

也就是说，直接命令行调用适合脚本化与精确控制，菜单入口适合交互式快速选择，两者最终都汇聚到同一个 executeCcusage 执行链路。

统计周期示例

日统计（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

注：以上为 ccusage 输出格式的示意（对应 daily/weekly/monthly 三种模式），实际数据以本机 usage.db 记录为准；表格布局还会根据终端宽度自动适配。

输出格式

默认格式（表格）

适合终端查看，格式清晰易读，会自动适配终端宽度。

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 价格进行成本估算：

# 生成月度使用报告
npx zcf ccu --period monthly --csv > monthly-usage.csv
# 然后在 Excel 中结合 API 价格计算成本

4. 自动化监控

搭配 cron 定时收集使用数据：

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

与 CCometixLine 集成

CCometixLine 状态栏同样可以显示使用统计摘要（详见 CCometixLine 状态栏）：

1. 安装 CCometixLine：npx zcf → 选择相应选项
2. 在状态栏中查看实时使用情况
3. 点击状态栏可查看详细统计

从 cometix.md 可以看到，CCometixLine 的“使用统计集成”与 ccusage 工具数据保持一致，显示当前会话的 Token 使用量、累计使用成本以及使用趋势。ZCF 在初始化时默认安装 CCometixLine（zcf init 的 --install-cometix-line true），两者配合即可在终端状态栏持续感知用量。

常见问题

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 文件（会丢失所有历史记录）。

Q: zcf ccu 执行失败怎么办？

A: 从 ccu.ts 的实现看，zcf ccu 本身不直接抛出详细堆栈，而是打印“CCUsage 运行失败”和“检查网络连接”两条提示后退出（退出码 1）。如果出现这种情况，请按以下顺序排查：

1. 确认网络可访问 npm registry（npx ccusage@latest 首次执行需要下载）；
2. 确认 usage.db 存在且有实际使用记录；
3. 如需查看完整错误详情，可设置环境变量 DEBUG=true 后重新运行，此时会输出“错误详情”信息（tools.json）；
4. 以上行为在测试中有明确覆盖，见 tests/commands/ccu.test.ts。

相关文档

• CCometixLine 状态栏 - 实时查看使用情况
• 使用分析功能介绍 - 功能概览
• 命令概览 - ZCF 全部命令一览