@arcaneorion/dsh-tavily-web：DeepSeek Harness Tavily 检索与网页抓取能力层

前言¶

DeepSeek Harness (DSH) 采用插件化架构。在构建需要联网能力的智能体或应用时，对接 Tavily API 进行检索以及获取网页正文是常见需求。本插件旨在为 DSH 提供一个能力层，通过注册两个模型可见的工具，解决单账号额度耗尽导致工具失效的问题，并提供基于 shell seam 的网页抓取能力。

核心能力¶

插件注册了两个模型可见的工具，并将自身挂载为宿主 web 注册表的唯一 fetch provider。

tavily_search：基于 Tavily API 的检索工具。返回包含来源列表（URL、标题、摘要、发布时间）的 JSON 数据。插件实现了多 API Key 轮询池，单账号额度耗尽时自动切换下一把 Key，不会导致整个工具失效。
web_fetch：基于 shell seam 调用 curl 抓取单页的工具。不依赖 Tavily API，无需 Key。返回 HTTP 状态码及去标签后的正文内容。

为了与出厂的 DeepSeek provider 区分，检索功能不注册为 web.search() provider，而是作为模型可见工具存在，避免选择歧义。

安装与启用¶

该插件为 profile bundle，安装一次后，该 profile 下的所有会话均可使用上述工具。

dsh plugin --profile web add @arcaneorion/dsh-tavily-web

安装完成后，需要重启 DSH（dsh --profile web），因为 host 插件不支持热重载。启动日志中应出现类似 (key pool: N ref(s), cooldown 900s) 的信息以确认加载成功。

配置说明¶

插件默认配置了一个包含 8 个 key 引用名的轮询池（TAVILY_API_KEY 至 TAVILY_API_KEY_8）。未配置的引用名会被自动跳过，零成本运行。

要覆盖默认配置，需修改用户层 ~/.dsh/profiles/<profile>/cordis.patch.yml，而不是修改包自带的 patch：

- id: tavily-web
  config:
    keyRefs: [TAVILY_API_KEY, TAVILY_WORK_KEY]   # 替换默认家族
    apiKeys: []                                  # 字面量 key，排在 keyRefs 之后；密钥更该放 seam
    cooldownSeconds: 900                         # 403/429/432 后的退避秒数

技术细节与注意事项¶

兼容性¶

当前插件适配 DSH 0.2.0-rc.1（peer 声明为 0.2.0）。在升级 DSH 版本前，建议先验证 peer 依赖版本，因为 web 注册表与 shell seam 的契约在不同版本间可能发生变化。

发布形态限制¶

npm tarball 仅包含 src/、cordis.patch.yml、README.md，不包含 tests/ 目录。要运行测试，需使用仓库副本。

入口文件类型¶

package.json 的 main 字段必须指向普通 .js 文件（src/tavily-web.js），不能指向 .ts 文件。这是因为 ESM 在 node_modules 中不支持 stripping types，直接加载 .ts 会导致静默失败（loader 无法初始化）。

Curl 调用陷阱¶

Tavily API 的报错体（如 432 错误）是合法的 JSON，但 curl 遇到 HTTP 错误时退出码仍为 0。如果代码仅解析 JSON 而不检查 HTTP 状态码，会将 API 错误误判为“搜索结果为空”。本插件在 web_fetch 中强制要求检查状态码。

短结尾¶

该插件为 DSH 提供了稳定的多 Key Tavily 检索和网页抓取能力，适合需要高可用性联网功能的场景。更多源码、测试用例及目录信息，可参考其 GitHub 仓库。