前言¶
在 DSH 环境下开发智能体，监控 API 套餐用量是日常运维的一部分。OpenCode Go 套餐的用量通常需要手动查询接口，缺乏直观的界面反馈。该插件在 DSH Web UI 的输入框工具行中集成了实时用量圆环与查询工具，解决了在对话中监控用量、查看重置倒计时以及主动查询余额的需求。
插件简介¶
dsh-opencode-go-usage 是一个 DeepSeek Harness (DSH) Web GUI 插件，由 qknc-bot 维护，归类于 admin-security。它专注于 OpenCode Go 套餐的用量监控，提供可视化界面与 Agent 工具能力。
核心功能¶
- 工具行圆环显示：输入框工具行常驻一个 5 小时滚动窗口 的用量圆环。圆环显示已用百分比，并根据阈值自动变色（绿色、橙色、红色）。圆环每 30 秒 自动刷新，悬停可查看详情。
- 展开卡片详情：点击圆环旁的白色卡片，展开显示 5 小时 / 每周 / 每月 三个窗口的进度条、百分比与重置倒计时。
- Agent 工具集成：注册了
opencode_go_usage工具，模型可以在对话中直接查询余额，无需离开对话窗口。 - 安全机制：API Key 通过 DSH 凭据引用（
OPENCODE_GO_API_KEY）解析，仅保留在 host 进程中，浏览器永不接触。代理路由带有 loopback-only 限制，防止局域网暴露部署时泄露 Key。 - 零 SDK 依赖：插件运行时无任何
@deepseek-ai/*包依赖，支持 git vendoring 或目录安装，开箱即用。
安装与启用¶
推荐从 GitHub 安装，将 <ref> 替换为具体的 commit SHA 以保证可复现。
dsh plugin --profile web add github:qknc-bot/dsh-opencode-go-usage#<ref>
若从本地目录安装，需注意 file: 协议无法解析含空格或中文的路径，源码应放在纯 ASCII 路径下：
dsh plugin --profile web add file:C:/path/to/dsh-opencode-go-usage
安装后重启 dsh web，输入框工具行左侧出现 5h 圆环即表示生效。
注意事项：
* 首次 git 安装若被 pnpm 的 allowBuilds 拦下，需在 profile 的 pnpm-workspace.yaml 中添加 allowBuilds: dsh-opencode-go-usage: true。
* 从旧版本升级时，建议先卸载再重新 add，避免 package.json 中的残留冲突。
配置说明¶
插件配置位于 profile 的 cordis.patch.yml（安装时自动生成）。以下是可覆盖的字段：
- id: opencode-go-usage
name: dsh-opencode-go-usage
config:
baseUrl: https://opencode.ai/zen/go # 上游网关基址，自动拼接 /v1/usage
timeoutMs: 15000 # 上游请求超时（毫秒）
refreshSeconds: 30 # 圆环自动刷新间隔（秒）
warnPercent: 60 # 5h 窗口达到该百分比后变橙
dangerPercent: 85 # 达到该百分比后变红
announceToAgent: true # 是否向 agent 公告插件能力
API Key 解析依赖 DSH 凭据引用 OPENCODE_GO_API_KEY，通常无需额外配置。
典型用法¶
- 界面交互：在输入框工具行悬停
5h圆环查看概览，点击展开查看 5h/周/月 三个维度的详细进度与重置时间。 - 对话查询：在对话中直接调用工具。模型会自动识别“余额”、“用量”、“quota”等关键词，并调用
opencode_go_usage工具返回当前用量状态。
注意事项¶
- 接口未公开：用量接口未在 OpenCode 公开文档中，响应结构可能随 opencode 演变。解析逻辑做了防御处理，非 200 或非 JSON 响应会以友好提示展示而非崩溃。
- 限额展示：套餐限额（如 $12 / $30 / $60）仅作展示参考，接口不返回金额数据。
- 升级提示：从旧版本升级时，务必先卸载再重新添加。
总结¶
该插件为 DSH 用户提供了可视化的用量监控入口，并赋予 Agent 查询权限。其零依赖的设计降低了集成成本，且通过 Host 进程隔离确保了 Key 安全。适合需要在开发过程中持续关注 OpenCode Go 套餐余量的开发者使用。
