前言¶
在 DeepSeek Harness（DSH）里做联网检索时，常见做法是接一家搜索 API，再通过 ctx.web 的搜索能力缝暴露给智能体。Tavily 的 /search 直接返回标题、URL、正文和可选发布日期，一次 HTTP 即可拿到结构化结果列表，不必再让模型从 provider 的自然语言里「抠」结果。
社区里已有多种 Tavily 类 DSH 插件。@0x427567/dsh-tavily（仓库 ShawnOY/dsh-tavily）的差异在于：本次搜索究竟走免密钥档还是你的 API 密钥，不应在后台静默切换。默认先试 Tavily 免密钥档；被拒后再用密钥，并在工具输出与日志里明确告知。下面介绍它的定位、安装与配置。
这是什么¶
@0x427567/dsh-tavily 是一个以 Tavily 为后端的搜索 provider，挂载在 DSH 的 web 能力缝（ctx.web）上，以 bundle 形式发布：dsh plugin add 会写入 profile，无需手改 cordis 配置。
- 维护者：ShawnOY（GitHub：ShawnOY/dsh-tavily）
- 分类：联网工具（社区目录：skillhub.cn/plugins/ShawnOY/dsh-tavily）
- 许可证：MIT（见仓库
package.json，当前版本 0.2.1） - 解决的问题：让
web_search由 Tavily 承接；同时把凭证策略（免密钥 / 密钥）和回退行为做成可配置、可观测。
安装后，bundle 自带的 patch 会注册 provider、将 web 缝的 search 固定到该插件，并关闭基础 bundle 自带的 DeepSeek 搜索 provider。因此在 Settings → Plugins → Plugin configuration 中，你会看到本插件卡片；其中的 Search provider 可在 Tavily 与官方 DeepSeek 后端之间切换，无需重启 harness（其它文件级配置另论）。
核心功能¶
Tavily 直连搜索¶
Tavily 对 /search 的响应即结果列表本身，一次请求对应一次搜索，不依赖额外模型轮次，也不依赖从 provider prose 里解析结果。
凭证策略：免密钥优先，回退可见¶
- Keyless first（默认）：无账号也可调用 Tavily 免密钥档；仅当免密钥档「拒绝」时才尝试你的密钥。
- 拒绝可见：免密钥被拒后，该档进入冷却，切换到密钥的事实会写在搜索结果正文里，并写入 harness 日志，措辞跟随 harness 语言偏好（默认简体中文示例见 README）。
- 显式模式：
keyless-first（默认）、key-first、keyless-only、key-only。
「拒绝」包括 HTTP 401、403、429，或 HTTP 200 但 body 是说明文字而非 results 数组（Tavily 对受限免密钥调用可能如此）。400 视为坏查询，不会用密钥重试。
免密钥免费但限流，Tavily 未公开免密钥上限；密钥档文档限流为开发 100 RPM、生产 1,000 RPM。
运行时与 UI¶
provider、mode、keylessCooldownMinutes、language 可在 Settings → Plugins → Plugin configuration 中修改，下一次搜索生效；profile patch 中的值为「重置」时的基准。插件自带 browser 端卡片（dsh-tavily 命名空间）。
无构建步骤¶
纯 ESM 发布，安装时不跑 install script，因此不需要 allowBuilds 权限。
环境与依赖¶
- Node：
^22.19 || >=24 - Harness peer（缺版本会导致安装失败而非勉强加载）：
@deepseek-ai/dsh-web、@deepseek-ai/dsh-credentials均为^0.1.5-rc.2
安装与启用¶
推荐从 npm 安装预构建包（作用域名 @0x427567/dsh-tavily 是因为 npm 上 dsh-tavily、dsh-web-tavily 已被其它 Tavily provider 占用）：
dsh plugin --profile web add @0x427567/dsh-tavily
从 GitHub 安装同一包：
dsh plugin --profile web add github:ShawnOY/dsh-tavily
安装完成后需要重启 harness：基础 bundle 的 hmr 行被禁用，新模块不会热加载。
本地开发请 npm pack 后安装 tarball，不要用 dsh plugin add 指向 checkout 目录（pnpm 符号链接会导致 peer 解析到 checkout 的 node_modules，启动失败）。资料中的示例：
npm pack
dsh plugin --profile web add ./0x427567-dsh-tavily-<version>.tgz
凭证配置¶
免密钥无需配置。要用密钥档，按先匹配先生效：
- 插件 config 中的字面量
apiKey（不推荐，会落在配置文件里） - harness 凭证库
~/.dsh/.credentials.yaml中的TAVILY_API_KEY（或你配置的apiKeyEnv）：
version: 1
refs:
TAVILY_API_KEY: tvly-...
- 启动 harness 进程时的同名环境变量
配置项¶
| Key | 默认值 | 含义 |
|---|---|---|
apiKey |
— | 字面量密钥，优先用凭证库 |
apiKeyEnv |
TAVILY_API_KEY |
每次搜索解析的凭证引用名 |
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 Settings → General → Language |
provider、mode、keylessCooldownMinutes、language 可在插件配置卡片改；其余项仅 profile / 文件配置。
典型体验¶
正常搜索¶
智能体调用 harness 的 web_search 时，由本 provider 请求 Tavily；成功路径下工具输出为结果列表，无额外切换提示。
免密钥用尽后的回退¶
当免密钥档拒绝且存在可用密钥时，工具输出中会包含类似说明（简体中文默认）：
⚠️ Tavily 免密钥额度已用尽，这次改用密钥；接下来约 10 分钟内直接使用密钥。
冷却期内再次搜索可能看到剩余分钟数提示。同一事件会 warn 写入 harness 日志。
切换搜索后端¶
在插件配置卡片将 Search provider 切到官方 DeepSeek 后端时，web_search 改由该后端响应，无需重启；切回 Tavily 同理。
适用场景与注意¶
适合谁
- 已在 DSH web profile 下开发智能体，需要稳定、结构化的联网检索。
- 希望先零配置试用 Tavily 免密钥，再在额度或限流触顶时用自有密钥，且要求切换对用户和日志可见。
- 需要与基础 bundle 自带 DeepSeek 搜索 provider 在同一卡片内切换，而不是混进多个未固定的第三方 search provider。
务必注意
- 插件在当前 dsh 进程权限下运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。
- 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系，并非官方应用商店。
- 勿将 API 密钥硬编码进可提交的 profile；优先
~/.dsh/.credentials.yaml或环境变量。 - 星标与生态热度以仓库页为准（目录抓取时为 0），选型时请结合版本、issue 与自身合规要求判断。
结尾¶
@0x427567/dsh-tavily 把 Tavily 接到 DSH 的 ctx.web 搜索缝，强调 keyless-first 与 回退可见，并 bundled 进 web profile，减少手改 cordis。若你正在 web profile 里做联网 agent，可按上文命令安装、按需配置密钥与 mode，重启 harness 后即可用 web_search 验证。
