# dsh-free-search

> 为 DeepSeek Harness 提供 10 个网页搜索引擎，无需 API key 即可联网搜索，自带时间过滤、平台搜索和网页设置界面。

## Metadata

- Author: [@DDDMUC](https://github.com/DDDMUC)
- Repo: <https://github.com/DDDMUC/dsh-free-search.git>
- GitHub: [DDDMUC/dsh-free-search](https://github.com/DDDMUC/dsh-free-search)
- Stars: 35
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `bing`, `deepseek-harness`, `dsh`, `dsh-plugin`, `duckduckgo`, `web-search`
- Forks: 4
- Open Issues: 0
- Last push: 2026-08-20T12:35:23.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:DDDMUC/dsh-free-search
```

## Wiki

## 一句话定位
给 DeepSeek Harness 提供 10 个可切换的网页搜索引擎，默认使用免费 Bing，无需任何 API key 就能让 agent 联网搜索，附带时间过滤、平台搜索和网页设置界面。

## 核心能力
- 提供 10 个网页搜索引擎（ddg / ddg-lite / bing / searxng / anysearch / exa / tavily / keenable / perplexity / deepseek-official），默认 bing 开箱即用
- 引擎失败自动回退：任何引擎出错（缺 key、401、限流、网络问题）都自动轮流尝试下一个，搜索永不直接失败，并在结果顶部注明实际生效的引擎
- 网页设置页 + 聊天框 `/free-search-engine` 命令切换引擎、配置 API key、测试连通性、切换中英文界面
- 支持时间过滤的 `advanced_search` 工具，可指定"最近 N 天/小时/月"或"某日期之后"
- 平台搜索 `platform_search` 工具，按 GitHub / V2EX / Bilibili / Reddit 检索公开 API
- 结果缓存（LRU 50 条，TTL 0-5 分钟可配），防免费引擎限流、节省付费额度

## 技术实现
- **语言**: JavaScript (ESM)
- **关键依赖**: `@deepseek-ai/dsh-settings`（配置接入与桥接）、`@deepseek-ai/dsh-tools`（注册 agent 工具）、`@deepseek-ai/schemastery`（配置 schema 校验）
- **架构模式**: 实现官方 `WebSearchProvider` 接口（`id / available / search`），通过 `cordis.patch.yml` 同时注入 `web-search-free` 子插件并把宿主 `web.searchProvider` 重定向到本插件的 `ddg` provider，让 DSH 自带的 `web_search` 工具自动走本插件的多引擎逻辑；host 端 + client 端双包（`lib/index.js` + `lib/client.js`）
- **入口文件**: `lib/index.js`（host 端，注册 provider/工具/设置面板桥接）、`lib/client.js`（浏览器端 React 设置卡片 + 弹出命令）

## 适用场景
当你不希望或没有 DeepSeek 官方 API key、又需要让 agent 联网搜索时使用本插件，例如日常问答、查资料、抓网页内容；或当你的 OpenAI 兼容网关不支持 `web_search` 工具时，本插件通过 host 端的实现直接接管搜索。普通用户想搜"最近一周 XX 新闻"、"GitHub 上找仓库"、"读一下这个链接的内容"这类需求都能直接覆盖。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH（@deepseek-ai/dsh-settings、@deepseek-ai/dsh-tools） | >= 0.1.0-rc.6 | peerDependencies，必须与宿主共用同一份安装 |
| Node | >= 20 | engines.node |
| 平台 | 跨平台 | 无原生模块，纯 JS + Node fetch |
| 原生模块 | 无 | 仅依赖 schemastery 校验配置 |

> 注意：`@deepseek-ai/dsh-settings` 和 `@deepseek-ai/dsh-tools` 刻意声明为 peerDependencies，DSH 运行时必须用安装树里的唯一实例。请通过 `dsh plugin --profile <profile> add ...` 安装，不要把 DSH 核心包复制到 profile 本地 `node_modules`，重复副本会破坏工具调度器。

## 安装方式
```bash
dsh plugin --profile web add github:DDDMUC/dsh-free-search
```

安装后重启 `dsh web` 生效。

## 配置项
配置保存在 `~/.dsh/settings.yaml` 的 `free-search` 命名空间下，也可通过网页设置页填写（key 字段在 UI 中只显示"已配置"，不会明文回显）。

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| provider | 字符串 | 首选搜索引擎，可选 `bing` / `ddg` / `ddg-lite` / `searxng` / `anysearch` / `exa` / `tavily` / `keenable` / `perplexity` / `deepseek-official` | `bing` |
| cache | 布尔 | 是否启用单 query 结果缓存（防限流、省额度） | `true` |
| cacheTtl | 数字 | 缓存时长（分钟），0-5 区间，0 关闭缓存 | `5` |
| lang | 字符串 | 设置页界面语言（`zh` / `en`） | `zh` |
| region | 字符串 | DuckDuckGo 区域（如 `cn-zh`） | 未设置 |
| bingMarket | 字符串 | Bing 市场代码 | `zh-CN` |
| searxngInstances | 字符串数组 | 自定义 SearXNG 实例地址列表，优先于内置实例 | 未设置 |
| platforms | 字符串数组 | 启用的平台搜索列表（github / v2ex / bilibili / reddit） | `[github, v2ex, bilibili, reddit]` |
| exaApiKey | 字符串（密钥） | Exa 引擎的 API key；不填走 MCP 匿名额度 | 未设置 |
| tavilyApiKey | 字符串（密钥） | Tavily 引擎的 API key；不填走 keyless 匿名额度 | 未设置 |
| keenableApiKey | 字符串（密钥） | Keenable 引擎的 API key；不填走 MCP 匿名额度 | 未设置 |
| perplexityApiKey | 字符串（密钥） | Perplexity 引擎的 API key（必需） | 未设置 |
| deepseekApiKey | 字符串（密钥） | DeepSeek 官方引擎的 API key（必需） | 未设置 |

## 常见问题

**Q: 安装后还需要配置 API key 吗？**

A: 不需要。默认引擎是免费 Bing，安装即可联网搜索。Exa/Tavily/Keenable 即使没填 key 也会走各家公开的匿名额度；只有 Perplexity 和 DeepSeek 官方这两个付费引擎需要 key。

**Q: 想换搜索引擎在哪里切换？**

A: 两种方式。在网页设置页 Settings → 插件 → 可配置 → Free Search 卡片的下拉框切换并保存；或在聊天框输入 `/free-search-engine` 弹出引擎选择窗口点选，效果等同于设置页切换+保存。

**Q: 一个引擎搜不到结果会怎样？**

A: 插件走统一回退链：首选引擎失败后依次尝试其他引擎（先已配 key 的付费引擎，再 Exa/Tavily/Keenable 的 keyless 通道，最后 Bing/AnySearch/DDG 等免费引擎）。结果顶部会加一行 Note 说明实际生效的引擎和跳过的原因（例如 "Note: perplexity unavailable or failed, using exa."）。

**Q: 怎么搜"最近一周的新闻"或"7 月以来的更新"？**

A: 直接用自然语言告诉 agent，例如"搜最近 3 天的 DSH 新闻"、"找 7 月以来的发布"。agent 会调用 `advanced_search` 工具并带上 `timeRange` 参数，支持固定档（day/week/month/year）、自定义相对值（`12h` / `3d` / `2mo` / `1y`）、绝对日期（`2026-07-01`）。

**Q: 想读搜索结果的网页全文呢？**

A: 让 agent "打开第一个链接看看内容" 即可。`web_fetch` 工具已启用（官方 `dsh-web-fetch-http` provider），自动跟随重定向并把 HTML 转纯文本。注意它无 SSRF 防护，agent 理论上可访问内网地址，请按需使用。

**Q: 国内用需要配代理吗？**

A: DuckDuckGo 等引擎在国内访问可能受限。Node 24+ 上需给 dsh 进程设置 `NODE_USE_ENV_PROXY=1`、`HTTPS_PROXY`、`HTTP_PROXY` 三个环境变量，否则 Node `fetch` 不走系统代理。

**Q: 怎么卸载？**

A: 在 DSH profile 的插件列表里移除本插件条目，重启 `dsh web` 即可。配置写在 `~/.dsh/settings.yaml` 的 `free-search` 命名空间，需要时可手动清理。

**Q: 和 DSH 自带的 web_search 是什么关系？**

A: 本插件实现了官方 `WebSearchProvider` 接口，并通过 `cordis.patch.yml` 把宿主 `web.searchProvider` 字段重定向到本插件的 provider（id=ddg）。因此 DSH 自带的 `web_search` 工具会自动调用本插件的多引擎+回退逻辑，两者不冲突。

## 上手难度
入门 — 默认 Bing 安装即可用，付费引擎也都有 keyless 兜底；想深度定制只需在网页设置页下拉切换引擎、按需填 key。

## 已知问题与限制
- DuckDuckGo（html / lite）偶发被反爬限流（"anti-bot challenge"），通常临时性，自动恢复；首次失败会被回退链跳过，结果里会注明
- Bing / AnySearch 不支持时间过滤参数（无对应查询字段），带 `timeRange` 时会被跳过并改用支持过滤的引擎
- Tavily / SearXNG / DDG 的时间过滤只支持固定档（day/week/month/year），自定义相对值（如 `3d`）会被近似映射到最近档位
- 付费引擎（Perplexity、DeepSeek 官方）未配置 key 时会被回退链跳过，不会"假装搜索"
- `web_fetch` 工具无 SSRF 防护，agent 理论上可读取内网地址
- 检查更新会请求 npm registry `https://registry.npmjs.org/dsh-free-search/latest`，国内环境若网络受限则获取不到版本号

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-free-search](https://deepseek-plugin.org/plugins/DDDMUC/dsh-free-search)
Wiki generated by AI (model: `MiniMax-M3`)