dsh-free-search 0.4.7 → 0.4.8

package/README.md

@@ -33,9 +33,10 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 - **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换
 - **弹出式切换命令** —— 聊天框输入 `/free-search-engine`，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
 - **引擎测试** —— `free_search_test` 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
-- **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：先试其他已配 key 的付费引擎，再试免费引擎，搜索永不直接失败
+- **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
 - **时间过滤** —— `advanced_search` 工具支持 `timeRange`：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
 - **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
+- **版本号 + 检查更新** —— 设置卡片显示当前版本（v0.4.8），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
 - **免费标注** —— 设置页中免费引擎带绿色 `FREE` 徽章，付费引擎带橙色 `API KEY` 徽章
 - **网页抓取（web_fetch）** —— 让 agent 抓取网页内容（官方 `dsh-web-fetch-http` provider，纯 JS，零额外依赖）
 - **平台搜索（platform_search）** —— 搜 GitHub / V2EX / B站（公开 API，零依赖）
@@ -266,9 +267,10 @@ This plugin provides multiple free search engines with automatic fallback, compl
 - **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)
-- **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.
+- **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 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.
 - **Time Filtering** — The `advanced_search` tool supports `timeRange`: fixed tiers, custom relative values, or an absolute date (details below)
 - **System Prompt Injection** — The agent is aware of the currently active engine and which engines require API keys
+- **Version + Update Check** — The settings card shows the current version (v0.4.8), and a "Check update" button queries the npm registry to compare against the latest release, prompting a one-click jump when a newer version exists
 - **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)
 - **Platform Search (`platform_search`)** — Search GitHub / V2EX / Bilibili (public APIs, zero extra dependencies)
@@ -290,7 +292,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 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.
+- **Auto-failover**: any engine failure (rate-limited free engine, or missing/invalid paid key, network error) automatically tries the next engine — the configured engine first, then other engines (exa/tavily/keenable 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 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>
   - Tavily: <https://app.tavily.com/home>

package/lib/client.js

@@ -20,9 +20,12 @@ window.__ModuleLoader__.load({
       ".dshfs-chevron{color:var(--dsw-alias-label-tertiary);flex:none;font-size:13px;transition:transform .12s}",
       ".dshfs-chevronOpen{transform:rotate(180deg)}",
       ".dshfs-body{flex-direction:column;gap:14px;padding:0 14px 14px;display:flex}",
-      ".dshfs-footer{justify-content:flex-end;align-items:center;gap:8px;display:flex}",
-      ".dshfs-failed{color:var(--dsw-alias-state-error-primary);margin:0 auto 0 0;font-size:12px}",
-      ".dshfs-testOk{color:#7ddb9c;margin:0 auto 0 0;font-size:12px;line-height:1.5}",
+      ".dshfs-footer{justify-content:space-between;align-items:center;gap:8px;display:flex;flex-wrap:wrap}",
+      ".dshfs-footerLeft{display:flex;align-items:center;gap:8px;flex-wrap:wrap;min-width:0}",
+      ".dshfs-footerRight{display:flex;align-items:center;gap:8px;flex-wrap:wrap}",
+      ".dshfs-failed{color:var(--dsw-alias-state-error-primary);font-size:12px}",
+      ".dshfs-testOk{color:#7ddb9c;font-size:12px;line-height:1.5}",
+      ".dshfs-resultRow{display:flex;flex-direction:column;align-items:flex-start;gap:4px;min-width:0;margin-top:2px}",
       ".dshfs-field{flex-direction:column;gap:4px;min-width:0;display:flex}",
       ".dshfs-label{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:500}",
       ".dshfs-select{border:1px solid var(--dsw-alias-border-l2);font:inherit;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-primary);background:var(--dsw-specific-input-major);border-radius:6px;padding:6px 8px;font-size:13px;transition:border-color .13s,box-shadow .13s;width:100%}",
@@ -45,6 +48,10 @@ window.__ModuleLoader__.load({
       ".dshfs-badgeFree{background:rgba(80,200,120,.15);color:#7ddb9c;border:1px solid rgba(80,200,120,.3);white-space:nowrap;border-radius:999px;flex:none;padding:1px 6px;font-size:11px}",
       ".dshfs-badgeKey{background:rgba(240,170,80,.15);color:#f0b060;border:1px solid rgba(240,170,80,.3);white-space:nowrap;border-radius:999px;flex:none;padding:1px 6px;font-size:11px}",
       ".dshfs-langToggle{border:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:transparent;flex:none;padding:2px 8px;font-size:11px;border-radius:6px}",
+      ".dshfs-update{color:var(--dsw-alias-state-warn-primary);flex:none;font-size:11px;white-space:nowrap;border:1px solid rgba(240,170,80,.3);background:rgba(240,170,80,.12);border-radius:999px;padding:1px 6px}",
+      ".dshfs-updateOk{color:#7ddb9c;flex:none;font-size:11px;white-space:nowrap;border:1px solid rgba(80,200,120,.3);background:rgba(80,200,120,.12);border-radius:999px;padding:1px 6px}",
+      ".dshfs-updateLine{display:flex;align-items:center;gap:8px;flex-wrap:wrap}",
+      ".dshfs-version{color:var(--dsw-alias-label-tertiary);font-size:11px;font-variant-numeric:tabular-nums;white-space:nowrap}",
     ].join("");
     const tagId = "dsh-free-search/card.css";
     if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
@@ -86,6 +93,12 @@ window.__ModuleLoader__.load({
         testOk: (r) => `✓ ${r.count} 条结果（引擎: ${r.engine}）${r.content ? ` — ${r.content}` : ""}${r.sample ? ` · 例如 "${r.sample.slice(0, 40)}"` : ""}`,
         testFail: (e) => `✗ ${e}`,
         toggleLang: "EN",
+        checkUpdate: "检查更新",
+        checkingUpdate: "检查中…",
+        updateAvailable: (c, l) => `发现新版本 v${l}（当前 v${c}）`,
+        updateLatest: (c) => `已是最新版本 v${c}`,
+        updateCheckFailed: "检查更新失败（无法访问 npm registry）",
+        updateView: "查看 →",
       },
       en: {
         description: "Free web search — no API key needed (Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable)",
@@ -114,9 +127,17 @@ window.__ModuleLoader__.load({
         testOk: (r) => `✓ ${r.count} results (engine: ${r.engine})${r.content ? ` — ${r.content}` : ""}${r.sample ? ` · e.g. "${r.sample.slice(0, 40)}"` : ""}`,
         testFail: (e) => `✗ ${e}`,
         toggleLang: "中文",
+        checkUpdate: "Check update",
+        checkingUpdate: "Checking…",
+        updateAvailable: (c, l) => `New version v${l} available (current v${c})`,
+        updateLatest: (c) => `You are up to date (v${c})`,
+        updateCheckFailed: "Update check failed (cannot reach npm registry)",
+        updateView: "View →",
       },
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
+    // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION 保持一致）
+    const PLUGIN_VERSION = "0.4.8";
     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" },
@@ -157,6 +178,15 @@ window.__ModuleLoader__.load({
       return response.json();
     }
 
+    async function bridgeCheckUpdate() {
+      const response = await fetch(`${BRIDGE_PREFIX}/check-update`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      });
+      return response.json();
+    }
+
     function FreeSearchCard(props) {
       const [open, setOpen] = react.useState(false);
       const [state, setState] = react.useState({ status: "loading" });
@@ -174,6 +204,8 @@ window.__ModuleLoader__.load({
       const [failed, setFailed] = react.useState(false);
       const [testing, setTesting] = react.useState(false);
       const [testResult, setTestResult] = react.useState(null);
+      const [checkingUpdate, setCheckingUpdate] = react.useState(false);
+      const [updateInfo, setUpdateInfo] = react.useState(null);
 
       const load = react.useCallback(async () => {
         try {
@@ -288,6 +320,24 @@ window.__ModuleLoader__.load({
         }
       };
 
+      const runCheckUpdate = async () => {
+        setCheckingUpdate(true);
+        setUpdateInfo(null);
+        setFailed(false);
+        try {
+          const result = await bridgeCheckUpdate();
+          if (result.ok) {
+            setUpdateInfo({ ok: true, ...result.value });
+          } else {
+            setUpdateInfo({ ok: false });
+          }
+        } catch {
+          setUpdateInfo({ ok: false });
+        } finally {
+          setCheckingUpdate(false);
+        }
+      };
+
       if (state.status === "loading") return null;
       const ready = state.status === "ready";
       const t = tt(lang);
@@ -312,14 +362,11 @@ window.__ModuleLoader__.load({
             "aria-expanded": open,
             onClick: () => setOpen(!open),
             children: [
-              react_jsx_runtime.jsx("span", {
-                className: "dshfs-headText",
-                children: [
+                      react_jsx_runtime.jsx("span", { className: "dshfs-headText", children: [
                   react_jsx_runtime.jsx("span", { className: "dshfs-name", children: title }),
                   react_jsx_runtime.jsx("span", { className: "dshfs-description", children: description }),
-                ],
-              }),
-                          react_jsx_runtime.jsx("span", { className: badgeClass, children: currentEngine.badge }),
+                ] }),
+                react_jsx_runtime.jsx("span", { className: badgeClass, children: currentEngine.badge }),
               dirty ? react_jsx_runtime.jsx("span", { className: "dshfs-pending", children: t.unsaved }) : null,
               react_jsx_runtime.jsx("button", {
                 type: "button",
@@ -488,24 +535,71 @@ react_jsx_runtime.jsx("div", {
                       }),
                     ],
                   }),
-                  !ready
-                    ? react_jsx_runtime.jsx("p", {
-                        className: "dshfs-hint",
-                        children: t.unavailable,
-                      })
-                    : null,
                   react_jsx_runtime.jsx("div", {
-                    className: "dshfs-footer",
+                    className: "dshfs-resultRow",
                     children: [
-                      failed ? react_jsx_runtime.jsx("p", { className: "dshfs-failed", children: t.saveFailed }) : null,
+                      failed ? react_jsx_runtime.jsx("span", { className: "dshfs-failed", children: t.saveFailed }) : null,
                       testResult
-                        ? react_jsx_runtime.jsx("p", {
+                        ? react_jsx_runtime.jsx("span", {
                             className: testResult.ok ? "dshfs-testOk" : "dshfs-failed",
                             children: testResult.ok
                               ? t.testOk(testResult)
                               : t.testFail(testResult.error),
                           })
                         : null,
+                    ],
+                  }),
+                  !ready
+                    ? react_jsx_runtime.jsx("p", {
+                        className: "dshfs-hint",
+                        children: t.unavailable,
+                      })
+                    : null,
+                  react_jsx_runtime.jsx("div", {
+                    className: "dshfs-footer",
+                    children: [
+                      react_jsx_runtime.jsx("div", {
+                        className: "dshfs-footerLeft",
+                        children: [
+                          react_jsx_runtime.jsx("span", { className: "dshfs-version", children: "v" + PLUGIN_VERSION }),
+                          react_jsx_runtime.jsx("button", {
+                            className: "dshfs-btn",
+                            type: "button",
+                            onClick: runCheckUpdate,
+                            disabled: checkingUpdate || saving || !ready,
+                            children: checkingUpdate ? t.checkingUpdate : t.checkUpdate,
+                          }),
+                          updateInfo && updateInfo.ok
+                            ? updateInfo.hasUpdate
+                              ? react_jsx_runtime.jsx("span", {
+                                  className: "dshfs-update",
+                                  children: [
+                                    t.updateAvailable(updateInfo.current, updateInfo.latest),
+                                    " ",
+                                    react_jsx_runtime.jsx("a", {
+                                      className: "dshfs-link",
+                                      href: updateInfo.updateUrl,
+                                      target: "_blank",
+                                      rel: "noopener noreferrer",
+                                      children: t.updateView,
+                                    }),
+                                  ],
+                                })
+                              : react_jsx_runtime.jsx("span", {
+                                  className: "dshfs-updateOk",
+                                  children: t.updateLatest(updateInfo.current),
+                                })
+                            : updateInfo && !updateInfo.ok
+                              ? react_jsx_runtime.jsx("span", {
+                                  className: "dshfs-failed",
+                                  children: t.updateCheckFailed,
+                                })
+                              : null,
+                        ],
+                      }),
+                      react_jsx_runtime.jsx("div", {
+                        className: "dshfs-footerRight",
+                        children: [
                       react_jsx_runtime.jsx("button", {
                         className: "dshfs-btn",
                         type: "button",
@@ -540,9 +634,11 @@ react_jsx_runtime.jsx("div", {
                       }),
                     ],
                   }),
-                ],
-              })
-            : null,
+                  ],
+                })
+              ],
+            })
+          : null,
         ],
       });
     }

package/lib/index.js

@@ -17,6 +17,46 @@ 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", "perplexity", "deepseek-official"];
 
+// 当前插件版本（发布时与 package.json 同步）
+const PLUGIN_VERSION = "0.4.8";
+// 检查更新的 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";
+const PLUGIN_REPO_URL = "https://github.com/DDDMUC/dsh-free-search";
+
+// 查询 npm registry 的最新版本；失败时返回 null（网络/代理问题不阻塞设置页）
+async function fetchLatestVersion(signal) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10000);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort);
+  try {
+    const response = await fetch(NPM_REGISTRY_URL, {
+      headers: { accept: "application/json", "user-agent": "deepseek-harness/free-search" },
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+// 简单的 semver 比较（仅处理 x.y.z 主/次/补丁，忽略预发布标签）；a>b 返回 1, a<b 返回 -1, 相等返回 0
+function compareVersions(a, b) {
+  const na = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const nb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((na[i] ?? 0) > (nb[i] ?? 0)) return 1;
+    if ((na[i] ?? 0) < (nb[i] ?? 0)) return -1;
+  }
+  return 0;
+}
+
 // time_range 支持：固定档 day/week/month/year，或自定义（相对 12h/3d/2mo/1y、绝对 YYYY-MM-DD）
 const TIME_RANGES = ["day", "week", "month", "year"];
 const DAYS_BY_RANGE = { day: 1, week: 7, month: 30, year: 365 };
@@ -898,6 +938,27 @@ function makeBridgeRoutes(settings, search, testEngine) {
       .map((descriptor) => String(descriptor.ns));
 
   const handlers = {
+    async checkUpdate() {
+      const latest = await fetchLatestVersion();
+      if (latest === null) {
+        return {
+          ok: false,
+          code: "update-check-failed",
+          message: "could not reach the npm registry (network/proxy) - check your connection",
+        };
+      }
+      const cmp = compareVersions(latest, PLUGIN_VERSION);
+      return {
+        ok: true,
+        value: {
+          current: PLUGIN_VERSION,
+          latest,
+          hasUpdate: cmp > 0,
+          updateUrl: PLUGIN_NPM_URL,
+          repoUrl: PLUGIN_REPO_URL,
+        },
+      };
+    },
     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)" };
@@ -1018,6 +1079,14 @@ function makeBridgeRoutes(settings, search, testEngine) {
         writeJson(res, 200, await handlers.mutate(body));
       },
     },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/check-update`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        writeJson(res, 200, await handlers.checkUpdate());
+      },
+    },
     {
       kind: "exact",
       path: `${BRIDGE_PREFIX}/raw-search`,
@@ -1085,7 +1154,9 @@ function apply(ctx, config) {
       const cfg = current();
       const preferred = cfg.provider ?? "bing";
       // time_range 过滤（仅 advanced_search 工具透传；标准 web_search 无此参数）
+      // 保留原始字符串用于 Note 展示；raw-search 桥可能已把 timeRange 解析成对象
       const timeRange = parseTimeRange(request.timeRange);
+      const timeRangeLabel = typeof request.timeRange === "string" ? request.timeRange : String(timeRange?.days ?? timeRange?.after ?? "");
 
       // 统一引擎链：首选优先，然后其他付费引擎（有 key 的优先尝试），最后免费引擎
       const paidEngines = ["exa", "tavily", "keenable", "perplexity", "deepseek-official"];
@@ -1093,12 +1164,21 @@ function apply(ctx, config) {
       // 支持 time_range 过滤的引擎：tavily / exa / keenable / searxng / ddg / ddg-lite
       const timeEngines = ["tavily", "exa", "keenable", "searxng", "ddg", "ddg-lite"];
       let chain;
+      // 首选引擎被跳过的原因（用于生成准确的 Note，避免误导 agent/用户）：
+      //  - "time-filter"：带 timeRange 且首选引擎不支持时间过滤（根本没尝试）
+      //  - "failed"：首选引擎确实被尝试但失败（缺 key / 401 / 限流 / 0 结果 / 网络）
+      //  - null：首选引擎成功或无回退
+      let preferredSkippedReason = null;
       if (timeRange) {
         // 有时间过滤需求时，把支持过滤的引擎排前面（首选引擎若支持仍优先）
         const preferredFirst = [preferred].filter((e) => timeEngines.includes(e));
         const otherTime = timeEngines.filter((e) => e !== preferred);
         const noTime = [...paidEngines, ...freeEngines].filter((e) => !timeEngines.includes(e) && e !== preferred);
         chain = [...preferredFirst, ...otherTime, ...noTime];
+        if (!timeEngines.includes(preferred)) {
+          // 首选引擎不支持时间过滤 → 它不在链里，不会被尝试（这不等于失败）
+          preferredSkippedReason = "time-filter";
+        }
       } else {
         const othersPaid = paidEngines.filter((e) => e !== preferred);
         const othersFree = freeEngines.filter((e) => e !== preferred);
@@ -1107,6 +1187,8 @@ function apply(ctx, config) {
 
       let lastError = null;
       let usedEngine = null;
+      // 首选引擎若被尝试后失败，记录失败详情（用于 Note）
+      let preferredFailure = null;
       for (const engine of chain) {
         try {
           let result;
@@ -1140,6 +1222,7 @@ function apply(ctx, config) {
             const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
             if (!key) {
               lastError = new Error("Perplexity requires PERPLEXITY_API_KEY");
+              if (engine === preferred) preferredFailure = "PERPLEXITY_API_KEY is not configured";
               logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
               continue; // 无 key 跳过
             }
@@ -1148,6 +1231,7 @@ function apply(ctx, config) {
             const key = await resolveApiKey("DEEPSEEK_API_KEY", "deepseekApiKey");
             if (!key) {
               lastError = new Error("DeepSeek requires DEEPSEEK_API_KEY");
+              if (engine === preferred) preferredFailure = "DEEPSEEK_API_KEY is not configured";
               logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
               continue; // 无 key 跳过
             }
@@ -1158,17 +1242,25 @@ function apply(ctx, config) {
 
           if (result.sources.length > 0) {
             usedEngine = engine;
-            // 用了非首选引擎时，在结果里附上提示（agent 会看到）
+            // 用了非首选引擎时，在结果里附上准确提示（区分"不支持时间过滤被跳过"与"真实失败"）
             if (engine !== preferred) {
-              result.content = `Note: ${preferred} unavailable or failed, using ${engine}.`;
+              if (preferredSkippedReason === "time-filter") {
+                result.content = `Note: ${preferred} does not support time filtering (timeRange=${timeRangeLabel}), using ${engine}.`;
+              } else if (preferredFailure) {
+                result.content = `Note: ${preferred} unavailable or failed (${preferredFailure}), using ${engine}.`;
+              } else {
+                result.content = `Note: ${preferred} unavailable or failed, using ${engine}.`;
+              }
             }
             return { ...result, provider: engine, engine: engine };
           }
           lastError = new Error(`engine "${engine}" returned 0 results`);
+          if (engine === preferred) preferredFailure = "returned 0 results";
           logger.warn(`free-search: ${engine} returned 0 results, trying next engine`);
         } catch (error) {
           lastError = error;
           const message = error instanceof Error ? error.message : String(error);
+          if (engine === preferred) preferredFailure = message;
           logger.warn(`free-search: engine "${engine}" failed (${message}), trying next engine`);
         }
       }
@@ -1407,7 +1499,15 @@ function apply(ctx, config) {
             }
             const limit = Math.min(args.maxResults ?? 5, 10);
             const result = await searchPlatform(platform, args.query, limit);
-            return { platform, sources: result.sources };
+            // lossless JSON 不允许 undefined 字段：剔除缺失字段
+            const sources = (result.sources ?? []).map((s) => {
+              const source = {};
+              if (s.url !== undefined && s.url !== null && s.url !== "") source.url = s.url;
+              if (s.title !== undefined && s.title !== null && s.title !== "") source.title = String(s.title);
+              if (s.snippet !== undefined && s.snippet !== null && s.snippet !== "") source.snippet = String(s.snippet);
+              return source;
+            });
+            return { platform, sources };
           },
           finalizeContent(exec, result) {
             // Tool-result content must be an array of content blocks, not a raw string.
@@ -1485,15 +1585,20 @@ function apply(ctx, config) {
             // engine 指定时：仅当该引擎可用才优先（仍走回退链，失败自动换引擎）
             if (args.engine && ALL_ENGINES.includes(args.engine)) request.engine = args.engine;
             const result = await provider.search(request);
+            // lossless JSON 不允许 undefined 字段：按存在的值构造对象，缺字段直接省略
             return {
-              provider: result.provider ?? result._provider,
-              content: result.content ?? "",
-              sources: (result.sources ?? []).map((s) => ({
-                url: s.url,
-                title: s.title,
-                snippet: s.snippet,
-                publishedAt: s.publishedAt,
-              })),
+              provider: result.provider ?? result._provider ?? "bing",
+              content: typeof result.content === "string" ? result.content : "",
+              sources: (result.sources ?? []).map((s) => {
+                const source = {};
+                if (s.url !== undefined && s.url !== null && s.url !== "") source.url = s.url;
+                if (s.title !== undefined && s.title !== null && s.title !== "") source.title = String(s.title);
+                if (s.snippet !== undefined && s.snippet !== null && s.snippet !== "") source.snippet = String(s.snippet);
+                if (s.publishedAt !== undefined && s.publishedAt !== null && s.publishedAt !== "") {
+                  source.publishedAt = String(s.publishedAt);
+                }
+                return source;
+              }),
             };
           },
           finalizeContent(exec, result) {
@@ -1538,7 +1643,7 @@ function apply(ctx, config) {
           "- perplexity - requires PERPLEXITY_API_KEY",
           "- deepseek-official - requires DEEPSEEK_API_KEY",
           "",
-          "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.",
+          "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 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.",
           "",
           "Use the free_search_test tool to test which engines actually work right now.",
           "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-free-search",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Free web search for DeepSeek Harness: 10 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable keyless) + time filtering + platform search + web_fetch, with web settings UI.",
   "type": "module",
   "main": "lib/index.js",