前言¶
DeepSeek Harness（DSH）採用插件化架構，通過組合配置與 UI 注入擴展功能。在智能體開發中，直接對接火山方舟（Volcengine Ark）的 Agent Plan 與 Coding Plan 套餐需要額外的路由配置與額度管理。該插件通過在 llm-pi-ai 適配器中聲明 Provider，並提供會話標題欄的額度 Pill 與模型管理頁面，解決了原生 DSH 對 Ark 套餐支持不足的問題。
核心功能¶
該插件主要解決以下問題：
* 模型接入：在 DeepSeek Harness 的模型選擇器中增加“火山方舟 Agent Plan”與“Coding Plan”兩個 Provider。
* 額度追蹤：在會話標題欄顯示每條車道的額度用量與刷新時間，避免跑滿後才發現。
* 精細控制：在設置頁逐條啓用或停用模型，隱藏不需要的模型。
安裝與啓用¶
安裝插件後，需要重啓對應的 profile（Web 端不能同時起兩個實例）。
dsh plugin --profile web add github:HaydenSmith1121/dsh-ark-plans
重啓後，依次完成以下步驟：
1. 打開 設置 → 模型，你會看到新增的兩個 Provider 行。
2. 點擊對應行的 API Key 輸入框，粘貼套餐的 API Key。
3. 回到對話頁，在模型選擇器中選擇方舟模型即可使用。
注意：API Key 會存儲在 $DSH_HOME/.credentials.yaml 的頂層 refs: 下，鍵名爲配置中聲明的引用名（如 ARK_AGENT_PLAN_API_KEY）。如果啓動 harness 的環境變量中存在同名變量，它會覆蓋頁面填寫的值（頁面會顯示只讀）。
額度顯示機制¶
會話標題欄右側會出現一個 Pill，每條車道一格，顯示進度條與已用百分比。
數據來源：
額度數據不在 OpenAI 兼容接口的 /usage 或 /quota 路徑中（實測返回 404）。真正的額度由控制面提供，插件通過 arkcli 在本地建立的身份（STS 或 AK-SK 簽名）調用控制面接口獲取。
狀態處理：
插件不會編造數字，當無法獲取額度時會顯示具體原因：
* expired：arkcli 的 SSO 憑證已過期，需運行 arkcli auth login volc-sso。
* no-identity：未找到 arkcli 身份。
* not-subscribed：該賬號下車道沒有生效訂閱。
* error：控制面簽名被拒絕。
在未登錄 arkcli 時，插件仍可正常調用模型，只是額度 Pill 顯示“不可用”並說明原因。
模型管理（啓用/停用）¶
插件 0.3.0 版本新增了設置頁面的模型管理功能。通過 設置 → 模型管理，可以勾選或取消勾選模型。
工作原理：
* 取消勾選會將模型 ID 從 dsh-ark-plans.enabledModelIds 中移除。
* 插件會在 llm-pi-ai.providers 的配置中動態調整模型清單，從而在模型選擇器中隱藏這些模型。
* 保存按鈕只在有改動時可點；寫入失敗會原地顯示原因，不會回滾勾選狀態。
邊界情況：
* 空清單代表“全開”（恢復默認），而非“全關”。
* 恢復全選必須列出完整的模型清單，因爲 pi-ai 的 models 字段是整表替換，不允許爲空。
模型清單與自定義¶
Agent Plan 車道：
該車道不支持模型發現接口，插件內置了 12 個已驗證模型 ID。這些 ID 是通過真實請求探測確認的，包括：
ark-code-latest, doubao-seed-evolving, doubao-seed-2-1-turbo, doubao-seed-2-0-lite, doubao-seed-2-0-mini, glm-5.3, glm-5-3-flash, kimi-k3, kimi-k2.7-code, minimax-m3, deepseek-v4-pro, deepseek-v4-flash。
Coding Plan 車道：
插件僅內置了官方文檔中的智能路由模型 ark-code-latest。如果需要添加其他模型，可以使用 arkcli plans model-list --plan coding-plan 獲取權威清單，並在 設置 → 模型 中手動編輯該 Provider 的 models 列表。
自定義模型：
你可以在 settings.yaml 中手動追加模型清單，這會整表替換該 Provider 的配置。注意，手動修改後若再點擊“保存”，會以頁面勾選狀態爲準。
已知限制¶
- 不支持圖片輸入：所有模型條目未聲明
input: [text, image]，輸入圖片會被 provider 拒絕。 - 不提供思考強度調節：雖然模型返回
reasoning_content，但插件未聲明reasoningEfforts，因此選擇器中無法調整思考強度，模型按默認強度運行。 - Provider 刪除限制：由於 pi-ai 的設計，組合層聲明的 Provider（如
ark-agent-plan）用戶無法通過設置頁刪除，只能通過卸載插件移除。 - 與 arkcli 衝突：
arkcli helper configure deepseek-harness與本插件會各自寫入配置，路由名不同（如arkcli-agent-planvsark-agent-plan），需注意不要混淆。
總結¶
該插件爲 DeepSeek Harness 提供了火山方舟 Agent Plan 與 Coding Plan 的完整接入方案。它利用官方 llm-pi-ai 適配器支持流式、工具調用與重試策略，並通過 arkcli 實現了準確的額度監控。對於需要使用火山方舟模型進行智能體開發的用戶，這是一個必要的配置補充。
