前言¶
DeepSeek Harness（dsh）把聯網搜索做成可替換的能力，而不是寫死在智能體循環裏。模型側始終調用同一套 web_search / web_fetch，真正去網上查資料的是 ctx.web 上註冊的搜索提供方。官方倉庫裏已經有 @deepseek-ai/dsh-web-search-exa：它走 Exa 的 POST /search REST 接口，但沒有 API 密鑰時提供方直接不可用。
很多本地試用、臨時排查、不想先去申請密鑰的場景，會卡在這一步。社區維護者 TonyDua 做了 @tonydua/dsh-web-search-exa（倉庫名 dsh-web-search-exa）：無密鑰時走 Exa 託管的匿名 MCP，配了 EXA_API_KEY 再自動切回 REST。本文按插件目錄頁、GitHub README / package.json、DeepSeek Harness 官方文檔和 Exa MCP 說明交叉覈對後整理。
DeepSeek Harness 的核心理念是「一切皆插件」。文中用到的 DSH 插件庫 是獨立社區站點，與 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。
這是什麼¶
dsh-web-search-exa 是一款 DeepSeek Harness 工具與能力插件，由 TonyDua 維護，許可證 MIT，主要語言 JavaScript，要求 Node.js 18 及以上。GitHub 倉庫爲 TonyDua/dsh-web-search-exa，npm 包名 @tonydua/dsh-web-search-exa。目錄頁與 GitHub 在本文覈對時均顯示 6 顆星；倉庫創建於 2026-08-14，目錄收錄日期同日。
它解決的問題很具體：給 ctx.web 註冊一個 Exa 搜索提供方，讓已有的模型工具、提示詞區和結果卡片不用改，就能用上網頁搜索。它不是官方包的替代品，而是官方包的零配置變體——官方實現只走帶密鑰的 REST；本包補上匿名 MCP 兜底，帶密鑰時的 REST 行爲與官方路徑一致。
倉庫 package.json 當前版本爲 0.1.3。npm 頁面在本文檢索時列出的最新發布仍是 0.1.2。0.1.3 的變更是：bundle 補丁不再重複定義官方已經佔用的 web 行，避免 dsh plugin add 後出現 duplicate loader entry id: web 啓動失敗。從 GitHub 安裝會拿到含該修復的源碼。
核心功能¶
默認免密鑰，走匿名 MCP¶
未配置 apiKey 或環境變量 EXA_API_KEY 時，搜索走 Exa 託管 MCP：https://mcp.exa.ai/mcp，JSON-RPC 2.0 調用 web_search_exa，請求裏不帶憑據。來源標識放在 x-exa-source: dsh-anything 頭裏。
Exa 自己的 MCP 頁面寫明：連接 https://mcp.exa.ai/mcp 不需要 API 密鑰。匿名調用有限流；HTTP 429 會以 WEB_PROVIDER_ERROR 返回，並提示去配置密鑰。
配了密鑰自動切 REST¶
設置了 EXA_API_KEY（或配置裏的字面量 apiKey）之後，提供方改走 https://api.exa.ai/search（POST /search，Authorization: Bearer）。倉庫說明這條路徑額度更高，對模型側的工具行爲沒有額外改動。REST 檢索模式 searchType 默認爲 auto，也可設爲 keyword 或 neural。
即插即用，不改模型工具¶
它只向 ctx.web 註冊 WebSearchProvider，不擁有 ctx.web 這個鍵，也不自己註冊面向模型的工具。工具名、參數、提示詞和結果卡片仍由 @deepseek-ai/dsh-tool-web 負責。返回結果會規範成 seam 的 WebSearchSource：url、title、snippet、publishedAt；maxResults 由 seam 在返回路徑上截斷。
DeepSeek Harness 文檔對選擇規則寫得很清楚：沒有配置提供方 id、且當時只有一個可用搜索提供方時，seam 會自動選中它。無密鑰時官方 DeepSeek 搜索提供方不可用，因此本插件可以在零配置下被自動選中。
可與官方 Exa 包共存¶
默認 provider id 是 exa，Cordis 插件名是 web-search-exa，和官方 @deepseek-ai/dsh-web-search-exa 相同。seam 遇到重複 id 會拋 WEB_DUPLICATE_PROVIDER，兩個包直接裝進同一個 profile 會在啓動時報錯，沒有靜默覆蓋。本包可用 providerId 改成例如 exa-anon，再在 web 配置裏顯式選擇。
主要配置項¶
| 配置鍵 | 默認值 | 含義 |
|---|---|---|
providerId |
exa |
註冊到 ctx.web 的提供方 id；與官方包共存時才需要改 |
apiKey |
未設置 | Exa 密鑰字面值；爲空則走匿名 MCP |
apiKeyEnv |
EXA_API_KEY |
未寫字面 apiKey 時讀取的環境變量名 |
apiURL |
https://api.exa.ai/search |
帶密鑰時的 REST 端點 |
mcpURL |
https://mcp.exa.ai/mcp |
匿名 MCP 端點 |
searchType |
auto |
REST 檢索模式：auto / keyword / neural |
numResults |
未設置 | 請求未帶 maxResults 時的默認條數 |
highlightsPerResult |
1 |
REST 路徑每個結果請求的高亮句子數 |
apiKey 標記了 role('secret')，不會出現在 describe() 響應裏。
安裝與啓用¶
插件目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端中運行：
dsh plugin add github:TonyDua/dsh-web-search-exa
如需可復現安裝，按目錄頁說明固定 commit 哈希：
dsh plugin add github:TonyDua/dsh-web-search-exa#commit
把 #commit 換成實際提交哈希。倉庫 README 還提供了按 web profile、從 npm 安裝的寫法（v0.1.3 起帶 dsh.bundle manifest，bundle 補丁會插入提供方行）：
dsh plugin --profile web add @tonydua/dsh-web-search-exa
裝完後重啓 dsh web。目錄頁寫明：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；安裝前應檢查源代碼倉庫和許可證。
典型用法¶
無密鑰、只裝這一個搜索提供方時，重啓後一般不用再改配置：官方 DeepSeek 搜索不可用，seam 會自動選中本插件。模型繼續用原來的 web_search 即可。搜索結果仍由 dsh-tool-web 渲染成來源、摘要、日期卡片，和 DeepSeek 搜索的展示方式相同。
已經配置了密鑰、希望明確走 Exa 時，在 $DSH_HOME/profiles/web/cordis.patch.yml 裏選中提供方（該文件在 bundle 補丁之後應用）：
- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: exa
也可以不改文件，用環境變量在運行時指定：
export DSH_WEB_SEARCH_PROVIDER=exa
本地開發目錄可以按 README 直接指向檢出路徑：
dsh plugin --profile web add ../plugins/dsh-web-search-exa
若要和官方 @deepseek-ai/dsh-web-search-exa 裝在同一個 profile，必須改 id。官方包的 id 固定爲 exa，給本包一個不同值，例如 exa-anon：
- insert:
- id: web-search-exa
name: '@tonydua/dsh-web-search-exa'
config:
providerId: exa-anon
- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: exa-anon
對應的環境變量是 $DSH_WEB_SEARCH_PROVIDER=exa-anon。更省事的做法是：每個 profile 只裝其中一個包，沿用默認 id。
當前版本沒有 Web 設置頁裏的可編輯卡片。Settings → Plugins 清單裏會出現 web-search-exa（@tonydua/dsh-web-search-exa），服務端也註冊了 web-search-exa 配置段，但沒有客戶端卡片綁定它。內置的 “Web search” 卡片改的是官方 web-search-deepseek 命名空間，和本插件無關。改配置請編輯 cordis.patch.yml 或環境變量，然後重啓 dsh web。README 寫明下一版本計劃補 UI 卡片，本文不把它當作已經交付的功能。
適用場景與注意事項¶
適合這些情況：
- 本地試用 DeepSeek Harness 的網頁搜索，暫時不想申請 Exa 密鑰
- 已經在用
web_search，只想換搜索後端，不想動工具和提示詞 - 需要和官方 Exa 包對比，或在同一套 profile 裏用
providerId顯式切換
使用前注意：
- 匿名 MCP 有限流。 頻繁搜索遇到 429 時，按倉庫說明配置
EXA_API_KEY或apiKey，提供方會切到 REST。Exa 託管 MCP 是 Exa 的官方產品，免費匿名可用，但額度由對方控制。 - 本插件只提供搜索，不提供抓取。
web_fetch仍走獨立的 fetch 提供方（官方文檔裏是dsh-web-fetch-http這一路），不要指望它順帶讀完整網頁。 - 不要無改動地雙裝官方包和本包。 默認 id 衝突會直接導致啓動失敗。
- 當前沒有設置 UI。 改
searchType、mcpURL、providerId等只能走補丁文件或環境變量。 - 運行時單例。 README 說明
@deepseek-ai/dsh-tools必須在一個 profile 裏解析成同一份物理實例。本插件不依賴它；若其它第三方插件把它裝成嵌套普通依賴，agent 循環可能在搜索提供方被調用前就報Cannot read properties of undefined (reading 'prepare')。應先修那個插件的依賴聲明。 - 權限與許可證。 插件以當前 dsh 進程權限運行。安裝前閱讀倉庫源碼和 MIT 許可證。DeepSeek Harness 本身仍處於開發者預覽，官方 README 寫明會有破壞兼容性的變更。
- 選型。 已有
EXA_API_KEY、希望跟官方實現走：用@deepseek-ai/dsh-web-search-exa。要零配置試用：用本包。
匿名 MCP 的接入方式，倉庫 README 寫明參考了 can1357/oh-my-pi 以及 @oh-my-pi/exa：有密鑰走 REST、無密鑰走 mcp.exa.ai/mcp。
小結¶
dsh-web-search-exa 把 Exa 接到 DeepSeek Harness 的 ctx.web 上：沒密鑰時用官方託管的匿名 MCP，有密鑰時自動升到 REST，模型側的 web_search 不用改。它是社區維護的零配置變體，不是官方包，也不是 DeepSeek 官方商店裏的「認證插件」。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-web-search-exa/
GitHub：https://github.com/TonyDua/dsh-web-search-exa
