anht3889/dsh-web-search

dsh-web-search

面向 DeepSeek Harness 的树外多引擎网络搜索。可安装的 bundle 注册了一个 dsh-web-search provider，可使用 Tavily、Brave Search 或私有 SearXNG 实例。

先决条件

- dsh CLI 和一个 Web profile。
- 对于源码检出：Node.js ^22.19 或 >=24、pnpm，以及同级的 ../deepseek-harness 检出。客户端类型检查和 tsdown 会扩展该目录树；已发布的安装使用预构建包，不需要它。
- 该引擎的 Tavily 或 Brave API key，或你运营或信任的私有 SearXNG 实例。

安装

将已发布的 bundle 添加到 profile。这是 dsh plugin add 唯一需要的包；@anht3889/dsh-web-search-service 是 bundle 的嵌套依赖，而不是第二个插件。

dsh plugin --profile web add @anht3889/dsh-web-search-bundle

从本地源码检出时，改为构建并添加工作区路径，而不是 npm 名称：

pnpm install && pnpm run build
dsh plugin --profile web add ./packages/bundle

任一种安装后，重启 Web profile：

dsh --profile web

打开 Settings → 网络搜索（英文区域设置下为 Web search），选择一个引擎，输入其所需的 key 或 URL，然后保存。引擎更改会在下一次搜索时生效，无需再次重启。

引擎

| 引擎 | 默认 base URL | 必需配置 |
|---|---|---|
| Tavily | https://api.tavily.com | TAVILY_API_KEY |
| Brave Search | https://api.search.brave.com | BRAVE_API_KEY |
| SearXNG | 无 | 私有实例 base URL |

初始引擎未选择，因此在配置引擎之前，固定的 provider 不可用。SearXNG 没有公开默认值：请使用你运营或信任的私有实例，并在其设置中启用 JSON 响应。搜索会请求 format=json；403 响应通常意味着该实例不允许 format: json。

配置与密钥

| 数据 | 默认位置 |
|---|---|
| 引擎选择和 base URL；不含密钥值 | $DSH_HOME/web-search/config.json |
| 备用 key 存储 | $DSH_HOME/web-search/secrets.yaml |
| Key 引用 | TAVILY_API_KEY、BRAVE_API_KEY |

密钥解析使用已挂载的 ctx.credentials 服务、私有备用文件、进程环境中的第一个非空值。当 ctx.credentials 已挂载时，Settings 会通过它写入 key；否则写入备用文件。HTTP API 和 Settings 状态仅暴露每个 key 是否已配置，绝不暴露其值。

如果未挂载 Host webserver，provider 仍支持无头搜索，但 Settings UI 和管理 HTTP 路由不可用。在启动该组合之前，请配置相同的目录和密钥位置。

运行时行为

bundle 将 web.searchProvider 固定为 dsh-web-search。在该固定设置生效期间，DeepSeek 的 deepseek-official provider 仍保持安装但不会被使用；不可用的 wrapper 不会静默回退到它。

管理服务
管理器发布 ctx.webSearchManager，其服务定义为 @anht3889/dsh-web-search-service。该服务暴露实时目录、无值的密钥状态、写入操作、提供方可用性以及变更通知，且无需 Web 服务器。没有回环 HTTP API 的宿主使用此服务直接管理同一运行时。

安装该 bundle 会将 seam 包作为 npm 依赖引入。希望使用 WebSearchManagement 类型的 TypeScript 宿主可以直接依赖 @anht3889/dsh-web-search-service；profile 用户绝不会通过 dsh plugin add 添加它。每个正在运行的 profile 都会在内存中缓存其目录；由另一个已在运行的 profile 写入的目录只有在重启后才会可见。

宿主管理 API 提供：

- GET 和 PUT /web-search/config
- GET 和 PUT /web-search/secrets

密钥写入是只写的；省略或为空的值会保持现有键不变。

恢复 DeepSeek 搜索

将此确切的层放入位于 $DSH_HOME/profiles/web/cordis.patch.yml 的 Web profile 补丁中：

- id: web
config:
searchProvider: deepseek-official

重启 Web profile。补丁行会替换整个 web 配置，因此请将任何其他必需的 web 配置键添加到同一映射中。

故障排除

- WEB_PROVIDER_CONFIGURED_UNAVAILABLE： 选择一个引擎。对于 SearXNG，还需提供有效的绝对私有实例 URL。没有自动的 DeepSeek 回退。
- 缺少 Tavily 或 Brave 密钥： 在设置、ctx.credentials、回退密钥文件或进程环境中设置匹配的密钥。在密钥解析之前，提供方可能显示为可用，但当密钥缺失时，搜索调用会以 WEB_PROVIDER_ERROR 失败。
- SearXNG HTTP 403： 在实例设置中启用 JSON 输出（format: json），并确认你使用的是自己的私有实例。
- config.json 损坏： 如果 $DSH_HOME/web-search/config.json 存在但不是有效的 JSON，或未通过目录验证（未知键、无效引擎，或选择了 SearXNG 但没有绝对 URL），宿主启动会失败。删除该文件以恢复空目录，或修复 JSON。不要将密钥放入此文件。

特定于包的导出列在 packages/bundle/README.md 中。