240xu/dsh-websearch

@240xu/dsh-websearch

npm version
license

面向 DeepSeek Harness 的聚合网页搜索 provider —— 一个插件 id unified，并发扇出到十一个后端，合并 + URL 去重结果，即使部分后端宕机仍保持可用。

纯 Cordis 直插：在 ctx.web 注册唯一一个 provider，因此 dsh-web 的选择规则永远不会触发 WEB_PROVIDER_AMBIGUOUS。开箱即用的零配置搜索（Exa + Parallel + DuckDuckGo + SearXNG 均无需 key）；API-key 后端（DeepSeek / Anthropic / OpenAI / Brave / Tavily / Serper / Mojeek）在通过 credentials 服务或环境变量提供 key 后自动激活。

DSH（DeepSeek Harness）原生插件：向 ctx.web 注册唯一的聚合搜索 provider unified，内置十一后端并发 fan-out，合并 + URL 去重后返回——即使部分后端宕机仍可用。

纯 Cordis 直插：只注册一个 provider，所以 dsh-web 的选择规则永远不会触发 WEB_PROVIDER_AMBIGUOUS。零配置即可搜索——Exa + Parallel + DuckDuckGo + SearXNG 四者皆无 key、开箱即用；DeepSeek / Anthropic / OpenAI / Brave / Tavily / Serper / Mojeek 在提供 API key 后自动激活。

后端 | Backends

| id | key | endpoint | 返回方式 | 备注 |
|---|---|---|---|---|
| exa | 无 | https://mcp.exa.ai/mcp | streamable-http MCP，工具 web_search_exa { query, numResults }，文本块 "Title:/URL:/Published:/Highlights:" | opencode 同源，无 key |
| parallel | 无 | https://search.parallel.ai/mcp | streamable-http MCP，工具 web_search { objective, search_queries[], session_id?, model_name? } 返回 JSON 字符串 { search_id, results: [{ url, title, publish_date, excerpts[] }] } | opencode 同源，无 key |
| ddg | 无 | https://html.duckduckgo.com/html/ | HTML 抓取，解码 uddg= 重定向参数获取真实 URL + result__snippet | 兜底，零依赖 |
| searxng | 无/可选 | https://searx.be/search（默认） | REST JSON /search?q=，公共实例无限制 | 元搜索，隐私友好 |
| brave | BRAVE_API_KEY | https://api.search.brave.com/res/v1/web/search | REST JSON，独立索引，每月 2000 次免费 | 高质量，无 Google 偏见 |
| tavily | TAVILY_API_KEY | https://api.tavily.com/search | REST JSON，面向 AI，answer + results[]，深度搜索 | AI 专用，含答案摘要 |
| serper | SERPER_API_KEY | https://google.serper.dev/search | REST JSON，抓取 Google organic[]，每月 2500 次免费 | 极速，结构化 |
| mojeek | MOJEEK_API_KEY | https://api.mojeek.com/v1/search | REST JSON，独立索引，每天 1000 次免费 | 无追踪，英文为主 |
| deepseek | DEEPSEEK_API_KEY | https://api.deepseek.com/anthropic/v1/messages | Anthropic Messages API + 原生 web_search_20250305 服务端工具，模型 deepseek-v4-flash | 与 dav web-search-deepseek 同机制 |
| anthropic | ANTHROPIC_API_KEY | https://api.anthropic.com/v1/messages | Anthropic Messages + web_search_20250305，模型 claude-sonnet-4-6 | Claude Code 同机制 |
| openai | OPENAI_API_KEY | https://api.openai.com/v1/responses | Responses API 原生 web_search 工具，解析 url_citation 注解 | Codex 同机制 |

可用性说明：available() 只做本地配置检查（不联网探测可达性）；密钥在每次搜索时按操作解析，缺失时该后端以明确错误码软失败（不阻塞其他后端）。全部缺 Key 时错误会指向设置页。

SearXNG 实例 | Public instances

SearXNG 默认指向 https://searx.be；公共实例可用性随网络环境波动，失败时错误信息会提示换源。
在设置面板修改 searxngBaseURL 即可切换，常见候选：

| 实例 | 备注 |
|---|---|
| https://searx.be | 官方默认，部分地区不可达 |
| https://searx.tiekoetter.com | 稳定性较好 |
| https://priv.au | 隐私友好 |
| 自托管 | 最可靠，支持 API Key（searxngApiKeyEnv） |

Install | 安装

方式一：作为 profile 依赖安装（推荐，规范做法）

cd ~/.dsh/profiles/web
在 package.json 的 dependencies 里加入：
"@240xu/dsh-websearch": "file:/path/to/@240xu/dsh-websearch"
pnpm install

插件自带 dsh.bundle 元数据（package.json 声明 "dsh": {"bundle": {"patch": "./cordis.patch.yml"}}），把它加入 profile package.json 的 dsh.profile.bundles 列表后即自动注册，无需在 cordis.patch.yml 手写条目。

只需在 ~/.dsh/profiles/web/cordis.patch.yml 里把内置 web_search 工具指到 unified provider：

- id: web
name: '@deepseek-ai/dsh-web'
config:
searchProvider: unified
- id: web-search-deepseek
name: '@deepseek-ai/dsh-web-search-deepseek'
disabled: true

重启 dsh web 即生效。

Settings | 配置

v2.0.3 起，配置界面位于 Settings → 左侧栏「搜索 / Web Search」（顶级分区，与通用/模型/插件同级）。
每个 API Key 字段旁有 「获取 Key ↗」 直达对应平台控制台；保存即写入凭证库并立即生效。

插件向 DSH 设置面板注册 unified-search namespace（Settings → Unified Search），全部字段扁平化、开箱可编辑：

全局

| 字段 | 默认 | 说明 |
|---|---|---|
| numResults | 8 | 每次搜索返回结果数（1-50） |
| concurrency | 6 | 并发后端数（1-10） |
| backendTimeoutMs | 30000 | 单后端超时毫秒 |
| recency | any | 时间范围过滤：day / week / month / year（映射到各后端原生参数） |
| language | 空 | 搜索语言，如 en、zh-CN（SearXNG/Brave/Serper 支持） |
| safeSearch | true | 安全搜索开关（SearXNG/Brave 支持） |
| dedupStrategy | url | url 仅按链接去重；url+title 额外合并同标题的转载镜像 |
| rerank | false | 按查询词相关性重排序（确定性；并列时保持后端优先级） |

v2.1 结果策略：设置面板新增「结果策略」分区。时间/语言过滤按各后端能力自动映射——Brave freshness/country/search_lang、Tavily time_range、Serper tbs/hl/gl（Google 日期语法）、SearXNG time_range/language、DDG df；不支持的后端自动忽略对应维度。内部超时以真实原因失败（backend "" timed out after Nms），不再被静默降级为取消；Mojeek 的 API Key 改走 Authorization 头，不再出现在 URL 中。

结果健康遥测（默认开）：每次搜索的 content 尾部附一行 [websearch backends] exa ✓5ms/3 · ddg ✗30000ms，
模型可据此自诊断并建议用户调整设置；设置面板「结果策略」可关闭（resultTelemetry）。

11 个后端开关：enableExa / enableParallel / enableDdg / enableSearxng（默认开）；enableBrave / enableTavily / enableSerper / enableMojeek / enableDeepseek / enableAnthropic / enableOpenai（默认关）

API Key 授权（credential-ref，填环境变量名，实际 key 存于 credentials 服务或环境变量）：

| 字段 | 默认引用 |
|---|---|
| braveApiKeyEnv | BRAVE_API_KEY |
| tavilyApiKeyEnv | TAVILY_API_KEY |
| serperApiKeyEnv | SERPER_API_KEY |
| mojeekApiKeyEnv | MOJEEK_API_KEY |
| deepseekApiKeyEnv | DEEPSEEK_API_KEY |
| anthropicApiKeyEnv | ANTHROPIC_API_KEY |
| openaiApiKeyEnv | OPENAI_API_KEY |
| searxngApiKeyEnv | SEARXNG_API_KEY（私有实例可选） |

Base URL / Model：每个 key-gated 后端都有对应 ${id}BaseURL；DeepSeek/Anthropic/OpenAI 另有 ${id}Model；Tavily 有 tavilySearchDepth（basic/advanced）。

环境变量兜底：未在 credentials 配置时回退读同名环境变量；DSH_UNIFIED_SEARCH_BACKENDS 可逗号分隔强制指定启用集合。

Design | 设计

- 一个 provider，无歧义：单个 registeredSearchProvider({id:"unified"}) —— dsh-web 接缝的选择规则会无歧义地选中它，且 search() 自行限制 maxResults。
- Promise.allSettled 扇出：每个已启用且可用的后端并发触发；单个后端失败会被降级为软 null，以便其余后端仍能贡献结果 —— 只有当全部失败时，provider 才抛出 WEB_PROVIDER_ERROR。
- 按后端中止降级：单个后端中止会变为软 null；只有当调用方自身的 AbortSignal 触发时，provider 才重新抛出 WEB_ABORTED。
- 去重策略：url 保留历史性的 URL 键合并，并跨后端填充字段；url+title 额外折叠同一事件的联合供稿镜像（标题 Jaccard >= 0.9，CJK 感知分词器），同时仍会丰富保留的条目。
- 确定性重排（可选）：查询词重叠评分（标题 x3 / 摘要 x2 / URL x1）；稳定平局保留扇出优先级 —— 相同输入始终产生相同顺序。
- 诚实的超时：每个后端都在一个内部中止控制器下运行，该控制器合并到调用方信号中；当只有内部计时器触发时，失败会被重新归类为 WEB_PROVIDER_ERROR（“backend  timed out”），而不是被掩盖为用户取消。
- 并发与超时控制：concurrency（默认 6）限制同时调用数；backendTimeoutMs（默认 30s）限制每个后端。
- Streamable-http MCP，自定义握手：lib/util/mcp-client.js 实现 initialize → notifications/initialized → tools/call，并针对 Exa 和 Parallel 缓存 Mcp-Session-Id 头 —— 不依赖完整的 MCP SDK。
- 宿主日志诊断：每个后端都通过 lib/util/log.js 将请求/结果路由到宿主日志记录器（ctx.logger），尽力而为且从不抛出 —— 刻意不作为会话事件：会话事件词汇表是一个封闭集合，第三方插件不得扩展（未知的信封类型会使整个会话日志不可读）。

Architecture | 架构

lib/
index.js                 # name/inject/Config/apply — registers settings + provider
provider.js              # UnifiedSearchProvider — fan-out, abort demotion, dedup, truncate, concurrency, timeout
util/
abort.js               # isAbortError / searchAborted / throwIfSearchAborted / maybeAbortError
mcp-client.js          # streamable-http MCP client (initialize + tools/call + session cache)
log.js                 # recordBackendRequest / recordBackendOutcome → session event log
backends/
exa.js                 # Exa (web_search_exa) via mcp-client
parallel.js            # Parallel (web_search) via mcp-client
ddg.js                 # DuckDuckGo HTML 抓取（uddg 重定向解码）
searxng.js             # SearXNG REST JSON（无需密钥）
brave.js               # Brave Search REST（需密钥）
tavily.js              # Tavily REST（需密钥，AI 回答 + 深度搜索）
serper.js              # Serper.dev REST（需密钥，Google 抓取）
mojeek.js              # Mojeek REST（需密钥）
anthropic-like.js      # 共享：DeepSeek + Anthropic（Messages API + web_search_* 服务端工具）
openai.js              # OpenAI /responses + web_search 工具（url_citation 解析）
index.js               # 统一注册表 + 单独导出
tests/
parse.test.js            # 28 个单元测试，针对每个后端的纯解析函数
provider.test.js         # 5 个扇出测试（合并/去重、中止降级、全部失败、maxResults 上限、并发）

Test | 测试

node --test tests/

33/33 通过。

License | 许可

MIT © 2026 240xu