内容
# LLM 成本守护 🛡️
[](https://www.npmjs.com/package/@wimoron/llm-cost-guard)
[](./LICENSE)
[](#运行测试)
跟踪 LLM 成本，设置支出限制，并在终端、浏览器或 AI 编辑器中接收警报。
**一条命令即可安装。一行代码即可开始跟踪。**
---
## 安装
```bash
npm install @wimoron/llm-cost-guard
```
就这样。不需要配置文件。不需要 API 密钥。立即生效。
---
## 启动仪表盘
```bash
npx @wimoron/llm-cost-guard start
```
在浏览器中打开实时仪表盘，地址为 **http://localhost:47821**。
---
## 跟踪 LLM 调用
在您的应用程序中添加一行代码：
**OpenAI：**
```js
import { patch } from '@wimoron/llm-cost-guard';
import OpenAI from 'openai';
const openai = patch(new OpenAI());
// 像以前一样使用 openai —— 每次调用都会自动跟踪
const res = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello!' }],
});
```
**Anthropic：**
```js
import { patch } from '@wimoron/llm-cost-guard';
import Anthropic from '@anthropic-ai/sdk';
const anthropic = patch(new Anthropic());
const msg = await anthropic.messages.create({
model: 'claude-3-5-sonnet-20241022',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello!' }],
});
```
**任何语言（HTTP）：**
```bash
curl -X POST http://localhost:47821/api/track \
-H "Content-Type: application/json" \
-d '{
"provider": "openai",
"model": "gpt-4o",
"promptTokens": 100,
"completionTokens": 50,
"totalTokens": 150,
"costUSD": 0.00125,
"latencyMs": 450,
"userId": "alice"
}'
```
---
## 设置支出限制
从代码中：
```js
import { addBudget } from '@wimoron/llm-cost-guard';
// 当 alice 的每日支出超过 2 美元时，阻止调用
addBudget({ scope: 'user', scopeId: 'alice', limitUSD: 2.00, windowHours: 24, hardBlock: true });
// 当团队的每日支出超过 50 美元时，发出警报（但不阻止）
addBudget({ scope: 'team', scopeId: 'eng', limitUSD: 50.00, windowHours: 24, hardBlock: false });
// 全局每日 200 美元软上限
addBudget({ scope: 'global', scopeId: 'global', limitUSD: 200.00, windowHours: 24, hardBlock: false });
```
或者，在仪表盘的 **预算** 选项卡中以可视化方式添加。
当达到硬限制时，修补的客户端会抛出：
```
Error: [llm-cost-guard] 用户 "alice" 的预算已超出：$2.0041 of $2.00
code: 'BUDGET_EXCEEDED'
```
像处理任何错误一样捕获它：
```js
try {
const res = await openai.chat.completions.create({ ... });
} catch (err) {
if (err.code === 'BUDGET_EXCEEDED') {
return res.status(429).json({ error: '每日限制已达到。明天再试。' });
}
throw err;
}
```
---
## 在 Claude Code、Cursor、Antigravity、Codex 中使用
**步骤 1 — 连接您的编辑器：**
```bash
npx @wimoron/llm-cost-guard setup
```
这会自动检测已安装的编辑器，并为每个编辑器编写 MCP 配置。
**步骤 2 — 重启您的编辑器。**
**步骤 3 — 在聊天中输入 `/guard` 。**
### 可用的斜杠命令
| 命令 | 功能 |
|---|---|
| `/guard` | 成本摘要 — 今日支出、预算、活动警报 |
| `/guard_dashboard` | 在浏览器中打开实时仪表盘 |
| `/guard_limit` | 为用户或团队设置支出限制 |
| `/guard_top` | 显示今日支出最高的用戶 |
| `/guard_ack` | 清除所有警报 |
### 手动 MCP 配置（如果自动设置找不到您的编辑器）
将以下内容添加到您的编辑器的 MCP 配置文件中：
```json
{
"mcpServers": {
"llm-cost-guard": {
"command": "npx",
"args": ["@wimoron/llm-cost-guard", "mcp"]
}
}
}
```
| 编辑器 | 配置文件位置 |
|---|---|
| Claude Code | `~/.claude/claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |
| Antigravity | `~/.gemini/antigravity/mcp_config.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Codex | `~/.codex/config.toml`（TOML 格式，见下文） |
| VS Code | `.vscode/mcp.json` |
**Codex config.toml 格式：**
```toml
[mcp_servers.llm-cost-guard]
command = "npx"
args = ["@wimoron/llm-cost-guard", "mcp"]
```
---
## 仪表盘
在 **http://localhost:47821** 处打开或运行 `npx @wimoron/llm-cost-guard start`。
| 选项卡 | 您看到的内容 |
|---|---|
| **概览** | 今日/本周支出、每小时图表、提供商分布、顶级用户 |
| **调用日志** | 每次 API 调用 — 模型、标记、成本、延迟、用户 |
| **警报** | 预算警告（80%、100%）、成本激增 |
| **预算** | 添加/删除限制，带有实时进度条 |
| **设置** | 复制粘贴代码段，适用于任何语言或编辑器 |
---
## 支持的提供商和模型
| 提供商 | 自动修补 | 模型 |
|---|---|---|
| OpenAI | ✅ `patch(new OpenAI())` | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo, o1, o3-mini |
| Anthropic | ✅ `patch(new Anthropic())` | claude-opus-4, claude-sonnet-4, claude-haiku-4, claude-3.5-* |
| Gemini | HTTP API | gemini-1.5-pro/flash, gemini-2.0-flash |
未知模型会回落到保守的价格估计。
---
## CLI 命令
```bash
npx @wimoron/llm-cost-guard start # 启动仪表盘（自动打开浏览器）
npx @wimoron/llm-cost-guard setup # 自动连接到所有检测到的编辑器
npx @wimoron/llm-cost-guard status # 检查服务器是否正在运行
npx @wimoron/llm-cost-guard mcp # 启动 MCP 模式（由编辑器内部使用）
```
---
## 运行测试
```bash
npm test
```
---
## API 参考
```js
import {
patch, // patch(client, userId?) — 包装 OpenAI 或 Anthropic
patchOpenAI, // 显式 OpenAI 修补
patchAnthropic, // 显式 Anthropic 修补
addCall, // 手动记录调用
calcCost, // calcCost(provider, model, promptTokens, completionTokens)
addBudget, // addBudget({ scope, scopeId, limitUSD, windowHours, hardBlock })
removeBudget, // removeBudget(id)
checkBudget, // checkBudget(userId) → { blocked, reason }
getStats, // 获取仪表盘统计数据快照
getCalls, // getCalls(limit, userId)
ackAlert, // ackAlert(id) 或 ackAlert('__all__')
startServer, // 以编程方式启动 HTTP 服务器
} from '@wimoron/llm-cost-guard';
```
---
## 要求
- Node.js 18+
- 核心跟踪不需要其他依赖项
- `@modelcontextprotocol/sdk` 和 `zod` 用于 MCP 斜杠命令（已包含）
---
## 许可证
MIT
