Tavily 搜索后端 xiaohj233/dsh-tavily-search-provider

dsh-tavily-search-provider

状态：功能插件（含兼容补丁），仅在 DeepSeek Harness 0.1.0-rc.6 上测试过。

dsh-tavily-search-provider 注册一个独立的 tavily_search 工具，并为 DSH 官方的 web_search 工具提供可选的 Tavily 后端：两条路径都完整覆盖了 Tavily 支持的搜索参数。Plugins 设置卡片里还有一个只写的 TAVILY_API_KEY 控件，凭据写入 DSH 的凭据机制。

问题

社区里的 Tavily provider 大多只覆盖基本的查询与结果条数行为。本包的范围是保住兼容补丁后的 web_search 在模型侧依赖的那些控件：深度、主题、时效、域名过滤、答案包含与原始内容。

干净的 rc.6 安装里，dsh-tool-web 不暴露这些字段，dsh-host-apiproxy 也不放行本插件的设置命名空间，因此本包针对这两处缺口各带一个守卫式补丁。

行为

- tavily_search：始终注册，返回 Tavily 形态的结果集，支持全部已声明控件。
- 可选的 web_search provider：把官方工具路由到 Tavily，同时保持官方的结果/卡片形态。
- 凭据按调用解析：修改 TAVILY_API_KEY 无需重启即可生效。
- 设置卡片：配置状态、密码输入、保存/替换、清除、后端开关，以及官方路径的结果上限。
- 状态路由：/api/tavily-search-provider/status 返回不含凭据值的 provider/设置状态。

非目标

本包不是 DSH 第一个或唯一的 Tavily 集成，不会替换 DSH 的 provider 注册表，也不自行抓取页面；当其他后端忽略 Tavily 控件时，本包也无法让这些控件生效。

兼容补丁

精确目标：

- @deepseek-ai/dsh-tool-web@0.1.0-rc.6：声明并转发 search_depth、topic、time_range、max_results、include_domains、exclude_domains、include_answer 和 include_raw_content。
- @deepseek-ai/dsh-host-apiproxy@0.1.0-rc.6：只把 dsh-tavily-search-provider 加进 Web 设置命名空间的 allowlist。

版本策略默认自适应：已安装副本的版本不是 0.1.0-rc.6，但只要每个锚点仍唯一匹配，就照常打补丁（记为 adaptive 匹配）；锚点漂移则跳过并说明原因。编程选项 strict 可恢复"只打精确版本"的旧行为。单个漂移、外来或遗留目标不会阻塞其他目标，补丁应用在启动期间也绝不会抛错。所有模式下还原都严格校验版本；apply 与 restore 均幂等，文件替换使用临时文件加 rename。

兼容性

需要 DeepSeek Harness 0.1.0-rc.6、Node.js ^22.19.0 || >=24、pnpm >=10，以及一个 Tavily API 密钥。上游升级后，运行一次 dsh-tavily-search-provider status，确认每个目标要么已应用、要么是有意跳过。

安装

dsh plugin --profile web add "github:xiaohj233/dsh-tavily-search-provider#v0.2.0"

重启一次，让启动时的守卫式补丁应用到干净的 rc.6 目标上。即使某个无关或遗留目标被拒绝，独立工具依然可用；但在该文件被还原之前，官方 web_search 的控件或设置卡片可能不完整。

API 密钥与配置

打开 Settings -> Plugins -> Tavily Search。密钥输入框只通过 credentials.set 写入 TAVILY_API_KEY；状态查询用不带值的 credentials.describe，清除用 credentials.unset。密钥草稿留空会保留当前值。

在非回环地址的明文 HTTP 上，密钥的设置与清除会被禁用。请使用 localhost/loopback 或 HTTPS。这并不会给 DSH Web 控制面整体加上认证。

卡片还控制 replaceOfficialSearch 与 searchMaxResults。把 dsh-tavily-search-provider 设置区里的 autoApplyPatches 设为 false，即可让启动时只检查、不应用补丁。

补丁状态、应用与还原

在 profile 中运行已安装的 CLI：

pnpm --dir "$DSH_HOME/profiles/web" exec dsh-tavily-search-provider status
pnpm --dir "$DSH_HOME/profiles/web" exec dsh-tavily-search-provider apply
pnpm --dir "$DSH_HOME/profiles/web" exec dsh-tavily-search-provider restore

卸载前先还原：

pnpm --dir "$DSH_HOME/profiles/web" exec dsh-tavily-search-provider restore
dsh plugin --profile web remove dsh-tavily-search-provider

未设置 $DSH_HOME 时，profile 位于用户主目录下（POSIX 为 ~/.dsh/profiles/web，Windows PowerShell 为 %USERPROFILE%\.dsh\profiles\web）；Windows 上请把解析后的路径传给 pnpm --dir，不要用 ~。

如果提示存在遗留或外来改动，请重新安装官方 DSH 包，而不要强行做模糊还原。

dsh-keepalive 会把它的 allowlist 行插到同一数组的顶部，因此两个补丁不再共享锚点：两个插件可以按任意顺序安装，各自的还原都会保留对方的行。

安全与隐私

Tavily API 会收到查询内容与已启用的搜索控件。开启 include_raw_content 后，可能把大量第三方页面内容带进模型上下文。域名过滤只是搜索约束，不是内容安全边界。请自行了解 Tavily 的数据处理方式与账户限额。

API 密钥只存在于浏览器草稿状态和本包创建的 credentials.set 请求中；它不会被写进插件设置区、工具结果、常规日志或状态响应。

网络韧性（DNS 污染 / fake-IP）

在 Clash/mihomo 这类以 fake-IP 模式接管 DNS 的机器上，系统解析器可能把 api.tavily.com 间歇性解析到 198.18.x.x 假地址（或上游投毒结果），导致裸 fetch 连接黑洞、请求超时——而真实 IP 本身始终可达。

本包 v0.3.5 起对 Tavily 全部端点（search/extract/map/crawl/deep-research）使用自带的韧性网络层：

1. 优先通过明文 HTTPS DoH（AliDNS、DNSPod、Google）解析真实 A 记录，过滤掉 fake-IP/私网/保留地址；
2. DoH 不可达时按 IP 字面量（8.8.8.8 / 223.5.5.5）直查，完全绕开系统 DNS；
3. 仍失败才回退系统解析器；全部失败时回退普通 fetch（行为与旧版一致）。

请求把 TCP 连接钉在验证过的真实 IP 上，同时保留 TLS SNI 与 Host 头，因此 DNS 被污染时搜索依然可用。解析结果缓存 5 分钟（失败 30 秒退避，过期后 1 小时内保留为兜底）。若连 DoH 都不可用（整网断连），网络错误消息会附带 fake-IP 排查提示。

测试

npm test
npm run check
npm pack --dry-run

测试覆盖：请求映射、结果投影、补丁/还原/版本/遗留状态的精确匹配、包语法、凭据 RPC 载荷、暂存密钥行为，以及对不安全传输的拒绝。

局限性与上游现状

官方的 DeepSeek 搜索 provider 会忽略 Tavily 特有的控件。补丁只针对 rc.6，且修改已加载的模块时需要重启。如果只需要更简单的 provider 行为，现有 Tavily 插件依然是合格的替代方案；本包面向的是上文所述的完整控件映射与凭据/设置集成。

License

MIT。补丁目标均为 MIT 许可，详见 THIRD_PARTY_NOTICES.md。