dshsearch-multi

Readme

# dshsearch-multi

> 面向 DeepSeek Harness（DSH）的多引擎网页搜索与网页抓取插件。

`dshsearch-multi` 将多个搜索服务统一成一个 DSH 搜索提供商，并提供网页正文抓取能力。它不修改 DSH 内部源码，只通过公开的 Provider 接口注册功能，因此可以独立安装和升级。

## 功能概览

- 一个搜索提供商，统一支持 AnySearch、Bing、DuckDuckGo、Tavily 和 Exa。
- 搜索失败或没有结果时，按顺序自动切换到其他可用引擎。
- AnySearch 无需配置 API Key，安装后即可使用；Tavily 和 Exa 仅在配置 API Key 后启用。
- 内置确定性的查询意图识别，不调用 LLM，也不会偷偷改写 `web_search` 的调用契约。
- 提供 `web.fetch(url)` 网页正文抓取，并按多个来源自动兜底。
- DSH Web 设置页提供中文/英文设置卡片，支持基础参数和高级参数。
- 附带命令行配置工具，适合无界面或脚本化场景。

## 支持的搜索引擎

| 标识 | 引擎 | 密钥 | 说明 |
| --- | --- | --- | --- |
| `anysearch` | AnySearch | 不需要 | 默认引擎，安装后即可匿名使用 |
| `bing` | Bing HTML 搜索 | 不需要 | 公共网页接口，可能受到限流或页面变更影响 |
| `duckduckgo` | DuckDuckGo HTML 搜索 | 不需要 | 公共网页接口，可能受到限流或页面变更影响 |
| `tavily` | Tavily Search API | `TAVILY_API_KEY` | 支持完整搜索参数 |
| `exa` | Exa Search API | `EXA_API_KEY` | 支持完整搜索参数 |

默认兜底顺序为：当前选中的引擎，然后是其余引擎。没有配置密钥的 Tavily/Exa 会自动跳过。

## 安装

发布到 npm 后，在 DSH 的目标 profile 中安装：

```powershell
dsh plugin --profile web add dshsearch-multi
```

也可以从 Git 仓库、本地目录或压缩包安装：

```powershell
dsh plugin --profile web add github:<user>/dshsearch-multi
dsh plugin --profile web add https://github.com/<user>/dshsearch-multi.git
dsh plugin --profile web add C:\path\to\dshsearch-multi
dsh plugin --profile web add dshsearch-multi-1.0.2.tgz
```

安装后，插件会将 DSH 的：

- `web.searchProvider` 设置为 `dshsearch-multi`
- `web.fetchProvider` 设置为 `dshsearch-multi-fetch`

设置入口兼容 DSH 新旧 Host：新版本使用 `dshsearch-multi` namespace，并按 keyed slot 契约注册卡片；旧版本若只暴露 `web-search-multi`，插件会自动使用兼容 namespace。升级后建议打开“设置 → 插件 → 插件配置”确认“网页搜索”卡片可见，并刷新页面验证配置仍然存在。

快速试用：

```powershell
dsh plugin --profile test add <上面的任意来源>
dsh --profile test --port 4000
```

然后打开 `http://127.0.0.1:4000`，进入“设置 → 插件”。

## 配置

### 在 DSH Web 中配置

打开“设置 → 插件 → 插件配置”，找到 **网页搜索** 卡片即可配置：

- 优先搜索引擎
- 最大结果数
- Tavily/Exa 的 API Key 和接口地址
- 查询意图模式
- Tavily 和 Exa 的高级检索参数

API Key 会通过 DSH 凭据服务保存，不会回传到浏览器。

### 使用 settings.yaml

配置文件位于：`%USERPROFILE%\.dsh\settings.yaml`。配置节点为插件自己的 `dshsearch-multi`：

```yaml
dshsearch-multi:
  provider: anysearch        # anysearch | bing | duckduckgo | tavily | exa
  intentMode: auto           # auto | manual
  maxResults: 5
  anysearchBaseURL: https://api.anysearch.com/mcp
  tavilyBaseURL: https://api.tavily.com
  exaBaseURL: https://api.exa.ai

  tavilySearchDepth: basic   # basic | advanced
  tavilyTopic: general       # general | news | finance
  tavilyDays: 0
  tavilyIncludeAnswer: false
  tavilyIncludeImages: false
  tavilyIncludeRawContent: false
  tavilyIncludeDomains: []
  tavilyExcludeDomains: []

  exaType: auto              # auto | neural | keyword
  exaCategory: ""
  exaStartPublishedDate: ""
  exaEndPublishedDate: ""
  exaIncludeDomains: []
  exaExcludeDomains: []
  exaUseAutoprompt: false
  exaMaxTextCharacters: 1000 # 0 表示不提取正文
```

### 配置 API Key

推荐在 DSH Web 设置卡片中填写，也可以写入 `%USERPROFILE%\.dsh\.credentials.yaml`：

```yaml
TAVILY_API_KEY: tlv-...
EXA_API_KEY: ...
```

不要将密钥提交到 Git 仓库。AnySearch 没有配置入口，也不需要配置密钥。

## 查询意图模式

`intentMode` 默认为 `auto`。插件使用正则和关键词进行确定性分类，不依赖 LLM：

- `finance`：股票代码、股价、财报、估值等财经查询。
- `news`：新闻、最新消息、发布、报道等查询。
- `academic`：论文、期刊、研究、预印本等学术查询。
- `code`：GitHub、仓库、源码、npm 等代码查询。
- `weather`：天气、气温、降水、台风等气象查询。
- `video`：视频、电影、影视、直播等视频查询。
- `shopping`：购物、优惠、折扣、价格等购物查询。
- `sports`：比分、比赛、足球、篮球等体育查询。
- `travel`：旅游、酒店、机票、攻略等旅行查询。
- `long-natural-language`：较长的问题或对比型问题，会提高 Tavily 检索深度。
- `general`：其他查询，完全使用当前配置。

自动模式会在配置值上应用上述分类提示。例如财经查询会将 Tavily 主题设为 `finance`，代码/天气/视频/购物/体育/旅行查询会将 Exa 类别分别设为 `github`/`weather forecast`/`video`/`product`/`sports`/`travel`。

如果需要严格使用手动配置，可设置：

```yaml
dshsearch-multi:
  intentMode: manual
```

AnySearch 的能力目录会在当前 DSH 进程中按地址和领域缓存，每个领域只发现一次。

## 网页抓取

`web.fetch(url)` 使用以下顺序获取网页正文，第一个成功的来源优先：

1. AnySearch `extract`，无需配置密钥。
2. Tavily `/extract`，需要 `TAVILY_API_KEY`。
3. Exa `/contents`，需要 `EXA_API_KEY`。
4. 直接请求网页并将 HTML 转换为文本。

直接抓取会跟随重定向、移除脚本和样式，并保留链接地址；正文最多返回 50,000 个字符。PDF、图片、音视频和压缩包等二进制内容会返回 `WEB_UNSUPPORTED_CONTENT_TYPE`。

## 命令行工具

插件附带 `dshsearch-multi` 命令，用于管理独立的本地配置文件：

```powershell
dshsearch-multi config show
dshsearch-multi config set provider anysearch
dshsearch-multi config set maxResults 5
dshsearch-multi config set tavily.apiKey YOUR_TAVILY_API_KEY
dshsearch-multi config set exa.baseURL https://api.exa.ai
dshsearch-multi config path
dshsearch-multi config reset
```

配置文件默认位于 `%USERPROFILE%\.dsh\dshsearch-multi.json`，文件权限会尽量限制为仅所有者可读写。`config show` 不会打印密钥内容。

注意：CLI 配置文件是独立的便捷配置。正在运行的 `dsh web` 读取的是 DSH 的 `dshsearch-multi` 设置节点，而不是这个 JSON 文件。插件会同时注册 `dshsearch-multi` 和旧版兼容的 `web-search-multi` namespace，并优先使用前者；如果当前 Host 只暴露旧 namespace，浏览器端设置卡片会自动回退到旧 namespace。若两个 namespace 都未暴露，设置卡片仍无法通过远程设置 API 读写，此时需要升级 DSH Host 或由宿主提供第三方 settings 暴露能力。

## 安装后排障

如果“设置 → 插件 → 插件配置”中没有“网页搜索”卡片：

1. 确认插件安装在当前正在运行的 profile，而不是其他 profile。
2. 重启 DSH Web 或刷新页面，让客户端重新加载插件 bundle。
3. 新版 Host 应暴露 `dshsearch-multi`；旧版 Host 只暴露 `web-search-multi` 时，插件会自动使用兼容 namespace。
4. 如果两个 namespace 都不可见，请升级 DSH Host。插件自身不能修改 Host 的 settings 暴露策略。

如果搜索可用但设置卡片不可见，可先在 `%USERPROFILE%\\.dsh\\settings.yaml` 中配置 `dshsearch-multi`，或使用测试 profile 验证安装：

```powershell
dsh plugin --profile test add dshsearch-multi
dsh --profile test --port 4000
```

## 开发与发布

项目使用 Node.js ESM。安装依赖后执行：

```powershell
pnpm install
pnpm run check
pnpm run pack:check
node test/test-intent-engine.mjs
node test/test-fetch-provider.mjs
```

`test-intent-engine.mjs` 默认只运行离线测试；需要真实 AnySearch 域目录探测时，显式设置 `$env:DSH_LIVE_TESTS = "1"`。Tavily 和 Exa 的真实 API 测试仅在对应凭据已配置时运行。

其中：

- `check` 检查 JSON、YAML、服务端入口、CLI 和浏览器端入口的基本语法。
- `pack:check` 使用 npm 的发布文件白名单生成压缩包，并检查包内容。

修改后建议先在测试 profile 中安装本地目录或 `.tgz`，确认 DSH Web 设置卡片和搜索/抓取链路正常，再发布到 npm。发布前建议执行 `npm pack --dry-run`，确认压缩包只包含发布白名单中的运行文件。普通第三方插件能注册自己的 settings namespace，但当前 DSH Host 是否向浏览器暴露该 namespace 由 Host 的显式策略决定；插件不能通过自身代码把 namespace 加入 Host 白名单。

## 限制

- Bing 和 DuckDuckGo 使用公共 HTML 页面，不是稳定的官方 API，可能被限流、触发验证或改变页面结构。
- AnySearch 的 `extract` 和直接抓取均有正文长度上限，且不支持 PDF 等二进制内容。
- Tavily 和 Exa 的实时接口验证需要对应 API Key；未配置时相关测试会跳过。
- DSH 当前版本的设置页对白名单外的第三方 namespace 不提供远程读写；若要在设置页显示本插件，需要 Host 版本提供第三方设置暴露机制，或由宿主显式加入 `dshsearch-multi`。

## 许可证

[MIT](LICENSE)