前言¶

在 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