dsh-web-search-thirdparty
English | 简体中文
为 DSH（DeepSeek Harness）开发的第三方网页搜索插件。它用可配置的搜索引擎替换 dsh 自带的
“仅官方 DeepSeek”搜索，为每个引擎提供独立设置，并可抓取网页全文，让模型既能搜索也能阅读。
基于 DeepSeek Harness 开发。
版本与兼容
支持 DSH 最新版，并自动兼容旧版设置 API（0.1.0-rc.6 起）：
| DSH 设置服务 | 代际特征 | 本插件的走法 |
|---|
≥ 0.1.7-alpha.1 | dsh-settings 导出 SettingsForms；设置文档按 profile 条目 id 自动服务该条目的 Config，且只投影 .volatile() 字段 | Config 每个可编辑字段声明 .volatile()；客户端走 ctx.configForms.get('web-search-thirdparty')；分区名 = 组合条目 id |
0.1.2 ~ 0.1.6-alpha.2 | 导出 SettingsProvider，有 installSection | Config 不声明 volatile；客户端走 ctx.settingsScope.bind({ namespace: 'dsh-web-search-thirdparty' }) |
≤ 0.1.1-rc.2 | 顶层 helper installSettingsSection | 同上一行，注册走 helper |
代际在运行期探测（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 逐引擎回报“配好了没有”
（走与真实搜索相同的凭据解析链），设置页用它显示运行期状态。
支持的引擎
| 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/<name>/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/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、
高级参数表单、测试路由映射、重置字段全部由它驱动），新增引擎只需两步：
- 在
src/index.ts 写实现函数并挂进 ENGINES；
- 在
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。
