Usage Tracker - Token 使用追踪系统

核心概念

对话轮次 → 记录 usage → 累计统计 → 预算检查 → 超限警告

数据结构

typescript
interface TokenUsage {
input_tokens: number;
output_tokens: number;
cachecreationinput_tokens?: number; // 缓存创建
cachereadinput_tokens?: number; // 缓存读取
}

interface TurnUsage {
turn: number;
prompt: string;
usage: TokenUsage;
timestamp: string;
}

interface UsageBudget {
maxInputTokens: number;
maxOutputTokens: number;
maxTotalTokens: number;
warningThreshold: number; // 80%
}

追踪指标

API 使用

javascript
const { UsageTracker } = require(./scripts/usage-tracker.mjs);

const tracker = new UsageTracker({
maxTotalTokens: 100000,
warningThreshold: 0.8
});

// 记录一次使用
tracker.record({
input_tokens: 500,
output_tokens: 200,
});

// 获取统计
const stats = tracker.getStats();
console.log(stats);
// {
// totalInput: 1500,
// totalOutput: 600,
// totalTokens: 2100,
// turnCount: 3,
// avgInputPerTurn: 500,
// avgOutputPerTurn: 200,
// budgetUsedPercent: 2.1,
// estimatedCost: 0.042
// }

// 检查是否超预算
const budget = tracker.checkBudget();
if (budget.exceeded) {
console.log(⚠️ 超出预算 ${budget.percent}%);
}

// 获取历史
const history = tracker.getHistory();

Token 估算（无需 API）

javascript
// 简单估算（中英文都适用）
function estimateTokens(text) {
// 中文约 1 token / 字符
// 英文约 1 token / 4 字符
const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).length;
const otherChars = text.length - chineseChars;
return chineseChars + Math.ceil(otherChars / 4);
}

费用估算

基于 Claude API 定价（仅供参考）：

预算控制

javascript
const tracker = new UsageTracker({
maxTotalTokens: 50000,
maxTurns: 20,
onBudgetExceeded: (stats) => {
console.log(⚠️ 预算超出！);
console.log(已用: ${stats.totalTokens} / ${stats.maxTotal});
}
});

文件结构

usage-tracker/
├── SKILL.md # 本文件
└── scripts/
└── usage-tracker.mjs # 核心实现