前言¶

在 DeepSeek Harness（DSH）里做智能体或日常对话，模型往往来自多个供应商；若你已在火山方舟开通 API，豆包、DeepSeek、GLM、Kimi 等模型都走同一套 Ark 网关，却还要在宿主里单独接路由、维护 Key 与模型清单，配置会分散在环境变量和手写 YAML 里。社区插件 dsh-connect-volcengine 把单一供应商「火山方舟 · Ark」整包接进 DSH：一把 ARK API Key 进模型选择器，多账号可轮换，可用性用真实请求探测，用量在提供 AK/SK 时可读。下面介绍它是什么、能做什么，以及如何安装与配置。

这是什么¶

维护者为 ElioFanyu，仓库 ElioFanyu/dsh-connect-volcengine，许可证 MIT，当前 package 版本 1.0.0。插件注册 LLM 路由 volcengine，显示名为「火山方舟 · Ark」，面向已在火山方舟控制台开通模型的用户。

与同生态的 dsh-connect-workbuddy 不同：后者是双供应商加积分体系，界面用 tab 分隔；本插件只有一个供应商，设置卡片采用单列阅读流（健康条 → 账号 → 模型 → 能力 → 诊断），把「能不能用」放在最上面，一屏可见关键状态。

核心功能¶

以下能力均来自仓库 README 与 package.json 说明，未在资料中出现的不要自行推断。

两个与实测相关的结论（README 明确写出）：

1. 未开通的模型通常返回 404 与 InvalidEndpointOrModel.NotFound；已开通但欠费可能仍是 403 与 AccountOverdueError。探测只对官方目录里存在的 id 下结论，404 一律按未开通/不可用处理，且无法与「id 写错」区分。
2. ARK API Key 不能读推理用量；方舟文档写明查询用量接口仅支持 Access Key 鉴权。未配置 AK/SK 时，卡片只给控制台直链，不展示编造数字。

模型规格中的 contextWindow / maxOutput 取自官方模型列表（README 标注 2026-10-26 版），与探测无关；二者不可混用，否则压缩时机与长度校验会错。

探测仅在用户点击按钮时执行，每个模型约一次 max_tokens: 1 请求（README 估算 18 个模型全探约 700 token），不会在后台偷偷跑。

安装与启用¶

资料中的安装方式为克隆仓库后在 DSH Plugin Manager 以目录安装，或写入 profile 的 cordis.patch.yml。

git clone https://github.com/ElioFanyu/dsh-connect-volcengine.git

在 Plugin Manager 中选择该目录安装，或在 profile 中增加：

- id: dsh-connect-volcengine
  name: dsh-connect-volcengine

运行环境要求 Node ^22.19.0 || >=24.0.0（见 package.json 的 engines）。插件以当前 DSH 进程权限运行，安装前请自行审阅源码与 MIT 许可证；社区目录 skillhub.cn 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。

配置¶

配置落在 profile 的 cordis.patch.yml；Web 设置卡片会代写，手改同样生效。

- id: dsh-connect-volcengine
  name: dsh-connect-volcengine
  config:
    enabled: true
    baseURL: https://ark.cn-beijing.volces.com/api/v3
    accounts:
      - id: default
        label: 主账号
        ref: ARK_API_KEY
        enabled: true
    activeAccountId: default
    poolEnabled: false
    models: []
    imageToolEnabled: false
    imageModel: doubao-seedream-3-0-t2i-250415
    accessKeyRef: ''      # 可选，读用量用
    secretKeyRef: ''

ref、accessKeyRef、secretKeyRef 均为凭据引用名，不是密钥明文：密钥由卡片写入宿主凭据库，分享 YAML 不会泄漏 Secret。

models: [] 表示使用内置种子（首次运行与账号已开通情况相关）；真实可用状态以「探测」结果为准，内置清单不是写死的终态。

可选：需要用量时在卡片中填写 AK/SK 引用；权限范围大于 ARK Key，仅在需要用量时配置。

典型用法¶

1. 接入账号并验证连通¶

1. 在设置卡片为主账号填写 ARK API Key（写入 ref 指向的凭据名，默认示例为 ARK_API_KEY）。
2. 使用卡片或本地 loopback 路由 POST .../test 做单账号连通性检测（直接请求上游，验证凭据与网关）。

会话里实际对话走 adapter → llm.stream；若链路某环配置错误，可能出现 /test 成功而会话失败的情况，此时可用 POST .../dispatch 走一次真正的派发做对比（README 说明二者职责不同）。

2. 刷新目录、探测、写回可用模型¶

1. POST .../refresh：拉取上游模型目录为草稿，不写配置。
2. POST .../probe：逐模型探测开通状态（会消耗少量 token）。
3. 在卡片使用「只保留可用」或 POST .../save：把结果写入配置。

搜索框可匹配 lib/model-notes.js 中的用途文案（例如「翻译」），而不必记住完整模型 id。

3. 多账号与池化¶

在 accounts 中增加多条 Key，设置 enabled 与 activeAccountId；需要失败换号时将 poolEnabled 设为 true。关闭池化则固定使用选中账号。

4. 上下文预算与图片、生图¶

在模型列表中为每行选择「预算」下拉（软约束，上游 context_window 超限时应调小）。按需开启逐模型图片输入；自主生图需将 imageToolEnabled 设为 true，默认模型 id 为 doubao-seedream-3-0-t2i-250415。

5. 用量与诊断¶

配置 accessKeyRef / secretKeyRef 后，通过 POST .../usage 或卡片读取用量。GET .../status 供卡片展示；GET .../models 返回宿主实际下发的模型清单，便于与选择器对照。

本地探测路由仅 loopback 可达，POST 需同源校验（README 路由表：/status、/models、/refresh、/probe、/usage、/save、/test、/dispatch）。

适用场景与注意¶

适合： 已在火山方舟开通模型、希望用 DSH 统一选模型与 Key 管理；需要按真实请求判断「是否开通」、多 Key 轮换、可选 AK/SK 读用量的用户。

注意（README「已知限制」摘要）：

• 欠费时探测可能对所有可达模型都返回 AccountOverdueError，只能判「已开通」，判不了「有余额」。
• doubao-seed-evolving 不在自动开通范围，需在控制台手动开通。
• 图片能力按官方文档标注，未逐模型实测；大输出模型仍受上游流控影响。
• 模型说明按 Ark 模型 id 精确匹配；自定义别名会导致说明行空白，属刻意行为，避免错贴文案。
• 当前 Web GUI 模型菜单只渲染名称，不渲染 description；完整「适合 / 注意」在设置卡片中查看。

结尾¶

dsh-connect-volcengine 把火山方舟收成 DSH 内单一 provider：账号池、真实探测、上下文预算、可选生图与 AK/SK 用量，并单列卡片集中呈现健康与诊断。进一步细节以仓库 README 为准。

• 目录页：https://www.skillhub.cn/plugins/ElioFanyu/dsh-connect-volcengine
• GitHub：https://github.com/ElioFanyu/dsh-connect-volcengine