AI Agent 成本工程

基於 Claude Code v2.1.88 的成本控制機制逆向分析。

模型成本矩陣

Cached tokens 便宜 75-90%。 這是 Claude Code 整個架構圍繞 cache 設計的原因。

Cost Envelope 模式

// Claude Code 的 cost-tracker.ts 核心邏輯
function addToTotalSessionCost(inputTokens, outputTokens, model, speed) {
  const costPerInputToken = MODEL_COSTS[model]?.input ?? UNKNOWN_FALLBACK
  const cost = inputTokens * costPerInputToken + outputTokens * costPerOutputToken
  sessionCost += cost
  // 支援 advisor 模型遞迴計費、Fast Mode OTEL 標記
}

實作要點：

1. 每個任務設預算上限，累計追蹤，超限就停
2. 未知模型用 fallback 費率 + analytics 警告
3. Session 成本持久化到 project config（以 sessionId 隔離）

Prompt Cache 12 種 Break 原因

使用者端避坑清單

Token Estimation 三策略

1. API countTokens（精確，需 API call）
2. Haiku fallback（近似，便宜）
3. length / 4（粗估，免費）
JSON 用 bytes / 2；圖片/PDF 固定 2000 tokens

Compaction 成本陷阱

• 壓縮後第一輪以 125% 費率重建 cache（input token 全是 cache_creation）
• 可觸發最多 3 次連鎖 compaction
• Compaction 用的 forked agent 帶全部 36 工具（已知缺陷，應帶 0 個）
• NO_TOOLS_PREAMBLE 解決 Sonnet 4.6 壓縮時 2.79% 誤呼叫工具

參考

詳見 references/cache-break-causes.md 和 references/cost-matrix.md。