前言¶

DeepSeek Harness (DSH) 的插件化架构允许开发者扩展其能力。对于需要联网搜索和网页抓取的 Agent，DSH 默认的 web-search-deepseek 可能无法满足需求，或者开发者希望使用 Tavily 和 Firecrawl 等第三方服务。dsh-tavily-firecrawl 是一个插件，它将 DSH 的联网能力替换为 Tavily 搜索 与 Firecrawl 抓取 的组合，并支持多 API Key 轮询。

前置条件¶

在安装和使用此插件前，请确保环境满足以下要求：

• DSH CLI：版本需 ≥ 0.1.0-rc.5。
• Node.js：版本需 ≥ 20。
• 包管理器：需要安装 pnpm（dsh plugin 命令依赖）。
• DSH 版本：需要安装了带 web seam（ctx.web）的 DSH 版本（官方 dsh-base + dsh-web-app 组合均满足）。

安装¶

通过 CLI 直接安装官方 bundle：

dsh plugin --profile web add dsh-tavily-firecrawl

也可以通过以下方式安装：

• 锁定 GitHub Tag：

    dsh plugin --profile web add github:skillre/dsh-tavily-firecrawl#v0.2.0

• 本地 tgz 包：

    npm pack
    dsh plugin --profile web add ./dsh-tavily-firecrawl-0.2.0.tgz

• 使用脚本（无需 pnpm / dsh CLI）：

    ./install.sh

安装完成后，需要重启 dsh 进程以加载插件配置。

核心功能¶

• 替换联网能力：插件会自动禁用内置的 web-search-deepseek，注册 Tavily 作为 web_search 提供方，注册 Firecrawl 作为 web_fetch 提供方。
• 多 Key 轮询：支持配置多个 API Key，插件会自动在可用 Key 之间轮流使用。当某个 Key 出现 401（失效）、429（限流）或 402/403/432/433（额度不足）等错误时，会自动切换到下一个 Key，确保单次请求不会因单一 Key 失效而失败。
• 纯 ESM 实现：纯 JavaScript ESM 模块，无需编译，依赖通过 DSH 的 node_modules 解析，无需额外安装。

配置与使用¶

安装后，需要在环境变量或配置文件中提供 Tavily 和 Firecrawl 的凭证。

方式 A：环境变量

在 $DSH_HOME/.env 或启动目录的 .env 中添加：

TAVILY_API_KEY=tvly-xxxx
FIRECRAWL_API_KEY=fc-xxxx

方式 B：多 Key 轮询（推荐）

如果注册了多个免费版账号，可以通过环境变量或配置文件列出 Key，插件会自动轮询：

# 逗号、分号或空白分隔都支持
TAVILY_API_KEYS=tvly-aaaa,tvly-bbbb,tvly-cccc
FIRECRAWL_API_KEYS=fc-aaaa;fc-bbbb

方式 C：配置文件

在 cordis.patch.yml 中添加配置：

- insert:
    - id: web-tavily-firecrawl
      name: 'dsh-tavily-firecrawl'
      config:
        search:
          apiKeys: ['tvly-aaaa', 'tvly-bbbb']
        fetch:
          apiKeys: ['fc-aaaa', 'fc-bbbb']

注意：凭证在插件加载时读取一次。修改 Key 或配置后必须重启 dsh 进程才能生效。

多 Key 轮询与失败处理¶

插件对 Key 的状态管理分为“永久失效”和“暂时冷却”两类。

正常调用：多个并发请求会落在不同的 Key 上，轮流使用。

冷却状态：保存在内存中，重启 dsh 进程后清空。

Key 读取优先级：
1. 配置文件 apiKeys（数组）
2. 配置文件 apiKey（字符串）
3. 环境变量 *_API_KEYS
4. 环境变量 *_API_KEY

注意：所有 Key 都不可用时，会明确报出每个 Key 的状态和预计恢复时间。

工具与预设¶

本插件只负责提供 web_search 和 web_fetch 的 Provider，工具的注册由 Agent 预设的 tool-web.fetch 决定。

• DSH 版本 ≥ 0.1.5：自带预设已开启 fetch: true，安装后直接可用。
• DSH 版本 ≈ 0.1.0-rc.5：自带预设未开启 fetch。需要手动启用，或使用本插件附带的 standard-web 预设：

    cp -R node_modules/dsh-tavily-firecrawl/presets/standard-web "$DSH_HOME/.agent-presets/"

验证¶

安装完成后，可以通过以下方式验证：

1. 命令行验证：直接让 Agent 执行操作。
   • “搜一下 DeepSeek”
   • “抓取 https://example.com”
2. 本地测试（无需联网）：

    node --test "test/**/*.test.mjs"

常见问题¶

• 搜索报 HTTP 432？ 该 Tavily 账号超了套餐额度，消息里会直接带原文。建议增加 Key 轮询或升级套餐。
• 搜索报 has no usable API key？ 所有 Key 都在冷却中或已失效。消息会列出每个 Key 的状态。重启进程可清空内存冷却状态。
• 改完配置不生效？ 插件在启动时加载配置，必须重启 dsh 进程。
• web_fetch 工具不存在？ 检查 Agent 预设中是否启用了 fetch: true。

结尾¶

dsh-tavily-firecrawl 是一个轻量级的 DSH 插件，通过引入 Tavily 和 Firecrawl，解决了原生联网能力的扩展与 Key 管理问题。其多 Key 轮询机制能有效提升服务的可用性。

• GitHub 仓库：https://github.com/skillre/dsh-tavily-firecrawl
• 插件目录：https://www.skillhub.cn/plugins/skillre/dsh-tavily-firecrawl