前言¶
在 DeepSeek Harness（DSH）或中國科大「詞元工坊」TokenWorks 中使用 USTC 網關時，額度信息通常散落在賬戶彈窗或官方入口裏，需要切換到其他頁面才能查看。頻繁查看剩餘額度會增加操作成本。本插件在左側欄提供一個常駐卡片，實時展示 3h / 12h / 24h 三個窗口的已用與剩餘、百分比和重置時間。
插件定位¶
插件名稱爲 awenforever/dsh-ustc-quota，由維護者 Awenforever 提供。它爲 DeepSeek Harness 和中國科大詞元工坊 TokenWorks 提供一個只讀的額度展示組件，不攔截請求、不更換 Key、不修改 provider 配置，僅讀取額度數據並在側邊欄渲染卡片。
核心功能¶
- 在側邊欄顯示 3h / 12h / 24h 三列額度進度。
- 每列展示當前窗口剩餘時間、已用額度、上限、百分比和下一次重置時刻。
- 已用額度用綠色條表示，剩餘爲淺灰槽；已用 ≥70% 變黃、≥90% 變紅。
- 對話當前實際使用的 Key 會在 Key 行標記星號，切換對話或模型時即時更新。
- 側邊欄收起時卡片自動隱藏，展開後恢復。
- 單把 Key 查詢失敗隻影響該行，保留 5 分鐘內的舊數據並標記錯誤。
- 24h 額度可能來自 Key 級或用戶級預算，單元格會標註數據來源。
安裝與啓用¶
安裝前請確認環境版本：DeepSeek Harness Web / Desktop 需要至少 0.2.0-rc.2，TokenWorks 需要至少 0.2.x。
DeepSeek Harness（Web / Desktop）¶
- 在左側欄打開「插件」→「安裝插件」。
- 填入倉庫地址（推薦固定版本）：
github:Awenforever/dsh-ustc-quota#v1.0.9
安裝後 Host、插件清單和 Client slot 會即時生效。DSH 的 client-hmr 會把新 client 加載進舊頁面，插件會自行刷新一次頁面（每個版本一次）。首次安裝 v1.0.9 可能需要一次頁面重載或應用重啓，之後更新會自動檢測 Host 版本變化並 reload。
TokenWorks（詞元工坊）¶
- 在左側欄打開「插件」→ 點右上角「+ 添加插件」。
- 填入倉庫地址（固定版本）：
github:Awenforever/dsh-ustc-quota#v1.0.9
安裝/更新後插件會在舊頁面自行刷新一次。v1.0.9 首次安裝可能需要一次頁面重載或應用重啓來裝入 watchdog，之後 Host 版本變化會自動 reload。用學校統一身份登錄後，卡片會自動出現。
注意：TokenWorks 的插件頁「官方」只列出發行版自帶的插件，第三方插件（包括本插件）不會出現在「官方」裏，而是出現在「已安裝」區域。
配置¶
一般情況下不需要配置。插件會自動發現指向 USTC 網關的 @deepseek-ai/dsh-llm-pi-ai provider（DSH）或使用內置 tokenworksUsage 服務（TokenWorks）。
若自動發現失敗或使用的適配器不是 @deepseek-ai/dsh-llm-pi-ai，可以在 profile 的 cordis.patch.yml 裏覆蓋插件配置：
- id: dsh-ustc-quota
name: dsh-ustc-quota
config:
baseURLs:
- https://api.llm.ustc.edu.cn
refreshIntervalMs: 10000
resettingRefreshIntervalMs: 8000
requestTimeoutMs: 8000
cacheTtlMs: 8000
errorCacheTtlMs: 20000
providers:
my-ustc-key:
apiKeyEnv: MY_USTC_API_KEY
label: my-key
providers 裏的 apiKeyEnv 是憑據引用名（環境變量或 DSH credentials 中的名字），不是 Key 本身。baseURLs 支持 https://api.llm.ustc.edu.cn 或帶 /v1 的形式，插件會歸一到站點根。
安全說明¶
- Key 只在 Host 內使用：DSH 通過
credentials解析，TokenWorks 通過官方tokenworksUsage讀取，不會把 Key 發到瀏覽器。 - 快照只包含 provider id、顯示名、額度數值、重置時間、安全錯誤碼。
- 不轉發
key、key_alias、user_email、user_alias、platform_user_id、keys、teams。 - 在 Web host 上路由先過
ctx.connection.requestRejection；官方 Desktop / TokenWorks 窗口從dsh-app://加載，fetch 不一定攜帶瀏覽器 session，因此和 dsh-market 一樣在 Desktop host 上跳過這道 fence（只讀、無 Key 數據，路由仍只綁定本機 Web server）。
注意事項¶
- 本插件以當前 DSH/TokenWorks 進程權限運行，請安裝前檢查源碼與許可證。
/key/info、/user/info是 USTC LiteLLM 的內部接口，字段變化時插件會顯示安全錯誤但不會崩潰。- 12:00 / 00:00 邊界上平臺可能短暫返回舊用量，插件會把過期窗口標成「重置中」，8 秒後重查。
- 額度數值是平臺額度單位（當前 3h/12h/24h 爲 30/70/100），不是 DSH token 數，插件不擅自換算。
- 如果使用了自定義反代路徑，請在
baseURLs裏顯式添加。
結語¶
本插件爲 DSH 與 TokenWorks 用戶提供了一個常駐的 USTC 額度卡片，減少了切換查看額度的操作成本。安裝後卡片會出現在側邊欄底部，與「更新」或 Cordis 按鈕分行顯示，三列額度信息完整展示。
- 插件目錄頁：https://www.skillhub.cn/plugins/Awenforever/dsh-ustc-quota
- GitHub 倉庫：https://github.com/Awenforever/dsh-ustc-quota
