前言¶
DeepSeek Harness（DSH）的「上下文已用」圓環只顯示當前會話的 token 消耗，無法直接看到 opencode Go 套餐的用量。這款插件在窗口角落掛一個浮窗，實時展示 Rolling / Weekly / Monthly 的使用情況與剩餘量，用滿即報錯，避免超出套餐。
插件定位¶
rshh0520/opencode-go-usage 是 DSH 的 admin-security 類插件，由維護者 rshh0520 開發。它以浮窗形式監控 opencode Go 套餐的用量，支持實時倒計時、換 Key 自動跟隨、主題適配。
核心功能¶
三窗口用量展示¶
浮窗垂直排列三個窗口：Rolling usage、Weekly usage、Monthly usage。每行包含「標籤 + 百分比徽章 + 重置倒計時 + 進度條」。
實時倒計時與預警¶
倒計時根據上游的 resetsAt 現算：不足 1 天顯示 3h 8m，超過 1 天顯示 4d 20h。某個窗口達到上限（status: rate-limited 或 percent ≥ 100）時，徽章與進度條轉爲錯誤色。
浮窗可拖動¶
按住卡片主體拖動即可換位置（位移小於 4px 視爲點擊）。位置存進 localStorage，刷新後保持。窗口變小時自動拉回可視區域。
查詢間隔可調¶
支持 30s / 1m / 2m / 5m / 10m，改完立即生效並持久化。
API Key 管理¶
面板裏默認顯示脫敏值（如 sk-AGs…Fz6W），可查看明文、一鍵複製，並標出 Key 來自哪個環境變量、DSH 憑據的哪一層或哪個文件。換 Key 後，下一次輪詢自動使用新值，無需重啓。
主題跟隨¶
顏色全部取自 DSH 主題 token，明暗主題自動適配。
失敗不閃屏¶
已經成功取過數，後續某次請求失敗時保留舊讀數，只把錯誤掛到懸停提示裏。
安裝¶
前置條件：已安裝 DeepSeek Harness（桌面版或 dsh CLI），並且 opencode 已登錄 —— 也就是 auth.json 裏存在 opencode-go 憑據，或已設置對應環境變量。
本倉庫是一個 DSH bundle：package.json 裏聲明瞭 dsh.bundle.patch，插件自帶的 cordis.patch.yml 會把自身 entry 插進 cordis 組合樹。因此不需要手工編輯 profile 的 cordis.patch.yml，也不會被宿主覆蓋。
桌面版¶
在 DSH 桌面版的插件管理界面裏，以本倉庫目錄作爲本地來源安裝。識別到 dsh.bundle 後，安裝器會自動把它登記進該 profile 的 dsh.profile.bundles。安裝後重啓應用。
命令行¶
dsh plugin --profile <profile> add "link:/絕對路徑/dsh-opencode-go-usage"
因爲聲明瞭 dsh.bundle，dsh plugin add 會自動把它寫進該 profile package.json 的 dsh.profile.bundles，同樣不用改 cordis.patch.yml。
把倉庫放在 profile 目錄之外，通過
link:或安裝器引入。不要直接拷進 profile 目錄。
使用方法¶
浮窗¶
安裝後浮窗默認出現在窗口右下角，每 60 秒自動刷新一次。它掛在 DSH 的幀級浮層座席 shell.overlay 上，與會話無關 —— 沒有打開任何會話時同樣顯示。
拖動¶
按住卡片主體拖動即可換位置（位移小於 4px 視爲點擊，不會誤拖）。位置存進 localStorage，刷新後保持。想回到默認位置，清掉 dsh.opencodeGoUsage.pos 即可。
設置面板¶
點右下角的齒輪按鈕展開：
| 區域 | 操作 |
|---|---|
| 查詢間隔 | 點 30s / 1m / 2m / 5m / 10m 中的一項，立即重建輪詢定時器 |
| API Key | 點「查看」加載 → 默認顯示脫敏值（如 sk-AGs…Fz6W）→ 點「顯示」切明文 → 點「複製」寫入剪貼板（成功後按鈕短暫變爲「已複製」）→ 點「刷新」重新讀取（宿主換過 Key 時面板會自動跟進，失敗時這裏顯示「重試」） |
| 來源 | 顯示 Key 來自哪個環境變量、DSH 憑據的哪一層，或哪個 auth.json |
懸停卡片可看到各窗口的剩餘百分比、上次刷新錯誤與操作提示。
配置¶
API Key 從哪來¶
每次刷新都重新解析（不緩存 Key），按順序取第一個命中的：
- 環境變量
OPENCODE_GO_API_KEY - 環境變量
OPENCODE_API_KEY - DSH 託管的憑據（
ctx.credentials→$DSH_HOME/.credentials.yaml裏的OPENCODE_GO_API_KEY）—— 在 DSH 設置頁填 / 換 Key 寫的就是這裏 - 環境變量
OPENCODE_AUTH_CONTENT（整份auth.json的 JSON 字符串） %USERPROFILE%\.local\share\opencode\auth.json裏的["opencode-go"]（key，oauth 憑據則取access）
第 3 項讓「在 DSH 裏換 Key」變成自動的：DSH 的託管憑據文檔不會寫回進程環境，只走這條 seam 才能讀到新值，所以插件每次取數都 resolve 一次，無需重啓。第 5 項是 opencode 自己的憑據文件位置，也可以用 XDG_DATA_HOME 重定位。只要 opencode 已登錄、或在 DSH 裏配過 Key，通常無需任何額外配置。
面板裏「來源」一行會寫明當前用的是哪一層（例如 OPENCODE_GO_API_KEY（DSH 憑據 / file） 或 …\opencode\auth.json）。
換了 Key 之後多久生效¶
| 改 Key 的位置 | 是否自動生效 | 說明 |
|---|---|---|
DSH 設置頁 / 憑據存儲（.credentials.yaml） |
✅ 自動，無需重啓 | 下一次輪詢就用新值，面板裏顯示的 Key 也會跟着重取 |
opencode 重新登錄改寫 auth.json |
✅ 自動 | 同上（只要環境變量那一層沒有更高的 Key 壓着） |
OPENCODE_GO_API_KEY / OPENCODE_API_KEY 環境變量 |
⚠️ 需重啓 DSH | Node 的 process.env 是啓動快照，改系統環境變量對已運行進程無效 |
生效延遲 = 宿主 30s 數據緩存 + 頁面輪詢間隔（默認 60s，可在面板改到 10m）。舊 Key 失效後，卡片會保留最後一次讀到的數字（不閃空白），懸停可在提示裏看到 401。
環境變量¶
| 變量 | 作用 |
|---|---|
OPENCODE_GO_API_KEY |
首選 API Key |
OPENCODE_API_KEY |
備用 API Key |
OPENCODE_AUTH_CONTENT |
直接以 JSON 字符串提供 auth.json 內容 |
XDG_DATA_HOME |
重定位 opencode/auth.json 所在目錄 |
瀏覽器側持久化¶
localStorage 鍵 |
內容 |
|---|---|
dsh.opencodeGoUsage.pos |
浮窗位置 {x, y} |
dsh.opencodeGoUsage.intervalMs |
查詢間隔（毫秒） |
適用場景¶
需要持續監控 opencode Go 套餐用量的開發者。插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
常見問題¶
浮窗一直顯示「opencode Go usage 不可用」
取數從未成功過。先確認 curl -H "Authorization: Bearer $KEY" https://opencode.ai/zen/go/v1/usage 能返回 200。
提示 401
Key 無效或已失效。
提示 403
Key 本身有效，但該賬號沒有 opencode Go 套餐（Zen 與 Go 共用同一個 workspace key，所以這個錯誤是「有 key、無套餐」）。
點「查看」顯示讀取失敗
「查看 Key」依賴宿主側的 /key 路由。如果你剛更新過插件，重啓一次 DSH 讓新的宿主代碼生效 —— 宿主側模塊不像前端 bundle 那樣熱更新。重啓後仍失敗可以點「重試」。
不想讓明文 Key 進入頁面
刪掉 lib/index.js 裏 /key 分支即可，此時面板會顯示讀取失敗而不是崩潰。
結尾¶
這款插件通過浮窗形式解決了 opencode Go 套餐用量監控的問題，支持實時倒計時、換 Key 自動跟隨、主題適配，適合需要持續監控用量的開發者。更多細節與源碼見插件目錄頁與 GitHub 倉庫。
