@240xu/dsh-websearch 2.1.1 → 2.3.0

package/README.md

@@ -31,6 +31,18 @@ DSH（[DeepSeek Harness](https://github.com/deepseek-ai/dsh)）原生插件：
 
 **Default enabled set**: `["exa", "parallel", "ddg", "searxng"]` — all keyless. The key-gated backends only join when their `available()` returns true (key present + baseURL reachable).
 
+### SearXNG 实例 | Public instances
+
+SearXNG 默认指向 `https://searx.be`；公共实例可用性随网络环境波动，失败时错误信息会提示换源。
+在设置面板修改 `searxngBaseURL` 即可切换，常见候选：
+
+| 实例 | 备注 |
+|---|---|
+| https://searx.be | 官方默认，部分地区不可达 |
+| https://searx.tiekoetter.com | 稳定性较好 |
+| https://priv.au | 隐私友好 |
+| 自托管 | 最可靠，支持 API Key（`searxngApiKeyEnv`） |
+
 ## Install | 安装
 
 ### 方式一：作为 profile 依赖安装（推荐，规范做法）
@@ -81,6 +93,9 @@ pnpm install
 
 **v2.1 结果策略**：设置面板新增「结果策略」分区。时间/语言过滤按各后端能力自动映射——Brave `freshness/country/search_lang`、Tavily `time_range`、Serper `tbs/hl/gl`（Google 日期语法）、SearXNG `time_range/language`、DDG `df`；不支持的后端自动忽略对应维度。内部超时以真实原因失败（backend "<id>" timed out after Nms），不再被静默降级为取消；Mojeek 的 API Key 改走 Authorization 头，不再出现在 URL 中。
 
+**结果健康遥测（默认开）**：每次搜索的 `content` 尾部附一行 `[websearch backends] exa ✓5ms/3 · ddg ✗30000ms`，
+模型可据此自诊断并建议用户调整设置；设置面板「结果策略」可关闭（`resultTelemetry`）。
+
 **11 个后端开关**：`enableExa` / `enableParallel` / `enableDdg` / `enableSearxng`（默认开）；`enableBrave` / `enableTavily` / `enableSerper` / `enableMojeek` / `enableDeepseek` / `enableAnthropic` / `enableOpenai`（默认关）
 
 **API Key 授权**（credential-ref，填环境变量名，实际 key 存于 credentials 服务或环境变量）：

package/lib/backends/searxng.js

@@ -66,7 +66,8 @@ export const searxngBackend = {
       });
     } catch (error) {
       if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
-      throw new WebError("SearXNG request failed: " + error, "WEB_PROVIDER_ERROR", { cause: error });
+      throw new WebError("SearXNG request failed: " + error +
+        " (instance unreachable? point searxngBaseURL at another public instance)", "WEB_PROVIDER_ERROR", { cause: error });
     }
 
     if (!response.ok) {

package/lib/client.js

@@ -31,7 +31,7 @@ window.__ModuleLoader__.load({
 			dedupStrategy: ["url", "url+title"],
 		};
 		/** Boolean settings staged as "true"/"false" strings by the selects. */
-		const BOOLEAN_FIELDS = ["rerank", "safeSearch"];
+		const BOOLEAN_FIELDS = ["rerank", "safeSearch", "resultTelemetry"];
 		const KEYLESS = BACKENDS.filter((b) => !b.keyEnv);
 		const KEYED = BACKENDS.filter((b) => b.keyEnv);
 
@@ -88,6 +88,8 @@ window.__ModuleLoader__.load({
 			dedupUrl: "按链接",
 			dedupTitle: "链接 + 标题（合并转载）",
 			langPlaceholder: "如 en、zh-CN，留空为默认",
+						envProvided: "环境变量提供",			readOnly: "只读，无需填写",			conflict: "设置已在其他端被修改，请重试",			keyFailed: "该 Key 保存失败",
+			telemetryLabel: "结果健康遥测",
 		};
 		const en = {
 			nav: "Web Search",
@@ -131,6 +133,11 @@ window.__ModuleLoader__.load({
 			dedupUrl: "By URL",
 			dedupTitle: "URL + title (merge syndication)",
 			langPlaceholder: "e.g. en, zh-CN; blank = backend default",
+			envProvided: "provided by env",
+			readOnly: "read-only, nothing to fill",
+			conflict: "Changed elsewhere - please retry",
+			keyFailed: "failed to save this key",
+			telemetryLabel: "Result health telemetry",
 		};
 
 		//#region styles
@@ -169,6 +176,8 @@ window.__ModuleLoader__.load({
 				this.keyState = new Map();    // envRef -> {configured}
 				this.saving = false;
 				this.failed = false;
+				this.conflict = false;
+				this.failedKeys = new Set();
 				this.savedAt = 0;
 				this.store = createStore(this.projection());
 				this.scope.subscribe(() => this.republish());
@@ -199,6 +208,8 @@ window.__ModuleLoader__.load({
 						const s = this.staged.get(field);
 						return s ? (s.clear ? "" : s.text) : undefined;
 					},
+					conflict: this.conflict,
+					failedKeys: [...this.failedKeys],
 					saving: this.saving,
 					failed: this.failed,
 					version: (this.staged.size + ":" + [...this.staged.keys()].join(",")),
@@ -223,7 +234,7 @@ window.__ModuleLoader__.load({
 					const res = await this.connection.api.credentials.describe({ refs: [ref] });
 					if (!res.result.ok) return;
 					const view = res.result.value.credentials[ref];
-					this.keyState.set(ref, { configured: view?.configured ?? false });
+					this.keyState.set(ref, { configured: view?.configured ?? false, writable: view?.writable !== false });
 				} catch { /* ignore */ }
 				this.republish();
 			}
@@ -274,15 +285,26 @@ window.__ModuleLoader__.load({
 					for (const [ref, staged] of this.stagedKeys) {
 						const value = staged.text.trim();
 						if (value !== "") {
-							await this.connection.api.credentials.set({ ref, value });
-							this.keyState.set(ref, { configured: true });
-							doneKeys.push(ref);
+							try {
+								await this.connection.api.credentials.set({ ref, value });
+								this.keyState.set(ref, { configured: true, writable: true });
+								doneKeys.push(ref);
+								this.failedKeys.delete(ref);
+							} catch (keyErr) {
+								// env-shadowed reference (fail-loud doctrine): isolate so other keys still land.
+								this.failed = true;
+								this.failedKeys.add(ref);
+								void keyErr;
+							}
 						}
 					}
 					for (const f of doneFields) this.staged.delete(f);
 					for (const k of doneKeys) this.stagedKeys.delete(k);
 					if (!this.failed && (doneFields.length > 0 || doneKeys.length > 0)) this.savedAt = Date.now();
-				} catch { this.failed = true; }
+				} catch (err) {
+					this.failed = true;
+					this.conflict = String(err).includes("SETTINGS_CONFLICT");
+				}
 				this.saving = false;
 				this.republish();
 			}
@@ -297,7 +319,7 @@ window.__ModuleLoader__.load({
 					reset: (f) => this.reset(f),
 					editKey: (r, t) => this.editKey(r, t),
 					save: () => this.save(),
-					discard: () => { this.staged.clear(); this.stagedKeys.clear(); this.failed = false; this.republish(); },
+					discard: () => { this.staged.clear(); this.stagedKeys.clear(); this.failed = false; this.conflict = false; this.failedKeys.clear(); this.republish(); },
 				};
 			}
 		}
@@ -445,6 +467,12 @@ window.__ModuleLoader__.load({
 						options: boolOptions,
 						onChange: (v) => card.edit("safeSearch", v),
 					}),
+					react_jsx_runtime.jsx(SelectField, {
+						label: props.t("telemetryLabel"),
+						value: selVal("resultTelemetry", "true"),
+						options: boolOptions,
+						onChange: (v) => card.edit("resultTelemetry", v),
+					}),
 				] }),
 				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) =>
@@ -458,15 +486,18 @@ window.__ModuleLoader__.load({
 									children: props.t("getKey"),
 								}),
 								react_jsx_runtime.jsx("span", { className: "wsc-badge" + (state.keyState[b.keyEnv]?.configured ? " wsc-badgeOn" : ""), children: state.keyState[b.keyEnv]?.configured ? props.t("keySet") : props.t("keyUnset") }),
+								state.keyState[b.keyEnv]?.configured && state.keyState[b.keyEnv]?.writable === false && react_jsx_runtime.jsx("span", { className: "wsc-badge", style: { opacity: .75 }, children: props.t("envProvided") }),
 							] }),
 						] }),
 						react_jsx_runtime.jsx("input", {
 							className: "wsc-keyInput", type: "password", autoComplete: "off",
-							placeholder: b.keyEnv,
+							disabled: state.keyState[b.keyEnv]?.configured && state.keyState[b.keyEnv]?.writable === false,
+							placeholder: (state.keyState[b.keyEnv]?.configured && state.keyState[b.keyEnv]?.writable === false) ? props.t("readOnly") : b.keyEnv,
 							value: state.stagedKeys[b.keyEnv] ?? "",
 							onChange: (e) => card.editKey(b.keyEnv, e.target.value),
 						}),
 						react_jsx_runtime.jsx("p", { className: "wsc-hint", children: props.t("keyHint") }),
+						state.failedKeys.includes(b.keyEnv) && react_jsx_runtime.jsx("p", { className: "wsc-hint", style: { color: "#e5534b" }, children: props.t("keyFailed") }),
 					] }, b.id)
 				) }),
 				state.stagedCount > 0 && react_jsx_runtime.jsx("p", { style: { margin: 0, fontSize: 12, opacity: .6 }, children: props.t("unsavedHint") }),
@@ -474,6 +505,7 @@ window.__ModuleLoader__.load({
 					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") }),
 					(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.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") }),
 				] }),
 			] });

package/lib/index.js

@@ -141,6 +141,8 @@ export const Config = z.object({
     .description("去重策略：url 仅按链接；url+title 额外合并同标题的转载镜像"),
   rerank: z.boolean().default(false)
     .description("按查询词相关性重排序（确定性、并列时保持后端优先级）"),
+  resultTelemetry: z.boolean().default(true)
+    .description("在搜索结果尾部附一行后端健康遥测（状态+耗时），模型可据此自诊断"),
 
   // Enable toggles (one per backend)
   enableExa: z.boolean().default(true).description(DEFAULT_LABELS.exa),
@@ -265,6 +267,7 @@ export function resolveOptions(ctx, config) {
     // v2.1 shaping options consumed by the provider merge pipeline.
     dedupStrategy: config?.dedupStrategy === "url+title" ? "url+title" : "url",
     rerank: config?.rerank === true,
+    resultTelemetry: config?.resultTelemetry !== false,
     filters: {
       recency: typeof config?.recency === "string" && config.recency !== "any" ? config.recency : undefined,
       lang: language.length > 0 ? language : undefined,

package/lib/provider.js

@@ -119,6 +119,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       const effectiveRequest =
         Object.keys(filters).length > 0 ? { ...request, filters } : request;
 
+      const telemetry = [];
       // Concurrency limiter
       const limit = createLimiter(opts.concurrency ?? 6);
 
@@ -128,6 +129,7 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       // reclassified as WEB_PROVIDER_ERROR so timeouts surface as real
       // failures instead of being silently demoted like user cancellations.
       const runBackend = ({ id, backend, beOpts, hooks }) => {
+        const startedAtMs = Date.now();
         const controller = new AbortController();
         const mergedSignal = signal
           ? AbortSignal.any([signal, controller.signal])
@@ -135,6 +137,16 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
         const timeoutId = setTimeout(() => controller.abort(), backendTimeoutMs);
         return backend
           .search(effectiveRequest, mergedSignal, beOpts, hooks)
+          .then(
+            (value) => {
+              telemetry.push({ id, ok: true, ms: Date.now() - startedAtMs, count: value?.sources?.length ?? 0 });
+              return value;
+            },
+            (err) => {
+              telemetry.push({ id, ok: false, ms: Date.now() - startedAtMs, error: String(err instanceof Error ? err.message : err).slice(0, 80) });
+              throw err;
+            },
+          )
           .catch((err) => {
             if (controller.signal.aborted && !(signal && signal.aborted)) {
               throw new WebError(
@@ -170,7 +182,10 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
       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;
@@ -182,9 +197,9 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
           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: "abort", err });
+            else failures.push({ id: failedId, err });
           } else {
-            failures.push({ id: "error", err });
+            failures.push({ id: failedId, err });
             if (hardError === null) hardError = err;
           }
         }
@@ -208,20 +223,33 @@ 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);
+        let outContent = mergedContent;
+        if (opts.resultTelemetry !== false && telemetry.length > 0) {
+          const line = "[websearch backends] " + telemetry
+            .map((t) => t.id + (t.ok ? " ✓" : " ✗") + t.ms + "ms" + (t.ok ? "/" + t.count : ""))
+            .join(" · ");
+          outContent = outContent === undefined ? line : outContent + "\n\n" + line;
+        }
         return {
           sources,
-          ...(mergedContent !== undefined ? { content: mergedContent } : {}),
+          ...(outContent !== undefined ? { content: outContent } : {}),
           truncated: ordered.length > maxResults,
         };
       }
 
-      // All enabled backends failed — synthesize a meaningful WEB_PROVIDER_ERROR.
-      const firstDetail =
-        hardError instanceof Error
-          ? hardError.message
-          : String(hardError ?? "unknown");
+      // All enabled backends failed - synthesize one meaningful error that
+      // names each backend's own reason so the caller (model or user) can act.
+      const detail = failures.slice(0, 4)
+        .map((f) => f.id + ": " + String(f.err instanceof Error ? f.err.message : f.err).slice(0, 120))
+        .join("; ");
+      const allKeyMissing =
+        failures.length > 0 &&
+        failures.every((f) => f.err instanceof WebError && f.err.code === "WEB_PROVIDER_UNAVAILABLE");
+      const hint = allKeyMissing
+        ? " (every enabled backend is missing its API key - add keys in Settings > Web Search, or enable a keyless backend)"
+        : "";
       throw new WebError(
-        `unified search: all enabled backends failed (${failures.length}). First: ${firstDetail}`,
+        `unified search: all enabled backends failed (${failures.length}) - ${detail}` + hint,
         "WEB_PROVIDER_ERROR",
         { cause: hardError ?? undefined },
       );

package/lib/util/log.js

@@ -1,51 +1,65 @@
 /**
  * @module dsh-websearch/util/log
  *
- * Emit a structured "search/backend-request" event onto the current session,
- * so debugging / token-cost attribution is possible from the dsh session log.
- * Mirrors the official dsh-web-search-deepseek `recordRequest` pattern but
- * is per-backend (each backend records its own endpoint + body so it is
- * auditable which backend fired which request).
+ * Per-backend request/outcome diagnostics.
  *
- * Resilient to missing agents plane — if the session ledger is unavailable,
- * the call silently no-ops (we MUST NOT break search just because we can't
- * record an audit row).
+ * IMPORTANT: these intentionally go to the HOST logger (ctx.logger), NOT to
+ * the session ledger. The session event vocabulary is a closed, generated set
+ * (@deepseek-ai/dsh-session known-event-types): the persistence read path
+ * refuses to interpret ANY session containing an envelope type outside that
+ * set unless the ENVELOPE carries ignorable: true -- and the runtime
+ * session.append() API provides no way to set that envelope marker (its opts
+ * carry only sourceEventSeqs/surfaceOp). A third-party plugin writing custom
+ * types therefore poisons the whole session log: writes succeed, the next
+ * continue/load refuses. Mirroring the in-repo web/deepseek-search-llm-request
+ * pattern is not available to out-of-repo packages by construction.
+ *
+ * Both emitters are best-effort and never throw: diagnostics must not break
+ * search.
  */
 
+/** One-line summary safe for the host log. */
+function summarize(request) {
+  try {
+    const body = request && request.body ? JSON.stringify(request.body) : "";
+    const trimmed = body.length > 200 ? body.slice(0, 200) + "..." : body;
+    return String((request && request.endpoint) || "") +
+      (request && request.toolName ? " tool=" + request.toolName : "") +
+      (trimmed ? " body=" + trimmed : "");
+  } catch {
+    return String(request && request.endpoint);
+  }
+}
+
 /**
- * Record one backend request to the current session's event ledger.
+ * Record one backend request to the host log.
  *
- * @param {object} ctx - the Cordis plugin context (`ctx.get("agents")`).
- * @param {string} backendId - e.g. "exa" / "parallel" / "ddg" / "deepseek" / "anthropic" / "openai".
- * @param {object} request - { endpoint, toolName, body, headers? } — headers are
- *   filtered by the caller (do not pass Authorization/x-api-key here).
+ * @param {object} ctx - the Cordis plugin context (ctx.logger).
+ * @param {string} backendId - e.g. exa / parallel / brave.
+ * @param {object} request - { endpoint, toolName, body } - never includes secrets.
  */
 export function recordBackendRequest(ctx, backendId, request) {
   try {
-    const agents = ctx.get?.("agents");
-    const initiator = agents?.currentInitiator?.();
-    const session = initiator?.session;
-    if (session?.append) {
-      session.append("web/unified-search-backend-request", { backendId, ...request, ignorable: true });
-    }
+    const logger = ctx && ctx.logger;
+    if (!logger || typeof logger.debug !== "function") return;
+    logger.debug("[websearch:" + backendId + "] request " + summarize(request));
   } catch {
-    // audit logging is best-effort; never fatal
+    // best-effort; never fatal
   }
 }
 
 /**
- * Record a backend's final outcome (number of sources returned / error message).
- * Pairs with recordBackendRequest; useful for token-cost attribution.
+ * Record a backend's final outcome (sources count / error message) to the host log.
  */
 export function recordBackendOutcome(ctx, backendId, outcome) {
   try {
-    const agents = ctx.get?.("agents");
-    const initiator = agents?.currentInitiator?.();
-    const session = initiator?.session;
-    if (session?.append) {
-      session.append("web/unified-search-backend-outcome", { backendId, ...outcome, ignorable: true });
-    }
+    const logger = ctx && ctx.logger;
+    if (!logger) return;
+    const status = outcome && typeof outcome.status === "string" ? outcome.status : "";
+    const line = "[websearch:" + backendId + "] outcome " + JSON.stringify(outcome ?? {});
+    if (status === "error" && typeof logger.warn === "function") logger.warn(line);
+    else if (typeof logger.debug === "function") logger.debug(line);
   } catch {
     // best-effort
   }
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@240xu/dsh-websearch",
-  "version": "2.1.1",
-  "description": "Unified web search provider for DeepSeek Harness (ctx.web): 11 backends — Exa + Parallel + DDG + SearXNG (keyless), DeepSeek + Anthropic + OpenAI + Brave + Tavily + Serper + Mojeek (key-gated via Settings credentials). Registers provider id \"unified\" for zero-config web_search tool.",
+  "version": "2.3.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.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {