cost-tracking

費用追蹤 (Cost Tracking)

使用此 Skill 來分析由 ECC 的 stop:cost-tracker hook 所寫入的指標紀錄，藉此掌握 Claude Code 的歷史費用與使用量。

資料儲存位置

追蹤器會在每次工作階段結束（session-stop）時，將一個 JSON 物件附加到 ~/.claude/metrics/costs.jsonl 中。每一列都是該工作階段的累計快照，因此若要計算總支出，請取每個 session_id 的最新一列再進行跨工作階段加總——直接加總每一列會導致重複計算。

列結構 schema：

欄位	說明
timestamp	快照的 ISO 時間戳記
session_id	Claude Code 工作階段識別碼
transcript_path	工作階段對話紀錄檔路徑
model	所使用的模型
input_tokens / output_tokens	Token 數量
cache_write_tokens / cache_read_tokens	Prompt 快取 token 數量
estimated_cost_usd	該工作階段預先計算的累計美元費用

請優先使用 estimated_cost_usd，而非手動計算價格——模型與快取的定價會隨時間變動，而追蹤器紀錄的數據才是權威來源。

使用時機

• 當使用者詢問「我花了多少錢？」、「這個 session 花了多少？」或「我的 token 使用量是多少？」時。
• 當使用者提及預算、支出上限、費用超支或成本控制時。
• 當使用者需要按模型、工作階段或日期進行費用拆解，或是匯出 CSV 檔時。

運作方式

首先確認紀錄檔是否存在（請使用 node 而非 sqlite3——因為追蹤器寫入的是 JSONL 格式，且 node 具備跨平台特性）：

node -e 'const fs=require("fs"),os=require("os"),p=require("path");const f=p.join(os.homedir(),".claude","metrics","costs.jsonl");console.log(fs.existsSync(f)?"cost log found":"cost log not found: "+f)'

如果紀錄檔不存在，請勿捏造使用數據。請告知使用者，在啟用 stop:cost-tracker hook 的情況下完成首次工作階段後，費用追蹤數據才會開始寫入。

範例 — 摘要、按模型分類、最近 7 天

node -e '
const fs=require("fs"),os=require("os"),path=require("path");
const f=path.join(os.homedir(),".claude","metrics","costs.jsonl");
if(!fs.existsSync(f)){console.log("cost log not found: "+f);process.exit(0);}
const rows=fs.readFileSync(f,"utf8").split(/\r?\n/).filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean);
const bySession=new Map();
for(const r of rows){const k=r.session_id||r.transcript_path||r.timestamp;const p=bySession.get(k);if(!p||String(r.timestamp)>String(p.timestamp))bySession.set(k,r);}
const latest=[...bySession.values()];
const cost=r=>Number(r.estimated_cost_usd)||0, day=r=>String(r.timestamp||"").slice(0,10), sum=a=>a.reduce((s,r)=>s+cost(r),0), f4=n=>"$"+n.toFixed(4);
const today=new Date().toISOString().slice(0,10), yest=new Date(Date.now()-864e5).toISOString().slice(0,10);
console.log("today: "+f4(sum(latest.filter(r=>day(r)===today)))+" | yesterday: "+f4(sum(latest.filter(r=>day(r)===yest)))+" | total: "+f4(sum(latest))+" ("+latest.length+" sessions)");
const m=new Map();for(const r of latest){const k=r.model||"(unknown)";m.set(k,(m.get(k)||0)+cost(r));}
console.log("by model:");[...m.entries()].sort((a,b)=>b[1]-a[1]).forEach(([k,v])=>console.log("  "+f4(v)+"  "+k));
'

若需要深入檢視單一工作階段或匯出 CSV，可以迭代相同的 latest 資料集（若要匯出 CSV 則使用原始列資料 rows），並印出所需的欄位。

報告與呈現建議

呈現費用數據時，請包含今日與昨日的花費對比、所有工作階段的總計支出、按模型分類的明細以及工作階段總數。低於 1 美元的金額請格式化至小數點後四位，較大金額則顯示至小數點後兩位。

應避免的做法 (Anti-Patterns)

• 切勿直接加總每一列——資料屬於單一工作階段的累計值，請先過濾出每個 session_id 的最新一列。
• 當存在 estimated_cost_usd 時，切勿使用原始 token 數量自行估算費用。
• 切勿在未經檢查的情況下預設紀錄檔必定存在。
• 切勿在向使用者說明的回覆中硬編碼（hard-code）當前的模型定價。
• 切勿推薦安裝未經審查、可能執行任意程式碼的 hook 或外掛。

相關資源

• /cost-report - 基於同一個指標紀錄檔產生的指令格式報告。
• cost-aware-llm-pipeline - 模型路由與預算設計模式。
• token-budget-advisor - 上下文（Context）與 token 預算規劃。
• strategic-compact - 上下文壓縮技術，用以減少重複消耗的 token 費用。