前言¶
在 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 套餐餘量的開發者使用。
