前言¶
DeepSeek Harness（DSH）的理念是「一切皆插件」：模型側的 web_search 工具、結果上限、引用展示由它自己的 web capability 負責，但具體去哪家搜索服務拿結果，取決於掛載的 searchProvider。如果你選定的搜索服務是博查（Bocha），按慣例就得自己實現一個 WebSearchProvider、註冊進 Profile，再處理憑據解析和錯誤映射。
@bocha-ai/dsh-web-search-bocha 把這件事做成了可安裝的 bundle：一條命令裝進 Profile，ctx.web 的搜索就路由到博查的 Web Search API。下面介紹它的定位、安裝步驟和配置方式。
這是什麼¶
一句話定位：爲 DeepSeek Harness 提供博查（Bocha）Web Search 驅動的 WebSearchProvider，附帶一個可安裝的 Profile bundle。
- 維護方：bocha-ai
- 包名：
@bocha-ai/dsh-web-search-bocha，當前版本 0.1.0 - 許可證：MIT
- 倉庫：https://github.com/bocha-ai/dsh-web-search-bocha
它只負責搜索這一段。模型側的 web_search 工具契約、結果邊界、引用與錯誤展示仍由 Harness 掌握，插件不接管這些。
核心功能¶
1、註冊 provider id 爲 bocha 的 WebSearchProvider，調用博查的 POST /v1/web-search 接口。
2、攜帶 dsh.bundle 補丁（cordis.patch.yml），安裝後將 web 行的 searchProvider 設爲 bocha，並插入 web-search-bocha 行來加載本包。
3、每次搜索時通過 Harness credentials 服務解析 BOCHA_API_KEY，密鑰輪換無需重啓，即對下一次請求生效。
4、結果映射：將博查返回的 url/name/summary/datePublished 映射爲 Harness 的 url/title/snippet/publishedAt；沒有有效 URL 的條目被丟棄。
5、請求的 maxResults 覆蓋默認 count，並在發送前截斷至博查上限 50。
6、錯誤處理有明確映射：
- HTTP 錯誤、網絡失敗、非 200 響應、響應體不可解析 →
WEB_PROVIDER_ERROR（存在log_id時保留） - 中止 →
WEB_ABORTED - 憑據缺失 →
WEB_PROVIDER_CREDENTIAL_MISSING - 重定向在訪問目標前被拒絕
安裝與啓用¶
先把 bundle 裝進 web Profile：
dsh plugin --profile web add @bocha-ai/dsh-web-search-bocha
裝完可以打印合成後的配置，確認補丁已生效（打印後退出，不啓動服務）：
dsh --profile web --dump-config
然後啓動 Web 應用：
dsh --profile web
插件需要博查（open.bocha.cn）的 API key 才能實際搜索，憑據配置兩種方式二選一。
方式一：寫入 DSH 憑據文檔 $DSH_HOME/.credentials.yaml（通常是 ~/.dsh/.credentials.yaml）：
BOCHA_API_KEY: your-api-key
POSIX 下把文件權限收緊爲僅屬主可讀寫：
chmod 600 ~/.dsh/.credentials.yaml
方式二：啓動前導出環境變量：
export BOCHA_API_KEY='your-api-key'
兩者同時配置時，環境變量優先。卸載也是一條命令，會移除對應的 provider 行和 bundle 層：
dsh plugin --profile web remove @bocha-ai/dsh-web-search-bocha
配置項¶
插入的 web-search-bocha 行支持以下配置：
| 配置項 | 默認值 | 說明 |
|---|---|---|
apiKey |
— | 可選的明文 API key，更推薦走憑據方式，避免明文 key 進入 Profile 補丁 |
apiKeyEnv |
BOCHA_API_KEY |
經 Harness credentials 服務解析的憑據引用，每次搜索時解析 |
baseURL |
https://api.bocha.cn |
API 基地址 |
freshness |
noLimit |
搜索附帶的時間過濾條件 |
summary |
true |
是否請求博查的每頁摘要 |
count |
10 |
請求未帶 maxResults 時的默認條數，取值 1–50 |
這些配置不需要改動包本身，通過後續 Profile patch 直接配置該行即可：
- id: web-search-bocha
config:
freshness: 2025-01-01..2025-04-06
summary: true
count: 10
經過上面的步驟，重新啓動後 ctx.web 的搜索請求就會帶着這些參數走博查。
適用場景與注意¶
適合的讀者：已經在跑 DSH Web 應用、想讓 web_search 走博查的部署者；需要按部署固定時間過濾（freshness）的團隊；不想在主工程裏手寫 WebSearchProvider 的開發者。
使用前注意以下幾點：
- 需要先在博查（open.bocha.cn）申請 API key，否則插件裝上也搜不了。
- Node 引擎要求
^22.19.0 || >=24.0.0。 - 當前上游 DSH 內置 Plugins UI 不暴露第三方搜索設置，需通過 Profile 行配置，並把
BOCHA_API_KEY存於憑據文件或啓動環境。 freshness是部署級配置，不是模型可傳參數：Harness 的中立請求只攜帶query和maxResults，同一 provider 掛載下的每次請求使用同一個freshness值。- 單次 API 調用最多返回 50 條來源；該端點不返回生成式答案，所以
WebSearchResult.content省略；博查特有的siteName及圖片、視頻等媒體字段也被省略。 - 安全提示：插件以當前 dsh 進程的權限運行，安裝前建議閱讀源碼並確認許可證（本項目爲 MIT）符合你的部署要求。
想參與開發的話，倉庫內可運行無 key 的測試與構建：
npm install
npm test
npm run build
npm pack --dry-run
有博查 key 時，可運行端到端冒煙測試：
BOCHA_API_KEY='your-api-key' npm run test:e2e
小結¶
這個插件解決的是一個很具體的問題：讓 DSH 的 ctx.web 用上博查搜索，而且安裝、配置、卸載都收斂在 Profile 和 bundle 機制裏，憑據輪換不用重啓。如果你的搜索服務選型恰好是博查，它是最直接的接法。
- 社區目錄頁：https://www.skillhub.cn/plugins/bocha-ai/dsh-web-search-bocha （目錄爲社區獨立維護，與 DeepSeek / 幻方無官方從屬關係）
- GitHub 倉庫：https://github.com/bocha-ai/dsh-web-search-bocha
