dsh-web-search-ark：Volcengine Ark Web Search Provider for DeepSeek Harness

前言¶

DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。官方的 DeepSeek 搜索提供商直接對接 DeepSeek 平臺，使用 Anthropic Messages API。當大模型運行在 Volcengine Ark 平臺上，且沒有 DeepSeek 平臺 Key 時，會出現認證失敗的問題。

Volcengine Ark 提供的聯網能力（web search plugin）僅通過 Responses API 原生暴露，模型側使用 {"type": "web_search"} 工具。dsh-web-search-ark 插件將 DSH 內置的 web_search 能力路由至 Ark 的 Responses API，解決了 Ark 部署環境下的聯網需求。

核心功能¶

該插件主要完成以下工作：

註冊搜索提供商：註冊名爲 ark-official 的搜索提供商，供 DSH 調用。
調用 Ark API：通過 POST {baseURL}/responses 調用 Ark Responses API，傳入原生的 web_search 工具。
結果映射：將模型返回的 url_citation 註解映射爲 DSH 的搜索源格式（去重後的標題、發佈時間、站點名）。
錯誤處理：當模型未觸發搜索時拋出結構化的 WEB_PROVIDER_ERROR。
設置卡片：在 Settings → Plugins 提供設置界面，支持模型、端點、最大關鍵詞數、API Key 的配置。
日誌記錄：記錄 web/ark-search-llm-request 事件到會話日誌。

安裝與啓用¶

環境要求¶

DSH 版本：0.1.2-rc.1 或更高（支持 1.1.0+）。
Node 環境：需要安裝 pnpm（dsh plugin 是 pnpm 的轉發器）。
Ark 賬戶：已啓用聯網內容插件（web search plugin）的賬戶，並擁有可用 API Key。
網絡：可訪問 ark.cn-beijing.volces.com 或自定義的 ARK_SEARCH_BASE_URL。

安裝步驟¶

安裝 DSH（鎖定到已覈實版本）：

    npx @deepseek-ai/dsh@0.1.2-rc.1

確保 pnpm 可用：

    npm install -g pnpm        # 或者: corepack enable

放置插件文件：
解壓插件包後，必須將其放置在 DSH 的插件目錄中。

    mkdir -p ~/.dsh/profiles/web/packages
    cp -R web-search-ark ~/.dsh/profiles/web/packages/

註冊插件：

    dsh plugin --profile web add ~/.dsh/profiles/web/packages/web-search-ark

配置搜索源：
在 ~/.dsh/profiles/web/cordis.patch.yml 中追加以下內容，將 web profile 的搜索源切換爲 ark-official：

    - id: web
      config:
        searchProvider: ark-official

配置憑證：
設置環境變量 VOLCENGINE_API_KEY。該 Key 也可在 Web UI 的 Settings → Models 頁面中配置，或在 ~/.dsh/.credentials.yaml 中配置。

配置說明¶

插件通過環境變量或配置文件覆蓋默認值：

配置項	默認值	說明
`apiKeyEnv`	`VOLCENGINE_API_KEY`	憑證引用，從憑證服務、啓動環境或本節 literal 值解析。
`baseURL`	`https://ark.cn-beijing.volces.com/api/v3`	Responses API 基礎地址，`/responses` 會被自動追加。可通過 `ARK_SEARCH_BASE_URL` 環境變量覆蓋。
`model`	`deepseek-v4-flash-ga-260731`	搜索子任務使用的模型 ID。
`maxKeyword`	`5`	每輪搜索允許的關鍵詞搜索上限（Ark 允許 1–50）。

插件目錄必須嚴格位於 ~/.dsh/profiles/<profile>/packages/ 下，否則 dsh plugin add 可能會因爲 Node 模塊解析路徑問題報錯。

成本與注意事項¶

計費模式：按實際搜索次數計費。每次 web_search 可能展開最多 maxKeyword 次關鍵詞搜索，每次調用均會產生費用。無緩存機制，重複調用需重新計費。
日誌：每次請求均記錄在會話詞彙 web/ark-search-llm-request 中，可在 Ark 控制台進行對賬。
插件目錄：務必遵守插件目錄位置要求，否則依賴解析可能失敗。

總結¶

dsh-web-search-ark 是連接 DeepSeek Harness 與 Volcengine Ark 聯網能力的橋樑，專爲 Ark 環境下的 DSH 部署設計。它通過映射原生 url_citation 並提供圖形化設置卡片，降低了 Ark 平臺下的搜索配置門檻。