Tavily 网页搜索 fan56/dsh-web-search-tavily

dsh-web-search-tavily

DeepSeek Harness (dsh) 插件，通过 Tavily Search API 提供网页搜索。

要求 dsh >= 0.2.0-rc.2 —— 本插件只面向 dsh 的 RC/stable 线（CI 和发布在运行时解析 latest/next dist-tags 中最新的一个）。alpha 线不再支持。

它替换掉 DeepSeek 默认的网页搜索 —— 默认搜索每次搜索都要花掉一整次辅助模型调用（Anthropic 兼容的 Messages API + web_search_20250305 服务端工具）—— 换成一个普通的 Tavily REST 调用：约 1 秒，basic 深度下消耗 1 个 credit，不花模型 token。

插件向官方 ctx.web 能力接缝注册一个 WebSearchProvider（id: "tavily"），所以工具周边的一切都保持出厂原样：模型仍然调用同一个 web_search 工具，引用格式、searchMaxResults 上限、超时预算都不变。换服务商只改变 harness 访问网络的方式，别的什么都不动。

要求

- dsh >= 0.2.0-rc.2（peer 依赖解析到配置档共享的 @deepseek-ai 闭包）
- 一个 Tavily API key（tvly-…，有免费额度）

安装

一条命令：

dsh plugin --profile <name> add @aiwayds/dsh-web-search-tavily

dsh plugin 把包安装进配置档（通过 pnpm），并自动在 dsh.profile.bundles 里注册。重启 dsh —— 服务商已注册就绪。本地开发：dsh plugin --profile <name> add link:/path/to/dsh-web-search-tavily（相对路径会锚定到你执行命令的目录）。手动方式 —— 自己把依赖和 bundle 条目加进 ~/.dsh/profiles/<name>/package.json，再在那里跑 pnpm install —— 效果完全一样。

和 anysearch 那个姊妹插件不同，本插件安装时不会抢占 web_search 默认位 —— Tavily 需要 API key，一个被选中却没配置好的服务商会让每次搜索都失败。存好 key 之后，用一条 patch 条目选中它（见下）。

@deepseek-ai/* 包按设计就是 peer 依赖：它们必须解析到配置档唯一共享的 dsh 闭包（link-dsh-closure）。把它们放进 dependencies 会装出第二个 cordis 实例，把加载器搞崩。

卸载

dsh plugin --profile <name> remove @aiwayds/dsh-web-search-tavily

宿主会自动清理整个安装：bundles 条目从配置档的 package.json 里剔除，依赖被移除，插件的 patch 层随包一起消失。重启 dsh，tavily 服务商就没了 —— web_search 回退到你的 patch 层仍然选中的那个服务商（默认是出厂的 deepseek-official）。

插件不保留任何磁盘状态。你的 Tavily API key 存在宿主管理的存储里 —— ~/.dsh/.credentials.yaml 中的 TAVILY_API_KEY ref，或者启动环境——卸载永远不会动它。如果你不再需要这个密钥（或者不再需要 searchProvider: tavily 这条选择服务商的补丁条目），手动删掉即可。

配置

1. API 密钥。 把密钥存进 dsh 托管的凭据文档（~/.dsh/.credentials.yaml）——每次搜索时解析，绝不写进配置文件：

version: 1
refs:
TAVILY_API_KEY: tvly-xxxxxxxx

回退顺序，按解析优先级：启动环境里的 TAVILY_API_KEY，然后是插件配置里的字面量 apiKey（不推荐）。

2. 选择服务商。 基础 bundle 把 web.searchProvider 固定为 deepseek-official，而配置过的 id 总是优先——所以把覆盖项加到配置档的 cordis.patch.yml（或者加到 home 级的 ~/.dsh/cordis.patch.yml，对所有配置档生效）：

- id: web
config:
searchProvider: tavily

也可以顺手把 DeepSeek 搜索插件整个停用：

- id: web-search-deepseek
disabled: true

重启 dsh。验证合成后的树：

dsh --profile <name> --dump-config | grep -A3 'id: web$' # searchProvider: tavily

回滚： 删掉补丁条目并重启——web_search 就回到随包发布的 DeepSeek 服务商。

插件配置（全部可选；通过补丁层写入，启动时读取）：

| 字段 | 默认值 | 说明 |
| apiKeyEnv | TAVILY_API_KEY | 凭据引用，每次搜索时解析 |
| apiKey | — | 字面量密钥；优先于引用 |
| baseURL | https://api.tavily.com | 环境变量覆盖：TAVILY_BASE_URL |
| searchDepth | basic | basic / advanced（2 credits）/ fast / ultra-fast |
| topic | general | general / news / finance |
| maxResults | 8 | 工具未传上限时的默认值；API 上限为 20 |
| includeAnswer | true | Tavily 生成的答案会成为结果的 content |

带配置的补丁条目示例：

- insert:
- id: web-search-tavily
name: '@aiwayds/dsh-web-search-tavily'
config:
searchDepth: advanced
topic: news

行为

- results[].content → 可移植的 snippet；Tavily 的 answer → 结果的 content；API 不返回发布日期，所以 publishedAt 永远不设置。
- 遵循 ctx.web 接缝契约：取消为 WEB_ABORTED，密钥缺失为 WEB_PROVIDER_CREDENTIAL_MISSING（会点名 TAVILY_API_KEY），服务商故障为 WEB_PROVIDER_ERROR，并带出 Tavily 自己的错误详情；密钥被拒时读作 Tavily rejected the API key (HTTP 401)。
- available() 只做本地检查（凭据来源存在、base URL 可解析）——绝不发起网络请求。
- 结果数量请求会被夹到 Tavily 的 max_results 上限（20）；接缝还会额外执行工具的 searchMaxResults 上限（默认 8）。

开发

npm install
npm run check # tsc --noEmit
npm test # build + node --test (14 tests)

改完 src/ 后，运行 npm run build 并重启 dsh——插件从 lib/。单元测试覆盖响应映射、可用性、请求结构，以及 HTTP、中止、凭据三类错误分支，fetch 已 mock。

许可证

MIT