内容
# 支出监控
**一个监控LLM使用情况、速率限制和跨多个提供商的支出** — 云和本地 — 具有预算保护、实时仪表盘、可机器读取的导出和MCP端点，代理可以在支出前查询。
一个Cognis Digital工具。**零第三方运行时依赖** — 仅Python 3.11+标准库。TUI使用`curses`（带有纯文本备用），HTTP使用`urllib`/`http.server`，Prometheus指标以文本暴露格式手动发出。`pytest`仅在运行测试套件时需要。
---
## 为什么使用支出监控
大多数使用计量器监控一个**单一**提供商，通常从浏览器会话中抓取。但每个严肃的代理堆栈都跨越多个云 **和** 本地模型，并且需要两个单一提供商小部件无法提供的功能：
1. **预算保护**，实际上可以阻止失控运行（CI友好退出代码）。
2. **代理可以询问的端点** — “我的剩余预算是多少？” — 在启动昂贵作业之前。
支出监控统一了所有这些：云和自托管支出在一个标准化的视图中，受保护、预测和可导出到您已经运行的工具中。
## 功能
- **多提供商数据摄入，一个模式。** Anthropic、OpenAI、OpenRouter和本地运行时（Ollama / LM Studio）的适配器将截然不同的原生有效载荷标准化为单个`UsageRecord`。云使用/成本API和本地令牌日志并存。
- **实时限制和会话跟踪。** 当前会话（滚动窗口）、每日、每周、每个模型使用情况与配置的限制、超出包含的计划津贴的支出（“额外使用”）和剩余余额 — 所有这些都源自摄入的记录，按需刷新。
- **预算保护。** 每个项目/每天/每个模型/每个提供商/全局上限，每个都有独立的**警告**和**拒绝**阈值。评估为CI友好的退出代码：`0` ok，`0`（或`1`在`--strict`模式下）警告，`2`拒绝。
- **成本模型。** 输入、输出、缓存、缓存写入和隐藏推理令牌的每个令牌定价，以及每个图像和每个嵌入率。附带可编辑的JSON定价表，具有确定性的模型→速率解析（精确 → 最长前缀 → 提供商默认值 → 表默认值）。
- **燃烧率预测。** 根据当前燃烧率和估计何时达到上限，预测项目每日和月底支出。
- **输出无处不在。** 实时TUI仪表盘、确定性JSON、CSV（记录或分组明细）和Prometheus指标端点，用于现有的可观察性堆栈。
- **MCP服务器。** 一个微小的自包含JSON-RPC/stdio服务器（无外部MCP SDK），暴露一个`remaining_budget`工具，代理可以在大作业前调用。
- **状态小部件桥。** 发出一个微小的、扁平的JSON文件，任何次要显示或流控制器小部件都可以轮询 — 涵盖所有提供商，一目了然。
- **离线优先。** 本地提供商不需要密钥，每个适配器都在确定性的固定装置模式下运行，因此整个管道无需触及付费API即可测试。实时HTTP路径是一个薄的、隔离的层。
## 安装
```bash
pip install -e .
# 或用于开发（添加pytest）
pip install -e ".[dev]"
```
无需安装即可从checkout运行：
```bash
python -m spendwatch --help
```
## 快速入门
```bash
# 以JSON格式显示完整报告（使用捆绑的演示配置 + 固定装置）
python -m spendwatch report --config fixtures/demo_config.json
# 文本仪表盘
python -m spendwatch report --config fixtures/demo_config.json --table
# 评估预算保护；退出代码在拒绝时为非零（非常适合CI）
python -m spendwatch budget --config fixtures/demo_config.json
echo "退出代码：$?"
# 为其他工具导出
python -m spendwatch export -c fixtures/demo_config.json --format csv
python -m spendwatch export -c fixtures/demo_config.json --format prometheus
# 发出状态小部件桥JSON
python -m spendwatch widget -c fixtures/demo_config.json --out status.json
# 将单个提供商有效载荷标准化为记录
python -m spendwatch ingest --provider anthropic --fixture fixtures/anthropic_usage.json
```
## 配置
配置是一个纯JSON对象。固定装置路径相对于配置文件目录解析。
```json
{
"prefer_reported": false,
"sources": [
{"provider": "anthropic", "fixture": "anthropic_usage.json"},
{"provider": "openai", "fixture": "openai_usage.json"},
{"provider": "openrouter", "fixture": "openrouter_usage.json"},
{"provider": "local", "fixture": "local_usage.json"}
],
"limits": {
"plan_allowance_usd": 100.0,
"weekly_limit_usd": 50.0,
"daily_limit_usd": 20.0,
"session_window_minutes": 300,
"per_model_usd": {"claude-opus-4-20250514": 5.0}
},
"budget": {
"strict_warn": false,
"rules": [
{"scope": "global", "limit_usd": 25.0, "warn_ratio": 0.8, "deny_ratio": 1.0, "period": "all"},
{"scope": "project", "key": "proj_alpha", "limit_usd": 10.0, "period": "day"},
{"scope": "model", "limit_usd": 8.0, "period": "all"},
{"scope": "provider", "key": "anthropic", "limit_usd": 15.0}
]
}
}
```
一个`source`可以提供一个`fixture`（路径）、内联`records`（原生行）或一个完整的`payload`（原生信封）。
### 预算规则
| 字段 | 含义 |
|---------------|--------------------------------------------------------------------|
| `scope` | `global`、`project`、`model`、`provider`或`day` |
| `key` | 规则针对的项目/模型/提供商；省略以检查**每个** |
| `limit_usd` | 上限 |
| `warn_ratio` | 触发**警告**的上限分数（默认`0.8`） |
| `deny_ratio` | 触发**拒绝**的上限分数（默认`1.0`） |
| `period` | `all`、`day`或`month`（相对于评估时间） |
**退出代码约定：** `0` = ok（和警告，除非`strict_warn`），`1` = 严格模式下的警告，`2` = 拒绝。在CI步骤中将`spendwatch budget`放入以硬停止超出预算的作业。
## 定价表
`spendwatch/pricing_table.json`是完全可编辑的。费率是每1,000,000个令牌的美元（`image`除外，后者是每张图片的美元）。解析是确定性的：
```
精确模型ID -> 最长前缀模型ID -> 提供商默认值 -> 表默认值
```
检查分辨率：
```bash
python -m spendwatch pricing --model gpt-4o-2024-08-06 --provider openai
```
> 捆绑的费率是合理的起点，而不是实时的价格馈送 — 支出监控从不联网。编辑表格以匹配您的合同。
## MCP：`remaining_budget`
运行stdio MCP服务器：
```bash
python -m spendwatch mcp --config fixtures/demo_config.json
```
它讲的是换行分隔的JSON-RPC 2.0，并实现了`initialize`、`tools/list`和`tools/call`。单个工具`remaining_budget`返回到目前为止的支出（今日/本周/生命周期）、剩余的每日/每周/计划余额、最严格的绑定预算规则、整体状态和CI退出代码 — 可选地限定为`project`或`provider`。当状态为`deny`时设置`isError`标志，因此代理可以拒绝启动昂贵的作业。
## Prometheus端点
```bash
python -m spendwatch metrics --config fixtures/demo_config.json --port 9109
# 然后抓取 http://127.0.0.1:9109/metrics
```
还提供`/report`（JSON）和`/healthz`。指标每抓取一次都会重建，因此保持实时。
## 程序化使用
```python
from spendwatch.config import load_and_build
from spendwatch.report import build_report, remaining_budget
ledger, pricing, guard, limits, prefer = load_and_build("fixtures/demo_config.json")
report = build_report(ledger, pricing, guard=guard, limits=limits)
print(report["summary"]["cost_usd"])
rb = remaining_budget(ledger, pricing, guard=guard, limits=limits)
print(rb["status"], rb["remaining_usd"])
```
## 项目布局
```
spendwatch/
__init__.py 包导出
__main__.py python -m spendwatch
cli.py argparse CLI + 控制台入口点
schema.py UsageRecord — 唯一的标准化模式
money.py 确定性美元数学（Decimal，ROUND_HALF_UP）
timeutil.py 时间戳标准化 + 时期键
pricing.py 成本模型 + 分辨率级联
pricing_table.json 可编辑的定价表
ledger.py 记录集合 + 聚合
budget.py 预算规则、保护、阈值、退出代码
forecast.py 燃烧率预测
session.py 会话/限制跟踪
report.py 规范报告 + 剩余预算
config.py 配置 -> 账本/定价/保护/限制
metrics_server.py Prometheus HTTP端点（stdlib http.server）
providers/ anthropic、openai、openrouter、本地适配器
outputs/ json、csv、prometheus、widget桥、tui
mcp/ 自包含的JSON-RPC/stdio MCP服务器
tests/ 全面的pytest套件
fixtures/ 示例提供商有效载荷 + 演示配置
```
## 测试
```bash
python -m pytest -q
```
该套件涵盖了所有四个提供商的数据摄入标准化、成本模型和定价层、预算保护阈值和退出代码、预测数学、每种输出格式、MCP端点、CLI和边缘情况（零使用、缺失字段、大支出、货币舍入、缓存/推理令牌）。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
