前言¶

如果你在用 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