of1102/dsh-web-search-ark

dsh-web-search-ark

一个用于 DeepSeek Harness (DSH) 的网页搜索提供方插件，
它将内置的 web_search 能力路由到 *火山方舟
(Volcengine Ark)。它专为聊天模型运行在方舟上、
且没有 DeepSeek 官方平台密钥的部署场景而设计。

中文使用指南见 docs/使用指南.md。

为什么

DeepSeek 官方搜索提供方使用 Anthropic Messages API 对接
DeepSeek 自有平台，因此仅使用方舟的部署会失败并报
Authentication Fails ... key is invalid。方舟仅通过 Responses API 配合原生
{"type": "web_search"} 工具来暴露其联网内容插件
（网页搜索插件）。本插件调用该端点，并将
模型的 url_citation 注解映射为 DSH 搜索来源。

它的功能

- 在 id ark-official 下注册一个搜索提供方
（web.searchProvider: ark-official，或 $DSH_WEB_SEARCH_PROVIDER=ark-official）。
- 使用原生 web_search 工具调用 POST {baseURL}/responses
（max_keyword 限定一轮可运行多少次关键词搜索；方舟
接受 1–50）。
- 将 Responses 响应体规范化为 DSH 的搜索结果结构（答案文本、
去重后的来源，含标题 / 发布时间 / 站点名称），并在
模型从未触发搜索时抛出结构化的 WEB_PROVIDER_ERROR。
- 在 设置 → 插件 中提供一个设置卡片（模型、端点、最大
关键词数、API 密钥），具有与内置卡片相同的分阶段保存 / 折叠行为。
- 在会话事件
web/ark-search-llm-request 下记录每个请求（注册到会话词汇表中，因此
故障关闭式持久化读取器仍能加载受影响的会话日志）。

要求

| 项目 | 要求 |
|---|---|
| DSH | 0.1.2-rc.1（已验证适用于 1.1.0+），例如 npx @deepseek-ai/dsh@0.1.2-rc.1（1.0.x 使用 0.1.1-rc.2） |
| Node / pnpm | dsh plugin 是 pnpm 转发器——请安装 pnpm（npm i -g pnpm 或 corepack enable） |
| 方舟账号 | 已启用联网内容插件（网页搜索插件），并拥有可用的 API 密钥 |
| 网络 | 可访问 ark.cn-beijing.volces.com（或你自己的 ARK_SEARCH_BASE_URL） |

安装

1. 安装 DSH（固定已验证版本）
npx @deepseek-ai/dsh@0.1.2-rc.1

2. 确保 pnpm 可用
npm install -g pnpm        # 或：corepack enable

3. 解压插件并将其放入 DSH 主目录内（重要！）
unzip dsh-web-search-ark-1.0.0.zip
mkdir -p ~/.dsh/profiles/web/packages
cp -R web-search-ark ~/.dsh/profiles/web/packages/

4. 注册插件（写入 package.json 依赖 + dsh.profile.bundles）
dsh plugin --profile web add ~/.dsh/profiles/web/packages/web-search-ark

5. 追加到 ~/.dsh/profiles/web/cordis.patch.yml（合并到数组中）：
- id: web
config:
searchProvider: ark-official

6. 配置方舟密钥（与你的聊天模型相同的密钥即可）：
A) Web UI 中的 设置 → 模型 页面，或
B) ~/.dsh/.credentials.yaml 中的 VOLCENGINE_API_KEY，或
C) 在启动环境中导出 VOLCENGINE_API_KEY

7. 启动并验证
dsh web

将插件目录保留在 ~/.dsh 内（官方位置为
~/.dsh/profiles//packages/）。如果它位于其他位置，dsh plugin
add 会失败并报错 Cannot find package '@deepseek-ai/schemastery'，因为
Node 会从插件的真实路径向上解析 @deepseek-ai/ 桥接包，直至
~/.dsh/profiles/node_modules/。

配置

| 键 | 默认值 | 描述 |
|---|---|---|
| apiKeyEnv | VOLCENGINE_API_KEY | 凭据引用：从凭据服务、启动环境或本节中的字面量 apiKey 解析 |
| 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） |

捆绑补丁（cordis.patch.yml）预设了 apiKeyEnv、model 和
maxKeyword；用户补丁只需设置 web.searchProvider: ark-official。
参见 examples/example-cordis.patch.yml。

费用

Ark 的网页搜索插件按实际搜索调用次数计费：一次
web_search 可能展开为最多 maxKeyword 次关键词搜索，每次单独计费。
没有缓存；重复调用会再次计费。每个请求都会记录在
web/ark-search-llm-request 下，以便在 Ark 控制台中对账。

开发

npm ci                      # 安装测试所需的 DSH 开发依赖
npm test                    # 离线契约 + 客户端卡片 + 会话加载检查
SMOKE_LIVE=1 npm run test:live   # 同时执行一次真实的 Ark 搜索（需要密钥）

测试框架的环境变量：

| 变量 | 默认值 | 用途 |
|---|---|---|
| DSH_MODULES_ROOT | 自动（./node_modules，然后是 ~/.dsh/profiles/node_modules） | @deepseek-ai/ 包的解析位置 |
| DSH_CREDENTIALS_FILE | ~/.dsh/.credentials.yaml | 用于实时测试的凭据文件 |
| SMOKE_LIVE | 未设置 | 执行实时 Ark 搜索场景 |
| ARK_SMOKE_API_KEY_ENV | VOLCENGINE_API_KEY | 实时调用的凭据引用 |
| ARK_SMOKE_MODEL | deepseek-v4-flash-ga-260731 | 实时调用的模型 |
| ARK_SMOKE_MAX_KEYWORD | 3 | 实时调用的 max_keyword |
| DSH_SESSIONS_ROOT / DSH_SESSION_ID | — | 会话日志 A/B 测试；未设置时跳过 |

发布

npm run release

构建 release/dsh-web-search-ark-.zip（一个可直接用于上述安装步骤的
web-search-ark/ 目录树）以及 release/SHA256SUMS.txt。该脚本会通过解压
zip 并比较每个条目来自我验证，然后才宣告成功；release/ 还会保留解压后的
目录树，因此 cd release && shasum -a 256 -c SHA256SUMS.txt 可以一次性
验证所有内容。推送 v 标签会触发 .github/workflows/release.yml，它会运行
测试并将产物附加到 GitHub release。
许可证

MIT © 2026 Oscar Fang