Tavily 搜索源coderdailyone/dsh-plugin-web-search-tavily

DeepSeek Harness（dsh）的社区 Tavily 搜索 provider。它向 ctx.web 能力接缝注册一个 WebSearchProvider，让自带的 web_search 工具由 Tavily 提供服务，而不触碰任何模型面 schema。

以 dsh bundle 形式分发：装进 profile 时自动插入插件行。

安装

dsh plugin --profile web add dsh-plugin-web-search-tavily

API key 经环境变量提供（TAVILY_API_KEY，可放在 $DSH_HOME/.env），或写进插件配置。当组合里有多个可用搜索 provider 时，用 $DSH_WEB_SEARCH_PROVIDER=tavily 或在 profile 的 cordis.patch.yml 里给 web 行钉 searchProvider 来指定选择；Tavily 是唯一可用 provider 时自动选中。

先不启动验证组合，再启动：

dsh --profile web --dump-config   # 应出现 "# == dsh-plugin-web-search-tavily" 层
dsh --profile web

配置

在 profile 的 cordis.patch.yml 里 patch web-search-tavily 行即可覆盖任意字段（patch 替换整个 config 值——保留的字段要重述）：

| 键 | 默认 | 含义 |
|---|---|---|
| apiKey | $TAVILY_API_KEY | Tavily API key。为空时 provider 注册但不可用。 |
| baseURL | https://api.tavily.com | 端点基址；/search 由本包追加。 |
| searchDepth | basic | Tavily 的 search_depth。advanced 返回更丰富的摘要，额外计费。 |
| topic | general | Tavily 的 topic 垂直类目（general 或 news；news 会填充 publishedAt）。 |
| includeAnswer | true | 请求 Tavily 生成的答案；作为搜索结果的 content 呈现。 |
| numResults | （缺省） | 请求未携带 maxResults 时的默认结果数。工具层上界始终由接缝强制执行。 |

- id: web-search-tavily
config:
searchDepth: advanced
includeAnswer: false

行为

- POST {baseURL}/search，携带 Authorization: Bearer ，尊重请求的 AbortSignal；拒绝重定向。
- results[].content 映射为 snippet，published_date 映射为 publishedAt；没有非空摘要的条目被丢弃，而不是用编造的文本填充。
- 非空 answer 映射为结果的 content；Tavily 未返回时不虚构任何内容。
- 取消以 WebError 代码 WEB_ABORTED 呈现；其余失败（传输、非 2xx、不可解析响应体）为 WEB_PROVIDER_ERROR，携带可得的最丰富 provider 细节并保留 cause 链。非 2xx JSON 错误体按 detail.error / detail / error / message 顺序取信息。
- available() 是廉价的本地检查（key 存在、基址可解析、界合法），永不触网。

Model Experience

What the model sees

本包不直接向模型呈现任何内容。模型面的 web_search schema 与渲染属于 @deepseek-ai/dsh-tool-web；本 provider 只改变服务该调用的后端。结果的 content（启用时为 Tavily 生成的答案）与逐来源的 title/snippet/publishedAt 经工具的常规渲染流入对话。

Token effect

includeAnswer: true 给模型读到的每次搜索结果增加一段 provider 生成的答案。searchDepth: advanced 倾向于返回更长的摘要。两者都是 provider 输出侧的效果；工具层的 maxResults 上界无论 provider 为谁都由接缝强制执行。

KV Cache effect

无。搜索结果作为普通工具结果进入对话；本包不贡献 prompt 段落，不改变任何请求前缀。

开发

npm install
npm run build
npm test                      # 无 key：回环替身断言线上形状与错误分类
TAVILY_API_KEY=tvly-... npm test   # 追加真机冒烟（无 key 自跳过）

无 key 测试用回环 HTTP 替身驱动真 provider，断言精确的请求形状（方法、路径、bearer 头、user-agent、body 字段）、响应映射、错误分类与取消。真机冒烟对真实 API 验证线上契约，无 key 自跳过；v0.1.1（2026-08）已对真实 Tavily API 验证通过。

Known Limitations and Deferred Work

- Tavily 线上契约钉在其 2026-08 公开文档。 字段名（search_depth、include_answer、max_results）由本包负责跟踪；真机冒烟是漂移探测器，v0.1.1 已对真实 API 验证为绿。
- 未暴露 include_domains / exclude_domains / days。 接缝的请求今天只携带 query 与 maxResults；域名过滤应是 provider 配置而非逐调用控制，且尚无消费者提出需求。
- 无重试策略。 瞬态 Tavily 失败呈现为一次 WEB_PROVIDER_ERROR；重试留给调用方或未来的接缝级策略，与树内 provider 一致。
- dsh 处于 developer preview。 本包钉在当前发布的预发布版 @deepseek-ai/dsh-web 上；上游迭代期间预期需要跟随升版。

License

MIT