前言¶

下面介绍的是 dsh-balanced-search。它解决的是 DSH 里联网搜索容易依赖单一搜索 API 的问题：某个服务不可用、返回失败或 key 配置不同时，调用链会受影响。这个插件把 Keenable、Exa、Tavily 三个搜索 API 放进同一套工具里，按 round-robin 轮流调用；某个服务失败时自动切换下一个，并统一返回标题、链接和内容摘要。它同时提供 dsh 原生插件和通用 MCP 服务器两种形态。

这是什么¶

dsh-balanced-search 由 tianmingwan 维护，采用 MIT 许可。它包含两种使用方式：

• dsh 原生插件：直接注册 balanced_search 和 balanced_fetch 两个 dsh 工具，无需 Python。
• 通用 MCP 服务器：通过 server.py 以 stdio 方式暴露 search 和 fetch，可供任意 MCP 客户端使用。

核心功能¶

这个插件主要做两类事：搜索和抓取。

• 搜索网页，返回标题、链接和内容摘要。
• 抓取指定 URL 的网页正文，返回 clean markdown。
• 对 Keenable、Exa、Tavily 三个搜索服务轮流调用，单个服务失败时自动切换下一个。
• 通过环境变量配置 API key；未配置 key 的服务不会启用。
• dsh 原生插件无需安装 Python 依赖；Python MCP 服务器需要按 requirements.txt 安装依赖。

安装为 dsh 插件¶

先确认本机已经安装 DeepSeek Harness（dsh），并且 Node.js 版本不低于 20。

dsh plugin --profile web add github:tianmingwan/dsh-balanced-search

安装后，至少配置一个搜索服务的 API key：

KEENABLE_API_KEY=...
EXA_API_KEY=...
TAVILY_API_KEY=...

dsh 原生插件直接读取进程环境变量。经过上面的步骤并重启 dsh --profile web 后，会话中会出现两个工具：

• balanced_search
• balanced_fetch

作为通用 MCP 服务器使用¶

如果不想走 dsh 插件，也可以用 Python MCP 服务器。先安装依赖：

python -m venv .venv
# Linux / macOS
.venv/bin/python -m pip install -r requirements.txt
# Windows
.venv\Scripts\python.exe -m pip install -r requirements.txt

然后以 stdio 模式运行：

# 直接使用当前 Python
python server.py
# 或使用虚拟环境中的 Python
.venv/bin/python server.py
.venv\Scripts\python.exe server.py

MCP 客户端接入示例如下。这里的 command 指向 Python，args 指向 server.py，并通过 env 注入三个 API key 环境变量：

{
  "mcpServers": {
    "balanced-search": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "KEENABLE_API_KEY": "...",
        "EXA_API_KEY": "...",
        "TAVILY_API_KEY": "..."
      }
    }
  }
}

Python MCP 服务器除了读取客户端注入的环境变量，还会自动读取同目录下的 .env 文件。

典型用法¶

dsh 原生工具和 MCP 工具的参数基本一致：

• balanced_search / search：参数为 query、max_results、time_range。
• balanced_fetch / fetch：参数为 url、max_chars、live。

参数说明如下：

• query（必填）：搜索关键词或自然语言问题。
• max_results：1–20，默认 8。
• time_range：可取 day、week、month、year。其中 Tavily 原生支持，Exa 映射为 startPublishedDate，Keenable 映射为 published_after。
• max_chars：抓取内容最大字符数，默认 30000，上限 50000。
• live：是否实时从源站抓取，绕过索引/缓存，默认 false。

搜索返回的 JSON 形如：

{
  "provider": "keenable|exa|tavily",
  "count": 1,
  "results": [
    {"title": "...", "url": "...", "content": "...", "published_at": "...", "score": 0.5}
  ]
}

抓取返回的 JSON 形如：

{
  "provider": "keenable|exa|tavily",
  "result": {"url": "...", "title": "...", "content": "..."}
}

适用场景与注意¶

这个插件适合把网页搜索和 URL 抓取接入 DSH，或者把同一套 search/fetch 能力暴露给 MCP 客户端的使用者。至少配置一个搜索服务的 API key；如果三个服务都配置了 key，插件会按 round-robin 轮流调用，并在某个服务失败时切换下一个。

需要注意的是，dsh 插件会以当前 dsh 进程权限运行。安装前建议先检查源码、依赖和 MIT 许可是否符合你的使用环境。若要新增搜索服务，可以在 providers.py 中添加 SearchProvider 子类并注册，也可以在 index.js 中添加 Provider 类。当前的 failover 策略是 round-robin + failover，文档说明它可以改为 weighted 或 health-aware。

结尾¶

总的来说，dsh-balanced-search 的价值在于把三个搜索服务放在一个均衡层里，同时保留 dsh 原生工具和通用 MCP 两种接入方式。仓库地址是：

• GitHub：https://github.com/tianmingwan/dsh-balanced-search