内容
**中文**
# 克劳德使用情况插件
[](LICENSE)
[](package.json)
[](package.json)
一个 **克劳德代码插件**，只有一个任务：报告您的克劳德账户的 **5小时** 和 **每周** 使用情况 —— 克劳德代码状态栏中显示的**官方**数字，而不是估计值。它**不施加任何限制**。没有阈值，没有拒绝逻辑，任何内容都不会被阻止。它只读取并报告。
## 目录
- [工作原理](#工作原理)
- [工具](#工具)
- [检查使用情况](#检查使用情况)
- [检查数据状态](#检查数据状态)
- [要求](#要求)
- [安装](#安装)
- [一次性状态栏设置（官方数字必填）](#一次性状态栏设置官方数字必填)
- [可选：工具使用后钩子](#可选工具使用后钩子)
- [设计笔记](#设计笔记)
- [许可证](#许可证)
## 工作原理
克劳德代码（v2.1.80+，Pro/Max）将包含 `rate_limits.{five_hour,seven_day}` 的 JSON 有效载荷发送到注册为其 **statusLine** 钩子的命令中，每次状态栏渲染时都会发送。在每次渲染时，它会将官方的 `rate_limits` 存储到 `~/.usage-guardian-mcp/statusline-latest.json` 中，并打印状态栏（例如 `Opus 4.8 · 5h 86% · 7d 80%`）。无网络调用，永不抛出异常，永不清空状态栏。
该插件有三个组件：
- **`capture-statusline.js`** — 状态栏钩子。在每次渲染时，它会将官方的 `rate_limits` 存储到 `~/.usage-guardian-mcp/statusline-latest.json` 中，并打印状态栏（例如 `Opus 4.8 · 5h 86% · 7d 80%`）。无网络调用，永不抛出异常，永不清空状态栏。
- **`index.js`** — MCP 服务器。它读取捕获并将其公开为两个无参数工具。
- **`usage-hook.js`** — 可选的工具使用后钩子。在每次工具调用后运行，并在克劳德的上下文中注入简短的使用情况摘要。
无网络调用，无会话 cookie，无爬取 —— 数据直接来自克劳德代码。
> **为什么使用状态栏而不是计时器？** 官方的 `rate_limits` 仅传递给状态栏命令。后台计时器无法获取它们，因此只能根据本地令牌计数来估计使用情况。要匹配克劳德代码显示的数字，插件使用状态栏。它在每次渲染时刷新（在您活动时小于一秒），比任何轮询间隔都更频繁。
## 工具
| 工具 | 输入 | 返回 |
|---|---|---|
| `check_usage` | 无 | `{"usage_percent": 86, "resets_at": "...", "seven_day_percent": 80, "seven_day_resets_at": "...", "stale": false}` — `usage_percent`/`resets_at` 为 5 小时窗口；`seven_day_*` 为每周窗口。 |
| `check_data_status` | 无 | `{"authenticated": true}` 或 `{"authenticated": false}` — 是否有可用的且新鲜的捕获（在过去 10 分钟内更新）？ |
结构化错误而不是静默失败：
- `{"error": "statusline_not_configured"}` — 状态栏钩子尚未连接（请参见下面的设置）。
- `{"error": "rate_limits_unavailable"}` — 存在捕获，但克劳德代码未报告 `rate_limits`（需要 v2.1.80+ 并且订阅 Pro/Max 计划）。
### 检查使用情况
读取由状态栏钩子写入的 `~/.usage-guardian-mcp/statusline-latest.json`，并返回单个 JSON 对象：
```json
{
"usage_percent": 86,
"resets_at": "2025-07-07T18:00:00.000Z",
"seven_day_percent": 80,
"seven_day_resets_at": "2025-07-13T00:00:00.000Z",
"stale": false
}
```
`stale: true` 表示捕获已超过 10 分钟 — 没有活动会话最近刷新过它。
### 检查数据状态
廉价的就绪检查：当存在且新鲜的捕获时，返回 `{"authenticated": true}`，否则返回 `{"authenticated": false}`。在调用 `check_usage` 之前运行以避免嘈杂的错误。
## 要求
- [Node.js](https://nodejs.org) 18 或更高版本
- 克劳德代码 v2.1.80+ 并且订阅 **Pro 或 Max 计划**（旧版本/其他计划不包括状态栏有效载荷中的 `rate_limits`）
## 安装
```bash
# 1. 克隆并安装依赖项
git clone https://github.com/MatinMHF/claude-usage-plugin.git
cd claude-usage-plugin
npm install
# 2. 将 MCP 服务器注册到克劳德代码中
claude mcp add claude-usage-plugin -s user -- node /path/to/claude-usage-plugin/index.js
```
或手动将其添加到 `~/.claude/claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"claude-usage-plugin": {
"command": "node",
"args": ["/path/to/claude-usage-plugin/index.js"]
}
}
}
```
### 一次性状态栏设置（官方数字必填）
MCP 服务器仅**读取**捕获；状态栏钩子保持其新鲜。由于克劳德代码仅向状态栏命令提供官方的 `rate_limits` — 而状态栏不是插件贡献的组件 — 请在 `~/.claude/settings.json` 中添加以下内容：
```json
{
"statusLine": {
"type": "command",
"command": "node \"/path/to/claude-usage-plugin/capture-statusline.js\""
}
}
```
> **Windows 用户：** 在路径中使用**正斜杠** — `C:/Users/you/claude-usage-plugin/capture-statusline.js` — 克劳德代码使用 POSIX 样式的单词拆分，其中反斜杠被破坏。
**已经使用状态栏？** 不要替换它 — 将 stdin 链接到两个命令，或将 `captureStatusline()` 调用从 `official.js` 折叠到您现有的脚本中。
重启克劳德代码，发送一条消息以触发钩子，然后 `check_usage` 将报告您的实时官方数字。
### 可选：工具使用后钩子
`usage-hook.js` 是一个工具使用后钩子，在每次工具调用后运行，并在克劳德的上下文中注入简短的使用情况摘要。要启用它，请在 `~/.claude/settings.json` 中添加：
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "node \"/path/to/claude-usage-plugin/usage-hook.js\""
}
]
}
]
}
}
```
此钩子**不施加任何限制**，并且永不会阻止工具调用 — 它始终退出 0。它纯粹是信息性的。
## 设计笔记
- **官方，非估计值。** 数字是克劳德代码自己的 `rate_limits`，与状态栏中显示的数据相同。
- **无限制。** 插件仅记录和报告 — 无阈值，无阻止，无副作用。
- **最小令牌。** 两个无参数工具返回紧凑的 JSON；状态栏钩子仅是运行时的，仅在模型的上下文中添加内容。
- **无网络调用。** `index.js` 仅读取本地 JSON 文件。无 cookie，无爬取，无 Cloudflare 挑战。
- **原子写入。** 捕获写入到 pid 唯一临时文件并重命名到位，因此并发读取永远不会看到半写入的文件。
- **永不清空状态栏。** 捕获和格式化失败在 `capture-statusline.js` 中被默默地吞咽。
## 许可证
[MIT](LICENSE)
