前言¶

使用 OpenCode Go 跑 DSH 智能体时，5 小时、每周、每月这几个用量窗口往往分散在账户侧，聊天界面里不容易直接看到。更常见的问题是：agent 已经发出请求，才发现额度快用尽，导致任务停在半路，或者浪费一次调用。

dsh-opencode-go-quota 是一个 DSH Web 持久化插件。它把 OpenCode Go 的额度状态放到聊天输入框附近，并在 agent 请求进入新档位时把一次额度提醒写入 system prompt。下面介绍它的功能、安装和常见配置。

这是什么¶

仓库名为 dsh-opencode-go-quota，由 GLFzr 维护，许可证为 MIT。它解决的是两个问题：

1、在 DSH Web 里快速看到当前 OpenCode Go 额度余量。
2、在 agent 请求中按需注入一次额度提醒，避免同档内重复提示。

插件会读取本地 OpenCode Go key，调用官方接口，再经 DSH 内部路由提供给浏览器端和 prompt 注入。

核心功能¶

输入框旁的额度圆环¶

在聊天输入框模型选择器左侧显示一个 22px 进度圆环：

• 中央显示 5 / W / M，点击可循环切换 5 小时、每周、每月用量窗口。
• 悬停显示已用百分比与重置倒计时。
• 颜色按紧急程度区分：绿 <30%、蓝 30-60%、橙 60-80%、红 ≥80%。
• 每 5 分钟自动刷新。
• 点击切换窗口时，如果数据超过 1 分钟，则强制刷新。
• 额度达到 ≥80% 时，圆环红色脉冲闪烁，并显示暂停建议。

system prompt 注入¶

每次 agent 请求时，插件会把当前额度状态动态注入 system prompt。这个注入只在进入新档位时发生一次；同档内后续请求不会重复注入。

当数据不可用时，prompt 注入为空，圆环显示灰色 !，悬停可以看到错误原因。这样既保留了调试信息，也不会向对话里加入无效提示。

数据读取与接口调用¶

插件在 Host 端读取：

~/.local/share/opencode/auth.json

其中取 opencode-go.key。如果设置了环境变量 OPENCODE_GO_API_KEY，优先使用该变量。auth.json 容忍 UTF-8 BOM；文件缺失、解析失败、无 key 会分别报错。

随后插件调用官方接口：

GET https://opencode.ai/zen/go/v1/usage

并使用 Bearer 鉴权。

结果经以下路由提供给浏览器端与 prompt 注入：

/ocg-quota/usage

响应包含 thresholds。

配置项¶

可以在 cordis.yml 中配置这些项：warnAt、criticalAt、escalateFrom、escalateStep、cacheTtl、weeklyWarnAt、monthlyWarnAt。例如：

- id: dsh-opencode-go-quota
  config:
    warnAt: 60
    criticalAt: 80
    escalateFrom: 90
    escalateStep: 2
    cacheTtl: 60
    weeklyWarnAt: 90
    monthlyWarnAt: 95

失败结果会按 errorCacheTtl 秒短缓存，默认 5 秒。

安装与启用¶

1、使用 GitHub 安装：

dsh plugin --profile web add github:GLFzr/dsh-opencode-go-quota

2、或从本地路径安装：

dsh plugin --profile web add <本目录绝对路径>

3、安装后重启 dsh web 生效。

卸载：

dsh plugin --profile web remove dsh-opencode-go-quota

典型用法¶

固定 Windows workspaceRoot¶

插件需要宿主 shell 能运行子进程。DSH 的 Windows ACL 沙箱要求 sandbox-policy.workspaceRoot 不包含系统 TEMP 目录。从用户主目录等位置启动 dsh web 可能触发该限制。

可以在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中固定 workspace 根目录：

- id: sandbox-policy
  config:
    workspaceRoot: <你的 workspace 绝对路径>

然后重启 dsh web。临时处理方式是先在目标 workspace 目录内启动 dsh web。

处理 key not found¶

如果提示 opencode-go key not found：

1、检查 ~/.local/share/opencode/auth.json 是否存在且包含 opencode-go.key。
2、或设置环境变量 OPENCODE_GO_API_KEY，然后重启 dsh web。
3、如果 auth.json 带 UTF-8 BOM 或文件损坏，也可能导致取 key 失败；0.3.2 起已容忍 BOM 并区分错误。

适用场景与注意¶

适合在 DSH Web 中使用 OpenCode Go 额度、并需要让 agent 感知额度档位的开发者。使用前后要注意：

• 插件会读取本地凭据并调用 https://opencode.ai/zen/go/v1/usage，因此会以当前 dsh 进程权限运行；安装前建议检查源码与 MIT 许可证。
• 额度（钱）和 token 用量是两回事。该插件回答“还剩多少额度”，不替代 token 记账；可以配合 dsh-token-ledger 同时安装，两者互不依赖。
• Windows 下如果从用户主目录启动，更容易碰到 ACL 沙箱限制，优先固定 workspaceRoot。

结尾¶

dsh-opencode-go-quota 把 OpenCode Go 的 5 小时、每周、每月额度做成输入框旁的圆环，并在 agent 请求进入新档位时注入一次提醒。对需要控制调用节奏和任务边界的 DSH 使用场景，这是一个比较直接的辅助组件。

仓库地址：

https://github.com/GLFzr/dsh-opencode-go-quota