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