@junjiangao/dsh-web-search-tavily

前言¶

DeepSeek Harness (DSH) 采用插件化架构，ctx.web 是接入 Web 搜索能力的关键 seam。在使用第三方搜索服务（如 Tavily）时，开发者通常需要处理 API 密钥配置、参数映射以及复杂的调参流程。@junjiangao/dsh-web-search-tavily 是一个基于 Tavily 的 WebSearchProvider，它解决了密钥管理繁琐的问题，并提供了一个仅包含能提升检索质量参数的原生配置表单。

插件介绍¶

这是一个为 DSH 的 ctx.web 能力提供支持的 Tavily 搜索提供者。它不拥有 ctx.web，也不注册面向模型的工具（即不注册 dsh-tool-web）。

该插件的核心价值在于：
* Keyless 模式：无需在任何位置（配置文件、设置页面、凭证系统、环境变量）提供 API 密钥，请求直接运行在 Tavily 的 keyless 模式下。
* 原生配置表单：在 DSH 的 Plugins 页面注册配置卡片，仅渲染对检索质量有影响的参数。
* 安全配置：表单分组设计，且具备依赖驱动的控制逻辑，防止配置导致 Tavily 返回 400 错误。

安装与启用¶

该插件以标准 bundle 的形式分发，需通过 dsh plugin 命令安装。

1. 安装插件¶

在目标 profile 下执行：

dsh plugin --profile <name> add github:junjiangao/dsh-web-search-tavily

2. 启用 Tavily 提供者¶

注册提供者与选择提供者是两回事。web seam 通过 searchProvider 字段决定使用哪个提供者。请确保在 profile 的 cordis.patch.yml 中指定：

- id: web
  config:
    searchProvider: tavily   # 必须显式指定，以覆盖默认的 deepseek-official

注意：环境变量 DSH_WEB_SEARCH_PROVIDER 仅在 web 行未配置 searchProvider 时生效。

核心功能¶

Keyless 模式¶

插件运行时不会发送 Authorization 头，也不会设置 x-tavily-access-mode: keyless。它利用 dsh-web-search-tavily-keyless 客户端源进行请求。

参数精简与分组¶

表单分为三个部分：凭证 / 检索 / 高级。
* 凭证：包含 apiKey（密钥）和 apiKeyEnv（环境变量引用）。
* 检索：包含 searchDepth、includeDomains、excludeDomains、language、filterByLanguage。
* 高级：包含 includeDomainsMode 和 includePublishedDate，该部分默认折叠。

所有其他 Tavily 参数（如 topic、timeRange、maxResults、autoParameters 等）保持 Tavily 的默认值，不显示在表单中，但可通过 profile patch 覆盖。

防止错误配置¶

表单实现了依赖控制。例如，当未设置 language 时，filterByLanguage 会被锁定并显示说明（因为 Tavily 会返回 400 错误）。当未设置 includeDomains 时，includeDomainsMode 同样会被锁定。

配置说明¶

表单渲染字段¶

区段	字段	说明
凭证	`apiKey`	直接填写的密钥（不推荐，配置文件会脱敏）
凭证	`apiKeyEnv`	环境变量引用，如 `TAVILY_API_KEY`
检索	`searchDepth`	精度/延迟/成本切换：basic, fast, advanced, ultra-fast
检索	`includeDomains`	仅搜索指定域名列表
检索	`excludeDomains`	排除指定域名列表
检索	`language`	结果语言过滤
检索	`filterByLanguage`	严格语言过滤，需配合 `language` 使用
高级	`includeDomainsMode`	`restrict`（仅限域名）或 `prefer`（加权域名）
高级	`includePublishedDate`	包含发布日期（默认 true，帮助模型判断时效性）

基础设施参数¶

以下参数不显示在表单中，因为它们属于基础设施或默认行为：
* baseURL：默认为 https://api.tavily.com，可通过环境变量或 patch 覆盖。
* topic、timeRange、maxResults、includeAnswer、includeRawContent、autoParameters、exactMatch、country 等。

注意事项¶

依赖环境：
- 需要安装 DSH 版本 0.2.x（0.2.0-rc.1 或更高）。
- 需要运行 Node.js ^22.19.0 || >=24.0.0。
运行权限：插件以当前 DSH 进程的权限运行，请确保安装前检查源码与许可证（MIT）。
数据源：该插件仅注册提供者，不注册工具。实际的数据获取由 ctx.web 和底层的 dsh-tool-web 处理。

结语¶

该插件通过 Keyless 模式和精简的配置表单，降低了接入 Tavily 搜索的门槛，并保证了检索配置的健壮性。如需查看目录或源码，请访问 SkillHub 或 GitHub。