dsh-api-meter

Readme

# dsh-api-meter

> 多供应商 API 用量 / 余额监控插件，用于 DeepSeek Harness (DSH)。

实时展示你已接入的所有 LLM / 视觉提供方的余额、额度窗口与重置时间，按 Provider 自动发现、按 API Key 去重、按用量直观可视化。

## 特点

- **动态 Provider 发现**：从 `llm-pi-ai` / `llm-deepseek` / `vision-toolkit` 配置命名空间 + pi-ai 目录 baseUrl 自动收集，无需手工登记
- **按 API Key 去重**：同一账户的多个入口（如 LLM provider + 视觉 provider 共用同一 key）只显示优先级最高的那张卡
- **余额适配器**：内置 DeepSeek (`/user/balance`)、MiniMax (`/v1/token_plan/remains`)、Moonshot (`/v1/users/me/balance`)；通用 JSON 路径可自定义
- **用量进度条（Kimi 风格）**：fill = 已用量（空条 = 剩余多，更直观）；"已用 X% · 剩余 Y% · X 小时后（YYYY-MM-DD HH:mm）"消除歧义
- **双入口**：设置 → 插件 → **API 用量** tab，对话区顶部视图环也有**API 用量**页签（和插件商店同位）
- **Agent 工具**：`api_meter` —— 在对话中问"我的余额多少"即可自动查询
- **后台刷新**：可配置间隔（默认 5 分钟），缓存 + 失败降级，单 provider 失败不影响其他
- **安全**：API Key 仅在服务端经 `ctx.credentials.resolve` 解析，绝不出现在浏览器响应中

## 安装

```bash
dsh plugin --profile web add "github:BigAdam-h/dsh-api-meter"
```

然后重启 `dsh web`，刷新浏览器。在设置 → 插件 → **API 用量** 标签或对话区顶部视图环即可看到。

## 配置

默认在 patch 层提供最小配置（provider 枚举 + 5 分钟刷新）。如需新增自定义通用 meter，编辑 `~/.dsh/profiles/web/cordis.patch.yml`：

```yaml
- id: api-meter
  name: dsh-api-meter
  config:
    refreshIntervalMinutes: 5
    requestTimeoutMs: 15000
    backgroundRefresh: true
    genericMeters:
      - provider: my-gateway
        displayName: My Gateway
        balanceUrl: https://gateway.example.com/v1/balance
        balancePointer: data.balance
        apiKeyEnv: MY_GATEWAY_KEY
```

## 适配器已验证

| Provider | 端点 | 支持 |
|---|---|---|
| DeepSeek | `GET {base}/user/balance` | ✅ |
| MiniMax | `GET {origin}/v1/token_plan/remains` | ✅（国内 + 国际 anthropic-protocol 路由） |
| Moonshot/Kimi | `GET {origin}/v1/users/me/balance` | ✅ |
| New API / Sub2API 中转 | 通用 balanceUrl + balancePointer | ✅ |
| 其他 | 通用 balanceUrl + balancePointer | ✅ |

## 兼容性

- DeepSeek Harness `web` profile
- `@deepseek-ai/dsh >= 0.1.0-rc.6`
- DSH 客户端 Cordis 限制：媒体类（视觉/音频）block 会被 DSH 丢弃，文本/结构化结果正常显示

## License

MIT