| name | cc-cost-engineering |
| description | AI Agent 成本工程 — 基於 Claude Code 的成本追蹤、prompt cache 最佳化、token 預算控制逆向分析。Use when: 優化 token 消耗、設計成本控制機制、分析 cache 效率、選擇模型配置。 |
| version | 202603 |
| context | fork |
AI Agent 成本工程
基於 Claude Code v2.1.88 的成本控制機制逆向分析。
模型成本矩陣
| 模型 | Input/MTok | Output/MTok | 相對成本 |
|---|
| Haiku 3.5 | $0.80 | $4.00 | 1x |
| Sonnet 4.6 | $3.00 | $15.00 | 3.75x |
| Opus 4.6 | $15.00 | $75.00 | 18.75x |
| Opus 4.6 Fast | $30.00 | $150.00 | 37.5x |
Cached tokens 便宜 75-90%。 這是 Claude Code 整個架構圍繞 cache 設計的原因。
Cost Envelope 模式
function addToTotalSessionCost(inputTokens, outputTokens, model, speed) {
const costPerInputToken = MODEL_COSTS[model]?.input ?? UNKNOWN_FALLBACK
const cost = inputTokens * costPerInputToken + outputTokens * costPerOutputToken
sessionCost += cost
}
實作要點：
- 每個任務設預算上限，累計追蹤，超限就停
- 未知模型用 fallback 費率 + analytics 警告
- Session 成本持久化到 project config（以 sessionId 隔離）
Prompt Cache 12 種 Break 原因
| # | 原因 | 影響 | 防禦 |
|---|
| 1 | System prompt 內容變化 | 全 bust | 靜態/動態邊界 |
| 2 | Tool schema 變化 | 全 bust | 不排序工具陣列 |
| 3 | MCP 工具動態載入 | 部分 bust | Deferred loading |
| 4 | Agent list 變化 | 全 bust | 移到 attachment |
| 5 | currentDate 跨日 | 全 bust | 已知缺陷，應移到 dynamic zone |
| 6 | Compaction 改寫訊息 | 全 bust | 不可避免，但可用 fork 繼承 |
| 7 | Feature flag 切換 | 全 bust | Sticky Latch |
| 8 | Beta header 變化 | Server-side bust | Latch 機制 |
| 9 | 版本更新 | 全 bust | 不可避免 |
| 10 | Permission mode 變化 | Tool schema bust | 避免 mid-session 切換 |
| 11 | Plugin/MCP 重載 | Tool bust | 避免 /reload-plugins |
| 12 | 使用者切換 cwd | env_info bust | 固定工作目錄 |
使用者端避坑清單
| 坑 | 成本影響 | 避法 |
|---|
| Auto Mode + Max 訂閱 | 每次工具操作用 Opus 分類，佔 15-28% | 關 Auto Mode 或改手動 |
| Agent SDK 的 file modification injection | 每輪吃 5-15% context | 用 CLI；或壓短 session |
| 跨午夜長 session | 整段 cache 全滅 | 午夜前結束 |
| 頻繁開關 session | 每次 max_tokens:1 探測 | 用長 session + /compact |
| 裝太多 MCP server | 每輪注入不快取指令 | 只裝需要的 |
| 工作中切目錄 | env_info bust cache | 固定目錄，用絕對路徑 |
| 大量改檔後繼續對話 | file modification diff 每輪注入 | 改完 /compact 或開新 session |
| Resume 舊 session | stale check 必觸發 | 不 resume，開新的 |
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。
