Back to Details

usage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Usage - Complete API Reference

使用指南 - 完整API参考

Track token usage, estimate costs, and analyze AI consumption across sessions and users.
追踪Token使用情况、估算成本，并跨会话和用户分析AI消耗。

Chat Commands

聊天命令

View Usage

查看使用情况

/usage                                      Current session usage
/usage today                                Today's total usage
/usage week                                 This week's usage
/usage month                                This month's usage
/usage                                      当前会话使用情况
/usage today                                今日总使用情况
/usage week                                 本周使用情况
/usage month                                本月使用情况

Detailed Breakdown

详细细分

/usage breakdown [today]                    Cost breakdown by model
/usage by-model                             Usage by AI model (alias)
/usage by-user                              Usage by user
/usage history [days]                       Historical usage (default 7 days)
/usage estimate <model> <in> <out>          Estimate cost for tokens
/usage user <id> [today]                    User-specific usage
/usage breakdown [today]                    按模型细分成本
/usage by-model                             按AI模型查看使用情况（别名）
/usage by-user                              按用户查看使用情况
/usage history [days]                       历史使用情况（默认7天）
/usage estimate <model> <in> <out>          估算Token成本
/usage user <id> [today]                    特定用户的使用情况

Management

管理操作

/usage reset                                Clear all usage data
/usage reset                                清除所有使用数据

TypeScript API Reference

TypeScript API参考

Create Usage Service

创建使用服务

typescript
import { createUsageService } from 'clodds/usage';

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

  // Pricing (per 1M tokens)
  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 },
  },

  // Footer mode
  footerMode: 'tokens',  // 'off' | 'tokens' | 'full'
});
typescript
import { createUsageService } from 'clodds/usage';

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

  // Pricing (per 1M tokens)
  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 },
  },

  // Footer mode
  footerMode: 'tokens',  // 'off' | 'tokens' | 'full'
});

Record Usage

记录使用情况

typescript
// Record a request
await usage.record({
  userId: 'user-123',
  sessionId: 'session-456',
  model: 'claude-3-sonnet',
  inputTokens: 1500,
  outputTokens: 800,
  durationMs: 2300,
  cached: false,
});
typescript
// Record a request
await usage.record({
  userId: 'user-123',
  sessionId: 'session-456',
  model: 'claude-3-sonnet',
  inputTokens: 1500,
  outputTokens: 800,
  durationMs: 2300,
  cached: false,
});

Get Session Usage

获取会话使用情况

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

console.log(`Session: ${session.sessionId}`);
console.log(`Requests: ${session.requests}`);
console.log(`Input tokens: ${session.inputTokens.toLocaleString()}`);
console.log(`Output tokens: ${session.outputTokens.toLocaleString()}`);
console.log(`Total tokens: ${session.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${session.estimatedCost.toFixed(4)}`);
console.log(`Duration: ${session.totalDurationMs}ms`);
typescript
const session = await usage.getSessionUsage('session-456');

console.log(`Session: ${session.sessionId}`);
console.log(`Requests: ${session.requests}`);
console.log(`Input tokens: ${session.inputTokens.toLocaleString()}`);
console.log(`Output tokens: ${session.outputTokens.toLocaleString()}`);
console.log(`Total tokens: ${session.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${session.estimatedCost.toFixed(4)}`);
console.log(`Duration: ${session.totalDurationMs}ms`);

Get User Usage

获取用户使用情况

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

console.log(`User: ${user.userId}`);
console.log(`Sessions: ${user.sessions}`);
console.log(`Total tokens: ${user.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${user.estimatedCost.toFixed(2)}`);
typescript
const user = await usage.getUserUsage('user-123', {
  period: 'month',  // 'day' | 'week' | 'month' | 'all'
});

console.log(`User: ${user.userId}`);
console.log(`Sessions: ${user.sessions}`);
console.log(`Total tokens: ${user.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${user.estimatedCost.toFixed(2)}`);

Get Total Usage

获取总使用情况

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

console.log(`Total requests: ${total.requests}`);
console.log(`Total tokens: ${total.totalTokens.toLocaleString()}`);
console.log(`Total cost: $${total.estimatedCost.toFixed(2)}`);
typescript
const total = await usage.getTotalUsage({
  from: '2024-01-01',
  to: '2024-01-31',
});

console.log(`Total requests: ${total.requests}`);
console.log(`Total tokens: ${total.totalTokens.toLocaleString()}`);
console.log(`Total cost: $${total.estimatedCost.toFixed(2)}`);

Usage by Model

按模型查看使用情况

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

for (const [model, stats] of Object.entries(byModel)) {
  console.log(`${model}:`);
  console.log(`  Requests: ${stats.requests}`);
  console.log(`  Tokens: ${stats.totalTokens.toLocaleString()}`);
  console.log(`  Cost: $${stats.cost.toFixed(2)}`);
}
typescript
const byModel = await usage.getUsageByModel({
  period: 'month',
});

for (const [model, stats] of Object.entries(byModel)) {
  console.log(`${model}:`);
  console.log(`  Requests: ${stats.requests}`);
  console.log(`  Tokens: ${stats.totalTokens.toLocaleString()}`);
  console.log(`  Cost: $${stats.cost.toFixed(2)}`);
}

Format Footer

格式化页脚

typescript
// Get formatted usage footer for messages
const footer = usage.formatFooter({
  inputTokens: 1500,
  outputTokens: 800,
  model: 'claude-3-sonnet',
});

// Output: "Tokens: 1.5k in / 800 out | Cost: ~$0.02"
typescript
// Get formatted usage footer for messages
const footer = usage.formatFooter({
  inputTokens: 1500,
  outputTokens: 800,
  model: 'claude-3-sonnet',
});

// Output: "Tokens: 1.5k in / 800 out | Cost: ~$0.02"

Format Summary

格式化摘要

typescript
// Get formatted summary
const summary = await usage.formatSummary({
  userId: 'user-123',
  period: 'today',
});

console.log(summary);
// "Today: 15 requests | 45k tokens | ~$0.85"
typescript
// Get formatted summary
const summary = await usage.formatSummary({
  userId: 'user-123',
  period: 'today',
});

console.log(summary);
// "Today: 15 requests | 45k tokens | ~$0.85"

Estimate Cost

估算成本

typescript
// Estimate cost for a request
const cost = usage.estimateCost({
  model: 'claude-3-opus',
  inputTokens: 5000,
  outputTokens: 2000,
});

console.log(`Estimated cost: $${cost.toFixed(4)}`);
typescript
// Estimate cost for a request
const cost = usage.estimateCost({
  model: 'claude-3-opus',
  inputTokens: 5000,
  outputTokens: 2000,
});

console.log(`Estimated cost: $${cost.toFixed(4)}`);

Model Pricing (per 1M tokens)

模型定价（每百万Token）

ModelInputOutput
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
模型输入输出
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

Footer Modes

页脚模式

ModeOutput
off
No usage shown
tokens
Tokens: 1.5k in / 800 out
full
`Tokens: 1.5k in / 800 out
模式输出内容
off
不显示使用情况
tokens
Tokens: 1.5k in / 800 out
full
`Tokens: 1.5k in / 800 out

Budget Alerts

预算告警

typescript
// Set monthly budget
usage.setBudget({
  userId: 'user-123',
  monthly: 50.00,  // $50/month
  alertAt: [0.5, 0.8, 0.95],  // Alert at 50%, 80%, 95%
});

// Check budget status
const budget = await usage.checkBudget('user-123');

console.log(`Budget: $${budget.limit}`);
console.log(`Used: $${budget.used.toFixed(2)} (${budget.percent}%)`);
console.log(`Remaining: $${budget.remaining.toFixed(2)}`);
typescript
// Set monthly budget
usage.setBudget({
  userId: 'user-123',
  monthly: 50.00,  // $50/month
  alertAt: [0.5, 0.8, 0.95],  // Alert at 50%, 80%, 95%
});

// Check budget status
const budget = await usage.checkBudget('user-123');

console.log(`Budget: $${budget.limit}`);
console.log(`Used: $${budget.used.toFixed(2)} (${budget.percent}%)`);
console.log(`Remaining: $${budget.remaining.toFixed(2)}`);

Best Practices

最佳实践

  1. Monitor regularly — Check usage weekly
  2. Set budgets — Prevent unexpected costs
  3. Use appropriate models — Haiku for simple tasks
  4. Cache when possible — Reduce duplicate queries
  5. Review by user — Identify heavy users
  1. 定期监控 — 每周检查使用情况
  2. 设置预算 — 避免意外成本
  3. 使用合适的模型 — 简单任务使用Haiku
  4. 尽可能缓存 — 减少重复查询
  5. 按用户查看 — 识别高频使用用户