dsh-free-search 0.4.28 → 0.4.30

package/README.md

@@ -29,8 +29,8 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 ### 特性
 
 - **零成本** —— 多个免费引擎，无需 key、无需注册
-- **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、DeepSeek 官方
-- **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换
+- **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase、DeepSeek 官方
+- **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；DSH 0.1.6-alpha.2+ 入口在左侧「插件」页的组件行配置，旧版在「设置 → 插件 → 可配置」
 - **弹出式切换命令** —— 聊天框输入 `/free-search-engine`，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
 - **引擎测试** —— `free_search_test` 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
 - **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
@@ -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？
@@ -111,7 +113,12 @@ dsh web
 
 #### 网页设置（推荐）
 
-安装后，打开 **设置 → 插件 → 可配置** 标签页 → **Free Search** 卡片（官方设置页）：
+安装后按 DSH 版本打开配置页：
+
+- **DSH 0.1.6-alpha.2 及以上**：左侧 **插件** 页 → **已安装** 分组 → `free-search` → 点击组件行 `web-search-free`（行内"配置"入口）
+- **DSH 0.1.5 及更早**：**设置 → 插件 → 可配置** 标签页 → **Free Search** 卡片
+
+配置页提供：
 
 - **Search engine**：下拉框切换引擎，保存即生效
 - **API keys**：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
@@ -152,7 +159,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 +171,7 @@ free-search:
   firecrawlApiKey: ...        # 或通过设置页填写
   parallelApiKey: ...         # 或通过设置页填写
   perplexityApiKey: ...
+  serpbaseApiKey: ...         # 或通过设置页填写
   deepseekApiKey: ...
 ```
 
@@ -290,8 +298,8 @@ 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
-- **Web Settings UI** — Engine switching, API key configuration (keys masked as "configured" in the UI), and a Chinese/English toggle
+- **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; on DSH 0.1.6-alpha.2+ the entry is the component-row config on the sidebar Plugins page, on older versions Settings → Plugins → Configurable
 - **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)
 - **Unified Engine Fallback** — Any engine failure (paid or free, missing key, 401, rate limit, network error) automatically tries the next engine: the configured engine first, then other engines (exa/tavily/keenable/firecrawl are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright.
@@ -321,6 +329,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 +340,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?
@@ -372,7 +382,12 @@ This plugin intentionally specifies `@deepseek-ai/dsh-settings` and `@deepseek-a
 
 #### Web Settings (Recommended)
 
-After installation, navigate to **Settings → Plugins → Configurable** tab → **Free Search** card (the official settings page):
+After installation, open the config page according to your DSH version:
+
+- **DSH 0.1.6-alpha.2 and later**: sidebar **Plugins** page → **Installed** group → `free-search` → click the `web-search-free` component row (the row's "configure" entry)
+- **DSH 0.1.5 and earlier**: **Settings → Plugins → Configurable** tab → **Free Search** card
+
+The config page provides:
 
 - **Search engine**: Select an engine from the dropdown; changes take effect immediately upon saving.
 - **API keys**: Enter keys for Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek (password fields; displayed as "configured" once saved).
@@ -413,7 +428,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 +440,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/cordis.patch.yml

@@ -1,8 +1,10 @@
 # dsh-free-search — free web search providers (no API key needed)
 # Registers the free-search plugin into ctx.web + a settings bridge
 # (/api/dsh-free-search-settings) that serves the "free-search" namespace.
-# The engine (ddg / ddg-lite / bing) is chosen from the web Settings page
-# (Settings > Plugins > Web UI plugins > Free Search) or settings.yaml:
+# The engine (ddg / ddg-lite / bing) is chosen from the web Settings page:
+#   DSH 0.1.6-alpha.2+: sidebar Plugins page -> Installed -> free-search -> row config
+#   DSH 0.1.5 and earlier: Settings > Plugins > Configurable > Free Search
+# or from settings.yaml:
 #   free-search:
 #     provider: bing
 #     region: cn-zh        # DuckDuckGo region

package/lib/client.js

@@ -13,6 +13,10 @@ window.__ModuleLoader__.load({
       ".dshfs-cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}",
       ".dshfs-header{width:100%;color:inherit;cursor:pointer;text-align:left;font:inherit;background:0 0;border:0;align-items:center;gap:8px;padding:10px 14px;display:flex}",
       ".dshfs-header:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}",
+      // 插件页 page 模式：页面自带标题，卡片固定展开、表头不可折叠
+      ".dshfs-pageMode>.dshfs-header{cursor:default}",
+      ".dshfs-pageMode>.dshfs-header:hover{background:0 0}",
+      ".dshfs-pageMode .dshfs-chevron{display:none}",
       ".dshfs-headText{flex-direction:column;flex:1;gap:2px;min-width:0;display:flex;overflow:hidden}",
       ".dshfs-name{color:var(--dsw-alias-label-primary);white-space:nowrap;text-overflow:ellipsis;font-weight:600;overflow:hidden}",
       ".dshfs-description{color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;font-size:12px;overflow:hidden}",
@@ -96,11 +100,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 +167,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 +222,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 +235,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" },
     ];
 
@@ -295,6 +302,14 @@ window.__ModuleLoader__.load({
       return response.json();
     }
 
+    // 插件页行配置的摘要文案（bundle 页每行显示；不触发 bridge 读取）
+    function summaryText() {
+      const primary = typeof navigator === "undefined" ? "zh" : String((navigator.languages && navigator.languages[0]) || navigator.language || "zh").toLowerCase();
+      return primary.startsWith("en")
+        ? "13 engines · time filtering · platform search · web_fetch"
+        : "13 个搜索引擎 · 时间筛选 · 平台搜索 · web_fetch";
+    }
+
     function FreeSearchCard(props) {
       // 检测应用主题深浅（读 body 的 --dsw-alias-bg-base 变量亮度），用于锁定原生下拉配色
       const isDarkScheme = react.useMemo(() => {
@@ -316,7 +331,10 @@ window.__ModuleLoader__.load({
         return typeof matchMedia === "function" ? matchMedia("(prefers-color-scheme: dark)").matches : false;
       }, []);
       const selectColorScheme = isDarkScheme ? "dark" : "light";
-      const [open, setOpen] = react.useState(false);
+      // 插件页（0.1.6-alpha.2+ 的 plugins.row.config）以 page 模式复用本卡片：
+      // 页面自带标题/面包屑，卡片固定展开、表头不再可折叠。
+      const pageMode = !!(props && props.page);
+      const [open, setOpen] = react.useState(pageMode);
       const [state, setState] = react.useState({ status: "loading" });
       const [provider, setProvider] = react.useState("bing");
       const [safeSearch, setSafeSearch] = react.useState("off");
@@ -328,6 +346,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 +382,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 +397,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 +409,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 +450,7 @@ window.__ModuleLoader__.load({
             ["parallelApiKey", parallelKey],
             ["perplexityApiKey", perplexityKey],
             ["deepseekApiKey", deepseekKey],
+            ["serpbaseApiKey", serpbaseKey],
           ];
           let credFailed = false;
           if (keyStorage === "credentials") {
@@ -559,13 +581,13 @@ window.__ModuleLoader__.load({
       };
 
       return react_jsx_runtime.jsx("li", {
-        className: open ? "dshfs-card dshfs-cardOpen" : "dshfs-card",
+        className: (open ? "dshfs-card dshfs-cardOpen" : "dshfs-card") + (pageMode ? " dshfs-pageMode" : ""),
         children: [
           react_jsx_runtime.jsx("button", {
             type: "button",
             className: "dshfs-header",
-            "aria-expanded": open,
-            onClick: () => setOpen(!open),
+            "aria-expanded": pageMode ? void 0 : open,
+            onClick: pageMode ? void 0 : () => setOpen(!open),
             children: [
                       react_jsx_runtime.jsx("span", { className: "dshfs-headText", children: [
                   react_jsx_runtime.jsx("span", { className: "dshfs-name", children: title }),
@@ -766,6 +788,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",
@@ -1050,6 +1084,20 @@ react_jsx_runtime.jsx("div", {
           FreeSearchCard
         )
       );
+      // 挂 0.1.6-alpha.2+ 的插件页 slot：侧栏 插件 → 已安装 → free-search → 行配置页。
+      // key 规则见 ui-plugin-manager 的 rowConfigKey：<包名>#<patch 里声明的行 id>。
+      ctx.slots.inject("plugins.row.config", () =>
+        ctx.slots.register(
+          {
+            name: "plugins.row.config",
+            key: "dsh-free-search#web-search-free",
+          },
+          (slotProps) =>
+            slotProps && slotProps.view === "summary"
+              ? summaryText()
+              : react_jsx_runtime.jsx(FreeSearchCard, { page: true })
+        )
+      );
       // /free-search-engine 弹出式命令：输入 "/" 选中后弹出引擎列表，点选即切换。
       // 等效于设置页切换引擎+保存；命令只改 provider 配置，搜索仍走回退链。
       // description 必须传函数：ui-commands 读回的是 contribution.description()，

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.30",
+  "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"
   ],