Usage Tracker - Token 使用追踪系统

核心概念

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

数据结构

interface TokenUsage {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens?: number;  // 缓存创建
  cache_read_input_tokens?: number;     // 缓存读取
}

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

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

追踪指标

API 使用

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）

// 简单估算（中英文都适用）
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 定价（仅供参考）：

预算控制

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 # 核心实现

龙虾王子自我进化的成果 🦞