前言¶
DeepSeek Harness（DSH）把聯網能力拆成 web_search 與 web_fetch 兩類原生工具，由 ctx.web 服務掛載具體 provider。默認裝配裏往往依賴雲端搜索後端；若你希望搜索與抓取都跑在自己可控的基礎設施上，需要單獨接 provider，並處理 Cordis 裝配、鑑權與超時等行爲與原生工具對齊的問題。
dsh-surfing-plugin 走另一條路：向 DSH 註冊兩個自託管 provider——搜索走 SearXNG，抓取走 Crawl4AI。原生工具名、參數、渲染、超時、取消與結果上限均保持不變，換的是後端實現。
這是什麼¶
dsh-surfing-plugin 由維護者 cyijun 發佈，歸類爲聯網工具。它在 DSH 的 ctx.web 層註冊 surfing-searxng（對應 web_search）與 surfing-crawl4ai（對應 web_fetch），分別對接 SearXNG 的 /search 與 Crawl4AI 的 /crawl。插件隨附的 cordis.patch.yml 會掛載插件、選中上述兩個 provider，並增加一個僅 fetch 的原生工具 consumer，以便在 headless 與 Web UI 兩種 DSH 裝配下都能正確分工：web_search 由裝配或 Agent Preset 決定掛載方，而 fetch 側由該 consumer 統一消費。
架構與數據流¶
flowchart LR
A[Native DSH web_search] --> B[surfing-searxng provider]
B --> C[SearXNG /search]
D[Native DSH web_fetch] --> E[surfing-crawl4ai provider]
E --> F[Crawl4AI /crawl]
SearXNG provider 以 format=json 向 POST /search 發送表單請求，保留絕對 HTTP(S) 結果 URL、按 URL 去重，並把 title、content、publishedDate 映射爲 DSH sources；非空的 SearXNG answers 會作爲結果內容返回。
Crawl4AI provider 向 POST /crawl 發送最小體 { "urls": [url] }；模型輸入不能附帶瀏覽器或爬蟲配置。僅接受 HTTP(S) 目標；目標頁非 2xx 狀態碼仍可作爲成功的 DSH fetch 結果返回，而 Crawl4AI API 層面的失敗會轉成結構化的 WebError。
環境與依賴¶
運行前需滿足：
- Node.js
^22.19.0或>=24.0.0 - DeepSeek Harness
>=0.1.0-rc.6 <0.2.0 - 可訪問的 SearXNG 與 Crawl4AI 服務
- SearXNG 配置中
search.formats已啓用 JSON
安裝與啓用¶
端點可填服務根地址，也可填完整的 /search 與 /crawl URL。先導出環境變量：
export SEARXNG_URL=http://127.0.0.1:8080
export CRAWL4AI_URL=http://127.0.0.1:11235
# 當前 Crawl4AI 發行版默認啓用 Bearer 鑑權
export CRAWL4AI_API_TOKEN=replace-with-your-token
本地 checkout 安裝到 web profile：
dsh plugin --profile web add .
dsh --profile web --dump-config
dsh --profile web
npm 發佈後可用包名安裝：
dsh plugin --profile web add dsh-surfing-plugin
移除：
dsh plugin --profile web remove dsh-surfing-plugin
從 GitHub 按提交固定版本時，README 給出的命令爲：
dsh plugin --profile web add github:cyijun/surfing-plugin#COMMIT_SHA
若使用 pnpm 10 及以上，Git 依賴首次安裝可能因 build-script 審批被攔截；將提示中的包名寫入 profile 的 pnpm-workspace.yaml 後重試：
allowBuilds:
dsh-surfing-plugin: true
npm 包與 pnpm pack 產物已包含 lib/，通常不需要上述審批。
配置¶
顯式配置優先於環境變量。可在 $DSH_HOME/profiles/web/cordis.patch.yml 中覆蓋本插件對應行：
- id: surfing-plugin
config:
searxng:
url: https://search.example.com
apiKeyEnv: MY_SEARXNG_KEY
authHeader: X-API-Key
authScheme: ''
language: en
categories: general,news
safeSearch: 1
timeRange: month
crawl4ai:
url: https://crawl.example.com
apiKeyEnv: CRAWL4AI_API_TOKEN
authHeader: Authorization
authScheme: Bearer
markdownMode: raw
maxContentChars: 100000
常用字段與環境變量對應關係如下（節選）：
| 字段 | 環境變量或默認 | 含義 |
|---|---|---|
searxng.url |
SEARXNG_URL |
服務根或 /search 端點 |
searxng.apiKeyEnv |
SEARXNG_API_KEY |
可選密鑰所在環境變量 |
searxng.language |
服務端默認 | SearXNG language 參數 |
searxng.categories |
服務端默認 | 逗號分隔的 categories |
searxng.safeSearch |
服務端默認 | 0、1 或 2 |
searxng.timeRange |
無 | day、month 或 year |
crawl4ai.url |
CRAWL4AI_URL |
服務根或 /crawl 端點 |
crawl4ai.apiKeyEnv |
CRAWL4AI_API_TOKEN |
可選密鑰所在環境變量 |
crawl4ai.markdownMode |
raw |
優先 raw、fit 或 citations markdown |
crawl4ai.maxContentChars |
100000 |
返回給 DSH 前的內容上限 |
字面量 apiKey 優先於 apiKeyEnv 指向的環境變量；無可用密鑰時不發送鑑權頭。fit 與 citations 模式在首選字段爲空時會回退到 raw markdown；僅當不存在 markdown 表示時才返回 HTML。
典型用法¶
完成安裝並啓動 dsh --profile web 後，Agent 側仍調用原生 web_search 與 web_fetch；無需改工具名或參數。搜索請求經 surfing-searxng 落到自託管 SearXNG；抓取請求經 surfing-crawl4ai 落到 Crawl4AI。你在對話裏提出的查詢與自然語言 URL 意圖，會按 DSH 原有語義流轉，只是後端不再依賴默認雲端搜索 provider。
開發或自檢插件本身時，倉庫內約定：
corepack pnpm install
corepack pnpm run check
corepack pnpm pack
適用場景與注意¶
適合需要在 DSH 中統一使用自託管搜索與抓取、且已部署或可部署 SearXNG 與 Crawl4AI 的開發者。插件以當前 dsh 進程權限運行；安裝前應閱讀源碼與 MIT 許可證，並自行評估後端服務的網絡暴露面。
安全方面，README 建議：優先用 apiKeyEnv，勿將憑據提交到版本庫；非迴環地址使用 HTTPS；Crawl4AI 負責瀏覽器隔離、目標網絡訪問與 SSRF 策略，對外暴露前應限制其網絡與鑑權；後端重定向會被拒絕，避免憑據被轉發到其他端點。
DSH 生態奉行「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。本插件在 GitHub 上約 13 stars，屬社區聯網工具類條目。
鏈接¶
- SkillHub 目錄頁：https://www.skillhub.cn/plugins/cyijun/dsh-surfing-plugin
- GitHub 倉庫：https://github.com/cyijun/dsh-surfing-plugin
