前言¶

DeepSeek Harness（DSH）里，模型调用的 web_search 与 web_fetch 并不直接连外网，而是经过可插拔的 web 能力 seam（ctx.web）：默认搜索走随附的 DeepSeek 通道，抓取走本地 HTTP 提供方。若你更习惯 Tavily 的搜索与 extract API，或希望统一用第三方联网栈，需要自己注册提供方并改 profile 里的 searchProvider / fetchProvider。dsh-tavily（维护者 mimoxh，分类：联网工具）把这两步封装成插件：挂载 Tavily 提供方，并在 patch 里固定 provider id，避免多个提供方同时「可用」时出现 WEB_PROVIDER_AMBIGUOUS。工具契约不变，模型侧仍是原来的工具名与结果形态。

下面介绍插件定位、能力边界、安装与配置要点。事实以 GitHub 仓库 README 为准；DSH 目前为 developer preview，本插件针对 0.2.1-rc.3 的 seam API 编写，与 DeepSeek 官方、Tavily 官方均无从属关系。

这是什么¶

dsh-tavily 是 DSH 的 web seam 插件：将内置 web_search 与 web_fetch 的请求转发到 Tavily 的 /search 与 /extract，替代默认的 DeepSeek 搜索通道与本地 HTTP 抓取通道。包描述为 zero build step（浏览器半边为手写 client.js）；Host 侧依赖 @deepseek-ai/schemastery ~3.18.5 用于设置页与 schema 校验，缺失时搜索/抓取仍可工作，但 Settings → Tavily 不会出现。

package.json 声明 dsh.seams: ["web"]，与 inject 一致，便于离线自测审计。

原理与核心功能¶

DSH web 栈中，@deepseek-ai/dsh-tool-web 暴露面向模型的工具；@deepseek-ai/dsh-web 负责注册并按 id 选择搜索/抓取提供方。本插件在 cordis.patch.yml 中完成两件事：注册 id 为 tavily 的提供方；将 web 行的 searchProvider / fetchProvider 设为 tavily（组合包 patch 在同一行上最后写入者生效）。

不改工具契约：接在 ctx.web 上，参数、结果卡片、引用格式与默认路径一致；搜索与抓取结果按 README 映射到 DSH 的 sources / body 等字段。

原生设置页：DSH 设置弹窗增加 Settings → Tavily，可编辑多数搜索/抓取参数与 API Key；密钥写入 DSH 凭据库（默认引用名 TAVILY_API_KEY），不写进 profile patch 明文（除非你在 patch 里写字面 apiKey）。

两个能力可分开启用：若不想用 Tavily 抓页（额度、隐私、内网 URL 等考量），可将 fetchProvider 改回 http，仅替换搜索。

离线自测：在插件目录执行 npm test 不需要网络、不需要安装依赖、不需要安装 DSH；npm run test:schema 需在 npm install 后校验设置 schema。

环境与兼容性¶

准备 API Key¶

1. 在 Tavily 控制台 注册，获取 tvly- 开头的 key。
2. 注意额度：一次 web_search 消耗 1 次搜索额度（includeAnswer 会额外消耗）；一次 web_fetch 消耗 1 次 extract 额度（extractDepth: advanced 更多）。

密钥优先级（README 明确）：字面 apiKey（patch）> 凭据库（Settings → Tavily）> 环境变量 TAVILY_API_KEY。推荐设置页或环境变量，避免明文落盘。

$env:TAVILY_API_KEY = 'tvly-...'

安装与启用¶

安装前请在插件目录执行 npm install（本地 link: 安装不会自动装 link 目标的依赖，含 schemastery）。新装或改动组合包后需完全退出并重启 DSH，否则仍可能走旧提供方。

方式 A：桌面端插件管理器 + 本地路径¶

1. 在插件目录执行 npm install；
2. 打开 DSH Web 界面 → 侧栏 插件 → 添加插件；
3. 粘贴本仓库目录的绝对路径；
4. 点 安装，等待包管理器完成；
5. 完全重启 DSH。

方式 B：命令行装到某个 profile¶

先在插件目录安装依赖，再指定 profile 添加本地路径（路径改为你机器上的绝对路径）：

npm install
dsh plugin --profile web add "D:/path/to/dsh-tavily"

桌面端 profile 为 desktop，通常由 App 管理器安装；profile 之间互不相干。

方式 C：overlay 临时覆盖¶

前提是该 profile 已安装本包：

$env:TAVILY_API_KEY = 'tvly-...'
dsh web --patch ./examples/dsh-tavily.overlay.yml

装完必做：配置 TAVILY_API_KEY（或设置页保存，或 patch 中的 apiKey）；完全重启 DSH。

回退：将 web 行的 searchProvider / fetchProvider 改回 deepseek-official / http，或禁用 web-tavily 行，再重启。

配置要点¶

主要配置位于 cordis.patch.yml 的 web-tavily 行 config；标为可在设置页编辑的字段保存后立即生效（volatile），无需重启。常用项包括：

• baseURL：默认 https://api.tavily.com
• timeoutMs / fetchTimeoutMs：默认 15000 / 30000
• maxResults：默认 8（提供方上限 ≤ 20）
• searchDepth：basic / advanced / fast / ultra-fast
• topic：general / news / finance
• includeAnswer、includeDomains / excludeDomains
• extractDepth、extractFormat、maxBodyChars

高级字段如 searchPath、extractPath、userAgent、headers 仅 patch 内修改，改后需让组合包重新加载（桌面端完全重启 DSH；CLI 模式下次启动生效）。

web_fetch 使用 Tavily 时的取舍¶

装插件前建议确认 README 第 6 节的三点：

1. 每次抓取消耗 Tavily extract 额度，extractDepth: advanced 更贵；
2. 目标 URL 会发给 Tavily，由第三方基础设施抓取；
3. 无法抓取内网/本机地址（如 localhost、192.168.x.x）。

任一条不可接受时，只改 fetchProvider: http，保留 Tavily 搜索即可。

验证¶

不依赖 DSH 与网络的 smoke 测试：

npm test
npm run test:schema
npm run test:all

适用场景与注意¶

适合：已在 DSH 里使用 web_search / web_fetch，希望统一走 Tavily API，并需要在设置页管理 key 与搜索/抓取参数的团队或个人开发者。

注意：

• 插件以当前 DSH 进程权限运行；安装前应自行审阅 源码与 LICENSE，社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
• DSH 与 seam API 可能随版本变化；升级 DSH 后建议回归 npm run test:schema。
• 缺少 schemastery 时功能降级为无设置页，控制台会有警告。

结尾¶

dsh-tavily 在不动模型工具面的前提下，把 DSH 默认联网通道换成 Tavily，并提供 Settings → Tavily 与可分的搜索/抓取策略。按需安装、配 key、重启后即可在原有 web_search / web_fetch 工作流中使用。

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