前言¶
使用 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
