前言¶
DSH 的理念是「一切皆插件」，用量查询这种小事通常也该由插件来做，而不是手动开一个网页再切回来。用 OpenCode Go 的人有个反复出现的动作：写代码时想知道 5 小时额度还剩多少，于是切到 Console，记下数字，再切回来。这个插件的定位就是把这个动作折回 Harness 界面里——输入框底栏放一个徽标，设置页放一节，别的什么都不加。
下面介绍的插件由 Jfreey 维护，在社区目录 SkillHub 上归在「客户端」分类，目前靠插件管理器指向仓库安装。它只做一件事：显示 OpenCode Go 的用量。没有多余界面，没有额外依赖，不需要构建步骤。
这是什么¶
一句话定位：一个轻量的 DSH 客户端插件，把 OpenCode Go 的三类额度（5 小时滚动、周、月）显示在 composer dock 的徽标和 Settings 页面里。
它解决的问题是「用量可见性」。插件从 https://opencode.ai/zen/go/v1/usage 读取上面三档额度，用你已经保存的密钥鉴权，把百分比和重置时间渲染成进度条。密钥不进浏览器，页面只收到百分比和重置时间。
维护者：Jfreey。许可证：MIT，仓库内随附 LICENSE 文件。
核心功能¶
输入框底栏徽标。 composer dock 里显示一个紧凑的 Go [进度条] 5h 13% 徽标，位置在 Turn-count 徽标的左侧。进度条可以关掉，跟踪的级别（5h / week / month）可配置，也可以按定时轮换。
展开面板。 鼠标悬停、点击或聚焦徽标，展开的面板里是三个额度各一条进度条，加上已用百分比、重置倒计时、手动刷新按钮，以及进度条、级别、轮换的开关。这里的改动保存在浏览器本地。
设置页。 Settings → OpenCode Go 一节包含三张卡片。打开时先读缓存、不额外查一次上游，之后每 60 秒自动刷新，按钮用于立刻取一次。
中英双语。 UI 跟随 Harness 应用语言，插件注册了中文和英文两套词条。访问读数走宿主只读路由，且面板会提示读数与 Console 最多差 1 个百分点。
安装与启用¶
仓库本身就是可安装的 bundle（package.json 里声明了 dsh.bundle）。在 Harness 的插件管理器里指向该目录或该 GitHub 仓库即可，没有需要手敲的安装命令。安装后刷新页面：底栏出现 Go 徽标，设置里出现「OpenCode Go」一节。
它依赖 DeepSeek Harness 0.2.x，具体用到的是 dsh.client、ctx.slots、ctx.locale 三个契约。版本不够的话先升级 Harness。
安装前建议把仓库里这几个文件读一遍，尤其是 index.js、client.js 和 cordis.patch.yml——patch 文件会改宿主代码，值得确认改动范围再启用。许可证是 MIT，商用和二次分发都允许。
配置¶
插件配置写成插件行的形式：
- id: opencode-go-usage
name: 'dsh-opencode-go-usage'
config:
apiKeyEnv: OPENCODE_GO_API_KEY # 凭据引用名
# apiKey: oc_sk_... # 也可以直接写死，不推荐
path: /dsh-opencode-go/usage # Host 只读路由
cacheSeconds: 60 # 宿主缓存秒数，也是底栏刷新周期
dock: true # 底栏徽标总开关
bar: true # 徽标里的进度条
level: rolling # 跟踪级别：rolling (5h) | weekly | monthly
rotate: false # 级别轮换显示
rotateSeconds: 5 # 轮换间隔（最小 2 秒），仅 rotate: true 时生效
level 也接受 week/w/周 与 month/m/月；无法识别时回落到 rolling。任何配置改动都要重载 Harness（重启应用或重新启用该 bundle）才生效。
密钥从哪里来¶
插件不需要你手动写密钥，它按下面的顺序逐次解析：
- 插件行里的
config.apiKey（显式填写时优先）。 - 凭据服务里的
config.apiKeyEnv引用，默认名是OPENCODE_GO_API_KEY——也就是「设置 → 模型」里为opencode-go保存的那把密钥。 - 同名进程环境变量。
所以只要模型页里已经有 opencode-go 的凭据，插件装上就能直接读数。
刷新与缓存¶
不同界面对同一条路由的行为不同：
| 场景 | 请求 | 行为 |
|---|---|---|
| 底栏徽标 | GET /dsh-opencode-go/usage |
每 60 秒拉一次；宿主缓存未过期时直接返回缓存 |
| 面板「刷新」 | GET …?refresh=1 |
跳过缓存，强制向上游查询 |
| 设置页打开 | GET …?cache=1 |
有缓存就用缓存（哪怕过期），只有从未读过时才查上游 |
| 设置页保持打开 | GET /dsh-opencode-go/usage |
每 60 秒自动刷新，与底栏同一节奏 |
| 设置页「刷新」 | GET …?refresh=1 |
立刻查一次上游 |
凭据变化（credentials/reference-updated 事件）会清空缓存，换 key 后下一次请求就用新凭据，不会继续显示上一个账号的数字。
HTTP 路由¶
Host 提供一条只读路由 GET /dsh-opencode-go/usage，?refresh=1 强制刷新，?cache=1 只读缓存。返回体的例子：
{
"ok": true,
"fetchedAt": "2026-11-04T12:40:00.000Z",
"credentialSource": "stored",
"dock": true,
"display": { "bar": true, "level": "rolling", "rotate": false, "rotateSeconds": 5 },
"servedFromCache": true,
"stale": false,
"usage": {
"rolling": { "status": "ok", "percent": 12.5, "resetsAt": "2026-11-04T17:33:21.000Z" },
"weekly": { "status": "ok", "percent": 4.1, "resetsAt": "2026-11-09T00:00:00.000Z" },
"monthly": { "status": "ok", "percent": 1.2, "resetsAt": "2026-12-04T12:23:50.000Z" }
}
}
失败时返回 { "ok": false, "error": { "code": "NO_KEY|UNAUTHORIZED|FORBIDDEN|TIMEOUT|NETWORK|UPSTREAM|SHAPE", "message": "…" } }，据此可以区分是没配密钥、鉴权失败还是上游异常。
适用场景与注意¶
适合两类人：一是不想切窗口查限额、希望用量一直可见的人；二是想给别的 provider 做同类用量插件、需要一个可参考实现的人——这个插件面很小，入口只有 dock 和 Settings 两处，代码量也少。
需要注意的几点：
- 插件以当前 dsh 进程的权限运行，能读到进程环境变量和凭据库里的引用。安装前检查源码与许可证，确认你愿意让插件拿到这些权限。
- 路由是只读、同源的 GET，不经过 Harness 的浏览器登录闸门。Harness 默认只监听回环地址；一旦你把它暴露到局域网或隧道，这条路由也会随之可达。
- 进度条颜色使用主题 token（
--dsw-alias-*），明暗主题都适用，不需要额外适配。 - 读数就是接口返回的整数百分比，与 Console 最多差 1 个百分点，插件面板上已注明。
目录页：https://www.skillhub.cn/plugins/Jfreey/dsh-opencode-go-usage
GitHub：https://github.com/Jfreey/dsh-opencode-go-usage
