dsh-volcengine

dsh-volcengine

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

1. 调用模型 —— 通过 cordis.patch.yml 把内置的 @deepseek-ai/dsh-llm-pi-ai 配出三条 provider 路由，让火山方舟的模型进入模型选择器，直接驱动 agent：

   路由	计费	Base URL	内容
   volcengine	按量付费（后付费）	https://ark.cn-beijing.volces.com/api/v3	完整 chat 模型目录（DeepSeek / GLM / 豆包）
   volcengine-agent-plan	Agent Plan 订阅（AFP 抵扣）	https://ark.cn-beijing.volces.com/api/plan/v3	全模态 + Harness 套餐的文本模型目录
   volcengine-coding	Coding Plan 订阅	https://ark.cn-beijing.volces.com/api/coding/v3	编程模型目录 + 控制台托管的 ark-code-latest（Auto）

2. 调用具体服务 —— 挂载本包自带的工具插件，用裸 fetch 调方舟的 OpenAI 兼容端点：

volcengine_chat 传 images: [{ url }] 即可把图片发给视觉模型（url 支持 http/https 或 data: URI）：豆包 Seed 多模态系列（如 doubao-seed-2-1-pro-260915）或 DeepSeek V4.1-Flash（deepseek-v4-1-flash-261017，原生视觉理解）都可以。工具走按量付费的 /api/v3，不吃订阅套餐额度。

为什么不用火山官方 SDK

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

构建

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

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

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

安装

本地 checkout（开发时）

npm install && npm run build   # 先构建出 lib/index.mjs
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：

1. npm run build && npm pack，把 tarball 放进 profile 的 vendor/。
2. package.json：dependencies 必须是精确版本（"dsh-volcengine": "0.3.0"，即本包 package.json 的 version；link: / file: 会被 projectManifest 判为非法），dsh.profile.bundles 追加 "dsh-volcengine"。
3. 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）。
4. 重启 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 里配置，可用你自己 profile 的 cordis.patch.yml 覆盖。三条路由各有一段 llm-pi-ai.providers 配置：

- id: llm-pi-ai
  config:
    providers:
      volcengine:
        displayName: Volcano Ark
        apiKeyEnv: ARK_API_KEY
        api: openai-completions          # 按量付费路由沿用 chat 协议
        baseURL: https://ark.cn-beijing.volces.com/api/v3
        models: [ ... ]
      volcengine-agent-plan:
        displayName: Volcano Ark Agent Plan
        apiKeyEnv: ARK_AGENT_PLAN_API_KEY # Agent Plan 专属 key，和另两条不通用
        api: openai-responses
        baseURL: https://ark.cn-beijing.volces.com/api/plan/v3
        models: [ ... ]
      volcengine-coding:
        displayName: Volcano Ark Coding Plan
        apiKeyEnv: ARK_API_KEY           # 换成 ARK_CODING_API_KEY 即可用独立密钥
        api: openai-responses
        baseURL: https://ark.cn-beijing.volces.com/api/coding/v3
        models: [ ... ]

• 优先用 apiKeyEnv 引用环境变量（不要写死 key）；紧急情况下可写 apiKey。

• 两套套餐是两套 key，不能混用。实测：Agent Plan 的 key 在 /api/plan/v3 上是 200，在 /api/coding/v3、/api/v3 上是 401；而按量付费那把 key 反过来。所以：

  路由	默认读的变量	说明
  volcengine	ARK_API_KEY	按量付费后付费 key
  volcengine-agent-plan	ARK_AGENT_PLAN_API_KEY	在 Agent Plan 页面创建的专属 key
  volcengine-coding	ARK_API_KEY	你账号里带 Coding Plan 权益的那把；若是独立 key 就改指 ARK_CODING_API_KEY

• 401 不等于 key 写错了：某条路由上没有权益时返回的也是 401 AuthenticationError（"The API key or AK/SK in the request is missing or invalid"），和 key 格式错误长得一样。先确认套餐订阅与 key 归属，再考虑轮换。

• Tool 插件单独有一段 volcengine 行，配置 chatModel / imageModel 和它自己读的 apiKeyEnv（默认 ARK_API_KEY），baseURL 也可用 ARK_BASE_URL 覆盖。

• 别串端点：套餐模型必须走 /api/plan/v3 或 /api/coding/v3。把套餐模型指到 /api/v3 不会消耗套餐额度，而是按量计费；反过来后付费模型走套餐端点会 404/无权限。

拿到 API key 与模型 id

1. 打开 火山方舟控制台。每个套餐各自签发 key，要用哪条路由就去对应页面的 API Key 处创建。
2. 想用 Agent Plan：到 开通管理-Agent Plan 订阅（专属入口也见 Agent Plan 活动页），把它签发的 key 放进 ARK_AGENT_PLAN_API_KEY。
3. 想用 Coding Plan：到方舟 Coding Plan 活动页订阅，把 key 放进 ARK_CODING_API_KEY（或复用它所在的 ARK_API_KEY）。
4. 模型 id 用本包预填的 Model Name（deepseek-v4.1-flash 这类），也可以换成控制台里的 接入点 ID（形如 ep-2024xxxxxxxx-xxxxx）。
5. 订阅/换 key 之后如果仍 401，先分别单独打一次两个端点确认 key 与套餐的对应关系，再回头改配置。

官方文档

• Agent Plan 个人版 · DeepSeek Harness 接入
• Coding Plan 个人版 · DeepSeek Harness 接入
• Agent Plan 套餐概览（支持模型及 Harness）
• Coding Plan 套餐概览（支持的模型）

支持的模型

cordis.patch.yml 预填了火山方舟各品牌当前 SOTA 模型，三条路由分开。下面两张套餐表里的每一项都用真实 key 在 /api/coding/v3 上逐个验过（模型 id 可用、maxTokens 不超过该模型接受的 max_completion_tokens 上限、声明为多模态的模型接受 image_url 输入），并已在 2026-10-21 于 /api/plan/v3 与 /api/coding/v3 上各重验一次。按量付费那张表则以 GET /api/v3/models（2026-10-21 快照：54 个未下线条目）为准对齐，新加的 id 都在 /api/v3 上实调过一次，声明多模态的带图调用。查新模型的方法见下方「怎么知道方舟上新了」。

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

按量付费路由的 id 带日期（随方舟上下架会变），务必换成你账号里实际可用的 id / 接入点 ep-xxx。

三点例外：

• deepseek-v4-1-flash-economy-261017（经济版）与标准版同一套权重、效果一致，价格更低、生成略慢；本包已在 /api/v3 上实调验证（文本 + 图片）。
• doubao-seed-2-0-pro-260215 已被方舟标记为即将下线（Retiring），新会话建议改用 doubao-seed-2-1-pro-260915。
• 豆包 1.6 / 1.8 系列（doubao-seed-1-8-251228、doubao-seed-1-6-251015、doubao-seed-1-6-flash-250828、doubao-seed-1-6-vision-250815）已被方舟 Shutdown，调用返回 InvalidEndpointOrModel.NotFound，因此已从本包移除。

开通是按账号 × 按模型独立生效的：一个 id 即便出现在方舟目录里，账号没在控制台开通它，调用仍会返回 ModelNotOpen: Your account ... has not activated the model ...。验证账号上 doubao-seed-evolving 就处于这种状态（模型本身在方舟正常在售）。遇到这个报错去 方舟控制台 的「开通管理」里勾上该模型即可，不必改配置。

volcengine-agent-plan — 方舟 Agent Plan /api/plan/v3

订阅套餐，按 Agent 燃料值（AFP）抵扣。全部 14 个文本模型如下（kimi-k3 与 Computer Use Agent 仅 Medium 及以上套餐可用，其余 Small 起就有）：

minimax-m3 与 kimi-k2.7-code 已被方舟标注即将下线，仍可用但建议尽早切走。

套餐 id 不带日期，方舟会自动把它解析到最新快照——实测 deepseek-v4.1-flash-economy 返回的 model 字段是 deepseek-v4-1-flash-economy-261017。所以按量付费那侧每次上新都要改 id，套餐这侧只有在套餐增减模型时才需要动。

套餐还带图片生成（doubao-seedream-5-0-pro）、视频生成（doubao-seedance-2.0 / 2.0-fast / 2.0-mini / 2.5，Large 起）、向量化（doubao-embedding-vision）、语音（doubao-seed-tts-2.0 / doubao-seed-asr-2.0）和 Harness（专业数据集、豆包搜索、Agent 记忆等）。这些不是 chat 模型，模型选择器驱动不了；图片生成可用本文的 volcengine_image_generate（走按量付费），其余需要另接端点。

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

与 Agent Plan 同一批文本模型 id，外加控制台托管的 ark-code-latest：

ark-code-latest 是「你在开通管理里选定的模型 / Auto 模式」的别名，背后的模型会变，所以它的容量按保守值声明；要固定行为就直接选具体模型 id。

deepseek-v4.1-flash-economy 是 2026-10-20 加进两个套餐的：与标准版同权重，AFP 抵扣系数更低（活动期内 5 折），适合不在意生成速度的场景。

怎么知道方舟上新了

方舟没有 RSS，但按量付费端点有一个 OpenAI 兼容的模型清单接口，用它比对最省事：

curl -s https://ark.cn-beijing.volces.com/api/v3/models \
  -H "Authorization: Bearer $ARK_API_KEY" \
| python3 -c 'import json,sys,datetime
rows=[m for m in json.load(sys.stdin)["data"] if m.get("status")!="Shutdown"]
rows.sort(key=lambda m:m.get("created",0),reverse=True)
for m in rows[:20]:
    d=datetime.datetime.utcfromtimestamp(m.get("created",0)).strftime("%Y-%m-%d")
    print(d, m["id"], m.get("status") or "")'

created 是该条目在方舟注册的时间，倒序排出来就是最近上新的模型；status 为 Retiring 的表示即将下线，Shutdown 的已下线。注意这个接口只列按量付费目录（套餐路由 /api/plan/v3/models 返回 404），套餐侧用的是不带日期的别名，会自动跟到该品牌最新版本，因此无需增删 id。

按量付费路由的日期 id 每次上新都要手动同步，对照 模型列表 和 模型发布公告 即可。

套餐侧没有清单接口，改动体现在文档的「支持模型」表格里，并且常在活动公告里提前露出（例如 deepseek-v4.1-flash-economy 就是先在「指定模型抵扣系数限时折扣活动」里出现，2026-10-20 才进套餐）。盯这两页 + 它们底部的「最近更新时间」就能发现上新：

• Agent Plan 套餐概览
• Coding Plan 套餐概览

发现新别名后，直接拿 /api/plan/v3 或 /api/coding/v3 的对应 key 打一次 chat/completions 就能确认它是否可用（未在套餐内会 404 / 无权限）：

curl -s https://ark.cn-beijing.volces.com/api/plan/v3/chat/completions \
  -H "Authorization: Bearer $ARK_AGENT_PLAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4.1-flash-economy","messages":[{"role":"user","content":"hi"}],"max_tokens":8}'

把 plan 换成 coding、key 换成 $ARK_API_KEY 即可验证 Coding Plan 侧。

API 协议与思考开关

• 协议：两条套餐路由用 api: openai-responses（Ark 官方 DeepSeek Harness 文档就是这份配置，且 Ark 建议编程场景用 Responses，推理效果更好）。方舟在这两个 Base URL 上同时提供 /responses 和 /chat/completions，想换成 chat 协议就把该路由的 api 改成 openai-completions。另外这两条路由还有 Anthropic 兼容根地址（/api/plan、/api/coding），可配 api: anthropic-messages，本包默认不启用。

• 思考开关默认不配：本包所有模型都不声明 reasoningEfforts，系统提示走 system 角色，模型在方舟侧按各自默认行为思考（deepseek-v4-pro / v4.1-flash / glm-5.3 / kimi-k3 默认就开思考）。实测原因：一旦声明思考等级，用户选「off」时 pi-ai 会发 thinking: {type: "disabled"}，而 glm-5.3、glm-5.3-flash、kimi-k2.7-code 会返回 thinking.type 'disabled' is not supported by this model。

• 想给某个模型开思考控制，在该模型下加：

  - id: deepseek-v4.1-flash
    reasoningEfforts: { off: disabled, high: high }
    compat: { thinkingFormat: deepseek, supportsDeveloperRole: false }
  

  这样 pi-ai 会发方舟原生的 thinking: {type: enabled|disabled} 和 reasoning_effort。方舟现在也接受 developer 角色（13 个模型实测都通过，旧版本 README 里「方舟不支持 developer 角色」的结论已过时），supportsDeveloperRole: false 只是保险。

模型选择

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

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

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

• 文生图（Seedream / 即梦） —— 已有 volcengine_image_generate（默认 imageModel 为 doubao-seedream-5-0-pro-260628）；doubao-seedream-5-0-flash-260915（更快更便宜）、doubao-seedream-4-5-251128 等可直接传 model 使用。旧的 doubao-seedream-4-0-250828 已进 Retiring。Agent Plan 也含图片生成额度，但需要把工具指向 /api/plan/v3（本包工具默认走按量付费）。
• 视频生成（Seedance） —— seedance 2.0 / 2.0-fast / 2.5 等；Agent Plan 的 Large / Max 套餐含视频额度。
• Embeddings —— doubao-embedding-large-text、doubao-embedding-vision-251215；Agent Plan 含 doubao-embedding-vision。
• Rerank —— jina-reranker、bge-reranker-v2-m3 等。
• 语音合成 / 识别（TTS / ASR） —— 走豆包语音 WebSocket V3 + appid/access token，需引入官方 @volcengine/openapi；Agent Plan 的语音模型走 /api/plan/v3。

这些需要各自新增工具（/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