前言¶

在 DeepSeek Harness（DSH）里做需要实时信息的智能体时，往往既要让壳自带的 web_search 走统一入口，又希望直接调用搜索、抽取、爬取、站点映射和深度研究等能力。自行对接 Tavily API 会重复处理鉴权、额度与审计。下面介绍社区插件 @zx06/tavily（仓库 zx06/dsh-tavily），它把 Tavily 注册为 ctx.web 的搜索 provider，并附带五个独立工具与设置页。

这是什么¶

@zx06/tavily 由维护者 zx06 发布，分类为联网工具。插件同时提供两种接入方式：

1. ctx.web 搜索 provider（id 为 tavily）——注册进 DSH 的 web 能力 seam，壳自带的 web_search 也可返回 Tavily 结果。
2. 五个独立工具——不依赖 provider 选择，安装 profile 后即可按工具名调用。

另含设置页：API Key、搜索选项、额度卡片、审计日志。当前 GitHub 星标为 0；包版本在资料中为 0.1.0，许可证 MIT。

核心功能¶

五个工具¶

tavily_research 的两种模式

• 传 input：创建任务并在工具内轮询到完成（受 researchTimeoutMs 限制）。若超时仍在运行，会返回 requestId 与提示，不会丢失任务。
• 传 request_id：只查询一次状态，用于继续轮询已有任务。

ctx.web Provider¶

插件注册 id 为 tavily 的搜索 provider。DSH 选择规则要点：

• 未配置 web.searchProvider 且只有一个可用 provider 时自动选中；
• 配置 web.searchProvider: tavily 时选中 Tavily；
• 未配置 Key 且关闭免密时，available() 返回 false，不参与选择，避免单 provider 部署因未配置 Tavily 而出现 WEB_PROVIDER_AMBIGUOUS。

若 profile 将 web.searchProvider 固定为 deepseek-official，Tavily provider 不会被选中，此时可直接使用 tavily_* 工具。

设置页与凭据¶

设置页包含：API Key 表单（密文，保存时自动校验）、搜索选项（默认结果数/深度/超时/是否允许免密）、额度卡片（Tavily /usage）、本月用量统计、审计日志表。

API Key 优先级（从高到低）：

1. DSH 设置页 → Tavily 搜索（推荐）。保存时用 Tavily /usage 校验，通过后写入 DSH 凭据服务（$DSH_HOME/.credentials.yaml）。
2. 环境变量 TAVILY_API_KEY。若已设置，设置页会拒绝保存并提示取消该环境变量（继承环境只读且遮蔽写入）。
3. 插件 config 的 apiKey 字段（role('secret')）。凭据引用名可通过 apiKeyEnv 修改，默认 TAVILY_API_KEY。

Key 申请：https://app.tavily.com。

免密模式¶

Tavily 允许无 Key 使用 search 与 extract（共享限速）。插件默认 allowKeyless: true：未配置 Key 时 tavily_search / tavily_extract 仍可用；crawl / map / research 会给出明确提示；触发免密限速时会提示配置 Key 及建议等待秒数。关闭 allowKeyless 后，未配置 Key 时所有工具直接报错。

审计¶

调用记录写入 ~/.dsh/tavily/audit-YYYYMM.jsonl：时间、工具、目标、耗时、结果数、状态/错误码、调用方、本次消耗的 credits。Key 不写入日志（目标中 tvly-... 等字符串会脱敏）。可在设置页查看，也可直接读文件。

安装与启用¶

在 web profile 下安装（npm 与 GitHub 通道为同一份构建产物）：

# npm 通道（推荐）
dsh plugin --profile web add @zx06/tavily

# GitHub 通道
dsh plugin --profile web add github:zx06/dsh-tavily

装好后重启 profile，在 设置 → Tavily 搜索 填写 API Key；也可先依赖免密模式试用 search / extract。

本地开发联调可先构建再以本地路径通道安装：

pnpm install && pnpm build

然后用 install_bundle 安装本仓库根目录。

典型用法¶

1. 仅要联网搜索与正文抽取：安装后可在未填 Key 的情况下调用 tavily_search、tavily_extract（受免密限速约束）。
2. 让壳内 web_search 走 Tavily：确保 profile 未独占其他 provider，或设置 web.searchProvider: tavily，并视需要配置 Key 或保持免密（仅 search/extract 相关能力在免密下可用）。
3. 爬取、站点地图、深度研究：在设置页配置有效 API Key 后使用 tavily_crawl、tavily_map、tavily_research；研究任务超时可凭返回的 requestId 用 request_id 参数继续查询。
4. 排查用量与失败：在设置页看额度与审计，或直接查看 ~/.dsh/tavily/audit-YYYYMM.jsonl。

README 未给出完整对话示例；实际参数以 DSH 工具 schema 与 Tavily 文档为准。

适用场景与注意¶

适合：已在 DSH web profile 中开发智能体、希望统一 Tavily 搜索与抽取，或需要 crawl/map/research 与额度、审计一体化的团队。

权限与安全：插件以当前 DSH 进程权限运行，会向 Tavily 发起外网请求。安装前请阅读仓库源码与 MIT 许可证，确认凭据存储方式（$DSH_HOME/.credentials.yaml）符合你的环境策略。

与旧版 @dsh-plugins/search-tavily 的差异：包名与 provider id 改为 tavily；Key 不再使用 ~/.dsh/tavily.key，需在设置页重新填写；审计目录由 ~/.dsh/search-tavily/ 改为 ~/.dsh/tavily/。

生态说明：DSH 社区插件目录（如 SkillHub、dsh-plugin.org）为独立站点，与 DeepSeek / 幻方无官方从属关系；本文不将其描述为官方应用商店。

结尾¶

@zx06/tavily 把 Tavily 的搜索 provider 与五类工具、设置页和审计收进一个 DSH 插件，便于在 Harness 内完成联网检索与研究类任务。目录与源码：

• 目录页：https://www.skillhub.cn/plugins/zx06/dsh-tavily
• GitHub：https://github.com/zx06/dsh-tavily