前言¶
在 DSH web GUI 中使用 OpenCode Go 套餐时，滚动、每周、每月用量以及重置时间需要被频繁查看。dsh-opencode-usage 把这个查询结果放到 composer 输入框下方：常驻徽章展示三个窗口的用量百分比和重置倒计时，点击徽章可以展开卡片，Agent 也可以通过一个无参数工具查询当前套餐用量。
下面按仓库名 vinyumao/dsh-opencode-usage 介绍它的功能、安装方式和需要注意的事项。
这是什么¶
- 仓库：
vinyumao/dsh-opencode-usage - 维护者：
vinyumao - 许可证：
MIT - 适用对象：DSH web GUI
- 用途：显示 OpenCode Go 套餐的滚动、每周、每月用量百分比和重置倒计时
- 插件形态：按 DSH bundle 插件方式安装；
package.json声明dsh.bundle.patch，安装后进入 profile 的dsh.profile.bundles层 - 源码形态：纯源码
index.mjs/client.js，无构建步骤；宿主侧运行时不导入@deepseek-ai/*包
它只针对 OpenCode Go 套餐的订阅配额窗口，不适用于 OpenCode Zen 按量计费余额。
核心功能¶
输入框下方的常驻徽章¶
插件会在 DSH web GUI 的 composer 输入框下方显示一个常驻徽章，展示：
- 滚动用量百分比
- 每周用量百分比
- 每月用量百分比
- 重置倒计时
徽章会按可配置间隔自动刷新。
用量卡片¶
点击徽章后展开用量卡片。卡片内包含：
- 滚动、每周、每月三个窗口的进度条
- 每个窗口已使用的百分比
- 每秒更新的重置倒计时
- 立即刷新按钮
- 一个
opencode链接，点击后在新标签打开 web 用量面板
卡片内配置表单¶
用量卡片内提供配置表单，可以填写：
- API key
- Base URL
- 刷新间隔
- web usage URL
保存会立即生效。
Agent 工具 opencode_go_usage¶
插件提供一个无参数的 Agent 工具：
opencode_go_usage
Agent 调用它后，可以查询 OpenCode Go 套餐当前三个窗口的余额或用量信息，包括滚动、每周、每月窗口的已用百分比和重置倒计时。
本地化¶
插件界面支持中文和英文：
- 文案跟随 DSH 全局语言设置
- 卡片页脚提供中文 / 英文切换
请求与密钥处理¶
浏览器不会直接请求上游。插件把相关请求交给宿主进程处理，使用同源路由：
/api/dsh-opencode-usage/*
API key 不进入浏览器。
API key 默认从环境变量读取：
OPENCODE_GO_API_KEY
通常情况下可以零配置使用。也可以在卡片配置表单中覆盖。
安装与启用¶
环境要求¶
插件要求 Node 版本满足：
^22.19.0 || >=24.0.0
安装命令¶
运行下面命令安装插件：
dsh plugin --profile web add github:vinyumao/dsh-opencode-usage#<ref>
这里的 <ref> 可以固定为 commit SHA，便于复现安装。
安装后重启 dsh web。启动后，composer 输入框下方应出现 OpenCode Go 用量徽章。
pnpm 构建权限问题¶
如果 pnpm 拒绝运行 git 依赖的 prepare 脚本，需要把 pnpm 打印的 package key 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds，然后重试。
典型用法¶
1. 安装并重启¶
dsh plugin --profile web add github:vinyumao/dsh-opencode-usage#<ref>
安装完成后重启 dsh web。
2. 查看徽章¶
打开 DSH web GUI，在 composer 输入框下方查看 OpenCode Go 徽章。徽章会显示三个窗口的用量百分比和重置倒计时。
3. 展开卡片¶
点击徽章展开用量卡片，查看进度条、已用百分比、每秒重置倒计时，并可以点击立即刷新按钮。
4. 让 Agent 查询¶
在会话中让 Agent 运行 opencode_go_usage 工具，获取滚动、每周、每月三个窗口的已用百分比和重置倒计时。
5. 处理查询失败¶
如果徽章显示 query failed，先检查是否设置了：
OPENCODE_GO_API_KEY
如果没有设置，也可以点击徽章，在卡片配置表单中填写 API key。
6. 卸载¶
运行下面命令卸载插件：
dsh plugin --profile web remove @chen-001/dsh-opencode-usage
卸载后重启 dsh web。
如果不再安装该插件，并且卡片配置表单中填写过 API key，可以删除本地配置文件：
rm ~/.dsh/dsh-opencode-usage.json
该文件保存 API key，文件权限为 0600。
适用场景与注意¶
适合在 DSH web GUI 中长期使用 OpenCode Go 套餐、并且希望在输入框附近直接看到用量状态的开发者。它也适合希望 Agent 在对话中按需查询套餐用量的场景。
使用前需要注意：
- 插件以当前
dsh进程的权限运行，安装前应检查仓库源码与许可证。 - 许可证为
MIT。 - 它只针对 OpenCode Go 套餐，不适用于 OpenCode Zen 按量计费余额。
- 用量端点被标注为未验证：
GET https://opencode.ai/zen/go/v1/usage
该端点不属于官方公开文档，响应结构可能变化，不能确认其长期稳定性。
- API key 默认读取 OPENCODE_GO_API_KEY，也可以在卡片配置表单中覆盖。
- 如果在卡片中保存了 API key，密钥会明文保存在：
~/.dsh/dsh-opencode-usage.json
不再使用时可删除该文件。
结尾¶
dsh-opencode-usage 解决的是 DSH web GUI 中 OpenCode Go 套餐用量的可见性问题：徽章常驻显示，卡片展开细节，Agent 可调用 opencode_go_usage 工具查询。当前资料未提供目录页 URL；GitHub 地址为：
