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 平台下的搜索配置门槛。