@240xu/dsh-websearch 2.4.0 → 2.7.3

package/README.md

@@ -115,6 +115,53 @@ pnpm install
 
 环境变量兜底：未在 credentials 配置时回退读同名环境变量；`DSH_UNIFIED_SEARCH_BACKENDS` 可逗号分隔强制指定启用集合。
 
+## 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 指引），客户端不再静默全死。
+- **DSH 0.1.7 服务端（P1）**：SettingsForms 无 installSection，原 typeof 守卫静默跳过；现输出一次性 console.warn（搜索功能经 cordis config 不受影响），SettingsForms 迁移已立牌。
+- **engines**：声明 `node >= 20.3`（AbortSignal.any 实测需求，Node 18/20.0-20.2 首次搜索即 TypeError）。
+- description 瘦身（版本历史移回本文件/CHANGELOG.md）。
+- **Windows 双端（P2）**：缓存/历史目录回退改用 `os.homedir()`（此前 `process.env.HOME` 在 Windows 通常未设 → 相对路径 → 缓存静默失效）。
+
+## 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.
@@ -160,7 +207,16 @@ tests/
 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/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
+      }
+    },
+  };
+}

package/lib/client.js

@@ -543,10 +543,23 @@ window.__ModuleLoader__.load({
 			] });
 		}
 
-		/** Plugin entry: register the card into the settings plugins page. */
+		/**
+		 * Plugin entry: register the card into the settings plugins page.
+		 * Compatibility (compat-audit P0): the settingsScope client service was
+		 * removed in DSH 0.1.7. It stays in `inject` so the fiber still
+		 * activates when the shim supplies it; every access is feature-detected.
+		 */
 		const inject = ["slots", "locale", "connection", "remote", "settingsScope"];
 		function apply(ctx) {
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "websearch: copy dictionaries");
+			const hasSettingsScope = ctx.get("settingsScope") !== undefined && typeof ctx.settingsScope?.bind === "function";
+			if (!hasSettingsScope) {
+				// DSH >= 0.1.7 without dsh-settings-scope-shim: the settings card
+				// cannot bind its scope. Stop wiring the card instead of hard-
+				// crashing the client fiber; the breadcrumb aids diagnosis.
+				console.warn("[dsh-websearch] settingsScope service unavailable (DSH >= 0.1.7); unified-search settings card disabled. Configure via server settings/cordis config or install dsh-settings-scope-shim.");
+				return;
+			}
 			const controller = new UnifiedSearchCardController(
 				ctx.settingsScope.bind({ namespace: PLUGIN_NS }),
 				ctx.get("connection"),
@@ -562,6 +575,34 @@ window.__ModuleLoader__.load({
 				inject: () => controller.inject(),
 			}, UnifiedSearchSection));
 			controller.refreshAllCredentials();
+
+			// Interop: devkit (and any third-party plugin) dispatches the window
+			// event "dsh-websearch:open-settings" to surface this plugin's
+			// settings. The host exposes no section-jump API, so: if devkit's
+			// toast is available, point the user at the path; otherwise log.
+			// (fe-ui C3 keeps devkit toast as the ecosystem standard notifier.)
+			const onOpenSettings = () => {
+				const hint = "统一搜索设置位于：设置 → 左侧栏「搜索 / Web Search」";
+				try {
+					if (window.__dshDevkit && typeof window.__dshDevkit.toast === "function") {
+						window.__dshDevkit.toast(hint, { kind: "info" });
+						return;
+					}
+				} catch (e) { /* fall through */ }
+				console.info("[dsh-websearch] " + hint);
+			};
+			// Probe contract (devkit 0.1.1): ready flag + ack event, so the
+			// palette can tell "listener present" from "gracefully absent".
+			try {
+				window.__dshWebsearchSettingsReady = true;
+				window.addEventListener("dsh-websearch:open-settings", (ev) => {
+					onOpenSettings(ev);
+					try {
+						window.dispatchEvent(new CustomEvent("dsh-websearch:open-settings:ack"));
+					} catch (e) { /* CustomEvent unavailable */ }
+				});
+				ctx.effect(() => () => window.removeEventListener("dsh-websearch:open-settings", onOpenSettings), "websearch: open-settings listener");
+			} catch (e) { /* non-window env */ }
 		}
 
 		exports.apply = apply;

package/lib/health.js

@@ -0,0 +1,103 @@
+// health.js — read-only health surface for the unified-search plugin.
+//
+// GET /api/unified-search/health reports which backends are enabled / keyless
+// and the LAST per-backend telemetry captured during a real search. It never
+// probes anything by itself (quota safety) and never echoes credential
+// material: error strings are truncated to 40-120 chars (matching the
+// provider's own telemetry truncation) and run through a defensive redaction
+// pass for token-like fragments.
+
+const MAX_ERROR_CHARS = 120;
+
+/** Token-like fragments that must never appear in a health payload. */
+const SECRET_PATTERNS = [
+  /sk-[A-Za-z0-9_-]{8,}/g,
+  /Bearer\s+[A-Za-z0-9._-]{8,}/gi,
+  /(api[_-]?key|token|secret|password)\s*[=:]\s*\S{6,}/gi,
+];
+
+/**
+ * Truncate + redact an error string for safe display.
+ * Returns "" for falsy input; length bounded to 40-120 chars.
+ */
+export function sanitizeError(err) {
+  if (err === null || err === undefined) return "";
+  let s = String(err instanceof Error ? err.message : err);
+  for (const re of SECRET_PATTERNS) s = s.replace(re, "[redacted]");
+  s = s.replace(/\s+/g, " ").trim();
+  if (s.length > MAX_ERROR_CHARS) s = s.slice(0, MAX_ERROR_CHARS);
+  return s;
+}
+
+/**
+ * Build the health report body (pure — no ctx, no I/O; unit-testable).
+ *
+ * @param {object} deps
+ * @param {Function} deps.resolveOptions  () => resolved options snapshot
+ * @param {object} deps.backends          keyed backend registry (BACKENDS)
+ * @param {Map|Function} deps.getBackendHealth  telemetry map or () => map
+ *   entries: { ok: boolean, at: ms, ms: duration, error?: string,
+ *              lastOkAt?: ms|null }
+ * @returns {object} JSON-serializable health payload
+ */
+export function buildHealthReport({ resolveOptions, backends, getBackendHealth }) {
+  const opts = resolveOptions();
+  const healthMap = typeof getBackendHealth === "function" ? getBackendHealth() : getBackendHealth;
+  const tel = healthMap instanceof Map ? healthMap : new Map();
+
+  const enabledSet = new Set(
+    (opts.enabledBackends ?? []).filter((id) => backends[id] !== undefined),
+  );
+
+  const list = Object.keys(backends).map((id) => {
+    const beOpts = opts.backends?.[id] ?? {};
+    const enabled = enabledSet.has(id);
+    const keyless = beOpts.requiresKey !== true;
+    const t = tel.get(id);
+    return {
+      id,
+      enabled,
+      keyless,
+      // reachable: true/false from the latest search telemetry; null = never probed.
+      reachable: t ? t.ok === true : null,
+      lastOk: t && typeof t.lastOkAt === "number" ? t.lastOkAt : null,
+      lastError: t && t.ok !== true ? sanitizeError(t.error) || "unknown error" : null,
+    };
+  });
+
+  const enabledList = list.filter((b) => b.enabled);
+  return {
+    ok: true,
+    enabled: enabledList.length,
+    keyless: enabledList.filter((b) => b.keyless).length,
+    backends: list,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Register the read-only health route on the (late-mounted) webServer.
+ * GET only; never probes backends; response is JSON with no credentials.
+ */
+export function registerHealthRoute(ws, deps) {
+  if (!ws || typeof ws.register !== "function") return;
+  ws.register({
+    kind: "exact",
+    path: "/api/unified-search/health",
+    handler: (req, res) => {
+      const send = (code, body) => {
+        res.writeHead(code, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+      };
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        send(405, { ok: false, error: "method not allowed (GET only)" });
+        return;
+      }
+      try {
+        send(200, buildHealthReport(deps));
+      } catch (err) {
+        send(500, { ok: false, error: sanitizeError(err) || "health report failed" });
+      }
+    },
+  });
+}

package/lib/history.js

@@ -0,0 +1,163 @@
+// history.js — v2.7.0 append-only search history (zero deps).
+//
+// Ring buffer of the most recent maxEntries searches, persisted as one JSON
+// file under the plugin's cache dir. Writes are atomic (tmp + rename) and
+// append-only: existing entries are never rewritten, only prepended; the
+// oldest entry beyond the cap is dropped. Exposure is strictly read-only via
+// GET /api/websearch/history; POST /api/websearch/history/clear empties it.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Ring-buffer cap (spec: 50). */
+export const HISTORY_MAX_ENTRIES = 50;
+
+/** Sanitize a history entry to the exact public shape (no credentials/URLs). */
+function toPublicEntry(entry) {
+  return {
+    query: String(entry?.query ?? "").slice(0, 500),
+    time: Number.isFinite(entry?.time) ? entry.time : Date.now(),
+    resultCount: Math.max(0, Math.floor(Number(entry?.resultCount) || 0)),
+    backendsOk: Math.max(0, Math.floor(Number(entry?.backendsOk) || 0)),
+    backendsTotal: Math.max(0, Math.floor(Number(entry?.backendsTotal) || 0)),
+  };
+}
+
+/**
+ * Create an append-only history store.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir         directory holding history.json (created lazily)
+ * @param {number} [opts.maxEntries] ring cap (default 50)
+ * @returns {{ record, list, clear }}
+ */
+export function createHistoryStore({ dir, maxEntries = HISTORY_MAX_ENTRIES }) {
+  const cap = Math.max(1, Math.floor(Number(maxEntries) || HISTORY_MAX_ENTRIES));
+  const file = () => path.join(dir, "history.json");
+  // Serialize every write through a promise chain: record() is called from
+  // concurrent search completions; without the chain, two interleaved
+  // read-modify-write cycles lose updates (arch-review P2-2). The body stays
+  // synchronous (atomic tmp+rename), so the chain is the only lock needed
+  // within this process; cross-process writers are out of scope and each
+  // write is still atomic for readers.
+  let writeChain = Promise.resolve();
+
+  function readAll() {
+    try {
+      if (!existsSync(file())) return [];
+      const parsed = JSON.parse(readFileSync(file(), "utf8"));
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+
+  function atomicWriteAll(list) {
+    mkdirSync(dir, { recursive: true });
+    const f = file();
+    const tmp = `${f}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(list, null, 2), "utf8");
+    renameSync(tmp, f);
+  }
+
+  return {
+    /** Append one search (best-effort; fs errors are swallowed). Newest first. */
+    record(entry) {
+      writeChain = writeChain.then(() => {
+        try {
+          const list = readAll();
+          list.unshift(toPublicEntry(entry));
+          if (list.length > cap) list.length = cap;
+          atomicWriteAll(list);
+        } catch {
+          // history write failures are non-fatal by design
+        }
+      });
+      return writeChain;
+    },
+
+    /** Read the current history, newest first (defensive copy). */
+    list() {
+      return readAll().slice(0, cap).map(toPublicEntry);
+    },
+
+    /** Empty the history (removes the file; best-effort). */
+    clear() {
+      try {
+        if (existsSync(file())) unlinkSync(file());
+      } catch {
+        // nothing to do
+      }
+    },
+  };
+}
+
+/**
+ * Minimal trust fence for plugin-registered routes (the host /api RPC fence
+ * does not cover webServer.register paths): require a loopback Host (blocks
+ * DNS rebinding) and a same-site browser context (sec-fetch-site same-origin
+ * / none, or an Origin whose host matches the request Host — blocks
+ * cross-site CSRF including text/plain preflight-less POSTs).
+ * Returns null when trusted, otherwise a short rejection reason.
+ */
+export function isTrustedApiRequest(req) {
+  const host = String(req?.headers?.host ?? "");
+  const hostOk = /^(localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[::1\])(:\d+)?$/.test(host);
+  if (!hostOk) return "untrusted host";
+  const site = req?.headers?.["sec-fetch-site"];
+  if (site === "same-origin" || site === "none") return null;
+  const origin = req?.headers?.origin;
+  if (!origin) return site !== undefined ? "cross-site request" : null;
+  try {
+    return new URL(origin).host === host ? null : "cross-origin request";
+  } catch {
+    return "invalid origin";
+  }
+}
+
+/**
+ * Register the read-only history routes on the (late-mounted) webServer.
+ * GET  /api/websearch/history        -> { ok, entries }
+ * POST /api/websearch/history/clear  -> { ok, cleared: true }
+ * Both routes sit behind isTrustedApiRequest (loopback Host + same-site).
+ */
+export function registerHistoryRoutes(ws, { getStore }) {
+  if (!ws || typeof ws.register !== "function") return;
+  const send = (res, code, body) => {
+    res.writeHead(code, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  };
+  const guarded = (handler) => (req, res) => {
+    const fence = isTrustedApiRequest(req);
+    if (fence) {
+      send(res, 403, { ok: false, error: `untrusted request (${fence})` });
+      return;
+    }
+    handler(req, res);
+  };
+  ws.register({
+    kind: "exact",
+    path: "/api/websearch/history",
+    handler: guarded((req, res) => {
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        send(res, 405, { ok: false, error: "method not allowed (GET only)" });
+        return;
+      }
+      const store = getStore();
+      send(res, 200, { ok: true, entries: store ? store.list() : [] });
+    }),
+  });
+  ws.register({
+    kind: "exact",
+    path: "/api/websearch/history/clear",
+    handler: guarded((req, res) => {
+      if (req.method !== "POST") {
+        send(res, 405, { ok: false, error: "method not allowed (POST only)" });
+        return;
+      }
+      const store = getStore();
+      store?.clear();
+      send(res, 200, { ok: true, cleared: true });
+    }),
+  });
+}

package/lib/index.js

@@ -10,10 +10,12 @@
  */
 import z from "@deepseek-ai/schemastery";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
-import {
-  installSettingsSection,
-  settingsNamespace,
-} from "@deepseek-ai/dsh-settings";
+// NOTE (2026-09-12, dsh 0.1.5 compat): installSettingsSection +
+// settingsNamespace were removed from @deepseek-ai/dsh-settings in the 0.1.5
+// line (only SettingsProvider/SettingsConflictError/redactSecrets remain).
+// Settings sections are now installed through the `settings` service, as the
+// stock plugins do (see dsh-permission-presets). NAMESPACE was always the
+// plain string "unified-search". No import needed anymore.
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { WebError } from "@deepseek-ai/dsh-web";
 
@@ -31,7 +33,13 @@ import { tavilyBackend } from "./backends/tavily.js";
 import { serperBackend } from "./backends/serper.js";
 import { searxngBackend } from "./backends/searxng.js";
 import { mojeekBackend } from "./backends/mojeek.js";
-import { createUnifiedSearchProvider } from "./provider.js";
+import { createUnifiedSearchProvider, getLatestBackendHealth } from "./provider.js";
+import { registerHealthRoute } from "./health.js";
+import { createSearchCache, CACHE_DEFAULTS } from "./cache.js";
+import { createHistoryStore, registerHistoryRoutes, HISTORY_MAX_ENTRIES } from "./history.js";
+import { BREAKER_DEFAULTS } from "./breaker.js";
+import os from "node:os";
+import path from "node:path";
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = "unified-search";
@@ -39,7 +47,7 @@ export const name = "unified-search";
 export const inject = ["web"];
 
 /** Settings namespace key. */
-const NAMESPACE = settingsNamespace("unified-search");
+const NAMESPACE = "unified-search";
 
 /** Full backend registry. Order = default fan-out priority. */
 const BACKENDS = {
@@ -144,6 +152,23 @@ export const Config = z.object({
   resultTelemetry: z.boolean().default(true)
     .description("在搜索结果尾部附一行后端健康遥测（状态+耗时），模型可据此自诊断"),
 
+  // v2.7.0 disk cache / circuit breaker / search history
+  // W1 (fe-ui review): labels speak user language with a group prefix
+  // (【缓存】/【熔断】/【历史】) instead of camelCase keys; units are
+  // spelled out (秒 / 毫秒) and grouping follows the field order below.
+  cacheEnabled: z.boolean().default(true)
+    .description("启用搜索结果缓存【缓存】：相同查询+过滤+条数在有效期内直接命中，不再请求后端"),
+  cacheTtl: z.number().step(30).min(30).max(86400).default(900)
+    .description("缓存有效期【缓存】（单位：秒）：默认 900 秒；不想用缓存请直接关闭上一项"),
+  breakerEnabled: z.boolean().default(true)
+    .description("后端熔断器【熔断】：连续失败达阈值后暂停该后端一段时间；全部暂停时自动放行，不会让搜索更差"),
+  breakerThreshold: z.number().step(1).min(1).max(20).default(BREAKER_DEFAULTS.threshold)
+    .description("熔断阈值【熔断】：连续失败多少次后触发（默认 3 次）"),
+  breakerCooldownMs: z.number().step(1000).min(0).max(3600000).default(BREAKER_DEFAULTS.cooldownMs)
+    .description("熔断冷却时长【熔断】（单位：毫秒）：默认 60000；设为 0 表示关闭冷却（熔断仅计数）"),
+  historyEnabled: z.boolean().default(true)
+    .description("记录搜索历史【历史】：只追加，最多 50 条；可在设置 → 搜索 中查看与清空"),
+
   // Enable toggles (one per backend)
   enableExa: z.boolean().default(true).description(DEFAULT_LABELS.exa),
   enableParallel: z.boolean().default(true).description(DEFAULT_LABELS.parallel),
@@ -190,6 +215,30 @@ export const Config = z.object({
     .description("显式启用后端列表（优先于上方开关；留空则用开关）"),
 });
 
+/**
+ * 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
+ * each v2.7 descriptor (meta.label, plus a plain .label for renderers that
+ * read the top level). Units live in the label tail (秒 / 毫秒). Whether the
+ * host actually renders them is visual-check V5; the schema layer now
+ * provides the field regardless.
+ */
+const FIELD_LABELS = {
+  cacheEnabled: "启用搜索结果缓存",
+  cacheTtl: "缓存有效期（秒）",
+  breakerEnabled: "后端熔断器",
+  breakerThreshold: "熔断阈值（连续失败次数）",
+  breakerCooldownMs: "熔断冷却时长（毫秒）",
+  historyEnabled: "记录搜索历史",
+};
+for (const [key, label] of Object.entries(FIELD_LABELS)) {
+  const sch = Config.dict?.[key];
+  if (sch) {
+    sch.meta = { ...sch.meta, label };
+    sch.label = label;
+  }
+}
+
 /**
  * Project one resolved settings section into the options snapshot the provider
  * serves its NEXT search with. Key resolution: credentialRef -> credentials
@@ -268,6 +317,15 @@ export function resolveOptions(ctx, config) {
     dedupStrategy: config?.dedupStrategy === "url+title" ? "url+title" : "url",
     rerank: config?.rerank === true,
     resultTelemetry: config?.resultTelemetry !== false,
+    // v2.7.0 cache / breaker / history
+    cacheEnabled: config?.cacheEnabled === true,
+    cacheTtlS: Math.max(30, Math.floor(Number(config?.cacheTtl) || CACHE_DEFAULTS.ttlMs / 1000)),
+    breakerEnabled: config?.breakerEnabled !== false,
+    breakerThreshold: Math.max(1, Math.floor(Number(config?.breakerThreshold) || BREAKER_DEFAULTS.threshold)),
+    breakerCooldownMs: config?.breakerCooldownMs != null
+      ? Math.max(0, Math.floor(Number(config?.breakerCooldownMs) || 0))  // 0 = disabled
+      : BREAKER_DEFAULTS.cooldownMs,
+    historyEnabled: config?.historyEnabled !== false,
     filters: {
       recency: typeof config?.recency === "string" && config.recency !== "any" ? config.recency : undefined,
       lang: language.length > 0 ? language : undefined,
@@ -277,6 +335,19 @@ export function resolveOptions(ctx, config) {
   };
 }
 
+/**
+ * Resolve the plugin's persistent store directory (cache + history).
+ * Pure and exported for tests: precedence is DSH_HOME > <home>/.dsh, where
+ * home falls back to os.homedir() — NOT process.env.HOME, which is usually
+ * unset on Windows and would silently disable cache/history (compat-audit
+ * P2-7).
+ * @param {{DSH_HOME?: string, HOME?: string}} env
+ * @param {string} [fallbackHome] injected os.homedir() for tests
+ */
+export function resolveStoreDir(env = process.env, fallbackHome = os.homedir()) {
+  return path.join(env.DSH_HOME || path.join(fallbackHome, ".dsh"), "cache", "websearch");
+}
+
 /**
  * Register the unified search provider with ctx.web. Installs a settings
  * section so users can configure enabled backends / numResults / base URLs /
@@ -285,18 +356,73 @@ export function resolveOptions(ctx, config) {
 export function apply(ctx, config) {
   let current = () => config;
 
-  installSettingsSection(ctx, NAMESPACE, Config, config, {
-    setSource: (source) => {
-      current = source;
-    },
-    onChange: () => {},
+  ctx.inject(["settings"], (settingsCtx) => {
+    const settings = settingsCtx.settings;
+    if (typeof settings?.installSection === "function") {
+      settings.installSection(ctx, NAMESPACE, Config, config, {
+        setSource: (source) => {
+          current = source;
+        },
+        onChange: () => {},
+      });
+      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.",
+    );
+  });
+
+  // v2.7.0 stores: disk cache + append-only search history, both under
+  // DSH_HOME/cache/websearch (created lazily; every fs error is swallowed so
+  // a broken store never breaks a search).
+  // DSH_HOME wins when set; otherwise the OS home directory. os.homedir()
+  // (not process.env.HOME) is the cross-platform fallback — HOME is usually
+  // unset on Windows, which previously made storeDir relative to the current
+  // working directory and silently disabled cache/history (compat-audit P2-7).
+  const storeDir = resolveStoreDir();
+  const searchCache = createSearchCache({
+    dir: path.join(storeDir, "results"),
+    ttlMs: () => resolveOptions(ctx, current()).cacheTtlS * 1000,
+    maxEntries: CACHE_DEFAULTS.maxEntries,
   });
+  const historyStore = createHistoryStore({ dir: storeDir, maxEntries: HISTORY_MAX_ENTRIES });
 
   const provider = createUnifiedSearchProvider({
     ctx,
     resolveOptions: () => resolveOptions(ctx, current()),
     backends: BACKENDS,
+    cache: {
+      get: (key) => searchCache.get(key),
+      set: (key, value) => searchCache.set(key, value),
+    },
+    history: {
+      record: (entry) => {
+        if (resolveOptions(ctx, current()).historyEnabled !== true) return;
+        historyStore.record(entry);
+      },
+    },
   });
 
   ctx.web.registerSearchProvider(provider);
+
+  // Read-only health route: webServer is an optional, late-mounted host
+  // service (same pattern as dsh-chat-import's panel routes). Headless / CI
+  // profiles never mount it and the callback simply never runs. The route
+  // only reads the settings snapshot + last per-search telemetry — it never
+  // probes backends and never touches credential values.
+  ctx.inject(["webServer"], (webCtx) => {
+    registerHealthRoute(webCtx.webServer, {
+      resolveOptions: () => resolveOptions(ctx, current()),
+      backends: BACKENDS,
+      getBackendHealth: getLatestBackendHealth,
+    });
+    // v2.7.0 search history: read-only GET + explicit clear POST.
+    registerHistoryRoutes(webCtx.webServer, { getStore: () => historyStore });
+  });
 }

package/lib/prompting.js

@@ -0,0 +1,105 @@
+/**
+ * dsh-websearch — 系统性搜索提示词（纯函数，零依赖）。
+ *
+ * 依据权威资料（2024-2026 官方文档与一手论文）实现三项必做：
+ *   1. 查询整形（query shaping）：后端扇出前对口语化长查询做确定性归一，
+ *      并导出给宿主/代理层使用的查询构造指引。
+ *      依据：Tavily Best Practices（agent 风格 ≤1500 字符查询、子查询分解）
+ *      https://docs.tavily.com/documentation/best-practices/best-practices-search
+ *      Exa Search Best Practices（语义丰富、描述性查询）
+ *      https://exa.ai/docs/search-best-practices
+ *   2. 结果呈现头（result-presentation header）：模型看到的结果块以「来源
+ *      甄别 + 引用要求」开头，要求每条事实注明来源链接、优先官方/一手来源、
+ *      时效敏感主题优先较新结果。
+ *      依据：Anthropic Web Search Tool（结果块置于问题之前、引用来源）
+ *      https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
+ *      OpenAI Prompt Engineering（分解 + 持久性指令）
+ *      https://platform.openai.com/docs/guides/prompt-engineering
+ *   3. 多面查询分解指引（导出常量，供宿主/代理层按需使用；不对本插件内
+ *      的单次请求盲目多查询——盲目多查询可能劣化，见 arXiv:2404.01037）。
+ *      依据：RAG-Fusion / 多查询变体 https://github.com/Raudaschl/rag-fusion
+ *      Step-Back Prompting https://arxiv.org/abs/2310.06117
+ *      HyDE https://arxiv.org/abs/2212.10496
+ * @module dsh-websearch/prompting
+ */
+
+/** 查询硬上限（Tavily：agent 查询应简短聚焦；>1500 字符视为跑题长文）。 */
+export const QUERY_MAX_CHARS = 1500;
+
+/** 去口语化前缀（中英常见寒暄/请求词，确定性剥离，不改写语义）。 */
+const FILLER_PREFIX_RE =
+  /^(?:please|pls|kindly|could you(?: please)?|can you(?: please)?|help me(?: to)?|search for|search|look up|google|find me|find|i(?:'d| would)? like to know|tell me|what is|who is|when is|where is|"|「|『)\s*/i;
+const FILLER_PREFIX_RE_ZH =
+  /^(?:请|麻烦|帮我?|帮忙|帮我查一?下|查一?下|查询|搜索一下?|搜一下?|查一下?|帮我找|找一下?|我想知道|请问)/;
+
+/**
+ * 确定性查询整形：剥离口语前缀（循环多次以处理叠加寒暄）、压缩空白、
+ * 截断到 QUERY_MAX_CHARS。绝不改写实体/版本号/日期。
+ * @param {string} query
+ * @returns {string}
+ */
+export function shapeQuery(query) {
+  if (typeof query !== "string") return "";
+  let q = query.replace(/\s+/g, " ").trim();
+  // 中文寒暄与英文寒暄交替剥离，直到稳定。
+  for (let i = 0; i < 6; i++) {
+    const before = q;
+    q = q.replace(FILLER_PREFIX_RE, "").trim();
+    q = q.replace(FILLER_PREFIX_RE_ZH, "").trim();
+    if (q === before) break;
+  }
+  if (q.length > QUERY_MAX_CHARS) q = q.slice(0, QUERY_MAX_CHARS).trim();
+  return q;
+}
+
+/**
+ * 结果呈现头（英文）。置于模型可见结果块最前（Anthropic：结果先于问题
+ * 显著提升引用召回）。要求：逐条标注 [n]、优先官方/一手来源、时效敏感
+ * 主题优先较新结果、每条事实给出来源链接、与问题无关的条目忽略。
+ */
+export const RESULT_HEADER_EN =
+  "Web search results (merged from multiple engines, deduplicated by URL). " +
+  "Each entry: [n] title — URL. Prefer official / primary sources; prefer newer " +
+  "results for fast-moving topics; ignore entries whose snippet does not actually " +
+  "answer the question. Cite the URL for every fact you take from a result.";
+
+/** 结果呈现头（中文）。 */
+export const RESULT_HEADER_ZH =
+  "网页搜索结果（多引擎合并、已按 URL 去重）。每条格式：[n] 标题 — 链接。" +
+  "优先采用官方/一手来源；时效敏感主题优先较新结果；摘要与问题无关的条目直接忽略。" +
+  "引用结果中的任何事实时必须注明来源链接。";
+
+/**
+ * 查询构造指引（导出给宿主/代理层注入 agent 系统提示用；本插件不发送）。
+ * EN 面向 agent，ZH 为同义说明。要点：一条聚焦查询、保留专名/版本/日期、
+ * 多面请求按维度拆成多条子查询、首轮结果不佳时先写 2-3 句假想答案再以其
+ * 关键短语重搜（HyDE）、持续检索直到每个维度都有答案。
+ */
+export const QUERY_GUIDANCE_EN =
+  "When searching the web: issue ONE concise, agent-style query (keep named " +
+  "entities, version numbers and dates; drop conversational filler). If the " +
+  "request has 2+ independent facets, issue separate focused queries per facet " +
+  "and merge findings. If the first round returns poor results, write a 2-3 " +
+  "sentence hypothetical ideal answer and re-query with its key phrases. " +
+  "Keep searching until every facet is answered or demonstrably unavailable.";
+
+/** 查询构造指引（中文版）。 */
+export const QUERY_GUIDANCE_ZH =
+  "联网检索时：一次发出一条简洁的 agent 风格查询（保留专名/版本号/日期，去掉口语寒暄）。" +
+  "若请求含 2 个以上独立维度，按维度分别发起聚焦查询并汇总结论。" +
+  "首轮结果不佳时，先写 2-3 句假想的理想答案，再用其中的关键短语重新检索。" +
+  "持续检索直到每个维度都有答案或确认不可得。";
+
+/**
+ * 按语言取结果呈现头。
+ * @param {"zh"|"en"|string} [lang]
+ */
+export function resultHeader(lang) {
+  return String(lang || "").toLowerCase().startsWith("zh") ? RESULT_HEADER_ZH : RESULT_HEADER_EN;
+}
+
+/**
+ * 遥测行自标注（零成本修复）：模型可能把后端失败遥测误读为结果来源；
+ * 显式声明「仅诊断，不是来源」。随结果块一并呈现。
+ */
+export const TELEMETRY_TAG = " (diagnostic only, not a source)";

package/lib/provider.js

@@ -22,9 +22,44 @@ import {
 } from "./util/log.js";
 import { dedupeSources, rerankSources } from "./util/rank.js";
 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";
 
 const PROVIDER_ID = "unified";
 
+// 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
+// report the LAST known reachability without firing probes or burning quota.
+// Entry shape: { ok: boolean, at: ms, ms: duration, count?: number,
+//                error?: string (already truncated to 80), lastOkAt: ms|null }
+const latestBackendHealth = new Map();
+
+/** Read-only access for the health route (never mutate the returned map). */
+export function getLatestBackendHealth() {
+  return latestBackendHealth;
+}
+
+function recordBackendHealth(id, entry, breakerCfg) {
+  const prev = latestBackendHealth.get(id);
+  const breaker = foldBreaker(prev, entry.ok === true, entry.at, breakerCfg ?? undefined);
+  latestBackendHealth.set(id, {
+    ...entry,
+    lastOkAt: entry.ok === true ? entry.at : (prev && prev.lastOkAt) || null,
+    failCount: breaker.failCount,
+    cooledUntil: breaker.cooledUntil,
+  });
+}
+
+/**
+ * Read-only access to one backend's breaker state (failCount / cooledUntil).
+ */
+export function getBackendBreaker(id) {
+  const e = latestBackendHealth.get(id);
+  return e ? { failCount: e.failCount ?? 0, cooledUntil: e.cooledUntil ?? 0 } : { failCount: 0, cooledUntil: 0 };
+}
+
 /**
  * Simple concurrency limiter using a semaphore pattern.
  * No external dependency needed.
@@ -52,6 +87,47 @@ function createLimiter(concurrency) {
   };
 }
 
+/**
+ * PHASE 1 (collect): fold settled fan-out results into the raw merge inputs.
+ * Sources keep fan-out priority order; dedupe/rank over the FULL set happens
+ * later (a mid-merge maxResults cap would silently drop later backends'
+ * entries before cross-backend fill-in and ranking could see them).
+ * URL scheme whitelist is enforced here — javascript:/data: payloads from
+ * compromised or poisoned backends never reach model/GUI consumers.
+ */
+function collectFanoutResults(results, eligible, signal) {
+  const collected = [];
+  let mergedContent;
+  let hardAborted = false;
+  let hardError = null;
+  const failures = [];
+
+  let backendIndex = 0;
+  for (const settled of results) {
+    const failedId = eligible[backendIndex] ? eligible[backendIndex].id : "unknown";
+    backendIndex++;
+    if (settled.status === "fulfilled") {
+      if (mergedContent === undefined && typeof settled.value?.content === "string" && settled.value.content.length > 0) {
+        mergedContent = settled.value.content;
+      }
+      for (const src of settled.value?.sources ?? []) {
+        if (src && typeof src.url === "string" && /^https?:\/\//i.test(src.url)) collected.push(src);
+      }
+    } else {
+      const err = settled.reason;
+      if (err instanceof WebError && err.code === "WEB_ABORTED") {
+        // Per-backend abort -> soft unless the caller signal fired.
+        if (signal?.aborted === true) hardAborted = true;
+        else failures.push({ id: failedId, err });
+      } else {
+        failures.push({ id: failedId, err });
+        if (hardError === null) hardError = err;
+      }
+    }
+  }
+  return { collected, mergedContent, hardAborted, hardError, failures };
+}
+
 /**
  * Build the UnifiedSearchProvider.
  *
@@ -60,7 +136,7 @@ function createLimiter(concurrency) {
  * @param {Function} deps.resolveOptions  () => resolved options snapshot
  * @param {object} deps.backends     keyed backend registry
  */
-export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
+export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cache, history }) {
   return {
     id: PROVIDER_ID,
 
@@ -92,20 +168,84 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       ...(request?.filters ?? {}),
       });
         let effReq = { ...request, maxResults: Math.max(1, Number(request?.maxResults) || opts.numResults || 8) };
+      // 系统性查询整形（Tavily/Exa best practices）：扇出前对口语化查询做
+      // 确定性归一 —— 剥离寒暄前缀、压缩空白、截断到 1500 字符；
+      // 专名/版本号/日期原样保留，不改写语义。
+      effReq.query = shapeQuery(effReq.query);
       if (Object.keys(filters).length > 0) effReq = { ...effReq, filters };
       const maxResults = effReq.maxResults;
       const concurrency = opts.concurrency ?? 6;
       const backendTimeoutMs = opts.backendTimeoutMs ?? 30000;
 
-      // Pick enabled & available backends.
-      const eligible = [];
+      // 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).
+      const cacheEnabled = opts.cacheEnabled === true && cache;
+      let cacheKey = null;
+      if (cacheEnabled) {
+        cacheKey = cacheKeyFor({ query: effReq.query, filters, maxResults, backends: opts.enabledBackends });
+        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
+          // merge; a tampered cache file must not bypass that whitelist.
+          const safeSources = hit.value.sources.filter(
+            (src) => src && typeof src.url === "string" && /^https?:\/\//i.test(src.url),
+          );
+          if (safeSources.length === 0) {
+            // whole entry poisoned or filtered empty -> treat as a miss
+            cacheKey = null;
+          } else {
+          let hitContent = typeof hit.value.content === "string" ? hit.value.content : undefined;
+          const cacheNote = `[websearch cache] cache hit, age ${hit.age}s`;
+          hitContent = hitContent === undefined ? cacheNote : hitContent + "\n\n" + cacheNote;
+          history?.record({
+            query: request?.query,
+            time: Date.now(),
+            resultCount: hit.value.sources.length,
+            backendsOk: 0,
+            backendsTotal: 0,
+          });
+          return {
+            sources: safeSources,
+            ...(hitContent !== undefined ? { content: hitContent } : {}),
+            truncated: hit.value.truncated === true,
+          };
+          }
+        }
+      }
+
+      // Pick enabled & available backends. With the breaker enabled, a
+      // 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.
+      const breakerCfg = opts.breakerEnabled === false ? null : {
+        threshold: opts.breakerThreshold,
+        cooldownMs: opts.breakerCooldownMs,
+      };
+      const nowMs = Date.now();
+      const candidates = [];
       for (const id of opts.enabledBackends) {
         const be = backends[id];
         if (!be) continue;
         const beOpts = opts.backends?.[id] ?? {};
         const avail = be.available(beOpts);
         if (!avail) continue;
-        eligible.push({ id, backend: be, beOpts });
+        candidates.push({ id, backend: be, beOpts });
+      }
+      const cooled = new Map();
+      let eligible = candidates;
+      if (breakerCfg) {
+        const active = candidates.filter((c) => {
+          if (isCooled(latestBackendHealth.get(c.id), nowMs)) {
+            cooled.set(c.id, latestBackendHealth.get(c.id));
+            return false;
+          }
+          return true;
+        });
+        if (active.length > 0) eligible = active;
+        else cooled.clear(); // all cooled -> fail-open
       }
 
       if (eligible.length === 0) {
@@ -121,7 +261,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
 
       const telemetry = [];
       // Concurrency limiter
-      const limit = createLimiter(opts.concurrency ?? 6);
+      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
@@ -152,10 +292,13 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
           .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) => {
-              telemetry.push({ id, ok: false, ms: Date.now() - startedAtMs, error: String(err instanceof Error ? err.message : err).slice(0, 80) });
+              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;
             },
           )
@@ -184,50 +327,18 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
 
       throwIfSearchAborted(signal);
 
-      // Collect every fulfilled backend's sources in fan-out priority order,
-      // then dedupe/rank ONCE over the full set. (The previous loop stopped at
-      // maxResults mid-merge, which silently dropped later backends' entries
-      // before cross-backend fill-in and ranking could see them.)
-      const collected = [];
-      let mergedContent;
-      let hardAborted = false;
-      let hardError = null;
-      const failures = [];
-
-      let backendIndex = 0;
-      for (const settled of results) {
-        const failedId = eligible[backendIndex] ? eligible[backendIndex].id : "unknown";
-        backendIndex++;
-        if (settled.status === "fulfilled") {
-          if (mergedContent === undefined && typeof settled.value?.content === "string" && settled.value.content.length > 0) {
-            mergedContent = settled.value.content;
-          }
-          for (const src of settled.value?.sources ?? []) {
-            // Scheme whitelist: parsed URLs reach model/GUI consumers; drop
-            // javascript:/data: payloads from compromised or poisoned backends.
-            if (src && typeof src.url === "string" && !/^https?:\/\//i.test(src.url)) continue;
-            collected.push(src);
-          }
-        } else {
-          // settled.status === "rejected"
-          const err = settled.reason;
-          if (err instanceof WebError && err.code === "WEB_ABORTED") {
-            // Per-backend abort → soft unless caller signal fired.
-            if (signal?.aborted === true) hardAborted = true;
-            else failures.push({ id: failedId, err });
-          } else {
-            failures.push({ id: failedId, err });
-            if (hardError === null) hardError = err;
-          }
-        }
-      }
+      // 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);
 
       // Caller-cancellation check (hard abort fires before we yield results).
       if (signal?.aborted === true || hardAborted) {
         throw searchAborted(signal);
       }
 
-      // Dedup: "url" preserves the historical URL-key behavior; "url+title"
+      // 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);
@@ -240,11 +351,37 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       // If we got ANY sources, return them even if some backends failed.
       if (ordered.length > 0) {
         const sources = ordered.slice(0, maxResults);
+        // 结果呈现头（Anthropic web-search / OpenAI grounding 官方指引）：
+        // 置于结果块最前，要求逐条引用来源 URL、优先官方/一手与较新来源；
+        // 语言按查询文本自动选择（含 CJK 用中文头）。可用
+        // opts.resultHeader === false 关闭。
         let outContent = mergedContent;
-        if (opts.resultTelemetry !== false && telemetry.length > 0) {
-          const line = "[websearch backends] " + telemetry
+        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;
+        }
+        // Store the pre-telemetry core (sources + headered content) so a cache
+        // hit reproduces the exact sources and the model-facing header.
+        if (cacheKey && cache) {
+          cache.set(cacheKey, { sources, content: outContent, truncated: ordered.length > maxResults });
+        }
+        history?.record({
+          query: request?.query,
+          time: Date.now(),
+          resultCount: sources.length,
+          backendsOk: telemetry.filter((t) => t.ok).length,
+          backendsTotal: telemetry.length,
+        });
+        if (opts.resultTelemetry !== false && (telemetry.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
             .map((t) => t.id + (t.ok ? " ✓" : " ✗") + t.ms + "ms" + (t.ok ? "/" + t.count : (t.error ? " (" + String(t.error).slice(0, 40) + ")" : "")))
-            .join(" · ");
+            .concat(cooledParts);
+          const line = "[websearch backends]" + TELEMETRY_TAG + " " + parts.join(" · ");
           outContent = outContent === undefined ? line : outContent + "\n\n" + line;
         }
         return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@240xu/dsh-websearch",
-  "version": "2.4.0",
-  "description": "Unified web search provider for DeepSeek Harness (ctx.web): 11 backends \u2014 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 tool.",
+  "version": "2.7.3",
+  "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",
   "exports": {
@@ -66,5 +66,8 @@
       ],
       "platform": "web"
     }
+  },
+  "engines": {
+    "node": ">=20.3"
   }
 }