前言¶
在 DSH（DeepSeek Harness）里长时间用 OpenCode Go 时，额度分散在 rolling、weekly、monthly 等多个时间窗口，上游接口又不宜直接在浏览器里带密钥调用。换页、开新会话时也不方便对照「今天还能用多少、有没有超速」。下面介绍的插件由 knight02-bit 维护，在 Web GUI 输入框下方常驻一条额度条，并在同源代理前提下把密钥留在宿主侧。
这是什么¶
dsh-opencode-go-usage 是 DSH Web 侧插件（package.json 中 dsh.client.platform 为 web），向对话 composer 注入底部 dock。它从宿主暴露的同源路径 /opencode-go-usage 拉取 JSON，展示三个窗口的剩余额度百分比；单击可浮出配速卡，提示按周、按月摊平后「每天 / 每周该花多少」以及今日、本周仍可用比例。社区目录分类为 admin-security；GitHub 仓库当前星标为 0，许可证为 MIT，版本 0.1.0，需要 Node.js ≥ 20。
核心功能¶
三窗口额度条¶
- rolling：滚动 5 小时窗口（上游定义）。
- weekly、monthly：周、月窗口。
上游返回的是已用百分比，插件统一换算为剩余；rate-limited 显示为「已耗尽」。进度条颜色：剩余 ≥50% 为绿，≥20% 为黄，其余为红。悬停某一窗口可查看剩余额度、重置时间、已用与时间进度对比。
配速卡¶
单击整条额度条（或聚焦后按 Enter / 空格），在 dock 上方浮出配速卡，不改变行高。内容包括：
- 每天 ≤X% 周额度、每周 ≤Y% 月额度（按 7 天与当月实际周数摊平）。
- 今日可用、本周可用（按当前剩余量重新摊平）。
- 与时间进度对比的 ▲ / ▼（±6 个百分点阈值；超速有风险，富余表示额度尚多）。
rolling 窗口上游未给出窗口长度，不做配速（pace.rolling.lengthMs = null）。
刷新与缓存¶
- 客户端：约 60 秒自动轮询；窗口重获焦点时补拉；浮层内「刷新」或双击整条可手动刷新。
- 宿主：30 秒缓存、5 秒最小请求间隔、并发去重。
安全与同源¶
上游 GET https://opencode.ai/zen/go/v1/usage 的 CORS 预检实测有问题，浏览器无法直接带 Authorization 请求。插件在 Node 侧（index.js）代拉上游，在同源 /opencode-go-usage 返回不含密钥的 JSON；client.js 仅访问页面相对 base 下的该路径。路由对跨站、Origin、socket 远端有约束，响应体只有百分比等用量字段。
主题使用 --dsh-alias-* token，文案走 Client locale（中/英）。dependencies 为空，发布包主要包含 index.js、client.js、cordis.patch.yml、locale 与图标等少量文件。
安装与启用¶
装好后刷新一次 GUI 页面，输入框下方应出现额度条。
方式一：本地目录 link 装入 profile（README 推荐）¶
先将仓库放到本机目录（README 示例使用 git clone 获取源码）。在 DSH 中把该目录装入当前 profile：
会话内（Agent 侧）：
plugin_manager→action: install_bundletarget指向插件目录的绝对路径- 返回
application: applied即生效
或使用 CLI（若已装过同一包，先 remove_bundle / remove）：
dsh plugin --profile <profile> add link:/abs/path/to/dsh-opencode-go-usage
方式二：预构建 tarball¶
Release 提供按 files 字段打包的 tarball（无需 node_modules、无需构建）：
https://github.com/knight02-bit/dsh-opencode-go-usage/releases/latest/download/dsh-opencode-go-usage.tgz
插件市场（如 dsh-market）可能优先展示该产物；与源码 link 安装方式产物一致。具体 tarball 安装步骤以 DSH 当前 profile / 市场文档为准。
配置密钥¶
密钥不会出现在路由响应中。宿主按下列优先级解析：
1. JSON 文件（$DSH_HOME/opencode-go-usage.json 或 ~/.dsh/opencode-go-usage.json）：
{ "apiKey": "oc_xxx", "orgId": "wrk_xxx" }
orgId 可选，会以 x-opencode-org-id 头发送（团队/工作区账号）。
2. 环境变量：OPENCODE_GO_API_KEY、OPENCODE_GO_ORG_ID
3. DSH 凭据库：~/.dsh/.credentials.yaml 中的 OPENCODE_GO_API_KEY
注意：通过 ctx.credentials.resolve(ref) 得到的是 { value, source } | undefined，不要对对象直接 String()，否则上游可能返回 401。
未配置密钥、密钥被拒（401/403）、上游不可达、窗口已耗尽等情况，界面会有对应提示（见 README 状态表）。
典型用法¶
- 完成安装并配置
apiKey（按需配置orgId）。 - 打开 DSH Web GUI，在 composer 下方查看 rolling / weekly / monthly 剩余百分比。
- 单击额度条展开配速卡，对照「每天 / 每周上限」与「今日 / 本周可用」，结合 ▲▼ 判断是否用得太快。
- 需要最新数据时：单击浮层「刷新」，或双击整条；也可等待自动轮询与焦点补拉。
展开状态保存在 localStorage['dsh-opencode-go-usage:expanded']。再点整条、点浮层外或按 Esc 可关闭浮层。
宿主侧调试示例（README）：
curl "http://127.0.0.1:<port>/opencode-go-usage?refresh=1"
开发自检：
npm run check
适用场景与注意¶
适合谁：在 DSH Web 界面常驻使用 OpenCode Go、希望一眼看到多窗口剩余额度，并想按周/月节奏控量的开发者或管理员。
运行权限：插件以当前 DSH 进程权限运行，宿主侧会持有 API 密钥并访问外网用量接口。安装前应阅读仓库源码与 MIT 许可证，确认密钥存放路径与凭据库策略符合你的环境要求。
生态说明：DSH 理念是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。本插件归类 admin-security，侧重用量可见性与密钥不进入浏览器。
结尾¶
dsh-opencode-go-usage 把 OpenCode Go 的三段额度与配速建议收进 DSH 底部一条 dock，用宿主代理解决 CORS 与密钥外露问题。目录页：https://www.skillhub.cn/plugins/knight02-bit/dsh-opencode-go-usage；源码与完整说明：https://github.com/knight02-bit/dsh-opencode-go-usage。
