dsh-volcengine
DeepSeek Harness 的火山引擎（Volcano Engine / 火山方舟 Ark）插件组合包（bundle）。一个项目，两件事：
- 调用模型 —— 通过
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）。
- 调用具体服务 —— 挂载本包自带的工具插件，用裸
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）或 DeepSeek V4.1-Flash（deepseek-v4-1-flash-260910，原生视觉理解）都可以。
为什么不用火山官方 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 后重跑）。
桌面 App（desktop profile）
桌面 App 的插件页只收 npm registry 的包名（packageNameFromSpec 直接拒绝 file:、路径和 URL），本地 checkout 的 bundle 装不进去，要按 App 自己的校验规则手工装进 ~/.dsh/profiles/desktop：
npm run build && npm pack，把 tarball 放进 profile 的 vendor/。package.json：dependencies 必须是精确版本（"dsh-volcengine": "0.2.3"，即本包 package.json 的 version；link: / file: 会被 projectManifest 判为非法），dsh.profile.bundles 追加 "dsh-volcengine"。pnpm-workspace.yaml 加 overrides 把这个版本指到本地 tarball，再用 App 自带的 node/pnpm 跑一次 pnpm install --ignore-scripts；pnpm 会解出 node_modules/dsh-volcengine 真目录（软链会被 validateDesktopPluginGraph 拒绝）并生成 pnpm-lock.yaml（App 将来重建 profile 时走 --frozen-lockfile）。- 重启 App 生效。
改了内容就要 bump 版本号：lockfile 用 sha512 钉住 tarball，同名覆盖会以 ERR_PNPM_TARBALL_INTEGRITY 拒绝（正是 App 重建 profile 走的那条路）。bump 后重新 npm pack 并重装，lock 会跟着更新。
peerDependencies 不能写 "*"：App 用 semver.satisfies 校验，prerelease 宿主（0.1.0-rc.20）不满足 *，整个 profile 会被 requires @deepseek-ai/dsh-tools@*, found 0.1.0-rc.20 拒绝启动。写 ">=0.1.0-rc.0"。
两个工具从 process.env 读 key（不吃托管凭据）：把 ARK_API_KEY=... 放进 ~/.dsh/.env（App 启动时按 项目 .env > ~/.dsh/.env 载入）。模型路由走托管凭据，~/.dsh/.credentials.yaml 里有 ARK_API_KEY 即可。
配置
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
- 打开 火山方舟控制台，开通模型、创建 API Key（按量付费路由）。
- 想用 Kimi / MiniMax，需订阅 方舟 Coding Plan，把 plan 密钥放到
ARK_CODING_API_KEY。
- 模型 id 用控制台里显示的 模型 ID，或你创建的 接入点 ID（形如
ep-2024xxxxxxxx-xxxxx）——两者都能作为 model 传。
cordis.patch.yml 里预填的模型 id 只是示例，务必换成你账号里实际可用的 id。
支持的模型
cordis.patch.yml 预填了火山方舟各品牌当前 SOTA 模型，两条路由分开：
volcengine — 按量付费 /api/v3（完整 chat 模型目录）
| 品牌 | 模型 ID | 名称 | 上下文 | 输入 |
|---|
| DeepSeek 深度求索 | deepseek-v4-1-flash-260910 | DeepSeek-V4.1-Flash | 1M | 文本 + 图片 |
| 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 |
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
