前言¶

如果你在用 DeepSeek Harness（DSH）搭建 Web 端智能体工作流，并且同时使用多个 OpenCode Go API key，一个具体问题是：这些 key 的 rolling、weekly、monthly 配额消耗和重置时间，通常分散在接口返回中，不容易在页面上直接对照。

DSH 插件 dsh-opencode-go-usage 解决的是这个查看问题：它作为 web 插件把 OpenCode Go 各 API key 的订阅用量展示在 DSH web 页面中，通过悬浮组件和可展开面板给出进度、百分比、重置倒计时和限流标记。下面先介绍它的定位，再给出安装、配置和运行检查步骤。

项目定位¶

这是一个 DeepSeek Harness web 插件，用于实时展示 OpenCode Go 各 API key 的订阅用量。

• 包名：@xiaweiliang060035/dsh-opencode-go-usage
• 版本：0.3.0
• 许可证：MIT
• GitHub 仓库：https://github.com/xiaweiliang060035/dsh-opencode-go-usage

它面向已经使用 DSH web profile，并且需要观察 OpenCode Go 配额状态的开发者。

核心功能¶

悬浮小组件¶

组件固定在页面右侧。按钮徽章展示所有 key 中最差的窗口状态，并用绿色、橙色、红色提示是否接近配额上限。

可展开面板¶

点击悬浮按钮打开面板后，每个 key 展示一张卡片。当前活跃 key 标 ★。卡片展示：

• rolling / weekly / monthly 进度条
• 百分比
• 重置倒计时
• 限流窗口标记 ⚠

实时刷新¶

Host 每 60 秒轮询官方 usage 端点，轮询间隔可配置。面板会自动刷新，也支持手动刷新。

自动发现 key 池¶

插件从 $DSH_HOME/.credentials.yaml 读取 OPENCODE_GO_KEY_<name> 条目，不硬编码 key 数量或名称。没有 key 池时，回退到 OPENCODE_GO_API_KEY。

国际化与主题¶

插件支持中文和英文，并根据浏览器语言自动选择。它使用 DSH 主题令牌，兼容亮色和暗色主题。

工作方式¶

插件同时包含 Host half 和 Client half。

Host 负责：

1. 从配置或 .credentials.yaml 发现 key 池。
2. 通过 DSH credentials 能力解析 key。
3. 调用官方 usage 端点：

GET https://opencode.ai/zen/go/v1/usage
Authorization: Bearer <API_KEY>

Client 负责：

• 注册到 shell.overlay slot
• 轮询 Host 路由 /plugins/dsh-opencode-go-usage/snapshot
• 在页面中渲染悬浮组件和面板

API key 不离开 Host。

README 指出，该 usage endpoint 尚未列入 OpenCode 公开文档，因此插件对响应解析采用防御性方式。

安装与启用¶

环境要求¶

需要 Node.js 和一个 DeepSeek Harness web profile。默认 dsh web profile 会挂载 webServer、credentials 和 timer，这些是该插件需要的能力。

peerDependencies 包括：

{
  "react": "^18.2.0",
  "@deepseek-ai/cordis": "^4.0.1",
  "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
  "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6"
}

npm 安装¶

先进入你的 DSH web profile 目录，再安装包：

cd $DSH_HOME/profiles/web
pnpm add @xiaweiliang060035/dsh-opencode-go-usage

然后把 "@xiaweiliang060035/dsh-opencode-go-usage" 加入 profile 的 dsh.profile.bundles 列表，并重启 dsh web。

本地包安装¶

如果你使用本地目录中的包，可以先把它复制到磁盘：

D:/tools/dsh-opencode-go-usage

然后在 profile 的 package.json 的 dependencies 中加入：

"@xiaweiliang060035/dsh-opencode-go-usage": "file:D:/tools/dsh-opencode-go-usage"

接着把 "dsh-opencode-go-usage" 加入 dsh.profile.bundles，执行安装并重启：

cd $DSH_HOME/profiles/web
pnpm install

最后重启 dsh web。

注意：插件同时包含 Host half 和 Client half。仅复制到 plugins/ 并且只加载 Host half，不足以呈现悬浮小组件。

配置¶

在 profile 的 cordis.patch.yml 的插件行 config 中，可以配置以下字段：

- id: opencode-go-usage
  config:
    keyNames: [go1, go2]
    baseUrl: https://opencode.ai/zen/go/v1/usage
    refreshMs: 60000
    timeoutMs: 15000
    dshHome: ~
    hideCordisPanel: true

这些配置项用于：

• keyNames：指定 key 池名称，对应 .credentials.yaml 中的 OPENCODE_GO_KEY_<name>
• baseUrl：指定 usage 端点
• refreshMs：Host 轮询间隔，单位毫秒
• timeoutMs：请求超时，单位毫秒
• dshHome：指定包含 .credentials.yaml 的 DSH home 目录
• hideCordisPanel：隐藏内置的 Cordis plugins 面板入口

key 池配置¶

key 从 $DSH_HOME/.credentials.yaml 读取。一个 key 池可以写成：

OPENCODE_GO_API_KEY: sk-opencode-...
OPENCODE_GO_KEY_ACTIVE: go2
OPENCODE_GO_KEY_go1: sk-opencode-...
OPENCODE_GO_KEY_go2: sk-opencode-...
OPENCODE_GO_KEY_go3: sk-opencode-...

任意 OPENCODE_GO_KEY_<name> 条目都会被自动发现，key 的数量和名称不需要固定。如果只配置一个 key，可以只设置 OPENCODE_GO_API_KEY，组件会展示这个单个 key。

运行检查¶

运行 dsh web 后，客户端通过以下路由获取快照：

/plugins/dsh-opencode-go-usage/snapshot

如果小组件显示 !，先确认两件事：

1. dsh web 正在运行。
2. 上述 /plugins/dsh-opencode-go-usage/snapshot 路由可以访问。

适用场景与注意¶

这个插件适合已经在 DSH web profile 中使用 OpenCode Go，并且需要同时查看多个 API key 配额状态的开发者。它围绕 OpenCode Go usage 端点和 DSH 凭据文件工作。

DSH 插件生态强调“一切皆插件”。相关插件目录是独立站点，不应理解为 DeepSeek 或幻方的官方应用商店。

插件以当前 dsh 进程权限运行，会读取配置指定的凭据并访问网络端点。安装前建议检查源码、许可证和 peerDependencies，确认它们与你的 DSH 环境兼容。

链接¶

• GitHub 仓库：https://github.com/xiaweiliang060035/dsh-opencode-go-usage