# 第一阶段 · 模块一 · 第十节：Cost Tracker 成本追踪
Claude Code 如何追踪 API 使用成本？Cost Tracker 的工作原理是什么？如何计算 Token 费用？如何避免意外超支？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 工具层（tools/） │
│ │
│ Cost Tracker ← 本节 │
│ ├── Token 计数 │
│ ├── 费用计算 │
│ ├── 限额警告 │
│ └── 使用报告 │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/cost-tracker.ts`
Claude API 按 Token 计费，Cost Tracker 帮助用户了解和控制 AI 使用成本，避免意外超支。
┌─────────────────────────────────────────────────────────────────────┐
│ Cost Tracker 功能 │
│ │
│ ├─ Token 计数 ──> 追踪输入/输出 Token │
│ ├─ 费用计算 ──> 按模型定价计算 USD │
│ ├─ 限额警告 ──> 接近限额时提醒 │
│ └─ 使用报告 ──> 生成详细的使用报告 │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/cost-tracker.ts`
// 成本追踪函数
getTotalCostUSD() // 获取总成本
getTotalInputTokens() // 获取输入 Token
getTotalOutputTokens() // 获取输出 Token
getUsageForModel() // 按模型统计
问 1：Cost Tracker 和普通日志有什么区别？
// 普通日志：
// - 记录 API 调用
// - 需要手动计算费用
// - 无限额警告
// Cost Tracker：
// - 实时成本计算
// - 自动汇总统计
// - 主动限额提醒
源码位置：`src/bootstrap/state.ts`
// Token 统计
getTotalInputTokens(): number // 总输入 Token
getTotalOutputTokens(): number // 总输出 Token
getTotalCacheCreationInputTokens(): number // 缓存创建 Token
getTotalCacheReadInputTokens(): number // 缓存读取 Token
getTotalWebSearchRequests(): number // 网页搜索次数
// 按模型统计
getUsageForModel(model: string): ModelUsage
type ModelUsage = {
inputTokens: number
outputTokens: number
cacheReadInputTokens: number
cacheCreationInputTokens: number
costUSD: number
}
追踪流程：
┌─────────────────────────────────────────────────────────────────────┐
│ 1. API 调用 │
│ └─> 输入 Token 计数 │
│ │
│ 2. 响应处理 │
│ └─> 输出 Token 计数 │
│ │
│ 3. 缓存命中 │
│ └─> 缓存 Token 计数 │
│ │
│ 4. 成本计算 │
│ └─> 按模型定价计算 │
└─────────────────────────────────────────────────────────────────────┘
问 1：哪些操作会产生 Token 费用？
// 费用产生的操作：
// 1. 发送消息
// - 用户输入 → 输入 Token
// - Claude 回复 → 输出 Token
// 2. 上下文压缩
// - 压缩操作产生额外 Token
// 3. 网页搜索
// - 搜索请求计入
// 4. 工具调用
// - 工具参数和结果计入
源码位置：`src/utils/modelCost.ts`
// USD 成本计算
calculateUSDCost(
inputTokens: number,
outputTokens: number,
model: string
): number
// 公式：
// cost = inputTokens * inputPrice + outputTokens * outputPrice
源码位置：`src/utils/modelCost.ts`
// 标准定价层（Sonnet 等）：$3 输入 / $15 输出
export const COST_TIER_3_15 = {
inputTokens: 3,
outputTokens: 15,
promptCacheWriteTokens: 3.75,
promptCacheReadTokens: 0.3, // 90% 折扣！
webSearchRequests: 0.01,
}
// Opus 4/4.1：$15 输入 / $75 输出
export const COST_TIER_15_75 = {
inputTokens: 15,
outputTokens: 75,
promptCacheWriteTokens: 18.75,
promptCacheReadTokens: 1.5,
webSearchRequests: 0.01,
}
// Opus 4.5：$5 输入 / $25 输出
export const COST_TIER_5_25 = {
inputTokens: 5,
outputTokens: 25,
promptCacheWriteTokens: 6.25,
promptCacheReadTokens: 0.5,
webSearchRequests: 0.01,
}
// Fast Mode（Opus 4.6）：$30 输入 / $150 输出
export const COST_TIER_30_150 = {
inputTokens: 30,
outputTokens: 150,
promptCacheWriteTokens: 37.5,
promptCacheReadTokens: 3,
webSearchRequests: 0.01,
}
// Haiku 3.5：$0.80 输入 / $4 输出
export const COST_HAIKU_35 = {
inputTokens: 0.8,
outputTokens: 4,
promptCacheWriteTokens: 1,
promptCacheReadTokens: 0.08,
webSearchRequests: 0.01,
}
// 缓存成本说明
// 缓存读取（Cache Read）
// - 命中缓存的 Token 价格降低 90%
// - 大幅降低重复查询成本
// 缓存创建（Cache Creation）
// - 首次创建缓存稍贵
// - 但后续读取极便宜
// 优化策略：
// 1. 复用上下文
// 2. 批量处理相似任务
问 1：如何估算一次对话的成本？
// 估算方法：
// 1. 记录 Token 数量
// - 输入: 1000 tokens
// - 输出: 500 tokens
// 2. 计算费用
// 输入费用 = 1000 / 1,000,000 * $3.00 = $0.003
// 输出费用 = 500 / 1,000,000 * $15.00 = $0.0075
// 总费用 = $0.0105
// 3. 考虑缓存
// - 如果 50% 命中缓存
// - 实际费用更低
// CLI 实时成本显示
// 位置：终端底部或侧边栏
// 显示内容：
// - 当前会话成本
// - 输入/输出 Token 数
// - 模型信息
// 格式示例：
// 💰 Cost: $0.023 | In: 1,234 | Out: 567 | Cache: 89%
// 使用报告内容
interface UsageReport {
sessionId: string
startTime: Date
endTime: Date
totalCostUSD: number
byModel: {
[model: string]: {
inputTokens: number
outputTokens: number
costUSD: number
}
}
cacheHitRate: number
averageLatency: number
}
// 历史成本统计
// 日/周/月统计
getDailyCost(): CostSummary
getWeeklyCost(): CostSummary
getMonthlyCost(): CostSummary
// 趋势分析
getCostTrend(days: number): TrendPoint[]
// 限额配置
interface CostLimits {
sessionWarningUSD: number // 会话警告阈值
dailyWarningUSD: number // 每日警告阈值
monthlyWarningUSD: number // 每月警告阈值
}
警告触发：
┌─────────────────────────────────────────────────────────────────────┐
│ 阈值级别 │
│ │
│ 50% ──> 绿色提示 │
│ 75% ──> 黄色警告 │
│ 90% ──> 橙色预警 │
│ 100% ──> 红色停止 │
└─────────────────────────────────────────────────────────────────────┘
问 1：如何设置合理的成本限额？
// 设置方法：
// 1. 评估需求
// - 日常使用：$1-5/天
// - 大量使用：$10-20/天
// 2. 设置缓冲
// - 限额略高于预期
// - 留出调整空间
// 3. 分级警告
// - 50%, 75%, 90%, 100%
// - 及时提醒
// 4. 紧急停止
// - 达到 100% 自动暂停
// - 避免超支
成本优化策略：
┌─────────────────────────────────────────────────────────────────────┐
│ 1. 提示词优化 │
│ - 简洁清晰的指令 │
│ - 避免重复说明 │
│ │
│ 2. 上下文管理 │
│ - 及时压缩上下文 │
│ - 删除无关历史 │
│ │
│ 3. 工具使用 │
│ - 优先使用轻量工具 │
│ - 避免重复调用 │
│ │
│ 4. 模型选择 │
│ - 简单任务用小模型 │
│ - 复杂任务用大模型 │
└─────────────────────────────────────────────────────────────────────┘
// 缓存利用优化
// 1. 保持上下文连贯
// - 相似任务连续执行
// - 提高缓存命中率
// 2. 批量处理
// - 合并多个小任务
// - 减少会话创建开销
// 3. 模板复用
// - 提示词模板化
// - 减少 token 浪费
答案：
// 控制成本的方法：
// 1. 监控
// - 开启 Cost Tracker
// - 定期检查使用报告
// 2. 限额
// - 设置合理的限额
// - 分级警告机制
// 3. 优化
// - 简化提示词
// - 高效使用上下文
// 4. 选择
// - 按需选择模型
// - 平衡质量和成本
答案：
// 缓存对成本的影响：
// 1. 降低重复查询成本
// - 90% 折扣
// - 相同上下文重用便宜
// 2. 增加首次查询成本
// - 缓存创建稍贵
// - 但长期来看划算
// 3. 优化建议
// - 保持上下文连贯
// - 任务批量处理
答案：
// 缓存对成本的影响计算：
// 假设：
// - 输入 Token: 10,000
// - 输出 Token: 5,000
// - 缓存命中率: 80%
// 无缓存成本：
// $3.00 * 10 + $15.00 * 5 = $30 + $75 = $105
// 有缓存成本：
// $3.00 * 2 + $15.00 * 5 + $0.30 * 8000 = $6 + $75 + $2.40 = $83.40
// 节省：$105 - $83.40 = $21.60 (约 20.6%)
答案：
// 成本告警设计：
interface CostAlert {
thresholdUSD: number // 阈值
warningPercent: number // 警告百分比
actions: AlertAction[] // 触发动作
}
type AlertAction =
| { type: 'notify'; message: string }
| { type: 'pause'; reason: string }
| { type: 'limit'; maxUSD: number }
// 实现
async function checkCostThreshold(usage: Usage): Promise<void> {
const cost = calculateTotalCost(usage)
for (const alert of configuredAlerts) {
if (cost >= alert.thresholdUSD * alert.warningPercent / 100) {
await executeAlert(alert)
}
}
}
| 资源 | 说明 |
| `src/cost-tracker.ts` | 成本追踪核心 |
| `src/utils/modelCost.ts` | 模型定价计算 |
| Token 计算器 | Anthropic 官方工具 |
下一节我们将进入 Remote Session 远程会话：
- WebSocket 通信
- 会话状态同步
- 跨设备体验