前言¶
DeepSeek Harness (DSH) 是一個插件化平臺，開發者通常通過本地命令行工具 arkcli 查看火山方舟的 Agent Plan 用量。本插件在 DSH 的 Web UI 左側邊欄底部添加了一張可視化卡片，直接從本機 arkcli 獲取數據並展示用量情況，避免頻繁切換終端。
插件概覽¶
- 名稱：
dsh-ark-plan-usage - 維護者：Barry-Liu-001
- 許可證：MIT
- 核心功能：在側邊欄實時展示 5h/周/月 用量，支持展開/收起（軌道模式），提供顏色編碼和一鍵重登錄。
前置條件¶
在安裝前需滿足以下條件：
- DSH 版本：0.1.1-rc.x（Web profile）。
- arkcli 狀態：已安裝
arkcli並登錄（arkcli auth status返回logged_in: true）。 - 訂閱權限：當前 DSH profile 持有 Agent Plan 訂閱。
安裝與啓用¶
通過 DSH 的插件管理命令安裝：
dsh plugin --profile web add github:Barry-Liu-001/dsh_ark_plan_usage
安裝完成後，重啓 DSH Web（dsh web），在左側邊欄底部即可看到用量卡片。
功能說明¶
- 實時展示：卡片顯示 5 小時總量的進度條、百分比、已用/總量及重置時間，下方附帶周/月用量小進度條。
- 軌道模式：
- 展開：顯示完整信息（圖標、進度條、數據）。
- 收起：僅顯示六邊形小圖標和百分比，鼠標懸停顯示完整信息。 - 顏色編碼：
- 綠色：< 50%
- 黃色：50% - 80%
- 紅色：≥ 80%
（主條、周/月條、圖標統一閾值） - 數據緩存：服務端採用 5 分鐘內存緩存，與
arkcli調用節奏一致。點擊卡片可強制刷新。拉取失敗時保留舊數據並標註stale。 - SSO 憑證處理：當 SSO 憑證過期時，卡片錯誤區會出現「重新登錄」按鈕。點擊後 host 會自動執行
arkcli auth login volc-sso打開瀏覽器進行授權，授權完成後自動刷新數據。
工作原理¶
插件通過 cordis.patch.yml 向 Loader 樹插入 Node 服務（arkPlanUsage Typert Remote），瀏覽器端通過 RPC 調用該服務。
數據獲取流程如下：
- 瀏覽器側邊欄卡片調用
ctx.remote.arkPlanUsage.getUsage()。 - Node 端
ArkPlanUsageService檢查緩存：
- 若緩存有效（< 5 分鐘），直接返回。
- 若緩存過期，執行arkcli usage balance --type plan --format json（超時 20 秒）。 - 解析 JSON 並返回結果。
錯誤處理場景包括：未找到 arkcli、SSO 過期、調用超時等，均會在界面上給出相應提示或操作入口。
配置與開發¶
環境變量¶
若 arkcli 不在默認路徑（/opt/homebrew/bin/arkcli、/usr/local/bin/arkcli、~/.local/bin/arkcli、/usr/bin/arkcli），可通過環境變量指定：
export ARK_PLAN_USAGE_ARKCLI=/path/to/arkcli
# 或
export ARKCLI_BIN=/path/to/arkcli
開發模式¶
插件零構建，依賴 DSH 宿主能力。
若使用本地源碼安裝（dsh plugin --profile web add /path/to/dsh-ark-plan-usage），需補軟鏈以解決 Node 模塊解析問題：
mkdir -p node_modules
ln -sfn ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai
修改 client.js 後刷新瀏覽器即可；修改 index.js 或 cordis.patch.yml 需重啓 dsh web。
卸載¶
dsh plugin --profile web remove dsh-ark-plan-usage
總結¶
該插件通過在 DSH 側邊欄嵌入可視化卡片，解決了開發者查看 Agent Plan 用量需頻繁操作終端的問題。其具備零構建、零運行時依賴的特點，集成 SSO 憑證管理功能，適合需要在 Web 界面實時監控配額的開發者使用。
