dsh-volcengine: DeepSeek Harness 的火山引擎（Ark）插件組合包

前言¶

DeepSeek Harness（DSH）通過插件化架構支持靈活擴展。在集成火山引擎（Volcano Engine / 火山方舟 Ark）時，開發者需要處理 API Key、模型路由和 OpenAI 兼容接口的適配。dsh-volcengine 是一個現成的插件組合包，它通過 DSH 的 cordis.patch.yml 配置文件，將方舟的模型路由注入到 DSH 的模型選擇器中，並提供工具插件以調用文生圖和視覺模型。

核心功能¶

本插件包含兩個主要部分：

模型路由：通過 cordis.patch.yml 配置兩條 provider 路由，將火山方舟的模型接入 DSH 模型選擇器。
- volcengine：按量付費路由，調用 /api/v3 端點，支持 DeepSeek、GLM、豆包（Doubao）等品牌。
- volcengine-coding：方舟 Coding Plan 路由，調用 /api/coding/v3 端點，支持 Kimi、MiniMax、GLM 等。
工具插件：掛載自帶的工具插件，使用裸 fetch 調用方舟的 OpenAI 兼容端點。
- volcengine_chat：調用任意方舟模型進行一次性補全（支持文本、推理、多模態視覺）。
- volcengine_image_generate：調用文生圖模型（Seedream/即夢）。

安裝¶

安裝方式取決於 DSH 運行的 Profile（Web 或桌面 App）。

Web Profile¶

使用 GitHub 倉庫安裝：

dsh plugin --profile web add github:you/dsh-volcengine

Desktop Profile¶

桌面 App 僅支持從 npm registry 安裝，不支持 file:、路徑或 URL。本地開發時需要手動構建並配置：

構建與打包：

    npm run build && npm pack

放置文件：將生成的 tarball 文件放入 ~/.dsh/profiles/desktop/vendor/ 目錄。
修改配置：在 package.json 中修改 dependencies 爲精確版本（如 "dsh-volcengine": "0.2.3"），並在 dsh.profile.bundles 中追加 "dsh-volcengine"。
配置依賴：在 pnpm-workspace.yaml 中添加 overrides 指向該本地 tarball。
安裝：在 App 的 Node/Pnpm 環境中運行 pnpm install --ignore-scripts。
重啓：重啓 App 生效。

注意：修改內容後需 bump 版本號並重新打包，因爲 lockfile 會通過 sha512 釘住 tarball 完整性。

配置¶

API Key 和模型 ID 的配置都在 cordis.patch.yml 中進行。你可以通過覆蓋本包提供的默認配置來修改。

基礎配置示例¶

- id: volcengine
  config:
    apiKeyEnv: ARK_API_KEY       # 存放 API Key 的環境變量名
    baseURL: https://ark.cn-beijing.volces.com/api/v3
    chatModel: deepseek-v4-pro-ga-260813
    imageModel: doubao-seedream-4-0-250828

Coding Plan 配置¶

如果需要使用 Kimi / MiniMax 等模型，需單獨配置 Coding Plan 路由，並使用獨立的 ARK_CODING_API_KEY。

獲取 Key 與模型 ID¶

登錄火山方舟控制台，開通模型並創建 API Key（按量付費路由）。
若使用 Coding Plan，需訂閱並獲取 Coding Plan 密鑰。
重要：cordis.patch.yml 中的模型 ID（如 deepseek-v4-pro-ga-260813）僅爲示例，必須替換爲你賬號控制台裏實際可用的模型 ID 或接入點 ID（ep-xxx）。

典型用法¶

調用視覺模型¶

通過 volcengine_chat 工具，在 images 參數中傳遞圖片 URL 即可調用視覺模型。

- id: volcengine_chat
  config:
    model: deepseek-v4-1-flash-260910  # 支持多模態的模型 ID
    apiKeyEnv: ARK_API_KEY

調用時傳入：

{
  messages: [...],
  images: [{ url: "https://example.com/image.jpg" }]
}

文生圖¶

使用 volcengine_image_generate 工具生成圖片。

- id: volcengine_image_generate
  config:
    model: doubao-seedream-4-0-250828
    apiKeyEnv: ARK_API_KEY

技術實現與限制¶

架構設計¶

輕量級：插件使用原生 fetch 調用方舟的 OpenAI 兼容端點，而非官方 SDK。這避免了簽名鑑權的負擔，降低了包體積。
依賴處理：@deepseek-ai/* 系列依賴被標記爲 external，由宿主提供，避免運行時 Symbol 衝突。
構建：使用 tsdown 打包，prepare 腳本會在 git 安裝時自動執行構建。本地開發 checkout 時需先手動運行 npm run build。

限制說明¶

桌面 App 限制：桌面 App 僅支持 npm registry 包名，且 peerDependencies 不能寫 "*"（必須寫具體版本範圍），否則會因爲版本不匹配導致 Profile 無法啓動。
模型路由：方舟的 chat 接口不支持 developer 角色發送系統提示（用於推理模型）。因此本插件在配置模型時按非推理模型處理（系統提示走 system 角色），但模型本身仍可返回 reasoning_content。
未覆蓋服務：目前插件僅支持 Chat 和文生圖。語音合成（TTS）、語音識別（ASR）、視頻點播、Embeddings、Rerank 等需要官方 SDK 的服務暫未接入。

Roadmap¶

後續計劃根據需求擴展以下能力：
* 視頻生成：Seedance 系列。
* Embeddings：文本與視覺 Embedding 模型。
* Rerank：重排序服務。
* 語音服務：豆包語音 WebSocket V3（需引入官方 SDK）。

許可證¶

MIT