dsh-web-search-thirdparty

English | 简体中文

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

基于 DeepSeek Harness 开发。

版本与兼容

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

代际在运行期探测（settingsGeneration()），两条路都受测试保护。注意：如果你的 DSH 是
≥ 0.1.7 而 @deepseek-ai/schemastery 低于 3.18.3（.volatile() 从 3.18.3 才提供），
插件会在日志里给出明确告警，设置页将无法保存。

排查：设置页保存后 key 像是“被清空”了

先看设置页输入框下方的运行期状态（由 GET /api/web-search-thirdparty/config 提供）：

• 显示“运行期状态：密钥可用 ✓” —— 保存成功，可以正常搜索。密钥出于安全不回显，
  输入框清空是刻意行为，留空即为“保持现状”。
• 显示“未配置” —— 密钥没有写进宿主。按顺序检查：日志里有没有
  schemastery 版本过低 告警；插件是否真的在 profile 的 dsh.profile.bundles 里；
  是否按提示重启过 dsh web。

系统要求

• 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 接口）。
• 运行期配置自检：GET /api/web-search-thirdparty/config 逐引擎回报“配好了没有”
  （走与真实搜索相同的凭据解析链），设置页用它显示运行期状态。

支持的引擎

> 注 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 路径则不被该管理器支持。

配置

设置页写入的字段落在当前 profile 的 patch 文档里，分区名随 DSH 代际而不同：

• DSH ≥ 0.1.7：分区名 = 组合条目 id，即 web-search-thirdparty（cordis.patch.yml 里 insert 的 id）。
• DSH ≤ 0.1.6：分区名 = 本插件注册的 namespace，即 dsh-web-search-thirdparty（写到 settings.yaml）。

web-search-thirdparty:          # ≤0.1.6 上是 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

> 在 DSH ≥ 0.1.7 上，配置字段在 schema 里都是 volatile()：设置页写入后无需重启，
> 插件下一次搜索就会用新值。

只在配置文件里生效的项

设置页表单覆盖常用项（供应商、密钥/实例 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 typecheck
```sh
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 抓取）：

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/[email protected] \
@deepseek-ai/[email protected] @deepseek-ai/[email protected] \
@deepseek-ai/[email protected] @deepseek-ai/[email protected] \
@deepseek-ai/[email protected] @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）：

全新 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）：

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。