dsh-free-search 0.4.5 → 0.4.6

package/README.en.md

@@ -28,7 +28,7 @@ This plugin provides multiple free search engines with automatic fallback, compl
 - **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Perplexity, and DeepSeek Official
 - **Web Settings UI** — Engine switching and API key configuration (API keys are masked in the UI and displayed as "configured")
 - **Engine Testing Tool** — `free_search_test`, allowing the agent to test the availability of all engines in a single call
-- **Automatic Fallback** — Automatically falls back to the next available free engine if one fails or gets rate-limited
+- **Unified Engine Fallback** — Any engine failure (paid or free, missing key, 401, rate limit, network error) automatically tries the next engine: other paid engines with configured keys first, then free engines. Search never fails outright.
 - **System Prompt Injection** — The agent is aware of the currently active engine and which engines require API keys
 - **Visual Badges** — Free engines feature a green `FREE` badge, while paid engines show an orange `API KEY` badge in the settings UI
 - **Webpage Fetching (`web_fetch`)** — Allows the agent to read full webpage contents (official `dsh-web-fetch-http` provider, pure JS, zero extra dependencies)
@@ -49,7 +49,7 @@ This plugin provides multiple free search engines with automatic fallback, compl
 | `deepseek-official` | DeepSeek Official | Paid | Requires `DEEPSEEK_API_KEY` |
 
 - **Default engine is `bing`** (free and most stable), ready to use out of the box after installation.
-- **Auto-failover**: any engine failure (rate-limited free engine, or missing/invalid paid key, network error) automatically falls back to a working free engine (Bing/AnySearch etc.) with a note attached to the results — a search never fails outright because of engine issues.
+- **Auto-failover**: any engine failure (rate-limited free engine, or missing/invalid paid key, network error) automatically tries the next engine — other paid engines with configured keys first, then free engines (Bing/AnySearch etc.) — with a note attached to the results. Search never fails outright because of engine issues.
 - **Official Links in Settings**: Free engines display "Visit Website →", while paid engines display "Get API Key →" (opens in a new tab):
   - Exa: <https://dashboard.exa.ai/api-keys>
   - Perplexity: <https://www.perplexity.ai/settings/api>
@@ -182,7 +182,7 @@ Windows users: The desktop shortcut already includes this configuration (`set NO
 
 ## How It Works
 
-- `lib/index.js`: Host side. Implements `WebSearchProvider` (`id` / `available()` / `search()`), multi-engine routing + auto-fallback; registers the `free-search` settings namespace; provides the `/api/dsh-free-search-settings` read/write bridge; registers the `free_search_test` tool; injects the engine list into system prompts.
+- `lib/index.js`: Host side. Implements `WebSearchProvider` (`id` / `available()` / `search()`), unified engine routing + auto-fallback (paid engines first, free as fallback); registers the `free-search` settings namespace; provides the `/api/dsh-free-search-settings` read/write bridge + `raw-search` debug endpoint; registers the `free_search_test` and `platform_search` tools; dynamically injects the engine list into system prompts (auto-refreshes on settings change).
 - `lib/client.js`: Browser side. React configuration card (engine select + key inputs), mounted into the official `settings.plugin.item` slot (Settings → Plugins → Configurable), without requiring `dsh-web-ui`.
 - `cordis.patch.yml`: Plugin loader configuration.
 

package/README.md

@@ -28,7 +28,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 - **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、Exa、Perplexity、DeepSeek 官方
 - **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）
 - **引擎测试工具** —— `free_search_test`，让 agent 一键测试所有引擎可用性
-- **自动回退** —— 免费引擎失败/限流时自动切换到下一个可用引擎
+- **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：先试其他已配 key 的付费引擎，再试免费引擎，搜索永不直接失败
 - **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
 - **免费标注** —— 设置页中免费引擎带绿色 `FREE` 徽章，付费引擎带橙色 `API KEY` 徽章
 - **网页抓取（web_fetch）** —— 让 agent 抓取网页内容（官方 `dsh-web-fetch-http` provider，纯 JS，零额外依赖）
@@ -49,7 +49,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 | `deepseek-official` | DeepSeek 官方 | 付费 | 需 `DEEPSEEK_API_KEY` |
 
 - **默认引擎为 `bing`**（免费且最稳定），安装后开箱即用。
-- **自动回退**：任何引擎失败（免费引擎限流/反爬，付费引擎缺 key/无效/网络错误）都会自动回退到可用的免费引擎（Bing/AnySearch 等），并在结果中附带回退提示——搜索不会因引擎问题直接失败。
+- **自动回退**：任何引擎失败（免费限流/反爬，付费缺 key/无效/网络错误）都会自动轮流尝试下一个引擎——先试其他已配 key 的付费引擎，再试免费引擎（Bing/AnySearch 等），并在结果中附带回退提示——搜索不会因引擎问题直接失败。
 - **设置页有官网链接**：免费引擎显示"访问官网 →"，付费引擎显示"获取 API Key →"（新标签页打开）：
   - Exa：<https://dashboard.exa.ai/api-keys>
   - Perplexity：<https://www.perplexity.ai/settings/api>
@@ -183,7 +183,7 @@ Windows 用户：桌面快捷方式已内置此配置（`set NODE_USE_ENV_PROXY=
 
 ## 工作原理
 
-- `lib/index.js`：host 端。实现 `WebSearchProvider`（`id` / `available()` / `search()`），多引擎路由 + 自动回退；注册 `free-search` settings namespace；提供 `/api/dsh-free-search-settings` 读写桥；注册 `free_search_test` 工具；注入引擎清单到系统提示词。
+- `lib/index.js`：host 端。实现 `WebSearchProvider`（`id` / `available()` / `search()`），统一引擎路由 + 自动回退（付费引擎优先，免费兜底）；注册 `free-search` settings namespace；提供 `/api/dsh-free-search-settings` 读写桥 + `raw-search` 调试接口；注册 `free_search_test` 和 `platform_search` 工具；动态注入引擎清单到系统提示词（设置变更时自动刷新）。
 - `lib/client.js`：浏览器端。React 配置卡片（引擎选择 + key 输入），挂载到官方设置页的 `settings.plugin.item` 插槽（设置 → 插件 → 可配置），不依赖 dsh-web-ui。
 - `cordis.patch.yml`：插件 loader 配置。
 

package/lib/client.js

@@ -388,6 +388,7 @@ window.__ModuleLoader__.load({
         ctx.slots.register(
           {
             name: "settings.plugin.item",
+            key: "free-search",
             id: "dsh-free-search",
             order: 120,
             inject: () => ({}),

package/lib/index.js

@@ -648,7 +648,7 @@ function toView(descriptor) {
   };
 }
 
-function makeBridgeRoutes(settings) {
+function makeBridgeRoutes(settings, search) {
   const allowlisted = () =>
     settings
       .describe({ redactSecrets: true })
@@ -656,6 +656,28 @@ function makeBridgeRoutes(settings) {
       .map((descriptor) => String(descriptor.ns));
 
   const handlers = {
+    async rawSearch(request) {
+      if (request === null || typeof request !== "object" || typeof request.query !== "string" || request.query.length === 0) {
+        return { ok: false, code: "search-rejected", message: "malformed bridge search request (query is required)" };
+      }
+      if (typeof search !== "function") {
+        return { ok: false, code: "search-unavailable", message: "search provider is not wired" };
+      }
+      const maxResults = Math.min(Math.max(Number(request.maxResults) || 5, 1), 10);
+      try {
+        const result = await search(request.query, maxResults);
+        return {
+          ok: true,
+          value: {
+            provider: (settings.describe({ redactSecrets: true }).find((c) => String(c.ns) === FREE_SEARCH_NS)?.schema ?? {}).provider ?? undefined,
+            sources: result.sources ?? [],
+            content: result.content ?? "",
+          },
+        };
+      } catch (error) {
+        return { ok: false, code: "search-failed", message: error instanceof Error ? error.message : String(error) };
+      }
+    },
     async describe() {
       const descriptors = settings.describe({ redactSecrets: true });
       return {
@@ -730,6 +752,19 @@ function makeBridgeRoutes(settings) {
         writeJson(res, 200, await handlers.mutate(body));
       },
     },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/raw-search`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        const body = await readJsonBody(req);
+        if (body === undefined) {
+          writeJson(res, 400, { ok: false, code: "search-rejected", message: "malformed JSON body" });
+          return;
+        }
+        writeJson(res, 200, await handlers.rawSearch(body));
+      },
+    },
   ];
 }
 //#endregion
@@ -753,6 +788,9 @@ function apply(ctx, config) {
   const logger = ctx.logger;
   const credentials = ctx.get("credentials");
 
+  // 系统提示词动态刷新：设置变更时重新生成，避免显示旧引擎
+  let refreshPrompt = null;
+
   // key 优先级：settings 的 free-search.<x>ApiKey > 环境变量/credentials
   const resolveApiKey = async (envName, settingsKey) => {
     const cfg = current();
@@ -767,8 +805,8 @@ function apply(ctx, config) {
   };
 
   // 总控 provider：按 settings 的 provider 字段路由到任意引擎。
-  // 任何引擎失败（缺 key / 401 / 限流 / 网络）都会自动回退到可用的免费引擎，
-  // 并在结果里附带回退提示，避免 agent 搜索直接失败。
+  // 任何引擎失败（缺 key / 401 / 限流 / 网络）都会自动轮流尝试下一个引擎，
+  // 直到成功或全部失败。并在结果里附带回退提示，避免 agent 搜索直接失败。
   const provider = {
     id: "ddg",
     available() {
@@ -778,83 +816,61 @@ function apply(ctx, config) {
       const cfg = current();
       const preferred = cfg.provider ?? "bing";
 
-      // 付费引擎：先尝试；失败（缺 key / 401 / 网络）则回退免费引擎链
-      let fallbackReason = null;
-      if (preferred === "exa" || preferred === "perplexity" || preferred === "deepseek-official") {
+      // 统一引擎链：首选优先，然后其他付费引擎（有 key 的优先尝试），最后免费引擎
+      const paidEngines = ["exa", "perplexity", "deepseek-official"];
+      const freeEngines = ["bing", "anysearch", "ddg", "ddg-lite", "searxng"];
+      const othersPaid = paidEngines.filter((e) => e !== preferred);
+      const othersFree = freeEngines.filter((e) => e !== preferred);
+      const chain = [preferred, ...othersPaid, ...othersFree];
+
+      let lastError = null;
+      let usedEngine = null;
+      for (const engine of chain) {
         try {
-          if (preferred === "exa") {
+          let result;
+          if (engine === "ddg") {
+            result = await searchDdgHtml(request.query, request.maxResults, cfg, signal);
+          } else if (engine === "ddg-lite") {
+            result = await searchDdgLite(request.query, request.maxResults, signal);
+          } else if (engine === "bing") {
+            result = await searchBing(request.query, request.maxResults, cfg, signal);
+          } else if (engine === "searxng") {
+            result = await searchSearxng(request.query, request.maxResults, cfg, signal);
+          } else if (engine === "anysearch") {
+            result = await searchAnysearch(request.query, request.maxResults, signal);
+          } else if (engine === "exa") {
+            // exa：有 key 走 REST，无 key 走 keyless MCP（免费）
             const key = await resolveApiKey("EXA_API_KEY", "exaApiKey");
             if (key) {
-              const result = await searchExa(request.query, request.maxResults, key, signal);
-              if (result.sources.length > 0) return result;
-              fallbackReason = "Exa returned no results";
+              result = await searchExa(request.query, request.maxResults, key, signal);
             } else {
-              // exa 无 key 时走 keyless MCP（免费）
-              try {
-                const result = await searchExaMCP(request.query, request.maxResults, signal);
-                if (result.sources.length > 0) return result;
-                fallbackReason = "Exa keyless MCP returned no results";
-              } catch (mcpError) {
-                fallbackReason = mcpError instanceof Error ? mcpError.message : String(mcpError);
-              }
+              result = await searchExaMCP(request.query, request.maxResults, signal);
             }
-          } else if (preferred === "perplexity") {
+          } else if (engine === "perplexity") {
             const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
-            if (!key) throw new Error("Perplexity search requires PERPLEXITY_API_KEY");
-            const result = await searchPerplexity(request.query, request.maxResults, key, signal);
-            if (result.sources.length > 0) return result;
-            fallbackReason = "Perplexity returned no results";
-          } else {
+            if (!key) {
+              lastError = new Error("Perplexity requires PERPLEXITY_API_KEY");
+              logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
+              continue; // 无 key 跳过
+            }
+            result = await searchPerplexity(request.query, request.maxResults, key, signal);
+          } else if (engine === "deepseek-official") {
             const key = await resolveApiKey("DEEPSEEK_API_KEY", "deepseekApiKey");
-            if (!key) throw new Error("DeepSeek search requires DEEPSEEK_API_KEY");
-            const result = await searchDeepSeekOfficial(request.query, request.maxResults, key, signal);
-            if (result.sources.length > 0) return result;
-            fallbackReason = "DeepSeek search returned no results";
+            if (!key) {
+              lastError = new Error("DeepSeek requires DEEPSEEK_API_KEY");
+              logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
+              continue; // 无 key 跳过
+            }
+            result = await searchDeepSeekOfficial(request.query, request.maxResults, key, signal);
+          } else {
+            continue;
           }
-        } catch (error) {
-          fallbackReason = error instanceof Error ? error.message : String(error);
-          logger.warn(`free-search: paid engine "${preferred}" failed (${fallbackReason}), falling back to free engines`);
-        }
-      }
 
-      // 免费引擎链（付费引擎失败时也走这里）
-      const chain =
-        preferred === "ddg-lite"
-          ? ["ddg-lite", "ddg", "anysearch", "searxng", "bing"]
-          : preferred === "bing"
-            ? ["bing", "anysearch", "searxng", "ddg", "ddg-lite"]
-            : preferred === "searxng"
-              ? ["searxng", "anysearch", "bing", "ddg", "ddg-lite"]
-              : preferred === "anysearch"
-                ? ["anysearch", "bing", "searxng", "ddg", "ddg-lite"]
-                : ["bing", "anysearch", "searxng", "ddg", "ddg-lite"];
-      let lastError = null;
-      for (const engine of chain) {
-        try {
-          let result;
-          switch (engine) {
-            case "ddg":
-              result = await searchDdgHtml(request.query, request.maxResults, cfg, signal);
-              break;
-            case "ddg-lite":
-              result = await searchDdgLite(request.query, request.maxResults, signal);
-              break;
-            case "bing":
-              result = await searchBing(request.query, request.maxResults, cfg, signal);
-              break;
-            case "searxng":
-              result = await searchSearxng(request.query, request.maxResults, cfg, signal);
-              break;
-            case "anysearch":
-              result = await searchAnysearch(request.query, request.maxResults, signal);
-              break;
-            default:
-              result = await searchDdgHtml(request.query, request.maxResults, cfg, signal);
-          }
           if (result.sources.length > 0) {
-            // 付费引擎失败回退时，在结果里附上提示（agent 会看到）
-            if (fallbackReason) {
-              result.content = `Note: ${preferred} search unavailable (${fallbackReason}). Results from ${engine}.`;
+            usedEngine = engine;
+            // 用了非首选引擎时，在结果里附上提示（agent 会看到）
+            if (engine !== preferred) {
+              result.content = `Note: ${preferred} unavailable or failed, using ${engine}.`;
             }
             return result;
           }
@@ -874,12 +890,17 @@ function apply(ctx, config) {
     setSource: (source) => {
       current = source;
     },
-    onChange: () => {},
+    onChange: () => {
+      // settings 变更时刷新系统提示词（显示最新引擎）
+      if (typeof refreshPrompt === "function") refreshPrompt();
+    },
   });
 
   ctx.inject(["webServer", "settings"], (sctx) => {
     sctx.effect(() => {
-      const disposers = makeBridgeRoutes(sctx.settings).map((route) => sctx.webServer.register(route));
+      const disposers = makeBridgeRoutes(sctx.settings, (query, maxResults) => provider.search({ query, maxResults }, undefined)).map((route) =>
+        sctx.webServer.register(route)
+      );
       return () => {
         for (const dispose of disposers) dispose();
       };
@@ -1100,10 +1121,15 @@ function apply(ctx, config) {
     }, "free-search: platform search tool");
   });
 
-  // 让 agent 知道可用搜索引擎（动态生成，随 key 配置变化）
+  // 让 agent 知道可用搜索引擎（动态生成，随 key/设置变化）
   ctx.inject(["systemPrompt"], (sctx) => {
-    sctx.effect(() => {
-      const section = {
+    let disposeSection = null;
+    refreshPrompt = () => {
+      if (disposeSection) {
+        disposeSection();
+        disposeSection = null;
+      }
+      disposeSection = sctx.systemPrompt.section({
         name: "free-search:engines",
         order: 500,
         text: [
@@ -1122,16 +1148,19 @@ function apply(ctx, config) {
           "- perplexity - requires PERPLEXITY_API_KEY",
           "- deepseek-official - requires DEEPSEEK_API_KEY",
           "",
-          "FREE engines auto-fallback to another FREE engine on failure. Paid engines fail with a clear error when their key is missing - tell the user which key to configure.",
+          "IMPORTANT: If the configured engine fails (missing key, invalid key, 401, rate limit, or network error), web_search automatically tries other engines in this order: (1) other PAID engines whose API key is configured, (2) then FREE engines (Bing, AnySearch, DuckDuckGo, SearXNG). This applies to ALL engines - paid or free. The results include a note showing which engine was actually used. Never tell the user search is unavailable - it always falls back.",
           "",
           "Use the free_search_test tool to test which engines actually work right now.",
           "",
           "For platform-specific searches (GitHub repos, V2EX threads, Bilibili videos), use the platform_search tool with platform: github|v2ex|bilibili.",
         ].join("\n"),
-      };
-      const dispose = sctx.systemPrompt.section(section);
+      });
+    };
+    sctx.effect(() => {
+      refreshPrompt();
       return () => {
-        dispose();
+        if (disposeSection) disposeSection();
+        disposeSection = null;
       };
     }, "free-search: engine list prompt section");
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-free-search",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Free web search for DeepSeek Harness: 8 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa keyless) + platform search + web_fetch, with web settings UI.",
   "type": "module",
   "main": "lib/index.js",
@@ -41,12 +41,12 @@
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-settings": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.7"
   },
   "dsh": {
     "bundle": {