前言¶
DeepSeek Harness（DSH）的「上下文已用」圆环只显示当前会话的 token 消耗，无法直接看到 opencode Go 套餐的用量。这款插件在窗口角落挂一个浮窗，实时展示 Rolling / Weekly / Monthly 的使用情况与剩余量，用满即报错，避免超出套餐。
插件定位¶
rshh0520/opencode-go-usage 是 DSH 的 admin-security 类插件，由维护者 rshh0520 开发。它以浮窗形式监控 opencode Go 套餐的用量，支持实时倒计时、换 Key 自动跟随、主题适配。
核心功能¶
三窗口用量展示¶
浮窗垂直排列三个窗口：Rolling usage、Weekly usage、Monthly usage。每行包含「标签 + 百分比徽章 + 重置倒计时 + 进度条」。
实时倒计时与预警¶
倒计时根据上游的 resetsAt 现算：不足 1 天显示 3h 8m，超过 1 天显示 4d 20h。某个窗口达到上限（status: rate-limited 或 percent ≥ 100）时，徽章与进度条转为错误色。
浮窗可拖动¶
按住卡片主体拖动即可换位置（位移小于 4px 视为点击）。位置存进 localStorage，刷新后保持。窗口变小时自动拉回可视区域。
查询间隔可调¶
支持 30s / 1m / 2m / 5m / 10m，改完立即生效并持久化。
API Key 管理¶
面板里默认显示脱敏值（如 sk-AGs…Fz6W），可查看明文、一键复制，并标出 Key 来自哪个环境变量、DSH 凭据的哪一层或哪个文件。换 Key 后，下一次轮询自动使用新值，无需重启。
主题跟随¶
颜色全部取自 DSH 主题 token，明暗主题自动适配。
失败不闪屏¶
已经成功取过数，后续某次请求失败时保留旧读数，只把错误挂到悬停提示里。
安装¶
前置条件：已安装 DeepSeek Harness（桌面版或 dsh CLI），并且 opencode 已登录 —— 也就是 auth.json 里存在 opencode-go 凭据，或已设置对应环境变量。
本仓库是一个 DSH bundle：package.json 里声明了 dsh.bundle.patch，插件自带的 cordis.patch.yml 会把自身 entry 插进 cordis 组合树。因此不需要手工编辑 profile 的 cordis.patch.yml，也不会被宿主覆盖。
桌面版¶
在 DSH 桌面版的插件管理界面里，以本仓库目录作为本地来源安装。识别到 dsh.bundle 后，安装器会自动把它登记进该 profile 的 dsh.profile.bundles。安装后重启应用。
命令行¶
dsh plugin --profile <profile> add "link:/绝对路径/dsh-opencode-go-usage"
因为声明了 dsh.bundle，dsh plugin add 会自动把它写进该 profile package.json 的 dsh.profile.bundles，同样不用改 cordis.patch.yml。
把仓库放在 profile 目录之外，通过
link:或安装器引入。不要直接拷进 profile 目录。
使用方法¶
浮窗¶
安装后浮窗默认出现在窗口右下角，每 60 秒自动刷新一次。它挂在 DSH 的帧级浮层座席 shell.overlay 上，与会话无关 —— 没有打开任何会话时同样显示。
拖动¶
按住卡片主体拖动即可换位置（位移小于 4px 视为点击，不会误拖）。位置存进 localStorage，刷新后保持。想回到默认位置，清掉 dsh.opencodeGoUsage.pos 即可。
设置面板¶
点右下角的齿轮按钮展开：
| 区域 | 操作 |
|---|---|
| 查询间隔 | 点 30s / 1m / 2m / 5m / 10m 中的一项，立即重建轮询定时器 |
| API Key | 点「查看」加载 → 默认显示脱敏值（如 sk-AGs…Fz6W）→ 点「显示」切明文 → 点「复制」写入剪贴板（成功后按钮短暂变为「已复制」）→ 点「刷新」重新读取（宿主换过 Key 时面板会自动跟进，失败时这里显示「重试」） |
| 来源 | 显示 Key 来自哪个环境变量、DSH 凭据的哪一层，或哪个 auth.json |
悬停卡片可看到各窗口的剩余百分比、上次刷新错误与操作提示。
配置¶
API Key 从哪来¶
每次刷新都重新解析（不缓存 Key），按顺序取第一个命中的：
- 环境变量
OPENCODE_GO_API_KEY - 环境变量
OPENCODE_API_KEY - DSH 托管的凭据（
ctx.credentials→$DSH_HOME/.credentials.yaml里的OPENCODE_GO_API_KEY）—— 在 DSH 设置页填 / 换 Key 写的就是这里 - 环境变量
OPENCODE_AUTH_CONTENT（整份auth.json的 JSON 字符串） %USERPROFILE%\.local\share\opencode\auth.json里的["opencode-go"]（key，oauth 凭据则取access）
第 3 项让「在 DSH 里换 Key」变成自动的：DSH 的托管凭据文档不会写回进程环境，只走这条 seam 才能读到新值，所以插件每次取数都 resolve 一次，无需重启。第 5 项是 opencode 自己的凭据文件位置，也可以用 XDG_DATA_HOME 重定位。只要 opencode 已登录、或在 DSH 里配过 Key，通常无需任何额外配置。
面板里「来源」一行会写明当前用的是哪一层（例如 OPENCODE_GO_API_KEY（DSH 凭据 / file） 或 …\opencode\auth.json）。
换了 Key 之后多久生效¶
| 改 Key 的位置 | 是否自动生效 | 说明 |
|---|---|---|
DSH 设置页 / 凭据存储（.credentials.yaml） |
✅ 自动，无需重启 | 下一次轮询就用新值，面板里显示的 Key 也会跟着重取 |
opencode 重新登录改写 auth.json |
✅ 自动 | 同上（只要环境变量那一层没有更高的 Key 压着） |
OPENCODE_GO_API_KEY / OPENCODE_API_KEY 环境变量 |
⚠️ 需重启 DSH | Node 的 process.env 是启动快照，改系统环境变量对已运行进程无效 |
生效延迟 = 宿主 30s 数据缓存 + 页面轮询间隔（默认 60s，可在面板改到 10m）。旧 Key 失效后，卡片会保留最后一次读到的数字（不闪空白），悬停可在提示里看到 401。
环境变量¶
| 变量 | 作用 |
|---|---|
OPENCODE_GO_API_KEY |
首选 API Key |
OPENCODE_API_KEY |
备用 API Key |
OPENCODE_AUTH_CONTENT |
直接以 JSON 字符串提供 auth.json 内容 |
XDG_DATA_HOME |
重定位 opencode/auth.json 所在目录 |
浏览器侧持久化¶
localStorage 键 |
内容 |
|---|---|
dsh.opencodeGoUsage.pos |
浮窗位置 {x, y} |
dsh.opencodeGoUsage.intervalMs |
查询间隔（毫秒） |
适用场景¶
需要持续监控 opencode Go 套餐用量的开发者。插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
常见问题¶
浮窗一直显示「opencode Go usage 不可用」
取数从未成功过。先确认 curl -H "Authorization: Bearer $KEY" https://opencode.ai/zen/go/v1/usage 能返回 200。
提示 401
Key 无效或已失效。
提示 403
Key 本身有效，但该账号没有 opencode Go 套餐（Zen 与 Go 共用同一个 workspace key，所以这个错误是「有 key、无套餐」）。
点「查看」显示读取失败
「查看 Key」依赖宿主侧的 /key 路由。如果你刚更新过插件，重启一次 DSH 让新的宿主代码生效 —— 宿主侧模块不像前端 bundle 那样热更新。重启后仍失败可以点「重试」。
不想让明文 Key 进入页面
删掉 lib/index.js 里 /key 分支即可，此时面板会显示读取失败而不是崩溃。
结尾¶
这款插件通过浮窗形式解决了 opencode Go 套餐用量监控的问题，支持实时倒计时、换 Key 自动跟随、主题适配，适合需要持续监控用量的开发者。更多细节与源码见插件目录页与 GitHub 仓库。
