Cost Tracking 专题¶

重要性：⭐⭐⭐（成本追踪——token 用量 + 美元成本 + 多 session 聚合） 真实位置：src/cost-tracker.ts (10706 字节) + src/utils/cost.ts + src/components/CostSummary/ 角色：跟踪每次 API 调用的 token 用量 + 美元成本关联：topics/cache-strategies.md、topics/insights-deep-dive.md

1. Cost Tracking 是什么¶

Cost Tracking = 跟踪 token / 美元成本 - 每次 API 调用的 input + output + cache token - 模型不同单价不同 - 累计 session / day / month - 成本上限

核心：cost-tracker.ts + costHook.ts。

2. 4 个 Cost 文件¶

src/
├── cost-tracker.ts          (10706 字节) 核心
├── costHook.ts              (617 字节)  hook 集成
├── utils/cost.ts            (推测)      计算
└── components/CostSummary/  (推测)      UI 显示

4 个文件。

3. 4 维 Cost 字段¶

type Cost = {
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number     // 推测
  cacheWriteTokens: number    // 推测
  costUSD: number
}

4 + 1 字段 —— 4 种 token + 美元。

3.1 Token 类型¶

input —— 发送的 token
output —— 接收的 token
cache_read —— 缓存命中读取
cache_write —— 缓存写入

3.2 costUSD¶

美元 —— 累计成本。

4. 模型单价¶

const PRICING = {
  'claude-opus-4-8': { input: 15, output: 75 },  // per 1M tokens
  'claude-sonnet-4-6': { input: 3, output: 15 },
  'claude-haiku-4-5': { input: 0.8, output: 4 },
  // ...
}

3+ 个模型 —— 不同单价。

4.1 推测精度¶

costUSD = (inputTokens / 1M) * inputPrice + (outputTokens / 1M) * outputPrice

简单计算 —— 不含 cache token。

5. CostHook¶

// costHook.ts
export function useCostHook() {
  // API 调用后调
  // 累加 cost
}

Hook —— 每次 API 后累加。

5.1 推测流程¶

const response = await api.call(...)

useCostHook({
  model: response.model,
  inputTokens: response.usage.input,
  outputTokens: response.usage.output,
})

自动累加。

6. Cost 累加¶

const totalSessionCost = addToTotalSessionCost(cost)

累加到 session —— 全局状态。

6.1 accumulateUsage¶

import { accumulateUsage, updateUsage } from 'src/services/api/claude.js'

2 个 API —— 累加 + 更新。

7. 成本上限¶

7.1 `--max-budget-usd`¶

--max-budget-usd 1.50

美元上限 —— 超过则退出。

7.2 `--task-budget`¶

--task-budget 5000

token 上限 —— 超过则退出。

7.3 检查¶

if (costUSD > maxBudgetUSD) {
  throw new Error('Budget exceeded')
}

检查 —— 推测。

8. session / day / month 聚合¶

8.1 session 累加¶

const sessionCost = getSessionCost()  // 当前 session

单 session。

8.2 day / month¶

推测：~/.claude/stats/ 持久化。

9. CostSummary 组件¶

// components/CostSummary/

UI 显示 —— 推测在 footer。

9.1 推测显示¶

$0.0123  today
$0.456   this week
$1.234   this month

3 行显示。

10. isOverageProvisioningAllowed¶

function isOverageProvisioningAllowed(): boolean

超额允许 —— 超过订阅限制时仍可用。

11. 与 `/insights` 集成¶

// /insights 命令显示成本

/insights —— 详细 cost 报告。

12. cache 成本¶

12.1 cache_read 成本¶

// 推测：cache_read 比 input 便宜 90%
cacheReadPrice = inputPrice * 0.1

cache 便宜 —— 鼓励使用。

12.2 cache_write 成本¶

// 推测：cache_write 比 input 贵 25%
cacheWritePrice = inputPrice * 1.25

cache 写贵 —— 第一次贵。

12.3 总成本¶

total = input*inputPrice 
      + output*outputPrice
      + cacheRead*0.1*inputPrice
      + cacheWrite*1.25*inputPrice

4 部分。

13. 关键设计模式¶

13.1 Hook 模式¶

每次 API 后自动累加。

13.2 模型单价¶

不同模型不同。

13.3 4 维 token¶

input + output + cache_read + cache_write。

13.4 上限保护¶

max-budget-usd / max-tokens。

13.5 session 累加¶

全局 session cost。

13.6 UI 展示¶

CostSummary 组件。

13.7 insights 集成¶

/insights 显示 cost 报告。

14. 安全 / 隐私¶

14.1 不上传 cost¶

本地累加 —— 不上报（推测）。

14.2 上限不暴露¶

不向 telemetry 上报 cost（推测）。

15. 关键洞察¶

14.1 4 维 token¶

input + output + cache 双向。

14.2 3 模型单价¶

Opus / Sonnet / Haiku 不同。

14.3 Hook 自动累加¶

无需手动。

14.4 上限保护¶

--max-budget-usd / --task-budget。

14.5 cache 成本优化¶

read 便宜 90%。

14.6 /insights 集成¶

详细报告。

14.7 session 累加¶

全局 state。

14.8 isOverageProvisioningAllowed¶

订阅超额仍可用。

14.9 CostSummary UI¶

3 行显示。

14.10 本地累加¶

不远程上报（推测）。

16. 改进方向¶

16.1 实时显示¶

每 token 显示。

16.2 按项目分组¶

每个项目一个 cost。

16.3 预测¶

预测月底 cost。

16.4 警告阈值¶

80% / 100% 警告。

16.5 历史趋势¶

图表显示趋势。

17. 阅读建议¶

看 cost-tracker.ts —— 核心
看 costHook.ts —— hook 集成
看 accumulateUsage in claude.ts —— 累加
看 /insights 输出 —— UI 展示

18. 与其他专题的关系¶

文件	关系
`cache-strategies.md`	cache token
`deep-dive-insights.md`	报告
`prompt-cache.md`	cache 成本