Tavily 搜索 ShawnOY/dsh-tavily

@0x427567/dsh-tavily

一个由 Tavily 支持的搜索提供程序，用于 DeepSeek Harness 的 Web 能力接缝（ctx.web），以 DSH bundle 形式发布，因此 dsh plugin add 即可将其接入，无需手动编辑 profile。

Tavily 对 /search 的响应直接返回结果列表本身——标题、URL、内容以及可选的发布日期——因此一次搜索就是一次 HTTP 请求：无需辅助模型轮次，也无需从提供程序的文本中抓取结果。

这个提供程序有何不同

DSH 已有多个 Tavily 提供程序。这一个围绕一个核心理念构建：究竟是哪个凭据层级为你的搜索服务，绝不应是一个悄无声息的决定。

- 无密钥优先。 Tavily 在完全无需账户的情况下即可提供 /search，因此本提供程序无需存储密钥即可工作。只有在无密钥层级拒绝服务后，才会去取用你的密钥。
- 拒绝是可见的。 当无密钥层级拒绝服务时，该层级会被冷却，而切换到你的密钥这一行为会在搜索结果本身中报告——并记录日志——而不是在你背后悄悄发生。两者都遵循你的 harness 语言。
- 显式模式。 keyless-first（默认）、key-first、keyless-only、key-only。
- 无需构建步骤。 纯 ESM，按原样发布。安装它不会运行任何安装脚本，因此不需要 allowBuilds 权限。

安装

需要 Node ^22.19 || >=24，以及一个在 ^0.1.5-rc.2 版本提供 @deepseek-ai/dsh-web 和 @deepseek-ai/dsh-credentials 的 harness——两者均声明为 peer 依赖，因此较旧的 harness 会导致安装失败，而不是加载一个它无法运行的插件。

从 npm 安装（推荐）

dsh plugin --profile web add @0x427567/dsh-tavily

已预构建，因此你的机器上不会编译任何内容。该包使用 scope 是因为 dsh-tavily 和 dsh-web-tavily 在 npm 上已被其他 Tavily 提供程序占用。

从 GitHub 安装

dsh plugin --profile web add github:ShawnOY/dsh-tavily

两种形式安装的是同一个包。它声明了 dsh.bundle.patch，因此 dsh plugin add 会将其注册到 profile 的 dsh.profile.bundles 中，而其随附的 patch 会挂载该提供程序、将 Web 接缝的搜索固定到它，并关闭基础 bundle 随附的 DeepSeek 搜索提供程序。因此 web_search 由 Tavily 支持，并且 Settings → Plugins → Plugin configuration 仅显示此插件的卡片。其 Search provider 选择器可切换到随附的 DeepSeek 后端，无需重启。无需其他配置。

之后重启 harness：基础 hmr 行已被禁用，因此新添加的模块不会被热重载。

从本地检出安装

先打包，然后安装 tarball：

npm pack
dsh plugin --profile web add ./0x427567-dsh-tavily-.tgz

不要将 dsh plugin add 指向检出目录。pnpm 会将目录依赖安装为符号链接，而 Node 会将符号链接模块解析到其真实路径——因此，位于 harness home 之外的检出目录会针对该检出目录的自己的 node_modules，而不是 harness 的，并且启动会失败并报 Cannot find package '@deepseek-ai/schemastery'。tarball 会把包解压到 profile 内部，在那里 peer 依赖能正确解析。在 checkout 中执行 npm install 仅用于运行测试套件；它会拉取宿主包自己的副本，这对打桩测试来说没问题，但加载到 harness 中就不对了。

手动方式，通过相对路径

如果你不想安装包，请将此目录复制到 /plugins/tavily-search/，并向 /cordis.patch.yml 添加：

- insert:
- id: web-search-tavily
name: ./plugins/tavily-search/index.js
config:
apiKeyEnv: TAVILY_API_KEY

The shipped DeepSeek provider starts off, so the default selection is this
one; the card switches between them inside this plugin. Pinning the seam is
what keeps a third search provider from making it ambiguous.
- id: web-search-deepseek
disabled: true

- id: web
config:
searchProvider: tavily
fetchProvider: http

凭据

无密钥方式不需要任何凭据。要使用带密钥的层级，请通过以下任一方式提供密钥——先匹配者生效：

1. 在此插件配置中直接写 apiKey（避免这样做；它会落入配置文件）。
2. 在 harness 的凭据存储 ~/.dsh/.credentials.yaml 中设置 TAVILY_API_KEY（或你的 apiKeyEnv）：

version: 1
refs:
TAVILY_API_KEY: tvly-...

3. 在启动 harness 的环境中设置同一变量。

无密钥方式免费但有速率限制，且 Tavily 未公布无密钥限制。密钥有已记录的限制（开发 100 RPM，生产 1,000 RPM）。当无密钥层级拒绝时，此提供方会回退到你的密钥并告知你。

配置

| 键 | 默认值 | 含义 |
| apiKey | — | 字面密钥。优先使用凭据存储。 |
| apiKeyEnv | TAVILY_API_KEY | 每次搜索时解析的凭据引用。必须是 shell 风格名称（[A-Za-z_][A-Za-z0-9_]）；其他任何内容在配置加载时都会被拒绝。 |
| baseURL | https://api.tavily.com | API 基础地址；会追加 /search。 |
| searchDepth | basic | Tavily 的 search_depth。advanced 费用更高。 |
| maxResults | 5 | 调用方未设置时的结果上限。 |
| includeAnswer | false | 同时向 Tavily 请求由 LLM 撰写的答案。 |
| provider | tavily | 由哪个后端响应 web_search：tavily 或 deepseek-official——参见切换提供方。 |
| mode | keyless-first | 凭据策略——见下文。 |
| keylessCooldownMinutes | 10 | 被拒绝的无密钥层级跳过多久。0 禁用冷却。 |
| language | auto | 仅此插件的文案语言。auto 遵循 harness 偏好——参见语言。 |

provider、mode、keylessCooldownMinutes 和 language 也可在运行时从设置 → 插件 → 插件配置 编辑。此包附带一个浏览器端部分，为其提供卡片 dsh-tavily 命名空间——仅在 Host 上注册命名空间本身是不够的，因为该页面只渲染卡片所声明的命名空间。那里的更改会在下一次搜索时生效，而配置文件补丁仍是重置时返回的基准值。其他键仅存在于文件中。

模式

| mode | 行为 |
| keyless-first （默认）* | 先尝试免密钥；被拒绝时，将该层级冷却并改用密钥重试。 |
| key-first | 只要解析到密钥就使用密钥；仅在无密钥可用时使用免密钥。 |
| keyless-only | 从不发送密钥。 |
| key-only | 要求密钥；从不使用免密钥层级。 |

拒绝是指 HTTP 401、403 或 429，或返回 200 但响应体携带的是说明文字而非 results 数组——Tavily 对达到上限的免密钥调用会返回说明，而不是机器可读的错误。
400（错误的查询）不算拒绝：用密钥重试也无济于事，因此错误会直接暴露。

回退时你会看到什么

该切换会在搜索结果中声明，harness 将其渲染为工具输出：

⚠️ Tavily 免密钥额度已用尽，这次改用密钥；接下来约 10 分钟内直接使用密钥。

并且，在冷却生效期间：

⚠️ Tavily 免密钥服务冷却中（约剩 7 分钟），这次使用密钥。

两者还会向 harness 日志发出 warn。正常路径是静默的。上述措辞是默认值（简体中文）；其他两种见语言。

语言

通知、日志警告以及此提供程序自身的错误消息都遵循 harness 语言偏好——设置 → 通用 → 语言——因此它们与设置卡片及 UI 其余部分已经使用的语言保持一致。
语言更改会在下一次搜索时生效。

卡片自身的 language 字段仅为此插件覆盖该设置。 将其保留为 auto 以跟随 harness；选择某种语言可将 UI 其余部分保持在原处，仅让此卡片和此插件的通知使用该语言。两半读取同一字段，因此卡片和记录不会在语言上产生分歧。

提供三种语言：

| 偏好 | 语言 | 来源 |
| zh （默认） | 简体中文 | harness 自带的 zh，因此与外壳一致 |
| en | 英语 | harness 自带的 en |
| zh-Hant | 繁体中文 | 此包添加的语言包 |

zh 和 en 内置于 harness；zh-Hant 随此插件的浏览器端一同提供，后者为其调用 ctx.locale.addLanguage。它会回退到 zh，因此语言包中缺失的键会被解析，而不会渲染为原始标识符。

该语言包注册在 script 标签下，刻意不使用诸如 zh-TW 这样的区域标签。
这样可将默认值保持在应有的位置：报告 zh-TW 或 zh-HK 的浏览器匹配 zh 主语言子标签并以简体打开，而繁体读者只需选择一次繁體中文即可选用。
若改为注册 zh-TW，则会精确匹配这些浏览器并将它们拉离默认值。
两半都以相同方式解析给定的偏好——精确 id 优先，其次是主子标签——因此未随附的 zh-TW 或 zh-HK 会在卡片和通知中都落到简体 zh，而不是两者不一致。

它们唯一可能分道扬镳的情况是浏览器从未选择过语言，并且自身报告 zh-Hant。客户端会精确匹配它并以繁体打开；而 Host 完全看不到已存储的偏好，因此其通知使用默认的简体。
在 Settings → General → Language 中选择一种语言会将其持久化并弥合这一差距。
其他任何方式都不行：浏览器的语言列表永远不会离开客户端，而且客户端有意不会将浏览器推导出的猜测写入持久设置文档。

切换提供商

Settings → Plugins → Plugin configuration → Tavily web search 带有一个 Search provider 选择项：

| 值 | 后端 | 页面上的卡片 |
| tavily （默认） | 本插件，优先无密钥 | 此卡片 |
| deepseek-official | dsh-base 随附的 DeepSeek 搜索提供商，在本插件内运行 | 此卡片 |

该选择会应用于下一次 web_search——无需重启——并且它存储在设置文档中，因此重启后依然保留。配置文件补丁仍然是重置后恢复到的值。

两种选择都通过本插件应答，因此无论哪种方式页面都保留一张搜索卡片。该接缝固定到此提供商，且永不重新解析，这也意味着同时安装的第三个搜索提供商无法使其产生歧义。

内置选择唯一没有继承过来的是它的设置卡片。随附提供商的端点和模型保持其默认值，以 DEEPSEEK_SEARCH_BASE_URL 作为覆盖项，其密钥从凭据存储或环境中的 DEEPSEEK_API_KEY 读取。

切换是如何接线的

web_search 本身不是搜索引擎：它是一个面向模型的工具，调用
ctx.web.search()，而接缝解析一个已注册的提供商。三行决定
是哪一行：

- web 行固定 searchProvider: tavily，因此接缝始终解析到此包；
- 只要其基础 URL 能解析，此包的提供商就会被注册并可用——无密钥层级不需要凭据，因此存储的密钥不是前提条件——并且其
search() 根据 provider 设置进行路由；
- web-search-deepseek 行保持禁用，这正是让 Plugins 页面只保留一张搜索卡片的原因。

因此，选择 deepseek-official 不会移动固定项，也不会触碰加载器。此包从 @deepseek-ai/dsh-web-search-deepseek 导入 DeepSeekSearchProvider——一个已声明的 peer 依赖——并委托给它，因此该后端的行为、错误和端点处理都是随附的。代价是随附提供商的自身配置卡片消失了，随之而来的是从 UI 编辑该端点和模型的能力。

该补丁还重新声明了 fetchProvider: http，因为补丁会替换目标行的整个 config，丢弃它会使 web fetch provider 处于未设置状态。

你自己的 cordis.patch.yml 会在每个 bundle 层之后应用，因此你仍然可以覆盖这些行中的任意一行——但要做到这一点，你必须重新声明整个 config。

注意事项

- 随附的 DeepSeek 搜索 provider 默认处于关闭状态，其设置卡片也保持关闭。 默认选择是 Tavily，因此 Settings → Plugins 只显示此插件的卡片；选择 deepseek-official 会运行该后端，但不会让其卡片重新出现。其 endpoint 和 model 无法从 UI 编辑。
- Keyless 没有账户，也没有合约。 你不接受任何条款，并且对数据去向的掌控力最小。它是试用工具的正确默认值，但不适合任何敏感用途——参见 Tavily on keyless。
如果你希望始终使用自己的账户，请设置 mode: key-first。
- 该卡片涵盖 provider、language、mode 和 cooldown。 其余键——apiKey、apiKeyEnv、baseURL、searchDepth、maxResults 和 includeAnswer——在 profile patch 或 settings document 中设置，并且没有“test this key”按钮。
- 繁体中文是一个语言包，而不是 zh 的一个构建。 harness 将裸 zh 读取为简体，因此繁體位于 zh-Hant。它在语言列表中显示为一个额外条目，而不是中文的一个变体，繁体读者必须选择它一次。没有提供 zh-TW/zh-HK 条目，因此除非有人另行选择，否则这些浏览器会保持简体默认值。

开发

npm test # both offline suites
node test/provider.test.mjs # the Host half only
node test/client.test.mjs # the browser half only
TAVILY_LIVE_TEST=1 node test/provider.test.mjs # + a live keyless call
TAVILY_LIVE_TEST=1 TAVILY_API_KEY=tvly-... node test/provider.test.mjs

离线断言会 stub fetch；实时断言是 opt-in 的。该插件以裸 specifier 导入其 @deepseek-ai/* peers，因此请在那些可以解析的地方运行测试——例如在已安装该插件的 profile 内。

test/client.test.mjs 使用 stub require 和 stub context 搭建 __ModuleLoader__ 合约，因此浏览器部分的接线——它注册的 dictionaries 和它添加的 language pack——无需浏览器即可检查。它不会渲染卡片。

client.js 是浏览器部分。它是一个预构建 bundle，形态符合 client module system 所提供的形式——一个接收宿主 require 的 window.__ModuleLoader__.load factory——因此它按原样提供，无需构建步骤。其 dsh.client.platform 为 web，并且在浏览器模块图中注册为 @0x427567/dsh-tavily/client.js。

许可证

MIT——参见 LICENSE。