@240xu/dsh-websearch 2.3.0 → 2.7.2

package/lib/client.js

@@ -15,7 +15,7 @@ window.__ModuleLoader__.load({
 			{ id: "exa", keyEnv: null, label: "Exa (MCP, 免费)" },
 			{ id: "parallel", keyEnv: null, label: "Parallel (MCP, 免费)" },
 			{ id: "ddg", keyEnv: null, label: "DuckDuckGo (HTML)" },
-			{ id: "searxng", keyEnv: "SEARXNG_API_KEY", label: "SearXNG (元搜索)" },
+			{ id: "searxng", keyEnv: "SEARXNG_API_KEY", optionalKey: true, label: "SearXNG (元搜索)" },
 			{ id: "brave", keyEnv: "BRAVE_API_KEY", label: "Brave Search" },
 			{ id: "tavily", keyEnv: "TAVILY_API_KEY", label: "Tavily (AI)" },
 			{ id: "serper", keyEnv: "SERPER_API_KEY", label: "Serper.dev" },
@@ -32,8 +32,9 @@ window.__ModuleLoader__.load({
 		};
 		/** Boolean settings staged as "true"/"false" strings by the selects. */
 		const BOOLEAN_FIELDS = ["rerank", "safeSearch", "resultTelemetry"];
-		const KEYLESS = BACKENDS.filter((b) => !b.keyEnv);
-		const KEYED = BACKENDS.filter((b) => b.keyEnv);
+		const KEYLESS = BACKENDS.filter((b) => !b.keyEnv || b.optionalKey);
+		const KEYED = BACKENDS.filter((b) => b.keyEnv && !b.optionalKey);
+		const OPTIONAL_KEYS = BACKENDS.filter((b) => b.keyEnv && b.optionalKey);
 
 		/** Where the user goes to get/rotate each key. */
 		const KEY_URLS = {
@@ -90,6 +91,10 @@ window.__ModuleLoader__.load({
 			langPlaceholder: "如 en、zh-CN，留空为默认",
 						envProvided: "环境变量提供",			readOnly: "只读，无需填写",			conflict: "设置已在其他端被修改，请重试",			keyFailed: "该 Key 保存失败",
 			telemetryLabel: "结果健康遥测",
+			fallbackHint: "全部后端已关闭：搜索将回退到默认免 Key 后端",
+			invalidFields: "以下字段未通过校验：",
+			readOnlyScope: "当前配置只读（可能由宿主锁定）",
+			optionalTitle: "私有实例可选 Key",
 		};
 		const en = {
 			nav: "Web Search",
@@ -138,6 +143,10 @@ window.__ModuleLoader__.load({
 			conflict: "Changed elsewhere - please retry",
 			keyFailed: "failed to save this key",
 			telemetryLabel: "Result health telemetry",
+			fallbackHint: "All backends off: search falls back to the default keyless four.",
+			invalidFields: "Fields failed validation:",
+			readOnlyScope: "Configuration is read-only (locked by host?)",
+			optionalTitle: "Private instance optional keys",
 		};
 
 		//#region styles
@@ -177,7 +186,8 @@ window.__ModuleLoader__.load({
 				this.saving = false;
 				this.failed = false;
 				this.conflict = false;
-				this.failedKeys = new Set();
+				this.failedKeys = new Map(); // envRef -> failure reason
+				this.failedFields = new Set();
 				this.savedAt = 0;
 				this.store = createStore(this.projection());
 				this.scope.subscribe(() => this.republish());
@@ -209,7 +219,8 @@ window.__ModuleLoader__.load({
 						return s ? (s.clear ? "" : s.text) : undefined;
 					},
 					conflict: this.conflict,
-					failedKeys: [...this.failedKeys],
+					failedKeys: [...this.failedKeys].map(([ref, reason]) => ({ ref, reason })),
+					failedFields: [...this.failedFields],
 					saving: this.saving,
 					failed: this.failed,
 					version: (this.staged.size + ":" + [...this.staged.keys()].join(",")),
@@ -224,7 +235,12 @@ window.__ModuleLoader__.load({
 
 			/** Toggles write immediately (no staging); globals/keys stage + save. */
 			async setToggle(id, checked) {
-				await this.scope.set("enable" + id.charAt(0).toUpperCase() + id.slice(1), checked);
+				try {
+					await this.scope.set("enable" + id.charAt(0).toUpperCase() + id.slice(1), checked);
+				} catch (err) {
+					this.failed = true;
+					this.conflict = String(err).includes("SETTINGS_CONFLICT");
+				}
 				
 				this.republish();
 			}
@@ -245,7 +261,8 @@ window.__ModuleLoader__.load({
 
 			async save() {
 				if (this.saving) return;
-				this.saving = true; this.failed = false; this.republish();
+				this.saving = true; this.failed = false;
+			this.conflict = false; this.failedFields.clear(); this.republish();
 				const doneFields = [];
 				const doneKeys = [];
 				try {
@@ -253,13 +270,13 @@ window.__ModuleLoader__.load({
 						// Empty draft clears the override so the schema default applies again.
 						if (staged.clear || staged.text === "") { await this.scope.unset(field); doneFields.push(field); continue; }
 						if (SELECT_FIELDS[field]) {
-							if (!SELECT_FIELDS[field].includes(staged.text)) { this.failed = true; continue; }
+							if (!SELECT_FIELDS[field].includes(staged.text)) { this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, staged.text);
 							doneFields.push(field);
 							continue;
 						}
 						if (BOOLEAN_FIELDS.includes(field)) {
-							if (staged.text !== "true" && staged.text !== "false") { this.failed = true; continue; }
+							if (staged.text !== "true" && staged.text !== "false") { this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, staged.text === "true");
 							doneFields.push(field);
 							continue;
@@ -274,7 +291,7 @@ window.__ModuleLoader__.load({
 								backendTimeoutMs: [1000, 120000],
 							};
 							const [lo, hi] = BOUNDS[field] ?? [-Infinity, Infinity];
-							if (Number.isNaN(num) || num < lo || num > hi) { this.failed = true; continue; }
+							{ this.failed = true; this.failedFields.add(field); continue; }
 							await this.scope.set(field, num);
 							doneFields.push(field);
 						} else {
@@ -293,7 +310,7 @@ window.__ModuleLoader__.load({
 							} catch (keyErr) {
 								// env-shadowed reference (fail-loud doctrine): isolate so other keys still land.
 								this.failed = true;
-								this.failedKeys.add(ref);
+								this.failedKeys.set(ref, String(keyErr && keyErr.message ? keyErr.message : keyErr).slice(0, 140));
 								void keyErr;
 							}
 						}
@@ -331,7 +348,7 @@ window.__ModuleLoader__.load({
 			// no client-side default list to drift against the server.
 			const checked = props.value === true;
 			// Status dot: green keyless-or-keyed, amber enabled-but-key-missing.
-			const needsKey = !!b.keyEnv && !props.keyConfigured;
+			const needsKey = !!b.keyEnv && !b.optionalKey && !props.keyConfigured;
 			const dotColor = needsKey ? (checked ? "#e6a700" : "#888") : "#2ea043";
 			return react_jsx_runtime.jsxs("label", { className: "wsc-toggle", style: { display: "flex", alignItems: "center", gap: 8, cursor: "pointer" }, children: [
 				react_jsx_runtime.jsx("input", {
@@ -373,7 +390,7 @@ window.__ModuleLoader__.load({
 
 			// Status summary: enabled backends + configured keys at a glance.
 			const enabledCount = BACKENDS.filter((b) => state.value[toggleField(b.id)] === true).length;
-			const keyedBackends = BACKENDS.filter((b) => b.keyEnv);
+			const keyedBackends = BACKENDS.filter((b) => b.keyEnv && !b.optionalKey);
 			const keysReady = keyedBackends.filter((b) => state.keyState[b.keyEnv]?.configured).length;
 
 			const recencyOptions = [
@@ -399,6 +416,8 @@ window.__ModuleLoader__.load({
 					react_jsx_runtime.jsxs("span", { children: [props.t("statusKeys"), ": ", react_jsx_runtime.jsx("b", { children: keysReady + "/" + keyedBackends.length })] }),
 				] }),
 				react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, opacity: .65 }, children: props.t("description") }),
+				(enabledCount === 0) && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, color: "#e6a700" }, children: props.t("fallbackHint") }),
+				(state.writable === false) && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, color: "#e6a700" }, children: props.t("readOnlyScope") }),
 				react_jsx_runtime.jsx("h5", { className: "wsc-sectionTitle", children: props.t("groupFree") }),
 				react_jsx_runtime.jsx("div", { className: "wsc-toggles", children: KEYLESS.map((b) =>
 					react_jsx_runtime.jsx(ToggleRow, {
@@ -475,7 +494,7 @@ window.__ModuleLoader__.load({
 					}),
 				] }),
 				react_jsx_runtime.jsx("h4", { className: "wsc-sectionTitle", children: props.t("keysTitle") }),
-				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: BACKENDS.filter((b) => b.keyEnv).map((b) =>
+				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: BACKENDS.filter((b) => b.keyEnv && !b.optionalKey).map((b) =>
 					react_jsx_runtime.jsxs("div", { children: [
 						react_jsx_runtime.jsxs("div", { className: "wsc-fieldHead", children: [
 							react_jsx_runtime.jsx("span", { className: "wsc-label", children: props.t("keyLabel", { id: b.id }) }),
@@ -500,11 +519,24 @@ window.__ModuleLoader__.load({
 						state.failedKeys.includes(b.keyEnv) && react_jsx_runtime.jsx("p", { className: "wsc-hint", style: { color: "#e5534b" }, children: props.t("keyFailed") }),
 					] }, b.id)
 				) }),
+				react_jsx_runtime.jsx("h5", { className: "wsc-sectionTitle", children: props.t("optionalTitle") }),
+				react_jsx_runtime.jsx("div", { className: "wsc-grid", children: OPTIONAL_KEYS.map((b) =>
+					react_jsx_runtime.jsxs("div", { children: [
+						react_jsx_runtime.jsx("div", { className: "wsc-fieldHead", children: react_jsx_runtime.jsx("span", { className: "wsc-label", children: props.t("keyLabel", { id: b.id }) }) }),
+						react_jsx_runtime.jsx("input", {
+							className: "wsc-keyInput", type: "password", autoComplete: "off",
+							placeholder: b.keyEnv,
+							value: state.stagedKeys[b.keyEnv] ?? "",
+							onChange: (e) => card.editKey(b.keyEnv, e.target.value),
+						}),
+					] }, b.id),
+				) }),
 				state.stagedCount > 0 && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, opacity: .6 }, children: props.t("unsavedHint") }),
 				react_jsx_runtime.jsxs("div", { className: "wsc-actions", children: [
-					react_jsx_runtime.jsx("button", { className: "wsc-btn", disabled: state.saving || state.stagedCount === 0, onClick: () => card.save(), children: state.saving ? props.t("saving") : props.t("save") }),
+					react_jsx_runtime.jsx("button", { className: "wsc-btn", disabled: state.saving || state.stagedCount === 0 || state.writable === false, onClick: () => card.save(), children: state.saving ? props.t("saving") : props.t("save") }),
 					(state.stagedCount > 0) && react_jsx_runtime.jsx("button", { className: "wsc-btn wsc-btnGhost", onClick: () => card.discard(), children: props.t("discard") }),
 					state.failed && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e5534b" }, children: props.t("failed") }),
+					(state.failedFields.length > 0) && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e5534b", fontSize: 11 }, children: props.t("invalidFields") + ": " + state.failedFields.join(", ") }),
 				state.conflict && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#e6a700" }, children: props.t("conflict") }),
 					!state.failed && !state.saving && state.savedAt > 0 && react_jsx_runtime.jsx("span", { className: "wsc-status", style: { color: "#2ea043" }, children: props.t("savedOk") }),
 				] }),
@@ -530,6 +562,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,12 @@ 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 path from "node:path";
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = "unified-search";
@@ -39,7 +46,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 +151,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 +214,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 +316,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,
@@ -285,18 +342,60 @@ 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) => {
+    if (typeof settingsCtx.settings?.installSection !== "function") return;
+    settingsCtx.settings.installSection(ctx, NAMESPACE, Config, config, {
+      setSource: (source) => {
+        current = source;
+      },
+      onChange: () => {},
+    });
+  });
+
+  // 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).
+  const storeDir = path.join(
+    process.env.DSH_HOME || path.join(process.env.HOME || "", ".dsh"),
+    "cache", "websearch",
+  );
+  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 });
+  });
 }