自托管搜索抓取 cyijun/dsh-surfing-plugin

dsh-surfing-plugin

dsh-surfing-plugin 为 DeepSeek Harness 加上自托管网页访问能力：web_search 走 SearXNG，web_fetch 走 Crawl4AI。它把服务商注册到 DSH 的 ctx.web 服务上，所以原生工具名、参数、渲染、超时、取消、结果数量限制都保持不变。

架构

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]

随附的 cordis.patch.yml 会挂载这个插件，选中 surfing-searxng 和 surfing-crawl4ai，并加一个只做抓取的原生工具消费者。这个独立消费者在两种 DSH 组装方式下都能用：无头模式保留宿主级的 web_search，Web UI 则保留每个 Agent Preset 挂载的 web_search。内置的 DeepSeek 搜索服务商可以继续挂着，但不会被选中。

环境要求

- 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

Current Crawl4AI releases enable Bearer authentication by default.
export CRAWL4AI_API_TOKEN=replace-with-your-token

把本地检出安装到 web 配置档：

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: 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.apiKey | 无 | 可选的明文密钥 |
| searxng.apiKeyEnv | SEARXNG_API_KEY | 存放可选密钥的环境变量 |
| searxng.authHeader | Authorization | 认证头 |
| searxng.authScheme | Bearer | 认证前缀；留空则直接发送密钥 |
| searxng.language | 服务端默认值 | SearXNG 的 language 参数 |
| searxng.categories | 服务端默认值 | 逗号分隔的 categories 参数 |
| searxng.safeSearch | 服务端默认值 | 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 | 返回 DSH 之前的内容上限 |

明文 apiKey 优先于 apiKeyEnv 指定的环境变量。没有可用密钥时不发送认证请求头。

服务商行为

SearXNG 服务商发送表单编码的 POST /search 请求，并带上 format=json。它保留绝对的 HTTP(S) 结果 URL，按 URL 去重，把 title、content 和 publishedDate 映射为 DSH 来源，并把非空的 SearXNG answers 作为结果内容暴露出来。

Crawl4AI 服务商向 POST /crawl 发送最小请求体 { "urls": [url] }；模型输入无法提供浏览器或爬虫配置。只接受 HTTP(S) 目标。目标返回非 2xx 状态码时，DSH 抓取结果仍算成功，而 Crawl4AI API 失败会变成结构化的 WebError 值。

fit 和 citations 模式在首选字段为空时回退到原始 markdown。只有在不存在 markdown 表示时才返回 HTML。

安全

- 优先使用 apiKeyEnv；绝不提交凭据。
- 非回环服务使用 HTTPS。
- Crawl4AI 负责浏览器隔离、目标网络访问和 SSRF 策略。对外暴露之前，先限制它的网络和认证。
- 拒绝后端重定向，避免凭据被转发到其他端点。

GitHub 安装

Git 安装通过 prepare 从源码构建。固定一个提交：

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

pnpm 10 及更新版本要求对 Git 依赖批准构建脚本。如果首次安装被拦截，把它确切的包键复制到配置档的 pnpm-workspace.yaml，然后重试：

allowBuilds:
dsh-surfing-plugin: true

npm 包和 pnpm pack 生成的 tarball 已经包含 lib/，不需要这项批准。

开发与发布

corepack pnpm install
corepack pnpm run check
corepack pnpm pack

CI 在 main 和 pull request 上运行。匹配 v* 的标签会触发 npm Trusted Publishing 工作流。首次发布之前，把这个仓库和 publish.yml 配置为 npm Trusted Publisher，并确认 dsh-surfing-plugin 包名仍然可用。

许可证

MIT