前言¶

DSH 的插件机制比较贴近「一切皆插件」：搜索提供方、抓取提供方可以挂到宿主接口上，而不是要求使用者重写主流程。对于需要把 web_search 切到外部搜索引擎的场景，常见痛点是配置分散、参数不完整、连通性验证不方便。

dsh-plugin-tavily 解决的就是这个问题：它为 DeepSeek Harness 提供一个 Tavily-backed web search provider，把完整请求参数放进 WebUI 设置卡，并保留 yaml 配置优先的能力。下面介绍它的定位、安装方式和典型用法。

这是什么¶

dsh-plugin-tavily 是 1624318455 维护的 DSH web search provider 插件。它向 harness 的 ctx.web seam 注册一个 tavily provider，使 web_search 请求可以通过 Tavily 回答。

插件同时提供 WebUI 设置卡，用于粘贴 API key、调整高级参数、测试连通性；也支持通过 cordis.patch.yml 固定配置。材料中 package.json 显示版本为 0.6.2。

核心功能¶

搜索提供方¶

• 向 ctx.web seam 注册 tavily search provider。
• web_search 工具本身不变，只是回答它的后端变成 Tavily。
• WebUI 中可在 tavily 与 official DeepSeek provider 之间切换。
• 无 Tavily key 时以 keyless 模式运行，免费且有限速；有 key 时使用对应账户层。
• 配置优先级为：cordis.patch.yml > WebUI > code defaults。
• WebUI 可编辑的 Tavily 参数包括：API key、API Base URL、maxResults、searchDepth、topic、includeAnswer、includeRawContent、timeout、days、chunksPerSource、timeRange、startDate/endDate、includeImages、includeDomains/excludeDomains、country。
• 提供参数预设：Deep research、Quick summary、Live news。
• 服务端连通性探测接口为 POST /api/tavily-probe。
• 状态接口为 GET /api/tavily-status，用于显示当前 key 与额度状态。
• API 连接测试会给出分类错误：invalid key、insufficient credits、rate limited、service down、timeout、network。
• 设置卡提供 Usage & cost 面板，可显示当前设置下单次搜索的 credit/token 估算，并通过 Tavily GET /usage 查看用量。

抓取提供方¶

• 提供基于 Tavily Extract 的 fetch provider：tavily-extract，用于从 URL 读取页面内容。
• 提供可选 Firecrawl fetch provider：firecrawl，默认凭证引用为 FIRECRAWL_API_KEY。
• 如果没有 Firecrawl key，抓取时报告 WEB_PROVIDER_CREDENTIAL_MISSING；未被选择时保持未启用。

稳定性与工程化选项¶

• 持久化结果缓存：cacheFile 默认关闭，best-effort，并带 debounce；磁盘失败不会导致搜索失败。
• 429 场景下的重试：有界 backoff，并可选 TTL/LRU cache。
• TTL/LRU cache 默认跳过时效敏感搜索，例如新闻、金融或带有时间窗口的请求。
• 可选 concise debug logging：不会记录 API key 或原始响应体。
• 多 key 轮换与故障切换：apiKeyRefs 只保存引用，key 仍保存在 credentials store 或环境中；连续失败 3 次后进入 60 秒冷却。
• 引用格式：citeFormat: footnote 或默认 plain。
• 自动降级引擎：fallbackEngine: deepseek，仅在 service-side Tavily failures 时触发，例如 timeout、network、5xx；key-level faults 如 429、401 不触发该降级。
• key 解析顺序：literal apiKey → credentials service（apiKeyEnv）→ process.env[apiKeyEnv]。

安装与启用¶

1、安装插件¶

先安装插件。官方安装命令如下：

dsh plugin --profile web add "github:1624318455/dsh-plugin-tavily#main"

开发阶段也可以从本地路径安装：

dsh plugin --profile web add "file:/absolute/path/to/dsh-plugin-tavily"

安装后重启 dsh。插件自带的 cordis.patch.yml 会将 web.config.searchProvider 设为 tavily，因此不需要再手动选择搜索提供方。

2、填写 Tavily API key¶

打开 WebUI：

设置 → 插件 → 网页搜索

展开 Web search (Tavily) 设置卡，将 Tavily API key 粘贴到 API key 字段。没有 key 时也可以使用 keyless 模式。

3、选择搜索提供方¶

在设置卡中切换 Web search engine：

• tavily
• official DeepSeek

经过上面的步骤后，继续使用 web_search 即可。工具接口不变，只有后端提供方发生变化。

4、手动覆盖 yaml（可选）¶

如果你希望手动固定 provider，可以写入 profile 配置：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: web
  config:
    searchProvider: tavily

典型用法¶

启用 Tavily Extract 抓取¶

如果还需要用 Tavily Extract 做页面抓取，可以设置 fetch provider：

export DSH_WEB_FETCH_PROVIDER=tavily-extract

或者在 cordis.patch.yml 中写：

- id: web
  config:
    searchProvider: tavily
    fetchProvider: tavily-extract

启用 Firecrawl 抓取（可选）¶

如果需要改用 Firecrawl 抓取页面，可以设置：

export DSH_WEB_FETCH_PROVIDER=firecrawl

或在同一行配置中写：

- id: web
  config:
    searchProvider: tavily
    fetchProvider: firecrawl

使用 Firecrawl 需要自己的 key。材料给出的默认凭证引用是 FIRECRAWL_API_KEY。没有 key 时，该 provider 在 fetch 时会报告 WEB_PROVIDER_CREDENTIAL_MISSING，其余情况保持未启用。

测试连接与查看状态¶

设置卡中的连接测试会检查当前输入的 key 和 API Base URL，并给出分类错误说明。已存储 key 不能由浏览器读回；如果测试已经配置好的 key，需要重新输入一次，且不会再次保存。

服务端接口：

POST /api/tavily-probe
GET /api/tavily-status

其中 GET /api/tavily-status 会读取已存储 key，并配合 Tavily GET /usage 显示状态。

适用场景与注意¶

适合以下场景：

• 希望 web_search 走 Tavily。
• 需要在 WebUI 中调整完整 Tavily 请求参数。
• 需要 yaml 配置优先，避免 UI 中旧值覆盖开发者固定值。
• 需要页面抓取，并可选用 tavily-extract 或 firecrawl。
• 需要连通性测试、用量查看、多 key 轮换、降级和调试日志。

使用前建议注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。材料中 package.json 列出了 LICENSE 文件，但未给出具体许可证类型。
• 已存储 key 不能由浏览器读回；测试已配置 key 时需要重新输入一次。
• 持久化结果缓存默认关闭，且为 best-effort。
• TTL/LRU cache 默认跳过时效敏感搜索，例如新闻、金融或带时间窗口的请求。
• 自动降级只在 service-side 失败时触发，不会把 429、401 这类 key-level 故障当成服务宕机。
• Firecrawl 未配置 key 时保持未启用，fetch 会报告 WEB_PROVIDER_CREDENTIAL_MISSING。
• DSH 插件目录是独立站点，不应理解成官方应用商店。

相关链接¶

• 目录页：https://www.skillhub.cn/plugins/1624318455/dsh-plugin-tavily
• GitHub：https://github.com/1624318455/dsh-plugin-tavily