verneuil/dsh-opencode-go-usage ↗★ 1
dsh-opencode-go-usage
提供官方余额与OpenCode Go用量悬浮窗及设置 适合需要实时监控DeepSeek官方余额和OpenCode Go订阅额度的用户。
同名包的其他仓库
安装
$
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:verneuil/dsh-opencode-go-usage说明文档
阅读完整 README ↗OCG 余量查询 · dsh-opencode-go-usage
中文 · English
一个 DeepSeek Harness 客户端插件：把 DeepSeek 官方余额 与 OpenCode Go 订阅的三个用量窗口 —— 5 小时（rolling）/ 本周 / 本月 —— 合并到同一个悬浮胶囊里，另带一个同名设置页。
An unofficial DeepSeek Harness plugin that shows your DeepSeek balance and OpenCode Go usage (5-hour / weekly / monthly) in one floating pill, with click-to-refresh, drag-to-snap and a light-rail refresh animation.
截图
前四张为 DSH 桌面版真机截图（浅色 / 深色）；最后一张为状态与配色的示意渲染（跑动中的光轨与封环很难截到稳定帧）。
| 浮窗 · 浅色 | 浮窗 · 深色 |
|---|---|
 |  |
| 设置页 · 浅色 | 设置页 · 深色 |
|---|---|
 |  |
| 形态与配色总览（示意：刷新中 / 成功封环 / 失败 / 三档配色 / 关掉余额后变窄） |
|---|
 |
特性
- 一屏两套数据：DeepSeek 官方余额（
¥金额）+ OpenCode Go 三窗口用量；点击浮窗即刷新（同时拉取，一侧失败不影响另一侧）。 - 三颗圆环：环心就是已用百分比（不显示
%），
GET https://api.deepseek.com/user/balance # DeepSeek 官方余额 Authorization: Bearer
用量接口返回 `{ usage: { rolling, weekly, monthly } }`，每个窗口含 `status` / `percent`（**已用**百分比）/ `resetsAt`；余额接口返回 `balance_infos[]`（优先取 CNY 行）。
宿主半侧负责拉取与解析（两把 Key 都不出宿主进程），客户端只读宿主写入的配置投影。
**Key 来源**（两侧各自独立，按优先级）：
1. 插件设置页里的「手动 Key」（写入本行配置持久化，客户端视图自动脱敏）；
2. DSH 凭据库 —— OpenCode Go 取 `OPENCODE_GO_API_KEY`（其次 `OPENCODE_API_KEY`），DeepSeek 取 `DEEPSEEK_API_KEY`。
## 构型
| 部分 | 位置 | 说明 |
| ------------ | ------------------ | ---------------------------------------------------------------------------------------------------- |
| Bundle 清单 | `package.json` | `dsh.bundle.patch` + `dsh.client`（platform web、immediately）+ `icon` + `locale/*.json` 显示元数据 |
| Loader patch | `cordis.patch.yml` | 插入一行 `id: opencode-go-usage`（本行 id 同时是设置表单的 ns） |
| 宿主半侧 | `index.js` | `export const Config`（schemastery）+ `apply(ctx, config)`；拉取、解析、写回快照、自动刷新 |
| 客户端半侧 | `client.js` | `window.__ModuleLoader__` 惰性工厂；只 `require('react')`，注册进 `shell.overlay`（浮窗）与 `settings.section`（设置页） |
## 配置项
设置页覆盖了常用项；下表中的字段也可以直接改本行 patch 的 `config`。
| 字段 | 说明 |
| ------------------------------------------------------------ | ----------------------------------------------- |
| `apiKey` | OpenCode Go 的手动 API Key（secret）。留空则自动使用 DSH 凭据库 |
| `deepseekApiKey` | DeepSeek 的手动 API Key（secret）。留空则自动使用 DSH 凭据库 |
| `refreshMinutes` | 自动刷新间隔（分钟，默认 5）；一轮同时刷新余额与用量 |
| `widgetVisible` | 浮窗显示开关 |
| `showBalance` | 浮窗上是否显示 DeepSeek 官方余额（默认开） |
| `widgetAnchorX/Y`、`widgetOffsetX/Y` | 浮窗锚定（拖动时由客户端写入，无需手改） |
| `refreshRequest` | 手动刷新计数（点击浮窗时由客户端递增） |
| `refreshTick` | 宿主每轮拉取前自增的「更新中」信号（客户端只读，用来点亮边框流光） |
| `keyStatus`、`keyHint`、`usageError`、`lastUpdated`、`usage` | OCG 用量的派生快照（宿主写入，客户端读取） |
| `balanceKeyStatus`、`balanceKeyHint`、`balanceError`、`balance` | DeepSeek 余额的派生快照（宿主写入，客户端读取） |
## 稳健性设计
- **只占官方为浮层保留的席位** `shell.overlay`（`replaceRisk: none`，点击穿透层，条目自行 opt-in 指针事件）；用自有 `id` 注册，属于「加在既有条目旁边」，不替换任何官方条目。
- **不遮蔽任何官方 UI**：不注册 `conversation.composer.dock`，不复刻官方组件。
- **样式只用主题令牌** `--dsw-alias-*`：令牌改名最多让外观退化，不会让渲染崩溃；无阴影、无模糊、无字面色值。
- **不引入任何 Harness 客户端包**（如 `dsh-client-ui-primitives`）：这类包随时会变，且普通 JS 插件没有类型检查；浮窗的控件全部自写。
- **宿主 API 契约自检**：启动时校验本插件实际用到的宿主契约，不匹配时打印可读警告并安全跳过，而不是抛 `TypeError` 让整条目静默不激活。
- **配置即通道**：宿主把派生快照写进本行 Config 的 volatile 字段，客户端经 `remote.settings.describe()` 读取；写回在 HMR 事务之外提交（避免 `HMR transactions cannot be nested`）。
- **失败不清空数据**：拉取失败时保留最后已知用量（并做 3s / 10s 抗抖动重试），不会因为一次网络抖动把进度条清成 `--` 或把空值持久化。
- 未取到 Key 时按阶梯重试（3/8/20/40/60/120 秒），手里有成功快照时容忍三次失手，避免启动瞬间误判「未配置」。
## 已知限制与免责声明
- **非官方插件**：本项目与 DeepSeek、OpenCode 官方**无任何隶属关系**；两个接口都不是官方长期冻结的公开契约，上游结构大改时可能失效（解析器已对「剩余百分比 / 已用金额与额度 / 距重置秒数」等常见变体做容错，失败时宿主会在 `usageError` 里给出可读文本）。
- **Key 只在本机使用**：宿主半侧直接请求上述两个接口，不经过任何第三方；设置页里填写的手动 Key 存在本机插件配置中，界面上只显示脱敏掩码（如 `sk-****5590`）。
- **网络抖动**：跨境 HTTPS 偶发超时属正常，此时浮窗保持**最后已知数值**、边框转告警色，宿主按 3/8/20/40 秒重试，成功后自动恢复。
- **界面语言**：浮窗与设置页支持**中英双语**，随 DSH 语言设置切换；接口层返回的**错误详情**（如 401/403、返回结构异常）目前仍为中文。
- **使用风险自负**：本软件按 MIT 许可「原样」提供，不附带任何担保。
## 许可
[MIT](https://github.com/verneuil/dsh-opencode-go-usage/blob/4ad47ff1291d1e3d66d6bee8e4ce7b8e9e18911a/LICENSE) © 2026 verneuil
## 反馈
问题与建议请开 [Issue](https://github.com/verneuil/dsh-opencode-go-usage/issues)，欢迎 PR。版本变更见 [CHANGELOG.md](https://github.com/verneuil/dsh-opencode-go-usage/blob/4ad47ff1291d1e3d66d6bee8e4ce7b8e9e18911a/CHANGELOG.md)。
## 使用
- **点击浮窗** = 立即刷新余额 + 用量（也可以等自动刷新）。
- **拖动浮窗** = 移动位置，松手自动吸附；「重置到右下角」按钮可一键回到默认位置。
- **设置页** = `设置 → 插件 → OCG 余量查询`。
## 配置项
设置页覆盖了常用项；下表中的字段也可以直接改本行 patch 的 `config`。
| 字段 | 说明 |
| ------------------------------------------------------------ | ----------------------------------------------- |
| `apiKey` | OpenCode Go 的手动 API Key（secret）。留空则自动使用 DSH 凭据库 |
| `deepseekApiKey` | DeepSeek 的手动 API Key（secret）。留空则自动使用 DSH 凭据库 |
| `refreshMinutes` | 自动刷新间隔（分钟，默认 5）；一轮同时刷新余额与用量 |
| `widgetVisible` | 浮窗显示开关 |
| `showBalance` | 浮窗上是否显示 DeepSeek 官方余额（默认开） |
| `widgetAnchorX/Y`、`widgetOffsetX/Y` | 浮窗锚定（拖动时由客户端写入，无需手改） |
| `refreshRequest` | 手动刷新计数（点击浮窗时由客户端递增） |
| `refreshTick` | 宿主每轮拉取前自增的「更新中」信号（客户端只读，用来点亮边框流光） |
| `keyStatus`、`keyHint`、`usageError`、`lastUpdated`、`usage` | OCG 用量的派生快照（宿主写入，客户端读取） |
| `balanceKeyStatus`、`balanceKeyHint`、`balanceError`、`balance` | DeepSeek 余额的派生快照（宿主写入，客户端读取） |