dsh-free-search 0.4.28 → 0.4.29

package/README.md

@@ -29,7 +29,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 ### 特性
 
 - **零成本** —— 多个免费引擎，无需 key、无需注册
-- **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、DeepSeek 官方
+- **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase、DeepSeek 官方
 - **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换
 - **弹出式切换命令** —— 聊天框输入 `/free-search-engine`，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
 - **引擎测试** —— `free_search_test` 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
@@ -60,6 +60,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 | `firecrawl` | Firecrawl | 免费 | **无 key 也可用**（官方免 key 匿名额度），配 key 提升限额 |
 | `parallel` | Parallel | 付费 | 需 `PARALLEL_API_KEY`（platform.parallel.ai 有免费额度） |
 | `perplexity` | Perplexity | 付费 | 需 `PERPLEXITY_API_KEY` |
+| `serpbase` | SerpBase | 付费 | 需 `SERPBASE_API_KEY`（serpbase.dev，注册送 100 次免费额度） |
 | `deepseek-official` | DeepSeek 官方 | 付费 | 需 `DEEPSEEK_API_KEY` |
 
 - **默认引擎为 `bing`**（免费且最稳定），安装后开箱即用。
@@ -70,6 +71,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
   - Keenable：<https://keenable.ai/login>
   - Parallel：<https://platform.parallel.ai>
   - Perplexity：<https://www.perplexity.ai/settings/api>
+  - SerpBase：<https://serpbase.dev>
   - DeepSeek：<https://platform.deepseek.com/api_keys>
 
 #### 为什么免费引擎不需要 key？
@@ -152,7 +154,7 @@ dsh web
 
 ```yaml
 free-search:
-  provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / deepseek-official
+  provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / serpbase / deepseek-official
   lang: zh                    # 设置页界面语言（zh / en）
   bingMarket: zh-CN           # Bing 市场
   region: cn-zh               # DuckDuckGo 区域（可选）
@@ -164,6 +166,7 @@ free-search:
   firecrawlApiKey: ...        # 或通过设置页填写
   parallelApiKey: ...         # 或通过设置页填写
   perplexityApiKey: ...
+  serpbaseApiKey: ...         # 或通过设置页填写
   deepseekApiKey: ...
 ```
 
@@ -290,7 +293,7 @@ This plugin provides multiple free search engines with automatic fallback, compl
 ### Features
 
 - **Zero Cost** — Multiple free engines with no API key or registration required
-- **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Tavily, Keenable, Firecrawl, Parallel, Perplexity, and DeepSeek Official
+- **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Tavily, Keenable, Firecrawl, Parallel, Perplexity, SerpBase, and DeepSeek Official
 - **Web Settings UI** — Engine switching, API key configuration (keys masked as "configured" in the UI), and a Chinese/English toggle
 - **Popup Switch Command** — Type `/free-search-engine` in the chat: a picker opens with all engines; click one to switch (equivalent to the settings page + save)
 - **Engine Testing** — `free_search_test` for the agent to check all engines in one call; the settings UI also has a "Test engine" button that tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error)
@@ -321,6 +324,7 @@ If this plugin has been helpful, a ⭐ on [GitHub](https://github.com/DDDMUC/dsh
 | `firecrawl` | Firecrawl | Free | **Usable without a key** (official keyless anonymous quota); configure a key for higher limits |
 | `parallel` | Parallel | Paid | Requires `PARALLEL_API_KEY` (free tier available at platform.parallel.ai) |
 | `perplexity` | Perplexity | Paid | Requires `PERPLEXITY_API_KEY` |
+| `serpbase` | SerpBase | Paid | Requires `SERPBASE_API_KEY` (serpbase.dev, 100 free queries on signup) |
 | `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.
@@ -331,6 +335,7 @@ If this plugin has been helpful, a ⭐ on [GitHub](https://github.com/DDDMUC/dsh
   - Keenable: <https://keenable.ai/login>
   - Parallel: <https://platform.parallel.ai>
   - Perplexity: <https://www.perplexity.ai/settings/api>
+  - SerpBase: <https://serpbase.dev>
   - DeepSeek: <https://platform.deepseek.com/api_keys>
 
 #### Why are some engines free?
@@ -413,7 +418,7 @@ Configuration is stored in `~/.dsh/settings.yaml`:
 
 ```yaml
 free-search:
-  provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / deepseek-official
+  provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / serpbase / deepseek-official
   lang: zh                    # settings UI language (zh / en)
   bingMarket: zh-CN           # Bing market
   region: cn-zh               # DuckDuckGo region (optional)
@@ -425,6 +430,7 @@ free-search:
   firecrawlApiKey: ...        # Or configure via the web settings UI
   parallelApiKey: ...         # Or configure via the web settings UI
   perplexityApiKey: ...
+  serpbaseApiKey: ...         # Or configure via the web settings UI
   deepseekApiKey: ...
 ```
 

package/lib/client.js

@@ -96,11 +96,12 @@ window.__ModuleLoader__.load({
         parallelPh: (c) => c ? "Parallel API 密钥（已配置）" : "Parallel API 密钥（必填，platform.parallel.ai）",
         perplexityPh: (c) => c ? "Perplexity API 密钥（已配置）" : "Perplexity API 密钥（pplx-...）",
         deepseekPh: (c) => c ? "DeepSeek API 密钥（已配置）" : "DeepSeek API 密钥（sk-...）",
+        serpbasePh: (c) => c ? "SerpBase API 密钥（已配置）" : "SerpBase API 密钥（serpbase.dev 获取）",
         keysHint: "密钥读取优先级：.credentials.yaml 凭据中心 > 这里 > 环境变量。推荐把 key 写进凭据中心（与官方 LLM 一致，一处管理）。",
         keyStorage: "Key 存储位置",
         keyStorageCred: "凭据中心（推荐）",
         keyStorageSettings: "设置页（兼容）",
-        keyStorageCredHint: (c) => `保存后写入 ~/.dsh/.credentials.yaml（最高优先级）。当前已配置：${["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "无"}`,
+        keyStorageCredHint: (c) => `保存后写入 ~/.dsh/.credentials.yaml（最高优先级）。当前已配置：${["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "serpbase", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "无"}`,
         keyStorageSettingsHint: "保存后写入 settings.yaml（向后兼容路径，优先级低于凭据中心）。",
         platformSearch: "平台搜索（platform_search 工具）",
         platformHint: "为 agent 的 platform_search 工具启用平台。禁用的平台会被跳过。",
@@ -162,11 +163,12 @@ window.__ModuleLoader__.load({
         parallelPh: (c) => c ? "Parallel API key (configured)" : "Parallel API key (required, platform.parallel.ai)",
         perplexityPh: (c) => c ? "Perplexity API key (configured)" : "Perplexity API key (pplx-...)",
         deepseekPh: (c) => c ? "DeepSeek API key (configured)" : "DeepSeek API key (sk-...)",
+        serpbasePh: (c) => c ? "SerpBase API key (configured)" : "SerpBase API key (from serpbase.dev)",
         keysHint: "Key resolution: .credentials.yaml credential center > here > environment variables. Recommended: store keys in the credential center (same as official LLM providers, one place for all).",
         keyStorage: "Key storage",
         keyStorageCred: "Credential center (recommended)",
         keyStorageSettings: "Settings page (legacy)",
-        keyStorageCredHint: (c) => `Saved to ~/.dsh/.credentials.yaml (highest priority). Currently configured: ${["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "none"}`,
+        keyStorageCredHint: (c) => `Saved to ~/.dsh/.credentials.yaml (highest priority). Currently configured: ${["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "serpbase", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "none"}`,
         keyStorageSettingsHint: "Saved to settings.yaml (backward-compatible path; lower priority than the credential center).",
         platformSearch: "Platform search (platform_search tool)",
         platformHint: "Enable platforms for the agent's platform_search tool. Disabled platforms are skipped.",
@@ -216,7 +218,7 @@ window.__ModuleLoader__.load({
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
     // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION 保持一致）
-    const PLUGIN_VERSION = "0.4.28";
+    const PLUGIN_VERSION = "0.4.29";
     const ENGINES = [
       { id: "ddg", label: "DuckDuckGo · HTML", badge: "FREE", link: "https://duckduckgo.com" },
       { id: "ddg-lite", label: "DuckDuckGo · Lite", badge: "FREE", link: "https://duckduckgo.com" },
@@ -229,6 +231,7 @@ window.__ModuleLoader__.load({
       { id: "firecrawl", label: "Firecrawl", badge: "FREE", link: "https://www.firecrawl.dev" },
       { id: "parallel", label: "Parallel", badge: "API KEY", link: "https://platform.parallel.ai" },
       { id: "perplexity", label: "Perplexity", badge: "API KEY", link: "https://www.perplexity.ai/settings/api" },
+      { id: "serpbase", label: "SerpBase · Google", badge: "API KEY", link: "https://serpbase.dev" },
       { id: "deepseek-official", label: "DeepSeek Official", badge: "API KEY", link: "https://platform.deepseek.com/api_keys" },
     ];
 
@@ -328,6 +331,7 @@ window.__ModuleLoader__.load({
       const [parallelKey, setParallelKey] = react.useState("");
       const [perplexityKey, setPerplexityKey] = react.useState("");
       const [deepseekKey, setDeepseekKey] = react.useState("");
+      const [serpbaseKey, setSerpbaseKey] = react.useState("");
       const [platforms, setPlatforms] = react.useState(["github", "v2ex", "bilibili", "reddit", "hn", "stackoverflow", "wikipedia", "npm"]);
       const [cacheTtl, setCacheTtl] = react.useState(5);
       const [keysConfigured, setKeysConfigured] = react.useState({});
@@ -363,6 +367,7 @@ window.__ModuleLoader__.load({
               setParallelKey(v.parallelApiKey ?? "");
               setPerplexityKey(v.perplexityApiKey ?? "");
               setDeepseekKey(v.deepseekApiKey ?? "");
+              setSerpbaseKey(v.serpbaseApiKey ?? "");
               setPlatforms(Array.isArray(v.platforms) && v.platforms.length > 0 ? v.platforms : ["github", "v2ex", "bilibili", "reddit", "hn", "stackoverflow", "wikipedia", "npm"]);
               setCacheTtl(v.cacheTtl === undefined ? 5 : Math.min(Math.max(Number(v.cacheTtl) ?? 5, 0), 5));
               // secrets 字段标记哪些 key 已配置（值被脱敏，仅显示"已配置"）
@@ -377,6 +382,7 @@ window.__ModuleLoader__.load({
                   if (path === "parallelApiKey") configured.parallel = true;
                   if (path === "perplexityApiKey") configured.perplexity = true;
                   if (path === "deepseekApiKey") configured.deepseek = true;
+                  if (path === "serpbaseApiKey") configured.serpbase = true;
                 }
               }
               setKeysConfigured(configured);
@@ -388,7 +394,7 @@ window.__ModuleLoader__.load({
                 const cred = await bridgeCredentialsStatus();
                 if (cred.ok) {
                   const cc = {};
-                  const map = { exaApiKey: "exa", tavilyApiKey: "tavily", keenableApiKey: "keenable", firecrawlApiKey: "firecrawl", parallelApiKey: "parallel", perplexityApiKey: "perplexity", deepseekApiKey: "deepseek" };
+                  const map = { exaApiKey: "exa", tavilyApiKey: "tavily", keenableApiKey: "keenable", firecrawlApiKey: "firecrawl", parallelApiKey: "parallel", perplexityApiKey: "perplexity", deepseekApiKey: "deepseek", serpbaseApiKey: "serpbase" };
                   for (const [k, v] of Object.entries(cred.value.configured ?? {})) {
                     if (map[k]) cc[map[k]] = v;
                   }
@@ -429,6 +435,7 @@ window.__ModuleLoader__.load({
             ["parallelApiKey", parallelKey],
             ["perplexityApiKey", perplexityKey],
             ["deepseekApiKey", deepseekKey],
+            ["serpbaseApiKey", serpbaseKey],
           ];
           let credFailed = false;
           if (keyStorage === "credentials") {
@@ -766,6 +773,18 @@ react_jsx_runtime.jsx("div", {
                           setFailed(false);
                         },
                       }),
+                      react_jsx_runtime.jsx("input", {
+                        className: "dshfs-input",
+                        type: "password",
+                        placeholder: t.serpbasePh(keysConfigured.serpbase),
+                        value: serpbaseKey,
+                        disabled: !ready || saving,
+                        onChange: (e) => {
+                          setSerpbaseKey(e.target.value);
+                          setDirty(true);
+                          setFailed(false);
+                        },
+                      }),
                       react_jsx_runtime.jsx("input", {
                         className: "dshfs-input",
                         type: "password",

package/lib/index.js

@@ -13,6 +13,7 @@ const FIRECRAWL_URL = "https://api.firecrawl.dev/v2/search";
 const PARALLEL_URL = "https://api.parallel.ai/v1/search";
 const KEENABLE_URL = "https://api.keenable.ai/v1/search";
 const KEENABLE_MCP_URL = "https://api.keenable.ai/mcp";
+const SERPBASE_URL = "https://api.serpbase.dev/google/search";
 const USER_AGENT =
   "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36";
 const ACCEPT_LANG = "zh-CN,zh;q=0.9,en;q=0.8";
@@ -47,10 +48,10 @@ const MARKET_TO_LANG = {
 const FREE_SEARCH_NS = "free-search";
 const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
 const FREE_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch"];
-const ALL_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch", "exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "deepseek-official"];
+const ALL_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch", "exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "serpbase", "deepseek-official"];
 
 // 当前插件版本（发布时与 package.json 同步）
-const PLUGIN_VERSION = "0.4.28";
+const PLUGIN_VERSION = "0.4.29";
 // 检查更新的 npm registry 元数据地址（dsh-free-search 是 npmjs 上的公开包）
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/dsh-free-search/latest";
 const PLUGIN_NPM_URL = "https://www.npmjs.com/package/dsh-free-search";
@@ -758,7 +759,7 @@ async function searchPlatform(platform, query, maxResults, signal, lang) {
 }
 //#endregion
 
-//#region paid engines (exa / tavily / perplexity / deepseek-official)
+//#region paid engines (exa / tavily / perplexity / serpbase / deepseek-official)
 async function searchExa(query, maxResults, apiKey, timeRange, signal) {
   if (!apiKey) throw new Error("Exa search requires EXA_API_KEY");
   const body = {
@@ -1206,6 +1207,72 @@ async function searchDeepSeekOfficial(query, maxResults, apiKey, signal) {
   }
   return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
 }
+
+// SerpBase: 必须配置 SERPBASE_API_KEY（无 key 跳过，同 perplexity）
+// Google SERP API：POST + X-API-Key 头，返回 organic[]（title/link/snippet/published_at）。
+// 注意：SerpBase 始终返回 HTTP 200，业务状态放在 JSON 的 status 字段（0=成功，1001=key 无效/缺失，1000=请求非法）。
+const SERPBASE_LOCALE = {
+  zh: { hl: "zh-CN", gl: "cn" },
+  en: { hl: "en", gl: "us" },
+  ru: { hl: "ru", gl: "ru" },
+  ja: { hl: "ja", gl: "jp" },
+  de: { hl: "de", gl: "de" },
+  fr: { hl: "fr", gl: "fr" },
+  es: { hl: "es", gl: "es" },
+  ko: { hl: "ko", gl: "kr" },
+};
+
+async function searchSerpbase(query, maxResults, apiKey, options, signal) {
+  if (!apiKey) throw new Error("SerpBase search requires SERPBASE_API_KEY");
+  // hl/gl 跟随设置页的 lang（SerpBase 支持 Google 的 hl/gl 本地化），默认 en/us
+  const locale = SERPBASE_LOCALE[options?.lang] ?? SERPBASE_LOCALE.en;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15000);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort);
+  let response;
+  try {
+    response = await fetch(SERPBASE_URL, {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        "X-API-Key": apiKey,
+        "content-type": "application/json",
+        accept: "application/json",
+        "user-agent": "deepseek-harness/free-search",
+      },
+      body: JSON.stringify({ q: query, hl: locale.hl, gl: locale.gl, page: 1 }),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    throw new Error(`SerpBase request failed: ${error?.message ?? String(error)}`);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(`SerpBase API error (HTTP ${response.status}): ${detail.slice(0, 200)}`);
+  }
+  // HTTP 200 + status 字段：0 成功 / 1001 key 无效或缺 / 1000 请求非法
+  const data = await response.json();
+  if (data.status !== 0) {
+    if (data.status === 1001) {
+      throw new Error("SerpBase API key is invalid or missing (status 1001) - update it in Settings > Plugins > Free Search");
+    }
+    throw new Error(`SerpBase API error (status ${data.status}): ${String(data.error ?? "").slice(0, 200)}`);
+  }
+  const sources = (data.organic ?? [])
+    .filter((r) => r.link)
+    .map((r) => ({
+      url: r.link,
+      ...(r.title ? { title: String(r.title) } : {}),
+      ...(r.snippet ? { snippet: String(r.snippet) } : {}),
+      ...((r.published_at ?? r.date) ? { publishedAt: String(r.published_at ?? r.date) } : {}),
+    }));
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
 //#endregion
 
 //#region bridge
@@ -1582,6 +1649,7 @@ const KEY_REF_MAP = {
   firecrawlApiKey: "FIRECRAWL_API_KEY",
   parallelApiKey: "PARALLEL_API_KEY",
   perplexityApiKey: "PERPLEXITY_API_KEY",
+  serpbaseApiKey: "SERPBASE_API_KEY",
   deepseekApiKey: "DEEPSEEK_API_KEY",
 };
 
@@ -1602,6 +1670,7 @@ const Config = z.object({
   firecrawlApiKey: z.string().role("secret"),
   parallelApiKey: z.string().role("secret"),
   perplexityApiKey: z.string().role("secret"),
+  serpbaseApiKey: z.string().role("secret"),
   deepseekApiKey: z.string().role("secret"),
 });
 
@@ -1675,7 +1744,7 @@ function apply(ctx, config) {
       }
 
       // 统一引擎链：首选优先，然后其他付费引擎（有 key 的优先尝试），最后免费引擎
-      const paidEngines = ["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "deepseek-official"];
+      const paidEngines = ["exa", "tavily", "keenable", "firecrawl", "parallel", "perplexity", "serpbase", "deepseek-official"];
       const freeEngines = ["bing", "anysearch", "ddg", "ddg-lite", "searxng"];
       // 支持 time_range 过滤的引擎：tavily / exa / keenable / firecrawl / parallel / searxng / ddg / ddg-lite
       const timeEngines = ["tavily", "exa", "keenable", "firecrawl", "parallel", "searxng", "ddg", "ddg-lite"];
@@ -1775,6 +1844,16 @@ function apply(ctx, config) {
               continue; // 无 key 跳过
             }
             result = await searchDeepSeekOfficial(request.query, request.maxResults, key, effSignal);
+          } else if (engine === "serpbase") {
+            // serpbase：必须配置 SERPBASE_API_KEY（无 key 跳过，同 perplexity）
+            const key = await resolveApiKey("SERPBASE_API_KEY", "serpbaseApiKey");
+            if (!key) {
+              lastError = new Error("SerpBase requires SERPBASE_API_KEY");
+              if (engine === preferred) preferredFailure = "SERPBASE_API_KEY is not configured";
+              logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
+              continue; // 无 key 跳过
+            }
+            result = await searchSerpbase(request.query, request.maxResults, key, cfg, effSignal);
           } else {
             continue;
           }
@@ -1933,6 +2012,11 @@ function apply(ctx, config) {
           if (!key) return { ok: false, error: "DEEPSEEK_API_KEY not configured" };
           return await searchDeepSeekOfficial(q, 2, key);
         }
+        case "serpbase": {
+          const key = await resolveApiKey("SERPBASE_API_KEY", "serpbaseApiKey");
+          if (!key) return { ok: false, error: "SERPBASE_API_KEY not configured" };
+          return await searchSerpbase(q, 2, key, cfg);
+        }
         default:
           return { ok: false, error: `unknown engine: ${engine}` };
       }
@@ -1968,7 +2052,7 @@ function apply(ctx, config) {
           parameters: {
             engines: {
               type: "array",
-              description: "Which engines to test (default: all). Options: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, firecrawl, parallel, perplexity, deepseek-official.",
+              description: "Which engines to test (default: all). Options: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, firecrawl, parallel, perplexity, serpbase, deepseek-official.",
               items: { type: "string" },
             },
             query: {
@@ -2152,7 +2236,7 @@ function apply(ctx, config) {
             },
             engine: {
               type: "string",
-              description: "Optional specific engine to try first: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, firecrawl, parallel, perplexity, deepseek-official.",
+              description: "Optional specific engine to try first: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, firecrawl, parallel, perplexity, serpbase, deepseek-official.",
             },
           },
           output: {
@@ -2253,6 +2337,7 @@ function apply(ctx, config) {
           "- parallel - requires PARALLEL_API_KEY",
           "- perplexity - requires PERPLEXITY_API_KEY",
           "- deepseek-official - requires DEEPSEEK_API_KEY",
+          "- serpbase - Google organic results via API, requires SERPBASE_API_KEY (100 free queries on signup)",
           "",
           "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) the configured engine first, (2) then other engines with API keys configured (exa/tavily/keenable/firecrawl work keyless too, so they are tried even without a key), (3) then the remaining 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 and why the preferred one was skipped. Understand the two note forms: (a) 'Note: X does not support time filtering (timeRange=...), using Y.' means X cannot filter by time so it was skipped BEFORE any attempt (X did NOT fail); (b) 'Note: X unavailable or failed (reason), using Y.' means X was actually tried but failed (missing key / invalid key / 401 / rate limit / network / 0 results). Never tell the user search is unavailable - it always falls back.",
           "",
@@ -2320,6 +2405,7 @@ export {
   searchPlatform,
   searchReddit,
   searchSearxng,
+  searchSerpbase,
   searchStackOverflow,
   searchTavily,
   searchV2ex,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-free-search",
-  "version": "0.4.28",
-  "description": "Free web search for DeepSeek Harness: 12 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable/Firecrawl keyless; Parallel/Perplexity/DeepSeek with key) + time filtering + platform search + web_fetch, with web settings UI.",
+  "version": "0.4.29",
+  "description": "Free web search for DeepSeek Harness: 13 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable/Firecrawl keyless; Parallel/Perplexity/SerpBase/DeepSeek with key) + time filtering + platform search + web_fetch, with web settings UI.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -27,6 +27,7 @@
     "firecrawl",
     "parallel",
     "perplexity",
+    "serpbase",
     "search",
     "free"
   ],