前言¶
DeepSeek Harness (DSH) 採用插件化架構，旨在通過擴展功能提升開發與調試效率。dsh-ark-balance 是一款掛件類插件，解決在 Web 界面查看火山方舟協作獎勵計劃免費資源包餘量的痛點。它直接複用官方 CLI 的數據源，無需額外登錄或配置 Key，常駐顯示在瀏覽器中。
插件信息¶
- 名稱：dsh-ark-balance
- 維護者：key8023lala
- 許可證：MIT
- Star 數：1
- 倉庫：https://github.com/key8023lala/dsh-ark-balance
前置條件¶
在安裝插件前，需確保本地已安裝官方 CLI 並完成登錄。插件會調用 CLI 獲取數據。
# 安裝 CLI
npm i -g @volcengine/ark-cli@latest
# 登錄授權（建議使用 volc-sso 掃碼）
arkcli auth login volc-sso
# 驗證登錄狀態
arkcli auth status
# 驗證數據獲取（能看到 JSON 即表示就緒）
arkcli usage balance --type free-quota
安裝與啓用¶
DSH 的插件通過命令行安裝。安裝後需重啓 Web 服務使掛件生效。
# 安裝插件
dsh plugin --profile web add dsh-ark-balance
# 重啓 dsh web 服務
# 然後在瀏覽器中刷新頁面（F5）
核心功能¶
- 官方視覺風格：懸浮圖標與標題欄使用火山方舟官方圖標（console.volcengine.com/ark 的 favicon），保持純白底色，無多餘特效。
- 可拖拽與位置記憶：摺疊態可拖拽圖標，展開態可拖拽卡片頭部。位置自動保存至
localStorage，並自動避讓視口邊緣。 - 模型分類與篩選：每個模型自動分類（文本、多模態、圖片、視頻、3D、代碼、翻譯、角色、向量）並顯示彩色徽標。支持按類型和廠商進行多選篩選，廠商名自動簡稱。
- 排序與發佈日期：支持按剩餘量、發佈日期（新→舊）、名稱排序。發佈日期從
primary_version解析，目錄緩存 6 小時。 - 疊加口徑展示：顯示總量與剩餘量，該數值爲「免費推理 + 數據權限」兩類資源包的疊加值。meta 行會顯示兩類拆分詳情。
- 固定高度與防抖動：卡片高度固定爲
min(560px, 70vh)，篩選操作不會導致窗口跳動。 - 刷新機制：支持 60 秒自動刷新與手動刷新（右上角 ↻）。宿主側緩存機制避免重複調用 API。
- 低餘量提醒：
- 懸浮圖標角標實時計數。
- 模型疊加剩餘跌破閾值（默認 20 萬 token）時彈出「餘量 / 耗盡」提醒卡片。
- 僅狀態躍遷觸發提醒，回升自動重置，不會頻繁轟炸。
- 支持一鍵只看告警，並在設置中調整閾值。 - 優雅降級：如果未安裝 CLI 或未登錄，界面會顯示安裝與登錄引導。
- 零依賴：純 Node ESM 模塊，無任何運行時依賴。
- 憑據零接觸：完全複用 CLI 登錄態，插件不讀取、不存儲、不上傳任何 Key。
使用方法¶
- 啓動與顯示：重啓
dsh web後，瀏覽器左下角會出現火山方舟圖標（摺疊態）。 - 拖拽佈局：按住圖標或展開後的卡片頭部，將其拖拽至屏幕任意位置。位置會被自動記住。
- 查看詳情：點擊圖標展開卡片。卡片頂部顯示工具欄（類型多選、廠商多選、排序下拉）。列表每行展示模型名、類型徽標、剩餘/總量、進度條、發佈日期及已用拆分（免費推理 / 數據權限）。
- 刷新數據：點擊右上角的 ↻ 按鈕手動刷新；系統每 60 秒自動刷新一次。
- 管理提醒：
- 點擊卡片頭部左側的 ⚠ 按鈕，可篩選出低餘量模型。
- 點擊 ⚙ 按鈕，可開啓/關閉提醒、調整閾值（萬 token）、預覽或清除已提醒記錄。
- 當模型剩餘跌破閾值時，右下角彈出提醒卡片，點擊「查看」可跳轉至告警列表。
數據來源¶
數據來源於 @volcengine/ark-cli 的內部命令。
# 數據獲取命令
arkcli usage balance --type free-quota --format json --page-size 200
資源包按 type 分爲兩類：
- FreeInference：免費推理額度（協作獎勵）。
- DataPermission：數據權限額度（如聲音復刻）。
發佈日期信息通過 models search 目錄拉取並緩存 6 小時。
注意事項¶
- 權限：插件以當前 DSH 進程的權限運行，請確保已安裝並登錄
arkcli。 - 刷新延遲：數據刷新延遲由
arkcli上游控制，控制台通常存在 5–30 分鐘的延遲。 - 驗證安裝：可通過以下命令驗證插件是否正確加載：
dsh --profile web --dump-config | Select-String "ark-balance"
- 生態說明：此插件託管於獨立社區目錄，與 DeepSeek 或火山引擎無官方隸屬關係，數據以官方控制台爲準。
