前言¶

DeepSeek Harness（dsh）裏，模型可以通過內置的 web_search 工具查網頁，而不必把「上網」塞進模型上下文裏額外燒 token。前提是 profile 裏要有一個在 ctx.web 上註冊好的 search provider。

dsh 0.2.1 前後插件接口有過變動：不少社區裏的 Brave provider 會從 @deepseek-ai/dsh-settings 等宿主包 import 運行時符號，宿主移除導出後模塊加載失敗，表現就是插件「裝了但搜索沒用」。下面介紹維護者 thomasly 的 dsh-web-search-brave：單文件、零依賴，走官方 ctx.web 接縫，provider id 爲 brave-search，複用你在憑據庫裏已有的 Brave API key。

這是什麼¶

dsh-web-search-brave（GitHub：thomasly/dsh-web-search-brave）把 Brave Search API 接進 dsh 的網頁搜索能力。它註冊在 dsh 官方 ctx.web 搜索接縫上，因此所有模型都能通過 dsh 自帶的 web_search 搜索，不綁定某一模型，也不靠模型自己「上網」。

• 直連 Brave 官方接口，不經過 LLM，不產生模型側搜索費用。
• 複用 ~/.dsh/.credentials.yaml 裏配置好的 Brave key，不在對話或日誌裏明文暴露。
• 單文件、零依賴、零 import 宿主包，降低因宿主接口變動或本地 link: 安裝路徑導致的加載失敗。
• 結果帶發佈日期（publishedAt，來自 Brave 的 page_age），對時效性查詢更有用。

適用版本：dsh 0.2.x（README 寫明在 0.2.1-rc.2 上實測通過）。運行環境：Node.js ≥ 22.19（見 package.json 的 engines）。插件版本 1.0.0，許可證 MIT。

核心功能¶

與 dsh 的銜接方式¶

插件在 ctx.web 上註冊 id 爲 brave-search 的 search provider。profile 裏把 web.searchProvider 設爲 brave-search 後，模型調用 web_search 時會走 Brave 的 Web Search 端點（默認 https://api.search.brave.com/res/v1/web/search）。

實現上不寫任何 import：只用運行時自帶的 fetch、URL，以及 ctx.web、ctx.credentials、ctx.launchEnvironment。配置與 key 在每次搜索時重新讀取，改憑據庫或環境變量後不必重啓 dsh 即可生效（bundle 仍須在安裝後重啓 web 進程纔會掛載）。

返回給模型的字段¶

web_search 需要 { url, title?, snippet?, publishedAt? }。插件從 Brave 響應映射如下（摘要）：

可選配置項¶

bundle 在 cordis.patch.yml 中插入 web-search-brave-local 行；其下 config 全部可選，常見字段包括：

freshness 是整個 provider 級設置，不是每個 query 單獨設置；dsh 的 web_search 入參只有 queries，若希望默認只看最近一週，可在 profile 裏配 freshness: pw。

API Key 解析順序¶

按順序找到即用：

1. 行配置裏的字面量 apiKey（不推薦，會進配置文件）；
2. 憑據庫 refs.<apiKeyEnv>（默認 refs.BRAVE_API_KEY）；
3. dsh 啓動環境快照中的 BRAVE_API_KEY（含 ~/.env）；
4. 當前進程環境變量 BRAVE_API_KEY。

手工寫入憑據庫示例：

refs:
  BRAVE_API_KEY: your-key-here

錯誤與限速¶

錯誤對象沿用接縫的 WebError 形狀（如 WEB_PROVIDER_CREDENTIAL_MISSING、WEB_PROVIDER_RATE_LIMITED、WEB_PROVIDER_TIMEOUT 等）。收到 429 且 Retry-After 不超過 5 秒時會自動等一次再重試；插件默認串行節流，web_search 一次最多 4 個 query 會串行發送。

安裝與啓用¶

從 GitHub 安裝（推薦）¶

dsh plugin --profile web add github:thomasly/dsh-web-search-brave

裝完後重啓一次 dsh web（bundle 類插件需要重啓纔會掛載）。也可在 Web 界面 插件 → 安裝 中填寫同一 GitHub 地址。

選中 provider¶

在 ~/.dsh/profiles/web/cordis.patch.yml 中增加或合併：

- id: web
  config:
    searchProvider: brave-search
    fetchProvider: http

fetchProvider: http 表示 web_fetch 繼續走 dsh 內置本地 HTTP 抓取，不額外爲抓取選付費 provider。

確認是否生效¶

重啓後問一句帶時效的問題（例如 README 中的 latest AI model release），觀察結果：

• 日期形如 (2026-11-01T10:55:46)（無 Z、無毫秒）通常表示 Brave 的 page_age 透傳；
• 若報 configured web provider "brave-search" is not registered，先確認已重啓，再執行：

dsh --profile web --dump-config | grep web-search-brave

應能看到 - id: web-search-brave-local。

本地目錄開發安裝時，README 說明可用 plugin_manager install_bundle 指向目錄絕對路徑，pnpm 以 link: 掛載；該目錄之後不能刪、不能移，否則搜索會失效。本文不展開 clone 流程，生產環境以 GitHub 安裝爲準。

典型用法¶

安裝並完成 searchProvider: brave-search 後，在 dsh web 對話中正常提問即可觸發 web_search；無需爲每個模型單獨配置搜索能力。

需要調參時，在 cordis.patch.yml 的 web-search-brave-local 插入塊下追加 config，例如：

- insert:
    - id: web-search-brave-local
      name: dsh-web-search-brave
      config:
        providerId: brave-search
        apiKeyEnv: BRAVE_API_KEY
        count: 10
        safesearch: moderate

保存後下一次搜索會讀取新配置（key 仍建議只放在憑據庫或環境變量）。

適用場景與注意¶

適合誰：已在 Brave Search API 有訂閱、希望在 dsh 0.2.x 裏用統一 web_search、且希望與舊版「import 宿主包」Brave 插件脫鉤的開發者。

分類：社區目錄將其歸爲聯網工具（目錄頁：skillhub.cn/plugins/thomasly/dsh-web-search-brave）。SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，安裝來源以你信任的倉庫與許可證爲準。

安全與權限：插件以當前 dsh 進程權限運行，會向 Brave 官方 API 發起 HTTPS 請求；安裝前請閱讀 倉庫源碼 與 MIT 許可證，自行評估 key 存放方式（優先憑據庫，避免字面量 apiKey 寫進 patch）。

配額：Brave 的速率與月額度由賬戶決定；插件默認保守節流，不改變 Brave 側額度。多 query 串行可能多等數秒。

故障提示：providerId 與 searchProvider 不一致、或多個 search provider 衝突時，可能出現 500 或註冊失敗；只保留一個 searchProvider 並保持 id 對齊。

結尾¶

dsh-web-search-brave 用零 import 的方式把 Brave Search 掛到官方 ctx.web 上，讓各模型共用 web_search，並複用已有 BRAVE_API_KEY 憑據。經過上面的安裝、啓用與重啓步驟，即可在 profile 裏穩定選中 brave-search。

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