前言¶

下面介紹的是 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