前言¶
在 DSH 裏同時使用 DeepSeek、GPT（Codex）、Gemini 的開發者，通常要在多個平臺賬戶頁之間切換才能確認各自還剩多少額度；賬號多、窗口規則不同，逐個查看既打斷工作流，也容易漏掉某個平臺的重置時間。已有做法是繼續開多個網頁，或依賴各平臺自己的額度文案。
dsh-quota-ring 把這個動作收進 DSH Web UI：在右下角顯示一個懸浮圓環，點擊後查看三家賬號的額度狀態。插件由 j352201657-debug 維護，屬於客戶端分類，在社區目錄的星標爲 1。下面介紹它的能力、安裝方式和配置。
這是什麼¶
dsh-quota-ring 是一個 DSH Web UI 插件，作用是聚合展示 DeepSeek / GPT（Codex）/ Gemini 三家賬號的額度狀態。當前版本爲 3.1.1，許可證爲 MIT，package.json 中聲明的運行要求是 Node.js >=18、DSH >=0.2.0-rc.1 <0.3.0-0。
它解決的問題很集中：不替換各平臺自己的查詢入口，而是在 DSH 界面內給一個統一視圖，讓額度餘量可見，而不是開多個窗口。
核心功能¶
圓環本身只顯示「已知百分比窗口中的最低剩餘額度」，即各平臺當前能確定的最小余量；點擊展開後才能看到明細。
DeepSeek 側顯示餘額、累計消費、今日消耗估算和峯谷時段提示。GPT（Codex）顯示賬號上報的速率窗口及重置時間。Gemini 按 Antigravity 返回的額度組顯示，可用組和窗口會隨賬號及上游接口變化。
三條設計約束值得注意：
- 三家平臺獨立查詢，某個平臺失敗時其餘平臺繼續顯示。
- 金額和百分比分別展示，插件不把不同幣種相加，也不做匯率折算。
- 未上報的數據不當作零額度或滿額度處理，避免把「讀不到」誤顯示成「用盡」。
刷新策略默認每 10 分鐘一次，界面支持手動刷新；失焦時按 idleMultiplier 降頻，頁面隱藏時可暫停，服務端側還有一層緩存用於合併併發的額度查詢。
安裝與啓用¶
插件需要帶 Web UI 和 webServer 服務的 DSH，以及 Node.js 18 或更高版本。安裝分兩種 profile。
桌面版通過桌面應用提供的插件安裝入口安裝，倉庫地址爲：
https://github.com/j352201657-debug/dsh-quota-ring
需要說明的是，桌面應用裏的 desktop 是保留 profile，由桌面安裝器管理，普通獨立 CLI 不接受對該 profile 的安裝命令。
獨立 Web 版在已提供 dsh 命令的終端中執行：
dsh plugin --profile web add https://github.com/j352201657-debug/dsh-quota-ring
安裝後重啓對應的 DSH 實例。
三家平臺的登錄與組件要求不同：
| 平臺 | 登錄與組件要求 |
|---|---|
| DeepSeek | 在 DSH 內置的 DeepSeek 賬號組件中登錄 |
| GPT（Codex） | 安裝 dsh-codex-subscription 並登錄訂閱賬號 |
| Gemini | 安裝 dsh-agy-cli 並完成 Antigravity 授權 |
補充兩點依賴限制：Gemini 的原始額度讀取依賴 Windows 憑據管理器，其他平臺使用 AGY 狀態接口回退，可能缺少部分窗口。只有對應平臺具備有效登錄狀態時，纔會顯示其額度。
卸載時在對應 profile 中移除本插件的依賴和註冊條目，再重啓 DSH。統計狀態位於 DSH 數據目錄下的 dsh-quota-ring/usage-state.json，可按需保留。
配置¶
配置寫在對應 profile 中本插件註冊條目的 config 字段裏。該插件提供的字段如下。
| 字段 | 默認值 | 說明 |
|---|---|---|
refreshIntervalMs |
600000 |
前端刷新間隔，毫秒，最小 5000 |
idleMultiplier |
3 |
失焦時的刷新間隔倍數 |
pauseWhenHidden |
false |
頁面隱藏時是否暫停刷新 |
dshHome |
'' |
DSH 數據目錄；留空自動查找 |
dshWebPort |
0 |
AGY 狀態接口端口；0 表示從請求 Host 推斷 |
proxy |
'' |
HTTP 或 HTTPS 代理地址；留空自動探測 |
serverCacheTtlMs |
60000 |
服務端緩存時長，毫秒；0 關閉緩存 |
requestTimeoutMs |
15000 |
單次上游請求超時，毫秒 |
corsOrigins |
迴環來源 | 允許的跨域來源；另允許迴環主機的任意端口 |
deepseekPeakWindows |
null |
UTC 峯時段列表，例如 [{start:1,end:4},{start:6,end:10}] |
deepseekPeakHolidays |
null |
UTC+8 假期日期列表，例如 ['2026-10-01'] |
憑據目錄按以下順序查找：config.dshHome；環境變量 DSH_HOME、DSH_DATA_DIR；從插件安裝目錄向上查找；用戶主目錄下的 .dsh。
代理按配置、HTTPS_PROXY / HTTP_PROXY / ALL_PROXY 環境變量、Windows 系統代理的順序探測；無可用代理時直連，迴環請求始終直連。服務端會合並併發的額度查詢，手動刷新繞過已完成結果的緩存、複用仍在進行的請求。登錄或切換賬號後，下一次實際查詢會重新讀取憑據。
界面默認的峯谷窗口爲 UTC 01:00–04:00、06:00–10:00（對應北京時間 09:00–12:00、14:00–18:00），週末和內置的 2026 年假期表參與計算。時段與假期均可通過配置覆蓋。
HTTP API¶
插件在宿主內暴露 HTTP 接口，路由前綴爲 /api/quota-hub，訪問需遵循 DSH 宿主的身份驗證和網絡訪問設置。
| 方法 | 路徑 | 用途 |
|---|---|---|
| GET | /summary |
查詢聚合額度，支持緩存 |
| GET | /summary?force=1 |
繞過已完成結果的緩存 |
| POST | /refresh |
手動刷新 |
| GET | /config |
獲取界面所需配置，代理僅返回配置狀態 |
| GET | /diag |
查詢本地診斷信息，不請求上游額度接口 |
額度結果包含 providers、fetchedAt 和 health。平臺條目的狀態爲 ok、missing_key、unavailable 或 error，明細包含 windows，Gemini 還可包含 groups。DeepSeek 附帶 peak 和 usage。
/diag 的詳細結果在 diag 字段，包括憑據文件路徑、解析狀態、插件版本及處理建議。診斷結果可能包含本機路徑，分享前應檢查內容。
典型用法¶
按安裝步驟裝好、重啓 DSH 後，進入 Web UI 即可在右下角看到圓環。如果某平臺顯示「未登錄」，先確認該平臺的登錄組件是否已保存憑據，再手動刷新一次。
排障時可對照官方給出的對照表：
| 現象 | 檢查項 |
|---|---|
| 圓環未顯示 | 檢查插件安裝的 profile、註冊條目和 DSH 啓動日誌 |
| 顯示未登錄 | 檢查對應賬號登錄狀態及 /diag 中的解析結果 |
| 登錄後仍顯示舊狀態 | 手動刷新；檢查 DSH 登錄組件是否已保存新的憑據 |
| Gemini 數據不可用 | 檢查 AGY 授權、組件啓用狀態和 DSH Web 端口 |
| Gemini 缺少部分窗口 | 檢查是否使用 AGY 狀態接口回退 |
| 查詢超時 | 檢查網絡和 proxy 配置 |
| 峯谷提示不符合當前規則 | 更新時段和假期配置 |
設置環境變量 QH_DEBUG=1 可啓用服務端調試日誌；公開日誌前應檢查其中的賬號信息和本機路徑。
想自己覈對實現的開發者可以運行離線測試，它使用臨時目錄和本地測試服務器，不讀取真實登錄憑據，也不請求平臺額度接口：
npm test
node --check client.js
node --check index.js
需要本機賬號生成預覽時執行 node preview/build-preview.cjs，然後打開生成的 preview/preview.html。該命令會實際查詢額度並更新本機消耗統計；預覽頁使用靜態快照，生成文件不應直接公開，脫敏處理不能替代人工檢查。
源碼使用 CommonJS，客戶端爲原生 DOM，沒有構建步驟。職責劃分如下：index.js 處理路由與宿主生命週期，client.js 處理圓環、卡片和刷新交互，src/aggregator.js 處理請求合併、緩存及平臺隔離，src/adapters/ 放各平臺請求和響應解析，src/credentials.js 和 src/keyring.js 讀取憑據，src/http.js 處理 HTTP、代理、超時及響應解析，src/peak.js、src/usage.js 處理時段提示和消耗估算。
適用場景與注意¶
適合在 DSH Web UI 內同時使用 DeepSeek、Codex、Gemini，且希望少開頁面的開發者。它的價值在於把多平臺餘量壓成一個常駐視圖，而不是提供新的計費或對賬能力。
使用前需要留意：
- 插件以當前 DSH 進程的權限運行，能讀取該進程可訪問的憑據、數據目錄和網絡出口。安裝前建議通讀源碼並確認 MIT 許可證符合你的要求。
- 文中列出的 DeepSeek、Codex、Gemini 接口並非本插件定義的穩定公開協議，上游字段或鑑權變化可能導致查詢失敗。
- 今日消耗依據餘額變化估算，不是官方賬單；峯谷提示亦不用於計算官方賬單，實際計費以平臺公佈的規則和賬單爲準。
- Gemini 原始額度讀取依賴 Windows 憑據管理器，其他平臺使用 AGY 狀態接口回退，可能缺少部分窗口。
- 項目沒有遙測上報邏輯，界面動態文本使用
textContent寫入；但生成預覽時會把額度快照寫到本機。
結尾¶
這個插件做的事情單一：把 DeepSeek、GPT（Codex）、Gemini 三家的額度狀態聚合到 DSH Web UI 右下角的懸浮圓環裏，並在平臺間保持查詢隔離。對於已經在 DSH 中跑多模型工作流的開發者，它省掉的是反覆切回各平臺賬戶頁的動作。
- 社區目錄頁：https://www.skillhub.cn/plugins/j352201657-debug/dsh-quota-ring
- GitHub：https://github.com/j352201657-debug/dsh-quota-ring
