免密网页搜索 hy-sde/dsh-web-search-public

[!NOTE]
📦 本插件位于 dsh-plugins 单体仓库 —— 问题反馈和 PR 请提交到那里。
npm：@hy-sde-org/dsh-web-search-public

dsh-web-search-public —— 免凭证的 DeepSeek Harness 网页搜索

为 DeepSeek Harness 提供的零 API key 网页搜索服务商。
只需一次 web_search 调用，它就会把查询并行分发到全部五个公共搜索引擎 —— Startpage、DuckDuckGo、Ecosia、Google、Mojeek —— 再按跨引擎共识合并结果。这样，单个引擎的机器人验证、超时或空页面都不会拖垮搜索。无需 API key，无需账号，无需 fetch 服务商，无需任何配置。

| 标识 | 值 |
| 包名 | @hy-sde-org/dsh-web-search-public |
| 插件 id | web-search-public |
| 服务商 id | public |
| 引擎（并行分发） | startpage、duckduckgo、ecosia、google、mojeek |
基于 oh-my-pi —— 免凭证引擎抓取器移植自 oh-my-pi 的 web/search/providers，本服务商忠实移植了 oh-my-pi 的并行 searchPublicWeb 聚合逻辑（分发、软/硬截止时间、共识合并），并适配到 DeepSeek Harness 的 ctx.web 接缝。
oh-my-pi 采用 MIT 协议（Mario Zechner、Can Bölük）；详见 THIRD-PARTY-NOTICES.md。

为什么需要它

DeepSeek Harness 自带的搜索服务商都需要 API key（DeepSeek、Exa、Perplexity）。
本插件是免凭证的默认选择：每次搜索都向所有公共搜索引擎并行发出匿名请求。遇到机器人验证、限流或宕机的引擎会被自动消化 —— 答案来自那些正常响应的引擎，多个引擎都认可的结果排在最前。整个调用受软/硬截止时间约束，所以卡住的引擎绝不会把搜索拖到工具预算上限。

前置条件

- Node.js 22.19 或更高版本，且 PATH 中有 npm 和 pnpm；
- DeepSeek Harness 0.2.0-rc.2，包含标准 dsh 命令行；
- 无需 API key —— 别的什么都不需要。

继续之前，先安装 Harness 命令行和 pnpm：

npm install --global @deepseek-ai/dsh@0.2.0-rc.2 pnpm
dsh --version

快速开始

路线 A —— 已发布的 npm 包（推荐）

dsh plugin --profile web add @hy-sde-org/dsh-web-search-public

路线 B —— 从源码安装（验证当前检出，或改造插件）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins/dsh-web-search-public
pnpm install
PACKAGE_TARBALL="$(pnpm pack | tail -n 1)"
dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
cd ../..

pnpm pack 会执行常规的 prepack 构建，产出包含 dist/ 的 tarball。直接依赖 github:<this-repo> 不包含构建产物，不是受支持的安装路径——始终安装构建好的 tarball（或已发布的包）。

验证组合后的配置

dsh web --dump-config

组合后的配置树必须显示 web.config.searchProvider: public，以及一行 web-search-public 插件记录，加载 @hy-sde-org/dsh-web-search-public。

运行

dsh web

让智能体用 web_search 搜点东西。工具会返回渲染好的来源，来自共识合并后的并发扇出。

卸载

dsh plugin --profile web remove @hy-sde-org/dsh-web-search-public

已经内置了？ 如果你的 harness 检出已经在基础 bundle 里挂载了 web-search-public （近期某个版本已把这个包采纳为随附默认项），跳过安装——它已经是生效中的服务商。
再叠加这个 bundle 会重复加载器记录，启动时报错（“duplicate loader entry id”）。

这个 bundle 做什么

包声明了一个 DSH bundle（dsh.bundle.patch → cordis.patch.yml），所以 dsh plugin 安装它时会把补丁层应用到配置档：

1. 把 web.config.searchProvider 设为 public（让免凭据的扇出成为默认），
2. 插入 web-search-public 插件记录。

带密钥的 DeepSeek 路由（web-search-deepseek，服务商 id 为 deepseek-official）没有 被禁用——偏好它的部署可以显式设置 web.searchProvider: deepseek-official 并提供 DEEPSEEK_API_KEY 凭据，保留自己的选择。
没有挂载 fetch 服务商，tool-web 保持 fetch: false：模型能搜索，不能抓取任意 URL，这样把 SSRF 暴露面完全推迟了。

扇出怎么工作

PublicSearchProvider.search() 并发竞速 engines（忠实移植自 oh-my-pi 的
searchPublicWeb）：

┌────────────────────── fan-out (one query) ──────────────────────┐
▼ ▼ ▼ ▼ ▼
startpage duckduckgo ecosia google mojeek
└────────────► consensus merge ◄────────────────┘

- 每个引擎并行发起查询。竞速在以下最早发生的时刻返回：所有引擎都已结束； 软截止时间（默认 5 秒）到达且手里至少有一个成功结果；或硬截止时间 （默认 30 秒）到达，无论情况如何——然后中止所有仍在运行的引擎。
如果软截止时间已过、还没有成功结果、且并非全部失败，调用会继续等到硬截止时间，等第一个成功结果。
- 来源跨引擎去重（URL 归一化：大小写、www.、末尾斜杠），按跨引擎共识排序——即有多少个引擎返回了同一 URL——再按最佳排名，再按引擎顺序。
信息量最大的摘要胜出；排名相同时，靠前引擎的标题/URL 胜出。
- 每个引擎仍跑在自己的 AbortSignal.timeout(timeoutMs) 竞速里，所以无视聚合取消的引擎会在自己的上限处终止。
- 限流韧性是尽力而为、分层的。 硬封锁（HTTP 4xx）或连续搜索都返回零结果时，会打开该引擎的熔断器：跳过该引擎 engineBackoffMs（默认 5 分钟，每连续触发一次翻倍，上限 maxEngineBackoffMs），期间不发送请求，窗口结束后再探测。可重试的传输失败（HTTP 5xx、超时、网络抓取失败）会按指数退避重试整个扇出（maxRetries/retryDelayMs，可中断的等待）；硬封锁永不重试。重试耗尽后——或所有引擎都不可用——服务商会快速失败 failureCooldownMs（默认 5 分钟），返回 retry in about Ns 错误，而不是再次猛打刚刚限流我们的引擎（那会加深封锁）。纯全 no results 聚合属于查询级，永不重试也不冷却。

- 只要配置了至少一个引擎，available() 就是 true——服务商始终可用，这正是重点。
- 调用方中断（signal.aborted）会中断扇出并抛出 WEB_ABORTED。
- 只有每个引擎都失败时，服务商才抛出 WEB_PROVIDER_ERROR，并附上各引擎的原因（id: <reason>; …）。零自然结果、引擎超时、HTTP 请求失败都算「该引擎没有内容」，由合并逻辑吸收。

默认配置的最坏情况约为 hardDeadlineMs（30 秒），远低于随附 harness bundle 中 dsh-tool-web 预留的 60 秒搜索预算。

浏览器升级（机器人墙）

Google、Ecosia 和 Mojeek 是浏览器后端（omp browserFetch 移植）：每个引擎先尝试普通 fetch，携带一致的 Chrome 导航头（由其 UA 推导的 client hints）；若收到机器人墙——启用 JS 的重试页、Cloudflare 托管挑战（「Ecosia Firewall」）、Mojeek 的 ALTCHA 工作量证明墙，或 Google 的「unusual traffic」/sorry 门——就通过 ctx.browser.fetchPageHtml（@hy-sde-org/dsh-browser 服务，stealth launch 或 CloakBrowser patch 后端）升级到真实浏览器：首页 URL 播种 cookie、尽力等待就绪选择器、ALTCHA 自动求解（强制点击 shadow-DOM 复选框 + 等待 PoW 重定向，omp 的 solveCaptcha）。只有所有传输——fetch 和浏览器——都被封锁时，熔断器才打开。

升级是可选的：把 browser 服务行挂载到本服务商之前，浏览器后端引擎就会启用；不挂载则保持仅 fetch（原始行为），timeoutMs（默认 30 秒）是覆盖 fetch → 浏览器各步骤的单引擎预算。

配置

所有选项均可选；常量填充默认值。通过配置档补丁中插件行的 config: 配置，或通过 ctx.plugin(...) 以编程方式配置。

| 选项 | 默认值 | 用途 |
| engines | startpage, duckduckgo, ecosia, google, mojeek | 扇出竞争的引擎 id；此顺序是共识平局时的决胜顺序；未列出的引擎保持禁用 |
| timeoutMs | 30000 | 每个引擎的传输超时（ms）：即使某个引擎忽略整体取消，也要限制它的耗时；浏览器类引擎可能把这段时间花在 fetch → stealth-browser 升级上，所以默认是 30 秒 |
| softDeadlineMs | 5000 | 软性总截止时间——所有引擎都结束，或超过这个时间且至少有 1 个成功，就立即返回 |
| hardDeadlineMs | 30000 | 硬性总截止时间——有多少返回多少，哪怕什么都没有；必须 ≥ softDeadlineMs |
| maxRetries | 1 | 当所有引擎都失败、且至少有一个引擎死于可重试的传输故障（HTTP 5xx、超时、网络请求失败）时，对整个聚合结果重试的次数。每次重试都会在退避后重新跑一遍完整的扇出，所以即使第一次尝试被短暂的引擎限流打掉，仍能拿到结果。0 表示不重试。硬性拦截（HTTP 4xx）永不重试——它会打开该引擎的熔断器——而纯粹全是 no results 的聚合属于查询层面，永不重试。 |
| retryDelayMs | 2000 | 第 1 次重试前的基础延迟（ms）；之后每次尝试翻倍。 |
| failureCooldownMs | 300000 | 所有引擎都挂掉（重试耗尽，或每个引擎都被硬性拦截/触发熔断）后的快速失败窗口（ms）：窗口内的搜索直接返回清晰的 retry in about Ns 错误，而不是再去猛打刚刚限流我们的引擎（那会加深封锁）。0 表示关闭该窗口。 |
| engineBackoffMs | 300000 | 每个引擎熔断器的基础窗口（ms）：某个引擎被硬性拦截（HTTP 4xx），或连续多次搜索都返回空结果，就在这段时间内跳过它，而不是每次搜索都再猛打一遍。每连续触发一次翻倍，上限为 maxEngineBackoffMs；探测成功后重置。0 表示关闭单引擎熔断器。 |
| maxEngineBackoffMs | 3600000 | 单引擎熔断器窗口翻倍后的上限（ms）。 |
| userAgent | 浏览器风格的常量 | 发给各引擎的 User-Agent（刻意不用产品 UA） |

- id: web-search-public
name: '@hy-sde-org/dsh-web-search-public'
config:
engines: [startpage, duckduckgo, google, mojeek] # drop Ecosia, reorder
timeoutMs: 30000
softDeadlineMs: 4000
hardDeadlineMs: 25000
maxRetries: 1
retryDelayMs: 2000
failureCooldownMs: 300000
engineBackoffMs: 300000
maxEngineBackoffMs: 3600000

PublicEngineId 的取值就是导出的引擎 id；任何不在已知集合里的 id 都会在启动时被丢弃，而引擎数为零的配置会让 available() 返回 false（并暴露 WEB_PROVIDER_CONFIGURED_UNAVAILABLE）。

错误

搜索失败使用 web 接缝的 WEB_* 错误码：

| 错误码 | 含义 |
| WEB_PROVIDER_ERROR | 所有引擎都失败；消息里列出 id: reason; … |

被限流的全失败聚合（传输特征、重试耗尽）会暴露同一个 WEB_PROVIDER_ERROR，消息为 public search engines are rate limited (…); retry in about Ns。
| WEB_ABORTED | 调用方在搜索中途中止 |
| WEB_PROVIDER_CONFIGURED_UNAVAILABLE | 配置的服务商不可用 |
| WEB_PROVIDER_CONFIGURED_MISSING | 配置的服务商 id 未注册 |

隐私与安全说明

- 不涉及凭据。 服务商从不读取密钥，因此不会发生泄露。引擎只收到查询和浏览器形态的 User-Agent，别的什么都没有。
- 把查询当作公开信息。 每个查询都以匿名请求发给公开搜索引擎——而且因为扇出，会同时发给多个引擎。不要搜索你不愿粘贴进公开搜索框的机密或 PII。
- 放大效应是固有的。 每次搜索都会并行联系所有已配置引擎（每个查询最多 5 次匿名抓取）。这是换取韧性和共识的代价，相比单引擎链路，它提高了触发机器人挑战 / 限流的风险——见 docs/operations.md。
- 没有 fetch 服务商。 tool-web 的 fetch: false 保持不变：模型无法指向任意 URL，因此 SSRF 和不安全内容的暴露面始终关闭。
- 重定向策略。 所有引擎抓取都使用 redirect: "error"——重定向按失败处理，由合并逻辑吸收，而不是把调用方泄露到外部位置。
- 遇到挑战是正常的。 Startpage、Ecosia 和 Google 经常返回机器人校验；解析器把被挑战的页面当作零结果，扇出逻辑容忍这种情况。运行时预期见 docs/operations.md。

兼容性

| 组件 | 支持的契约 |
| Node.js | 22.19 或更新 |
| DeepSeek Harness | 0.2.0-rc.2（@deepseek-ai/dsh-web、@deepseek-ai/cordis peer 范围） |
| Seam | ctx.web WebSearchProvider（无密钥，无 fetch 服务商） |

本服务商只实现 WebSearchProvider seam 契约；面向模型的工具是 @deepseek-ai/dsh-tool-web，本包不提供。DeepSeek Harness 是开发者预览版。上游 seam 契约变更需要发布新包并做契约评审。

开发

npm ci
npm run check
npm test
npm run build
npm pack --dry-run

默认测试套件针对 fixture HTML 运行解析器和 provider 契约测试（不联网），覆盖扇出、共识合并和截止时间行为。要对抓取器做真实网络验证、对照当前引擎标记，请运行需手动开启的真实测试——它会用 Startpage、DuckDuckGo 和 Mojeek 跑自然结果，并验证被机器人挑战的引擎（Ecosia/Google）是降级而不是崩溃：

DSH_WEB_SEARCH_REAL_E2E=1 npm run test:real

发布检查清单和设计约束见 CONTRIBUTING.md，运行时行为和故障排查见 docs/operations.md。

许可与署名

本包采用 MIT 许可——与其上游 oh-my-pi 相同。无凭据的引擎抓取器和并行 searchPublicWeb 聚合设计移植自 oh-my-pi（MIT License，© Mario Zechner 2025，© Can Bölük 2025-2026）；上游版权持有人记录在 LICENSE 中，与本包自己的声明并列，上游声明全文转载于 THIRD-PARTY-NOTICES.md。

本插件是独立可安装的包；harness 仍归其所属项目所有。