[upstream statusline lines]
Usage: ▓▓▓▓░░░░ 40% 🕗1h27m·5h · ▓▓░░░░░░ 20% 🕔4d3h·7d # Quota
Balance: ¥110.00 · $3.5 # Balance
# CreditGauge — 快速上手指南
> **1 分钟** （只需要4条命令）从零装好 CreditGauge，*无需配置* \*，让 Claude Code 状态栏显示你的外接Provider的 **token 套餐用量 / 剩余额度**（或 **账户余额**）。想要每个字段、每个模块的完整说明，请看 [MANUAL.md](./MANUAL.md)。
```
/plugin marketplace add cwf818/creditgauge
/plugin install creditgauge@creditgauge
/reload-plugins
/creditgauge:install
```
- 第1条命令需要多点耐心，有时候会报错，不是 CreditGauge 原因，多试几次或重启再试试看。
- \* 已内置 Minimax (Quota类型) 和 DeepSeek (Balance类型) 的套餐端点，**安装完直接可用**。其他 provider（kimi、moonshot、z.ai、私有网关）可通过插件接入。
- 为什么只有 Minimax 和 DeepSeek ？我只订阅了 Minimax，顺便往 DeepSeek 账户充了点值。
- 前几天开通了kimi，写了个插件，目前已退款无法持续验证，所以放在了 `query_plugins` 目录（如果验证可用，再移入内置插件目录）。不过这个套餐端点需要 access_token 才能访问，不能开箱即用，有点遗憾。请看 [HOW_TO_CREATE_A_PLUGIN.md](./HOW_TO_CREATE_A_PLUGIN.md) 说明。
- 如果你正在使用 `claude-hud` 或 `ccstatusline`，CreditGauge 会在它们的状态栏下方渲染自己的行，不破坏原有布局。/creditgauge:install 和 /creditgauge:uninstall 会正确处理共存方案。
- CreditGauge 绝不会收集你的 token，也不会把它们写入日志或落盘。运行过程中，CreditGauge 只会把 token 作为 Bearer 头传给 provider 的套餐端点。详情请看 [SECURITY.md](./SECURITY.md)。
## 插件的插件
> CreditGauge 本身是支持 **插件的插件**（the Plugins of Plugin, PoP）架构的。你可以通过动态导入的方式接入其他 provider 的套餐端点，只需要一个 *.js 文件和一段 provider 节点配置，便可实现一个新 provider 的支持。从v1.1.8开始，为了更方便使用，CreditGauge 还提供了一个 **npx creditgauge plugin** 子命令，用于安装、删除不同的 provider 套餐插件。以 `opencode go` 为例（主要是我自己换到了这个），安装命令如下：
```
# 列出所有可用插件
npx creditgauge plugin list
# 安装 opencode 插件
npx creditgauge plugin add opencode
# opencode 登录认证，会安装一个约 300MB 左右的 playwright + chromium
# 之后会弹出浏览器窗口让你登录opencode账号，登录后会自动获取cookie并
# 写入 ~/.claude/plugins/creditgauge/credentials
npx creditgauge plugin auth opencode
# 查询用量（不带 provider 查全部已配置的，带 provider 只查指定那个）
npx creditgauge status
npx creditgauge plugin status opencode
```
## 目录
0. [效果](#0-效果)
1. [简介](#1-简介)
2. [安装](#2-安装)
3. [基本配置](#3-基本配置)
4. [插件（接入自定义 provider）](#4-插件接入自定义-provider)
5. [安全与协议](#5-安全与协议)
6. [延伸阅读](#6-延伸阅读)
---
## 0. 效果
一行紧凑的状态栏（simple预设），随 `ANTHROPIC_BASE_URL` 自动切换内容：
Usage: ▓▓▓░░░░░ 38% 🕖47m·5h · ▓▓▓░░░░░ 39% 🕓4d47m·7d
Remain: ░░░▓▓▓▓▓ 62% 🕖47m·5h · ░░░▓▓▓▓▓ 61% 🕓4d47m·7d
Balance: ¥110.00 · $3.5
- **Quota**（如 MiniMax）：5 小时窗口 + 每周窗口，分段进度条 + 彩色百分比 + 重置倒计时。
- **Balance**（如 DeepSeek）：账户余额，多币种以 ` · ` 拼接。
- 5 段配色（256 色 SGR）：亮绿 / 深绿 / 黄 / 橙 / 红，随用量升高（余量降低）变红。
**simple 预设**（与已安装的 `claude-hud` 协同效果）——最小布局，单独一行 Quota：
**standard 预设**——context、内存、git、quote（可设置外链）、session / project 实时用量、 5h / 7d 周期用量，实时 Quota / Balance 行：
---
## 1. 简介
CreditGauge 是一个 **provider 无关** 的 Claude Code 状态栏插件，专注于外接 provider 特有的 **quota / balance** 数据，外加从 Claude Code stdin 读取的轻量用量统计。
> Claude 套餐的额度信息通常包含在 stdin 数据中，没订阅过，因此无法确认验证。现有 `claude-hud` / `ccstatusline` 已经可以显示。不过它们是 **内置 provider 绑定** 的，CreditGauge 则更多考虑 **外接 provider** 的额度实时显示，避免在心流工作状态中可能受到 provider 额度限制而被迫中断。当然，CreditGauge 也会在合适的时机加入对 Claude 套餐的额度信息显示的支持。
它按 `ANTHROPIC_BASE_URL` (settings.json) 决定渲染什么，因此同一个插件对任何受支持 provider 的套餐端点都能用，**无需按 provider 重装，也无需繁琐配置**。当前内置支持：
| `ANTHROPIC_BASE_URL` | 渲染行 | 数据来源 |
| ------------------------------------ | ------------------------ | -------------------------------- |
| `https://api.minimaxi.com/anthropic` | `Usage: …` / `Remain: …` | `/v1/token_plan/remains`（MiniMax） |
| `https://api.deepseek.com/anthropic` | `Balance: …` | `/user/balance`（DeepSeek） |
| 其他（原生 Anthropic、OpenRouter…） | （隐藏） | — |
对未识别的 provider，插件会**隐藏 Quota / Balance 行**，并原样透传上游状态栏（如 `claude-hud` / `ccstatusline`）。
CreditGauge 设计了可扩展性极好的**插件的插件** （the Plugins of Plugin, PoP）架构，通过动态导入的方式实现更多 provider 的支持，只需要一个 *.js 文件和一段 provider 节点配置，便可实现一个新 provider 的支持。如果你愿意，可以创建一个自定义插件（ESM 文件）来接入其他 provider 的套餐端点，**无需 fork**。完整 ABI、填充契约、覆盖解析顺序、内置插件和仓库现有的外部插件目录（包括 kimi 的凭证获取、copilot-api 的 localhost 端点），以及用 provider 参数设定显示条件的方法，都在 [HOW_TO_CREATE_A_PLUGIN.md](./HOW_TO_CREATE_A_PLUGIN.md)。也欢迎分享其他 providers 的插件，或者提 PR 把它们放进内置目录。
## 2. 安装
**第一步 —— 装插件**（这是一个单插件市场）：
```
/plugin marketplace add cwf818/creditgauge
/plugin install creditgauge@creditgauge
/reload-plugins
```
> `/reload-plugins` 必不可少：让加载器识别新命令。忘了这步是安装后「command not found」的最常见原因。
**第二步 —— 接入 `settings.json`**：
```
/creditgauge:install
```
这会给当前 `settings.json` 打补丁（默认用户级；加 `--project` 走项目级）。若 `statusLine.command` 仍指向本插件的包装器，则为空操作（基于命令字符串匹配，不依赖旧版 `_creditgauge_managed` 标记）。
**卸载**（自包含清理，即使缓存已被清也能用；不动 `env` 里的 token；默认会保留插件数据，加 `--completely` 参数完全卸载，包括配置文件、自定义插件目录和缓存目录）：
```
/creditgauge:uninstall
```
**其他命令**：`/creditgauge:clean`（清理旧 `.bak.` 备份）、`/creditgauge:clean-cache`（删除旧版本缓存目录，只留最新）。
**或者使用 `npx creditgauge`**（无需走 marketplace）：启动交互式 TUI，可视化选择安装/卸载/清理/查看诊断。也支持静默模式——`npx creditgauge install`、`npx creditgauge uninstall` 等。
---
## 3. 基本配置
配置文件路径（启动时加载一次）：
- **Unix**：`~/.claude/plugins/creditgauge/config.json`
- **Windows**：`%USERPROFILE%\.claude\plugins\creditgauge\config.json`
一份含全部字段的参考：[config.example.json](./config.example.json)——复制到上面的路径后编辑即可。
### 最常改的几项
**显示模式**——默认 `remaining`（行首 `Remain:`，显示剩余百分比）。切成已用模式：
```json
{ "display": "used" }
```
`used` 模式行首变 `Usage:`，显示已用百分比，进度条彩色段代表已用部分。（`display` 仅对 Quota 有效；DeepSeek 的 `Balance:` 没有百分比可翻转。）
**配色阈值**——5 段配色的分界：
```json
{
"thresholds": {
"percentBands": [60, 70, 80, 90],
"balanceBands": [5, 10, 20, 50]
}
}
```
**刷新缓存 TTL**——一次成功 API 响应缓存多久（默认 60 秒）：
```json
{ "cacheTtlMs": 60000 }
```
**布局模板**——用 `statuslineTemplate` + `lineTemplates` 拼你想要的行，`lineTemplates` 用于使用内置可视化模块配置基础模板，`statuslineTemplate` 用于使用内置可视化模块和 `lineTemplates` 配置状态栏的呈现模板。
`statuslineTemplate` 提供了4种快速的预设： `simple`、`compact`、`standard`、`solo`，可以直接在config.json中设置使用。
`lineTemplates` 提供了 `quota`、 `balance`、 `model_info`、 `context_info`、 `plugin_info`、 `mem_info`、 `git_info`、 `tickline`、 `scopeline`、 `periodline`、 `quote` 等预设内置模板，用户可以通过 `m_template` 模块使用，也可以自定义更多模板。
CreditGauge 提供了配置非常灵活的配置方法，模板、模块目录与 inline-args 语法见 [MANUAL.md §2](./MANUAL.md#2-top-level-schema) 与 [§8 模块参考](./MANUAL.md#8-module-reference)。
---
## 4. 插件（接入自定义 provider）
内置只带两个 provider（`minimax` / `deepseek`）。要接入 **kimi、moonshot、z.ai、私有网关** 等其他 provider，**无需 fork**——往指定目录 （`~/.claude/plugins/creditgauge/query_plugins/`） 丢一个 ESM 文件，并配置 provider 节点即可静默覆盖内置链路。
最短路径（三步）：
```bash
# 1. 建插件目录（跨缓存滚动稳定）
mkdir -p ~/.claude/plugins/creditgauge/query_plugins/
# 2. 放插件文件，导出 default { fetchAccountCredit(authenticationKey, ctx) }
# 返回 Partial 或 Partial，host 会补全规范形状
# 3. 在 config.json 的 providers. 里登记 BASE_URL_COMPARED_TO 等字段
```
其中 `` 必须与 `config.json` 里 `providers.` 的键一致。
插件最好是单个 ESM 文件，这样避免处理复杂的导入依赖关系，导出 `default { fetchAccountCredit(authenticationKey, ctx) }`，返回一个包含 `short`、 `mid`、 `long` (建议的 key，内置预设已使用；如果采用其他自定义的 key， 则需要同时修改m_windowQuota / m_countdown 模块的 `term` 参数)的 JSON对象：
```js
export default {
async fetchAccountCredit(authenticationKey, ctx) {
// 1. 用 authenticationKey 调用 provider 的套餐端点，获取 JSON 数据
// 2. 解析 JSON，返回 Partial 或 Partial，供 CreditGauge 渲染
return {
short: {
windowId: string | null; // 用于m_sum*统计模块枚举，可选 5h / 7d / 30d 等dhms格式的字符串或任意字符串
label: string | null; // 自由字符串，可选，显示在倒计时后面
startAt: number | null; // epoch-ms / UTC iso8601
endAt: number | null; // epoch-ms / UTC iso8601
intervalMs: number | null; // epoch-ms （三选二）
remainingPercent: number | null; // 0..100
usedPercent: number | null; // 0..100; （二选一）
remainingQuota: number | null; // absolute units
usedQuota: number | null; // absolute units
limitQuota: number | null; // absolute units （三选二）
},
mid: null, // 参考short，如果没有 mid 数据，可以返回 null
long: null, // 参考short，如果没有 long 数据，可以返回 null
};
};
}
```
完整 ABI、填充契约、覆盖解析顺序、内置插件目录（kimi 的凭证获取、copilot-api 的 localhost 端点），以及用 provider 参数设定显示条件的方法，都在 [HOW_TO_CREATE_A_PLUGIN.md](./HOW_TO_CREATE_A_PLUGIN.md)。
---
## 5. 安全与协议
- 插件复用 `process.env.ANTHROPIC_AUTH_TOKEN` 调用 provider 端点，**不引入新环境变量**。
- token **仅**用作单次 GET/POST 的 `Bearer` 头，**从不**被日志记录、写入 stdout、出现在错误信息中或落盘。
- 卸载脚本本地运行、无 API 调用，**不触碰** `settings.json` 的 `env` 块（含你的 token）。
- 完整策略见 [SECURITY.md](./SECURITY.md)。发现漏洞请提 `security` 标签的 issue，**勿在报告中附真实 token**。
**协议**：MIT，见 [LICENSE](./LICENSE)。
---
## 6. 延伸阅读
- [**README.md**](./README.md) —— 完整功能说明、命令、组合方式、诊断日志、缓存机制。
- [**MANUAL.md**](./MANUAL.md) —— 详尽配置参考：顶层 schema、provider 条目、预设、fragment、inline-args 语法、全部 `m_*` 模块目录、配方。
- [**HOW_TO_CREATE_A_PLUGIN.md**](./HOW_TO_CREATE_A_PLUGIN.md) —— 接入自定义 provider 的插件 ABI、填充契约、覆盖解析。
- [**CHANGELOG.md**](./CHANGELOG.md) —— 逐版本变更历史（破坏性变更、新模块、移除的别名、schema 升级）。
- [**SECURITY.md**](./SECURITY.md) —— 安全策略与 token 处理细节。
*除本文档外，其他文档大部分由AI模型生成，仅做了少量人工校对。*