免费搜索插件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、DeepSeek 官方
- 网页设置页 —— 引擎切换 + API key 配置（UI 中 key 脱敏显示“已配置”）+ 中英文切换；DSH 0.1.6-alpha.2+ 入口在左侧「插件」页的组件行配置，旧版在「设置 → 插件 → 可配置」
- 弹出式切换命令 —— 聊天框输入 /free-search-engine，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
- 引擎测试 —— free_search_test 工具让 agent 一键测试所有引擎；设置页也有“测试引擎”按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
- 统一引擎回退 —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl/parallel 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 Note: perplexity unavailable or failed, using exa.）
- 时间过滤 —— advanced_search 工具支持 timeRange：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
- 系统提示词注入 —— agent 知道当前用哪个引擎、哪些需要 key
- 版本号 + 检查更新 —— 设置卡片显示当前版本（v0.4.17），“检查更新”按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
- 结果缓存 —— 相同查询（含引擎/时间过滤参数）5 分钟内命中缓存（LRU 50 条），防免费引擎限流、省付费额度；时长可在设置页 0-5 分钟自由配置（0 关闭）
- 免费标注 —— 设置页中免费引擎带绿色 FREE 徽章，付费引擎带橙色 API KEY 徽章
- 网页抓取（web_fetch） —— 让 agent 抓取网页内容（官方 dsh-web-fetch-http provider，纯 JS，零额外依赖）
- 平台搜索（platform_search） —— 搜 GitHub / V2EX / B站 / Reddit / Hacker News / Stack Overflow / 维基百科 / npm（公开 API，零依赖）
- 干净集成 —— 实现官方 WebSearchProvider seam 接口，与官方插件共存

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

引擎列表

| id | 引擎 | 费用 | 说明 |
|---|---|---|---|
| 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 提升限额 |
| parallel | Parallel | 免费 | 无 key 也可用（官方 MCP 匿名额度），配 key 提升额度并支持精确时间过滤 |
| perplexity | Perplexity | 付费 | 需 PERPLEXITY_API_KEY |
| serpbase | SerpBase | 付费 | 需 SERPBASE_API_KEY（serpbase.dev，注册送 100 次免费额度） |
| deepseek-official | DeepSeek 官方 | 付费 | 需 DEEPSEEK_API_KEY |

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

为什么免费引擎不需要 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 与自定义日期区间）。

安装

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

然后重启：

dsh 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 版本打开配置页：

- DSH 0.1.6-alpha.2 及以上：左侧 插件 页 → 已安装 分组 → free-search → 点击组件行 web-search-free（行内“配置”入口）
- DSH 0.1.5 及更早：设置 → 插件 → 可配置 标签页 → Free Search 卡片

配置页提供：

- Search engine：下拉框切换引擎，保存即生效
- API keys：为 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 填写 key（密码框，保存后只显示“已配置”；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 只撤销尚未保存的编辑
- Platform search：勾选启用 GitHub / V2EX / Bilibili 平台搜索（platform_search 工具按此过滤）
- EN / 中文：切换界面语言（默认中文）

▲ 免费引擎（显示绿色 FREE 徽章与官网链接）

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

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

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

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

配置文件

配置存在 ~/.dsh/settings.yaml：

free-search:
provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / serpbase / deepseek-official
lang: zh                    # 设置页界面语言（zh / en）
bingMarket: zh-CN           # Bing 市场
region: cn-zh               # DuckDuckGo 区域（可选）
searxngInstances:           # 自定义 SearXNG 实例（可选）
- https://your-instance.example
exaApiKey: ...              # 或通过设置页填写
tavilyApiKey: ...           # 或通过设置页填写
keenableApiKey: ...         # 或通过设置页填写
firecrawlApiKey: ...        # 或通过设置页填写
parallelApiKey: ...         # 或通过设置页填写
perplexityApiKey: ...
serpbaseApiKey: ...         # 或通过设置页填写
deepseekApiKey: ...

让 agent 测试所有引擎

对 agent 说“测试一下所有搜索引擎”，它会调用 free_search_test 工具，逐个测试并报告：

Search engine test:
- ddg: FAIL - DuckDuckGo is rate-limited right now (anti-bot challenge, usually temporary) - Bing works
- bing: OK (2 results, e.g. "DeepSeek Harness developer preview...")
- exa: FAIL - EXA_API_KEY not configured

时间过滤（advanced_search）

让 agent 搜“最近一周的新闻”、“这个月的发布”、“最近 3 天的消息”、“7 月以来的更新”，它会调用 advanced_search 工具，带 timeRange 参数。该工具同样走统一回退链，且可显式指定 engine，返回结构同 web_search。

timeRange 支持三种形式：

| 形式 | 示例 | 含义 |
|---|---|---|
| 固定档 | day / week / month / year | 分别 = 1 / 7 / 30 / 365 天 |
| 自定义相对值 | 12h、3d、2mo、1y | 最近 12 小时 / 3 天 / 2 个月 / 1 年 |
| 绝对日期 | 2026-07-01 | 该日期（含）之后发布的结果 |

各引擎对 timeRange 的处理逻辑：

| 引擎 | 参数 | 是否精确 | 说明 |
|---|---|---|---|
| Exa | startPublishedDate | ✅ 精确 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
| 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（有 key 时精确）；无 key 走 MCP，无日期参数，改为把窗口写进 objective 作为新鲜度提示（软过滤） | ✅ 精确 / ⚠️ 软过滤 | 自定义天数转成 ISO 日期（N 天前），绝对日期原样传入 |
| SearXNG | time_range | ⚠️ 近似 | 同上 |
| DuckDuckGo / Lite | df | ⚠️ 近似 | 同上 |
| Bing / AnySearch | — | ❌ 忽略 | 无对应参数 |

“最近似档位”映射规则：≤2 天 → day，≤14 天 → week，≤90 天 → month，否则 year。例如 3d 在 Tavily 上按 day 处理，2mo 按 month 处理。

引擎链优先级：当带 timeRange 搜索时，支持时间过滤的引擎（tavily / exa / keenable / firecrawl / parallel / searxng / ddg / ddg-lite）会排到引擎链前面，确保过滤真正生效——即使首选引擎是 bing（不支持过滤），也会先尝试支持过滤的引擎。

示例对话：“帮我搜最近 3 天关于 DSH 的新闻” → agent 调用 advanced_search，timeRange: "3d"。

抓取网页内容（web_fetch）

搜索到 URL 后，可以让 agent 读取网页全文（如“打开第一个链接看看内容”）。web_fetch 工具已启用（官方 dsh-web-fetch-http provider）：

- 自动跟随重定向、解码正文（HTML 转文本）
- 支持超时和大小限制
- ⚠️ 注意：web_fetch 无 SSRF 防护，agent 理论上可访问内网地址——按需使用

平台搜索（platform_search）

让 agent 搜特定平台，如“在 GitHub 上搜 deepseek harness”、“看看 B站有什么相关视频”、“V2EX 上关于 dsh 的讨论”。platform_search 工具支持：

| 平台 | 用途 |
|---|---|
| github | GitHub 仓库搜索（API，免费无 key） |
| v2ex | V2EX 热门/相关主题 |
| bilibili | B站视频/内容搜索（公开接口） |
| reddit | Reddit 帖子/讨论搜索（公开 JSON API；部分网络环境可能被 Reddit 反爬拦截） |
| hn | Hacker News 技术社区讨论（Algolia 官方 API） |
| stackoverflow | Stack Overflow 技术问答（Stack Exchange 官方公开 API） |
| wikipedia | 维基百科词条（中文环境用 zh.wikipedia.org，lang: en 时切换 en.wikipedia.org） |
| npm | npm 包搜索（registry 官方 API） |

全部走公开 API，零外部依赖、无需任何 key，开箱即用。

本地引擎切换工具（tools/）

tools/ 目录附带了一个本地切换小工具（零依赖）：

- 启动搜索引擎切换器.cmd（Windows）——双击启动本地 Node 服务（http://127.0.0.1:4789）并自动打开浏览器选择页面
- switch-engine.html —— 选择页面：显示当前引擎，点选新引擎，一键写入配置
- server.mjs —— 本地服务，负责读写 ~/.dsh/profiles/web/cordis.patch.yml
- switch-engine.ps1 —— 无界面命令行版：powershell -File tools/switch-engine.ps1 -Engine bing

切换后重启 dsh web 生效。

配置卡片挂在官方设置页的 settings.plugin.item 插槽（dsh 自带），配置读写走插件自建 bridge，不依赖 dsh-web-ui，插件可独立使用。

代理说明（国内用户）

DuckDuckGo 等引擎可能需要代理才能访问，而 Node.js 的 fetch 默认不走系统代理。需要给 dsh 进程设置（Node 24+）：

export NODE_USE_ENV_PROXY=1
export HTTPS_PROXY=http://127.0.0.1:7897   # 你的代理地址
export HTTP_PROXY=http://127.0.0.1:7897

Windows 用户：桌面快捷方式已内置此配置（set NODE_USE_ENV_PROXY=1&& set HTTPS_PROXY=...）。

工作原理

- lib/index.js：host 端。实现 WebSearchProvider（id / available() / search()），统一引擎路由 + 自动回退（付费引擎优先，免费兜底）；解析 timeRange（固定档/相对值/绝对日期）并透传给各引擎；注册 free-search settings namespace；提供 /api/dsh-free-search-settings 读写桥 + raw-search 调试接口；注册 free_search_test、platform_search、advanced_search 工具；动态注入引擎清单到系统提示词（设置变更时自动刷新）。
- lib/client.js：浏览器端。React 配置卡片（引擎选择 + key 输入 + 连通测试 + 中英切换），挂载到官方设置页的 settings.plugin.item 插槽；注册 /free-search-engine 弹出式切换命令（commandUi popupSelect，与 /model 同机制）。
- cordis.patch.yml：插件 loader 配置。

English

▲ 免费引擎（以 Bing 为例）

为什么你需要它
dsh 的默认搜索提供商依赖官方 DeepSeek API 密钥（DEEPSEEK_API_KEY）。如果你：
- 没有（或不愿使用）官方 DeepSeek 密钥，
- 使用像 opencode-go 这样的网关（其 OpenAI 兼容端点不支持 web_search 工具），

……那么内置搜索必然会失败，智能体会告诉你“我无法访问互联网。”

本插件提供多个免费搜索引擎并支持自动回退，让你完全摆脱对 DeepSeek 官方密钥的依赖。

功能特性

- 零成本 — 多个免费引擎，无需 API 密钥或注册
- 多引擎支持 — DuckDuckGo（HTML / Lite）、Bing、AnySearch AI、SearXNG（支持自定义实例的元搜索）、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase 以及 DeepSeek 官方
- Web 设置界面 — 引擎切换、API 密钥配置（密钥在界面中显示为“已配置”）、中英文切换；在 DSH 0.1.6-alpha.2+ 上入口为侧边栏插件页面的组件行配置，在旧版本上为设置 → 插件 → 可配置
- 弹窗切换命令 — 在聊天中输入 /free-search-engine：会打开一个包含所有引擎的选择器；点击即可切换（等同于设置页面 + 保存）
- 引擎测试 — free_search_test 供智能体一次调用检查所有引擎；设置界面也有“测试引擎”按钮，可直接测试所选引擎（不走回退链；无密钥的付费引擎会报告明确错误）
- 统一引擎回退 — 任何引擎失败（付费或免费、缺少密钥、401、限流、网络错误）都会自动尝试下一个引擎：先尝试已配置的引擎，然后尝试其他引擎（exa/tavily/keenable/firecrawl/parallel 即使没有密钥也会尝试，因为它们有内置的免密钥额度），再尝试剩余的免费引擎（Bing/AnySearch 等）——结果中会附带一条说明，指明实际提供服务的引擎（例如 Note: perplexity unavailable or failed, using exa.）。搜索永远不会彻底失败。
- 时间过滤 — advanced_search 工具支持 timeRange：固定档位、自定义相对值或绝对日期（详见下文）
- 系统提示注入 — 智能体知晓当前激活的引擎以及哪些引擎需要 API 密钥
- 版本 + 更新检查 — 设置卡片显示当前版本（v0.4.17），“检查更新”按钮会查询 npm registry 以对比最新版本，当存在更新版本时提示一键跳转
- 结果缓存 — 相同查询（相同引擎 / 时间过滤参数）会命中 LRU 缓存（50 条），最长 5 分钟，保护免费引擎免于限流并节省付费额度；TTL 可在设置界面中配置为 0-5 分钟（0 表示禁用缓存）
- 可视化徽章 — 免费引擎在设置界面中带有绿色 FREE 徽章，而付费引擎显示橙色 API KEY 徽章
- 网页抓取（web_fetch） — 允许智能体读取完整网页内容（官方 dsh-web-fetch-http 提供程序，纯 JS，零额外依赖）
- 平台搜索（platform_search） — 搜索 GitHub / V2EX / Bilibili / Reddit / Hacker News / Stack Overflow / Wikipedia / npm（公共 API，零额外依赖）
- 干净集成 — 实现官方 WebSearchProvider 接缝接口，与官方插件无缝共存

如果这个插件对你有帮助，在 GitHub 上点一个 ⭐ 将意义重大——这是开发者持续维护它的最大动力。谢谢！

支持的引擎

| id | 引擎 | 费用 | 描述 |
|---|---|---|---|
| ddg | DuckDuckGo HTML | 免费 | 偶尔会触发速率限制（反机器人挑战）；会自动恢复 |
| ddg-lite | DuckDuckGo Lite | 免费 | 轻量版本；速率限制行为与上述相同 |
| bing | Bing | 免费 | 默认引擎，最稳定，针对中文（zh-CN）优化 |
| anysearch | AnySearch AI | 免费 | AI 搜索，无需密钥（匿名配额） |
| searxng | SearXNG 元搜索 | 免费 | 多实例自动故障转移；支持自定义实例 |
| exa | Exa | 免费 | 无需密钥即可使用（匿名 MCP）；配置密钥可获得更高配额 |
| tavily | Tavily | 免费 | 无需密钥即可使用（无密钥匿名）；配置密钥可获得更高配额 |
| keenable | Keenable | 免费 | 无需密钥即可使用（匿名 MCP）；配置密钥可获得更高配额 |
| firecrawl | Firecrawl | 免费 | 无需密钥即可使用（官方无密钥匿名配额）；配置密钥可获得更高限额 |
| parallel | Parallel | 免费 | 无需密钥即可使用（官方 MCP 匿名配额）；密钥可提高限额并启用精确时间过滤 |
| perplexity | Perplexity | 付费 | 需要 PERPLEXITY_API_KEY |
| serpbase | SerpBase | 付费 | 需要 SERPBASE_API_KEY（serpbase.dev，注册赠送 100 次免费查询） |
| deepseek-official | DeepSeek 官方 | 付费 | 需要 DEEPSEEK_API_KEY |

- 默认引擎为 bing（免费且最稳定），安装后开箱即用。
- 自动故障转移：任何引擎故障（免费引擎被限流，或付费密钥缺失/无效，网络错误）都会自动尝试下一个引擎——先尝试配置的引擎，然后尝试其他引擎（exa/tavily/keenable/firecrawl/parallel 即使没有密钥也会尝试，因为它们内置了无密钥配额），再尝试其余免费引擎（Bing/AnySearch 等）——并在结果中附加一条说明，指明实际提供服务的引擎（例如 Note: perplexity unavailable or failed, using exa.）。搜索绝不会因引擎问题而彻底失败。
- 设置中的官方链接：免费引擎显示“访问网站 →”，付费引擎显示“获取 API 密钥 →”（在新标签页中打开）：
- Exa:
- Tavily:
- Keenable：
- Parallel：
- Perplexity：
- SerpBase：
- DeepSeek：

为什么有些引擎是免费的？

- AnySearch：其 v1/search REST 端点提供匿名公共搜索配额，无需注册或 API 密钥。配额受速率限制（足以应对日常查询），但作为具有相互回退机制的免费引擎之一，它依然保持可靠。
- Exa：其公共 MCP 端点（mcp.exa.ai/mcp）支持匿名请求，因此无需密钥即可使用；配置 EXA_API_KEY 可获得更高的使用配额。
- Tavily：通过 x-tavily-access-mode: keyless 请求头提供无密钥匿名配额——无需密钥即可使用；配置 TAVILY_API_KEY 可切换到账户层级，以获得更高配额和更稳定的结果。
- Keenable：无密钥时通过其公共 MCP 端点（api.keenable.ai/mcp）调用；配置 KEENABLE_API_KEY 可切换到 REST API（api.keenable.ai/v1/search），以获得更高配额和组织级速率限制。
- Firecrawl：其 /v2/search 端点开箱即用，无需密钥（官方文档称“无需 API 密钥即可开始使用”，并设有匿名速率限制）；配置 FIRECRAWL_API_KEY 可提高限制。支持 tbs 时间过滤（qdr:h/d/w/m/y 及自定义日期范围）。

安装

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

然后重启：

dsh web

姊妹插件：dsh-preset-workbench

同一作者的姊妹插件：一个可视化工作台，可直接在设置中创建/编辑智能体预设——分节提示词、15 项能力开关，以及内置的“鲸鱼女孩 / 梁神模式”模板，无需 YAML。搭配使用：free-search 为你的 AI 提供网络搜索，preset-workbench 塑造其人格与能力——两者均免费且零配置。

- 仓库：
- 安装：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 核心包复制到配置文件本地的 node_modules 中，因为重复副本可能会破坏工具调度器。

用法

Web 设置（推荐）

安装后，根据你的 DSH 版本打开配置页面：

- DSH 0.1.6-alpha.2 及更高版本：侧边栏 Plugins 页面 → Installed 分组 → free-search → 点击 web-search-free 组件行（该行的“configure”入口）
- DSH 0.1.5 及更早版本：设置 → 插件 → 可配置 标签页 → Free Search 卡片

配置页面提供：

- 搜索引擎：从下拉菜单中选择一个引擎；保存后更改立即生效。
- API 密钥：输入 Exa / Tavily / Keenable / Firecrawl / Parallel / Perplexity / DeepSeek 的密钥（密码字段；保存后显示为“已配置”；Exa / Tavily / Keenable / Firecrawl / Parallel 无需密钥也可使用）。
- 推荐：将付费引擎的密钥存储在 harness 凭据中心 ~/.dsh/.credentials.yaml 中（例如 DEEPSEEK_API_KEY: sk-...，与官方 LLM 提供商相同——所有密钥集中一处）。解析顺序：凭据中心 > 设置页面 > 环境变量；设置页面字段保留以向后兼容。
- 测试引擎：直接测试所选引擎（无回退链；未配置密钥的付费引擎会报告明确错误）。
- 使用 Bing 默认：暂存切换回稳定的免费 Bing 引擎；Discard 仅取消未保存的编辑
- 平台搜索：勾选平台（GitHub / V2EX / Bilibili / Reddit / HN / Stack Overflow / Wikipedia / npm）以为 platform_search 工具启用它们（已禁用的平台会被跳过）。
- EN / 中文：切换界面语言（默认中文）。

▲ 免费引擎（显示绿色 FREE 徽章和官方网站链接）

▲ 付费 / API 密钥引擎（显示橙色 API KEY 徽章和获取 API 密钥的链接）

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

你也可以直接在聊天中切换引擎——无需打开设置页面。输入 /free-search-engine：会打开一个包含所有引擎的选择器（与 /model 选择模型的交互相同）。点击一个即可切换；当前引擎会被标记。等同于在设置页面中切换并保存，语言跟随设置页面（中文/英文）。
该命令仅更改首选引擎；搜索仍会经过 web_search + 统一回退链——即使首选引擎失败，也会自动切换到其他引擎，绝不会直接失败。系统提示会相应地刷新。

配置文件

配置存储在 ~/.dsh/settings.yaml 中：

free-search:
provider: bing              # ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / firecrawl / parallel / perplexity / serpbase / deepseek-official
lang: zh                    # 设置界面语言（zh / en）
bingMarket: zh-CN           # Bing 市场
region: cn-zh               # DuckDuckGo 地区（可选）
searxngInstances:           # 自定义 SearXNG 实例（可选）
- https://your-instance.example
exaApiKey: ...              # 或通过 Web 设置界面配置
tavilyApiKey: ...           # 或通过 Web 设置界面配置
keenableApiKey: ...         # 或通过 Web 设置界面配置
firecrawlApiKey: ...        # 或通过 Web 设置界面配置
parallelApiKey: ...         # 或通过 Web 设置界面配置
perplexityApiKey: ...
serpbaseApiKey: ...         # 或通过 Web 设置界面配置
deepseekApiKey: ...

让 Agent 测试所有引擎

告诉 Agent “测试所有搜索引擎”，它就会调用 free_search_test 工具依次检查每个引擎并汇报结果：

搜索引擎测试：
- ddg: FAIL - DuckDuckGo 当前受到速率限制（反机器人挑战，通常是暂时的） - Bing 可用
- bing: OK（2 条结果，例如 “DeepSeek Harness developer preview...”）
- exa: FAIL - 未配置 EXA_API_KEY

时间过滤（advanced_search）

向 Agent 询问 “过去一周的新闻”、“本月的发布”、“过去 3 天的更新” 或 “自 7 月以来的帖子”，它就会调用带 timeRange 参数的 advanced_search 工具。它使用相同的统一回退链，可以强制指定 engine，并返回与 web_search 相同的结构。

timeRange 参数接受三种形式：

| 形式 | 示例 | 含义 |
|---|---|---|
| 固定档位 | day / week / month / year | = 1 / 7 / 30 / 365 天 |
| 自定义相对时间 | 12h、3d、2mo、1y | 过去 12 小时 / 3 天 / 2 个月 / 1 年 |
| 绝对日期 | 2026-07-01 | 在该日期或之后发布的结果 |

各引擎如何处理 timeRange：

| 引擎 | 参数 | 精确？ | 说明 |
|---|---|---|---|
| Exa | startPublishedDate | ✅ 精确 | 自定义天数会转换为 ISO 日期（N 天前）；绝对日期直接透传 |
| Keenable | published_after | ✅ 精确 | 相对值（12h/3d/2mo/1y）和绝对日期直接透传 |
| Tavily | time_range | ⚠️ 近似 | 仅支持固定档位；自定义天数会映射到最接近的档位 |
| Firecrawl | tbs | ⚠️ 近似 | 固定档位映射为 qdr:d/w/m/y；绝对日期使用 cdr:1,cd_min:M/D/YYYY（精确） |
| 并行 | 带密钥的 source_policy.after_date（精确）；不带密钥时 MCP 路径没有日期参数，因此时间窗口会作为新鲜度提示（软过滤）写入目标中 | ✅ 精确 / ⚠️ 软过滤 | 自定义天数会转换为 ISO 日期（N 天前）；绝对日期直接透传 |
| SearXNG | time_range | ⚠️ 近似 | 同上 |
| DuckDuckGo / Lite | df | ⚠️ 近似 | 同上 |
| Bing / AnySearch | — | ❌ 忽略 | 没有对应参数 |

最近层级映射规则：≤2 天 → day，≤14 天 → week，≤90 天 → month，否则为 year。例如，3d 在 Tavily 上会变为 day，2mo 会变为 month。

引擎链优先级：当存在 timeRange 时，支持时间过滤的引擎（tavily / exa / keenable / firecrawl / parallel / searxng / ddg / ddg-lite）会被移到回退链的前面，这样过滤器才能真正生效——即使首选引擎是 bing（不支持过滤），也会先尝试支持过滤的引擎。

示例：“查找最近 3 天的 DSH 新闻” → agent 调用 advanced_search，并传入 timeRange: "3d"。

抓取网页内容（web_fetch）

搜索之后，agent 可以读取完整网页内容（例如，“打开第一个链接并总结它”）。web_fetch 工具默认启用（官方 dsh-web-fetch-http 提供程序）：

- 自动跟随重定向，并将 HTML 解码为纯文本。
- 支持超时和响应大小限制。
- ⚠️ 注意：web_fetch 没有 SSRF 保护；agent 理论上可以访问内部网络地址。请按需使用。

平台搜索（platform_search）

让 agent 搜索特定平台（例如，“在 GitHub 上搜索 deepseek harness”、“在 Bilibili 上查找相关视频”，或 “V2EX 上关于 dsh 的讨论”）。platform_search 工具支持：

| 平台 | 用途 |
|---|---|
| github | GitHub 仓库搜索（公共 API，免费，无需密钥） |
| v2ex | V2EX 热门 / 相关主题 |
| bilibili | Bilibili 视频 / 内容搜索（公共 API） |
| reddit | Reddit 帖子 / 讨论（公共 JSON API；在某些网络环境中可能会被 Reddit 反机器人机制屏蔽） |
| hn | Hacker News 技术社区讨论（官方 Algolia API） |
| stackoverflow | Stack Overflow 问答（官方公共 Stack Exchange API） |
| wikipedia | 维基百科文章（中文使用 zh.wikipedia.org；当 lang: en 时切换到 en.wikipedia.org） |
| npm | npm 包搜索（registry 官方 API） |

所有平台搜索都依赖公共端点，零外部依赖，无需 API 密钥——开箱即用。

本地引擎切换器（tools/）

tools/ 目录包含一个轻量级、零依赖的切换器：

- 启动搜索引擎切换器.cmd（Windows）—— 双击启动本地 Node 服务器（http://127.0.0.1:4789），并自动在浏览器中打开引擎选择器页面。
- switch-engine.html — 选择器 UI：显示当前引擎状态，并支持一键切换。
- server.mjs — 本地后端服务，负责读写 ~/.dsh/profiles/web/cordis.patch.yml。
- switch-engine.ps1 — 无头 PowerShell 脚本：powershell -File tools/switch-engine.ps1 -Engine bing。

切换后请重启 dsh web 以应用更改。

设置卡片挂载到官方的 settings.plugin.item 插槽（DSH 内置），配置的读写通过插件自身的桥接进行。不依赖 dsh-web-ui —— 该插件可独立使用。

代理说明（面向中国大陆用户）

DuckDuckGo 等引擎可能需要代理。由于 Node.js 的 fetch 默认不使用系统代理，请为 dsh 进程设置以下环境变量（Node 24+）：

export NODE_USE_ENV_PROXY=1
export HTTPS_PROXY=http://127.0.0.1:7897   # 你的代理地址
export HTTP_PROXY=http://127.0.0.1:7897

Windows 用户：桌面快捷方式已包含此配置（set NODE_USE_ENV_PROXY=1&& set HTTPS_PROXY=...）。

工作原理

- lib/index.js：宿主端。实现 WebSearchProvider（id / available() / search()），统一引擎路由 + 自动回退（优先付费引擎，免费引擎作为回退）；解析 timeRange（固定档位 / 相对值 / 绝对日期）并将其转发给各引擎；注册 free-search 设置命名空间；提供 /api/dsh-free-search-settings 读写桥接 + raw-search 调试端点；注册 free_search_test、platform_search 和 advanced_search 工具；将引擎列表动态注入系统提示词（设置变更时自动刷新）。
- lib/client.js：浏览器端。React 配置卡片（引擎选择、密钥输入、连通性测试，以及中英文切换），挂载到官方的 settings.plugin.item 插槽；注册 /free-search-engine 弹窗切换命令（commandUi popupSelect，与 /model 相同的机制）。
- cordis.patch.yml：插件加载器配置。

许可证

MIT

safeSearch 安全搜索过滤

- 全新配置项 safeSearch：off（引擎默认，不加参数）/ moderate / strict
- 作用于 Bing（adlt）、DuckDuckGo HTML（adlt）、DuckDuckGo Lite（adlt）
- 默认 off：不额外过滤，保持引擎自身默认行为；需要时在「设置 > 插件 > Free Search」切换