# dsh-web-search-chain

给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的
`web_search` 工具换一条**可自定义顺序的搜索链路**：默认 **Tavily 优先，
DeepSeek Search API 兜底**。

它通过 `ctx.web` 注册两个搜索提供方：

| provider id | 行为 |
|---|---|
| `tavily` | 只用 Tavily（失败直接报错，不降级） |
| `tavily-first` | 按 `order` 顺序逐个尝试，第一个返回结果的赢；默认 `tavily -> deepseek` |

`tavily-first` 的内部链路：

1. `tavily`：`POST <baseURL>/search`，Bearer 认证；
2. `deepseek`：`POST <baseURL>/search`（默认 `https://api.deepseek.com/v1/tools`），Bearer 认证；
3. 任意第三方 id：直接调用 `ctx.web.searchProviders` 里已注册的提供方，例如
   `deepseek-official`（`dsh-web-search-deepseek`，Messages 搜索）或
   `deepseek-search-api`（`dsh-web-deepseek-api`）。

失败、超时、HTTP 非 2xx、空结果（可用 `fallbackOnEmpty: false` 关闭）都会触发下一个。

模型可见的 `web_search` / `web_fetch` 工具、系统提示词、结果格式都不变，
这里只替换 `ctx.web` 的搜索后端。

## 安装

### 插件管理器 / CLI

```bash
dsh plugin --profile <profile> add dsh-web-search-chain
```

也可以在 dsh 的 **设置 → 插件** 里按包名安装。安装后包自带的
`cordis.patch.yml` 会把 `web.searchProvider` 指到 `tavily-first`。

### 手动挂载

已经在本机插件目录里时，也可以直接写进 profile 的 `cordis.patch.yml`：

```yaml
- id: web
  config:
    searchProvider: tavily-first
    fetchProvider: http

- insert:
    - id: web-search-chain
      name: file:///C:/path/to/dsh-web-search-chain/index.mjs
      config:
        order: [tavily, deepseek]
```

## 密钥

密钥放在 `$DSH_HOME/.credentials.yaml` 的 `refs` 下（不要写进 YAML 配置）：

```yaml
refs:
  DSH_WEB_SEARCH_TAVILY_API_KEY: th-...
  DSH_WEB_SEARCH_DEEPSEEK_API_KEY: sk-...
```

插件按 `apiKey 字面值 -> credentials 引用 -> 进程环境变量` 的顺序解析。
dsh 的「网页搜索」设置页写入的也是 `DSH_WEB_SEARCH_DEEPSEEK_API_KEY`，
和本插件的兜底用同一把密钥。

## 默认配置

| 字段 | 默认值 | 说明 |
|---|---|---|
| `id` | `tavily-first` | 链路提供方 id；`tavily` 保留给单 Tavily 提供方 |
| `order` | `[tavily, deepseek]` | 尝试顺序；可混入已注册提供方 id |
| `fallbackOnEmpty` | `true` | 返回 0 条结果时是否继续下一个 |
| `snippetMaxChars` | `800` | 单条来源 snippet 的字符上限 |
| `tavily.baseURL` | `https://tavily.fuhuagoogle.top/api/tavily` | 不含 `/search` 的基地址 |
| `tavily.apiKey` / `apiKeyEnv` | 无 / `DSH_WEB_SEARCH_TAVILY_API_KEY` | 字面密钥优先于引用 |
| `tavily.searchDepth` | `basic` | `basic` 或 `advanced` |
| `tavily.includeAnswer` | `false` | Tavily 的 `answer` 作为提供方答案返回 |
| `tavily.maxResults` | `8` | 1–20 |
| `tavily.timeoutMs` | `25000` | 单次请求超时 |
| `deepseek.baseURL` | `https://api.deepseek.com/v1/tools` | 不含 `/search` 的基地址 |
| `deepseek.apiKey` / `apiKeyEnv` | 无 / `DSH_WEB_SEARCH_DEEPSEEK_API_KEY` | 同上 |
| `deepseek.count` | `10` | 1–50；请求里更小的 `maxResults` 优先 |
| `deepseek.timeoutMs` | `25000` | 单次请求超时 |

默认 Tavily 基地址指向作者维护的中转；使用官方 Tavily 时把它改成
`https://api.tavily.com` 即可。

## 常见改法

**Tavily 优先，失败走 Messages 搜索**（不依赖 Search API）：

```yaml
order: [tavily, deepseek-official]
```

**只用 DeepSeek**：把 `web.searchProvider` 改成 `deepseek-search-api`（或
`deepseek-official`），或把 `order` 设成 `[deepseek]`。

**Tavily 单用**：把 `web.searchProvider` 改成 `tavily`。

**Tavily 为主、DeepSeek 只在空结果时补**：`fallbackOnEmpty: true` 是默认行为。

## 注意

- **不要动「设置 → 插件 → 内置插件配置 → 网页搜索」里的开关**：那个页面只会写
  `deepseek-search-api` / `deepseek-official`，保存后会把 `searchProvider`
  从 `tavily-first` 改掉，本插件的链路就不会被调用。要切回 Tavily 优先，把
  profile 里 `web.searchProvider` 改回 `tavily-first` 即可。该页面的 API key
  字段仍然可用，写入的是 `DSH_WEB_SEARCH_DEEPSEEK_API_KEY`。
- 搜索链在 `ctx.web.search()` 里同步执行，受工具自己的协作超时
  （`dsh-tool-web` 默认 60s）约束。
- 修改插件配置或 `cordis.patch.yml` 后，dsh 的 HMR 会重载 profile 配置；
  改 `index.mjs` 源码不会热重载，需要重启应用。
- 插件只 import `node:process`，不依赖 asar 里的包，因此从 `file:///` 或
  `node_modules` 加载都可以。
- `tavily` 提供方 id 是固定注册的；如果又安装了别的 Tavily 插件（同样注册
  `tavily`），删掉其中一个以免 `WEB_DUPLICATE_PROVIDER`。

## License

MIT
