dsh-plugin-opencode-usage
OpenCode Go 用量百分比悬浮面板:在 DeepSeek Harness Web 会话窗口左下角显示滚动/每周/每月用量百分比与重置时间。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-plugin-opencode-usage@0.1.3
Plugin Opencode Usage 以 dsh-plugin-opencode-usage 发布，当前版本为 0.1.3。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
OpenCode Go 订阅用量悬浮面板：在 DeepSeek Harness Web GUI 会话窗口左下角显示订阅额度使用情况。
shell.bottom 底部行时相对会话列底边定位Esc 与点击面板外部关闭OPENCODE_GO_API_KEY」的可操作提示，而不是笼统的「暂时不可用」浅色 / 深色（DeepSeek Harness 0.2.1-rc.5）：
| 浅色 | 深色 |
|---|---|
| 浅色面板 | 深色面板 |
DSH Web 浏览器
│ 1. 点击会话窗口左下角按钮（同源请求，自动带 Harness 登录 cookie）
▼
GET /plugins/opencode-usage/stats
│
▼
DSH Host 插件
│ 2. Host/Origin + 登录校验（ctx.connection.requestRejection，0.2.1+）
│ 3. ctx.credentials.resolve("OPENCODE_GO_API_KEY")
│ 4. GET https://opencode.ai/zen/go/v1/usage
│ Authorization: Bearer <api-key>
│ 5. 透出 percent / remainingPercent / resetsAt
▼
返回 JSON，由 React 面板渲染
官方接口只返回 percent 与 resetsAt：
{
"usage": {
"rolling": { "status": "ok", "percent": 30, "resetsAt": "..." },
"weekly": { "status": "ok", "percent": 19, "resetsAt": "..." },
"monthly": { "status": "ok", "percent": 9, "resetsAt": "..." }
}
}
插件直接展示官方 API 返回的百分比，不做金额换算。上游只回部分窗口时，插件只渲染返回了的窗口，不会因为少一个窗口就整体报错。
路由状态码：
| 状态码 | 含义 |
|---|---|
200 | { ok: true, periods: { rolling?, weekly?, monthly? } } |
424 | { ok: false, code: "credential_not_configured" }：没有配置 API key |
500 | { ok: false, code: "usage_query_failed" }：上游失败（上游细节只写进 host 日志） |
401 / 403 | Harness 连接栅栏拒绝（未登录 / 非受信 Host） |
405 | 只接受 GET / HEAD |
dsh-plugin-opencode-usage/
├── cordis.patch.yml # bundle patch: 把插件插入 profile host 组合
├── lib/
│ ├── index.js # Host 半: 订阅额度 API 查询 + HTTP 路由
│ └── client.js # Client 半: 会话窗口左下角悬浮按钮 + 面板
├── scripts/
│ └── verify-dsh.mjs # 端到端验证: 临时 profile 启动真实 dsh 并检查路由/客户端 bundle
├── tests/
│ ├── host.test.mjs # Host 半契约单测（node:test，无依赖）
│ └── client.test.mjs# Client 半契约单测（桩 __ModuleLoader__ / React / document）
├── LICENSE
├── package.json # dsh.bundle / dsh.client / 兼容性元数据
└── README.md
不同模型的额度金额不同（例如 V4 Pro 月度 $15、V4 Flash 月度 $30， 整体月上限 $60），因此插件只展示官方 API 返回的百分比，不做金额换算。
| 窗口 | 官方接口字段 | 说明 |
|---|---|---|
| 滚动用量 | usage.rolling | 5 小时滚动窗口百分比 |
| 每周用量 | usage.weekly | 每周窗口百分比 |
| 每月用量 | usage.monthly | 月度窗口百分比 |
官方 API 只返回 percent 与 resetsAt；插件同时给出 remainingPercent = 100 - percent。
命令行 Web（dsh web）：
dsh plugin --profile web add dsh-plugin-opencode-usage
桌面端（DeepSeek Harness 桌面应用，profile 名 desktop）：
dsh plugin --profile desktop add dsh-plugin-opencode-usage
也可以从 GitHub 仓库安装（无构建步骤，lib/ 即源码），或从本地目录安装：
dsh plugin --profile web add github:jiekesu967/dsh-plugin-opencode-usage
dsh plugin --profile web add /path/to/dsh-plugin-opencode-usage
安装后 dsh plugin 会自动写入该 profile 的 dependencies，并把
dsh-plugin-opencode-usage 追加到 dsh.profile.bundles。重启 DSH
并刷新页面后，会话窗口左下角会出现独立的“OpenCode Go 用量”悬浮入口。
本地开发时也可以不发布：把本仓库软链到 profile 的
node_modules/下， 并把dsh-plugin-opencode-usage加进dsh.profile.bundles。npm run verify演示了这种做法。
在 profile 的 cordis.patch.yml 覆盖 opencode-usage 条目：
- id: opencode-usage
config:
# Harness credentials 文件中保存 API key 的变量名
credentialRef: OPENCODE_GO_API_KEY
# OpenCode Go 订阅接口
apiBaseUrl: https://opencode.ai/zen/go/v1
# host 成功结果缓存时间
cacheMs: 30000
credentialRef 必须是合法的 POSIX shell 标识符；非法值会退回默认的
OPENCODE_GO_API_KEY 并在 host 日志里留一条警告，而不是静默失败。
在 ~/.dsh/.credentials.yaml 中确认存在：
OPENCODE_GO_API_KEY: sk-...
也可以通过 DSH Web 的 Models / Credentials 设置页写入。
0.2.1 起的优先级变化：Harness 的 credentials 解析顺序在 0.2.1 这一线 改成了「托管文件优先，环境变量其次」（0.1.5 / 0.2.0 是环境变量优先）。 如果同一个变量名同时出现在
~/.dsh/.credentials.yaml和进程环境里， 0.2.1 会使用文件里的值。插件本身不受影响，但排查「key 不生效」时值得先看一眼。
入口注册在 shell.overlay，绝对定位于 AppFrame 的会话中心列左下角：
12px、底部 16px12px392px，右侧/顶部超出视口时自动回退ResizeObserver 监听会话中心列，侧边栏展开/收起、详情面板开关、窗口缩放时实时跟随0.2.1 布局适配（这几条是 0.1.3 新增的）：
[data-slot="main"] 槽位出口的父节点定位，取不到才回退到旧的
AppFrame.children[1]，不再依赖「第几个子节点」这种未公开顺序shell.bottom 底部行（状态栏/检查器占位）时，按钮改为相对会话中心列底边
定位，不会掉进底部行里插件在 package.json 里声明它支持哪一版 Harness。
1. 范围声明（真正的门禁） —— Harness 启动预检与 dsh plugin add 只读 engines.dsh：
"engines": {
"node": "^22.19.0 || >=24.0.0",
"dsh": ">=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0"
},
"peerDependencies": {
"@deepseek-ai/cordis": "^4.0.2",
"@deepseek-ai/dsh-client-locale": ">=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0",
"@deepseek-ai/dsh-client-ui-renderer": "同上",
"@deepseek-ai/dsh-credentials": "同上",
"@deepseek-ai/dsh-host-webserver": "同上"
}
2. 逐版本兼容表 —— 市场 / DSH STORE 读它（Harness 运行时不读，纯发布元数据）：
"dsh": {
"compatibility": {
"dshReleases": {
"0.1.5-rc.1": "compatible",
"0.1.5-rc.2": "compatible",
"0.2.0-rc.2": "compatible",
"0.2.1-rc.5": "compatible" // 0.1.3 起在 Linux + Node 22/24 上实测
},
"dsh": ">=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.2.1-0 || >=0.2.1-rc.1 <0.2.2-0"
}
}
| DSH 版本 | 状态 | 说明 |
|---|---|---|
0.2.1-rc.5 | compatible | 当前安装版本，0.1.3 起逐条实测（含真实 dsh 启动 + 浏览器面板） |
0.2.0-rc.2 | compatible | 桌面端验证版本（0.1.2） |
0.1.5-rc.1 / 0.1.5-rc.2 | compatible | 原始验证版本 |
0.2.2-alpha.x | 未声明 | 尚未实测；等 smoke test 通过后再加 |
为什么范围要写成三段：node-semver 只在范围内某个比较符与该版本的
major.minor.patch元组一致、且自身带预发布标签时，才放行预发布版本。>=0.1.5-rc.1 <0.3.0-0这类「看起来覆盖一切」的写法在0.2.0/0.2.1元组上没有这样的比较符，会把0.2.0-rc.2、0.2.1-rc.5静默排除； 而>=0.2.1-rc.1 <0.3.0-0又会把未实测的0.2.2-alpha.x一并放进来。 所以每条发布线单独写一段，上界统一用<x.y.z-0拒绝该行的预发布。
0.2.1-rc.5 下插件不需要重写渲染逻辑：用到的每个 seam 都还在。0.1.3 在这台
Linux + Node 22/24 环境上逐条实测（真实 dsh web 启动、真实浏览器渲染）：
| 用到的 seam | 0.2.1-rc.5 结果 |
|---|---|
window.__ModuleLoader__.load({ id, factory })、exports.apply/inject | 不变（bundle id 仍须等于包名） |
dsh.client.platform/inject、exports["./client"] | 不变；inject 只是加载顺序提示 |
shell.overlay 列表槽位、data-shell-overlay | 不变；outlet 包装为 [data-slot="shell.overlay"] |
AppFrame 子节点顺序（旧 frame.children[1]） | 仍成立，但改成 [data-slot="main"] 定位（更稳） |
ctx.slots.inject / ctx.slots.register({ name, id, order, locale }) | 不变；列表槽位仍要求 id |
props.t(key, vars)、ctx.locale.register(ns, { zh, en }) | 不变；locale 描述符仍驱动 t |
22 个 --dsw-* / --ds-* CSS token | 全部存在（含暗色主题），无死 token |
webServer.register({ kind: "exact", path, handler }) | 不变；重复 (kind, path) 仍抛错 |
ctx.credentials.resolve(ref) → { value, source } | 不变；未配置返回 undefined（不抛错） |
ctx.inject(["webServer"], cb) + ctx.effect | 新增用法，替代旧的 internal/service 轮询 |
ctx.connection.requestRejection(req) | 新增：给非 /api 路由补 Host/Origin + cookie 鉴权 |
shell.bottom 底部行、[data-composer-card] | 新增布局；入口按上面第 6/7 条避让 |
无需构建步骤，lib/ 就是发布产物。仓库自带两层验证：
npm test # Host/Client 契约单测（node:test，50 个用例，无第三方依赖）
npm run verify # 端到端：临时 DSH_HOME + 真实 dsh 启动，检查
# 1) 页面 boot graph 与 client bundle 里有本插件
# 2) /plugins/opencode-usage/stats 的 JSON 契约
# 3) 不带登录 cookie 的请求被 401 拒绝
npm run verify:mock # 同上，外加本地 mock 上游：验证 200 + 三个窗口的真实数据链路
npm run verify:verbose
npm run verify 需要本机已安装 dsh（0.2.1-rc.5 上验证通过）。它会自己创建并
清理临时 DSH_HOME，不会碰你正在用的 profile，也不依赖 ~/.dsh 里的凭据。
desktop、命令行 web）；headless 下
不注册路由，面板也不出现GET /plugins/opencode-usage/stats 不在 Harness 的 /api 前缀下：
ctx.connection.requestRejection 补上 Host/Origin 栅栏与
登录校验，未登录 / 非受信 Host 一律 401/4030.2.1-rc.5（Linux + Node 22/24 实测），逐版本兼容表补上 0.2.1 线0.2.2-alpha.x 一起放进来ctx.connection.requestRejection，补上 Host/Origin 栅栏与
cookie 鉴权；只接受 GET/HEAD（405 + Allow）ctx.inject(["webServer"], …) + ctx.effect，webserver 热重载后
不会悄悄丢路由；去掉从未存在过的 httpServer 别名424 + credential_not_configured，面板给出设置提示shell.bottom 底部行与贴底输入框卡片，避免遮挡输入框控件tests/（50 个用例）与 scripts/verify-dsh.mjs（真实 dsh 启动验证）MIT