dsh-free-search 0.4.30 → 0.4.32

package/README.md

@@ -33,7 +33,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 - **网页设置页** —— 引擎切换 + 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.`）
+- **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl/parallel 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
 - **时间过滤** —— `advanced_search` 工具支持 `timeRange`：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
 - **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
 - **版本号 + 检查更新** —— 设置卡片显示当前版本（v0.4.17），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
@@ -58,7 +58,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 | `tavily` | Tavily | 免费 | **无 key 也可用**（keyless 匿名），配 key 提升额度 |
 | `keenable` | Keenable | 免费 | **无 key 也可用**（MCP 匿名），配 key 提升额度 |
 | `firecrawl` | Firecrawl | 免费 | **无 key 也可用**（官方免 key 匿名额度），配 key 提升限额 |
-| `parallel` | Parallel | 付费 | 需 `PARALLEL_API_KEY`（platform.parallel.ai 有免费额度） |
+| `parallel` | Parallel | 免费 | **无 key 也可用**（官方 MCP 匿名额度），配 key 提升额度并支持精确时间过滤 |
 | `perplexity` | Perplexity | 付费 | 需 `PERPLEXITY_API_KEY` |
 | `serpbase` | SerpBase | 付费 | 需 `SERPBASE_API_KEY`（serpbase.dev，注册送 100 次免费额度） |
 | `deepseek-official` | DeepSeek 官方 | 付费 | 需 `DEEPSEEK_API_KEY` |
@@ -121,7 +121,7 @@ dsh web
 配置页提供：
 
 - **Search engine**：下拉框切换引擎，保存即生效
-- **API keys**：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
+- **API keys**：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"；Exa / Tavily / Keenable / Firecrawl / Parallel 不填也可免 key 使用）
   - **推荐**：付费引擎 key 建议写入 harness 凭据中心 `~/.dsh/.credentials.yaml`（如 `DEEPSEEK_API_KEY: sk-...`，与官方 LLM provider 一致，一处管理所有 key）。插件读取优先级：凭据中心 > 设置页 > 环境变量，设置页填的 key 仅作为遗留兼容。
 - **Test engine**：直测当前引擎可用性（不走回退链，付费引擎无 key 会明确报错）
 - **Use Bing default**：把当前搜索引擎切回稳定的免费 Bing；`Discard` 只撤销尚未保存的编辑
@@ -206,7 +206,7 @@ Search engine test:
 | Keenable | `published_after` | ✅ 精确 | 相对值原样传（`12h/3d/2mo/1y`），绝对日期原样传 |
 | Tavily | `time_range` | ⚠️ 近似 | 只认固定档，自定义天数自动映射到最近似档位 |
 | Firecrawl | `tbs` | ⚠️ 近似 | 固定档映射到 `qdr:d/w/m/y`；绝对日期用 `cdr:1,cd_min:M/D/YYYY`（精确） |
-| Parallel | `source_policy.after_date` | ✅ 精确 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
+| Parallel | `source_policy.after_date`（有 key 时精确）；无 key 走 MCP，无日期参数，改为把窗口写进 objective 作为新鲜度提示（软过滤） | ✅ 精确 / ⚠️ 软过滤 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
 | SearXNG | `time_range` | ⚠️ 近似 | 同上 |
 | DuckDuckGo / Lite | `df` | ⚠️ 近似 | 同上 |
 | Bing / AnySearch | — | ❌ 忽略 | 无对应参数 |
@@ -302,7 +302,7 @@ 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; 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.
+- **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/parallel 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.17), 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
@@ -327,13 +327,13 @@ If this plugin has been helpful, a ⭐ on [GitHub](https://github.com/DDDMUC/dsh
 | `tavily` | Tavily | Free | **Usable without a key** (keyless anonymous); configure a key for higher quota |
 | `keenable` | Keenable | Free | **Usable without a key** (anonymous MCP); configure a key for higher quota |
 | `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) |
+| `parallel` | Parallel | Free | **Works without a key** (official MCP anonymous quota); a key raises limits and enables precise time filtering |
 | `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.
-- **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/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 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/firecrawl/parallel 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>
@@ -390,7 +390,7 @@ After installation, open the config page according to your DSH version:
 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).
+- **API keys**: Enter keys for Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek (password fields; displayed as "configured" once saved; Exa / Tavily / Keenable / Firecrawl / Parallel work without a key too).
   - **Recommended**: store paid-engine keys in the harness credential center `~/.dsh/.credentials.yaml` (e.g. `DEEPSEEK_API_KEY: sk-...`, same as the official LLM providers — one place for all keys). Resolution order: credentials center > settings page > environment variable; the settings-page fields remain for backward compatibility.
 - **Test engine**: Tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error).
 - **Use Bing default**: stage a switch back to the stable free Bing engine; `Discard` only cancels unsaved edits
@@ -475,7 +475,7 @@ Ask the agent for *"news from the last week"*, *"releases this month"*, *"update
 | Keenable | `published_after` | ✅ precise | relative values (`12h/3d/2mo/1y`) and absolute dates pass through |
 | Tavily | `time_range` | ⚠️ approximate | only fixed tiers; custom days map to the nearest tier |
 | Firecrawl | `tbs` | ⚠️ approximate | fixed tiers map to `qdr:d/w/m/y`; absolute dates use `cdr:1,cd_min:M/D/YYYY` (precise) |
-| Parallel | `source_policy.after_date` | ✅ precise | custom days become an ISO date (N days ago); absolute dates pass through |
+| Parallel | `source_policy.after_date` with a key (precise); without a key the MCP path has no date parameter, so the window is written into the objective as a freshness hint (soft filter) | ✅ precise / ⚠️ soft | custom days become an ISO date (N days ago); absolute dates pass through |
 | SearXNG | `time_range` | ⚠️ approximate | same as above |
 | DuckDuckGo / Lite | `df` | ⚠️ approximate | same as above |
 | Bing / AnySearch | — | ❌ ignored | no corresponding parameter |

package/lib/client.js

@@ -86,7 +86,7 @@ window.__ModuleLoader__.load({
     const NS = "free-search";
     const I18N = {
       zh: {
-        description: "免费搜索 —— 无需 API key（Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable / Firecrawl）",
+        description: "免费搜索 —— 无需 API key（Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable / Firecrawl / Parallel）",
         unsaved: "未保存",
         searchEngine: "搜索引擎",
         visit: "访问官网 →",
@@ -97,7 +97,7 @@ window.__ModuleLoader__.load({
         tavilyPh: (c) => c ? "Tavily API 密钥（已配置）" : "Tavily API 密钥（可选，不填也可免费使用）",
         keenablePh: (c) => c ? "Keenable API 密钥（已配置）" : "Keenable API 密钥（可选，不填也可免费使用）",
         firecrawlPh: (c) => c ? "Firecrawl API 密钥（已配置）" : "Firecrawl API 密钥（可选，不填也可免费使用）",
-        parallelPh: (c) => c ? "Parallel API 密钥（已配置）" : "Parallel API 密钥（必填，platform.parallel.ai）",
+        parallelPh: (c) => c ? "Parallel API 密钥（已配置）" : "Parallel API 密钥（可选，不填走 MCP 免 key）",
         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 获取）",
@@ -153,7 +153,7 @@ window.__ModuleLoader__.load({
         marketKoKR: "ko-KR —— 韩国",
       },
       en: {
-        description: "Free web search — no API key needed (Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable / Firecrawl)",
+        description: "Free web search — no API key needed (Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable / Firecrawl / Parallel)",
         unsaved: "unsaved",
         searchEngine: "Search engine",
         visit: "Visit website →",
@@ -164,7 +164,7 @@ window.__ModuleLoader__.load({
         tavilyPh: (c) => c ? "Tavily API key (configured)" : "Tavily API key (optional, free without)",
         keenablePh: (c) => c ? "Keenable API key (configured)" : "Keenable API key (optional, free without)",
         firecrawlPh: (c) => c ? "Firecrawl API key (configured)" : "Firecrawl API key (optional, free without)",
-        parallelPh: (c) => c ? "Parallel API key (configured)" : "Parallel API key (required, platform.parallel.ai)",
+        parallelPh: (c) => c ? "Parallel API key (configured)" : "Parallel API key (optional, free without)",
         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)",
@@ -222,7 +222,7 @@ window.__ModuleLoader__.load({
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
     // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION 保持一致）
-    const PLUGIN_VERSION = "0.4.29";
+    const PLUGIN_VERSION = "0.4.32";
     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" },
@@ -233,7 +233,7 @@ window.__ModuleLoader__.load({
       { id: "tavily", label: "Tavily", badge: "FREE", link: "https://app.tavily.com/home" },
       { id: "keenable", label: "Keenable", badge: "FREE", link: "https://keenable.ai/login" },
       { id: "firecrawl", label: "Firecrawl", badge: "FREE", link: "https://www.firecrawl.dev" },
-      { id: "parallel", label: "Parallel", badge: "API KEY", link: "https://platform.parallel.ai" },
+      { id: "parallel", label: "Parallel", badge: "FREE", 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" },

package/lib/index.js

@@ -11,6 +11,7 @@ const BING_URL = "https://www.bing.com/search";
 const TAVILY_URL = "https://api.tavily.com/search";
 const FIRECRAWL_URL = "https://api.firecrawl.dev/v2/search";
 const PARALLEL_URL = "https://api.parallel.ai/v1/search";
+const PARALLEL_MCP_URL = "https://search.parallel.ai/mcp";
 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";
@@ -51,7 +52,7 @@ const FREE_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch"];
 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.29";
+const PLUGIN_VERSION = "0.4.32";
 // 检查更新的 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";
@@ -930,7 +931,7 @@ async function searchFirecrawl(query, maxResults, apiKey, timeRange, signal) {
   return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
 }
 
-// Parallel: 需 PARALLEL_API_KEY（x-api-key），自然语言 objective + search_queries，返回带 excerpts 的结果
+// Parallel: 有 key 走 REST（x-api-key）；无 key 走官方 MCP 免 key。自然语言 objective + search_queries，返回带 excerpts 的结果
 async function searchParallel(query, maxResults, apiKey, timeRange, signal) {
   if (!apiKey) throw new Error("Parallel search requires PARALLEL_API_KEY");
   const controller = new AbortController();
@@ -991,6 +992,91 @@ async function searchParallel(query, maxResults, apiKey, timeRange, signal) {
   return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
 }
 
+// Parallel keyless：官方 MCP（search.parallel.ai/mcp）匿名额度，无需 API key。
+// 与 REST 的差异：MCP 的 web_search 工具没有 max_results / after_date 参数
+// （条数由服务端决定），时间过滤退化为 objective 里的新鲜度提示（软过滤）。
+const PARALLEL_MCP_SESSION = (() => {
+  let id = "";
+  for (let i = 0; i < 32; i++) id += Math.floor(Math.random() * 16).toString(16);
+  return id;
+})();
+
+async function searchParallelMCP(query, maxResults, timeRange, signal) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 25000);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort);
+  let response;
+  try {
+    const after = timeRange
+      ? timeRange.after ?? (timeRange.days !== undefined ? isoDaysAgo(timeRange.days).slice(0, 10) : undefined)
+      : undefined;
+    const objective = after ? `${query} (prefer results published after ${after})` : query;
+    response = await fetch(PARALLEL_MCP_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: Date.now(),
+        method: "tools/call",
+        params: {
+          name: "web_search",
+          arguments: {
+            objective,
+            search_queries: [query],
+            session_id: PARALLEL_MCP_SESSION,
+          },
+        },
+      }),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    throw new Error(`Parallel MCP request failed: ${error?.message ?? String(error)}`);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+  if (!response.ok) throw new Error(`Parallel MCP error (HTTP ${response.status})`);
+  const text = await response.text();
+  // 兼容 JSON 与 SSE（event: message\ndata: {...}）两种响应形态
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    for (const line of text.split("\n")) {
+      if (line.startsWith("data: ")) {
+        try {
+          json = JSON.parse(line.slice(6));
+          break;
+        } catch {}
+      }
+    }
+  }
+  if (!json || json.error) throw new Error(`Parallel MCP error: ${json?.error?.message ?? "no data"}`);
+  const blocks = (json.result?.content ?? []).filter((b) => b.type === "text").map((b) => b.text);
+  if (json.result?.isError) throw new Error(`Parallel MCP error: ${blocks.join(" ").slice(0, 200) || "tool call failed"}`);
+  let payload = null;
+  for (const block of blocks) {
+    try {
+      payload = JSON.parse(block);
+      break;
+    } catch {}
+  }
+  const sources = (payload?.results ?? [])
+    .filter((r) => r.url)
+    .map((r) => {
+      const excerpt = (r.excerpts ?? []).find((e) => String(e).trim().length > 0);
+      return {
+        url: r.url,
+        ...(r.title ? { title: String(r.title) } : {}),
+        ...(excerpt ? { snippet: String(excerpt).slice(0, 300) } : {}),
+        ...(r.publish_date ? { publishedAt: String(r.publish_date) } : {}),
+      };
+    });
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+
 // 把任意天数转成 Keenable 的相对时间格式（12h / Nd / Nmo / Ny）
 function formatKeenableRelative(days) {
   if (days <= 0.5) return "12h";
@@ -1817,15 +1903,13 @@ function apply(ctx, config) {
             const key = await resolveApiKey("FIRECRAWL_API_KEY", "firecrawlApiKey");
             result = await searchFirecrawl(request.query, request.maxResults, key, timeRange, effSignal);
           } else if (engine === "parallel") {
-            // parallel：必须配置 PARALLEL_API_KEY（无 key 跳过，同 perplexity）
+            // parallel：有 key 走 REST（支持 after_date 精确过滤），无 key 走 keyless MCP（免费匿名额度）
             const key = await resolveApiKey("PARALLEL_API_KEY", "parallelApiKey");
-            if (!key) {
-              lastError = new Error("Parallel requires PARALLEL_API_KEY");
-              if (engine === preferred) preferredFailure = "PARALLEL_API_KEY is not configured";
-              logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
-              continue; // 无 key 跳过
+            if (key) {
+              result = await searchParallel(request.query, request.maxResults, key, timeRange, effSignal);
+            } else {
+              result = await searchParallelMCP(request.query, request.maxResults, timeRange, effSignal);
             }
-            result = await searchParallel(request.query, request.maxResults, key, timeRange, effSignal);
           } else if (engine === "perplexity") {
             const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
             if (!key) {
@@ -1999,8 +2083,8 @@ function apply(ctx, config) {
         }
         case "parallel": {
           const key = await resolveApiKey("PARALLEL_API_KEY", "parallelApiKey");
-          if (!key) return { ok: false, error: "PARALLEL_API_KEY not configured" };
-          return await searchParallel(q, 2, key, tr);
+          if (key) return await searchParallel(q, 2, key, tr);
+          return await searchParallelMCP(q, 2, tr);
         }
         case "perplexity": {
           const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
@@ -2089,7 +2173,9 @@ function apply(ctx, config) {
                 }
                 return `- ${r.engine}: FAIL - ${r.error}`;
               });
-              return `Search engine test:\n${lines.join("\n")}`;
+              // 契约要求直接返回 ContentBlock[]：finalizeContent 在 tools/post-execute 之后才执行，
+              // 只返回字符串会让该阶段的消费者（如 dsh-hooks-codex）拿到裸字符串崩溃。
+              return [{ type: "text", text: `Search engine test:\n${lines.join("\n")}` }];
             },
           },
           async execute(args) {
@@ -2113,7 +2199,7 @@ function apply(ctx, config) {
             return { results };
           },
           finalizeContent(exec, result) {
-            // 把 render 输出包装成合法的 text block（content 必须是 block 数组）
+            // render 已直接返回 block 数组；这里仅作旧路径兼容兜底（幂等）
             const text = result.content;
             if (typeof text === "string" && text.length > 0) {
               return [{ type: "text", text }];
@@ -2172,7 +2258,7 @@ function apply(ctx, config) {
             },
             render(args, value) {
               const lines = value.sources.map((s, i) => `- [${s.title ?? s.url}](${s.url})${s.snippet ? ` - ${s.snippet.slice(0, 120)}` : ""}`);
-              return `Platform search (${value.platform}):\n${lines.join("\n") || "No results found."}`;
+              return [{ type: "text", text: `Platform search (${value.platform}):\n${lines.join("\n") || "No results found."}` }];
             },
           },
           async execute(args) {
@@ -2200,7 +2286,7 @@ function apply(ctx, config) {
             return { platform, sources };
           },
           finalizeContent(exec, result) {
-            // Tool-result content must be an array of content blocks, not a raw string.
+            // render 已直接返回 block 数组；这里保留为幂等兜底
             const text = result.content;
             return typeof text === "string" && text.length > 0 ? [{ type: "text", text }] : undefined;
           },
@@ -2263,7 +2349,7 @@ function apply(ctx, config) {
             },
             render(args, value) {
               const lines = value.sources.map((s, i) => `- [${s.title ?? s.url}](${s.url})${s.snippet ? ` - ${s.snippet.slice(0, 120)}` : ""}${s.publishedAt ? ` (${s.publishedAt})` : ""}`);
-              return `Search (${value.provider}${args.timeRange ? `, timeRange=${args.timeRange}` : ""}):\n${lines.join("\n") || "No results found."}${value.content ? `\n\n${value.content}` : ""}`;
+              return [{ type: "text", text: `Search (${value.provider}${args.timeRange ? `, timeRange=${args.timeRange}` : ""}):\n${lines.join("\n") || "No results found."}${value.content ? `\n\n${value.content}` : ""}` }];
             },
           },
           async execute(args) {
@@ -2293,7 +2379,7 @@ function apply(ctx, config) {
             };
           },
           finalizeContent(exec, result) {
-            // Tool-result content must be an array of content blocks, not a raw string.
+            // render 已直接返回 block 数组；这里保留为幂等兜底
             const text = result.content;
             return typeof text === "string" && text.length > 0 ? [{ type: "text", text }] : undefined;
           },
@@ -2334,12 +2420,12 @@ function apply(ctx, config) {
           "- tavily - FREE keyless or TAVILY_API_KEY for higher limits",
           "- keenable - FREE keyless (MCP) or KEENABLE_API_KEY for higher limits",
           "- firecrawl - FREE keyless or FIRECRAWL_API_KEY for higher limits",
-          "- parallel - requires PARALLEL_API_KEY",
+          "- parallel - FREE keyless (MCP) or PARALLEL_API_KEY for higher limits",
           "- 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.",
+          "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/parallel 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,7 +1,7 @@
 {
   "name": "dsh-free-search",
-  "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.",
+  "version": "0.4.32",
+  "description": "Free web search for DeepSeek Harness: 13 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable/Firecrawl/Parallel keyless; Perplexity/SerpBase/DeepSeek with key) + time filtering + platform search + web_fetch, with web settings UI.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {