dsh-free-search

dsh plugin --profile web add dsh-free-search

dsh-free-search

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

[中文](#中文) · [English](#english)

---

中文

<div align="center">

<a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png">

<img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png" alt="免费引擎设置 (Bing)" width="820" />

</a>

<br>

_{▲ 免费引擎（以Bing为例）}

</div>

为什么需要它

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、Outcrawl、DeepSeek 官方、DeepSeek 原生搜索 API、You.com、百度千帆、Kimi、阿里云百炼、火山联网搜索（豆包搜索）、知乎全网/站内（zhihu_global/zhihu_site，经知乎开放平台 MCP）、Antigravity CLI 搜索（agy，需本机安装）、OpenAI / Gemini / Claude 模型内置搜索
• 5 个 HTML 搜索页引擎（默认关闭） —— 把传统搜索页并入同一套引擎 / 回退 / 冷却 / 设置体系：baidu-html（百度网页）、so360、sogou、wechat（微信文章）、toutiao。免 key、免额度，代价是抓页面：验证码/反爬按 bot-wall 归类并让整个家族冷却 10 分钟（整段出口 IP 都会被打标），结果也没有 API 摘要。它们默认不进 auto / 回退链 / 语言池，只在显式 engine= 或加入语言池时运行。
• 按 key 冷却与诊断 —— 429 与额度错误按 key 分别冷却，同一引擎的其他 key 不受牵连；冷却状态写入磁盘，重启后仍在；失败信息和日志里的 key 一律打码；设置页底部的「诊断」按钮列出每个引擎当前为什么不可用、冷却还剩多久
• 引擎白名单 —— 设置页「只使用勾选的引擎」开启后，只有勾选的引擎可用，升级新增的引擎默认不启用；配置里对应 allowedEngines（非空时等价于把其余引擎全部禁用）
• 自带更新 —— 卡片底部显示当前版本和「检查更新」；npm 安装的版本可一键升级到 latest，本地 link 开发模式改为跳转 npm 页面并提示 git pull
• 截断安全 —— 标题和摘要按码点截断，搜索结果、工具输出和 web_fetch 正文在离开插件前统一清除孤立代理；含 emoji 的结果不会再让会话历史出现无法序列化的字符（#108）
• 网页设置页 —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；入口在左侧「插件」页的组件行配置（plugins.row.config，DSH 0.1.7-rc.1+）。远程访问（VPS / 反向代理 / 自定义域名）下也能用：桥接接口沿用宿主的 Host 围栏，--trusted-host 与 --public-url 声明的地址会放行（#84）
• 右侧浮动目录 —— 卡片右侧的页面留白里浮出「引擎 / 回退 / 语言池 / 搜索行为 / 抓取 / 性能 / 提示词管理」七个快捷跳转，滚动自动高亮当前项、点击平滑跳转；不占用正文宽度（正文布局与 0.9.6 一致），右侧留白不足时自动隐藏；每项都是真链接（#/panel/plugins/dsh-free-search/<分区>），可复制、可开新标签，见下方「分区链接契约」

提示词分三段

设置页第七段「提示词」分成三段：状态、工具、约束。每段都有自己的翻页器，页 1 是内置英文、页 2 是内置中文，都按当前配置实时生成，不入盘，不能删也不能改；页 3 起是你自己加的页。发送时每段取你当前停的那一页，拼起来就是注入内容；三段都空则整段不注入。

「工具」那一段是九个工具各一行：前面的勾选框决定这个工具给不给模型，后面的框里是写给模型的那句话，只读，跟插件更新走，不能改。这一段的右上角有中英切换，一下切换全部工具；工具列表最上面是一个「全选」勾选框，勾上就是全部交给模型，取消就是全部不交，只勾一部分时它显示为半选。取消勾选的工具不再交给模型，工具说明也一并从请求里去掉，那一段里也不会再列出它。想加自己的要求，写在「约束」那一段的自定义页里。

分区链接契约（与 dsh-url-router 对接）

规则见 dsh-url-router/docs/panel-sections.md（数量不限，当前 7 段：engines / fallback / pools / behavior / fetch / performance / prompt）：

• 页面根发布恰好一个 data-dsh-panel-section="<id>" = 读者正在看的那一节（跟着滚动走，不做“到底=最后一节”的猜测）
• 每个分区容器带 data-dsh-section="<id>"（滚动目标）
• 侧栏每项是 <a data-dsh-section="<id>" href="#/panel/plugins/dsh-free-search/<id>">
• 本插件不写 URL：location.hash / history.pushState / replaceState 一律不碰，地址栏唯一写者是 dsh-url-router；地址栏里出现本页分区链接时（hashchange）插件负责把它滚进视野

加新分区只需三步：容器加 data-dsh-section="<新id>"、NAV_ITEMS 加一条（侧栏锚点自动生成，href 由 item.id 拼）、assert-rail-section 的 id 列表加一项。

• 多 key 轮换 —— 任何 key 字段（或对应环境变量）都可以用逗号 / 分号 / 换行分隔多把 key；平时按请求轮流使用（round-robin，避免单 key 撞 QPS/RPM 风控），遇到 401/402/429（鉴权失败、额度耗尽、限流）先轮换同一引擎的下一把，再走引擎回退；multi 模式同样生效（#96）
• 弹出式切换命令 —— 聊天框输入 /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）的网页文本包在 <untrusted-web-content> 边界内（正文里自带的同名标记会被剥离，防止提前闭合）；核心 web_search / web_fetch 由 DSH 核心自带同类提示（External web content follows...）；所有 snippet 统一清洗并截断到 300 字符
• 版本号 —— 设置卡片底部显示当前版本（跟随 PLUGIN_VERSION，随发布更新）。检查与升级交给官方插件页（插件 → 已安装 → dsh-free-search → 更新），插件不再自带第二套更新按钮
• 结果缓存 —— 相同查询（含引擎/时间过滤参数）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 抓取，零依赖）；X (Twitter) 经本地 Grok Build CLI（需 SuperGrok / X Premium 登录）
• 垂直领域直查（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）*

…(truncated)