Tavily 搜索中继 hjnvv00v/dsh-web-search-tavily-relay

dsh-web-search-tavily-relay

为 DeepSeek Harness 的 web 接缝（ctx.web）提供由 Tavily 驱动的网页搜索——端点、凭据、传输协议全部可配置，所以中继或网关域名用起来和官方域名完全一样。

注册进 ctx.web 后，harness 内置的 web_search 工具会直接使用这个服务商。不用再学额外的工具，中间也没有 MCP 进程。

为什么不用官方 Tavily MCP 服务器？

Tavily 确实提供了一个（tavily-mcp），DSH 也能通过 dsh-mcp-client 接入。但它不适合中继部署：

- 端点硬编码为 https://api.tavily.com/{search,extract,crawl,map,research,feedback}，没有 base URL 设置项，用不了自定义域名。
- 它的工具绕开了 ctx.web 接缝，内置的 web_search 仍然使用接缝选定的服务商，模型还得在两套并行的工具之间做选择。

这个插件走的是接缝原生路线：一个服务商，三种传输协议，一个可配置端点。

协议

| protocol | 请求 | 适用场景 |
| tavily（默认） | POST {base}/search，请求体用 Tavily 自己的格式 | Tavily 本身，以及照搬其 REST 形态的中继 |
| openai-responses | POST {base}/responses，使用原生 web_search 工具 | 暴露 Responses API 的 OpenAI 兼容网关 |
| openai-chat | POST {base}/chat/completions，带 web_search_options | 模型能搜索并给出引用的 OpenAI 兼容网关 |

别名也接受（responses、chat、rest 等），端点既可以是 base（https://relay.example/v1 → …/v1/search），也可以是完整 URL。

来源只从结构化证据里读取：Tavily 的 results[]、Responses 载荷的 url_citation 注解和 web_search_call 来源，或者 Chat 载荷的注解——网关完全不返回注解时，才回退到答案里的 markdown 链接。

配置

下面这些都能在 Web 侧边栏 Plugins 下的插件页面里改，也可以写进配置档的 cordis.patch.yml。

| 字段 | 默认值 | 含义 |
| providerId | tavily | 注册表 id；必须和 web 条目的 searchProvider 一致 |
| protocol | tavily | tavily、openai-responses 或 openai-chat |
| baseURL | 协议默认值 | 中继域名或完整端点；留空则用 https://api.tavily.com 或 https://api.openai.com/v1 |
| apiKey | 省略 | 明文密钥；建议改用 apiKeyEnv，别让密钥进设置文件 |
| apiKeyEnv | TAVILY_API_KEY | 凭据引用，先经 ctx.credentials 解析，再查启动环境 |
| authStyle | auto | auto、bearer、body、header 或 none |
| authHeader | 省略 | authStyle: header 时的请求头名 |
| authScheme | Bearer | 密钥前缀；留空则直接发送密钥 |
| model | gpt-4o-search-preview / gpt-4o | OpenAI 兼容协议使用的模型名 |
| searchDepth | basic | Tavily search_depth |
| topic | general | Tavily topic |
| maxResults | 5 | 向服务商请求的结果数上限 |
| includeAnswer | "false" | 让 Tavily 返回一段综合答案，作为结果的 content 呈现（即来源列表上方那段文字） |
| includeRawContent | false | 同时让 Tavily 返回 raw_content；接缝的来源结构里没有存放整页正文的位置，所以它只能补上缺失的摘要片段——要抓整页请用 web_fetch |
| includeDomains / excludeDomains | [] | Tavily 域名过滤 |
| responsesToolType | web_search | 有些网关需要 web_search_preview |
| chatWebSearchOptions | true | 在 Chat Completions 请求里发送 web_search_options |
| timeoutMs | 30000 | 单次请求超时 |
| defaultParameters | 省略 | 兜底请求字段，最后合并——对应官方 MCP 的 DEFAULT_PARAMETERS |
| extraHeaders | {} | 额外请求头，最后合并 |

兜底参数

Tavily 官方 MCP 用一个 DEFAULT_PARAMETERS 环境变量（或请求头）配置搜索行为，里面是一个 JSON 对象，可以覆盖 tavily_search 工具的任意参数。本插件接收同一个对象，字段名为 defaultParameters，所以 Tavily 以后新增参数时，插件不用改：

- id: web-search-tavily
name: dsh-web-search-tavily-relay
config:
baseURL: https://relay.example
defaultParameters:
time_range: week
country: China
exact_match: true

设置表单只能暂存字符串，所以卡片里写入的是同一份值的 JSON 文本（{"time_range":"week"}）；配置档的 YAML 可以直接写对象。两者最终解析出的字段相同。

它最后合并进请求体，MCP 就是这样把默认值盖在工具自身参数之上的——所以它也会覆盖上面那些已建模的字段。唯一无法替换的字段是 query：如果搜索主题来自配置而不是来自模型，失败会悄无声息，让人一头雾水。

与 MCP 的一处刻意差异。 MCP 的合并循环遍历的是它已经要发送的参数（for (const key in searchParams) if (key in defaults) …），所以 DEFAULT_PARAMETERS 只能覆盖已有值——无法引入服务端从不发送的键。这就导致 include_answer 和 chunks_per_source 无论如何都碰不到官方 MCP。本插件的循环遍历的是配置对象，所以既能覆盖字段，也能新增字段。

| 官方 MCP tavily_search 参数 | 本插件 |
| query | 调用方的 query——永远不可覆盖 |
| search_depth | searchDepth |
| topic | topic |
| max_results | maxResults |
| include_raw_content | includeRawContent |
| include_domains / exclude_domains | includeDomains / excludeDomains |
| time_range、start_date、end_date、country、exact_match、include_images、include_image_descriptions、include_favicon | defaultParameters |
| — 完全无法通过 MCP 访问 | includeAnswer、chunks_per_source，以及 Tavily 接受的其他任何参数 |

认证

authStyle: auto 会发送 Authorization: Bearer <key>，对于 tavily 协议，还会在请求体里带上 api_key —— 实际部署的中转服务通常只实现其中一种。中转服务要求严格时，选 bearer、body 或 header；端点不需要凭证时，选 none。

密钥按以下顺序解析：字面量 apiKey，然后是 ctx.credentials 中 apiKeyEnv 对应的值，最后是启动 DSH 时的环境变量。在配置页面填写的密钥走凭证域，因此不会落到设置文档里。

没有任何密钥时，发往 https://api.tavily.com 的请求会以 Tavily 的无密钥模式发送。

安装

dsh plugin --profile web add github:hjnvv00v/dsh-web-search-tavily-relay

web 是配置档名称 —— 换成你自己的（桌面应用用 desktop）。然后打开 Web 侧边栏 Plugins 下的插件页面，设置凭证；如果你用中转服务，再设置端点，然后重新加载 UI。

单独执行 dsh plugin add 就够了。包里带了 cordis.patch.yml，所以这个 bundle 既挂载自己的 loader 行，又把 web 条目的 searchProvider 指向 tavily —— 为什么这个绑定必须跟着插件走，见选择服务商。

从克隆安装

node install.mjs # copies into the desktop profile and wires the seam
node install.mjs --profile web # or any other profile

安装脚本把包复制到 <profile>/node_modules，加进配置档的 dsh.profile.bundles，并记录依赖。它是幂等的，编辑每个文件前都会备份，node install.mjs --uninstall 可以全部撤销。

选择服务商

ctx.web 只在构造 seam 时读一次 searchProvider，当有多个服务商可用时拒绝猜测 —— 没被选中的服务商就是永远不会被调用的服务商。所以这个绑定放在插件自己的 cordis.patch.yml 里：

- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: tavily

补丁会替换目标条目的整个 config 对象，而不是合并进去，所以这里只重述 searchProvider。fetchProvider 故意不动：默认配置档只挂载一个 fetch 服务商，seam 会自动选中它，重述反而会绑定一个不属于本插件的后端。

配置档自己的 cordis.patch.yml 在所有 bundle 层之后应用，所以想换搜索后端的配置档在那里设置 searchProvider，就能覆盖插件自带的绑定。如果你改过名字，把 tavily 换成对应的 providerId。

失败情况

错误带有 seam 的机器可路由代码：凭证缺失时是 WEB_PROVIDER_CREDENTIAL_MISSING， key，调用方取消时用 WEB_ABORTED，其他所有情况用 WEB_PROVIDER_ERROR——包括超时、非 2xx 响应，或者响应体读不出来。派发之后的每一次失败都会写明解析出的 endpoint，而 HTTP 401/403 的报错信息会直接指向 authStyle 和 key 配置，不让模型自己去猜。

测试

npm install # the schema checks need the @deepseek-ai/schemastery peer
node test/smoke.mjs # host half: protocols, auth, errors, and the Host's schema projection
node test/client.mjs # browser half: bundle contract, slot registration, and a rendered card
node test/install.mjs # installer: what it must write, and what it must never write

测试里没有任何一处会访问网络：test/smoke.mjs 会在 127.0.0.1 上自己起一个 stub endpoint。@deepseek-ai/schemastery 是可选的 peer——运行时由 Host 提供自己的副本，所以有没有它插件都能加载——把它列在 devDependencies 里，纯粹是为了让 npm install 拉一份副本给这些检查用。不装它直接跑，依赖 schema 的检查会报 skip，而不是失败。

test/smoke.mjs 特意让 Config schema 走一遍 host 自己的那份 @deepseek-ai/schemastery：插件解析的是 Host 提供的 peer，而设置投影正是跨过这条边界的唯一契约。这项检查需要知道运行中的 host 把副本放在哪，所以除非你指给它一个位置，否则会跳过：

DSH_HOST_SCHEMASTERY='file:///C:/path/to/dsh/node_modules/@deepseek-ai/schemastery/lib/index.mjs' \
node test/smoke.mjs

License

MIT