sunx16963-design/dsh-web-search-thirdparty

dsh-web-search-thirdparty

为 DSH（DeepSeek Harness）开发的第三方网页搜索插件。它用可配置的搜索引擎替换 dsh 自带的
“仅官方 DeepSeek”搜索，为每个引擎提供独立设置，并可抓取网页全文，让模型既能搜索也能阅读。

基于 DeepSeek Harness 开发。

ci

版本与兼容

支持 DSH 最新版，并自动兼容旧版设置 API（0.1.0-rc.6 起）。

系统要求

- DSH（DeepSeek Harness）0.1.0-rc.6 或更高，且 dsh web 可正常启动。
- Node.js >= 22.19（与 DSH 自身要求一致；从源码构建时 build:client 需要 Node ^22.18 或 >=24.11）。
- 能访问至少一个已配置的搜索引擎 / API。

插件做什么

DSH 默认只挂官方 DeepSeek 搜索 provider，并且默认不挂 fetch provider、web_fetch 处于关闭状态
（官方理由：抓取目标由模型选择，SSRF 防护属于 fetch provider 的责任）。这个插件让你改用自己想要的
搜索源——自建 SearXNG、Tavily、Bing、Brave、Serper 或 Google——并自带一个带 SSRF 防护的抓取
provider，从而把 web_search 与 web_fetch 一起打开。全部在设置页里配置，不需要改代码。

上游另有官方可选 provider：@deepseek-ai/dsh-web-search-exa、@deepseek-ai/dsh-web-search-perplexity、
@deepseek-ai/dsh-web-fetch-http。如果只需要 Exa/Perplexity，可以直接用官方插件；本插件的差异点是
“多引擎（含免 key 的 SearXNG）+ 每引擎独立设置 + 可自建实例/内网代理 + 熔断与用量统计”。

主要功能

- 六个内置引擎，统一入口：SearXNG、Tavily、Serper、Brave、Bing、Google CSE。
- 浏览器设置页：选择供应商、填写 API key、按引擎配置参数（语言、地区、市场、搜索深度、安全级别）。
- 每个提供商可配置自定义 endpoint / baseURL（自建 SearXNG、内网代理）。
- 自定义请求头，以及带退避的网络重试（仅 429 / 5xx 重试，尊重 Retry-After）。
- 提供商失败时自动降级；可选多源合并并去重（带并发上限）。
- 域名去重、相关度排序、结果条数与超时控制，并如实上报 truncated。
- TTL 结果缓存（防击穿 + 有界容量 + 命中率统计），避免重复请求、节省配额。
- “测试连接”功能，反馈延迟、结果条数与首条标题。
- web_fetch 抓取 provider：HTML 清洗为 Markdown，逐跳重定向都过 SSRF 校验。
- 开放 provider 注册 API，其它插件可挂载自己的搜索源。
- 每源熔断与用量统计（设置页“用量统计”面板可查看各源请求/错误/延迟、缓存命中与熔断状态，
也有 GET /api/web-search-thirdparty/stats 接口）。

支持的引擎

| id | 服务 | 需要 key | 配置 |
| --- | --- | --- | --- |
| searxng（默认） | SearXNG（自托管 / 公共） | 否 | searxngBaseURL |
| tavily | Tavily | 是 | tavilyApiKey / TAVILY_API_KEY |
| serper | Serper（Google SERP） | 是 | serperApiKey / SERPER_API_KEY |
| brave | Brave Search | 是 | braveApiKey / BRAVE_API_KEY |
| bing | Bing Web Search | 是 | bingApiKey / BING_SEARCH_API_KEY |
| google-cse | Google 自定义搜索 | 是（key + cx） | googleApiKey + googleSearchEngineId |

注 1：微软 Bing Web Search API 已于 2025 年退役。bing 引擎保留用于对接兼容其协议的替代
endpoint（如 Azure Grounding 网关或自建镜像），可通过 bingEndpoint 指向。

注 2：默认值 https://searx.be 只是公共实例示例。公共实例普遍禁用 JSON 输出或带 bot 检测，
推荐自建 SearXNG（需在 settings.yml 的 search.formats 中加入 json），并把
searxngBaseURL 指向自建实例。

key 可以在设置页直接填写、写入 DSH credentials 服务，或通过环境变量导出；解析顺序为
字面量 → credentials 服务 → 启动环境变量。

安装

推荐用插件管理器 CLI（dshpm）安装：它会在安装时做质量门与健康检查（依赖全链扫描、bundle patch
行校验、安装即回滚）。dshpm 来自 dsh-web-plugin-manager；
如果还没装，先装管理器再装本插件。

方式一：从 npm 安装
dshpm install dsh-web-search-thirdparty --profile web

方式二：从 GitHub 安装（lib/ 已提交，无需本地构建）
dshpm install github:sunx16963-design/dsh-web-search-thirdparty --profile web
方式三：本地构建（先把构建产物放进 profile 内，再安装 —— 见下方警告）
git clone https://github.com/sunx16963-design/dsh-web-search-thirdparty.git
cd dsh-web-search-thirdparty
npm install
npm run build
关键：拷贝到 profile 目录内部（target 在 profile 内，链接才能解析到宿主包）
cp -r . "$DSH_HOME/profiles/web/vendor/dsh-web-search-thirdparty"
dshpm install "$DSH_HOME/profiles/web/vendor/dsh-web-search-thirdparty" --profile web

安装后重启 dsh web，设置页才会出现。卸载 / 升级：

dshpm update dsh-web-search-thirdparty --profile web
dshpm remove dsh-web-search-thirdparty --profile web

安装时的两个注意点

1）git / 本地源安装会被质量门暂停询问密钥 —— 直接留空跳过。
本插件安装与构建不需要任何密钥（密钥在设置页里填）。但管理器会扫描 README 里出现的
XXX_API_KEY / xxxApiKey 形态名称（上限 8 个，所以恰好是 tavily/serper/brave/bing 这些），
把它们当成“安装期需要的环境变量”并暂停询问。按提示补 --env KEY=（空值即跳过）再跑一次即可，
例如：

dshpm install github:sunx16963-design/dsh-web-search-thirdparty --profile web \
--env tavilyApiKey= --env TAVILY_API_KEY= --env serperApiKey= --env SERPER_API_KEY= \
--env braveApiKey= --env BRAVE_API_KEY= --env bingApiKey= --env BING_SEARCH_API_KEY=

2）本地路径必须落在 profile 目录内部，否则整个 profile 会启动失败。
dshpm install /repo/之外的绝对路径 会写成 link:/那个路径；插件代码是按它自己的位置解析
@deepseek-ai/ 的（宿主通过 profiles/node_modules 提供这些包），路径在 profile 外时解析链
够不到宿主包，启动时报
failed to import loader entry … Cannot find package '@deepseek-ai/cordis'，整个 profile 起不来。
所以本地安装请把构建产物放进 profiles//vendor/ 之后再 dshpm install（上面方式三就是这么做的）。
另外：github: 源在包已发布于 npm 时会被管理器映射到 npm 版本（日志会写 “installed from npm”），
所以 npm 上的版本落后时，github 安装拿到的是 npm 上那个版本；.tgz 路径则不被该管理器支持。

配置

设置存放在 dsh-web-search-thirdparty 分区下：

dsh-web-search-thirdparty:
provider: searxng
searxngBaseURL: https://searx.be   # 或自建实例
maxResults: 8
mergeResults: false
maxPerDomain: 2
relevanceSort: false
cacheEnabled: true
cacheTtlMs: 60000
retryCount: 1
retryBackoffMs: 250
默认 true：注册自带 web_fetch 抓取 provider。
设为 false 可把 web_fetch 交回宿主的官方 provider
（同时需要删掉本插件 bundle patch 里的 fetchProvider 行）。
enableFetchProvider: true

只在配置文件里生效的项

设置页表单覆盖常用项（供应商、密钥/实例 URL、条数、合并、域名限额、相关度、缓存、以及各引擎的高级参数）。
下面这些进阶项没有做进表单，只有写 settings.yaml / 配置层才生效（它们同样包含在“恢复默认”的清理清单里）：

timeoutMs、snippetMaxLength、retryCount、retryBackoffMs、extraHeadersJson、
fallbackProviders、maxProviderQueries、maxProviderConcurrency、
circuitEnabled、circuitFailureLimit、circuitCooldownMs、statsEnabled、
fetchAllowPrivate、fetchMaxBodyChars、fetchTimeoutMs、fetchUserAgent。

安全

- web_fetch 默认拒绝私网 / 环回 / link-local / 云元数据（169.254.169.254）以及一批特殊段：
IPv4 0.0.0.0/8、100.64.0.0/10(CGNAT)、192.0.0.0/24、192.88.99.0/24、198.18.0.0/15、
240.0.0.0/4；IPv6 ::1、fc00::/7、fe80::/10、ff00::/8、2002::/16(6to4)、
2001::/32(Teredo)、2001:db8::/32、64:ff9b::/96(NAT64)，以及 IPv4-mapped 的各种写法。
- 重定向手动逐跳跟随，每一跳都重新做 SSRF 校验（默认 follow 不会复查 Location）。
- DNS 解析失败按拒绝处理（解析路径不一致正是 rebinding 的入口）。
- 需要抓取内网时显式设置 fetchAllowPrivate: true。
- “测试连接”路由会把表单传入的 SearXNG 实例 URL 也过一遍 SSRF 校验。
- 已知残留风险：校验通过到实际连接之间仍存在一次 DNS 重解析窗口（0-TTL rebinding 的 TOCTOU）。
彻底消除需要在 connect 层 pin 已校验 IP（要引入 undici 之类的自定义 dispatcher），当前实现选择
不增加运行期依赖，因此该窗口仍在。请勿在不可信输入下打开 fetchAllowPrivate。

开发者

npm install
npm run build:host     # 编译宿主插件（lib/index.js）
npm run build:client   # 打包浏览器 UI（lib/client.js）
npm run typechecksh
npm install
npm run build:host     # 编译宿主插件（lib/index.js）
npm run build:client   # 打包浏览器 UI（lib/client.js）
npm run typecheck
npm test
npm pack

真实宿主自检（推荐，防上游断代）

单元测试用的是仓库自写的平台垫片，发现不了"上游删掉某个 API"这类断代。这个脚本把构建产物装进
真实的 cordis + dsh-web + dsh-settings-file 栈里跑一遍（apply 不抛错 / 设置分区注册 /
ctx.web.search 归一化 / ctx.web.fetch 抓取）：
sh
mkdir -p /tmp/dsh-e2e && cd /tmp/dsh-e2e
npm init -y >/dev/null && npm pkg set type=module
npm i --legacy-peer-deps @deepseek-ai/cordis@4 @deepseek-ai/dsh-web@0.1.5-rc.2 \
@deepseek-ai/dsh-settings@0.1.5-rc.2 @deepseek-ai/dsh-settings-file@0.1.5-rc.2 \
@deepseek-ai/dsh-credentials@0.1.5-rc.2 @deepseek-ai/dsh-launch-environment@0.1.5-rc.2 \
@deepseek-ai/dsh-llm@0.1.5-rc.2 @deepseek-ai/schemastery@3
peer 不随依赖安装：按报错把缺的 @deepseek-ai/ 再装一次
node ./scripts/e2e-real-host.mjs /tmp/dsh-e2e

换 0.1.1-rc.2 之类的版本即可验证旧一代 settings API 路径（脚本会打印当前栈走的是哪一代）。

源码按职责拆分（src/index.ts 只保留引擎实现、门面、抓取 provider、路由与 apply）：

| 文件 | 职责 |
| --- | --- |
| src/engine-spec.ts | 引擎单表（provider 列表 / 标签 / 凭据输入 / endpoint / 高级参数 / 测试路由映射 / 重置字段） |
| src/config.ts | 配置形状与 schemastery 模式 |
| src/text.ts、src/html.ts | 结果归一化、片段清洗、实体解码、HTML→Markdown（纯函数） |
| src/net.ts | SSRF 校验与逐跳重定向 |
| src/state.ts | 结果缓存、并发执行、熔断、用量统计 |
| src/settings-compat.ts | 设置分区注册的两代 API 兼容层 |

全新 clone 只用公共 npm 包即可构建。@deepseek-ai/* 的编译期类型由仓库自带的 ambient 垫片提供；
运行期仍由 DSH 提供真实包（宿主按 profile 链接解析，不会产生第二份副本）。

新增一个搜索引擎

引擎信息集中在 src/engine-spec.ts 一张表里（provider 列表、标签、凭据输入行、endpoint、
高级参数表单、测试路由映射、重置字段全部由它驱动），新增引擎只需两步：

1. 在 src/index.ts 写实现函数并挂进 ENGINES；
2. 在 src/engine-spec.ts 加一条 spec。

宿主端与浏览器端共用这张表，tests/engine-spec.test.ts 会双向校验防止漂移。

Provider API

其它 Cordis 插件注入 web-search-thirdparty 服务即可注册自己的搜索源
（内置引擎 id 属于保留命名空间，第三方请使用自己的 id）：
ts
export const inject = ['web-search-thirdparty']

function apply(ctx) {
ctx.get('web-search-thirdparty').register({
id: 'my-source',
label: 'My Source',
search: async ({ query, maxResults, config }, signal) => ({
sources: [{ url, title, snippet }],
content: '可选 answer',
}),
})
}

许可证

BSD-3-Clause。见 LICENSE。