DDDMUC/dsh-free-search

dsh-free-search

DeepSeek Harness 免费搜索插件 —— 无需 API key，零成本，多引擎可切换。 一个给 DeepSeek Harness (dsh) 添加多引擎搜索 provider 的插件，注册进 ctx.web seam。内置 web_search 工具自动选用，支持网页设置页切换引擎、配置 API key、一键测试所有引擎、弹出式命令切换引擎。

中文 · English

中文

▲ 免费引擎（以Bing为例）

为什么需要它

dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（DEEPSEEK_API_KEY）。如果你：

• 没有（或不想用）DeepSeek 官方 key，
• 用的是 opencode-go 这类网关（其 OpenAI 兼容端点不支持 web_search 工具），

……那么内置搜索必然失败，agent 会告诉你"无法联网"。

这个插件提供多个免费引擎 + 自动回退，彻底摆脱 DeepSeek 官方 key 的依赖。

特性

• 零成本 —— 多个免费引擎，无需 key、无需注册
• 多引擎可选：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase、Serply、DeepSeek 官方、DeepSeek 原生搜索 API、You.com、百度千帆、Kimi、阿里云百炼、火山联网搜索（豆包搜索）、知乎全网/站内（zhihu_global/zhihu_site，经知乎开放平台 MCP）、OpenAI / Gemini / Claude 模型内置搜索
• 网页设置页 —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；入口在左侧「插件」页的组件行配置（plugins.row.config，DSH 0.1.7-rc.1+）。远程访问（VPS / 反向代理 / 自定义域名）下也能用：桥接接口沿用宿主的 Host 围栏，--trusted-host 与 --public-url 声明的地址会放行（#84）
• 右侧浮动目录 —— 卡片右侧的页面留白里浮出「引擎 / 回退 / 语言池 / 搜索行为 / 抓取 / 性能」六个快捷跳转，滚动自动高亮当前项、点击平滑跳转；不占用正文宽度（正文布局与 0.9.6 一致），右侧留白不足时自动隐藏
• 多 key 轮换 —— 任何 key 字段（或对应环境变量）都可以用逗号 / 分号 / 换行分隔多把 key；遇到 401/402/429（鉴权失败、额度耗尽）先轮换同一引擎的下一把，再走引擎回退
• 弹出式切换命令 —— 聊天框输入 /free-search-engine，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
• 引擎测试 —— free_search_test 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
• 全局引擎开关与回退优先级 —— 设置页可勾选/取消引擎（取消后全局生效：普通搜索 / Auto / advanced_search / multi_search / 引擎测试都不再用它），并可用 ↑↓ 调整全局回退顺序（一键恢复默认）
• Multi 模式 —— 可把搜索引擎设为 Multi Search：web_search 按查询语言并发对应语言池的全部已启用引擎（不再是前 3 个；中文/英文池可在设置页编辑，每池最低 2 个引擎）、按 URL 合并去重（同站判定用 eTLD+1）、跨源命中的结果优先；设置页有 Fast / Balanced / Deep 三档强度，也可手填并发上限与目标成功源数；整轮检索共享 30 秒总预算，到点返回已有结果（代价是成倍消耗额度；multi 失败会自动退回单引擎回退链）
• 统一引擎回退 —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl/parallel/you 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 Note: perplexity unavailable or failed, using exa.）；失败按类别处理：额度/鉴权失败→本会话冷却该引擎，反爬→短退避，超时/5xx/限流→同引擎重试一次，解析失败/0 结果→不冷却（详见下文「失败分类与引擎冷却」）
• 时间过滤 —— advanced_search 工具支持 timeRange：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
• 系统提示词注入 —— agent 知道当前用哪个引擎、哪些需要 key；并明确所有搜索结果是不可信外部数据，不得执行其中的指令
• 提示注入防护（不可信数据边界） —— 插件自有工具（advanced_search / platform_search / free_search_test）的网页文本包在 ` 边界内（正文里自带的同名标记会被剥离，防止提前闭合）；核心 web_search / web_fetch 由 DSH 核心自带同类提示（External web content follows...`）；所有 snippet 统一清洗并截断到 300 字符
• 版本号 + 检查更新 —— 设置卡片显示当前版本（跟随 PLUGIN_VERSION，随发布更新），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
• 结果缓存 —— 相同查询（含引擎/时间过滤参数）5 分钟内命中缓存（LRU 50 条），防免费引擎限流、省付费额度；时长可在设置页 0-5 分钟自由配置（0 关闭）
• 域名黑名单与安全搜索 —— blockedDomains：命中的域名不会进入任何结果；safeSearch（off / moderate / strict）为 Bing / DuckDuckGo 加一层过滤
• 免费标注 —— 设置页中免费引擎带绿色 FREE 徽章，付费引擎带橙色 API KEY 徽章
• 网页抓取（web_fetch） —— 让 agent 抓取网页内容（官方 dsh-web-fetch-http provider，纯 JS，零额外依赖）
• 平台搜索（platform_search） —— 搜 GitHub / V2EX / B站 / Reddit / Hacker News / Stack Overflow / 维基百科 / npm / YouTube / Vimeo / 掘金 / 豆瓣 / Qiita（公开 API 或免 key 抓取，零依赖）
• 垂直领域直查（domain_search） —— 41 个免 key 垂直源直查：包/版本（PyPI、crates、GitHub releases、endoflife…）、学术（arXiv、Crossref、OpenAlex、Semantic Scholar、PubMed、dblp、Zenodo…）、安全（NVD、OSV、CISA KEV）、金融（SEC EDGAR、IMF、World Bank、CFETS、Yahoo Finance、CoinGecko…）、法律（US Federal Register、US CourtListener、openlegaldata、UK legislation）、新闻（Google News、GDELT）等
• 视频搜索（video_search） —— 跨站找视频：Bing Videos + DuckDuckGo Videos（免 key，失败互相回退），返回视频链接、标题与来源/时长等元信息
• 一次调用完成研究（research） —— 多引擎并发搜索 → 候选重排 → 分层抓取正文 → 段落选窗 → 带出处的 Markdown 证据包；模型组件（重排/嵌入/决策模型）全部可选，缺失或失败时静默回退规则路径
• 检索正文缓存（cache_search） —— 全文检索 research 抓过的正文（node:sqlite 持久缓存，存储 7 天；node:sqlite 不可用时自动降级为 no-op，免 flag 需 ≥ 22.13，22.5–22.12 需 --experimental-sqlite）
• 干净集成 —— 实现官方 WebSearchProvider seam 接口，与官方插件共存

如果这个插件帮到了你，欢迎给仓库点个 ⭐（GitHub）——星标是开发者继续维护的最大动力，感谢支持！

引擎列表

id · 引擎 · 费用 · 说明 auto · Auto 智能路由 · 动态 · 根据查询语言/时间条件自动选路（含中文优先 Bing/Baidu/Aliyun/AnySearch，英文优先 Bing/Exa/Tavily；时间过滤优先支持引擎），末尾全量回退 ddg · DuckDuckGo HTML · 免费 · 偶发限流（反爬），解封自动恢复 ddg-lite · DuckDuckGo Lite · 免费 · 轻量版，同上 bing · Bing · 免费 · 默认引擎，最稳定，中文优化（zh-CN） anysearch · AnySearch AI · 免费 · AI 搜索，无 key（匿名额度） searxng · SearXNG 元搜索 · 免费 · 多实例自动切换，支持自定义实例 exa · Exa · 免费 · 无 key 也可用（MCP 匿名），配 key 提升额度 tavily · Tavily · 免费 · 无 key 也可用（keyless 匿名），配 key 提升额度 keenable · Keenable · 免费 · 无 key 也可用（MCP 匿名），配 key 提升额度 firecrawl · Firecrawl · 免费 · 无 key 也可用（官方免 key 匿名额度），配 key 提升限额。注意：keyless 档按出口 IP 判定，VPN/代理出口会被 403 拒绝；插件会冷却 6 小时并说明原因（有 key 不受影响） parallel · Parallel · 免费 · 无 key 也可用（官方 MCP 匿名额度），配 key 提升额度并支持精确时间过滤 you · You.com · 免费 · 无 key 也可用（官方免 key 档，每天 100 次），配 YDC_API_KEY 提升额度（旧名 YOUCOM_API_KEY 继续兼容） perplexity · Perplexity · 付费 · 需 PERPLEXITY_API_KEY serpbase · SerpBase · 付费 · 需 SERPBASE_API_KEY（serpbase.dev，注册送 100 次免费额度） serply · Serply · 付费 · 需 SERPLY_API_KEY（serply.io，新账户 30 天内 2,500 次免费额度）；Google 网页结果，按设置页语言本地化 deepseek-official · DeepSeek 官方 · 付费 · 需 DEEPSEEK_API_KEY；走 Anthropic 兼容的 web_search 服务端工具，每次搜索是一整个模型轮次（慢、耗 token） deepseek-tools · DeepSeek 原生搜索 API · 付费 · 需 DEEPSEEK_API_KEY（与上一档共用）；直接 POST /v1/tools/search，无模型参与，返回结构化 results[]（title/url/summary/date），同 query 实测 ~0.3s vs 上一档 ~5-6s baidu · 百度千帆 AI 搜索 · 额度 · 需 BAIDU_API_KEY（千帆 AI 搜索，每日赠 50 次，超额按量后付费）；中文全网，支持时间过滤 kimi · Kimi（Moonshot）联网搜索 · 付费 · 需 MOONSHOT_API_KEY（basic 约 ￥0.01/次），返回带正文 chunks 的中文结果；无免费额度，适合显式选用或作质量升级池，不建议放进默认并发池 kimi · Kimi（Moonshot）联网搜索 · 付费 · 需 MOONSHOT_API_KEY（basic 约 ￥0.01/次），返回带正文 chunks 的中文结果 aliyun · 阿里云百炼 EnhancedSearch · 付费 · 需 DASHSCOPE_API_KEY（MCP search_pro，约 ￥0.03/次，新用户 200 次免费包）；中文全网带来源 hostname doubao · 火山引擎联网搜索（豆包搜索） · 免费额度 · 需 DOUBAO_SEARCH_API_KEY（联网搜索控制台开通，每月 500 次免费，超出按量付费）；中文时效内容强，支持时间/站点过滤，返回千字级摘要 zhihu_global · 知乎全网搜索（开放平台 MCP） · 免费额度 · 需 ZHIHU_API_KEY；每日 5,000 次试用额度（试用结束需另行开通）；支持时间过滤（publish_time）；无 key 时自动跳过 zhihu_site · 知乎站内搜索（开放平台 MCP） · 免费额度 · 需 ZHIHU_API_KEY；每日 5,000 次试用额度（与 zhihu_global 共享）；不支持时间过滤 zhihu_global · 知乎全网搜索（开放平台 MCP） · 付费 · 需 ZHIHU_API_KEY；支持时间过滤（publish_time）；无 key 时自动跳过 zhihu_site · 知乎站内搜索（开放平台 MCP） · 付费 · 需 ZHIHU_API_KEY；不支持时间过滤 openai · OpenAI 模型内置搜索 · 付费 · 需 OPENAI_API_KEY；走 Responses API 的 web_search 工具，返回带引用的回答。按次计费，仅在显式选中时使用（不参与自动回退/auto）；默认 gpt-6-luna，模型与端点可配（openaiModel / openaiBaseUrl） gemini · Gemini Grounding with Google Search · 付费 · 需 GEMINI_API_KEY（兼容 GOOGLE_API_KEY）；走官方推荐的 Interactions API（POST /v1beta/interactions，tools:[{type:"google_search"}]），从 steps[].content[].annotations 取引用。按次计费，仅在显式选中时使用；默认 gemini-3.8-flash，模型与端点可配（geminiModel / geminiBaseUrl） claude · Claude 服务端 web_search · 付费 · 需 ANTHROPIC_API_KEY；结果来自 web_search_tool_result。按次计费，仅在显式选中时使用；默认 claude-sonnet-5-5，模型与端点可配（claudeModel / claudeBaseUrl）

• 默认引擎为 `bing`（免费且最稳定），安装后开箱即用。
• 自动回退：任何引擎失败（免费限流/反爬，付费缺 key/无效/网络错误）都会自动轮流尝试下一个引擎——先试其他已配 key 的付费引擎，再试免费引擎（Bing/AnySearch 等），并在结果中附带回退提示——搜索不会因引擎问题直接失败。
• 设置页有官网链接：免费引擎显示"访问官网 →"，付费引擎显示"获取 API Key →"（新标签页打开）：
• Exa：
• Tavily：
• Keenable：
• Parallel：
• Perplexity：
• SerpBase：
• Serply：（API 文档：）
• DeepSeek：
• 豆包搜索（火山联网搜索）：
• You.com：

引擎额度分层

「免费 / 付费」二分不足以决定谁该进默认池——真正的约束是额度模型：有没有免费量、有多少、用超了怎么算。按这个口径分五档（配置并发池时按这档选，能避免整池并发时额度翻倍）：

档位 · 引擎 · 超出后 ① 无限免 key · ddg / ddg-lite / bing / searxng / anysearch · — ② 匿名额度（不配 key 也能跑） · exa / tavily / keenable / firecrawl / parallel / you（每天 100 次） · 配 key 提额 ③ 免费额度（需 key） · zhihu_global / zhihu_site（每日 5,000 次试用）、doubao（每月 500 次）、baidu（每日 50 次）、aliyun（新用户 200 次包） · 按量后付费 ④ 付费升级（需 key 才有产出） · serpbase（注册送 100 次）/ serply（30 天 2,500 次）/ perplexity / deepseek-official / deepseek-tools / kimi · 按量 / 按次 ⑤ 按次计费（模型内置，显式-only） · openai / gemini / claude · 按 token + 每次搜索

选默认池的经验：① 打底 + ③ 打主力；② 可以进但要知道它在烧匿名额度；④ 只在你确实需要该源时显式选用；⑤ 永不入池。完整的逐引擎额度事实与默认池提案见 docs/engine-quota-tiers.md。

为什么免费引擎不需要 key？

• AnySearch：其 v1/search REST 接口提供匿名的公共搜索额度，无需注册或 API key。额度有限流（适合日常搜索），但作为免费引擎之一，与其他免费引擎互相回退，体验稳定。
• Exa：公开 MCP 端点（mcp.exa.ai/mcp）支持匿名调用，不配 key 也能用；配置 EXA_API_KEY 后可获得更高额度。
• Tavily：通过 x-tavily-access-mode: keyless 头走 keyless 匿名额度，不配 key 即可用；配置 TAVILY_API_KEY 后走账号档，额度更高、结果质量更稳定。
• Keenable：无 key 时走其公开 MCP 端点（api.keenable.ai/mcp）匿名调用；配置 KEENABLE_API_KEY 后走 REST API（api.keenable.ai/v1/search），额度更高、按组织限流。
• Firecrawl：其 /v2/search 端点无需 key 即可使用（官方文档明确说明，有匿名限流）；配置 FIRECRAWL_API_KEY 后可提高限额。支持 tbs 时间过滤（qdr:h/d/w/m/y 与自定义日期区间）。
• You.com：无 key 时走官方免 key 档（api.you.com/v1/agents/search），每天 100 次免费搜索，无需注册；配置 YDC_API_KEY（旧名 YOUCOM_API_KEY 继续兼容）后走官方 Search API（ydc-index.io/v1/search），额度更高。

安装

git clone https://github.com/DDDMUC/dsh-free-search.git
dsh plugin --profile web add /path/to/dsh-free-search

然后重启：

dsh web

接管行为与验证

插件加载后自动接管搜索：

• web.searchProvider 未设置，或仍是 DSH 出厂默认的官方搜索 deepseek-official 时，自动切换为本插件的 provider（id 固定为 ddg）；
• 如果（你或别的插件）已显式选择其他 provider，本插件不抢占，只在启动日志输出 WARN 与切换用的 YAML。

接管会写进 profile（DSH 0.2.x）：从 0.2.0-rc.2 起 provider 选择存放在 config 的 volatile ref 里，只能经 settings.mutate("web", …) 写入，落盘结果就是 profiles//cordis.patch.yml 多出：

- id: web
  config:
    searchProvider: ddg
    fetchProvider: fs-quality-fetch

所以停用或卸载本插件之前，请先删掉 `- id: web` 这两行（或整行删掉让 DSH 回到出厂默认）。否则配置仍指向 ddg 而没有任何东西注册它，每次搜索都会失败：

Error: configured web provider "ddg" is not registered

更早的 DSH（0.1.x）由 patch 静态覆盖 config，不需要也更不该手写这段，这里不再赘述。

DSH 的「DeepSeek 搜索 API」开关

DSH 0.2.1 设置 → 网页搜索 → DeepSeek 搜索 API 开关会和本插件互相影响，行为如下：

操作 · 结果 打开开关 · web.searchProvider 写成 deepseek-search-api（属于「显式选择其他 provider」），本插件主动让路，搜索走官方直连 API；抓取同时变成 deepseek-fetch-api 关闭开关 · DSH 会把整行 - id: web 删掉，provider 回到出厂默认 deepseek-official —— 这是模型搜索（一次完整 aux 请求，实测 ~12s、按 token 计费），不是免费引擎 关闭后 · 0.9.8 起：插件检测到 deepseek-official 会在运行时补一次接管（日志 DSH's search switch put the web providers back to the official defaults — re-took …），通常几秒内恢复免费链路；若没恢复，完整重启 DSH

想换引擎请用 /free-search-engine 或本插件设置页，不要动那个开关。打开开关再关掉，官方直连会退回模型搜索，直到插件重新接管或重启。

如果你在 0.1.x 时代按旧文档手写过 - id: web，现在可以删掉：0.2.x 由运行时接管写入。手写时注意 fetchProvider 应该是 fs-quality-fetch（本插件注册的抓取 provider），不是 http。

• searchProvider: ddg —— 本插件的 provider id（固定值），不是"使用 DuckDuckGo 引擎"；用哪个引擎由设置页的 provider 字段决定（bing/baidu/auto/…）。
• fetchProvider: fs-quality-fetch —— 本插件的抓取 provider（直接 → exa contents → firecrawl → crawl4ai）。
• 想改用官方搜索：先删掉 `- id: web` 的两行，再在插件管理器里停用本插件。

姊妹插件：dsh-preset-workbench（预设工作台）

同作者的姊妹插件：在设置页里可视化创建/编辑 Agent 预设——分段提示词、15 项能力开关、内置「鲸鱼娘 / 梁神模式」模板，不用手写 YAML。两者搭配：free-search 解决"AI 联网搜索"、preset-workbench 解决"AI 人设能力编排"，都是纯免费、开箱即用。

• 仓库：
• 安装：dsh plugin --profile web add github:DDDMUC/dsh-preset-workbench
• 用法：设置 → 预设工作台

如果你觉得 preset-workbench 也有用，同样欢迎给它的仓库点个 ⭐。🙏

依赖说明

插件对 @deepseek-ai/dsh-settings 和 @deepseek-ai/dsh-tools 使用 peerDependencies，这是刻意的：DSH 运行时必须使用安装树中的唯一实例。请通过 dsh plugin --profile add ... 安装插件，不要把 DSH 核心包复制进 profile 的本地 node_modules；重复副本会导致工具调度器失效。

使用

网页设置（推荐）

安装后打开配置页（DSH 0.1.7-rc.1+）：

• 左侧 插件 页 → 已安装 分组 → free-search → 点击组件行 web-search-free（行内"配置"入口）

配置页提供：

• Search engine：下拉框切换引擎，保存即生效
• API keys：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek / SerpBase / Serply / You.com 填写 key（密码框，保存后只显示"已配置"；Exa / Tavily / Keenable / Firecrawl / Parallel / You.com 不填也可免 key 使用）
• 推荐：付费引擎 key 建议写入 harness 凭据中心 ~/.dsh/.credentials.yaml（如 DEEPSEEK_API_KEY: sk-...，与官方 LLM provider 一致，一处管理所有 key）。插件读取优先级：凭据中心 > 设置页 > 环境变量，设置页填的 key 仅作为遗留兼容。
• Test engine：直测当前引擎可用性（不走回退链，付费引擎无 key 会明确报错）
• Use Bing default：把当前搜索引擎切回稳定的免费 Bing；Discard 只撤销尚未保存的编辑
• Platform search：勾选启用 GitHub / V2EX / Bilibili / Reddit / Hacker News / Stack Overflow / 维基百科 / npm / YouTube / Vimeo / 掘金 / 豆瓣 / Qiita 平台搜索（platform_search 工具按此过滤）
• EN / 中文：切换界面语言（默认中文）

▲ 免费引擎（显示绿色 FREE 徽章与官网链接） ▲ 付费/API Key 引擎（显示橙色 API KEY 徽章与获取链接）

聊天框切换引擎（/free-search-engine）

不用进设置页也能切换引擎：在聊天框输入 /free-search-engine，弹出引擎选择窗口（和 /model 选模型一样的交互），点选即切换，当前引擎会标记出来。等效于设置页切换 + 保存，且界面语言跟随设置页（中文/英文）。

命令只改首选引擎配置，搜索仍走 web_search + 统一回退链：即使首选引擎挂了也会自动换其他引擎，永不直接失败。系统提示词同步刷新。

引擎开关、回退优先级与 Multi 模式

设置页有这些块（都会保存进条目 config）：

• 全局启用的搜索引擎：取消勾选后，该引擎会从普通 web_search 回退链、Auto 智能路由、advanced_search、multi_search 和引擎测试中全局排除；至少要保留一个引擎。
• 全局回退优先级：用 ↑↓ 调整先后顺序。首选引擎仍先尝试；Auto 保留"语言/时间"路由规则，但自定义后同一分组内及后续回退按此顺序。被禁用的引擎保留在列表里（标记「已禁用」）但不执行；「恢复默认顺序」一键还原。
• 中文查询池（zhPool）/ 英文查询池（enPool）：Auto 路由的起始组，也是 Multi 模式的并发池。按查询语言自动二选一（检测到中日韩文字走中文池，其余走英文池）；两池都可用 ↑↓ 排序、下拉添加引擎、「−」移除（每池最低 2 个引擎，无上限）。默认中文池 bing / baidu / aliyun / anysearch，默认英文池 bing / exa / tavily；禁用/冷却/缺 key 的引擎运行时自动跳过。
• 搜索引擎下拉里的 `Multi Search`：选中后 web_search 会并发查询查询语言对应池的全部已启用引擎（不再是前 3 个），URL 去重合并、跨源命中的结果排前面。注意整池并发会成倍消耗额度（池里含按额度计费引擎时尤其注意）；Multi 失败时会自动退回普通单引擎回退链并在结果里注明。

失败分类与引擎冷却（Failure-aware fallback）

回退链不再把所有失败一视同仁，而是先给失败分类（issue #36）：

• `quota`（额度/预算耗尽，HTTP 402 / `NO_MORE_CREDITS` / SerpBase 免费额度用尽）：立即切换，并把该引擎在本进程内冷却——后续搜索不再尝试它，避免反复撞墙；
• `auth`（401/403、key 无效或未配置）：同上，冷却到本会话结束（改好 key 重载插件即恢复）；
• `bot-wall`（如 DDG 反爬挑战）：冷却一小段（默认 60s）后再自动放回链中；
• `transient`（超时 / 5xx / 网络 / 429 限流）：同一引擎重试一次再回退，避免一次抖动就丢掉好引擎；
• `invalid-response`（解析失败 / 结构变化 / 返回 0 结果）：照常回退，但归类为插件侧问题，不冷却引擎。

回退结果的 Note: 现在会给出具体类别，例如 Note: exa is out of quota, using doubao.、Note: perplexity is misconfigured (API key rejected), using doubao.、Note: bing failed (transient), using doubao.。free_search_test 也会为每个失败引擎附上类别（failureClass）。

冷却只作用于本进程（重载插件或重启即清空），且对配置的首选引擎同样适用：若它正在冷却，本轮会跳过并回退，结果里注明 is cooling down；冷却中的引擎一旦成功即自动解冻。

fallbackOn 控制哪些失败类别允许触发回退：默认勾选全部六类，即当前的「搜索永不直接失败」；取消某类后，遇到该类失败会停下并把该引擎的错误报出，不再换引擎（例如去掉 invalid-response：首选引擎返回空/解析失败时直接报错，而不是静默退回低质引擎）。设为空数组 [] 则任何失败都立即中止。注意缺 key、被禁用、不支持时间过滤不算失败，无论怎样都照常换引擎。设置页有对应勾选框，也可在 config 写 fallbackOn: [quota, auth, bot-wall, transient, invalid-response, unknown]。

安全搜索（safeSearch）

safeSearch 控制内置来源是否额外套一层安全过滤，默认 off（不加参数，保持引擎自身默认行为）：

值 · 含义 off（默认） · 不加过滤参数，保持引擎默认行为 moderate · 过滤成人内容 strict · 最严格过滤

作用于 Bing（adlt）、DuckDuckGo HTML（adlt）、DuckDuckGo Lite（adlt）；其它引擎没有对应参数，不受影响。设置页有下拉框，也可直接在 config 里写 safeSearch: moderate。

fetch provider 接管（与其它 fetch 插件冲突）

插件运行时会尝试接管 web.fetchProvider：

• 未设置、或仍是出厂默认 http → 接管为 fs-quality-fetch（直连 → exa contents → firecrawl → crawl4ai）；
• 已被显式指向其它 provider（例如 playwright）→ 不抢占，只记一条日志（进程内只打一次）。

如果你同时装了也会注册 fetch provider 的插件（例如 dsh-web-fetch-playwright、dsh-chatgpt-subscription），请在 profile 的 `cordis.patch.yml` 里明确让一方退出：

- id: web
  config:
    fetchProvider: playwright   # 用别人的 fetch；本插件只接管 search

否则启动阶段可能出现「互相写 web config → web 服务重建 → 插件重复 apply」的循环（见 issue #82）。

如果你特意 pin 了 fetchProvider: http（只想要内置抓取），把 fetchProviderTakeover 设为 false 即可：本插件不再把 http 当成「出厂默认」去接管，但仍会在完全未设置时补上。

searchProvider 的规则相同：未设置或仍是 deepseek-official 时接管，显式指定其它 provider 时不抢占。

配置文件

DSH 0.1.7-rc.1 起，配置跟随 profile 的插件条目保存：设置页与 /free-search-engine 都会写入当前 profile 的 cordis.patch.yml 中 web-search-free（dsh-free-search）条目的 config。

旧版 ~/.dsh/settings.yaml 的 free-search: 段不会被 DSH 核心自动导入（核心的 importLegacyDocument 只为 ui-developer-tools / ui-onboarding / shell 三个段提供了映射），原文件在导入其它段后会被改名为 settings.yaml.imported，该段的值只留在那里。插件会在启动时检测 settings.yaml.imported（或仍存在的 settings.yaml）中的 free-search: 段，把可识别的字段一次性补种进当前 profile 的条目 config（写一次后不再重复，可在启动日志看到 free-search: migrated N field(s)…）。如果你想手动处理，也可以照着 settings.yaml.imported 里的值在插件页行配置中填一遍。