用量与成本计算说明 · USAGE & COST EXPLAINED

控制台里的「用量」其实来自两个互不相交的数据源,口径不同、覆盖范围不同,所以经常看着「对不上」。本文把两者来源、为什么对不上、成本怎么算、按天/周/月怎么分桶讲清楚。

两个数据源 · TWO SOURCES

A · 账号级订阅额度

额度条 / QuotaMeter(顶栏)
  • daemon 直连 GET api.anthropic.com/api/oauth/usage,取 five_hour / seven_day 的利用率百分比。
  • 覆盖范围 = 整个 Claude Code 账号:你手敲的交互会话、别的项目、别的工具,全部计入。
  • maestro 只能拿到这个「总量百分比」,拿不到明细,也无法拆出「哪部分是 maestro 烧的」。
  • 来源:src/daemon/usage.ts

B · maestro 自有 run 的 cost / token

AGENT 卡 2×2 + 用量详情弹框
  • 每次 maestro worker 跑 CC 调用,从 result 读 四类 token 写进 outbox.ndjson,daemon 折算累加进 runs.cost_usd / runs.usage
  • 覆盖范围 = 仅 maestro 的任务执行(executor + 双复审 + 解冲突等),你自己的会话不在内
  • 天然比额度条少 —— 它只统计自己发起的 run。
  • 来源:cc.ts → ingest.ts → store.setRunUsage() / costSummary() / usageDetail()
「最近只有 maestro 在跑,却还有其他 token 消费」的真相:
那是你自己用 Claude Code 烧的额度(交互会话 / 其他工具)。它只反映在数据源 A(账号级额度条)里,maestro 采集不到、也算不进数据源 B 的明细,但额度条照样会动。这不是 bug,是两个数据源口径不同。 控制台已分别标注:额度条标「账号级,含交互会话」,AGENT 卡 / 详情标「仅统计 maestro 任务执行」。
成本如何计算 · COST FORMULA

数据源 B 的成本是逐次 CC 调用精确折算后累加的。公式:

成本(USD) = Σ( input·Pin + output·Pout + cacheRead·Pcr + cacheWrite·Pcw ) / 1,000,000 四类 token 各按其模型单价折算;单价单位 = USD / 每 1M token。一个 run 可能含多次 CC 调用(executor + 双复审 / resume / 回退),每次按各自模型精确折算后求和 → runs.cost_usd 准确。来源:src/model/pricing.ts · store.setRunUsage()
模型 input output cacheRead cacheWrite
claude-opus-4-815751.518.75
claude-sonnet-4-63150.33.75
claude-haiku-4-5150.11.25

单价单位:USD / 1M token。模型名归一:精确命中优先,否则按已知前缀匹配(容忍日期 / 区域后缀,如 claude-opus-4-8-20260101)。源:src/model/pricing.ts · MODEL_PRICES

$ 是按 API 列表价的名义估算,不是订阅实际扣费。 它衡量「这些 run 若按 API 计价值多少钱」,便于横向比较项目/模型开销;你的实际账单取决于订阅套餐,二者不应直接相等。控制台 $ 处标注「按 API 列表价估算,非订阅实际扣费」,并以 前缀提示。
按天 / 周 / 月分桶与时区 · BUCKETING
本次修复(时区分桶): 此前分桶与窗口起点全用 UTC,UTC+8 用户在本地 00:00–08:00 跑的 run 会被算进前一天、当天窗口晚 8 小时开始 → 柱状图整体偏移一天、当天偏小。现已统一改为 daemon 本地时区(local-first 单机,daemon 时区即用户时区,零配置)。SQL 比较的是绝对时刻,本地零点转 ISO 后比较仍正确。源:store.ts · localDay / localMonth / periodStartISO / weekStartLabel / usageDetail
已知近似 · KNOWN APPROXIMATIONS
单一事实源:成本计价集中于 src/model/pricing.ts,分桶 / 窗口集中于 src/store/store.ts
数据源 A(额度):src/daemon/usage.ts;数据源 B(明细):cc.ts → ingest.ts → store.ts
本文随实现变化更新;新增 / 迁移文档请同步登记 docs/index.html