前言¶
在 DSH 里使用 opencode-go 模型时，订阅往往同时受多个时间窗口约束：5 小时滚动窗口、本周、本月。仅靠终端或外部控制台，很难在写代码、改会话时一眼看到剩余比例和重置时间。下面介绍社区客户端插件 dsh-opencode-quota-panel（维护者 Flem83）：把三条额度读数嵌进 DSH Web UI，并在 Host 侧用同源接口拉取用量，密钥不下发到浏览器。
这是什么¶
dsh-opencode-quota-panel 是 DeepSeek Harness（DSH）的 客户端（web） 插件，npm 包名与插件 id 均为 opencode-quota / dsh-opencode-quota-panel。它在侧边栏提供「OpenCode 额度」页面，并在对话输入框模型选择区域左侧显示额度徽章；数据来自 OpenCode Zen 的只读接口 GET https://opencode.ai/zen/go/v1/usage，由 Host 用与 opencode-go provider 相同的凭证 ref OPENCODE_GO_API_KEY 代为请求，浏览器只访问同源路由 /opencode-quota/v2/usage 拿到归一化后的百分比。
插件本身不含凭证或订阅数据；页面展示的是当前 Host 上该 API Key 对应账号的额度。许可证 MIT，engines.dsh 要求 >=0.2.1-rc.5。
核心功能¶
额度页（侧边栏「OpenCode 额度」）¶
打开后上方为三枚环形表盘（5h 滚动、本周、本月），环长表示剩余额度，环心为剩余百分比；颜色随剩余比例变化（低于 50% 偏黄、低于 20% 偏红）。每个环下有两行：重置倒计时、预计用到 X%（按整个周期已过时间的平均消耗外推，不做突发速率外推；若预测会超额则数字变红）。
视觉中心下方是常驻明细表（不靠悬浮）：各窗口的已用 %、平均速率、精确重置时间；表下用两行说明速率口径与估算假设（窗口刚开始时不估算；本月按 30 天估算时会在说明中注明）。窗口刚开始、暂无可靠预测时速率显示 —。
页内有一行「输入框徽章」开关，持久保存在 Host 侧，浅色/深色主题下均可见。
输入框旁的额度徽章¶
挂在 conversation.input.right：三段读数形如 ● 5h 94% │ ● 周 93% │ ● 月 33%，点击跳转额度页。悬停或键盘聚焦时，在 body 上弹出小卡（三枚迷你环 + 倒计时 + 预计用到 X%），按 Esc、移出或滚动关闭。
仅当当前会话会用到 opencode-go 时显示：已记录的选择（next/lastUsed）或 Host 目录默认模型属于 opencode-go；否则完全隐藏，避免用其他模型时误以为额度正在被消耗。
刷新与状态提示¶
- 每 5 分钟自动刷新；额度页标题行右侧图标可立即拉数（绕过 Host 缓存并重新积累预测样本）。
- 侧边栏图标带状态点，颜色取「最紧张」窗口，不必打开页面也能感知松紧。
- 失败时显示一行错误条（含原因与刷新按钮）；加载中为虚线占位。
Host 侧能力与预测口径¶
Host 半（index.js）负责凭证解析、请求、缓存、预测，并通过 ctx.effect 注册只读路由。响应中每个窗口含 percent（已用 0–100）、resetsAt、forecast 等；剩余 = 100 − percent。
预测使用整周期均值：rate = percent / 已过时间，projected = percent + rate × 剩余时间，不使用近期样本速率，以免连续使用几小时后外推失真。reliable 为 false 时不显示「预计用到 X%」；assumedSpan: true 表示周期长度为假设值（本月按 30 天）。
凭证经 DSH 凭证服务解析 OPENCODE_GO_API_KEY，兜底读同名环境变量；密钥仅在 Host 进程内使用，不写日志、不进响应体。
安装与启用¶
需要先在「设置 → 模型」里配置 OPENCODE_GO_API_KEY（与 opencode-go provider 共用），否则页面会提示未找到凭证。
从 npm 安装（推荐，插件页可检查更新）
在 DSH 网页打开「插件 → 添加插件」，输入包名：
dsh-opencode-quota-panel
或在命令行：
dsh plugin --profile <profile> add dsh-opencode-quota-panel
从 GitHub 安装（不经 npm）
dsh plugin --profile <profile> add "github:Flem83/dsh-opencode-quota-panel#v1.0.0"
开发时从本地目录安装
dsh plugin --profile desktop add "<本仓库的绝对路径>"
安装后刷新 DSH 网页（或重启桌面端），即可看到侧边栏条目与输入框区域徽章（徽章默认开启，可在额度页关闭）。
典型用法¶
- 安装插件并完成
OPENCODE_GO_API_KEY配置后，在侧边栏进入「OpenCode 额度」，查看三环与明细表。 - 在对话界面选用
opencode-go相关模型时，观察输入框左侧三段徽章；需要详情时点击徽章或侧边栏入口。 - 若不想在输入框显示徽章，在额度页关闭「输入框徽章」；偏好写在
$DSH_HOME/opencode-quota/settings.json（{ "badge": true/false }），也可通过GET/POST /opencode-quota/v2/prefs读写。删除该文件恢复默认（开启）。
可选配置：在 profile 的 cordis.patch.yml 中覆盖插件行，例如更换 credentialRef、调整 cacheTtlMs（默认 60000）、或修改 endpoint / prefsEndpoint：
- id: opencode-quota
name: 'dsh-opencode-quota-panel'
config:
credentialRef: OPENCODE_GO_API_KEY
endpoint: /opencode-quota/v2/usage
prefsEndpoint: /opencode-quota/v2/prefs
cacheTtlMs: 60000
更新：npm 安装可在插件详情页更新，或执行 dsh plugin --profile <profile> add dsh-opencode-quota-panel@<新版本>；GitHub / 本地路径安装需卸载后按新 tag 或路径重装。
适用场景与注意¶
适合谁：长期在 DSH Web 里用 OpenCode Go、需要同时盯 5h/周/月三个窗口、又不想把 API Key 暴露给浏览器脚本的开发者。
运行与信任：插件以当前 DSH Host 进程权限运行，会向 opencode.ai 发起只读 GET，不消耗额度、不改订阅状态。安装前建议阅读仓库源码与 MIT 许可证；社区目录 skillhub.cn 与 GitHub 由维护者发布，与 DeepSeek / 幻方无官方从属关系。
已知边界（README 原文）：
/zen/go/v1/usage为 Zen 内部接口，官方未承诺稳定性；无法解析时页面提示错误，不崩溃。- 预测是整周期均值的线性外推，不反映「接下来几小时是否会猛用」；窗口刚开始（不足 1 分钟或不足周期 2%）不给预测。
- 未覆盖 OpenCode Zen 预付费余额（需 console cookie，暂未支持）。
结尾¶
经过上面的步骤，你可以在 DSH 网页里集中查看 OpenCode Go 的三段订阅额度、重置时间与粗粒度期末预测，并在选用 opencode-go 时通过徽章快速跳转。更多说明与 Issue 见维护者仓库。
- 目录页：https://www.skillhub.cn/plugins/Flem83/dsh-opencode-quota-panel
- GitHub：https://github.com/Flem83/dsh-opencode-quota-panel
