dsh-volcengine

DeepSeek Harness 的火山引擎（Volcano Engine / 火山方舟 Ark）插件组合包（bundle）。一个项目，两件事：

1. 调用模型 —— 通过 cordis.patch.yml 把内置的 @deepseek-ai/dsh-llm-pi-ai 配出两条 provider 路由，让火山方舟的模型进入模型选择器，直接驱动 agent：volcengine（按量付费 /api/v3，DeepSeek / GLM / 豆包 Doubao）与 volcengine-coding（方舟 Coding Plan /api/coding/v3，Kimi / MiniMax / GLM）。
2. 调用具体服务 —— 挂载本包自带的工具插件，用裸 fetch 调方舟的 OpenAI 兼容端点：

工具	作用	端点
volcengine_chat	调用任意方舟模型做一次性补全（文本 / 推理 / 多模态视觉）	POST /chat/completions
volcengine_image_generate	文生图（豆包 Seedream / 即梦）	POST /images/generations

volcengine_chat 传 images: [{ url }] 即可把图片发给视觉模型（url 支持 http/https 或 data: URI），模型用豆包 Seed 多模态系列（如 doubao-seed-2-1-pro-260628，文本 + 图片输入）。

为什么不用火山官方 SDK

方舟的 chat 与图片生成是 OpenAI 兼容 + Bearer API Key，官方自己也是让你用 OpenAI SDK 或直接 HTTP 调。裸 fetch 更轻、无签名负担，和 llm-deepseek 一致。签名鉴权的服务（语音 TTS/ASR、视频点播等）才需要官方 @volcengine/openapi——见下方 roadmap。

构建

源码是 TypeScript，用 tsdown 打包成 lib/index.js。@deepseek-ai/* 保持 external，运行时由宿主提供（避免重复拷贝导致的 Symbol 冲突）。

npm install     # 或 pnpm install
npm run build   # tsdown → lib/index.js
npm run typecheck   # tsc --noEmit（可选）

prepare 脚本就是 tsdown，所以 git 安装会自动构建；本地 checkout 安装前需先手动 npm run build。

安装

本地 checkout（开发时）

npm install && npm run build   # 先构建出 lib/index.js
dsh plugin --profile web add .
dsh web

从 GitHub 安装

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

git 安装会跑 prepare 自动构建（pnpm ≥10 首次会要求 allowBuilds，按提示把 dsh-volcengine: true 写进 profile 的 pnpm-workspace.yaml 后重跑）。

配置

API key 与模型 id 都在 cordis.patch.yml 的 volcengine 行里配置，可用你自己 profile 的 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

• 优先用 apiKeyEnv 引用环境变量（不要写死 key）；紧急情况下可写 apiKey。
• ARK_API_KEY 在启动环境中导出即可；baseURL 也可用 ARK_BASE_URL 覆盖。
• Coding Plan 路由（Kimi / MiniMax）用独立的 ARK_CODING_API_KEY，见下方「支持的模型」。

拿到 API key 与模型 id

1. 打开 火山方舟控制台，开通模型、创建 API Key（按量付费路由）。
2. 想用 Kimi / MiniMax，需订阅 方舟 Coding Plan，把 plan 密钥放到 ARK_CODING_API_KEY。
3. 模型 id 用控制台里显示的 模型 ID，或你创建的 接入点 ID（形如 ep-2024xxxxxxxx-xxxxx）——两者都能作为 model 传。
4. cordis.patch.yml 里预填的模型 id 只是示例，务必换成你账号里实际可用的 id。

支持的模型

cordis.patch.yml 预填了火山方舟各品牌当前 SOTA 模型，两条路由分开：

volcengine — 按量付费 /api/v3（完整 chat 模型目录）

品牌	模型 ID	名称	上下文	输入
DeepSeek 深度求索	deepseek-v4-pro-ga-260813	DeepSeek-V4-Pro	1M	文本
DeepSeek 深度求索	deepseek-v4-flash-ga-260731	DeepSeek-V4-Flash	1M	文本
智谱 Zhipu	glm-5-2-260617	GLM-5.2	1M	文本
智谱 Zhipu	glm-5-3-flash-260828	GLM-5.3-Flash	1M	文本 + 图片
豆包 Doubao	doubao-seed-2-1-pro-260628	Doubao-Seed-2.1-Pro	256K	文本 + 图片
豆包 Doubao	doubao-seed-2-1-turbo-260628	Doubao-Seed-2.1-Turbo	256K	文本 + 图片
豆包 Doubao	doubao-seed-evolving	Doubao-Seed-Evolving	256K	文本 + 图片
豆包 Doubao	doubao-seed-2-0-pro-260215	Doubao-Seed-2.0-Pro	256K	文本 + 图片
豆包 Doubao	doubao-seed-2-0-lite-260428	Doubao-Seed-2.0-Lite	256K	文本 + 图片
豆包 Doubao	doubao-seed-2-0-mini-260428	Doubao-Seed-2.0-Mini	256K	文本 + 图片
豆包 Doubao	doubao-seed-2-0-code-preview-260215	Doubao-Seed-2.0-Code	262K	文本 + 图片
豆包 Doubao	doubao-seed-1-8-251228	Doubao-Seed-1.8	256K	文本 + 图片
豆包 Doubao	doubao-seed-1-6-251015	Doubao-Seed-1.6	256K	文本
豆包 Doubao	doubao-seed-1-6-flash-250828	Doubao-Seed-1.6-Flash	256K	文本 + 图片
豆包 Doubao	doubao-seed-1-6-vision-250815	Doubao-Seed-1.6-Vision	256K	文本 + 图片
豆包 Doubao	doubao-seed-character-260628	Doubao-Seed-Character	256K	文本 + 图片

volcengine-coding — 方舟 Coding Plan /api/coding/v3

Kimi / MiniMax / GLM 只通过 Coding Plan 订阅提供（需单独的 plan 密钥）：

品牌	模型 ID	名称	上下文	输入
Kimi 月之暗面	kimi-k2.6	Kimi-K2.6	262K	文本 + 图片
Kimi 月之暗面	kimi-k2.7-code	Kimi-K2.7-Code	262K	文本 + 图片
MiniMax 稀宇	minimax-m3	MiniMax-M3	512K	文本 + 图片
智谱 Zhipu	glm-5.3-flash	GLM-5.3-Flash	1M	文本 + 图片

模型 id 只是示例，务必换成你账号里实际可用的 id / 接入点 ep-xxx（尤其按量付费路由，模型随方舟上下架会变）。

为什么不给模型配「思考」开关？ 方舟的 chat 接口只接受 system/assistant/user/tool 四种消息角色，而 pi-ai 对推理型模型会把系统提示当 developer 角色发送，方舟会回 400 InvalidParameter。所以本插件的模型一律按非推理模型声明：系统提示走 system 角色（正常可用），模型在方舟侧仍按各自默认行为出结果（推理内容照常在 reasoning_content 返回）。这是方舟 + pi-ai 的已知限制，等方舟支持 developer 角色后可放开思考开关。

模型选择

安装后，模型选择器里会出现 Volcano Ark、Volcano Ark Coding Plan 及上述路由里的模型；会话里切过去即可让 agent 用火山模型。想设为默认模型，改 agent-default-model 行或直接在 Web 模型页选择。

Roadmap（方舟其它能力，暂未接工具）

方舟除了 chat 模型，还有这些能力，本插件目前只接了 chat + 文生图：

• 文生图（Seedream / 即梦） —— 已有 volcengine_image_generate；新模型如 doubao-seedream-5-0-pro-260628、doubao-seedream-4-5-251128 可直接传 model 使用。
• 视频生成（Seedance） —— seedance 2.0 / 2.0-fast / 2.5 等。
• Embeddings —— doubao-embedding-large-text、doubao-embedding-vision-251215。
• Rerank —— jina-reranker、bge-reranker-v2-m3 等。
• 语音合成 / 识别（TTS / ASR） —— 走豆包语音 WebSocket V3 + appid/access token，需引入官方 @volcengine/openapi。

这些需要各自新增工具（/embeddings、/rerank、视频/语音端点等），需要的话可以按需加。

上传到 GitHub

cd dsh-volcengine
git init
git add .
git commit -m "init: dsh-volcengine bundle"
git branch -M main
git remote add origin https://github.com/<you>/dsh-volcengine.git
git push -u origin main

然后别人（或你自己换机器）就能用 dsh plugin --profile web add github:<you>/dsh-volcengine 安装。

许可

MIT