dsh-free-search 0.2.0

package/lib/index.js

@@ -0,0 +1,815 @@
+import { SettingsConflictError, installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import z from "@deepseek-ai/schemastery";
+
+const DDG_HTML_URL = "https://html.duckduckgo.com/html/";
+const DDG_LITE_URL = "https://lite.duckduckgo.com/lite/";
+const BING_URL = "https://www.bing.com/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";
+
+const FREE_SEARCH_NS = settingsNamespace("free-search");
+const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
+const FREE_ENGINES = ["ddg", "ddg-lite", "bing", "searxng"];
+const ALL_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "exa", "perplexity", "deepseek-official"];
+
+function decodeEntities(text) {
+  return String(text)
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)));
+}
+
+function stripTags(html) {
+  return decodeEntities(String(html).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim());
+}
+
+function extractDdgUrl(rel) {
+  if (!rel) return null;
+  const m = rel.match(/uddg=([^&]+)/);
+  if (m) {
+    try {
+      return decodeURIComponent(m[1]);
+    } catch {
+      return m[1];
+    }
+  }
+  if (rel.startsWith("//")) return `https:${rel}`;
+  return rel;
+}
+
+function uniqueSources(sources, limit) {
+  const seen = new Set();
+  const out = [];
+  for (const s of sources) {
+    if (s.url && !seen.has(s.url)) {
+      seen.add(s.url);
+      out.push(s);
+    }
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+async function fetchHtml(url, signal) {
+  // 单次请求超时 12s，避免挂起被当成 Connection error
+  let response;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 12000);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort);
+    response = await fetch(url, {
+      headers: { "user-agent": USER_AGENT, "accept-language": ACCEPT_LANG },
+      signal: controller.signal,
+      redirect: "follow",
+    });
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    throw new Error(`connection error: ${error?.message ?? String(error)}`);
+  }
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} from ${url.split("?")[0]}`);
+  }
+  const html = await response.text();
+  // DuckDuckGo 反爬验证页检测（HTTP 202 或验证关键字）
+  if (response.status === 202 || /anomaly|captcha|unusual traffic|robot check/i.test(html.slice(0, 4000))) {
+    throw new Error("DuckDuckGo is rate-limited right now (anti-bot challenge, usually temporary) - Bing works");
+  }
+  return html;
+}
+
+// 带重试的抓取：网络错误/空结果时重试，间隔 1.5s，最多 3 次
+async function fetchHtmlWithRetry(url, signal) {
+  let lastError;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      const html = await fetchHtml(url, signal);
+      if (html.length > 500) return html;
+      lastError = new Error(`empty response (${html.length} bytes)`);
+    } catch (error) {
+      lastError = error;
+    }
+    if (attempt < 3) await new Promise((resolve) => setTimeout(resolve, 1500));
+  }
+  throw lastError ?? new Error("fetch failed");
+}
+
+async function searchDdgHtml(query, maxResults, options, signal) {
+  const params = new URLSearchParams({ q: query });
+  if (options?.region) params.set("kl", options.region);
+  const html = await fetchHtmlWithRetry(`${DDG_HTML_URL}?${params}`, signal);
+  const blocks = html.match(/<div class="result results_links[\s\S]*?<\/div>\s*<\/div>\s*<\/div>/g) ?? [];
+  const sources = [];
+  for (const block of blocks) {
+    const urlMatch = block.match(/<a[^>]*class="result__a"[^>]*href="([^"]*)"/);
+    const titleMatch = block.match(/<a[^>]*class="result__a"[^>]*>(.*?)<\/a>/);
+    const snippetMatch = block.match(/<a[^>]*class="result__snippet"[^>]*>(.*?)<\/a>/);
+    const dateMatch = block.match(/<span[^>]*>\s*([\dT:.+-]+)\s*<\/span>/);
+    const url = extractDdgUrl(urlMatch?.[1]);
+    if (!url) continue;
+    sources.push({
+      url,
+      ...(titleMatch ? { title: stripTags(titleMatch[1]) } : {}),
+      ...(snippetMatch ? { snippet: stripTags(snippetMatch[1]) } : {}),
+      ...(dateMatch ? { publishedAt: dateMatch[1] } : {}),
+    });
+  }
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+
+async function searchDdgLite(query, maxResults, signal) {
+  const params = new URLSearchParams({ q: query });
+  const html = await fetchHtmlWithRetry(`${DDG_LITE_URL}?${params}`, signal);
+  const linkMatches = html.match(/<a[^>]*class=['"]result-link['"][^>]*>[\s\S]*?<\/a>/g) ?? [];
+  const snippetMatches = html.match(/class=['"]result-snippet['"][^>]*>([\s\S]*?)<\/td>/g) ?? [];
+  const sources = [];
+  for (let i = 0; i < linkMatches.length; i++) {
+    const tag = linkMatches[i];
+    const hrefMatch = tag.match(/href="([^"]*)"/);
+    const titleMatch = tag.match(/class=['"]result-link['"][^>]*>(.*?)<\/a>/);
+    if (!hrefMatch) continue;
+    const url = extractDdgUrl(hrefMatch[1]);
+    if (!url) continue;
+    const snippet = snippetMatches[i]?.match(/class=['"]result-snippet['"][^>]*>([\s\S]*?)<\/td>/)?.[1];
+    sources.push({
+      url,
+      ...(titleMatch ? { title: stripTags(titleMatch[1]) } : {}),
+      ...(snippet ? { snippet: stripTags(snippet) } : {}),
+    });
+  }
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+
+async function searchBing(query, maxResults, options, signal) {
+  const params = new URLSearchParams({ q: query, mkt: options?.bingMarket ?? "zh-CN" });
+  const html = await fetchHtmlWithRetry(`${BING_URL}?${params}`, signal);
+  const blocks = html.match(/<li class="b_algo"[\s\S]*?<\/li>/g) ?? [];
+  const sources = [];
+  for (const block of blocks) {
+    const hrefMatch = block.match(/<a[^>]*href="(https?:\/\/[^"]+)"/);
+    const titleMatch = block.match(/<h2[^>]*>[\s\S]*?<a[^>]*>(.*?)<\/a>[\s\S]*?<\/h2>/);
+    const snippetMatch = block.match(/<p[^>]*>([\s\S]*?)<\/p>/);
+    if (!hrefMatch) continue;
+    sources.push({
+      url: hrefMatch[1],
+      ...(titleMatch ? { title: stripTags(titleMatch[1]) } : {}),
+      ...(snippetMatch ? { snippet: stripTags(snippetMatch[1]) } : {}),
+    });
+  }
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+
+//#region searxng (meta-search, free instances, auto-failover)
+const SEARXNG_INSTANCES = [
+  "https://opnxng.com",
+  "https://priv.au",
+  "https://searx.be",
+  "https://searx.tiekoetter.com",
+  "https://search.inetol.net",
+  "https://paulgo.io",
+];
+
+async function searchSearxng(query, maxResults, options, signal) {
+  const instances = options?.searxngInstances?.length
+    ? options.searxngInstances
+    : SEARXNG_INSTANCES;
+  let lastError = null;
+  for (const base of instances) {
+    try {
+      const params = new URLSearchParams({ q: query, format: "json" });
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 8000);
+      const onAbort = () => ctrl.abort();
+      signal?.addEventListener("abort", onAbort);
+      const response = await fetch(`${base}/search?${params}`, {
+        headers: { "user-agent": USER_AGENT, accept: "application/json" },
+        signal: ctrl.signal,
+      });
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      if (!response.ok) {
+        lastError = new Error(`${base} HTTP ${response.status}`);
+        continue;
+      }
+      const data = await response.json().catch(() => null);
+      if (!data || !Array.isArray(data.results)) {
+        lastError = new Error(`${base} invalid JSON`);
+        continue;
+      }
+      const sources = data.results
+        .filter((r) => r.url)
+        .map((r) => ({
+          url: r.url,
+          ...(r.title ? { title: String(r.title) } : {}),
+          ...(r.content ? { snippet: String(r.content) } : {}),
+        }));
+      if (sources.length > 0) {
+        return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+      }
+      lastError = new Error(`${base} 0 results`);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError ?? new Error("all SearXNG instances failed");
+}
+//#endregion
+
+//#region paid engines (exa / perplexity / deepseek-official)
+async function searchExa(query, maxResults, apiKey, signal) {
+  if (!apiKey) throw new Error("Exa search requires EXA_API_KEY");
+  const response = await fetch("https://api.exa.ai/search", {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      authorization: `Bearer ${apiKey}`,
+      "content-type": "application/json",
+      accept: "application/json",
+      "user-agent": "deepseek-harness/free-search",
+    },
+    body: JSON.stringify({
+      query,
+      type: "auto",
+      contents: { highlights: { highlightsPerUrl: 1 } },
+      ...(maxResults !== undefined ? { numResults: maxResults } : {}),
+    }),
+    ...(signal !== undefined ? { signal } : {}),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    if (response.status === 401) {
+      throw new Error("Exa API key is invalid (HTTP 401) - update it in Settings > Plugins > Free Search");
+    }
+    throw new Error(`Exa API error (HTTP ${response.status}): ${detail.slice(0, 200)}`);
+  }
+  const data = await response.json();
+  const sources = (data.results ?? [])
+    .map((result) => {
+      const snippet = result.highlights?.find((h) => h.trim().length > 0);
+      if (!snippet) return null;
+      return {
+        url: result.url,
+        ...(result.title ? { title: result.title } : {}),
+        snippet,
+        ...(result.publishedDate ? { publishedAt: result.publishedDate } : {}),
+      };
+    })
+    .filter(Boolean);
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+
+async function searchPerplexity(query, maxResults, apiKey, signal) {
+  if (!apiKey) throw new Error("Perplexity search requires PERPLEXITY_API_KEY");
+  const response = await fetch("https://api.perplexity.ai/chat/completions", {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      authorization: `Bearer ${apiKey}`,
+      "content-type": "application/json",
+      accept: "application/json",
+    },
+    body: JSON.stringify({
+      model: "sonar",
+      max_tokens: 1024,
+      messages: [{ role: "user", content: query }],
+    }),
+    ...(signal !== undefined ? { signal } : {}),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    if (response.status === 401) {
+      throw new Error("Perplexity API key is invalid (HTTP 401) - update it in Settings > Plugins > Free Search");
+    }
+    throw new Error(`Perplexity API error (HTTP ${response.status}): ${detail.slice(0, 200)}`);
+  }
+  const data = await response.json();
+  const answer = data.choices?.[0]?.message?.content ?? "";
+  const citations = data.citations ?? [];
+  const sources = citations.map((url) => ({ url, ...(answer ? { snippet: answer.slice(0, 200) } : {}) }));
+  return {
+    content: answer,
+    sources: uniqueSources(sources, maxResults ?? 10),
+    truncated: false,
+  };
+}
+
+async function searchDeepSeekOfficial(query, maxResults, apiKey, signal) {
+  if (!apiKey) throw new Error("DeepSeek search requires DEEPSEEK_API_KEY");
+  const response = await fetch("https://api.deepseek.com/anthropic/v1/messages", {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      "x-api-key": apiKey,
+      authorization: `Bearer ${apiKey}`,
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+      accept: "application/json",
+      "user-agent": "deepseek-harness/free-search",
+    },
+    body: JSON.stringify({
+      model: "deepseek-v4-flash",
+      max_tokens: 4096,
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: `Perform a web search for the query: ${query}` }],
+        },
+      ],
+      tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 1 }],
+    }),
+    ...(signal !== undefined ? { signal } : {}),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    if (response.status === 401) {
+      throw new Error("DeepSeek API key is invalid (HTTP 401) - update it in Settings > Plugins > Free Search");
+    }
+    throw new Error(`DeepSeek API error (HTTP ${response.status}): ${detail.slice(0, 200)}`);
+  }
+  const data = await response.json();
+  const blocks = data.content ?? [];
+  const resultBlocks = blocks.filter((block) => block.type === "web_search_tool_result");
+  const snippets = new Map();
+  for (const block of blocks) {
+    if (block.type !== "text") continue;
+    for (const cite of block.citations ?? []) {
+      if (cite.url && cite.cited_text && !snippets.has(cite.url)) snippets.set(cite.url, cite.cited_text);
+    }
+  }
+  const sources = [];
+  for (const block of resultBlocks) {
+    for (const item of block.content ?? []) {
+      if (item.type !== "web_search_result" || !item.url) continue;
+      if (sources.some((s) => s.url === item.url)) continue;
+      sources.push({
+        url: item.url,
+        ...(item.title ? { title: item.title } : {}),
+        ...(snippets.get(item.url) ? { snippet: snippets.get(item.url) } : {}),
+        ...(item.page_age ? { publishedAt: item.page_age } : {}),
+      });
+    }
+  }
+  return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
+}
+//#endregion
+
+//#region bridge
+const MAX_JSON_BODY_BYTES = 64 * 1024;
+
+function isLoopbackRequest(request) {
+  const address = request.socket.remoteAddress;
+  if (address !== "127.0.0.1" && address !== "::1" && address !== "::ffff:127.0.0.1") return false;
+  const host = request.headers.host;
+  if (typeof host !== "string") return false;
+  let hostUrl;
+  try {
+    hostUrl = new URL("http://" + host);
+  } catch {
+    return false;
+  }
+  if (hostUrl.hostname !== "127.0.0.1" && hostUrl.hostname !== "localhost" && hostUrl.hostname !== "[::1]") return false;
+  if (request.headers["sec-fetch-site"] === "cross-site") return false;
+  const origin = request.headers.origin;
+  if (origin === undefined) return true;
+  try {
+    return new URL(origin).host === hostUrl.host;
+  } catch {
+    return false;
+  }
+}
+
+function writeJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "referrer-policy": "no-referrer" });
+  res.end(payload);
+}
+
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = chunk;
+    size += buffer.length;
+    if (size > MAX_JSON_BODY_BYTES) return undefined;
+    chunks.push(buffer);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function toView(descriptor) {
+  return {
+    ns: String(descriptor.ns),
+    schema: descriptor.schema,
+    value: descriptor.value,
+    ...(descriptor.base === undefined ? {} : { base: descriptor.base }),
+    ...(descriptor.user === undefined ? {} : { user: descriptor.user }),
+    ...(descriptor.secrets === undefined
+      ? {}
+      : { secrets: descriptor.secrets.map((secret) => ({ path: [...secret.path], set: secret.set })) }),
+    revision: descriptor.revision,
+  };
+}
+
+function makeBridgeRoutes(settings) {
+  const allowlisted = () =>
+    settings
+      .describe({ redactSecrets: true })
+      .filter((descriptor) => String(descriptor.ns) === FREE_SEARCH_NS)
+      .map((descriptor) => String(descriptor.ns));
+
+  const handlers = {
+    async describe() {
+      const descriptors = settings.describe({ redactSecrets: true });
+      return {
+        ok: true,
+        value: {
+          namespaces: allowlisted()
+            .map((ns) => descriptors.find((descriptor) => String(descriptor.ns) === ns))
+            .filter((descriptor) => descriptor !== undefined)
+            .map(toView),
+          writable: settings.writable !== false,
+        },
+      };
+    },
+    async mutate(request) {
+      const body = request;
+      if (body === null || typeof body !== "object" || typeof body.ns !== "string" || !Array.isArray(body.ops)) {
+        return { ok: false, code: "settings-rejected", message: "malformed bridge settings request" };
+      }
+      const { ns } = body;
+      if (!allowlisted().includes(ns)) {
+        return { ok: false, code: "settings-not-exposed", message: `settings namespace "${ns}" is not exposed` };
+      }
+      const expectedRevision = typeof body.expectedRevision === "number" ? body.expectedRevision : undefined;
+      try {
+        await settings.mutate(settingsNamespace(ns), body.ops, expectedRevision);
+      } catch (error) {
+        if (error instanceof SettingsConflictError) {
+          return { ok: false, code: "settings-conflict", message: error.message };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, code: "internal", message };
+      }
+      const descriptor = settings.describe({ redactSecrets: true }).find((candidate) => String(candidate.ns) === ns);
+      if (descriptor === undefined) {
+        return { ok: false, code: "internal", message: `settings namespace "${ns}" was disposed after the mutate` };
+      }
+      return { ok: true, value: toView(descriptor) };
+    },
+  };
+
+  const guard = (req, res) => {
+    if (!isLoopbackRequest(req)) {
+      writeJson(res, 403, { error: "loopback requests only" });
+      return false;
+    }
+    if (req.method !== "POST") {
+      writeJson(res, 405, { error: "method not allowed: " + (req.method ?? "") });
+      return false;
+    }
+    return true;
+  };
+
+  return [
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/describe`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        writeJson(res, 200, await handlers.describe());
+      },
+    },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/mutate`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        const body = await readJsonBody(req);
+        if (body === undefined) {
+          writeJson(res, 400, { ok: false, code: "settings-rejected", message: "malformed JSON body" });
+          return;
+        }
+        writeJson(res, 200, await handlers.mutate(body));
+      },
+    },
+  ];
+}
+//#endregion
+
+const name = "web-search-free";
+const inject = ["web"];
+
+const Config = z.object({
+  provider: z.string().default("bing"),
+  region: z.string(),
+  bingMarket: z.string().default("zh-CN"),
+  searxngInstances: z.array(z.string()),
+  exaApiKey: z.string().role("secret"),
+  perplexityApiKey: z.string().role("secret"),
+  deepseekApiKey: z.string().role("secret"),
+});
+
+function apply(ctx, config) {
+  let current = () => config ?? {};
+  const logger = ctx.logger;
+  const credentials = ctx.get("credentials");
+
+  // key 优先级：settings 的 free-search.<x>ApiKey > 环境变量/credentials
+  const resolveApiKey = async (envName, settingsKey) => {
+    const cfg = current();
+    if (settingsKey && cfg[settingsKey]) return cfg[settingsKey];
+    if (credentials) {
+      try {
+        const resolved = await credentials.resolve(envName);
+        if (resolved?.value) return resolved.value;
+      } catch {}
+    }
+    return process.env[envName] ?? "";
+  };
+
+  // 总控 provider：按 settings 的 provider 字段路由到任意引擎。
+  // 免费引擎失败自动回退其他免费引擎；付费引擎缺 key 时报清晰错误（不静默切换）。
+  const provider = {
+    id: "ddg",
+    available() {
+      return true;
+    },
+    async search(request, signal) {
+      const cfg = current();
+      const preferred = cfg.provider ?? "bing";
+
+      // 付费引擎：直接调用，缺 key 报错
+      if (preferred === "exa") {
+        const key = await resolveApiKey("EXA_API_KEY", "exaApiKey");
+        return searchExa(request.query, request.maxResults, key, signal);
+      }
+      if (preferred === "perplexity") {
+        const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
+        return searchPerplexity(request.query, request.maxResults, key, signal);
+      }
+      if (preferred === "deepseek-official") {
+        const key = await resolveApiKey("DEEPSEEK_API_KEY", "deepseekApiKey");
+        return searchDeepSeekOfficial(request.query, request.maxResults, key, signal);
+      }
+
+      // 免费引擎：首选 + 自动回退（searxng 元搜索多实例自动切换）
+      const chain =
+        preferred === "ddg-lite"
+          ? ["ddg-lite", "ddg", "searxng", "bing"]
+          : preferred === "bing"
+            ? ["bing", "searxng", "ddg", "ddg-lite"]
+            : preferred === "searxng"
+              ? ["searxng", "bing", "ddg", "ddg-lite"]
+              : ["ddg", "searxng", "ddg-lite", "bing"];
+      let lastError = null;
+      for (const engine of chain) {
+        try {
+          let result;
+          switch (engine) {
+            case "ddg":
+              result = await searchDdgHtml(request.query, request.maxResults, cfg, signal);
+              break;
+            case "ddg-lite":
+              result = await searchDdgLite(request.query, request.maxResults, signal);
+              break;
+            case "bing":
+              result = await searchBing(request.query, request.maxResults, cfg, signal);
+              break;
+            case "searxng":
+              result = await searchSearxng(request.query, request.maxResults, cfg, signal);
+              break;
+            default:
+              result = await searchDdgHtml(request.query, request.maxResults, cfg, signal);
+          }
+          if (result.sources.length > 0) return result;
+          lastError = new Error(`engine "${engine}" 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);
+          logger.warn(`free-search: engine "${engine}" failed (${message}), trying next engine`);
+        }
+      }
+      throw lastError ?? new Error("all search engines failed");
+    },
+  };
+
+  installSettingsSection(ctx, FREE_SEARCH_NS, Config, config ?? {}, {
+    setSource: (source) => {
+      current = source;
+    },
+    onChange: () => {},
+  });
+
+  ctx.inject(["webServer", "settings"], (sctx) => {
+    sctx.effect(() => {
+      const disposers = makeBridgeRoutes(sctx.settings).map((route) => sctx.webServer.register(route));
+      return () => {
+        for (const dispose of disposers) dispose();
+      };
+    }, "free-search: settings bridge");
+  });
+
+  ctx.web.registerSearchProvider(provider);
+
+  // 测试工具：让 agent 逐个测试所有搜索引擎，报告可用性
+  const runEngineTest = async (engine, query) => {
+    const cfg = current();
+    const q = query || "DeepSeek Harness";
+    const attempt = async () => {
+      switch (engine) {
+        case "ddg":
+          return await searchDdgHtml(q, 2, cfg);
+        case "ddg-lite":
+          return await searchDdgLite(q, 2);
+        case "bing":
+          return await searchBing(q, 2, cfg);
+        case "searxng":
+          return await searchSearxng(q, 2, cfg);
+        case "exa": {
+          const key = await resolveApiKey("EXA_API_KEY", "exaApiKey");
+          if (!key) return { ok: false, error: "EXA_API_KEY not configured" };
+          return await searchExa(q, 2, key);
+        }
+        case "perplexity": {
+          const key = await resolveApiKey("PERPLEXITY_API_KEY", "perplexityApiKey");
+          if (!key) return { ok: false, error: "PERPLEXITY_API_KEY not configured" };
+          return await searchPerplexity(q, 2, key);
+        }
+        case "deepseek-official": {
+          const key = await resolveApiKey("DEEPSEEK_API_KEY", "deepseekApiKey");
+          if (!key) return { ok: false, error: "DEEPSEEK_API_KEY not configured" };
+          return await searchDeepSeekOfficial(q, 2, key);
+        }
+        default:
+          return { ok: false, error: `unknown engine: ${engine}` };
+      }
+    };
+    try {
+      const result = await attempt();
+      // 付费引擎无 key：直接透传失败结果
+      if (result.ok === false) return result;
+      // 免费引擎偶发反爬/空结果时重试一次
+      if (result.sources && result.sources.length === 0) {
+        await new Promise((resolve) => setTimeout(resolve, 1500));
+        return await attempt();
+      }
+      return { ok: true, sources: result.sources ?? [], truncated: result.truncated ?? false };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+
+  ctx.inject(["tools"], (sctx) => {
+    sctx.effect(() => {
+      const dispose = sctx.tools.register(
+        defineTool({
+          name: "free_search_test",
+          description:
+            "Test every configured web search engine and report which ones work. Use this to verify engine availability, diagnose search failures, or check whether an API key is configured.",
+          parameters: {
+            engines: {
+              type: "array",
+              description: "Which engines to test (default: all). Options: ddg, ddg-lite, bing, exa, perplexity, deepseek-official.",
+              items: { type: "string" },
+            },
+            query: {
+              type: "string",
+              description: "Optional search query to use for the test (default: 'DeepSeek Harness').",
+            },
+          },
+          output: {
+            schema: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                results: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      engine: { type: "string" },
+                      status: { type: "string" },
+                      results: { type: "number" },
+                      error: { type: "string" },
+                      sampleTitle: { type: "string" },
+                      sampleUrl: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+            render(args, value) {
+              const lines = value.results.map((r) => {
+                if (r.status === "ok") {
+                  return `- ${r.engine}: OK (${r.results} results${r.sampleTitle ? `, e.g. "${r.sampleTitle.slice(0, 40)}"` : ""})`;
+                }
+                return `- ${r.engine}: FAIL - ${r.error}`;
+              });
+              return `Search engine test:\n${lines.join("\n")}`;
+            },
+          },
+          async execute(args) {
+            const engines = args.engines && args.engines.length > 0 ? args.engines : ALL_ENGINES;
+            const results = [];
+            for (const engine of engines) {
+              const r = await runEngineTest(engine, args.query);
+              if (r.ok) {
+                const item = {
+                  engine,
+                  status: "ok",
+                  results: r.sources.length,
+                };
+                if (r.sources[0]?.title) item.sampleTitle = String(r.sources[0].title);
+                if (r.sources[0]?.url) item.sampleUrl = String(r.sources[0].url);
+                results.push(item);
+              } else {
+                results.push({ engine, status: "fail", error: r.error ?? "unknown error" });
+              }
+            }
+            return { results };
+          },
+          finalizeContent(exec, result) {
+            // 把 render 输出包装成合法的 text block（content 必须是 block 数组）
+            const text = result.content;
+            if (typeof text === "string" && text.length > 0) {
+              return [{ type: "text", text }];
+            }
+            return undefined;
+          },
+        })
+      );
+      return () => {
+        dispose();
+      };
+    }, "free-search: test engines tool");
+  });
+
+  // 让 agent 知道可用搜索引擎（动态生成，随 key 配置变化）
+  ctx.inject(["systemPrompt"], (sctx) => {
+    sctx.effect(() => {
+      const section = {
+        name: "free-search:engines",
+        order: 500,
+        text: [
+          "## Available web search engines (free-search plugin)",
+          "",
+          "You have the web_search tool. Its backend engine is chosen in Settings > Plugins > Free Search.",
+          "Current engine: " + (current().provider ?? "bing"),
+          "",
+          "Available engines and their requirements:",
+          "- ddg (DuckDuckGo HTML) - FREE, no key (may be rate-limited)",
+          "- ddg-lite (DuckDuckGo Lite) - FREE, no key (may be rate-limited)",
+          "- bing (Bing) - FREE, no key (most stable)",
+          "- searxng (meta-search, multi-instance) - FREE, no key",
+          "- exa - requires EXA_API_KEY",
+          "- perplexity - requires PERPLEXITY_API_KEY",
+          "- deepseek-official - requires DEEPSEEK_API_KEY",
+          "",
+          "FREE engines auto-fallback to another FREE engine on failure. Paid engines fail with a clear error when their key is missing - tell the user which key to configure.",
+          "",
+          "Use the free_search_test tool to test which engines actually work right now.",
+        ].join("\n"),
+      };
+      const dispose = sctx.systemPrompt.section(section);
+      return () => {
+        dispose();
+      };
+    }, "free-search: engine list prompt section");
+  });
+}
+
+export {
+  ALL_ENGINES,
+  BING_URL,
+  Config,
+  DDG_HTML_URL,
+  DDG_LITE_URL,
+  FREE_ENGINES,
+  FREE_SEARCH_NS,
+  SEARXNG_INSTANCES,
+  apply,
+  inject,
+  name,
+  searchBing,
+  searchDeepSeekOfficial,
+  searchDdgHtml,
+  searchDdgLite,
+  searchExa,
+  searchPerplexity,
+  searchSearxng,
+};