前言¶

在 DeepSeek Harness（DSH）裏，模型通過官方 web 能力縫（ctx.web）調用 web_search 工具做聯網檢索。默認 bundled 的 DeepSeek 檢索提供方，一次搜索往往要消耗一整輪模型調用，延遲和成本都偏高。若你已有 Brave Search API 訂閱，或希望「一次搜索 = 一次 HTTP GET、不佔用模型輪次」，可以把檢索後端換成社區插件 huohua-dev/dsh-web-search-brave。下面介紹它的定位、安裝方式與配置要點。

這是什麼¶

dsh-web-search-brave（npm 包名 @huohua-dev/dsh-web-search-brave，當前版本 0.1.0）由 huohua-dev 維護，分類爲 聯網工具。它掛載在 DSH 官方 web 能力縫上，調用 Brave 官方端點 https://api.search.brave.com/res/v1/web/search，將響應中的 web.results[] 映射爲縫約定的 WebSearchResult；對上層模型而言，工具名仍是穩定的 web_search，只是底層提供方變爲 Brave。

與 README 中的表述一致：One search is one HTTP request — no model turn，相對 bundled DeepSeek 提供方更輕、更快。

• 目錄頁：https://www.skillhub.cn/plugins/huohua-dev/dsh-web-search-brave
• 源碼與文檔：https://github.com/huohua-dev/dsh-web-search-brave
• 許可證：MIT

環境與依賴¶

安裝前請確認：

1. dsh 版本 0.1.1-rc.2 或更高；
2. Node.js >= 20.3.0；
3. 有效的 Brave Search API 訂閱 Token（可在 api-dashboard.search.brave.com 申請，資料說明存在免費檔）。

核心功能¶

以下能力均來自項目 README，僅作歸納說明。

純檢索、無模型輪次¶

每次 web_search 對應一次 HTTP GET，不向模型再開一輪對話來完成檢索。

安全與請求約束¶

• 訂閱 Token 僅通過請求頭 X-Subscription-Token 發往 Brave，不出現在 URL 中，也不寫入日誌；
• baseURL 默認鎖定官方端點；若改用自定義地址，須顯式設置 allowCustomBaseURL: true 且使用 https，避免配置被注入後把密鑰導向其它主機；
• 每次請求有硬超時 searchTimeoutMs（默認 30 秒），並尊重調用方的 abort signal。

結果與參數¶

• 調用方的 maxResults 在請求層生效，count 不超過配置值與 API 上限（20）；
• URL 去重；page_age 僅在能解析爲日期時映射爲 publishedAt。

代理與熱更新¶

• 可選 proxy，默認讀取啓動環境中的 HTTPS_PROXY / HTTP_PROXY；在 api.search.brave.com 遭遇 DNS 污染等場景，可在代理側解析主機名。實現上通過懶加載 undici（optional dependency），未配置代理則不加載該依賴。
• 已掛載後，配置段在搜索之間會重新讀取，改 profile patch 無需重啓 DSH；enabled: false 可暫停提供方而不卸載插件。

一鍵切換提供方¶

隨包提供的 cordis.patch.yml 會掛載插件，並把 web.searchProvider 從 bundle 默認的 deepseek-official 切到 brave。

安裝與啓用¶

從 GitHub 安裝（命令來自 README 原文）：

dsh plugin --profile web add github:huohua-dev/dsh-web-search-brave

安裝完成後，bundle 的 patch 會自動掛載插件並選擇 searchProvider: brave。若要改回官方 DeepSeek 提供方，可移除該插件，或在 profile 的 patch（$DSH_HOME/profiles/<profile>/cordis.patch.yml）中覆蓋：

- id: web
  config:
    searchProvider: deepseek-official

注意： README 寫明，新安裝的插件需要重啓 dsh 纔會生效；運行中的 host 不會熱掛載新插件。對已掛載插件的配置修改則支持熱重載。

驗證是否掛載成功：

dsh --profile web --dump-config   # 應能看到 web-search-brave 條目

API Key 配置¶

Token 在每次搜索時按「先命中者優先」解析：

1. DSH 憑據服務（推薦）：在 $DSH_HOME/.credentials.yaml 中追加 BRAVE_API_KEY: <your-token>；
2. 環境變量：啓動 dsh 前 export BRAVE_API_KEY=<your-token>（可通過配置項 apiKeyEnv 改名）；
3. 插件配置中的字面量 apiKey（secret 角色，settings describe 輸出中會脫敏）。

缺少密鑰時，搜索失敗並報 WEB_PROVIDER_CREDENTIAL_MISSING，錯誤信息會複述上述幾種方式。

典型配置¶

所有字段可選，在 profile 的 cordis.patch.yml 裏編輯 web-search-brave 條目，例如：

- id: web-search-brave
  config:
    apiKeyEnv: BRAVE_API_KEY
    count: 10
    country: cn
    searchLang: zh-hans

常用字段（默認值與說明以 README 表格爲準）：

典型用法¶

1. 按上文完成安裝、配置 BRAVE_API_KEY 並重啓 dsh（若爲新裝插件）。
2. 執行 dsh --profile web --dump-config 確認 web-search-brave 已掛載且 searchProvider 爲 brave。
3. 在對話中讓模型使用 web_search 工具；對模型側接口與 bundled 提供方一致，無需改 prompt 裏的工具名。

開發側自測（維護者文檔）：

npm install
npm test    # vitest，README 稱 43 個用例

包內爲手寫 ESM 源碼，無額外 build 步驟。

適用場景與注意¶

適合誰

• 已在用或計劃用 Brave Search API，希望 DSH 聯網檢索不佔用模型輪次；
• 需要按 country / searchLang 等參數做區域化檢索；
• 網絡環境需經 HTTP 代理 訪問 api.search.brave.com 的用戶。

使用前請知悉

• DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
• 插件在 當前 dsh 進程權限 下運行，出站目標僅爲 Brave API（或你顯式允許的 https 鏡像）。安裝前建議閱讀源碼與 MIT 許可證；README 說明無遙測、無 install hooks、隨包 patch 中無 !!js 表達式。
• 項目 README 致謝了官方 DeepSeek 檢索插件及社區同類實現；結構與錯誤語義對齊 @deepseek-ai/dsh-web-search-deepseek。

結尾¶

huohua-dev/dsh-web-search-brave 把 DSH 的 web_search 接到 Brave Search API：一次搜索一次 HTTP，Token 與端點策略偏保守，並支持代理與配置熱更新。若你的 profile 已是 web，按 README 安裝命令添加插件、配置 BRAVE_API_KEY 並重啓即可切換提供方。

• 目錄：https://www.skillhub.cn/plugins/huohua-dev/dsh-web-search-brave
• GitHub：https://github.com/huohua-dev/dsh-web-search-brave