使用情况跟踪Skill usage

---

名称: 使用情况 描述: “令牌使用情况跟踪、成本估算和使用分析” 表情: “📊”

使用情况 - 完整API参考

跟踪令牌使用、估算成本和跨会话及用户分析AI消耗。

---

聊天命令

查看使用情况

/usage                                      当前会话使用情况
/usage today                                今日总使用情况
/usage week                                 本周使用情况
/usage month                                本月使用情况

详细细分

/usage by-model                             按AI模型使用情况
/usage by-user                              按用户使用情况 (管理员)
/usage by-session                           按会话使用情况
/usage history                              历史使用情况

成本跟踪

/usage cost                                 估算成本
/usage cost today                           今日成本
/usage cost month                           月度成本
/usage budget                               检查预算

设置

/usage footer on                            在响应中显示使用情况
/usage footer tokens                        仅显示令牌计数
/usage footer full                          显示令牌计数和成本
/usage footer off                           隐藏使用情况页脚

---

TypeScript API参考

创建使用情况服务

import { createUsageService } from 'clodds/usage';

const usage = createUsageService({
  // 存储
  storage: 'sqlite',  // 'sqlite' | 'postgres' | 'memory'
  dbPath: './usage.db',

  // 定价 (每1百万令牌)
  pricing: {
    'claude-3-opus': { input: 15.00, output: 75.00 },
    'claude-3-sonnet': { input: 3.00, output: 15.00 },
    'claude-3-haiku': { input: 0.25, output: 1.25 },
    'gpt-4': { input: 30.00, output: 60.00 },
    'gpt-4o': { input: 5.00, output: 15.00 },
  },

  // 页脚模式
  footerMode: 'tokens',  // 'off' | 'tokens' | 'full'
});

记录使用情况

// 记录一个请求
await usage.record({
  userId: 'user-123',
  sessionId: 'session-456',
  model: 'claude-3-sonnet',
  inputTokens: 1500,
  outputTokens: 800,
  durationMs: 2300,
  cached: false,
});

获取会话使用情况

const session = await usage.getSessionUsage('session-456');

console.log(`会话: ${session.sessionId}`);
console.log(`请求: ${session.requests}`);
console.log(`输入令牌: ${session.inputTokens.toLocaleString()}`);
console.log(`输出令牌: ${session.outputTokens.toLocaleString()}`);
console.log(`总令牌: ${session.totalTokens.toLocaleString()}`);
console.log(`估算成本: $${session.estimatedCost.toFixed(4)}`);
console.log(`持续时间: ${session.totalDurationMs}ms`);

获取用户使用情况

const user = await usage.getUserUsage('user-123', {
  period: 'month',  // 'day' | 'week' | 'month' | 'all'
});

console.log(`用户: ${user.userId}`);
console.log(`会话数: ${user.sessions}`);
console.log(`总令牌: ${user.totalTokens.toLocaleString()}`);
console.log(`估算成本: $${user.estimatedCost.toFixed(2)}`);

获取总使用情况

const total = await usage.getTotalUsage({
  from: '2024-01-01',
  to: '2024-01-31',
});

console.log(`总请求: ${total.requests}`);
console.log(`总令牌: ${total.totalTokens.toLocaleString()}`);
console.log(`总成本: $${total.estimatedCost.toFixed(2)}`);

按模型使用情况

const byModel = await usage.getUsageByModel({
  period: 'month',
});

for (const [model, stats] of Object.entries(byModel)) {
  console.log(`${model}:`);
  console.log(`  请求: ${stats.requests}`);
  console.log(`  令牌: ${stats.totalTokens.toLocaleString()}`);
  console.log(`  成本: $${stats.cost.toFixed(2)}`);
}

格式化页脚

// 获取用于消息的格式化使用情况页脚
const footer = usage.formatFooter({
  inputTokens: 1500,
  outputTokens: 800,
  model: 'claude-3-sonnet',
});

// 输出: "令牌: 1.5k 输入 / 800 输出 | 成本: ~$0.02"

格式化摘要

// 获取格式化摘要
const summary = await usage.formatSummary({
  userId: 'user-123',
  period: 'today',
});

console.log(summary);
// "今日: 15 请求 | 45k 令牌 | ~$0.85"

估算成本

// 估算一个请求的成本
const cost = usage.estimateCost({
  model: 'claude-3-opus',
  inputTokens: 5000,
  outputTokens: 2000,
});

console.log(`估算成本: $${cost.toFixed(4)}`);

---

模型定价 (每1百万令牌)

模型	输入	输出
claude-3-opus	$15.00	$75.00
claude-3-sonnet	$3.00	$15.00
claude-3-haiku	$0.25	$1.25
gpt-4	$30.00	$60.00
gpt-4o	$5.00	$15.00
gpt-4o-mini	$0.15	$0.60

---

页脚模式

模式	输出
off	不显示使用情况
tokens	令牌: 1.5k 输入 / 800 输出
full	`令牌: 1.5k 输入 / 800 输出

---

预算警报

// 设置月度预算
usage.setBudget({
  userId: 'user-123',
  monthly: 50.00,  // $50/月
  alertAt: [0.5, 0.8, 0.95],  // 在50%, 80%, 95%时警报
});

// 检查预算状态
const budget = await usage.checkBudget('user-123');

console.log(`预算: $${budget.limit}`);
console.log(`已使用: $${budget.used.toFixed(2)} (${budget.percent}%)`);
console.log(`剩余: $${budget.remaining.toFixed(2)}`);

---

最佳实践

1. 定期监控 — 每周检查使用情况
2. 设置预算 — 防止意外成本
3. 使用合适的模型 — 简单任务使用Haiku
4. 尽可能缓存 — 减少重复查询
5. 按用户审查 — 识别重度用户