cost-tracking

费用追踪 (Cost Tracking)

使用此 Skill 分析由 ECC 的 stop:cost-tracker Hook 生成的指标日志，获取 Claude Code 的开销与使用历史。

数据存储位置

追踪器会在每次会话结束（session-stop）时，向 ~/.claude/metrics/costs.jsonl 文件末尾追加一条 JSON 数据。每一行代表该会话的累计快照，因此在计算总开销时，必须先过滤出每个 session_id 的最新一行再汇总——如果对所有行直接求和会导致数据重复计算。

数据行字段说明：

Field	Meaning
timestamp	快照的 ISO 时间戳
session_id	Claude Code 会话唯一标识
transcript_path	会话 Transcript 的文件路径
model	所使用的模型
input_tokens / output_tokens	Token 消耗量（输入/输出）
cache_write_tokens / cache_read_tokens	Prompt 缓存 Token 消耗量（写入/读取）
estimated_cost_usd	预先计算好的该会话累计费用（单位：美元 USD）

请优先使用 estimated_cost_usd，不要手动计算费用——模型和缓存的价格随时可能变动，日志中的追踪器数据才是唯一真实依据。

使用场景

• 用户询问“我花了多少钱？”、“这次会话花了多少钱？”或“我的 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 时也可直接遍历原始行数据），并打印所需字段即可。

报告输出规范

向用户展示开销数据时，需包含以下信息：今日与昨日对比、所有会话的总开销、按模型统计的费用明细以及会话总数。对于小于 1 美元的金额，保留 4 位小数；金额大于或等于 1 美元时，保留 2 位小数。

常见误区与避坑指南

• 切勿对所有行直接求和——每行数据是会话内的累计值，必须先按 session_id 过滤提取最新一行。
• 当日志中已包含 estimated_cost_usd 时，不要试图通过原始 Token 数量自行估算费用。
• 切勿未经检查就默认日志文件必定存在。
• 严禁在给用户的回答中硬编码当下的模型单价。
• 严禁推荐安装未经审核、可能执行任意代码的 Hook 或插件。

相关参考

• /cost-report - 基于相同指标日志生成报告的指令形式工具。
• cost-aware-llm-pipeline - 模型路由与预算设计模式。
• token-budget-advisor - 上下文与 Token 预算规划。
• strategic-compact - 上下文压缩以减少重复的 Token 开销。