@240xu/dsh-websearch 2.3.0 → 2.7.2

package/README.md

@@ -29,7 +29,7 @@ DSH（[DeepSeek Harness](https://github.com/deepseek-ai/dsh)）原生插件：
 | `anthropic` | `ANTHROPIC_API_KEY` | `https://api.anthropic.com/v1/messages` | Anthropic Messages + `web_search_20250305`, model `claude-sonnet-4-6` | Claude Code 同机制 |
 | `openai` | `OPENAI_API_KEY` | `https://api.openai.com/v1/responses` | Responses API native `web_search` tool, parse `url_citation` annotations | Codex 同机制 |
 
-**Default enabled set**: `["exa", "parallel", "ddg", "searxng"]` — all keyless. The key-gated backends only join when their `available()` returns true (key present + baseURL reachable).
+> 可用性说明：available() 只做本地配置检查（不联网探测可达性）；密钥在每次搜索时按操作解析，缺失时该后端以明确错误码软失败（不阻塞其他后端）。全部缺 Key 时错误会指向设置页。
 
 ### SearXNG 实例 | Public instances
 
@@ -115,6 +115,45 @@ pnpm install
 
 环境变量兜底：未在 credentials 配置时回退读同名环境变量；`DSH_UNIFIED_SEARCH_BACKENDS` 可逗号分隔强制指定启用集合。
 
+## v2.7.2 补丁 | What's new in v2.7.2
+
+- 设置项 label：6 个新设置项在 schema 层挂用户语言 label（含单位尾注，如「缓存有效期（秒）」），宿主渲染不再回退 camelCase 键名；description 同步以人话名称开头（真机渲染行为归视觉待办 V5）。
+
+## v2.7.1 评审修复 | What's new in v2.7.1
+
+- **缓存 key 加入 enabledBackends 选择集**（arch-review P1-1）：切换后端组合后立即拿到与新配置一致的结果，不再吃旧组合缓存。
+- **缓存命中路径复用 URL scheme 白名单**（纵深防御）：被篡改的缓存文件里的 javascript:/data: 条目在命中时同样被过滤。
+- **history 并发写串行化**：record() 经进程内 promise 链串行，杜绝并发搜索完成时的丢失更新；单条写入仍为 tmp+rename 原子替换。
+- **history 路由信任围栏**：两条 /api/websearch/* 路由要求回环 Host（防 DNS rebinding）+ same-site 浏览器上下文（防跨站 text/plain CSRF）；无头客户端（curl）放行只读 GET。
+- **熔断冷却时长支持 0**：`breakerCooldownMs=0` 显式关闭冷却（此前静默回退 60s）。
+- **设置文案**：6 个新设置项改用户语言并按【缓存】/【熔断】/【历史】分组，单位（秒/毫秒）写入说明。
+- **互操作**：新增 window 事件 `dsh-websearch:open-settings`（devkit 命令联动）；收到时经 devkit toast 提示设置路径（宿主无分区跳转 API）。
+
+## v2.7.0 新增 | What's new in v2.7.0
+
+三大增量功能，全部经设置开关控制、默认为保守值，且不改变既有结果语义（v2.6.0 提示词原样保留）：
+
+### 1. 搜索结果磁盘缓存（默认开）
+
+- 相同 **(整形后查询 + filters + maxResults + 启用后端集合)** 在 TTL 内直接命中缓存，不打任何后端；`sources` 与首次搜索完全一致。
+- 命中时 `content` 追加一行 `[websearch cache] cache hit, age Ns`。
+- 存储位置：`$DSH_HOME/cache/websearch/results/`，单条目一个 JSON 文件，tmp+rename 原子写，超出上限按最旧淘汰；任何 fs 错误都被吞掉，缓存坏了绝不影响搜索。
+- 设置：`cacheEnabled`（默认 true）、`cacheTtl`（秒，默认 900）。
+
+### 2. 后端熔断器（默认开，保守阈值）
+
+- 同一后端**连续失败 3 次**进入 **60s 冷却**；冷却期内 eligible 选择直接跳过该后端，遥测行标注 `id ⏸cooled Ns`。
+- 状态与 `recordBackendHealth` 共用（健康条目新增 `failCount` / `cooledUntil` 字段），任意一次成功立即复位。
+- **Fail-open 兜底**：若所有候选后端都处于冷却期，则全部放行照常扇出——熔断器永远只会让搜索更快，不会让它更差。
+- 设置：`breakerEnabled`（默认 true）、`breakerThreshold`（默认 3）、`breakerCooldownMs`（默认 60000）。
+
+### 3. 搜索历史 API（默认开，只追加 / 只读暴露）
+
+- 每次搜索（含缓存命中）追加一条记录，环形上限 50 条，新在前；文件 `$DSH_HOME/cache/websearch/history.json`，写前原子替换。
+- `GET /api/websearch/history` → `{ ok, entries: [{ query, time, resultCount, backendsOk, backendsTotal }] }`（只读，无凭证、无 URL）。
+- `POST /api/websearch/history/clear` → `{ ok, cleared: true }` 显式清空。
+- 设置：`historyEnabled`（默认 true）。
+
 ## Design | 设计
 
 - **One provider, no ambiguity**: a single `registeredSearchProvider({id:"unified"})` — the `dsh-web` seam's selection rule picks it unambiguously, and `search()` caps `maxResults` itself.
@@ -125,7 +164,7 @@ pnpm install
 - **Honest timeouts**: each backend runs under an internal abort controller merged into the caller signal; when only the internal timer fires, the failure is reclassified as WEB_PROVIDER_ERROR ("backend <id> timed out") instead of being masked as a user cancellation.
 - **Concurrency & Timeout Control**: `concurrency` (default 6) limits simultaneous calls; `backendTimeoutMs` (default 30s) caps each backend.
 - **Streamable-http MCP, custom handshake**: `lib/util/mcp-client.js` implements `initialize → notifications/initialized → tools/call` with `Mcp-Session-Id` header caching against Exa and Parallel — no dependency on the full MCP SDK.
-- **hooks.recordRequest/recordOutcome bridge**: each backend routes its request/outcome to `lib/util/log.js` which records `web/unified-search-backend-request` / `…backend-outcome` events onto the active DSH session via `ctx.get("agents")?.currentInitiator()?.session.append(...)` (mirrors `dsh-web-search-deepseek`).
+- **Host-logger diagnostics**: each backend routes request/outcome through lib/util/log.js to the host logger (ctx.logger), best-effort and never thrown - deliberately NOT session events: the session event vocabulary is a closed set third-party plugins must not extend (an unknown envelope type makes the whole session log unreadable).
 
 ## Architecture | 架构
 
@@ -157,10 +196,19 @@ tests/
 ## Test | 测试
 
 ```bash
-node --test tests/parse.test.js tests/provider.test.js
+node --test tests/
 ```
 
-33/33 pass.
+v2.7.0 起共 76+ tests pass（`node --test "tests/*.test.js" "test/*.test.mjs"`）。
+
+## 权威依据与取舍 | Authoritative sources & design trade-offs
+
+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 会话日志里存在；若未来历史跨设备同步，脱敏/加密是上线前置条件。
 
 ## License | 许可
 

package/lib/backends/anthropic-like.js

@@ -19,7 +19,7 @@ import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort
 import { WebError } from "@deepseek-ai/dsh-web";
 
 /** Attribution header; bumped with the package version. */
-const UA = "dsh-websearch/2.1";
+const UA = "dsh-websearch/2.3";
 
 /**
  * Factory: create an Anthropic-like Messages backend.
@@ -30,7 +30,6 @@ const UA = "dsh-websearch/2.1";
  * @param {string} spec.defaultModel
  * @param {string} spec.defaultApiVersion   e.g. "2023-06-01"
  * @param {string} spec.toolName            "web_search_20250305"
- * @param {string} [spec.futureToolName]    optional newer tool for dual fallback
  * @returns {object} backend object { id, requiresCredential, available, search }
  */
 export function createAnthropicLikeBackend(spec) {
@@ -40,7 +39,6 @@ export function createAnthropicLikeBackend(spec) {
     defaultModel,
     defaultApiVersion,
     toolName,
-    futureToolName,
   } = spec;
 
   return {
@@ -154,7 +152,7 @@ export function createAnthropicLikeBackend(spec) {
       }
 
       try {
-        const result = mapAnthropicResponse(await response.json(), id, futureToolName);
+        const result = mapAnthropicResponse(await response.json(), id);
         hooks.recordOutcome?.({ status: "ok", sources: result.sources.length });
         return { sources: result.sources, content: undefined, truncated: false };
       } catch (err) {
@@ -174,15 +172,7 @@ export function createAnthropicLikeBackend(spec) {
   };
 }
 
-/**
- * Optional dual-tool fallback: try the newer tool first; if that tool name is
- * rejected by the API (HTTP error mapping is upstream of us), the provider
- * retries with the established fallback. Here we just expose both — the
- * provider loops through candidates and uses whichever result block appears.
- */
-export function tryDualToolResponse(response, id, primaryTool, fallbackTool) {
-  return mapAnthropicResponse(response, id, primaryTool);
-}
+
 
 /**
  * Walk web_search_tool_result blocks for citeable web_search_result items,

package/lib/backends/brave.js

@@ -51,8 +51,10 @@ export const braveBackend = {
         headers: {
           "X-Subscription-Token": apiKey,
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -61,7 +63,7 @@ export const braveBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: `HTTP ${response.status}: ${text}` });
       throw new WebError(`Brave Search API error (HTTP ${response.status}): ${text}`, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/ddg.js

@@ -40,7 +40,7 @@ export const ddgBackend = {
         headers: {
           "Content-Type": "application/x-www-form-urlencoded",
           "Accept": "text/html",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body,
         ...(signal !== undefined ? { signal } : {}),

package/lib/backends/exa.js

@@ -7,7 +7,7 @@
 // .../Highlights: .../  ..." separated by "\n\n---\n\n"; we split into source objects.
 // Exa is keyless — its public MCP endpoint requires no API key.
 
-import { mcpCall, invalidateSession } from "../util/mcp-client.js";
+import { mcpCall } from "../util/mcp-client.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
 const EXA_ENDPOINT = "https://mcp.exa.ai/mcp";

package/lib/backends/mojeek.js

@@ -41,7 +41,7 @@ export const mojeekBackend = {
     const headers = {
       "Accept": "application/json",
       "Authorization": "Bearer " + apiKey,
-      "User-Agent": "dsh-websearch/2.1",
+      "User-Agent": "dsh-websearch/2.3",
     };
 
     hooks?.recordRequest?.({
@@ -55,6 +55,8 @@ export const mojeekBackend = {
       response = await fetch(url, {
         method: "GET",
         headers,
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -63,7 +65,7 @@ export const mojeekBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
       throw new WebError("Mojeek API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/openai.js

@@ -13,7 +13,7 @@
 import { throwIfSearchAborted, searchAborted, isAbortError } from "../util/abort.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
-const UA = "dsh-websearch/2.1";
+const UA = "dsh-websearch/2.3";
 
 export const openaiBackend = {
   id: "openai",
@@ -47,7 +47,7 @@ export const openaiBackend = {
       );
     }
     const baseURL = (options.baseURL || "https://api.openai.com/v1").replace(/\/$/, "");
-    const model = options.model || "gpt-5";
+    const model = options.model || "gpt-4o";
     const endpoint = `${baseURL}/responses`;
 
     const body = {

package/lib/backends/parallel.js

@@ -13,18 +13,15 @@
 // JSON-string with { search_id, results: [{ url, title, publish_date, excerpts:[] }] }.
 // Parallel is keyless — its public MCP endpoint requires no API key.
 
-import { mcpCall, invalidateSession } from "../util/mcp-client.js";
+import { randomUUID } from "node:crypto";
+import { mcpCall } from "../util/mcp-client.js";
 import { WebError } from "@deepseek-ai/dsh-web";
 
 const PARALLEL_ENDPOINT = "https://search.parallel.ai/mcp";
 const PARALLEL_TOOL = "web_search";
 
-/** Per-process session id — stable across searches so Parallel's free-tier
- * rate limiter correlates calls consistently. */
-const SESSION_ID =
-  "dsh-websearch-" +
-  process.pid?.toString(36) + "-" +
-  Math.random().toString(36).slice(2, 10);
+/** Per-process session id - stable so Parallel free-tier rate limiting correlates calls. */
+const SESSION_ID = "dsh-websearch-" + randomUUID().slice(0, 8);
 
 export const parallelBackend = {
   id: "parallel",
@@ -60,9 +57,26 @@ export const parallelBackend = {
       );
     }
 
-    hooks.recordOutcome?.({ status: "ok" });
+    if (result?.isError === true) {
+
+
+      const message = String(result.content?.[0]?.text ?? "unknown");
+
+
+      hooks.recordOutcome?.({ status: "error", message });
+
+
+      throw new WebError(`parallel returned an MCP error: ${message}`, "WEB_PROVIDER_ERROR");
+
+
+    }
+
+
     const sources = parseParallelResult(result, request.maxResults ?? 8);
 
+
+    hooks.recordOutcome?.({ status: "ok", count: sources.length });
+
     if (result?.isError === true) {
       throw new WebError(
         `parallel returned an MCP error: ${String(result.content?.[0]?.text ?? "unknown")}`,

package/lib/backends/searxng.js

@@ -44,7 +44,7 @@ export const searxngBackend = {
 
     const headers = {
       "Accept": "application/json",
-      "User-Agent": "dsh-websearch/2.1",
+      "User-Agent": "dsh-websearch/2.3",
     };
     
     if (apiKey) {
@@ -62,6 +62,8 @@ export const searxngBackend = {
       response = await fetch(url, {
         method: "GET",
         headers,
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -71,8 +73,11 @@ export const searxngBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
+      if (response.status === 429 || response.status >= 500) {
+        throw new WebError("SearXNG API error (HTTP " + response.status + "): " + text + " (instance struggling? point searxngBaseURL at another public instance)", "WEB_PROVIDER_ERROR");
+      }
       throw new WebError("SearXNG API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }
 

package/lib/backends/serper.js

@@ -52,9 +52,11 @@ export const serperBackend = {
           "X-API-KEY": apiKey,
           "Content-Type": "application/json",
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body: JSON.stringify(body),
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -63,7 +65,7 @@ export const serperBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: "HTTP " + response.status + ": " + text });
       throw new WebError("Serper API error (HTTP " + response.status + "): " + text, "WEB_PROVIDER_ERROR");
     }

package/lib/backends/tavily.js

@@ -56,9 +56,11 @@ export const tavilyBackend = {
           "Authorization": `Bearer ${apiKey}`,
           "Content-Type": "application/json",
           "Accept": "application/json",
-          "User-Agent": "dsh-websearch/2.1",
+          "User-Agent": "dsh-websearch/2.3",
         },
         body: JSON.stringify(body),
+        redirect: "error",
+
         signal,
       });
     } catch (error) {
@@ -67,7 +69,7 @@ export const tavilyBackend = {
     }
 
     if (!response.ok) {
-      const text = await response.text().catch(() => "");
+      const text = await response.text().catch(() => "").then((tx) => tx.slice(0, 300));
       hooks?.recordOutcome?.({ status: "error", message: `HTTP ${response.status}: ${text}` });
       throw new WebError(`Tavily API error (HTTP ${response.status}): ${text}`, "WEB_PROVIDER_ERROR");
     }

package/lib/breaker.js

@@ -0,0 +1,65 @@
+// breaker.js — v2.7.0 per-backend circuit breaker (pure functions, zero deps).
+//
+// State lives ON the backend health entry (the same object recordBackendHealth
+// in provider.js maintains), as two extra fields:
+//   failCount  — consecutive failures (reset to 0 on any success)
+//   cooledUntil  — epoch ms until which the backend is skipped; 0 = closed
+// Breaker opens when failCount reaches threshold and stays open for
+// cooldownMs. Failure modes are deliberately conservative: unknown state or
+// missing fields never trip; a fully-cooled fan-out falls back to running
+// every backend (fail-open) so the breaker can never make search WORSE than
+// no breaker.
+
+/** Default breaker tuning (settings can override; cooldownMs 0 = disabled). */
+export const BREAKER_DEFAULTS = {
+  threshold: 3,
+  cooldownMs: 60_000,
+};
+
+/**
+ * Fold one backend outcome into the breaker fields of a health entry.
+ * Pure: returns the new fields; caller merges into the entry.
+ *
+ * @param {object|undefined} prev  previous entry (may be undefined)
+ * @param {boolean} ok             did this call succeed?
+ * @param {number} nowMs
+ * @param {{threshold?: number, cooldownMs?: number}} cfg
+ * @returns {{ failCount: number, cooledUntil: number }}
+ */
+export function foldBreaker(prev, ok, nowMs, cfg = {}) {
+  const threshold = Math.max(1, Math.floor(Number(cfg.threshold) || BREAKER_DEFAULTS.threshold));
+  // cooldownMs === 0 explicitly disables the cooldown window (cooledUntil = now
+  // expires instantly). Only null/undefined falls back to the default — an
+  // explicit 0 must not silently become 60s (arch-review P2 note).
+  const cooldownMs = cfg.cooldownMs != null
+    ? Math.max(0, Math.floor(Number(cfg.cooldownMs) || 0))
+    : BREAKER_DEFAULTS.cooldownMs;
+  if (ok) return { failCount: 0, cooledUntil: 0 };
+  const failCount = (Number.isFinite(prev?.failCount) ? prev.failCount : 0) + 1;
+  if (failCount >= threshold) {
+    return { failCount, cooledUntil: nowMs + cooldownMs };
+  }
+  // Keep an existing open window if the backend was already open (failure
+  // while open extends nothing, but must not silently close it).
+  return { failCount, cooledUntil: Number.isFinite(prev?.cooledUntil) ? prev.cooledUntil : 0 };
+}
+
+/**
+ * Is the backend currently in its cooldown window?
+ * @param {object|undefined} entry  health entry (failCount/cooledUntil optional)
+ * @param {number} nowMs
+ */
+export function isCooled(entry, nowMs = Date.now()) {
+  const cooledUntil = entry?.cooledUntil;
+  return Number.isFinite(cooledUntil) && cooledUntil > nowMs;
+}
+
+/**
+ * Human telemetry annotation for a cooled backend, e.g. "⏸cooled 42s".
+ * Empty string when not cooled.
+ */
+export function cooledAnnotation(entry, nowMs = Date.now()) {
+  if (!isCooled(entry, nowMs)) return "";
+  const restS = Math.max(0, Math.ceil((entry.cooledUntil - nowMs) / 1000));
+  return `⏸cooled ${restS}s`;
+}

package/lib/cache.js

@@ -0,0 +1,151 @@
+// cache.js — v2.7.0 disk cache for unified search results (zero dependencies).
+//
+// Cache key: sha256 over the canonical JSON of {query (already shaped),
+// filters, maxResults} — exactly the dimensions that change a search outcome.
+// Entries live as one JSON file per key under <dir>, written atomically
+// (tmp file + rename) so a crash mid-write never leaves a corrupt cache.
+// Eviction: when the entry count exceeds maxEntries, the oldest-by-mtime
+// files are deleted first. Every fs error is swallowed by the caller-facing
+// API (get/set never throw) — a broken cache must never break a search.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+/** Defaults (overridable per instance; settings feed these from index.js). */
+export const CACHE_DEFAULTS = {
+  ttlMs: 900_000, // 900s
+  maxEntries: 200,
+};
+
+/**
+ * Compute the deterministic cache key for a search.
+ * Includes the enabledBackends selection set (sorted): switching the backend
+ * 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 }) {
+  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,
+  });
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+
+/** Age of a record in whole seconds (bounded >= 0). */
+function ageSeconds(record, nowMs) {
+  return Math.max(0, Math.floor((nowMs - (record?.time ?? 0)) / 1000));
+}
+
+/**
+ * Create a disk-backed result cache.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir         cache directory (created lazily)
+ * @param {number} [opts.ttlMs]     entry TTL in ms (default 900_000)
+ * @param {number} [opts.maxEntries] entry cap (default 200)
+ * @returns {{ get, set, clear }}  get/set/clear never throw
+ */
+export function createSearchCache({ dir, ttlMs = CACHE_DEFAULTS.ttlMs, maxEntries = CACHE_DEFAULTS.maxEntries }) {
+  // ttlMs may be a number or () => number (settings can change at runtime).
+  const ttlOf = typeof ttlMs === "function" ? ttlMs : () => Number(ttlMs) || 0;
+  const cap = Math.max(1, Math.floor(Number(maxEntries) || CACHE_DEFAULTS.maxEntries));
+
+  const fileFor = (key) => path.join(dir, `${key}.json`);
+
+  function ensureDir() {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  /**
+   * Atomic write: tmp sibling + rename. Atomic on POSIX (rename(2) replaces
+   * atomically) and on Windows via libuv's MoveFileExW(MOVEFILE_REPLACE_
+   * EXISTING) — see README "权威依据与取舍" for the Windows caveat.
+   */
+  function atomicWrite(file, data) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, file);
+  }
+
+  /** List current entries as [{key, file, mtime}] sorted oldest first. */
+  function listEntries() {
+    if (!existsSync(dir)) return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".json") || name.includes(".tmp")) continue;
+      const file = path.join(dir, name);
+      try {
+        out.push({ key: name.slice(0, -5), file, mtime: statSync(file).mtimeMs });
+      } catch {
+        // raced delete — skip
+      }
+    }
+    return out.sort((a, b) => a.mtime - b.mtime);
+  }
+
+  function evict() {
+    const entries = listEntries();
+    for (let i = 0; i < entries.length - cap; i++) {
+      try { unlinkSync(entries[i].file); } catch { /* raced */ }
+    }
+  }
+
+  return {
+    /**
+     * Look up a cached result.
+     * @returns {{ value: object, age: number } | null} age in seconds; null on miss/expiry
+     */
+    get(key, nowMs = Date.now()) {
+      try {
+        const file = fileFor(key);
+        if (!existsSync(file)) return null;
+        const record = JSON.parse(readFileSync(file, "utf8"));
+        if (!record || typeof record !== "object" || !record.value) return null;
+        const age = ageSeconds(record, nowMs);
+        const ttl = Math.max(0, Number(ttlOf()) || 0);
+        if (age * 1000 > ttl) {
+          try { unlinkSync(file); } catch { /* raced */ }
+          return null;
+        }
+        return { value: record.value, age };
+      } catch {
+        return null;
+      }
+    },
+
+    /** Store a result (best-effort; fs errors are swallowed). */
+    set(key, value, nowMs = Date.now()) {
+      try {
+        ensureDir();
+        atomicWrite(fileFor(key), JSON.stringify({ key, time: nowMs, value }));
+        evict();
+      } catch {
+        // cache write failures are non-fatal by design
+      }
+    },
+
+    /** Drop every cached entry (best-effort). */
+    clear() {
+      try {
+        for (const e of listEntries()) {
+          try { unlinkSync(e.file); } catch { /* raced */ }
+        }
+      } catch {
+        // nothing to do
+      }
+    },
+  };
+}