前言¶
DeepSeek Harness (DSH) 採用插件化架構，旨在將功能擴展與核心應用解耦。在使用 Ollama Cloud 服務時，開發者需要關注會話窗口、每週額度以及具體的請求成本。原生的 ollama.com 設置頁與 DSH 界面分離，無法直接在開發環境中查看剩餘額度或管理 API Key。
dsh-ollama-cloud-usage 插件通過註冊 settings.section，在 DSH 設置頁的“賬號與餘額”下方新增了一個名爲 ollama-quota 的配置區塊（order: -9）。該區塊直接展示 Cloud 配額數據，並集成了 API Key 的編輯功能，解決了監控與配置割裂的問題。
插件定位¶
- 名稱:
dsh-ollama-cloud-usage - 作者: adamaik
- 定位: DeepSeek Harness 插件，用於在本地 DSH 界面中查看 Ollama Cloud 剩餘額度及管理 API Key。
- 解決的問題: 解決了在 DSH 環境下無法查看 Cloud 配額、無法快速切換或編輯 API Key 的痛點。
核心功能¶
該插件通過輪詢 ollama.com/api/usage 接口獲取數據，並利用 DSH 的 Remote 機制處理憑證。
配額顯示¶
在設置頁的 ollama-quota 區塊中，插件顯示以下信息：
* Session 窗口剩餘: 數值範圍爲 [0, 1]。
* Weekly 窗口剩餘: 直接數值。
* 每模型請求計數: 針對各個窗口的 limits.<window>.models[].request_count。
* 最近 4 周成本: 顯示 activity.cost 和 activity.period。
API Key 管理¶
- 編輯器: 提供一個輸入框，用於編輯或替換 API Key。
- 寫入機制: 僅編輯列表中第一個
keyEnvs引用的 Key。 - 存儲路徑: 保存至
$DSH_HOME/.credentials.yaml。 - 安全機制: Key 從不在瀏覽器中渲染，輸入框始終爲空，API 返回的數據中不包含明文 Key。
安裝與啓用¶
從 npm 倉庫安裝該插件：
dsh plugin --profile <profile> add dsh-ollama-cloud-usage
注意：
1. 如果安裝後 Host 行未出現，請重啓 DSH 應用。
2. 客戶端更新通常需要刷新頁面生效（桌面應用目前不支持客戶端熱重載）。
配置說明¶
插件支持通過配置文件自定義行爲。默認配置如下：
| 配置項 | 默認值 | 說明 |
|---|---|---|
keyEnvs |
["OLLAMA_CLOUD_API_KEY", "OLLAMA_API_KEY"] |
優先嚐試讀取的憑證引用順序，僅第一個可編輯 |
refreshMs |
60000 |
快照刷新間隔，最小 5000 |
timeoutMs |
15000 |
請求超時時間 |
示例配置¶
在 DSH 的配置文件中，可以通過 YAML 語法覆蓋上述默認值：
- id: ollama-cloud-usage
config:
refreshMs: 120000
憑證配置¶
插件通過 ctx.credentials 讀取 Key，支持環境變量、$DSH_HOME/.env 或 $DSH_HOME/.credentials.yaml 中的 refs。
$DSH_HOME/.credentials.yaml 示例：
version: 1
refs:
OLLAMA_CLOUD_API_KEY: ollama_cloud_api_key_here
注意事項¶
- 平臺限制: 僅支持 Web 平臺。
- 環境要求: 需要 Node.js 版本
>= 22.19.0。 - 編輯限制: 僅
keyEnvs列表中的第一個引用支持編輯，後續引用僅作只讀展示。 - 更新機制: 採用輪詢方式獲取數據，而非推送更新。在憑證更新時會自動觸發刷新。
- 數據缺失:
ollama.com/api/usage接口不返回計劃名稱和重置時間戳，因此插件界面只顯示窗口剩餘量。 - 驗證腳本: 項目包含
scripts/verify.mjs，可離線驗證 Host 路由和 Client 組件渲染邏輯。
結語¶
dsh-ollama-cloud-usage 插件爲 DSH 用戶提供了原生的 Cloud 配額監控入口，併兼顧了 API Key 的安全性管理。它通過標準的 DSH Remote 接口與憑證系統交互，適合需要在本地開發環境中頻繁切換或監控 Ollama Cloud 資源的使用者。
- 插件目錄: SkillHub 插件目錄
- 源碼地址: GitHub
