dsh-union-search

dsh plugin --profile web add dsh-union-search

dsh-union-search

DeepSeek Harness 联合搜索插件（原 dsh-free-search）—— 免费搜索与多种专业付费搜索 API 的联合体。 一个给 DeepSeek Harness (dsh) 添加多引擎搜索 provider 的插件，注册进 ctx.web seam。内置 web_search 工具自动选用，支持网页设置页切换引擎、配置 API key、一键测试所有引擎、弹出式命令切换引擎。免费引擎开箱即用、零成本；也支持接入多种专业付费搜索 API（Perplexity / DeepSeek 官方 / Kimi / 智谱 / 博查 / 秘塔 / 豆包 / You.com / OpenAI / Gemini / Claude / Grok 等）提升结果质量。

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

---

中文

<div align="center">

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

<img src="https://raw.githubusercontent.com/drscrewdriver/dsh-union-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 会告诉你"无法联网"。

这个插件提供多个免费引擎 + 多种专业付费搜索 API + 自动回退：不配任何 key 开箱即用，彻底摆脱 DeepSeek 官方 key 的依赖；配置付费 key 后可获得更高额度与更专业的搜索质量。

特性

• 免费 + 付费联合 —— 多个零成本免费引擎（无需 key、无需注册）+ 多种专业付费搜索 API（Perplexity / DeepSeek 官方 / Kimi / 智谱 / 博查 / 秘塔 / 豆包 / You.com / OpenAI / Gemini / Claude / Grok 等）；只用免费引擎零成本，配付费 key 提质提额
• 多引擎可选：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase、Serply、DeepSeek 官方、You.com、百度千帆、Kimi、阿里云百炼、火山联网搜索（豆包搜索）、知乎全网/站内（zhihu_global/zhihu_site，经知乎开放平台 MCP）、智谱 Web Search（zhipu，普通平台 Key）、博查（bocha，DeepSeek 官方供应方）、秘塔（metaso，多模态）、OpenAI / Gemini / Claude / Grok（grok，xAI Responses API x_search 搜 X/Twitter）模型内置搜索
• 网页设置页 —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；入口在左侧「插件」页的组件行配置（plugins.row.config，DSH 0.1.7-rc.1+）
• 弹出式切换命令 —— 聊天框输入 /union-search-engine，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
• 引擎测试 —— 设置卡「测试全部引擎」一键逐个测试并列出结果，失败引擎进入建议禁用清单（勾选后「应用禁用」，保存生效；auto/multi 虚拟模式不会入列）；另有「测试引擎」按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
• 全局引擎开关与回退优先级 —— 设置页可勾选/取消引擎（取消后全局生效：普通搜索 / Auto / advanced_search / multi_search / 引擎测试都不再用它），并可用 ↑↓ 调整全局回退顺序（一键恢复默认）
• Multi 模式 —— 可把搜索引擎设为 Multi Search：web_search 并发请求前 3 个已启用引擎、按 URL 合并去重、跨源命中的结果优先（代价是成倍消耗额度；multi 失败会自动退回单引擎回退链）
• 统一引擎回退 —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable/firecrawl/parallel 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 Note: perplexity unavailable or failed, using exa.）；失败按类别处理：额度/鉴权失败→本会话冷却该引擎，反爬→短退避，超时/5xx/限流→同引擎重试一次，解析失败/0 结果→不冷却（详见下文「失败分类与引擎冷却」）
• 时间过滤 —— advanced_search 工具支持 timeRange：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
• 系统提示词注入 —— agent 知道当前用哪个引擎、哪些需要 key；并明确所有搜索结果是不可信外部数据，不得执行其中的指令
• 提示注入防护（不可信数据边界） —— 插件自有工具（advanced_search / platform_search / multi_search）的网页文本包在 <untrusted-web-content> 边界内（正文里自带的同名标记会被剥离，防止提前闭合）；核心 web_search / web_fetch 由 DSH 核心自带同类提示（External web content follows...）；所有 snippet 统一清洗并截断到 300 字符
• 版本号 + 检查更新 —— 设置卡片显示当前版本（v0.4.17），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
• 结果缓存 —— 相同查询（含引擎/时间过滤参数）5 分钟内命中缓存（LRU 50 条），防免费引擎限流、省付费额度；时长可在设置页 0-5 分钟自由配置（0 关闭）
• 免费标注 —— 设置页中免费引擎带绿色 FREE 徽章，付费引擎带橙色 API KEY 徽章
• 网页抓取（web_fetch） —— 让 agent 抓取网页内容（官方 dsh-web-fetch-http provider，纯 JS，零额外依赖）
• 增强抓取（advance_fetch，实验性 · 免费） —— 在 web_fetch 之上的插件自有工具，零 key、零按次计费（区别于按次计费的付费搜索 API）：整页转 GitHub-Flavored Markdown（转换配置与宿主 tool-web 同款复刻：不可见节点整体剔除、GFM 表格不展开跨列），并支持 CSS selector 限定范围与 fields（label=selector|attr，分号分隔）定向结构化抽取——只要页面的一部分时优先用它。依赖插件自带（turndown + @joplin/turndown-plugin-gfm + cheerio），不碰宿主内部面；输出经门户页脏面清洗（javascript: 等伪协议链接只留文本、布局表全空管道行丢弃、表格内 <br> 归一为 " / "、行边界截断不留残句/不拆代理对/不留未闭合代码围栏）；相对链接按最终 URL 自动绝对化并剥离 utm/gclid/fbclid 等跟踪参数；GBK/GB2312 等非 UTF-8 老站按声明字符集解码（header → BOM → meta charset 探测）；200 状态的反爬挑战页（captcha/验证码等文案 + 近空正文）识别为失败而非当正文；RSS/Atom 按文本透传；登录墙/纯客户端渲染站只返回壳并附 note 提示。抓取身份可配置：设置页可自定义 User-Agent、Referer 与按域 Cookie（逐行 域名 cookie串，仅在抓取目标匹配该域时附带、重定向换域不外流）——凭据只存设置页，勿在对话中粘贴。导航密集型门户页建议优先用 selector/fields 定向抽取；仅 http/https，重定向限 5 跳逐跳复检，SSRF 地址门默认拒绝回环/内网/云元数据地址（advanceFetchAllowPrivate 可显式放行局域网设备），抓取内容包进不可信边界
• 按需帮助（search_fetch_tool_manual） —— 转换分派（HTML/JSON/RSS 透传、字符集探测、跟踪参数剥离、输出上限与截断）、fields 语法、引擎清单（读当前设置生成，不另立第二份真相）、抓取身份（自定义 UA/Referer/按域 Cookie）与故障形态，都可按工具名或主题号在 search_fetch_tool_manual 查询；各工具描述只留短说明，不再把长规则平铺在每轮都付费的 schema 面里。
• 反馈内说明（note 通道） —— 与本次调用直接相关的局限随结果 note 返回：平台局限（如 v2ex 取热榜后本地过滤，不是站内全文）、某视频源空返、vimeo 搜索页空结果退回站内搜索、无结果、引擎成败清单等；advance_fetch 首次在会话内被调用时还会附一句指向手册的提示。指导类文字按「同会话同工具只发一次」去重——工具返回值进的是会话历史，每次调用都附等于把同一段说明复制多份，而首触一次既有「调用即得」的时机又不产生副本。
• 平台搜索（platform_search） —— 搜 GitHub / V2EX / B站 / Reddit / Hacker News / Stack Overflow / 维基百科 / npm / YouTube / Vimeo（公开 API 或免 key 抓取，零依赖）
• 视频搜索（video_search） —— 跨站找视频：Bing Videos + DuckDuckGo Videos（免 key，失败互相回退），返回视频链接、标题与来源/时长等元信息
• 干净集成 —— 实现官方 WebSearchProvider seam 接口，与官方插件共存
• 屏蔽系统自带搜索 —— 设置页「屏蔽系统自带搜索」开关（blockSystemSearch）：开启后强制接管 web_search，并把出厂官方搜索引擎 deepseek-official / rc.2 起的 deepseek-search-api 从所有引擎链与接管判据中剔除；保存即生效
• SearXNG 返回语言可锁定 —— 设置项 searxngLanguage（默认 auto）：自动档按 query 文字检测（假名→ja、谚文→ko、西里尔→ru、汉字→zh-CN，判不出落设置页语言兜底）；选具体值（zh-CN/zh-TW/en/ja/ko/ru/de/fr/es/all）则锁定不随 query 变化；非法 locale 自动归一防 400
• SearXNG 多实例综合 —— 自定义列表配置 ≥2 个端点时，自动向前两个端点并发双发请求，等两份请求都返回后按 URL 合并去重，双实例共同命中的条目优先；两个都失败才顺序回退剩余实例

如果这个插件帮到了你，欢迎给仓库点个 ⭐（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 元搜索 · 免费 · 实例三态严格互斥：公网池 / 本地 Docker（回环）/ 自定义列表，任一态不向其他态回落；自定义列表 ≥2 端点时自动向前两个并发双发、等两份都返回后综合（双命中条目优先）；返回语言按 query 文字自动判定（假名→ja、谚文→ko、西里尔→ru、汉字→zh-CN），判不出才落设置页

…(truncated)