AI 应用CLI开发工具【免费下载链接】ccusagenpx ccusage项目地址https://gitcode.com/gh_mirrors/cc/ccusage点击查看免费下载ccusage 为统计 AI 编码 AgentClaude Code、Codex、OpenCode、Copilot、Gemini 等 20 工具的 token 消耗与成本提供了极其丰富的命令行选项本文基于官方文档 docs/guide/cli-options.md 并结合仓库源码系统讲解每个选项的用法、参数取值、默认行为与底层实现原理。读完本文你将能够熟练使用日期窗口、最近周期、成本模式、时区、输出格式等全套选项组合出适合个人开发、团队协作与成本监控的完整命令方案。所有选项的优先级均高于配置文件与环境变量且对时间、时区、日期等关键输入采取严格校验、拒绝静默降级的策略——这一点会在下文结合源码逐一验证。全局选项Global Options所有 ccusage 命令包括各个 per-agent 报告命令都支持以下全局选项。这些选项在 rust/crates/ccusage-cli/src/types.rs 中统一建模为SharedArgs结构体包含since、until、last、json、mode、debug、debug_samples、order、breakdown、offline、timezone、config、no_cost、jq、compact等字段由 rust/crates/ccusage-cli-parser/src/parser.rs 负责解析填充。日期过滤Date Filtering用日期范围过滤使用数据# 按日期区间过滤两个边界都包含 ccusage daily --since 20260101 --until 20260531 # 只看某一天之后的数据 ccusage monthly --since 20260101 # 只看某一天之前的数据 ccusage session --until 20260531--since与--until两个边界都接受YYYY-MM-DD或YYYYMMDD两种写法且都是**包含式inclusive**边界。任何其他拼写或不是真实日历日期的值如2026-02-30都会以非零退出码被拒绝而不是静默地改变报告保留的行——这一设计避免过滤条件悄悄失效造成数据偏差。从源码看这一校验在两层完成参数归一化层normalize_date_boundrust/crates/ccusage-cli/src/types.rs只接受长度为 8 的YYYYMMDD或长度为 10 且第 4、7 位为-的YYYY-MM-DD随后逐位校验day是否在当月天数范围内含闰年判断非法值返回None交由调用方报错窗口判定层date_within_rangerust/crates/ccusage-core/src/date_utils.rs把日期统一成紧凑的YYYYMMDD字符串做字典序比较since/until均含边界因此部分边界如--since 2026依然可以正常工作date_range_bounds_ms则把窗口解析为半开区间[since 00:00, until 次日 00:00)的 Unix 毫秒边界遇到夏令时跳变日spring-forward会正确处理 23 小时或 25 小时的天长。同样的校验规则也适用于 配置文件 中的since和until。若--since晚于--until无论边界来自命令行参数、配置文件还是两者混合都会被同样拒绝。唯一的例外是statusline命令因为它忽略报告日期过滤包括配置的默认值。近期周期Recent Periods不想手动推算日期时可以直接要最近的 N 个报告周期# 今天 ccusage daily --last 1 # 本周 ccusage weekly --last 1 # 本月 ccusage monthly --last 1 # 最近 7 天、最近 3 个月 ccusage daily --last 7 ccusage monthly --last 3计数包含当前周期daily --last 2覆盖昨天和今天两天。周从报告分桶的起始日开始统一报告一律从周一开始除了ccusage claude weekly它由--start-of-week决定。--last适用于所有 daily、weekly、monthly 报告包括 per-agent 报告如ccusage codex daily --last 1。它在没有日历周期的session、blocks、statusline上不可用也不能与--since、--until、--sections组合使用。源码实现--last N并不是运行时逐行计数而是在参数解析后被转换为--since边界。resolve函数rust/crates/ccusage/src/cli/last_window.rs先根据命令确定周期单位PeriodUnit::Day/Week/Month再调用last_periods_sincerust/crates/ccusage-core/src/last_window.rs计算窗口起点日周期从今天往前推count - 1天count.max(1) - 1因此--last 0等价于--last 1即今天周周期先按start_of_week求出本周起点统一报告恒为周一再往前推count - 1周月周期先定位到本月 1 号再往前推count - 1个月自动跨年如2026-01-15的--last 3会得到20251101。仓库测试 last_window.rs 测试模块 覆盖了跨月、跨年、周起点差异、零计数与非法日期等边界场景并在解析入口 rust/crates/ccusage/src/cli.rs 中先于命令执行被调用。输出格式Output Format# JSON 输出便于程序化处理 ccusage daily --json ccusage daily -j # 按模型展示细分 ccusage daily --breakdown ccusage daily -b # 隐藏成本列与 JSON 成本字段 ccusage daily --no-cost ccusage daily --json --no-cost # 组合使用 ccusage daily --json --breakdown--no-cost会从表格输出中移除成本列并从 JSON 输出中移除totalCost、costUSD、cost等成本字段——适合在只需要 token 统计、或成本数据需要保密/由另一套系统核算的场景。--breakdown展示每个模型的 token 与成本细分。成本计算模式Cost Calculation Mode# auto 模式默认——优先使用 costUSD ccusage daily --mode auto # calculate 模式——始终从 token 数计算 ccusage daily --mode calculate # display 模式——只显示预计算的 costUSD ccusage daily --mode display三种模式的语义在 docs/guide/cost-modes.md 中有完整阐述auto会智能选择——当数据自带预计算成本如 Claude 的costUSD时直接使用否则按模型定价从 token 数重新计算calculate始终基于 token 数与模型定价计算display则只展示数据中预置的成本。对应CostMode枚举定义在 rust/crates/ccusage-cli/src/types.rs默认值为Auto。排序方式Sort Order# 最新在前默认 ccusage daily --order desc # 最旧在前 ccusage daily --order asc注意 rust/crates/ccusage-cli/src/types.rs 中SharedArgs::with_defaults()默认设置的是order: SortOrder::Ascorder_explicit字段用于区分用户是否显式指定——报告层的排序逻辑以显式指定为准。离线模式Offline Mode# 使用缓存的定价数据 ccusage daily --offline ccusage daily -O离线模式强制使用本地缓存的模型定价数据避免网络请求。对应offline与no_offline两个布尔字段便于脚本与配置覆盖。时区Timezone# 使用 UTC ccusage daily --timezone UTC # 使用指定 IANA 时区 ccusage daily --timezone America/New_York ccusage daily -z Asia/Tokyo # 短别名 ccusage monthly -z Europe/London时区值必须是UTC、其他 IANA 时区名如America/New_York或local表示系统时区。未知名称如Not/AZone会以非零退出码被拒绝不会静默回退到系统时区——因为回退可能导致使用数据被归到错误的日期分组。相同的校验也作用于 配置文件 中的timezone。源码实现校验发生在 rust/crates/ccusage/src/cli/timezone.rs 的validate函数中它提取命令最终生效的时区命令行 flag 覆盖配置文件值并调用is_valid_timezonerust/crates/ccusage-core/src/date_utils.rslocal与UTC直接放行其余名称通过 jiff 库的JiffTimeZone::get查表确认查不到即报错。测试用例rejects_unknown_timezones_wherever_they_are_given验证了根命令、daily、claude daily/session、codex monthly、blocks、statusline等所有入口的拒绝行为checks_config_timezones_after_flags_override_them则验证了配置时区可被命令行覆盖。时区对分组的影响时区决定了使用数据按哪个自然日归组。例如北京时间 1 月 1 日晚上 11 点即 UTC 1 月 1 日 15:00产生的使用量--timezone UTC→ 记入1 月 1 日--timezone America/New_YorkESTUTC-5→ 记入1 月 1 日当地 1 月 1 日上午 10 点--timezone Asia/TokyoJSTUTC9→ 记入1 月 2 日当地已是 1 月 2 日 0 点。对于跨时区协作的团队统一--timezone UTC可以保证大家看到完全一致的日期分组。调试选项Debug Options# 调试模式——显示定价不一致与配置加载过程 ccusage daily --debug # 显示抽样不一致 ccusage daily --debug --debug-samples 10--debug输出定价不匹配与配置加载细节--debug-samples N控制抽样的样本数量默认值为 5见SharedArgs::with_defaults中的debug_samples: 5。配置文件Configuration File# 指定自定义配置文件 ccusage daily --config ./my-config.json ccusage monthly --config /path/to/team-config.json--config指向一个自定义 JSON 配置文件其中的默认值会被加载并作为本次运行的基准。关于配置文件的 schema、defaults与commands分节写法参见 docs/guide/config-files.md。命令特定选项Command-Specific Options统一报告选项Unified Report Options以下选项适用于聚合所有检测到的来源时的ccusage daily、ccusage weekly、ccusage monthly与ccusage session# 一次加载来源输出多个 JSON 报告小节 ccusage daily --sections daily,monthly,session --json # 在 daily/weekly/monthly 的 JSON 行中追加按 Agent 的细分 ccusage daily --by-agent --json--sections接受逗号分隔的daily、weekly、monthly、session列表被调用的报告小节总是会被包含例如ccusage daily --sections weekly仍会输出 daily 表格外加 weekly。表格输出时每个请求的小节打印为一张独立表格。--by-agent仅对 JSON 有效——session 行本身就已经是按 Agent 的。从源码看--sections与--by-agent在 rust/crates/ccusage-cli/src/types.rs 的AgentCommandArgs中建模sections: OptionVecAgentReportKind、by_agent: bool解析时由RootAllOptions收集并注入到Command::All或对应命令的参数中rust/crates/ccusage-cli-parser/src/parser.rs。同时--sections与--last互斥违反组合会在last_option_error阶段直接报错。daily 命令# 按项目分组instances 即项目实例维度 ccusage daily --instances ccusage daily -i # 过滤到特定项目 ccusage daily --project myproject ccusage daily -p myproject # 组合项目过滤 ccusage daily --instances --project myprojectDailyArgsrust/crates/ccusage-cli/src/types.rs包含instances: bool与project: OptionString两个专属字段。--instances把默认的按日聚合切换为按项目分组--project支持前缀/模糊匹配项目名常用于只看某个项目的成本。weekly 命令# 设置周起始日 ccusage weekly --start-of-week monday ccusage weekly --start-of-week sundayWeeklyArgs中的start_of_week: WeekDay决定周的边界。注意统一报告含ccusage weekly默认以周一为一周起点UNIFIED_WEEK_START见 rust/crates/ccusage/src/cli/last_window.rs而ccusage claude weekly允许用此选项覆盖且--last的窗口计算也会同步使用该周起点测试keeps_the_claude_weekly_start_of_week验证了这一点。session 命令# 按会话 ID 过滤 ccusage session --id abc123-session # 按项目过滤 ccusage session --project myprojectSessionArgs提供id: OptionString精确过滤单个会话配合--project可以只查看某个项目下的会话明细。session 报告没有日历周期因此不接受--last、--sections。blocks 命令5 小时计费块# 只显示进行中的块 ccusage blocks --active ccusage blocks -a # 显示最近块最近 3 天 ccusage blocks --recent ccusage blocks -r # 设置告警 token 上限 ccusage blocks --token-limit 500000 ccusage blocks --token-limit max # 实时监控模式 ccusage blocks --live ccusage blocks --live --refresh-interval 2 # 自定义会话长度小时 ccusage blocks --session-length 5BlocksArgsrust/crates/ccusage-cli/src/types.rs包含active、recent、token_limit: OptionString、session_length: f64。--token-limit接受数字或max超过上限时给出告警提示--session-length允许覆盖默认会话长度默认值由二进制的DEFAULT_SESSION_DURATION_HOURS常量提供用于把连续的 5 小时块重新切分。--live配合--refresh-interval秒持续刷新适合长时间挂在终端里观察预算消耗。statusline# 基础状态行 ccusage statusline # 强制离线 ccusage statusline --offline # 启用缓存 ccusage statusline --cache # 自定义刷新间隔 ccusage statusline --refresh-interval 5statusline为 Claude Code hooks 输出紧凑的单行状态token 使用、成本、上下文余量等自带混合时间文件缓存Beta--cache/--no-cache控制缓存开关--refresh-interval控制刷新频率。它的StatuslineArgsrust/crates/ccusage-cli/src/types.rs独立持有timezone、config、debug、visual_burn_rate、cost_source、context_low_threshold、context_medium_threshold等字段。正如前面提到的statusline 忽略报告日期过滤因此不适用--since/--until/--last。JSON 输出# 输出 JSON ccusage daily --json # 输出不含成本字段的 JSON ccusage daily --json --no-cost # 管道给 jq ccusage daily --json | jq .data[] # 提取特定字段 ccusage session --json | jq .data[] | {date, cost}JSON 模式是脚本化、自动化集成的首选结构稳定、字段齐全且可以自由与jq组合做二次加工。若希望脚本静默运行可配合环境变量LOG_LEVEL0抑制日志输出LOG_LEVEL0 ccusage daily --json选项优先级Option Precedence选项按以下顺序生效从高到低命令行参数——直接指定的 CLI 选项自定义配置文件——通过--config指定项目本地配置——.ccusage/ccusage.json用户配置——~/.config/claude/ccusage.json旧版配置——~/.claude/ccusage.json内置默认值这一优先级在解析入口得到体现parse_from_with_configrust/crates/ccusage-cli-parser/src/parser.rs先通过ConfigContext加载配置并调用config.apply_shared填充默认值随后命令行 flag 逐个覆盖时区校验代码也专门注释说明命令行 flag 覆盖配置值后才统一校验一次rust/crates/ccusage/src/cli/timezone.rs。实战示例个人开发工作流# 每日开发检查按项目分组 按模型细分 ccusage daily --instances --breakdown # 检查某项目自年初的成本 ccusage daily --project myapp --since 20260101 # 导出月度报告 ccusage monthly --json monthly-report.json团队协作# 使用团队统一配置 ccusage daily --config ./team-config.json # 统一时区保证跨地区日期分组一致 ccusage daily --timezone UTC # 生成可分享的周报 ccusage weekly --json成本监控# 实时监控进行中的计费块 ccusage blocks --active --live # 检查是否接近 token 上限 ccusage blocks --token-limit 500000 # 历史分析始终从 token 重算成本 模型细分 ccusage monthly --mode calculate --breakdown问题排查# 调试配置加载 ccusage daily --debug --config ./test-config.json # 检查定价不一致抽样 20 条 ccusage daily --debug --debug-samples 20 # 脚本静默模式 LOG_LEVEL0 ccusage daily --json短别名速查Short Aliases长选项短选项说明--json-jJSON 输出--breakdown-b按模型细分--offline-O离线模式--timezone-z设置时区--instances-i按项目分组--project-p过滤项目--active-a只显示进行中的块--recent-r显示最近块此外-h/--help显示帮助、-v/-V/--version显示版本这两个控制参数在 rust/crates/ccusage-cli-parser/src/parser.rs 的control_arg中被优先识别并立即退出。解析器还支持--flagvalue内联赋值写法见 rust/crates/ccusage-cli-parser/src/arg_parser.rs缺失参数值时会报 Missing value for --flag 并以非零退出码结束。相关文档环境变量——通过环境变量配置配置文件——持久化配置与优先级成本计算模式——深入理解 auto / calculate / display 三种模式赞分享AI 应用CLI开发工具【免费下载链接】ccusagenpx ccusage项目地址https://gitcode.com/gh_mirrors/cc/ccusage点击查看免费下载相关推荐Composer 命令行完全指南从全局选项到环境变量的命令手册Composer 命令行完全指南从全局选项到环境变量的命令手册 Composer 是 PHP 生态中最核心的依赖管理器本文以 doc/03 cli.md h包管理器开发工具CLIreact-boilerplate 命令行命令完全指南从初始化、开发到部署的 npm 脚本实战手册react boilerplate 命令行命令完全指南从初始化、开发到部署的 npm 脚本实战手册 导读 本文是 react boilerplate 项目 官前端示例工程开发工具终极Qwen命令行交互指南从零基础到专业实战的完整手册终极Qwen命令行交互指南从零基础到专业实战的完整手册 Qwen通义千问是阿里巴巴云推出的开源大型语言模型提供了强大的命令行交互功能。本指南将帮助你快速大模型人工智能微调模型量化模型评测本地部署模型推理服务Qwen上一篇IntersectionObserver 使用教程下一篇WSAGAScript多架构支持x86_64与ARM64安装差异详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考