使用情况 - 完整API参考

Name: Usage-CompleteAPIReference
Rating: 5 (1 reviews)

跟踪令牌使用情况，估算成本，并分析跨会话和用户的AI消费情况。

聊天命令

查看使用情况

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

详细分解

/usage breakdown [today]                    按模型成本分解
/usage by-model                             按AI模型使用（别名）
/usage by-user                              按用户使用
/usage history [days]                       历史使用情况（默认7天）
/usage estimate <model> <in> <out>          估算令牌成本
/usage user <id> [today]                     特定用户使用情况

管理

/usage reset                                清除所有使用数据

TypeScript API参考

创建使用服务

import { createUsageService } from 'clodds/usage';

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

  // 定价（每100万令牌）
  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)}`);

模型定价（每100万令牌）

模型	输入	输出
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)}`);

最佳实践

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