@240xu/dsh-websearch 2.7.3 → 2.8.1

package/README.md

@@ -115,6 +115,36 @@ pnpm install
 
 环境变量兜底：未在 credentials 配置时回退读同名环境变量；`DSH_UNIFIED_SEARCH_BACKENDS` 可逗号分隔强制指定启用集合。
 
+## v2.8.1 SettingsForms 适配 | What's new in v2.8.1
+
+- **0.2.0 设置面板表单**：Config 标记 `meta.volatile`——0.2.0 SettingsForms 从插件 Config 自动生成表单，但 volatileForm 只保留 volatile 字段（此前 websearch 表单为空）；现整棵 Config 成为 0.2.0 表单。裁决与考证见 dsh-plugin-hub/docs/reviews/cross-settings-forms.md。
+- 删除 0.2.0 线上与可见 UI 自相矛盾的 "no installSection" console.warn（0.1.5 路径不变）。
+- 补齐全部裸字段（×ApiKeyEnv/×BaseURL/×Model）的 description——0.2.0 表单渲染唯一用户可见文案来自 meta.description。
+
+## v2.8.0 查全查多 | What's new in v2.8.0
+
+面向「查的多一点、查的全一点」的检索深度升级，全部 feature-gated、默认关：
+
+### 1. multiQuery 多查询 RRF 融合（`multiQueryEnabled`，默认关）
+
+- 门控启发式（刻意从严）：查询长度 > 60 字符，或含 `vs / and / 比较 / 对比 / 和` 分隔词，才触发；简单查询单扇出，行为与旧版完全一致（arXiv:2404.01037：盲目多查询会劣化）。
+- 触发后派生 ≤3 个子查询（原查询永远参与融合且保持全权重），各自走完整 11 后端扇出，再用 RRF（k=60）融合：出现在多个子查询结果里的条目被提升，单列表独占条目按位次衰减；URL 去重、首见元数据保留。
+- 遥测行合并各变体并截断至 12 条，避免淹没结果。
+
+### 2. deepCoverage 深度覆盖（`deepCoverage`，默认关）
+
+- 每后端请求条数上调至 `ceil(maxResults × 1.5)`，全局去重后仍按 maxResults 截断——牺牲带宽换覆盖面。
+- 后端能力适配（feature-detect，不破坏旧参数）：Tavily 自动切 `search_depth: advanced`（2 credits，多 snippet/URL）；SearXNG 类目扩为 `general,news,it`（Search API `categories` 逗号列表）。
+- Exa：`inferExaCategory` 从查询推断 data category（github / research paper / news，仅高置信注入）。
+
+### 3. 运维可观测（P2）
+
+- `GET /api/websearch/history` 响应新增 `backends` 字段：每后端最近真实成败/延迟/熔断状态（`{id, ok, ms, at, failCount, cooled}`，无错误串无凭证），兜底冗余度可观测。
+
+### 4. per-backend 超时上限（P2）
+
+- `ddg` / `searxng` 专属超时上限 5s（`min(5s, backendTimeoutMs)`，全局默认仍 30s、配置更短则以配置为准）——不可达后端不再拖住整个扇出尾。实测见 docs/real-call-2.8.0.md。
+
 ## v2.7.3 兼容修复 | What's new in v2.7.3
 
 - **DSH 0.1.7 客户端兼容（P0）**：settingsScope 客户端服务在 0.1.7 被移除；现改为 feature-detect——0.1.5（或装 dsh-settings-scope-shim）行为不变，0.1.7 无 shim 时设置卡片优雅停用（console.warn 指引），客户端不再静默全死。
@@ -216,7 +246,9 @@ v2.7.0 缓存/熔断/历史三项的依据与刻意取舍（含查证过的反
 1. **熔断器（Circuit Breaker）**：出处 Michael T. Nygard《Release It!》(Pragmatic Bookshelf, 2007) 与 Microsoft Azure Architecture Center「Circuit Breaker pattern」https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker 。经典状态机是 Closed → Open → Half-Open（半开态放行少量探测请求）。**本插件刻意省略半开态**：冷却到期即视为 Closed（下一次真实搜索就是探测），失败则立即重新开窗——因为这里的"请求"是一次多后端扇出中的单个后端调用，探测请求必然真实发生且失败成本只是一次软降级，无需额外探测计数器；同时保留 fail-open 兜底（全部冷却时放行），比经典模式更保守。
 2. **缓存失效（TTL-only vs 事件驱动）**：Cloudflare「Retention vs Freshness (TTL)」https://developers.cloudflare.com/cache/concepts/retention-vs-freshness/ 与「Revalidation」https://developers.cloudflare.com/cache/concepts/revalidation/ 。搜索结果没有可靠的原站变更信号可订阅（网页索引持续变化），事件驱动失效无锚点；TTL-only + 把 TTL 做成设置项（默认 900s）+ key 纳入后端组合，是"可接受的最终一致性"。取舍：900s 内索引更新不可见——对搜索场景可接受，且用户可调低。
 3. **原子写（tmp + renameSync）**：POSIX 上 rename(2) 原子替换（Node 文档：newPath 已存在时覆盖）；Windows 上 libuv 将 fs.rename 映射为 MoveFileExW(MOVEFILE_REPLACE_EXISTING)（libuv#283 https://github.com/joyent/libuv/issues/283 ，LWN 讨论 https://lwn.net/Articles/682988/ 指出 MS 文档不承诺该调用的原子性）。**结论：POSIX 双端原子；Windows 实践上等价但官方文档不背书**——因此本插件在写入端额外做了兜底：读端永远校验 JSON 完整性、坏条目按 miss 处理并删除，即使 Windows 上出现半写状态也不会返回坏数据。
-4. **搜索历史隐私**：Article 29 Working Party 意见书 WP148 https://ec.europa.eu/justice/article-29/documentation/opinion-recommendation/files/2008/wp148_en.pdf 认定查询日志（query + 时间 + 来源标识）属个人数据；EFF 六条自保建议 https://w2.eff.org/Privacy/search/searchtips.pdf 的第一条是"别在搜索词里放 PII"——说明 query 天然可能携带 PII（人名、账号、地址）。本插件的取舍：历史只存 {query, time, resultCount, backendsOk/Total}（无 IP、无 cookie、无结果 URL）、环形 50 条自动滚动即短保留、本机存储不出网、提供 historyEnabled 开关与 POST clear 端点。**未做 query 脱敏**：脱敏会破坏"查看最近搜了什么"的核心用途，且本机单用户场景下该数据本就在 DSH 会话日志里存在；若未来历史跨设备同步，脱敏/加密是上线前置条件。
+4b. **查全查多（v2.8.0）**：Tavily Search API（`search_depth: advanced` 2 credits、`max_results` 0-20、`include_answer`、topic=news 时间加权）https://docs.tavily.com/api-reference/endpoint/search ；Exa Search API（type 分类检索、category 枚举、livecrawl；注意 2026 版 coding-agent 指南声明 neural 为 legacy 术语、且告诫勿臆造 category 值——本插件只注入 OpenAPI 枚举内的高置信值）https://exa.ai/docs/reference/search-api-guide-for-coding-agents 与 https://github.com/exa-labs/openapi-spec/blob/master/exa-openapi-spec.yaml ；SearXNG Search API（`categories` 逗号多类目、`language`）https://docs.searxng.org/dev/search_api.html ；Brave Search API（`freshness`、`result_filter`，本轮仅调研未接线）https://api-dashboard.search.brave.com/app/documentation 。多查询融合：RRF 出自 Cormack et al. 2009，RAG-Fusion 实现 https://github.com/Raudaschl/rag-fusion ；HyDE https://arxiv.org/abs/2212.10496 ；**门控依据** arXiv:2404.01037（盲目多查询劣化）——因此 multiQuery 默认关、启发式从严、原查询全权重参与。
+4c. **per-backend 超时**：不可达主机的 TCP 连接失败不受应用层超时保护，只能靠 abort 计时器兜底；ddg（HTML 抓取）与 SearXNG（公共实例无 SLA）是拖尾主力，5s 上限取「P50 成功延迟的一个数量级」。
+4d. **搜索历史隐私**：Article 29 Working Party 意见书 WP148 https://ec.europa.eu/justice/article-29/documentation/opinion-recommendation/files/2008/wp148_en.pdf 认定查询日志（query + 时间 + 来源标识）属个人数据；EFF 六条自保建议 https://w2.eff.org/Privacy/search/searchtips.pdf 的第一条是"别在搜索词里放 PII"——说明 query 天然可能携带 PII（人名、账号、地址）。本插件的取舍：历史只存 {query, time, resultCount, backendsOk/Total}（无 IP、无 cookie、无结果 URL）、环形 50 条自动滚动即短保留、本机存储不出网、提供 historyEnabled 开关与 POST clear 端点。**未做 query 脱敏**：脱敏会破坏"查看最近搜了什么"的核心用途，且本机单用户场景下该数据本就在 DSH 会话日志里存在；若未来历史跨设备同步，脱敏/加密是上线前置条件。
 
 ## License | 许可
 

package/cordis.patch.yml

@@ -1,3 +1,13 @@
+# Bundle patch layer:
+# 1. insert the plugin row (registers the unified search provider)
+# 2. wire the built-in web_search tool to the unified provider (the plugin's
+#    whole reason to exist — previously a manual cordis.patch.yml edit, now
+#    automatic; revert = remove this row or disable the plugin, the base
+#    default (deepseek-official) is one yaml line away).
 - insert:
     - id: dsh-websearch
       name: '@240xu/dsh-websearch'
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: unified

package/lib/backends/exa.js

@@ -13,6 +13,22 @@ import { WebError } from "@deepseek-ai/dsh-web";
 const EXA_ENDPOINT = "https://mcp.exa.ai/mcp";
 const EXA_TOOL = "web_search_exa";
 
+/**
+ * Infer an Exa data category from the query (v2.8.0). Only high-confidence
+ * patterns map — Exa rejects unknown categories with a 400, so this returns
+ * undefined unless a signal is explicit. Valid values per the Exa OpenAPI
+ * enum: github / "research paper" / news / pdf / company / people /
+ * "personal site" / "financial report".
+ */
+export function inferExaCategory(query) {
+  const q = typeof query === "string" ? query.toLowerCase() : "";
+  if (!q) return undefined;
+  if (/\bgithub\b|\brepo\b|repository|开源项目|源码/.test(q)) return "github";
+  if (/\barxiv\b|\bpaper\b|论文|研究文献|preprint/.test(q)) return "research paper";
+  if (/\bnews\b|新闻|最新消息|动态/.test(q)) return "news";
+  return undefined;
+}
+
 export const exaBackend = {
   id: "exa",
   requiresCredential: false,
@@ -26,6 +42,10 @@ export const exaBackend = {
       query: request.query,
       numResults: request.maxResults ?? 8,
     };
+    // v2.8.0: category inference (feature-detect — only sent when confident;
+    // if the endpoint rejects it the fan-out demotes softly).
+    const category = inferExaCategory(request.query);
+    if (category) args.category = category;
     hooks.recordRequest?.({
       endpoint: EXA_ENDPOINT,
       toolName: EXA_TOOL,

package/lib/backends/searxng.js

@@ -33,7 +33,9 @@ export const searxngBackend = {
     url.pathname = url.pathname.replace(/\/+$/,"") + "/search";
     url.searchParams.set("q", request.query);
     url.searchParams.set("format", "json");
-    url.searchParams.set("categories", "general");
+    // deepCoverage widens the category sweep (docs.searxng.org Search API:
+    // categories is a comma-separated list) — breadth over one category.
+    url.searchParams.set("categories", request.deepCoverage === true ? "general,news,it" : "general");
     // Language: settings/request filter wins, else historical "en" default.
     const filters = normalizeFilters(request.filters);
     url.searchParams.set("language", filters.lang ?? "en");

package/lib/backends/tavily.js

@@ -31,7 +31,12 @@ export const tavilyBackend = {
 
     const baseURL = backendOpts.baseURL ?? TAVILY_ENDPOINT;
     const maxResults = Math.min(request.maxResults ?? 8, 20);
-    const searchDepth = backendOpts.searchDepth ?? "basic";
+    // deepCoverage (provider sets request.deepCoverage) upgrades the depth:
+    // advanced = highest relevance, multiple snippets per URL (2 API credits).
+    // An explicit operator setting keeps precedence unless it was left basic.
+    const searchDepth = request.deepCoverage === true && backendOpts.searchDepth !== "advanced"
+      ? "advanced"
+      : (backendOpts.searchDepth ?? "basic");
 
     const body = {
       query: request.query,

package/lib/cache.js

@@ -33,13 +33,14 @@ export const CACHE_DEFAULTS = {
  * mix must never serve a stale result produced by a different combination
  * (arch-review P1-1). Pure function; exported for tests and host reuse.
  */
-export function cacheKeyFor({ query, filters, maxResults, backends }) {
+export function cacheKeyFor({ query, filters, maxResults, backends, mode }) {
   const backendSet = Array.isArray(backends) ? [...backends].sort().join(",") : "";
   const canonical = JSON.stringify({
     q: typeof query === "string" ? query : "",
     f: filters ?? {},
     n: Number(maxResults) || 0,
     b: backendSet,
+    m: typeof mode === "string" ? mode : "",
   });
   return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }

package/lib/history.js

@@ -115,13 +115,37 @@ export function isTrustedApiRequest(req) {
   }
 }
 
+/**
+ * Project the module-level backend health map into a small observability
+ * payload (v2.8.0 P2): per-backend last real success/failure, latency and
+ * breaker state — no error strings, no credentials, safe for the GUI.
+ */
+export function toBackendObservability(healthMap, nowMs = Date.now()) {
+  const out = [];
+  if (healthMap instanceof Map) {
+    for (const [id, e] of healthMap) {
+      out.push({
+        id,
+        ok: e?.ok === true,
+        ms: Number.isFinite(e?.ms) ? e.ms : null,
+        at: Number.isFinite(e?.at) ? e.at : null,
+        failCount: Number.isFinite(e?.failCount) ? e.failCount : 0,
+        cooled: Number.isFinite(e?.cooledUntil) && e.cooledUntil > nowMs,
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Register the read-only history routes on the (late-mounted) webServer.
- * GET  /api/websearch/history        -> { ok, entries }
+ * GET  /api/websearch/history        -> { ok, entries, backends }
+ *   backends: per-backend last real outcome/latency/breaker state (v2.8.0),
+ *   so fallback redundancy is observable without a separate endpoint.
  * POST /api/websearch/history/clear  -> { ok, cleared: true }
  * Both routes sit behind isTrustedApiRequest (loopback Host + same-site).
  */
-export function registerHistoryRoutes(ws, { getStore }) {
+export function registerHistoryRoutes(ws, { getStore, getBackendHealth }) {
   if (!ws || typeof ws.register !== "function") return;
   const send = (res, code, body) => {
     res.writeHead(code, { "content-type": "application/json" });
@@ -144,7 +168,11 @@ export function registerHistoryRoutes(ws, { getStore }) {
         return;
       }
       const store = getStore();
-      send(res, 200, { ok: true, entries: store ? store.list() : [] });
+      send(res, 200, {
+        ok: true,
+        entries: store ? store.list() : [],
+        backends: toBackendObservability(typeof getBackendHealth === "function" ? getBackendHealth() : getBackendHealth),
+      });
     }),
   });
   ws.register({

package/lib/index.js

@@ -169,6 +169,12 @@ export const Config = z.object({
   historyEnabled: z.boolean().default(true)
     .description("记录搜索历史【历史】：只追加，最多 50 条；可在设置 → 搜索 中查看与清空"),
 
+  // v2.8.0 查全查多
+  multiQueryEnabled: z.boolean().default(false)
+    .description("多查询融合【查全】：复杂查询（长度>60 或含 vs/and/比较/对比/和）自动派生 2-3 个子查询，各扇出后用 RRF(k=60) 融合；默认关"),
+  deepCoverage: z.boolean().default(false)
+    .description("深度覆盖【查全】：每后端请求条数上调 50% 再全局去重截断，牺牲带宽换覆盖面；Tavily 自动切 advanced 深度，SearXNG 扩展多类目；默认关"),
+
   // Enable toggles (one per backend)
   enableExa: z.boolean().default(true).description(DEFAULT_LABELS.exa),
   enableParallel: z.boolean().default(true).description(DEFAULT_LABELS.parallel),
@@ -183,30 +189,48 @@ export const Config = z.object({
   enableOpenai: z.boolean().default(false).description(DEFAULT_LABELS.openai),
 
   // Credential refs (env-var names; secrets live in the credentials service)
-  braveApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.brave),
-  tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.tavily),
-  serperApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.serper),
-  mojeekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.mojeek),
-  deepseekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.deepseek),
-  anthropicApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.anthropic),
-  openaiApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.openai),
+  braveApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.brave)
+    .description("Brave API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.tavily)
+    .description("Tavily API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  serperApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.serper)
+    .description("Serper API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  mojeekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.mojeek)
+    .description("Mojeek API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  deepseekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.deepseek)
+    .description("Deepseek API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  anthropicApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.anthropic)
+    .description("Anthropic API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  openaiApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.openai)
+    .description("Openai API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
   searxngApiKeyEnv: z.string().role("credential-ref").default("SEARXNG_API_KEY")
-    .description("SearXNG 私有实例的 API Key（公共实例留空）"),
+    .description("SearXNG 私有实例的 API Key 凭证引用（公共实例留空）"),
 
   // Base URLs (defaults from built-in registry)
-  braveBaseURL: z.string().default(DEFAULT_BASE_URLS.brave),
-  tavilyBaseURL: z.string().default(DEFAULT_BASE_URLS.tavily),
-  serperBaseURL: z.string().default(DEFAULT_BASE_URLS.serper),
-  mojeekBaseURL: z.string().default(DEFAULT_BASE_URLS.mojeek),
-  searxngBaseURL: z.string().default(DEFAULT_BASE_URLS.searxng),
-  deepseekBaseURL: z.string().default(DEFAULT_BASE_URLS.deepseek),
-  anthropicBaseURL: z.string().default(DEFAULT_BASE_URLS.anthropic),
-  openaiBaseURL: z.string().default(DEFAULT_BASE_URLS.openai),
+  braveBaseURL: z.string().default(DEFAULT_BASE_URLS.brave)
+    .description("Brave API 端点（默认官方；自托管/代理实例改此项）"),
+  tavilyBaseURL: z.string().default(DEFAULT_BASE_URLS.tavily)
+    .description("Tavily API 端点（默认官方；自托管/代理实例改此项）"),
+  serperBaseURL: z.string().default(DEFAULT_BASE_URLS.serper)
+    .description("Serper.dev API 端点（默认官方；自托管/代理实例改此项）"),
+  mojeekBaseURL: z.string().default(DEFAULT_BASE_URLS.mojeek)
+    .description("Mojeek API 端点（默认官方；自托管/代理实例改此项）"),
+  searxngBaseURL: z.string().default(DEFAULT_BASE_URLS.searxng)
+    .description("SearXNG API 端点（默认官方；自托管/代理实例改此项）"),
+  deepseekBaseURL: z.string().default(DEFAULT_BASE_URLS.deepseek)
+    .description("DeepSeek API 端点（默认官方；自托管/代理实例改此项）"),
+  anthropicBaseURL: z.string().default(DEFAULT_BASE_URLS.anthropic)
+    .description("Anthropic API 端点（默认官方；自托管/代理实例改此项）"),
+  openaiBaseURL: z.string().default(DEFAULT_BASE_URLS.openai)
+    .description("OpenAI API 端点（默认官方；自托管/代理实例改此项）"),
 
   // Models
-  deepseekModel: z.string().default(DEFAULT_MODELS.deepseek),
-  anthropicModel: z.string().default(DEFAULT_MODELS.anthropic),
-  openaiModel: z.string().default(DEFAULT_MODELS.openai),
+  deepseekModel: z.string().default(DEFAULT_MODELS.deepseek)
+    .description("DeepSeek 后端使用的模型名"),
+  anthropicModel: z.string().default(DEFAULT_MODELS.anthropic)
+    .description("Anthropic 后端使用的模型名"),
+  openaiModel: z.string().default(DEFAULT_MODELS.openai)
+    .description("OpenAI 后端使用的模型名"),
   tavilySearchDepth: z.union(["basic", "advanced"]).default("basic")
     .description("Tavily 搜索深度"),
 
@@ -215,6 +239,15 @@ export const Config = z.object({
     .description("显式启用后端列表（优先于上方开关；留空则用开关）"),
 });
 
+// 0.2.0 SettingsForms adapter (cross-settings-forms.md ruling): the 0.2.0
+// settings service auto-generates its form from entry.fiber.runtime.Config —
+// but volatileForm (RT dsh-settings lib/index.js:122-138) keeps ONLY fields
+// with meta.volatile; a Config without any yields an empty form. Marking the
+// top object makes the whole Config the form. Direct meta assignment (not
+// .volatile(), which returns a NEW schema and throws on re-wrap) is
+// equivalent and idempotent on both the 0.1.5 and 0.2.0 schemastery lines.
+Config.meta = { ...Config.meta, volatile: true };
+
 /**
  * Per-field user-language labels (fe-ui W1 remainder): the settings renderer
  * falls back to camelCase keys when no label is present, so attach one to
@@ -326,6 +359,9 @@ export function resolveOptions(ctx, config) {
       ? Math.max(0, Math.floor(Number(config?.breakerCooldownMs) || 0))  // 0 = disabled
       : BREAKER_DEFAULTS.cooldownMs,
     historyEnabled: config?.historyEnabled !== false,
+    // v2.8.0 coverage / multiQuery
+    multiQueryEnabled: config?.multiQueryEnabled === true,
+    deepCoverage: config?.deepCoverage === true,
     filters: {
       recency: typeof config?.recency === "string" && config.recency !== "any" ? config.recency : undefined,
       lang: language.length > 0 ? language : undefined,
@@ -359,6 +395,7 @@ export function apply(ctx, config) {
   ctx.inject(["settings"], (settingsCtx) => {
     const settings = settingsCtx.settings;
     if (typeof settings?.installSection === "function") {
+      // 0.1.5 SettingsProvider line: explicit section install (unchanged).
       settings.installSection(ctx, NAMESPACE, Config, config, {
         setSource: (source) => {
           current = source;
@@ -367,15 +404,10 @@ export function apply(ctx, config) {
       });
       return;
     }
-    // DSH 0.1.7+: the settings service is SettingsForms and has no
-    // installSection. The Config schema still resolves through cordis config
-    // (this file reads `current()`), so search keeps working; surface the gap
-    // once instead of silently swallowing it (compat-audit P1).
-    console.warn(
-      "[dsh-websearch] settings service has no installSection (DSH >= 0.1.7 SettingsForms line); " +
-      "the Settings panel section is not installed. Configure the unified-search namespace via cordis config " +
-      "or the client settings card; migration to the SettingsForms API is tracked for a future release.",
-    );
+    // 0.2.0 SettingsForms line: no installSection; the settings form is
+    // auto-generated from the volatile-marked Config above — no action and no
+    // warning here (the form IS the section; a warning would contradict the
+    // visible UI). Config values still resolve via cordis config.
   });
 
   // v2.7.0 stores: disk cache + append-only search history, both under
@@ -423,6 +455,10 @@ export function apply(ctx, config) {
       getBackendHealth: getLatestBackendHealth,
     });
     // v2.7.0 search history: read-only GET + explicit clear POST.
-    registerHistoryRoutes(webCtx.webServer, { getStore: () => historyStore });
+    // v2.8.0: GET also carries per-backend last-outcome observability.
+    registerHistoryRoutes(webCtx.webServer, {
+      getStore: () => historyStore,
+      getBackendHealth: getLatestBackendHealth,
+    });
   });
 }

package/lib/multiquery.js

@@ -0,0 +1,48 @@
+// multiquery.js — v2.8.0 query-variant derivation (pure functions, zero deps).
+//
+// Gated multi-query: arXiv:2404.01037 (Wang et al.) shows BLIND multi-query
+// can degrade retrieval — so variants are only derived for queries that look
+// genuinely multi-faceted, and the original query always participates in the
+// fusion with full weight. Splitting is purely mechanical (at separator
+// words/punctuation); entity text is never rewritten.
+//
+// Separators per the v2.8 spec: "vs", "and", 比较, 对比, 和 — plus sentence
+// punctuation for the long-query case.
+
+const SEPARATOR_SPLIT_RE = /\s+(?:vs\.?|and)\s+|\s*(?:比较|对比|和)\s*|\s*[、；;。！？!?|]+\s*/i;
+const COMPLEX_MARK_RE = /(?:\bvs\.?\b|\band\b|比较|对比|和)/i;
+
+/** Sub-query hard cap (original + 2 variants max). */
+export const MAX_SUB_QUERIES = 3;
+
+/**
+ * Heuristic gate: does this query look multi-faceted enough to justify
+ * multi-query fan-out? Long queries (>60 chars) or queries containing a
+ * separator word qualify. Returns false for anything else — blind
+ * multi-query degrades (arXiv:2404.01037), so the default is NO.
+ */
+export function isComplexQuery(query) {
+  if (typeof query !== "string") return false;
+  const q = query.trim();
+  if (q.length === 0) return false;
+  if (q.length > 60) return true;
+  return COMPLEX_MARK_RE.test(q);
+}
+
+/**
+ * Derive 2-3 sub-query variants from a complex query: the original query
+ * (always first, full weight in fusion) plus up to two mechanical splits at
+ * separator boundaries. Never rewrites entity text; returns [query] when no
+ * usable split exists.
+ */
+export function deriveSubQueries(query) {
+  const base = typeof query === "string" ? query.trim() : "";
+  if (base.length === 0) return [];
+  const parts = base
+    .split(SEPARATOR_SPLIT_RE)
+    .map((p) => p.trim())
+    .filter((p) => p.length >= 2);
+  if (parts.length < 2) return [base];
+  const variants = [base, parts[0], parts.slice(1).join(" ")];
+  return [...new Set(variants.map((v) => v.trim()).filter(Boolean))].slice(0, MAX_SUB_QUERIES);
+}

package/lib/provider.js

@@ -25,9 +25,27 @@ import { normalizeFilters } from "./util/filters.js";
 import { shapeQuery, resultHeader, TELEMETRY_TAG } from "./prompting.js";
 import { cacheKeyFor } from "./cache.js";
 import { foldBreaker, isCooled, cooledAnnotation } from "./breaker.js";
+import { rrfFuse } from "./rrf.js";
+import { isComplexQuery, deriveSubQueries } from "./multiquery.js";
 
 const PROVIDER_ID = "unified";
 
+// Per-backend timeout ceilings (v2.8.0, P2): ddg/scrapes and self-hosted
+// SearXNG instances are the slowest to fail when unreachable — a 30s global
+// default lets one dead backend stall the whole fan-out tail. The effective
+// timeout is min(override, backendTimeoutMs), so an operator's shorter global
+// timeout always wins.
+const BACKEND_TIMEOUT_OVERRIDES_MS = {
+  ddg: 5000,
+  searxng: 5000,
+};
+
+/** Effective per-backend timeout = min(override ?? ∞, global). Exported for tests. */
+export function effectiveBackendTimeoutMs(id, backendTimeoutMs) {
+  const override = BACKEND_TIMEOUT_OVERRIDES_MS[id];
+  return Number.isFinite(override) ? Math.min(override, backendTimeoutMs) : backendTimeoutMs;
+}
+
 // Module-level per-backend health telemetry (id -> entry), updated on every
 // backend completion during a real search. Purely passive: nothing writes here
 // outside search(), so the read-only /api/unified-search/health route can
@@ -177,14 +195,25 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
       const concurrency = opts.concurrency ?? 6;
       const backendTimeoutMs = opts.backendTimeoutMs ?? 30000;
 
-      // v2.7.0 disk cache: keyed on (shaped query + filters + maxResults).
-      // A hit short-circuits the fan-out entirely; sources are byte-identical
-      // to the first search and content carries a "cache hit, age Ns" note.
-      // Cache failures never break the search (cache API never throws).
+      // v2.8.0 coverage / multiQuery gates (both default OFF; arXiv:2404.01037
+      // warns blind multi-query degrades, so the gate is deliberately strict).
+      const coverage = opts.deepCoverage === true;
+      // Per-backend widening: fetch more per backend, dedupe down afterwards.
+      const backendMaxResults = coverage ? Math.ceil(maxResults * 1.5) : maxResults;
+      const multi = opts.multiQueryEnabled === true && isComplexQuery(effReq.query);
+      const variants = multi ? deriveSubQueries(effReq.query) : [effReq.query];
+      // Cache-key mode marker: different coverage/multiQuery settings must not
+      // serve each other's cached results.
+      const cacheMode = (multi ? "multi" : "single") + (coverage ? "+coverage" : "");
+
+      // v2.7.0 disk cache: keyed on (shaped query + filters + maxResults +
+      // backends + mode). A hit short-circuits the fan-out entirely; sources
+      // are byte-identical to the first search and content carries a
+      // "cache hit, age Ns" note. Cache failures never break the search.
       const cacheEnabled = opts.cacheEnabled === true && cache;
       let cacheKey = null;
       if (cacheEnabled) {
-        cacheKey = cacheKeyFor({ query: effReq.query, filters, maxResults, backends: opts.enabledBackends });
+        cacheKey = cacheKeyFor({ query: effReq.query, filters, maxResults, backends: opts.enabledBackends, mode: cacheMode });
         const hit = cache.get(cacheKey);
         if (hit && Array.isArray(hit.value?.sources) && hit.value.sources.length > 0) {
           // Defense in depth: the fresh path drops non-http(s) schemes before
@@ -219,7 +248,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
       // backend inside its 60s cooldown window is skipped (annotated in
       // telemetry as "id ⏸cooled"). Fail-open: if EVERY candidate is cooled,
       // run them all anyway — the breaker must never make search worse than
-      // no breaker.
+      // no breaker. The pick is shared by every query variant.
       const breakerCfg = opts.breakerEnabled === false ? null : {
         threshold: opts.breakerThreshold,
         cooldownMs: opts.breakerCooldownMs,
@@ -255,98 +284,109 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
         );
       }
 
-      // Settings-level default filters, overridden by per-request filters
-      // (normalizeFilters drops unknown/invalid values so typos degrade to
-      // "no filter" instead of breaking the search).
-
-      const telemetry = [];
-      // Concurrency limiter
-      const limit = createLimiter(concurrency);
-
-      // Run one backend under the per-backend timeout. The internal timer's
-      // controller is merged into the caller's signal; when the INTERNAL timer
-      // fired (caller did not abort), a backend abort-shaped failure is
-      // reclassified as WEB_PROVIDER_ERROR so timeouts surface as real
-      // failures instead of being silently demoted like user cancellations.
-      const runBackend = ({ id, backend, beOpts, hooks }) => {
-        const startedAtMs = Date.now();
-        // Trust boundary: baseURL is operator-configurable and API keys are sent to it.
-        // Enforce http(s); plain http only for private hosts (self-hosted SearXNG).
-        // Reject embedded credentials. Failure is a per-backend soft error.
-        if (beOpts.baseURL !== undefined) {
-          let bu = null;
-          try { bu = new URL(beOpts.baseURL); } catch { bu = null; }
-          const privHost = bu ? /^(localhost|127(\.\d{1,3}){3}|10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){3}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){3})$/.test(bu.hostname) : false;
-          const schemeOk = bu && (bu.protocol === "https:" || (bu.protocol === "http:" && privHost));
-          if (!schemeOk || bu.username || bu.password) {
-            throw new WebError(`backend "${id}" has an invalid baseURL: https required (plain http only for private hosts), credentials-in-URL rejected`, "WEB_PROVIDER_ERROR");
+      // Run ONE query variant through the full fan-out: breaker-aware backend
+      // execution under the per-variant limiter, then PHASE 1 collect. The
+      // internal abort/timeout semantics are unchanged from v2.7.
+      const fanoutVariant = async (variantReq) => {
+        const telemetry = [];
+        const limit = createLimiter(concurrency);
+        const runBackend = ({ id, backend, beOpts, hooks }) => {
+          const startedAtMs = Date.now();
+          // Trust boundary: baseURL is operator-configurable and API keys are sent to it.
+          // Enforce http(s); plain http only for private hosts (self-hosted SearXNG).
+          // Reject embedded credentials. Failure is a per-backend soft error.
+          if (beOpts.baseURL !== undefined) {
+            let bu = null;
+            try { bu = new URL(beOpts.baseURL); } catch { bu = null; }
+            const privHost = bu ? /^(localhost|127(\.\d{1,3}){3}|10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){3}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){3})$/.test(bu.hostname) : false;
+            const schemeOk = bu && (bu.protocol === "https:" || (bu.protocol === "http:" && privHost));
+            if (!schemeOk || bu.username || bu.password) {
+              throw new WebError(`backend "${id}" has an invalid baseURL: https required (plain http only for private hosts), credentials-in-URL rejected`, "WEB_PROVIDER_ERROR");
+            }
           }
-        }
-        const controller = new AbortController();
-        const mergedSignal = signal
-          ? AbortSignal.any([signal, controller.signal])
-          : controller.signal;
-        const timeoutId = setTimeout(() => controller.abort(), backendTimeoutMs);
-        return backend
-          .search(effReq, mergedSignal, beOpts, hooks)
-          .then(
-            (value) => {
-              telemetry.push({ id, ok: true, ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 });
-              recordBackendHealth(id, { ok: true, at: Date.now(), ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 }, breakerCfg);
-              return value;
-            },
-            (err) => {
-              const msg = String(err instanceof Error ? err.message : err).slice(0, 80);
-              telemetry.push({ id, ok: false, ms: Date.now() - startedAtMs, error: msg });
-              recordBackendHealth(id, { ok: false, at: Date.now(), ms: Date.now() - startedAtMs, error: msg }, breakerCfg);
+          const controller = new AbortController();
+          const mergedSignal = signal
+            ? AbortSignal.any([signal, controller.signal])
+            : controller.signal;
+          const effectiveTimeoutMs = effectiveBackendTimeoutMs(id, backendTimeoutMs);
+          const timeoutId = setTimeout(() => controller.abort(), effectiveTimeoutMs);
+          return backend
+            .search(variantReq, mergedSignal, beOpts, hooks)
+            .then(
+              (value) => {
+                telemetry.push({ id, ok: true, ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 });
+                recordBackendHealth(id, { ok: true, at: Date.now(), ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 }, breakerCfg);
+                return value;
+              },
+              (err) => {
+                const msg = String(err instanceof Error ? err.message : err).slice(0, 80);
+                telemetry.push({ id, ok: false, ms: Date.now() - startedAtMs, error: msg });
+                recordBackendHealth(id, { ok: false, at: Date.now(), ms: Date.now() - startedAtMs, error: msg }, breakerCfg);
+                throw err;
+              },
+            )
+            .catch((err) => {
+              if (controller.signal.aborted && !(signal && signal.aborted)) {
+                throw new WebError(
+                  `backend "${id}" timed out after ${effectiveTimeoutMs}ms`,
+                  "WEB_PROVIDER_ERROR",
+                  { cause: err instanceof Error ? err : undefined },
+                );
+              }
               throw err;
-            },
-          )
-          .catch((err) => {
-            if (controller.signal.aborted && !(signal && signal.aborted)) {
-              throw new WebError(
-                `backend "${id}" timed out after ${backendTimeoutMs}ms`,
-                "WEB_PROVIDER_ERROR",
-                { cause: err instanceof Error ? err : undefined },
-              );
-            }
-            throw err;
-          })
-          .finally(() => clearTimeout(timeoutId));
-      };
-
-      const results = await Promise.allSettled(
-        eligible.map(({ id, backend, beOpts }) => {
-          const hooks = {
-            recordRequest: (req) => recordBackendRequest(ctx, id, req),
-            recordOutcome: (out) => recordBackendOutcome(ctx, id, out),
-          };
-          return limit(() => runBackend({ id, backend, beOpts, hooks }));
-        }),
-      );
-
-      throwIfSearchAborted(signal);
+            })
+            .finally(() => clearTimeout(timeoutId));
+        };
 
-      // PHASE 1 collect: fold the settled fan-out into raw sources (fan-out
-      // priority order), first backend content, and per-backend failures.
-      const { collected, mergedContent, hardAborted, hardError, failures } =
-        collectFanoutResults(results, eligible, signal);
+        const results = await Promise.allSettled(
+          eligible.map(({ id, backend, beOpts }) => {
+            const hooks = {
+              recordRequest: (req) => recordBackendRequest(ctx, id, req),
+              recordOutcome: (out) => recordBackendOutcome(ctx, id, out),
+            };
+            return limit(() => runBackend({ id, backend, beOpts, hooks }));
+          }),
+        );
+        throwIfSearchAborted(signal);
+        const fold = collectFanoutResults(results, eligible, signal);
+        return { ...fold, telemetry };
+      };
 
-      // Caller-cancellation check (hard abort fires before we yield results).
-      if (signal?.aborted === true || hardAborted) {
-        throw searchAborted(signal);
+      // Fan out per variant (sequential — the limiter already parallelizes
+      // backends within a variant), dedupe/rank each list, then fuse.
+      const perVariant = [];
+      const allTelemetry = [];
+      const allFailures = [];
+      let hardError = null;
+      for (const variantQuery of variants) {
+        const variantReq = {
+          ...effReq,
+          query: variantQuery,
+          maxResults: backendMaxResults,
+          ...(coverage ? { deepCoverage: true } : {}),
+        };
+        const fold = await fanoutVariant(variantReq);
+        allTelemetry.push(...fold.telemetry);
+        allFailures.push(...fold.failures);
+        if (fold.hardError !== null && hardError === null) hardError = fold.hardError;
+        // Caller-cancellation check (hard abort fires before we yield results).
+        if (signal?.aborted === true || fold.hardAborted) {
+          throw searchAborted(signal);
+        }
+        // PHASE 2 dedupe / PHASE 3 rerank (per variant list, pre-fusion).
+        const strategy = opts.dedupStrategy === "url+title" ? "url+title" : "url";
+        const deduped = dedupeSources(fold.collected, strategy);
+        const ordered = opts.rerank === true ? rerankSources(deduped, variantQuery) : deduped;
+        perVariant.push({ query: variantQuery, ordered, mergedContent: fold.mergedContent });
       }
 
-      // PHASE 2 dedupe / PHASE 3 rerank: "url" preserves the historical
-      // URL-key behavior; "url+title"
-      // additionally collapses same-story syndicated copies across backends.
-      const strategy = opts.dedupStrategy === "url+title" ? "url+title" : "url";
-      const deduped = dedupeSources(collected, strategy);
-      // Optional deterministic relevance rerank (stable ties keep fan-out order).
-      const ordered =
-        opts.rerank === true
-          ? rerankSources(deduped, typeof request?.query === "string" ? request.query : "")
-          : deduped;
+      // PHASE 4 fuse: multi-query mode fuses the per-variant ranked lists with
+      // RRF (k=60); single-query mode keeps the historical behavior (the one
+      // list, unchanged ordering).
+      const orderedLists = perVariant.filter((v) => v.ordered.length > 0).map((v) => v.ordered);
+      const ordered = multi
+        ? rrfFuse(orderedLists).fused
+        : (orderedLists[0] ?? []);
 
       // If we got ANY sources, return them even if some backends failed.
       if (ordered.length > 0) {
@@ -355,7 +395,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
         // 置于结果块最前，要求逐条引用来源 URL、优先官方/一手与较新来源；
         // 语言按查询文本自动选择（含 CJK 用中文头）。可用
         // opts.resultHeader === false 关闭。
-        let outContent = mergedContent;
+        let outContent = perVariant.find((v) => v.mergedContent !== undefined)?.mergedContent;
         if (opts.resultHeader !== false && (sources.length > 0 || outContent !== undefined)) {
           const header = resultHeader(typeof request?.query === "string" && /[\u4e00-\u9fff]/.test(request.query) ? "zh" : "en");
           outContent = outContent === undefined ? header : header + "\n\n" + outContent;
@@ -369,18 +409,22 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
           query: request?.query,
           time: Date.now(),
           resultCount: sources.length,
-          backendsOk: telemetry.filter((t) => t.ok).length,
-          backendsTotal: telemetry.length,
+          backendsOk: allTelemetry.filter((t) => t.ok).length,
+          backendsTotal: allTelemetry.length,
         });
-        if (opts.resultTelemetry !== false && (telemetry.length > 0 || cooled.size > 0)) {
+        if (opts.resultTelemetry !== false && (allTelemetry.length > 0 || cooled.size > 0)) {
           const cooledParts = [];
           for (const [cid, centry] of cooled) {
             const ann = cooledAnnotation(centry, Date.now()) || "⏸cooled";
             cooledParts.push(cid + " " + ann);
           }
-          const parts = telemetry
+          // Multi-query fans every variant through every backend; cap the line
+          // so the telemetry note cannot dwarf the results themselves.
+          const parts = allTelemetry
+            .slice(0, 12)
             .map((t) => t.id + (t.ok ? " ✓" : " ✗") + t.ms + "ms" + (t.ok ? "/" + t.count : (t.error ? " (" + String(t.error).slice(0, 40) + ")" : "")))
             .concat(cooledParts);
+          if (allTelemetry.length > 12) parts.push(`… +${allTelemetry.length - 12}`);
           const line = "[websearch backends]" + TELEMETRY_TAG + " " + parts.join(" · ");
           outContent = outContent === undefined ? line : outContent + "\n\n" + line;
         }
@@ -393,17 +437,17 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
 
       // All enabled backends failed - synthesize one meaningful error that
       // names each backend's own reason so the caller (model or user) can act.
-      const detail = failures.slice(0, 4)
+      const detail = allFailures.slice(0, 4)
         .map((f) => f.id + ": " + String(f.err instanceof Error ? f.err.message : f.err).slice(0, 120))
         .join("; ");
       const allKeyMissing =
-        failures.length > 0 &&
-        failures.every((f) => f.err instanceof WebError && (f.err.code === "WEB_PROVIDER_UNAVAILABLE" || f.err.code === "WEB_PROVIDER_CREDENTIAL_MISSING"));
+        allFailures.length > 0 &&
+        allFailures.every((f) => f.err instanceof WebError && (f.err.code === "WEB_PROVIDER_UNAVAILABLE" || f.err.code === "WEB_PROVIDER_CREDENTIAL_MISSING"));
       const hint = allKeyMissing
         ? " (every enabled backend is missing its API key - add keys in Settings > Web Search, or enable a keyless backend)"
         : "";
       throw new WebError(
-        `unified search: all enabled backends failed (${failures.length}) - ${detail}` + hint,
+        `unified search: all enabled backends failed (${allFailures.length}) - ${detail}` + hint,
         "WEB_PROVIDER_ERROR",
         { cause: hardError ?? undefined },
       );

package/lib/rrf.js

@@ -0,0 +1,56 @@
+// rrf.js — v2.8.0 Reciprocal Rank Fusion (pure functions, zero deps).
+//
+// RRF merges multiple ranked result lists into one: each list contributes
+// score 1/(k + rank) to every item it contains (k=60 is the canonical value
+// from Cormack et al. 2009, popularized by RAG-Fusion
+// https://github.com/Raudaschl/rag-fusion). Items are deduped by URL; the
+// first-seen entry wins for metadata, scores accumulate across lists.
+//
+// Why RRF over naive concatenation: it needs no score calibration across
+// backends/queries (only ranks), and demotes one-off hits while promoting
+// items that appear in several lists.
+
+/** Canonical RRF constant. */
+export const RRF_K = 60;
+
+/** Stable key for dedupe (URL string; missing/odd URLs fall back to title). */
+function itemKey(item) {
+  if (item && typeof item.url === "string" && item.url.length > 0) return item.url;
+  if (item && typeof item.title === "string") return `t:${item.title}`;
+  return "";
+}
+
+/**
+ * Fuse ranked lists of search sources with Reciprocal Rank Fusion.
+ *
+ * @param {Array<Array<object>>} lists  each list is already ranked best-first
+ * @param {{k?: number}} [opts]         k constant (default 60)
+ * @returns {{ fused: object[], scores: Map<string, number> }}
+ *   fused: sources sorted by accumulated RRF score desc (ties keep first
+ *   appearance order); sources without a usable key are dropped.
+ */
+export function rrfFuse(lists, { k = RRF_K } = {}) {
+  const kk = Number(k) > 0 ? Number(k) : RRF_K;
+  const scores = new Map(); // key -> accumulated score
+  const firstSeen = new Map(); // key -> source object (first metadata wins)
+  const order = []; // keys in first-appearance order (stable ties)
+
+  for (const list of Array.isArray(lists) ? lists : []) {
+    if (!Array.isArray(list)) continue;
+    for (let rank = 0; rank < list.length; rank++) {
+      const item = list[rank];
+      const key = itemKey(item);
+      if (!key) continue;
+      scores.set(key, (scores.get(key) ?? 0) + 1 / (kk + rank));
+      if (!firstSeen.has(key)) {
+        firstSeen.set(key, item);
+        order.push(key);
+      }
+    }
+  }
+
+  const fused = [...order]
+    .sort((a, b) => (scores.get(b) ?? 0) - (scores.get(a) ?? 0))
+    .map((key) => firstSeen.get(key));
+  return { fused, scores };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@240xu/dsh-websearch",
-  "version": "2.7.3",
+  "version": "2.8.1",
   "description": "Unified web search provider for DeepSeek Harness (ctx.web): 11 backends — Exa + Parallel + DDG + SearXNG (keyless), DeepSeek + Anthropic + OpenAI + Brave + Tavily + Serper + Mojeek (key-gated via Settings credentials). Registers provider id \"unified\" for zero-config web_search. 统一网页搜索聚合：11 后端并发扇出、去重合并，零依赖。See CHANGELOG.md for version history.",
   "type": "module",
   "main": "lib/index.js",