前言¶
在 DSH 里用 opencode-go 路由跑模型时，额度往往分散在供应商 Console 或外部页面里，会话过程中很难一眼看到「5 小时 / 本周 / 本月」还剩多少、何时重置。切换路由或 key 后，还要自己对照配置是否生效。
dsh-model-usage 是维护者 kabarryo 发布的客户端类 DSH 插件（社区目录：kabarryo/dsh-model-usage）。它在会话输入框下方的状态区增加一枚与内置统计 pill 样式一致的额度 pill，汇总展示 opencode-go 订阅的三段用量百分比；点开可看进度条、重置时间与倒计时。数据走 Host 侧 GET {baseURL}/usage，与对话共用同一把 API Key，浏览器侧只拿到百分比快照。
这是什么¶
插件全名 dsh-model-usage（npm 包名同号，当前版本 0.1.2，MIT）。定位是「DSH 模型额度 pill」：显示 opencode-go 订阅的 5 小时 / 本周 / 本月用量与重置时间。
需要事先说明范围：名称虽叫 model usage，当前只实现了 opencode-go 订阅（含同一套 /usage 端点的 Go / Go Plus 计划）。DeepSeek 官方、第三方中转、BYOK 等没有该端点时，插件不报错，pill 直接不显示。其它订阅在 README 中标注为「随缘开发」，不做承诺；若第三方也有等价用量端点，可通过配置增加 meter。
界面与数据口径¶
收起态示例（与 README 一致）：
5H 26% · W 23% · M 25%
点开明细层后，三个窗口各有一条进度条、百分比、重置时间与倒计时；底部显示数据新鲜度并提供刷新按钮。进度条按用量分五档：绿（0–69%）、黄（70–79%）、橙（80–89%）、红（90–99%）；到 100% 或端点拒绝时在 pill 图标位与行首出现 ⚠。
Host 调用 GET {baseURL}/usage，典型响应形状如下：
{"usage":{
"rolling":{"status":"ok","percent":26,"resetsAt":"2026-10-27T04:37:33Z"},
"weekly": {"status":"ok","percent":23,"resetsAt":"2026-11-02T00:00:00Z"},
"monthly":{"status":"ok","percent":25,"resetsAt":"2026-11-22T03:26:20Z"}}}
口径要点：
- 三个窗口对应 5 小时（rolling 滚动窗）/ 本周（weekly，每周一 00:00 UTC）/ 本月（monthly，订阅周年日，非自然月 1 号）；端点无「日」窗口，故 pill 用
5H · W · M。 - 返回为订阅级数字，不区分模型；弹层会说明「订阅级用量，不区分模型」。
- API Key 仅在 Host 进程使用；快照路由
/api/dsh-model-usage仅接受本机回环请求。
安装与启用¶
环境要求（来自 README）：DSH 0.2.x（Web 或桌面 profile 均可），Node 20+，且已配置 OPENCODE_GO_API_KEY（与模型调用同一把 key）。
在 DSH 会话中让 agent 执行 bundle 安装（路径改为你本机克隆或下载后的绝对路径）：
plugin_manager install_bundle target=/绝对路径/dsh-model-usage
等价手工步骤：
- 编辑
~/.dsh/profiles/<profile>/package.json：在dependencies增加"dsh-model-usage": "link:/绝对路径/dsh-model-usage"，在dsh.profile.bundles追加"dsh-model-usage"。 - 在该 profile 目录执行
pnpm install。 - 重启对应 DSH；Web 客户端需刷新页面。
验收：确认本机快照可用，例如（端口换成当前 GUI 端口）：
curl http://127.0.0.1:<当前 GUI 端口>/api/dsh-model-usage?provider=opencode-go
应返回 200 与 usage 数字；刷新页面后，输入框下方应出现 5H / W / M 三个百分比。若当前 profile 不是正在用的 web / desktop，需在对应 profile 重装，否则容易装错归属。
README 另提供「交给 agent 的安装清单」（含 clone、pull、install_bundle、curl 验收、刷新页面）；比纯手动更不易漏 profile 与刷新两步。安装前建议自行阅读 GitHub 仓库 源码与 MIT 许可证：插件以当前 DSH 进程权限运行，会读取环境变量中的 key 并访问配置的 baseURL。
配置¶
cordis.patch.yml 中 meters 决定「哪条 LLM 路由用哪把 key 查哪个端点」。一个 meter 对应一个订阅、一把 key：
- insert:
- id: dsh-model-usage
name: dsh-model-usage
config:
refreshSeconds: 60
meters:
- id: opencode-go
label: opencode-go
providers: [opencode-go]
baseURL: https://opencode.ai/zen/go/v1
keyRef: OPENCODE_GO_API_KEY
- 换 key 改
keyRef；增加订阅则增加一行 meter（需对方有等价/usage端点）。 - meter 懒加载：仅当当前会话的
provider命中该 meter 时才请求；切换模型路由时插件自动换用对应 key 重新取数，无需重启。 - 未配置凭据的路由在切到时显示「未配置凭据」，不影响其它 meter。
刷新与典型使用方式¶
无需额外 CLI：pill 挂在 conversation.composer.dock，随会话界面常驻。
刷新策略（README 说明）：
- 页面可见时每 3 秒轮询本机快照路由。
- Host 缓存 TTL 60 秒（与默认
refreshSeconds: 60一致）；每轮assistant/message落盘后将对应 meter 标脏，下一次轮询回源。 - 有旧数据时先返回旧值、后台刷新，不阻塞 UI。
典型操作：在 opencode-go 路由下正常对话，观察 pill 百分比；用量进入黄/橙/红档时注意额度；需要精确重置时间时点开 pill 查看倒计时与 resetsAt。
适用场景与限制¶
适合：主要使用 DSH + opencode-go（或 Go Plus）订阅，希望在 Composer 旁持续看到三段额度，并在发消息后尽快看到用量更新的开发者。
不适合或需注意：
- 非 opencode-go 路由不会显示 pill（设计如此，非故障）。
- 数字与 OpenCode Console 同源，依赖未公开文档的端点；形状变化时会降级为「暂不可用」，而非显示可能错误的数。
resetsAt缺失时只显示百分比，无倒计时。- 卸载：
plugin_manager remove_bundle target=dsh-model-usage，或从 profile 的 bundles / dependencies 移除后pnpm install并重启。
结尾¶
dsh-model-usage 把 opencode-go 订阅的三段额度收进 DSH 输入框下方一枚 pill，Host 侧拉取 /usage、本机快照对外暴露百分比，切换 provider 时按 meter 懒加载换 key。若你正在 DSH 0.2.x 上跑 opencode-go，可按上文 install_bundle 安装并核对 /api/dsh-model-usage。
