前言¶
DeepSeek Harness（DSH）可以在「設置 → 模型」裏手填 provider，但火山方舟 Ark 的 Agent Plan、Coding Plan、後付費 API 各自對應不同的 Base URL、協議和模型 id，抄錯一個字段就會連不上。下面介紹社區插件 ark-plan-api（維護者 BaChongYingovo，分類：模型推理）：它通過 bundle 補丁預置五條 Ark provider 路由，裝好後這些套餐會直接出現在 DSH 原生模型列表裏，你只需填入對應套餐的 API Key。默認走 Anthropic Messages API（anthropic-messages），與 Ark plan / coding 端點一致。
這是什麼¶
ark-plan-api 是 DSH 的一個 bundle 插件。它在 @deepseek-ai/dsh-llm-pi-ai 上通過 cordis.patch.yml 註冊火山引擎 Ark 的五條 provider 路由（含國內與 BytePlus 海外），並可選提供 Web 側「填 API Key」頁。服務端 index.js 的 apply 爲空函數，實際推理仍由 DSH 自帶的 pi-ai 適配器發出；插件只貢獻配置，不讀憑據、不發請求。
- 倉庫：https://github.com/BaChongYingovo/ark-plan-api
- 目錄頁：https://www.skillhub.cn/plugins/BaChongYingovo/ark-plan-api
- 許可證：MIT（README 與 package.json）
- 當前版本：0.2.1（package.json）
- 運行環境：Node.js >= 20
已註冊的 Provider 路由¶
裝好後會出現五個 Provider ID，Key 需與套餐一致（混用會 401）。
| Route（Provider ID） | 定位 | Base URL | 協議 |
|---|---|---|---|
ark-agent-plan-cn |
Agent Plan | https://ark.cn-beijing.volces.com/api/plan |
anthropic-messages |
ark-coding-plan-cn |
Coding Plan | https://ark.cn-beijing.volces.com/api/coding |
anthropic-messages |
ark-coding-plan-byteplus |
Coding Plan 海外 | https://ark.ap-southeast.bytepluses.com/api/coding |
anthropic-messages |
ark-cn |
後付費 API | https://ark.cn-beijing.volces.com/api/v3/compatible |
anthropic-messages |
ark-byteplus |
後付費 API 海外 | https://ark.ap-southeast.bytepluses.com/api/v3/compatible |
anthropic-messages |
說明：Base URL 不含 /v1 後綴，由 Anthropic SDK 自行追加 /v1/messages。
各 route 預置了一批模型 id（如 doubao-seed-2.1-pro、deepseek-v4-pro 等），可在 cordis.patch.yml 裏增刪。doubao-seed-* 系列支持多模態輸入 input: [text, image]。完整模型列表見倉庫 README 表格。
安裝與啓用¶
插件需加入 profile 的 bundles 並重啓 DSH 宿主；僅寫在 dependencies 裏不夠。
從本地目錄裝入¶
在已有插件目錄的前提下（例如放在 ~/dsh-plugins/ark-plan-api），執行：
dsh plugin --profile desktop add ~/dsh-plugins/ark-plan-api
dsh --profile desktop # 重啓 DSH
dsh plugin add 會把目錄寫入 profile 的 dependencies，並自動加入 bundles。
從 tarball 裝入¶
在插件源碼目錄打包後安裝：
npm pack # 產出 ark-plan-api-0.1.0.tgz（示例文件名以實際爲準）
dsh plugin --profile desktop add ./ark-plan-api-0.1.0.tgz
手動登記¶
編輯 $DSH_HOME/profiles/<profile>/package.json，在 dependencies 與 dsh.bundles 中加入 ark-plan-api，然後在 profile 目錄執行 pnpm install 並重啓。
檢查是否裝好¶
dsh --profile desktop --dump-config | grep -A2 llm-pi-ai # 應看到 "patched by ark-plan-api"
卸載：
dsh plugin --profile desktop remove ark-plan-api
若使用 0.2.0 曾出現啓動失敗（client.js 未聲明 remote），應升級到 0.2.1；README 說明了臨時從 dsh.bundles 移除以救急的做法。
填寫 API Key¶
憑據寫入 DSH 憑據庫（$DSH_HOME/.credentials.yaml），與「設置 → 模型」手填等價。憑據名由 provider id 派生，例如 ark-agent-plan-cn → ARK_AGENT_PLAN_CN_API_KEY：
PROVIDER_ID.toUpperCase().replace(/[^A-Z0-9]+/g, '_') + '_API_KEY'
也可用同名環境變量；存儲值優先於環境變量。
路徑一（推薦）：側欄 插件 → 插件列表 → ark-plan-api 行尾 填 API Key。頁面按五張卡片區分套餐，顯示憑據名與「已配置 / 未配置」，不回顯 Key；保存即時生效，無需重啓（首次安裝插件本身仍需重啓以加載 client.js）。
路徑二：設置 → 模型，選中對應 Ark route 粘貼 Key。若宿主未暴露憑據服務或沒有 plugins.row.config 插槽，用此路徑即可。
各套餐 Key 在火山方舟控制台申請（README 給出 Agent Plan、Coding Plan、後付費 API Key 的控制台鏈接）。
工作原理（簡述）¶
- 在 cordis 中
insert空載插件條目，滿足插件列表與市場入口文件要求。 - 對
llm-pi-ai行補丁寫入config.providers，作爲設置的 base 層，與用戶settings.yaml按 provider 逐鍵深合併；不會在深合併意義上覆蓋你手加的同名 provider 的自定義字段。 client.js僅在瀏覽器側註冊「填 API Key」頁，通過宿主ctx.remote.credentials讀寫憑據。
自定義¶
直接編輯倉庫內 cordis.patch.yml 後重啓 DSH。可改 displayName、apiKeyEnv、api、baseURL、models（id 可爲方舟推理接入點 ep-xxxxxxxx），或複製整段 route 增地區/套餐。改完後可在插件目錄運行 npm run check 做結構自檢（README「開發與自檢」一節）。
適用場景與注意¶
適合：已在火山方舟開通 Agent Plan、Coding Plan 或後付費 API，希望在 DSH 裏用原生模型選擇器切換 Doubao / DeepSeek 等預置模型，且不想逐個抄 Base URL 與模型表的用戶。
注意：
- 插件以當前 DSH 進程權限運行；安裝前請自行查看源碼與 MIT 許可證，社區目錄（SkillHub）與 DeepSeek / 幻方無官方從屬關係。
- Key 必須對 route：Agent Plan 的 Key 不能用於
ark-cn後付費 route。 - 裝完列表沒有 Ark 時，覈對 profile、
bundles、重啓宿主，並用--dump-config確認patched by ark-plan-api。 - 0.2.0 有啓動兼容問題，請用 0.2.1。
結尾¶
ark-plan-api 把五條火山方舟 Ark 路由和模型表打進 DSH 的 pi-ai 配置底層，把「抄配置」收成「選 route、填 Key」。需要細節、變更記錄與自檢命令時，見 GitHub 倉庫 與 SkillHub 目錄頁。
