dsh-opencode-go-usage

DSH（DeepSeek Harness）插件：OpenCode Go 套餐用量查询。

通过 opencode_usage 工具实时查询 opencode.ai 官方用量 API，返回滚动 5 小时 / 每周 / 每月三个计费窗口的用量百分比与重置时间。一次查询 = 一次 HTTP 请求，不消耗任何模型额度。

功能

• opencode_usage agent 工具：查询三个窗口的用量百分比、状态、重置时间（本地时区展示）
• 设置页「opencodego」卡片：DSH 设置 → 插件 → opencodego，可直接填入自己的 API key（secret，不显示明文、留空不修改），并调整 key 来源 / 超时 / 代理等参数，保存即时生效，无需改任何文件
• 侧边栏「用量」可视化面板（客户端插件，无需构建步骤的手写 bundle）：
  • 三条进度条（滚动 5 小时 / 每周 / 每月），按用量分级着色（<60% 绿 / 60-85% 黄 / ≥85% 红）
  • 显示百分比、状态、重置倒计时、重置时刻；⟳ 手动刷新，打开面板自动刷新；面板右上角 ✕ 随时关闭
  • 与 SSH / 任务看板面板互斥（共享 dsh-panel-activate 事件与激活属性，自动互踢）
• key 自动解析，通常零配置：
  1. 插件设置里的 apiKey（secret）
  2. 环境变量 OPENCODE_GO_API_KEY / OPENCODE_API_KEY
  3. opencode 自己的认证文件 ~/.local/share/opencode/auth.json 中的 opencode-go 条目（与 opencode CLI 共用，登录 opencode 后即有）
• 系统提示词自动向 agent 宣告插件存在与用法
• 兼容 API 返回格式变化（新旧字段名都解析）

安装

方式一：从 npm 安装（已发布）

dsh plugin --profile web add @dsh-ltctfer/dsh-opencode-go-usage

方式二：本地路径安装（开发调试）

dsh plugin --profile web add "@dsh-ltctfer/dsh-opencode-go-usage@file:E:/dsh插件/dsh-opencode-go-usage"

然后在 profile 的 cordis.patch.yml（~/.dsh/profiles/web/cordis.patch.yml）追加：

- insert:
    - id: opencode-go-usage
      name: '@dsh-ltctfer/dsh-opencode-go-usage'

重启 DSH Web GUI（或 dsh web 进程）后生效。

配置项（设置页 / 组合条目 config）

设置页「插件」标签下有 opencodego 卡片（侧边栏「用量」面板同款插件的设置入口），可直接填入 API key 与各参数，保存即时生效；也可在组合条目 config 里配置：

| 字段 | 默认值 | 说明 | | --- | --- | --- | | apiKey | 无 | 字面 API key（sk-...），可选（卡片里填入即写此字段，留空不修改） | | apiKeyId | opencode-go | auth.json 中存放订阅 key 的条目名 | | authFile | ~/.local/share/opencode/auth.json | opencode 认证文件路径 | | baseURL | https://opencode.ai/zen/go/v1/usage | API 端点 | | timeoutMs | 15000 | 请求超时（毫秒） | | proxy | 无（直连） | 代理 URL，如 http://127.0.0.1:7890 | | forceIPv4 | false | IPv6 路由黑洞的网络可设 true 强制 IPv4 | | announceToAgent | true | 是否在系统提示词中宣告插件 | | enabled | true | 总开关 |

使用

面板：重启 GUI 后，侧边栏会出现「用量」入口，点击打开可视化面板，面板右上角 ✕ 可关闭（再点侧边栏「用量」重新打开）。

对话：直接对 agent 说「查一下 opencode go 用量」，或要求调用 opencode_usage 工具。输出示例：

window   |  used | status | resets in  | resets at
---------|-------|--------|------------|-----------------------------
rolling  |    0% | ok     |       1h 5m | 2026/8/14 18:21:21
weekly   |   26% | ok     |       2d 3h | 2026/8/17 08:00:00
monthly  |   15% | ok     |      23d 7h | 2026/9/7 15:52:27

架构

浏览器（GUI）                          宿主（dsh web 进程）
┌──────────────────────────┐        ┌──────────────────────────────┐
│ lib/client.js（手写 bundle）│  fetch │ lib/routes.js                 │
│  ├ 侧边栏「用量」入口（DOM 自愈） │ ─────▶ │  GET /api/dsh-opencode-     │
│  ├ 用量面板（React 进度条）    │  JSON  │  go-usage/usage（回环围栏）    │
│  └ 设置卡片（opencodego）    │ ─────▶ │  GET/POST /api/dsh-opencode- │
│                          │  JSON  │  go-usage/settings（回环围栏）  │
│                          │        ├ lib/usage.js（key 解析+API 调用）│
│ opencode_usage 工具       │ ◀───── │ lib/tools.js                  │
└──────────────────────────┘  工具   └──────────────────────────────┘

• 客户端 bundle 是 window.__ModuleLoader__.load({id, factory}) 格式的手写文件，宿主经 /plugins/@dsh-ltctfer/dsh-opencode-go-usage/client.js 原样服务，无需打包器
• 面板样式用壳的 --dsw-alias-* 主题变量，明暗主题自适应
• 宿主侧多注册了一个只读 JSON 路由（dsh.client manifest + exports["./client"] 声明）

设置卡片的原理

DSH 设置页「插件」标签的官方设置表单走 settingsScope 服务，但宿主 apiproxy 只对硬编码白名单里的 namespace 开放（agent-loop / shell / web-search-deepseek 等），第三方插件的 namespace 一律返回「设置段不可用」。因此本插件自建了一个loopback settings bridge：

• 宿主侧注册 GET/POST /api/dsh-opencode-go-usage/settings（与用量路由同一回环围栏：仅 127.0.0.1 + 同源标记放行），GET 返回脱敏后的 namespace 视图（schema / value / revision / writable），POST 把 path ops 交给官方 settings.mutate 落盘（校验、revision 锁、持久化与官方表单完全一致）；
• 客户端「opencodego」卡片直接读写该路由，不经过官方 settingsScope；保存后宿主侧 onChange 会即时重载工具/面板的配置快照；
• 设置路由独立于 enabled 开关注册——即使插件被关闭，设置页卡片仍可打开并重新启用。

说明与限制

• 用量数据来自官方 API，反映真实计费窗口，可能有短暂延迟
• 查询本身不消耗 opencode 额度
• API key 从本机认证文件读取，不跨网络传输密钥以外的任何数据
• 若自定义了 opencode 的认证文件路径（XDG_DATA_HOME 等），用 authFile 配置指向它

开发与测试

# 在插件仓库内修改代码后，同步已安装副本（pnpm 对 file: 依赖是拷贝）：
dsh plugin --profile web install

# 冒烟测试（需在 profile 目录下运行，以解析 @deepseek-ai/* 依赖）：
cp test/ocg-smoke.mjs test/client-smoke.mjs ~/.dsh/profiles/web/
cd ~/.dsh/profiles/web
node ocg-smoke.mjs       # 宿主侧：模块形状 / key 解析 / 真实 API / 工具 / 路由
node client-smoke.mjs    # 客户端：bundle 注册 / CSS 注入 / 挂载 / 入口点击 / 互踢 / 清理

致谢

感谢 linux.do 社区——DSH 插件开发与交流的宝贵阵地。

License

MIT