dsh-surfing-plugin

English | 中文

dsh-surfing-plugin 为 DeepSeek Harness 提供自托管网页搜索与抓取：web_search 调用 SearXNG，web_fetch 调用 Crawl4AI。插件注册到 DSH 的 ctx.web Provider 接口，因此工具名称、参数、结果展示、超时与取消仍由 DSH 原生 web_search 和 web_fetch 实现。

工作方式

flowchart LR
  A[DSH 原生 web_search] --> B[surfing-searxng Provider]
  B --> C[SearXNG /search]
  D[DSH 原生 web_fetch] --> E[surfing-crawl4ai Provider]
  E --> F[Crawl4AI /crawl]

随包发布的 cordis.patch.yml 完成三件事：挂载插件、将 DSH 的搜索与抓取 Provider 分别固定为 surfing-searxng 和 surfing-crawl4ai、增加一个只注册原生 web_fetch 的 Consumer 行。这个独立 Consumer 同时适配两种 DSH 组装：headless 继续使用宿主层 web_search，Web UI 继续使用各 Agent Preset 内的 web_search。已有的 DeepSeek 搜索 Provider 可以继续挂载，但不会被选中。

要求

• 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?format=json 会被拒绝

快速开始

先配置服务地址。地址既可以是服务根地址，也可以是完整的 /search 或 /crawl 端点：

export SEARXNG_URL=http://127.0.0.1:8080
export CRAWL4AI_URL=http://127.0.0.1:11235

# Crawl4AI 当前版本默认启用 Bearer token；无认证部署可以省略。
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

配置

显式配置优先于环境变量。可在 $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: zh-CN
      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.apiKey	无	直接配置的可选密钥
searxng.apiKeyEnv	SEARXNG_API_KEY	可选密钥所在的环境变量名
searxng.authHeader	Authorization	认证请求头
searxng.authScheme	Bearer	认证前缀；空字符串表示直接发送密钥
searxng.language	SearXNG 服务默认值	language 参数
searxng.categories	SearXNG 服务默认值	逗号分隔的 categories 参数
searxng.safeSearch	SearXNG 服务默认值	0、1 或 2
searxng.timeRange	无	day、month 或 year
crawl4ai.url	CRAWL4AI_URL	服务根地址或 /crawl 端点
crawl4ai.apiKey	无	直接配置的可选密钥
crawl4ai.apiKeyEnv	CRAWL4AI_API_TOKEN	可选密钥所在的环境变量名
crawl4ai.authHeader	Authorization	认证请求头
crawl4ai.authScheme	Bearer	认证前缀；空字符串表示直接发送密钥
crawl4ai.markdownMode	raw	优先使用 raw、fit 或 citations markdown
crawl4ai.maxContentChars	100000	Provider 返回给 DSH 前的字符上限

配置了 apiKey 时，它优先于 apiKeyEnv 指向的环境变量。没有密钥时不会发送认证请求头，适合无认证的本地服务。

Provider 行为

SearXNG

插件向 /search 发送表单编码的 POST 请求，并固定请求 format=json。它只保留绝对 HTTP(S) 结果 URL，按 URL 去重，将 title、content、publishedDate 映射到 DSH source，并在 SearXNG 返回 answers 时生成搜索结果的 content。maxResults 同时在 Provider 和 DSH web service 中执行。

Crawl4AI

插件向 /crawl 发送最小请求 { "urls": [url] }，不允许模型向 Crawl4AI 注入浏览器或 crawler 配置。仅接受 HTTP(S) 目标。Crawl4AI 返回的目标 HTTP 状态会原样进入 DSH 结果；Crawl4AI API 本身的非 2xx、抓取失败或无法表示的响应会成为结构化 WebError。

raw 保留完整 markdown；fit 与 citations 在对应字段为空时回退到 raw markdown。没有 markdown 但存在 cleaned_html 或 html 时，Provider 返回 HTML body。

安全说明

• 优先使用 apiKeyEnv，不要把密钥提交到 Git。
• 对非本机服务使用 HTTPS，避免认证头以明文传输。
• Crawl4AI 负责浏览器隔离、目标网络访问与 SSRF 策略；公开部署前应按 Crawl4AI 的安全配置限制网络和认证。
• Provider 请求禁止重定向，避免认证头被转发到另一个后端地址。

从 GitHub 安装

Git 安装会从源码运行本包的 prepare 构建。建议锁定 commit：

dsh plugin --profile web add github:cyijun/surfing-plugin#COMMIT_SHA

pnpm 10 及更高版本需要先授权 Git 依赖的构建脚本。首次安装提示被阻止时，将提示中的确切包键加入该 profile 的 pnpm-workspace.yaml：

allowBuilds:
  dsh-surfing-plugin: true

然后重新执行安装。npm 包和 pnpm pack 生成的 tarball 已包含 lib/，不需要此授权。

开发与发布

corepack pnpm install
corepack pnpm run check
corepack pnpm pack

.github/workflows/ci.yml 在 main 与 pull request 上运行全部检查。.github/workflows/publish.yml 在推送 v* tag 时使用 npm Trusted Publishing 发布；首次发布前，需要在 npm 包设置中把该 GitHub 仓库和 publish.yml 配置为 Trusted Publisher，并确认 dsh-surfing-plugin 包名仍可注册。

许可证

MIT