dsh-web-search-plugin 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本项目的重要变更都记录在此。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.3.0] - 2026-08-25
+
+### 新增
+
+- **内置 REST provider 元数据化**（`lib/providers.js` 静态表 + `lib/rest.js` 通用后端）：内置 REST 供应商由单一元数据表驱动，新增即"表里加一行 + 官方跳转链接"，零定制执行代码。
+  - 新增内置 provider：**Serper / SerpApi / Exa / SearXNG / Scavio / Firecrawl**（`provider` 值 `serper` / `serpapi` / `exa` / `searxng` / `scavio` / `firecrawl`）。
+  - Firecrawl 响应 `data.web[]` 走专用 `firecrawl` 解析分支；Scavio 复用 `organic_results` 解析。
+  - DuckDuckGo 无官方 API：下拉以禁用项提示经 SearXNG 使用，不提供独立后端。
+  - 元数据字段：`method`（GET/POST）/ `queryIn`（query-string / body）/ `queryParam` / `countParam` / `params[]`（`when: always` / `nonEmpty` / `keyed` / `keyless`，受限谓词清单）/ `auth.type`（bearer / header / none / **query**）/ `response` / `hooks` / `officialUrl`。
+  - 通用后端 `RestSearchProvider` 接管 brave / tavily / serper / serpapi / exa / searxng / scavio / firecrawl；`deepseek-official`（模型工具型）仍走专用 `lib/deepseek.js`。
+  - Tavily 额度回传、Brave 限流头/代理作为可选 hook 注入，通用体不写死业务逻辑。
+  - 设置卡对需要 key 的内置 provider 渲染「获取 API key ↗」跳官方控制台；免 key 的（SearXNG / Tavily keyless）不渲染。
+
+### 变更
+
+- **默认引擎从 `tavily` 改为 `deepseek-official`**：schema 默认、服务端/客户端回退、bundle patch 初始值一致改为官方默认（已保存的显式 `provider` 不被覆盖）。
+- `provider` 取值扩展为 `tavily` / `brave` / `deepseek-official` / `serper` / `serpapi` / `exa` / `searxng` / `scavio` / `firecrawl`。
+- **修复 Tavily `include_answer` 类型错误**：`params[]` 布尔值不再强转字符串，请求体发真布尔（`true`/`false`），兼容 Tavily API 对 `include_answer` / `include_images` / `include_usage` 的类型要求。
+- **修复 SearXNG 卡片误显「获取 API key ↗」**：仅需要 key 的 provider 才显示获取 key 跳转，免 key 的（SearXNG / Tavily keyless）不显示。
+- **收紧未配置 key 的提示文案**：placeholder 缩短为「未配置密钥」，补充说明移至输入框下方提示，避免溢出。以下未纳入内置：TinyFish、Google CSE、SERPJET（官网不可访问）、DuckDuckGo（无官方 API，经 SearXNG 使用）。
+
 ## [0.2.1] - 2026-08-18
 
 相对 0.2.0 的补丁：设置卡补上额度进度条、两列布局和输入校验，并收紧空态文案。

package/README.md

@@ -1,18 +1,28 @@
 # dsh-web-search-plugin
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web 能力接缝（`ctx.web`）的统一网页搜索插件，内置 **DeepSeek（官方）/ Tavily / [Brave Search](https://brave.com/search/api/) 三个后端**。本包只向接缝注册 **一个** `WebSearchProvider`，稳定 id 为 `dsh-web-search`。在 **设置 → 网页搜索** 里切换引擎即可，不必再改 `web.searchProvider`。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web 能力接缝（`ctx.web`）的统一网页搜索插件，内置 **DeepSeek（官方，默认）/ Tavily / [Brave Search](https://brave.com/search/api/) / Serper / SerpApi / Exa / SearXNG / Scavio / Firecrawl 九个后端**。本包只向接缝注册 **一个** `WebSearchProvider`，稳定 id 为 `dsh-web-search`。在 **设置 → 网页搜索** 里切换引擎即可，不必再改 `web.searchProvider`。
 
-- **DeepSeek（官方）** — 走 DeepSeek 的 Anthropic 兼容 Messages API（原生 `web_search_20250305` 工具，凭据名 `DEEPSEEK_API_KEY`），一次搜索消耗一个模型轮次。
-- **Tavily（默认）** — `keyless`（免费、限流、无需账号）或 `keyed`（`TAVILY_API_KEY`，Bearer token）。keyed 会在设置卡显示额度进度条。
+- **DeepSeek（官方，默认）** — 走 DeepSeek 的 Anthropic 兼容 Messages API（原生 `web_search_20250305` 工具，凭据名 `DEEPSEEK_API_KEY`），一次搜索消耗一个模型轮次。
+- **Tavily** — `keyless`（免费、限流、无需账号）或 `keyed`（`TAVILY_API_KEY`，Bearer token）。keyed 会在设置卡显示额度进度条。
 - **Brave Search** — `GET https://api.search.brave.com/res/v1/web/search`，请求头 `X-Subscription-Token`（凭据名 `BRAVE_API_KEY`）。一次搜索就是一次 HTTP 请求，不走模型轮次；设置卡按响应头展示 Capacity / 月配额。
+- **Serper** — Google 结果（`POST /search`，头 `X-API-KEY`，凭据名 `SERPER_API_KEY`）。
+- **SerpApi** — `GET /search.json`，key 走 query（`api_key=`），凭据名 `SERPAPI_API_KEY`。
+- **Exa** — 语义/神经搜索（`POST /search`，Bearer，凭据名 `EXA_API_KEY`）。
+- **SearXNG** — 自建/协议免 key 的元搜索（`GET /search?format=json`），可填自托管实例地址。
+- **Scavio** — Google SERP（`POST /api/v2/google`，Bearer，凭据名 `SCAVIO_API_KEY`），响应与 SerpApi 同构。
+- **Firecrawl** — 搜索+抓取（`POST /v2/search`，Bearer，凭据名 `FIRECRAWL_API_KEY`），`sources: ["web"]`。
+- **DuckDuckGo** — 无官方搜索 API，不提供独立后端；下拉中以禁用项提示：选 SearXNG 并指向聚合了 DuckDuckGo 的实例即可。
+- **官方 key 跳转** — 需要 key 的内置 provider 在设置卡带「获取 API key ↗」一键跳官方控制台；免 key 的（SearXNG / Tavily keyless）不渲染。
 - **不写自定义 session 事件** — 工具结果已经走接缝自己的事件，无需多余信封。
 
 ## 特性
 
 - 与官方 `@deepseek-ai/dsh-web-search-deepseek` 相同的提供方约定：`inject: ['web']` + `installSettingsSection` + `ctx.web.registerSearchProvider`。
 - 顶层 **设置 → 网页搜索** 分区：两列布局、未保存草稿、保存 toast；结果数量为 1–20 下拉。
+- **默认引擎为 DeepSeek（官方）**：新装 / 未显式改动时，搜索直接走 `deepseek-official`，不再依赖 keyless 的 Tavily。
+- 纯 REST 后端由**静态元数据表 + 通用后端**驱动，新增 provider 即"表里加一行 + 官方跳转链接"，无定制执行代码。
 - Tavily keyless 无需密钥即可用；Brave 需要订阅 token（若本机已有 `BRAVE_API_KEY` 凭据，可直接复用）。
-- Tavily keyed / Brave 在设置卡展示额度进度条（DeepSeek 官方与 Tavily keyless 不展示）。
+- Tavily keyed / Brave 在设置卡展示额度进度条（DeepSeek 官方与 Tavily keyless / 其余 REST 后端不展示）。
 - 各引擎结果都规范化为接缝的 `WebSearchResult`（可选 `content` + `sources[]`），按 URL 去重。
 - 设置段 `dsh-web-search-plugin` 通过 rc.7 的 `settings.describe()` 动态暴露，不需要宿主白名单补丁，也不需要自建回环 settings 桥。
 - 错误映射为 `WEB_PROVIDER_ERROR` / `WEB_ABORTED` / `WEB_PROVIDER_CREDENTIAL_MISSING`。
@@ -32,56 +42,7 @@
 dsh plugin --profile web add dsh-web-search-plugin
 ```
 
-### 从本地目录安装
-
-同盘可以用相对路径：
-
-```powershell
-dsh plugin --profile web add ".\dsh-web-search-plugin"
-```
-
-**Windows 跨盘不要 `dsh plugin add` 绝对路径。** Profile 在 `C:`、仓库在 `D:` 时，它会写成 `link:d:/...`；pnpm 把盘符当成相对路径，junction 会指到 `profiles\web\D:\...` 并链坏。也不要写 `file:D:/...`：pnpm 10 同样会把跨盘绝对路径拼进 profile 目录。
-
-正确做法是快照到与 profile **同盘**，再用 `file:`：
-
-```powershell
-$dst = "$env:USERPROFILE\.dsh\profiles\web\.local\dsh-web-search-plugin"
-New-Item -ItemType Directory -Force -Path $dst | Out-Null
-robocopy "D:\gddi\dsh-web-search-plugin" $dst /E /XD node_modules .git .github /NFL /NDL /NJH /NJS
-```
-
-在 profile 的 `package.json` 里：
-
-```json
-"dsh-web-search-plugin": "file:.local/dsh-web-search-plugin"
-```
-
-并保证 `dsh.profile.bundles` 含本包，然后：
-
-```powershell
-dsh plugin --profile web install
-```
-
-`file:` 是快照：改完仓库后要再 robocopy + `install` 并重启 DSH。
-
-用 `dsh --profile web --dump-config` 确认：组成树里应有 `dsh-web-search-plugin` 行，且 `web.searchProvider` 为 `dsh-web-search`。
-
-若 profile 已经覆盖了 `web`（例如旧包 `@dsh-ltctfer/dsh-web-search-brave` 留下的 `brave-official`），后打的 patch 仍会生效。请改指向本插件，并卸掉旧包：
-
-```yaml
-- id: web
-  name: '@deepseek-ai/dsh-web'
-  config:
-    searchProvider: dsh-web-search
-```
-
-```powershell
-dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
-```
-
-然后在 **设置 → 网页搜索** 里把引擎切到想要的提供方，即可继续使用对应的 API key。
-
-> **关于 `file:`（本地）安装** — pnpm 会把 `file:` 依赖做成快照。改完本仓库后，需要再同步快照并 `dsh plugin --profile web install`，然后重启。Windows 上 profile 与仓库不在同一盘时，用同盘 `file:.local/...`，不要 `link:` / `file:` 指向另一块盘。
+> 从源码仓库本地安装（含 Windows 跨盘注意事项）见 [开发 → 本地安装与验证](#本地安装与验证)。
 
 ## 配置
 
@@ -89,12 +50,12 @@ dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
 
 | 键 | 默认值 | 含义 |
 |---|---|---|
-| `provider` | `tavily` | `tavily`、`brave` 或 `deepseek-official` |
+| `provider` | `deepseek-official` | `tavily`、`brave`、`deepseek-official`、`serper`、`serpapi`、`exa`、`searxng`、`scavio` 或 `firecrawl` |
 | `mode` | `keyless` | 仅 Tavily：`keyless` 或 `keyed` |
 | `apiKey` | — | Tavily API key 字面量（走凭据域，不会回显） |
 | `apiKeyEnv` | `TAVILY_API_KEY` | keyed Tavily 使用的凭据/环境变量名 |
 | `baseURL` | `https://api.tavily.com` | Tavily REST 基址；会再拼 `/search` |
-| `maxResults` | `8` | 每次搜索返回的源数量，三个后端共用。设置卡为 1–20 下拉，超出上限会夹到 20 |
+| `maxResults` | `8` | 每次搜索返回的源数量，各后端共用。设置卡为 1–20 下拉，超出上限会夹到 20 |
 | `searchDepth` | `basic` | 仅 Tavily：`basic` 或 `advanced` |
 | `includeAnswer` | `true` | 仅 Tavily：请求生成摘要，写入结果 `content` |
 | `topic` | `general` | 仅 Tavily：`general` 或 `news` |
@@ -112,6 +73,23 @@ dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
 | `searchLang` | — | Brave 的 `search_lang`（如 `zh-hans`）；留空使用 Brave 默认 |
 | `freshness` | — | Brave 的 `freshness`：`pd` / `pw` / `pm` / `py` |
 | `proxy` | — | Brave 使用的 HTTP(S) 代理；留空回退 `HTTPS_PROXY` / `HTTP_PROXY` |
+| `serperApiKey` / `serperApiKeyEnv` / `serperBaseURL` | — / `SERPER_API_KEY` / — | Serper 的 key 字面量 / 凭据引用名 / 端点覆盖 |
+| `serpapiApiKey` / `serpapiApiKeyEnv` / `serpapiBaseURL` | — / `SERPAPI_API_KEY` / — | SerpApi 的 key 字面量 / 凭据引用名 / 端点覆盖 |
+| `exaApiKey` / `exaApiKeyEnv` / `exaBaseURL` | — / `EXA_API_KEY` / — | Exa 的 key 字面量 / 凭据引用名 / 端点覆盖 |
+| `searxngBaseURL` | — | SearXNG 自托管实例基址；留空用 `https://searx.be` |
+| `scavioApiKey` / `scavioApiKeyEnv` / `scavioBaseURL` | — / `SCAVIO_API_KEY` / — | Scavio 的 key 字面量 / 凭据引用名 / 端点覆盖 |
+| `firecrawlApiKey` / `firecrawlApiKeyEnv` / `firecrawlBaseURL` | — / `FIRECRAWL_API_KEY` / — | Firecrawl 的 key 字面量 / 凭据引用名 / 端点覆盖 |
+
+## 未纳入的服务
+
+以下服务**不内置**（在引擎下拉中不会出现，也不提供后端）：
+
+| 服务 | 不做的原因 |
+|---|---|
+| **TinyFish** | 免费额度极小（每分钟 5 次）；其 Search + Fetch 形态超出"纯 REST 搜索"边界，仅搜索部分价值低 |
+| **Google CSE** | 官方已对新用户关闭注册，并将于 2027-01-01 停用 |
+| **SERPJET** | 官网当前不可访问，暂不接入 |
+| **DuckDuckGo** | 无官方搜索 API（HTML/社区库抓取不符合元数据表"纯 REST"边界）。下拉中有禁用提示，指引经 SearXNG 使用 |
 
 环境变量：启动时 `DSH_WEB_SEARCH_PROVIDER=dsh-web-search` 会选中本接缝 id。未设置 `baseURL` 时，Tavily 基址回退 `$TAVILY_BASE_URL`。
 
@@ -129,25 +107,84 @@ DeepSeek 已并入本插件（`provider: deepseek-official`），无需切回。
 ## 工作方式
 
 - **DeepSeek** — `POST {deepseekBaseURL}/messages`，请求头 `x-api-key` / `authorization: Bearer`，工具 `web_search_20250305`。
-- **Tavily** — `POST {baseURL}/search`。keyless 发送 `x-tavily-access-mode: keyless`；keyed 发送 `authorization: Bearer <key>`。
-- **Brave** — `GET {braveBaseURL}?q=&count=`，请求头 `x-subscription-token`。不向 session 追加自定义事件。
+- **纯 REST 类（Tavily / Brave / Serper / SerpApi / Exa / SearXNG）** — 由静态元数据表（`lib/providers.js`）+ 通用后端（`lib/rest.js`）驱动，无独立定制代码。请求方法 / 路径 / 查询字段名 / 鉴权（bearer / header / none / query）/ 固定参数 / 响应形态全部由表里的行决定。
+  - **Tavily** — `POST {baseURL}/search`。keyless 发送 `x-tavily-access-mode: keyless`；keyed 发送 `authorization: Bearer <key>`，并带 `include_usage` 回传 credits。
+  - **Brave** — `GET {braveBaseURL}?q=&count=`，请求头 `x-subscription-token`。不向 session 追加自定义事件。
+  - **Serper / SerpApi / Exa / SearXNG** — 按各自表的 `method` / `auth` / `params` 约定请求。
 - 非 2xx 映射为 `WEB_PROVIDER_ERROR`；调用方取消映射为 `WEB_ABORTED`。
 
 ## 仓库布局
 
 ```
-lib/index.js       Host 插件：Config、分发提供方、设置段、额度路由
-lib/deepseek.js    DeepSeek 后端（Anthropic Messages + web_search_20250305）
-lib/tavily.js      Tavily 后端（keyed 时带 include_usage）
-lib/brave.js       Brave 后端（解析 X-RateLimit-*，不写自定义 session 事件）
+lib/index.js       Host 插件：Config、按元数据分发提供方、设置段、额度路由
+lib/providers.js   静态元数据表：内置 REST provider 的请求/鉴权/响应/官方跳转（纯数据，无定制代码）
+lib/rest.js        通用 REST 后端：按元数据驱动请求构造与响应规范化（可选 hooks）
+lib/deepseek.js    DeepSeek 后端（Anthropic Messages + web_search_20250305，模型工具型专用）
+lib/tavily.js      Tavily 选项解析 / 响应映射（额度由 Tavily hook 回传）
+lib/brave.js       Brave 选项解析 / 响应映射（解析 X-RateLimit-*）
 lib/usage.js       Tavily/Brave 用量本地缓存与 /usage 对账
 lib/shared.js      中止 / 凭据解析辅助
-lib/client.js      浏览器 bundle：顶层「网页搜索」分区 + 引擎切换 + 额度条
+lib/client.js      浏览器 bundle：顶层「网页搜索」分区 + 引擎切换 + 官方 key 跳转 + 额度条
 cordis.patch.yml   Bundle patch：插入 Host 行、设 searchProvider、禁用内置 deepseek
 ```
 
 ## 开发
 
+### 本地安装与验证
+
+改源码后本机验证，把仓库装进某个 profile（以 `web` 为例）。**同盘**可以直接用相对路径：
+
+```powershell
+dsh plugin --profile web add ".\dsh-web-search-plugin"
+```
+
+**Windows 跨盘不要 `dsh plugin add` 绝对路径。** Profile 在 `C:`、仓库在 `D:` 时，它会写成 `link:d:/...`；pnpm 把盘符当成相对路径，junction 会指到 `profiles\web\D:\...` 并链坏。也不要写 `file:D:/...`：pnpm 10 同样会把跨盘绝对路径拼进 profile 目录。
+
+正确做法是快照到与 profile **同盘**，再用 `file:`：
+
+```powershell
+$dst = "$env:USERPROFILE\.dsh\profiles\web\.local\dsh-web-search-plugin"
+New-Item -ItemType Directory -Force -Path $dst | Out-Null
+robocopy "D:\sample\dsh-web-search-plugin" $dst /E /XD node_modules .git .github /NFL /NDL /NJH /NJS
+```
+
+在 profile 的 `package.json` 里：
+
+```json
+"dsh-web-search-plugin": "file:.local/dsh-web-search-plugin"
+```
+
+并保证 `dsh.profile.bundles` 含本包，然后：
+
+```powershell
+dsh plugin --profile web install
+```
+
+`file:` 是快照：改完仓库后要再 robocopy + `install` 并重启 DSH。
+
+用 `dsh --profile web --dump-config` 确认：组成树里应有 `dsh-web-search-plugin` 行，且 `web.searchProvider` 为 `dsh-web-search`。
+
+> **关于 `file:`（本地）安装** — pnpm 会把 `file:` 依赖做成快照。改完本仓库后，需要再同步快照并 `dsh plugin --profile web install`，然后重启。Windows 上 profile 与仓库不在同一盘时，用同盘 `file:.local/...`，不要 `link:` / `file:` 指向另一块盘。
+
+### 迁移旧后端包
+
+若 profile 已经覆盖了 `web`（例如旧包 `@dsh-ltctfer/dsh-web-search-brave` 留下的 `brave-official`），后打的 patch 仍会生效。请改指向本插件，并卸掉旧包：
+
+```yaml
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: dsh-web-search
+```
+
+```powershell
+dsh plugin --profile web remove @dsh-ltctfer/dsh-web-search-brave
+```
+
+然后在 **设置 → 网页搜索** 里把引擎切到想要的提供方，即可继续使用对应的 API key。
+
+### 语法检查
+
 ```powershell
 npm run check
 ```
@@ -156,15 +193,15 @@ npm run check
 
 ## 发布
 
-发布由 GitHub Actions（`.github/workflows/publish.yml`）自动完成：**推送 `v*` 标签**（例如 `v0.2.1`）会带 provenance 发到 npm。向 `main` 的普通推送不会发布。
+发布由 GitHub Actions（`.github/workflows/publish.yml`）自动完成：**推送 `v*` 标签**（例如 `v0.3.0`）会带 provenance 发到 npm。向 `main` 的普通推送不会发布。
 
-1. 确认 `package.json` 的 `version` 与即将推送的标签一致（例如 `0.2.1` → `v0.2.1`）。
+1. 确认 `package.json` 的 `version` 与即将推送的标签一致（例如 `0.3.0` → `v0.3.0`）。
 2. 在 GitHub **Settings → Secrets and variables → Actions** 里配置有 publish 权限的 npm automation token（仓库密钥 `NPM_TOKEN`），并允许 Actions 运行。
 3. 打标签并推送：
 
    ```powershell
-   git tag v0.2.1
-   git push origin v0.2.1
+   git tag v0.3.0
+   git push origin v0.3.0
    ```
 
 工作流会先核对标签与 `package.json` 的 `version`，再执行 `npm publish --provenance --access public`。

package/cordis.patch.yml

@@ -22,5 +22,5 @@
     - id: dsh-web-search-plugin
       name: dsh-web-search-plugin
       config:
-        provider: tavily
+        provider: deepseek-official
         mode: keyless

package/lib/client.js

@@ -25,6 +25,25 @@ window.__ModuleLoader__.load({
 
 		/** Settings namespace of this plugin. */
 		const NS = "dsh-web-search-plugin";
+		/** Built-in REST providers (mirrors `lib/providers.js`; browser bundle is self-contained). */
+		const BUILTIN_REST_PROVIDERS = [
+			{ id: "serper", name: "Serper", officialUrl: "https://serper.dev/", keyRequired: true, keyField: "serperApiKey", keyEnvField: "serperApiKeyEnv", baseURLField: "serperBaseURL" },
+			{ id: "serpapi", name: "SerpApi", officialUrl: "https://serpapi.com/", keyRequired: true, keyField: "serpapiApiKey", keyEnvField: "serpapiApiKeyEnv", baseURLField: "serpapiBaseURL" },
+			{ id: "exa", name: "Exa", officialUrl: "https://dashboard.exa.ai/", keyRequired: true, keyField: "exaApiKey", keyEnvField: "exaApiKeyEnv", baseURLField: "exaBaseURL" },
+			{ id: "searxng", name: "SearXNG", officialUrl: "https://docs.searxng.org/", keyRequired: false, keyField: "", keyEnvField: "", baseURLField: "searxngBaseURL" },
+			{ id: "scavio", name: "Scavio", officialUrl: "https://scavio.dev/", keyRequired: true, keyField: "scavioApiKey", keyEnvField: "scavioApiKeyEnv", baseURLField: "scavioBaseURL" },
+			{ id: "firecrawl", name: "Firecrawl", officialUrl: "https://firecrawl.dev/", keyRequired: true, keyField: "firecrawlApiKey", keyEnvField: "firecrawlApiKeyEnv", baseURLField: "firecrawlBaseURL" }
+		];
+		/** Find a built-in REST provider by id. */
+		function builtinRest(id) {
+			for (const entry of BUILTIN_REST_PROVIDERS) if (entry.id === id) return entry;
+			return void 0;
+		}
+		/** Find a built-in REST provider by its literal key field name. */
+		function builtinRestByKeyField(field) {
+			for (const entry of BUILTIN_REST_PROVIDERS) if (entry.keyField === field) return entry;
+			return void 0;
+		}
 		/** Credential reference Tavily keyed mode resolves when the section names none. */
 		const DEFAULT_TAVILY_KEY_REF = "TAVILY_API_KEY";
 		/** Credential reference Brave resolves when the section names none. */
@@ -37,7 +56,9 @@ window.__ModuleLoader__.load({
 		const BRAVE_API_KEY_FIELD = "braveApiKey";
 		/** Form field the DeepSeek write-only credential control stages under. */
 		const DEEPSEEK_API_KEY_FIELD = "deepseekApiKey";
-		const SECRET_FIELDS = new Set([TAVILY_API_KEY_FIELD, BRAVE_API_KEY_FIELD, DEEPSEEK_API_KEY_FIELD]);
+		/** Form fields carrying literal API keys (write-only, staged under the credentials domain). */
+		const REST_KEY_FIELDS = BUILTIN_REST_PROVIDERS.map((entry) => entry.keyField).filter((field) => field !== "");
+		const SECRET_FIELDS = new Set([TAVILY_API_KEY_FIELD, BRAVE_API_KEY_FIELD, DEEPSEEK_API_KEY_FIELD, ...REST_KEY_FIELDS]);
 		const DRAFT_KEY = "dsh-web-search-plugin:settings-draft";
 
 		function readDraft() {
@@ -81,7 +102,8 @@ window.__ModuleLoader__.load({
 			apiKey: "API key",
 			apiKeyHint: "Stored outside the settings file. Leave blank to keep the current key.",
 			apiKeySet: "A key is configured.",
-			apiKeyUnset: "No key is configured; keyed / Brave search is unavailable until one is.",
+			apiKeyUnset: "No key set",
+			apiKeyUnavailableHint: "Search is unavailable until a key is configured.",
 			apiKeyEnv: "Credential reference",
 			apiKeyEnvHint: "Name of the credential/env var resolved for keyed Tavily search.",
 			braveApiKeyEnv: "Credential reference",
@@ -125,6 +147,9 @@ window.__ModuleLoader__.load({
 			maxUsesHint: "Maximum web_search server-tool uses per request.",
 			expand: "Show settings",
 			collapse: "Hide settings",
+			getKey: "Get API key",
+			ddgDisabled: "DuckDuckGo — use via SearXNG",
+			ddgHint: "DuckDuckGo has no official search API. Pick SearXNG and point it at an instance that includes DuckDuckGo (most public ones do), or self-host one.",
 			save: "Save",
 			saving: "Saving…",
 			discard: "Discard",
@@ -173,7 +198,8 @@ window.__ModuleLoader__.load({
 			apiKey: "API Key",
 			apiKeyHint: "不写入设置文件。留空表示保持当前密钥。",
 			apiKeySet: "已配置密钥。",
-			apiKeyUnset: "未配置密钥；keyed / Brave 模式下搜索不可用。",
+			apiKeyUnset: "未配置密钥",
+			apiKeyUnavailableHint: "未配置密钥前搜索不可用。",
 			apiKeyEnv: "凭据引用名",
 			apiKeyEnvHint: "keyed 模式解析的凭据/环境变量名。",
 			braveApiKeyEnv: "凭据引用名",
@@ -217,6 +243,9 @@ window.__ModuleLoader__.load({
 			maxUsesHint: "每次请求 web_search 服务端工具的最大调用次数。",
 			expand: "展开设置",
 			collapse: "收起设置",
+			getKey: "获取 API key",
+			ddgDisabled: "DuckDuckGo — 请经 SearXNG 使用",
+			ddgHint: "DuckDuckGo 没有官方搜索 API。请选择 SearXNG,并填入一个聚合了 DuckDuckGo 的实例地址(多数公共实例都有),或自建一个。",
 			save: "保存",
 			saving: "保存中…",
 			discard: "放弃修改",
@@ -328,7 +357,14 @@ window.__ModuleLoader__.load({
 					textField("model"),
 					textField("apiVersion"),
 					numberField("maxTokens", { min: 1 }),
-					numberField("maxUses", { min: 1 })
+					numberField("maxUses", { min: 1 }),
+					textField("serperApiKeyEnv"),
+					textField("serperBaseURL"),
+					textField("serpapiApiKeyEnv"),
+					textField("serpapiBaseURL"),
+					textField("exaApiKeyEnv"),
+					textField("exaBaseURL"),
+					textField("searxngBaseURL")
 				].map((spec) => [spec.field, spec]));
 				this.staged = new Map();
 				this.saving = false;
@@ -486,7 +522,7 @@ window.__ModuleLoader__.load({
 				this.staged.set(field, edit);
 				this.failed = false;
 				this.publish();
-				if (field === "provider" || field === "apiKeyEnv" || field === "braveApiKeyEnv" || field === "deepseekApiKeyEnv") this.readCredential();
+				if (field === "provider" || field === "apiKeyEnv" || field === "braveApiKeyEnv" || field === "deepseekApiKeyEnv" || BUILTIN_REST_PROVIDERS.some((entry) => entry.keyEnvField === field)) this.readCredential();
 			}
 			snapshotOf() {
 				return this.scope.getSnapshot();
@@ -513,7 +549,8 @@ window.__ModuleLoader__.load({
 				const staged = this.staged.get("provider");
 				if (staged !== void 0 && !staged.clear && staged.text.trim() !== "") return staged.text.trim();
 				const declared = this.sectionValue("provider");
-				return declared === "brave" || declared === "deepseek-official" ? declared : "tavily";
+				if (declared === "tavily" || declared === "brave" || declared === "deepseek-official" || builtinRest(declared) !== void 0) return declared;
+				return "deepseek-official";
 			}
 			tavilyRef() {
 				const declared = this.sectionValue("apiKeyEnv");
@@ -530,7 +567,17 @@ window.__ModuleLoader__.load({
 			/** The credential reference the currently visible engine uses. */
 			refOf() {
 				const provider = this.providerOf();
-				return provider === "brave" ? this.braveRef() : provider === "deepseek-official" ? this.deepseekRef() : this.tavilyRef();
+				if (provider === "brave") return this.braveRef();
+				if (provider === "deepseek-official") return this.deepseekRef();
+				const rest = builtinRest(provider);
+				if (rest !== void 0 && rest.keyRequired) return this.restKeyRef(rest);
+				return this.tavilyRef();
+			}
+			/** Credential reference for a built-in REST provider's key env field. */
+			restKeyRef(rest) {
+				const declared = this.sectionValue(rest.keyEnvField);
+				if (declared !== void 0 && declared.length > 0) return declared;
+				return rest.id === "serper" ? "SERPER_API_KEY" : rest.id === "serpapi" ? "SERPAPI_API_KEY" : "EXA_API_KEY";
 			}
 			async readCredential() {
 				const ref = this.refOf();
@@ -560,7 +607,13 @@ window.__ModuleLoader__.load({
 				this.readCredential();
 			}
 			async writeKey(field, value) {
-				const ref = field === BRAVE_API_KEY_FIELD ? this.braveRef() : field === DEEPSEEK_API_KEY_FIELD ? this.deepseekRef() : this.tavilyRef();
+				let ref;
+				if (field === BRAVE_API_KEY_FIELD) ref = this.braveRef();
+				else if (field === DEEPSEEK_API_KEY_FIELD) ref = this.deepseekRef();
+				else {
+					const rest = builtinRestByKeyField(field);
+					ref = rest !== void 0 ? this.restKeyRef(rest) : this.tavilyRef();
+				}
 				try {
 					await this.api.credentials.set({ ref, value });
 				} catch (_credentialWriteFailure) {}
@@ -606,6 +659,16 @@ window.__ModuleLoader__.load({
 					apiVersion: this.form.field("apiVersion"),
 					maxTokens: this.form.field("maxTokens"),
 					maxUses: this.form.field("maxUses"),
+					serperApiKey: this.form.field("serperApiKey"),
+					serperApiKeyEnv: this.form.field("serperApiKeyEnv"),
+					serperBaseURL: this.form.field("serperBaseURL"),
+					serpapiApiKey: this.form.field("serpapiApiKey"),
+					serpapiApiKeyEnv: this.form.field("serpapiApiKeyEnv"),
+					serpapiBaseURL: this.form.field("serpapiBaseURL"),
+					exaApiKey: this.form.field("exaApiKey"),
+					exaApiKeyEnv: this.form.field("exaApiKeyEnv"),
+					exaBaseURL: this.form.field("exaBaseURL"),
+					searxngBaseURL: this.form.field("searxngBaseURL"),
 					apiKeyConfigured: this.form.credential.configured,
 					apiKeyWritable: this.form.credential.writable,
 					toastKey: this.form.toastKey
@@ -674,11 +737,14 @@ window.__ModuleLoader__.load({
 				".dshws_quota_alert{font-size:11.5px;margin:0;line-height:1.45}",
 				".dshws_quota_alert_warning{color:var(--dsw-alias-state-warn-primary,#f59e0b)}",
 				".dshws_quota_alert_danger{color:var(--dsw-alias-state-error-primary,#ef4444)}",
-				".dshws_btn{appearance:none;font:inherit;cursor:pointer;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5;display:inline-flex;align-items:center;justify-content:center;transition:filter .15s ease,opacity .15s ease}",
-				".dshws_btn:disabled{cursor:not-allowed;opacity:.45}",
-				".dshws_btn_primary{border:1px solid transparent;color:var(--dsw-alias-label-on-brand,#fff);background:var(--dsw-alias-bg-brand-solid,var(--dsw-alias-brand-primary,#3b82f6));font-weight:600}",
-				".dshws_btn_primary:hover:not(:disabled){filter:brightness(1.08)}",
-				".dshws_btn_outline{border:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:transparent}",
+				".dshws_btn{appearance:none;font:inherit;cursor:pointer;border-radius:6px;padding:8px 16px;font-size:12.5px;font-weight:500;line-height:1.5;display:inline-flex;align-items:center;justify-content:center;border:1px solid transparent;transition:filter .15s ease,opacity .15s ease}",
+				".dshws_btn:disabled{cursor:not-allowed;opacity:.6}",
+				".dshws_btn_primary{background:var(--dsw-alias-button-primary-fill,var(--dsw-alias-brand-primary,#3b82f6));color:var(--dsw-alias-label-primary-foreground,#fff);font-weight:600}",
+				".dshws_btn_primary:hover:not(:disabled){filter:brightness(1.12)}",
+				".dshws_btn_secondary{background:var(--dsw-alias-button-tool-bar-fill,var(--dsw-alias-interactive-bg-hover,rgba(128,128,128,.1)));color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l2,var(--dsw-alias-border-secondary,rgba(128,128,128,.25)))}",
+				".dshws_btn_secondary:hover:not(:disabled){background:var(--dsw-alias-button-tool-bar-hover,var(--dsw-alias-interactive-bg-active,rgba(128,128,128,.16)))}",
+				".dshws_btn_outline{background:transparent;border-color:var(--dsw-alias-border-l2,var(--dsw-alias-border-secondary,rgba(128,128,128,.25)));color:var(--dsw-alias-label-secondary)}",
+				".dshws_btn_outline:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l1,rgba(128,128,128,.45));background:var(--dsw-alias-interactive-bg-hover,rgba(128,128,128,.1))}",
 				".dshws_toast{position:fixed;bottom:24px;left:50%;transform:translateX(-50%);background:var(--dsw-alias-state-success-primary,#10b981);color:#fff;padding:8px 18px;border-radius:999px;box-shadow:var(--dsw-shadow-lv3,0 8px 24px rgba(0,0,0,.3));font-size:12.5px;font-weight:500;z-index:100000;animation:dshws-toast-in .2s ease-out}",
 				".dshws_toast_error{background:var(--dsw-alias-state-error-primary,#ef4444)}",
 				".dshws_toast_info{background:var(--dsw-alias-label-secondary,#6b7280)}",
@@ -894,10 +960,13 @@ window.__ModuleLoader__.load({
 			const { t, state, actions } = props;
 			if (!state.available) return null;
 			const disabled = !state.writable;
-			const provider = state.provider.text === "brave" ? "brave" : state.provider.text === "deepseek-official" ? "deepseek-official" : "tavily";
+			const provider = state.provider.text === "tavily" || state.provider.text === "brave" || state.provider.text === "deepseek-official" || builtinRest(state.provider.text) !== void 0 ? state.provider.text : "deepseek-official";
 			const brave = provider === "brave";
 			const deepseek = provider === "deepseek-official";
+			const tavily = provider === "tavily";
+			const restMeta = builtinRest(provider);
 			const keyed = state.mode.text === "keyed";
+			const keyHint = state.apiKeyConfigured ? t("apiKeyHint") : t("apiKeyHint") + " " + t("apiKeyUnavailableHint");
 			const toastText = toastCopy(t, state.toastKey);
 			const toastTone = state.toastKey === "failed" || state.toastKey === "invalid" ? "error" : state.toastKey === "nothing" ? "info" : "success";
 			const row = (field, label, hint, children) => fieldRow(label, hint, children, {
@@ -930,29 +999,32 @@ window.__ModuleLoader__.load({
 					row("provider", t("provider"), null, selectInput({ id: "ws-provider", value: provider, disabled, onChange: (e) => actions.edit("provider", e.target.value), children: [
 						react.createElement("option", { value: "tavily", key: "tavily" }, t("providerTavily")),
 						react.createElement("option", { value: "brave", key: "brave" }, t("providerBrave")),
-						react.createElement("option", { value: "deepseek-official", key: "deepseek-official" }, t("providerDeepseek"))
-					] })),
-					deepseek || brave ? null : row("mode", t("mode"), null, selectInput({ id: "ws-mode", value: state.mode.text, disabled, onChange: (e) => actions.edit("mode", e.target.value), children: [
+						react.createElement("option", { value: "deepseek-official", key: "deepseek-official" }, t("providerDeepseek")),
+						...BUILTIN_REST_PROVIDERS.map((entry) => react.createElement("option", { value: entry.id, key: entry.id }, entry.name)),
+						react.createElement("option", { value: "__ddg__", key: "ddg", disabled: true }, t("ddgDisabled"))
+					] }),
+					react.createElement("p", { className: "dshws_field_hint", style: { padding: "4px 0 0" } }, t("ddgHint"))),
+					tavily ? row("mode", t("mode"), null, selectInput({ id: "ws-mode", value: state.mode.text, disabled, onChange: (e) => actions.edit("mode", e.target.value), children: [
 						react.createElement("option", { value: "keyless", key: "keyless" }, t("modeKeyless")),
 						react.createElement("option", { value: "keyed", key: "keyed" }, t("modeKeyed"))
-					] }))
+					] })) : null
 				),
 				react.createElement(QuotaCard, { t, provider, keyed }),
 				deepseek ? pair(
-					fieldRow(t("apiKey"), t("apiKeyHint"), secretInput({ id: "ws-deepseek-key", value: state.deepseekApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(DEEPSEEK_API_KEY_FIELD, e.target.value) })),
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-deepseek-key", value: state.deepseekApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(DEEPSEEK_API_KEY_FIELD, e.target.value) })),
 					row("deepseekApiKeyEnv", t("deepseekApiKeyEnv"), t("deepseekApiKeyEnvHint"), textInput({ id: "ws-deepseek-keyref", value: state.deepseekApiKeyEnv.text, disabled, onChange: (e) => actions.edit("deepseekApiKeyEnv", e.target.value) }))
 				) : null,
 				brave ? pair(
-					fieldRow(t("apiKey"), t("apiKeyHint"), secretInput({ id: "ws-brave-key", value: state.braveApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(BRAVE_API_KEY_FIELD, e.target.value) })),
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-brave-key", value: state.braveApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(BRAVE_API_KEY_FIELD, e.target.value) })),
 					row("braveApiKeyEnv", t("braveApiKeyEnv"), t("braveApiKeyEnvHint"), textInput({ id: "ws-brave-keyref", value: state.braveApiKeyEnv.text, disabled, onChange: (e) => actions.edit("braveApiKeyEnv", e.target.value) }))
 				) : null,
-				(!brave && !deepseek && keyed) ? pair(
-					fieldRow(t("apiKey"), t("apiKeyHint"), secretInput({ id: "ws-tavily-key", value: state.apiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(TAVILY_API_KEY_FIELD, e.target.value) })),
+				(tavily && keyed) ? pair(
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-tavily-key", value: state.apiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(TAVILY_API_KEY_FIELD, e.target.value) })),
 					row("apiKeyEnv", t("apiKeyEnv"), t("apiKeyEnvHint"), textInput({ id: "ws-tavily-keyref", value: state.apiKeyEnv.text, disabled, onChange: (e) => actions.edit("apiKeyEnv", e.target.value) }))
 				) : null,
 				deepseek ? row("deepseekBaseURL", t("deepseekBaseURL"), t("deepseekBaseURLHint"), textInput({ id: "ws-deepseek-base", value: state.deepseekBaseURL.text, disabled, onChange: (e) => actions.edit("deepseekBaseURL", e.target.value) })) : null,
 				brave ? row("braveBaseURL", t("braveBaseURL"), t("braveBaseURLHint"), textInput({ id: "ws-brave-base", value: state.braveBaseURL.text, disabled, onChange: (e) => actions.edit("braveBaseURL", e.target.value) })) : null,
-				(!brave && !deepseek) ? row("baseURL", t("baseURL"), t("baseURLHint"), textInput({ id: "ws-tavily-base", value: state.baseURL.text, disabled, onChange: (e) => actions.edit("baseURL", e.target.value) })) : null,
+				tavily ? row("baseURL", t("baseURL"), t("baseURLHint"), textInput({ id: "ws-tavily-base", value: state.baseURL.text, disabled, onChange: (e) => actions.edit("baseURL", e.target.value) })) : null,
 				deepseek ? pair(
 					row("model", t("model"), t("modelHint"), textInput({ id: "ws-model", value: state.model.text, disabled, onChange: (e) => actions.edit("model", e.target.value) })),
 					row("apiVersion", t("apiVersion"), t("apiVersionHint"), textInput({ id: "ws-apiversion", value: state.apiVersion.text, disabled, onChange: (e) => actions.edit("apiVersion", e.target.value) }))
@@ -961,7 +1033,7 @@ window.__ModuleLoader__.load({
 					row("maxTokens", t("maxTokens"), t("maxTokensHint"), numberInput({ id: "ws-maxtokens", value: state.maxTokens.text, disabled, onChange: (e) => actions.edit("maxTokens", e.target.value), className: state.maxTokens.invalid ? "dshws_input_invalid" : void 0 })),
 					row("maxUses", t("maxUses"), t("maxUsesHint"), numberInput({ id: "ws-maxuses", value: state.maxUses.text, disabled, onChange: (e) => actions.edit("maxUses", e.target.value), className: state.maxUses.invalid ? "dshws_input_invalid" : void 0 }))
 				) : null,
-				(!brave && !deepseek) ? pair(
+				tavily ? pair(
 					row("searchDepth", t("searchDepth"), null, selectInput({ id: "ws-depth", value: state.searchDepth.text, disabled, onChange: (e) => actions.edit("searchDepth", e.target.value), children: [
 						react.createElement("option", { value: "basic", key: "basic" }, t("searchDepthBasic")),
 						react.createElement("option", { value: "advanced", key: "advanced" }, t("searchDepthAdvanced"))
@@ -971,7 +1043,7 @@ window.__ModuleLoader__.load({
 						react.createElement("option", { value: "news", key: "news" }, t("topicNews"))
 					] }))
 				) : null,
-				(!brave && !deepseek) ? pair(
+				tavily ? pair(
 					row("includeAnswer", t("includeAnswer"), t("includeAnswerHint"), checkboxInput({ id: "ws-answer", checked: state.includeAnswer.text === "true", disabled, onChange: (e) => actions.edit("includeAnswer", e.target.checked ? "true" : "") })),
 					maxResultsRow
 				) : null,
@@ -991,10 +1063,25 @@ window.__ModuleLoader__.load({
 				) : null,
 				brave ? row("proxy", t("proxy"), null, textInput({ id: "ws-proxy", value: state.proxy.text, disabled, placeholder: t("proxyPlaceholder"), onChange: (e) => actions.edit("proxy", e.target.value) })) : null,
 				deepseek ? maxResultsRow : null,
+				restMeta ? react.createElement("div", { className: "dshws_form" },
+					restMeta.keyRequired && restMeta.officialUrl ? react.createElement("a", {
+						href: restMeta.officialUrl,
+						target: "_blank",
+						rel: "noopener noreferrer",
+						className: "dshws_field_hint",
+						style: { color: "var(--dsw-alias-brand-primary,#3b82f6)", textDecoration: "none", padding: "8px 0", display: "inline-block" }
+					}, t("getKey") + " ↗") : null,
+					restMeta.keyRequired ? pair(
+						fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-" + restMeta.id + "-key", value: state[restMeta.keyField]?.text ?? "", disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(restMeta.keyField, e.target.value) })),
+						row(restMeta.keyEnvField, t("apiKeyEnv"), t("apiKeyEnvHint"), textInput({ id: "ws-" + restMeta.id + "-keyref", value: state[restMeta.keyEnvField]?.text ?? "", disabled, onChange: (e) => actions.edit(restMeta.keyEnvField, e.target.value) }))
+					) : null,
+					row(restMeta.baseURLField, t("baseURL"), t("baseURLHint"), textInput({ id: "ws-" + restMeta.id + "-base", value: state[restMeta.baseURLField]?.text ?? "", disabled, onChange: (e) => actions.edit(restMeta.baseURLField, e.target.value) })),
+					maxResultsRow
+				) : null,
 				react.createElement("div", { style: { borderTop: "1px solid var(--dsw-alias-border-l2)", justifyContent: "flex-end", alignItems: "center", gap: "8px", padding: "12px 0 4px", display: "flex" } },
 					react.createElement("button", {
 						type: "button",
-						className: "dshws_btn dshws_btn_outline",
+						className: "dshws_btn dshws_btn_secondary",
 						disabled: (!state.dirty && !state.failed) || state.saving,
 						onClick: (event) => {
 							event.preventDefault();

package/lib/index.js

@@ -23,6 +23,8 @@ import { TAVILY_DEFAULT_API_KEY_ENV, TAVILY_DEFAULT_BASE_URL, TavilySearchProvid
 import { BRAVE_DEFAULT_API_KEY_ENV, BRAVE_DEFAULT_BASE_URL, BraveSearchProvider, resolveBraveOptions } from "./brave.js";
 import { DEEPSEEK_DEFAULT_API_KEY_ENV, DEEPSEEK_DEFAULT_BASE_URL, DeepSeekSearchProvider, resolveDeepseekOptions } from "./deepseek.js";
 import { TAVILY_USAGE_POLL_MS, UsageTracker } from "./usage.js";
+import { RestSearchProvider, resolveRestProvider } from "./rest.js";
+import { BUILTIN_REST_IDS, REST_PROVIDERS, findProvider } from "./providers.js";
 
 /** Stable id this plugin registers under on `ctx.web`. */
 const SEARCH_PROVIDER_ID = "dsh-web-search";
@@ -34,8 +36,8 @@ const inject = ["web"];
 
 /** Plugin config (all optional — `apply` fills defaults). */
 const Config = z.object({
-	/** Active backend: `deepseek-official`, `tavily` (default), or `brave`. */
-	provider: z.string().default("tavily"),
+	/** Active backend: `deepseek-official` (default), `tavily`, `brave`, `serper`, `serpapi`, `exa`, or `searxng`. */
+	provider: z.string().default("deepseek-official"),
 	/** Tavily auth mode: `keyless` (default) or `keyed`. */
 	mode: z.string().default("keyless"),
 	/** Literal Tavily API key; prefer {@link apiKeyEnv}. */
@@ -66,6 +68,38 @@ const Config = z.object({
 	freshness: z.string().default(""),
 	/** Optional HTTP(S) proxy URL for Brave (falls back to HTTPS_PROXY / HTTP_PROXY). */
 	proxy: z.string().default(""),
+	/** Literal Serper API key; prefer {@link serperApiKeyEnv}. */
+	serperApiKey: z.string().role("secret").default(""),
+	/** Credential reference for Serper search. */
+	serperApiKeyEnv: z.string().role("credential-ref").default("SERPER_API_KEY"),
+	/** Serper endpoint base. `/search` is appended. */
+	serperBaseURL: z.string().default(""),
+	/** Literal SerpApi API key; prefer {@link serpapiApiKeyEnv}. */
+	serpapiApiKey: z.string().role("secret").default(""),
+	/** Credential reference for SerpApi search. */
+	serpapiApiKeyEnv: z.string().role("credential-ref").default("SERPAPI_API_KEY"),
+	/** SerpApi endpoint base. `/search.json` is appended. */
+	serpapiBaseURL: z.string().default(""),
+	/** Literal Exa API key; prefer {@link exaApiKeyEnv}. */
+	exaApiKey: z.string().role("secret").default(""),
+	/** Credential reference for Exa search. */
+	exaApiKeyEnv: z.string().role("credential-ref").default("EXA_API_KEY"),
+	/** Exa endpoint base. `/search` is appended. */
+	exaBaseURL: z.string().default(""),
+	/** Optional SearXNG instance base URL (self-hosted). `/search` is appended. */
+	searxngBaseURL: z.string().default(""),
+	/** Literal Scavio API key; prefer {@link scavioApiKeyEnv}. */
+	scavioApiKey: z.string().role("secret").default(""),
+	/** Credential reference for Scavio search. */
+	scavioApiKeyEnv: z.string().role("credential-ref").default("SCAVIO_API_KEY"),
+	/** Scavio endpoint base. `/api/v2/google` is appended. */
+	scavioBaseURL: z.string().default(""),
+	/** Literal Firecrawl API key; prefer {@link firecrawlApiKeyEnv}. */
+	firecrawlApiKey: z.string().role("secret").default(""),
+	/** Credential reference for Firecrawl search. */
+	firecrawlApiKeyEnv: z.string().role("credential-ref").default("FIRECRAWL_API_KEY"),
+	/** Firecrawl endpoint base. `/v2/search` is appended. */
+	firecrawlBaseURL: z.string().default(""),
 	/** Literal DeepSeek API key; prefer {@link deepseekApiKeyEnv}. */
 	deepseekApiKey: z.string().role("secret").default(""),
 	/** Credential reference for DeepSeek search. */
@@ -106,6 +140,13 @@ class PluginSearchProvider {
 			...this.resolveOptions().brave,
 			onRateLimit: (headers) => usage?.recordBraveHeaders(headers)
 		}));
+		this.rest = new Map();
+		for (const providerId of BUILTIN_REST_IDS) {
+			this.rest.set(providerId, new RestSearchProvider(providerId, () => this.resolveOptions().rest[providerId], {
+				onUsage: providerId === "tavily" ? (credits) => usage?.recordTavilyCredits(credits) : void 0,
+				onRateLimit: providerId === "brave" ? (headers) => usage?.recordBraveHeaders(headers) : void 0
+			}));
+		}
 	}
 
 	available() {
@@ -117,21 +158,63 @@ class PluginSearchProvider {
 	}
 
 	backend() {
-		const provider = this.resolveOptions().provider;
-		if (provider === "brave") return this.brave;
+		const options = this.resolveOptions();
+		const provider = options.provider;
+		const restInstance = this.rest.get(provider);
+		if (restInstance !== void 0) return restInstance;
 		if (provider === "deepseek-official") return this.deepseek;
-		return this.tavily;
+		// Fallback: provider points at something unknown → official default.
+		return this.deepseek;
 	}
 }
 
 /** Project one resolved section into options for each backend. */
 function resolveOptions(ctx, config) {
-	const provider = config.provider === "brave" || config.provider === "deepseek-official" ? config.provider : "tavily";
+	const isBuiltIn = config.provider === "tavily" || config.provider === "brave" || config.provider === "deepseek-official" || BUILTIN_REST_IDS.includes(config.provider);
+	const provider = isBuiltIn ? config.provider : "deepseek-official";
+	// Per-provider literal key / optional endpoint override, used when the
+	// metadata row's default is not enough (self-hosted SearXNG, proxied
+	// providers, custom key refs).
+	const keySourceByProvider = {
+		brave: { literal: config.braveApiKey, envName: config.braveApiKeyEnv ?? BRAVE_DEFAULT_API_KEY_ENV, baseURL: config.braveBaseURL ?? "", proxy: config.proxy },
+		tavily: { literal: config.apiKey, envName: config.apiKeyEnv ?? TAVILY_DEFAULT_API_KEY_ENV, baseURL: config.baseURL ?? "" },
+		serper: { literal: config.serperApiKey, envName: config.serperApiKeyEnv ?? "SERPER_API_KEY", baseURL: config.serperBaseURL ?? "" },
+		serpapi: { literal: config.serpapiApiKey, envName: config.serpapiApiKeyEnv ?? "SERPAPI_API_KEY", baseURL: config.serpapiBaseURL ?? "" },
+		exa: { literal: config.exaApiKey, envName: config.exaApiKeyEnv ?? "EXA_API_KEY", baseURL: config.exaBaseURL ?? "" },
+		searxng: { baseURL: config.searxngBaseURL ?? "" },
+		scavio: { literal: config.scavioApiKey, envName: config.scavioApiKeyEnv ?? "SCAVIO_API_KEY", baseURL: config.scavioBaseURL ?? "" },
+		firecrawl: { literal: config.firecrawlApiKey, envName: config.firecrawlApiKeyEnv ?? "FIRECRAWL_API_KEY", baseURL: config.firecrawlBaseURL ?? "" }
+	};
+	const settings = {
+		country: config.country,
+		searchLang: config.searchLang,
+		freshness: config.freshness,
+		searchDepth: config.searchDepth,
+		topic: config.topic,
+		includeAnswer: config.includeAnswer
+	};
+	const rest = {};
+	for (const providerId of BUILTIN_REST_IDS) {
+		const row = findProvider(providerId);
+		if (row === void 0) continue;
+		const source = keySourceByProvider[providerId] ?? {};
+		const resolved = resolveRestProvider(ctx, row, {
+			config,
+			settings,
+			keyed: providerId === "tavily" ? config.mode === "keyed" : false,
+			keySource: source
+		});
+		// Endpoint override: an explicit config baseURL wins over the row default.
+		if (source.baseURL != null && source.baseURL.length > 0) resolved.baseURL = source.baseURL;
+		if (providerId === "brave" && (source.proxy ?? "").length > 0) resolved.proxy = source.proxy;
+		rest[providerId] = resolved;
+	}
 	return {
 		provider,
 		deepseek: resolveDeepseekOptions(ctx, config),
 		tavily: resolveTavilyOptions(ctx, config),
-		brave: resolveBraveOptions(ctx, config)
+		brave: resolveBraveOptions(ctx, config),
+		rest
 	};
 }
 
@@ -236,11 +319,14 @@ function apply(ctx, config) {
 export {
 	BRAVE_DEFAULT_API_KEY_ENV,
 	BRAVE_DEFAULT_BASE_URL,
+	BUILTIN_REST_IDS,
 	BraveSearchProvider,
 	Config,
 	DEEPSEEK_DEFAULT_API_KEY_ENV,
 	DEEPSEEK_DEFAULT_BASE_URL,
 	DeepSeekSearchProvider,
+	REST_PROVIDERS,
+	RestSearchProvider,
 	SEARCH_PROVIDER_ID,
 	TAVILY_DEFAULT_API_KEY_ENV,
 	TAVILY_DEFAULT_BASE_URL,
@@ -250,6 +336,8 @@ export {
 	WEB_SEARCH_SETTINGS_NAMESPACE,
 	WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE,
 	apply,
+	findProvider,
 	inject,
-	name
+	name,
+	resolveRestProvider
 };

package/lib/providers.js

@@ -0,0 +1,212 @@
+/**
+ * Static metadata table for every built-in REST web-search provider.
+ *
+ * This module is intentionally **data, not code**: adding a new REST provider
+ * means adding one row here (plus an optional official "get a key" link in the
+ * settings card), with zero per-provider execution code. The generic backend in
+ * `lib/rest.js` reads a row and performs `method` / `path` / `queryParam` /
+ * `countParam` / `params` / `auth` / `response` / `hooks`.
+ *
+ * Only **pure REST providers** ("one query → one HTTP request → one result
+ * array") belong here. Model-native search tool (DeepSeek's Anthropic Messages
+ * `web_search_20250305`, Perplexity sonar tools, OpenAI Responses) is **not**
+ * REST and stays on its dedicated backend (`lib/deepseek.js`).
+ *
+ * @module dsh-web-search-plugin/providers
+ */
+
+/**
+ * Built-in REST providers.
+ * `auth.type` ∈ { `bearer`, `header`, `none`, `query` }:
+ *   - `bearer` — `Authorization: Bearer <key>`
+ *   - `header` — key in a named header (`auth.header`)
+ *   - `none`   — no key (SearXNG, keyless)
+ *   - `query`  — key as a query-string parameter (`auth.param`, e.g. SerpApi)
+ * `params[].when` ∈ { `always`, `nonEmpty`, `keyed`, `keyless` }.
+ */
+export const REST_PROVIDERS = [
+	{
+		id: "brave",
+		name: "Brave Search",
+		kind: "rest",
+		method: "GET",
+		baseURL: "https://api.search.brave.com/res/v1/web/search",
+		path: "",
+		queryIn: "query",
+		queryParam: "q",
+		countParam: "count",
+		auth: { type: "header", header: "X-Subscription-Token" },
+		keyRequired: true,
+		apiKeyRef: "BRAVE_API_KEY",
+		response: "brave",
+		params: [
+			{ key: "country", setting: "country", when: "nonEmpty" },
+			{ key: "search_lang", setting: "searchLang", when: "nonEmpty" },
+			{ key: "freshness", setting: "freshness", when: "nonEmpty" }
+		],
+		officialUrl: "https://api-dashboard.search.brave.com/",
+		hooks: ["rate-limit", "proxy"]
+	},
+	{
+		id: "tavily",
+		name: "Tavily",
+		kind: "rest",
+		method: "POST",
+		baseURL: "https://api.tavily.com",
+		path: "/search",
+		queryIn: "body",
+		queryParam: "query",
+		countParam: "max_results",
+		auth: { type: "bearer" },
+		keyRequired: false, // keyless by default; keyed only when a key is configured
+		apiKeyRef: "TAVILY_API_KEY",
+		response: "tavily",
+		params: [
+			{ key: "search_depth", setting: "searchDepth", when: "nonEmpty" },
+			{ key: "topic", setting: "topic", when: "nonEmpty" },
+			{ key: "include_answer", setting: "includeAnswer", when: "nonEmpty" },
+			{ key: "include_images", value: false, when: "always" },
+			{ key: "include_usage", value: true, when: "keyed" }
+		],
+		keylessHeaders: { "x-tavily-access-mode": "keyless" },
+		keylessHeaderWhen: "keyless",
+		officialUrl: "https://app.tavily.com/",
+		hooks: ["usage"]
+	},
+	{
+		id: "serper",
+		name: "Serper",
+		kind: "rest",
+		method: "POST",
+		baseURL: "https://google.serper.dev",
+		path: "/search",
+		queryIn: "body",
+		queryParam: "q",
+		countParam: "num",
+		auth: { type: "header", header: "X-API-KEY" },
+		keyRequired: true,
+		apiKeyRef: "SERPER_API_KEY",
+		response: "serper",
+		params: [],
+		officialUrl: "https://serper.dev/",
+		hooks: []
+	},
+	{
+		id: "serpapi",
+		name: "SerpApi",
+		kind: "rest",
+		method: "GET",
+		baseURL: "https://serpapi.com",
+		path: "/search.json",
+		queryIn: "query",
+		queryParam: "q",
+		countParam: "num",
+		auth: { type: "query", param: "api_key" },
+		keyRequired: true,
+		apiKeyRef: "SERPAPI_API_KEY",
+		response: "serper",
+		params: [],
+		officialUrl: "https://serpapi.com/",
+		hooks: []
+	},
+	{
+		id: "exa",
+		name: "Exa",
+		kind: "rest",
+		method: "POST",
+		baseURL: "https://api.exa.ai",
+		path: "/search",
+		queryIn: "body",
+		queryParam: "query",
+		countParam: "num_results",
+		auth: { type: "bearer" },
+		keyRequired: true,
+		apiKeyRef: "EXA_API_KEY",
+		response: "exa",
+		params: [
+			{ key: "contents", value: "text", when: "always" }
+		],
+		officialUrl: "https://dashboard.exa.ai/",
+		hooks: []
+	},
+	{
+		id: "searxng",
+		name: "SearXNG",
+		kind: "rest",
+		method: "GET",
+		baseURL: "https://searx.be",
+		path: "/search",
+		queryIn: "query",
+		queryParam: "q",
+		countParam: "count",
+		auth: { type: "none" },
+		keyRequired: false,
+		apiKeyRef: "",
+		response: "searxng",
+		params: [
+			{ key: "format", value: "json", when: "always" }
+		],
+		officialUrl: "https://docs.searxng.org/",
+		hooks: []
+	},
+	{
+		id: "scavio",
+		name: "Scavio",
+		kind: "rest",
+		method: "POST",
+		baseURL: "https://api.scavio.dev",
+		path: "/api/v2/google",
+		queryIn: "body",
+		queryParam: "query",
+		countParam: "",
+		auth: { type: "bearer" },
+		keyRequired: true,
+		apiKeyRef: "SCAVIO_API_KEY",
+		response: "serper",
+		params: [
+			{ key: "hl", setting: "searchLang", when: "nonEmpty" },
+			{ key: "gl", setting: "country", when: "nonEmpty" }
+		],
+		officialUrl: "https://scavio.dev/",
+		hooks: []
+	},
+	{
+		id: "firecrawl",
+		name: "Firecrawl",
+		kind: "rest",
+		method: "POST",
+		baseURL: "https://api.firecrawl.dev",
+		path: "/v2/search",
+		queryIn: "body",
+		queryParam: "query",
+		countParam: "limit",
+		auth: { type: "bearer" },
+		keyRequired: true,
+		apiKeyRef: "FIRECRAWL_API_KEY",
+		response: "firecrawl",
+		params: [
+			{ key: "sources", value: "web", when: "always" }
+		],
+		officialUrl: "https://firecrawl.dev/",
+		hooks: []
+	}
+];
+
+/** Location of one provider by id (the id doubles as the `provider` value). */
+export function findProvider(id) {
+	for (const entry of REST_PROVIDERS) if (entry.id === id) return entry;
+	return void 0;
+}
+
+/** Set of ids that live in the metadata table. */
+export function restProviderIds() {
+	const ids = /* @__PURE__ */ new Set();
+	for (const entry of REST_PROVIDERS) ids.add(entry.id);
+	return ids;
+}
+
+/** The built-in REST provider ids (seam-facing `provider` values). */
+export const BUILTIN_REST_IDS = REST_PROVIDERS.map((entry) => entry.id);
+
+/** The model-native (non-REST) provider id, kept on its own backend. */
+export const TOOL_PROVIDER_IDS = ["deepseek-official"];

package/lib/rest.js

@@ -0,0 +1,325 @@
+/**
+ * Generic REST web-search backend driven by the static metadata table in
+ * `lib/providers.js`. One instance handles any built-in REST provider and any
+ * user-defined `customProviders[]` entry, so adding a provider is data (a table
+ * row), not a new backend class.
+ *
+ * Request shape comes from the provider row: `method` (GET/POST), `path`
+ * (POST suffix), `queryIn` (query-string vs JSON body), `queryParam` /
+ * `countParam` (field names), `params[]` (fixed/conditional extra params), and
+ * `auth` (bearer/header/none/query). Response shape is normalized by the
+ * lenient parser in this module to the seam's `WebSearchResult`.
+ *
+ * Side effects (Tavily credits, Brave rate-limit headers, proxy dispatch) are
+ * optional hooks the caller injects; the generic body never hard-codes them.
+ *
+ * @module dsh-web-search-plugin/rest
+ */
+import { WebError } from "@deepseek-ai/dsh-web";
+import { ProxyAgent } from "undici";
+import { MAX_RESULTS_CAP, USER_AGENT, isAbortError, resolveApiKey, resolveSecret, searchAborted, throwIfSearchAborted } from "./shared.js";
+
+/** Acceptable auth templates (superset includes `query` for SerpApi). */
+const AUTH_TYPES = new Set(["bearer", "header", "none", "query"]);
+
+/** Read a non-empty string field. */
+function str(value) {
+	return typeof value === "string" ? value : "";
+}
+
+/** Resolve a `params[]` entry to `{ key, value }` or `null` (skip). */
+/** Keep the param's native type: booleans stay booleans (JSON true/false). */
+function paramValue(value) {
+	if (typeof value === "boolean") return value;
+	return value === void 0 ? "" : String(value);
+}
+
+function resolveParam(param, ctx) {
+	if (param === null || typeof param !== "object") return null;
+	const when = str(param.when) || "always";
+	const key = str(param.key);
+	if (key === "") return null;
+	if (when === "always") {
+		return { key, value: paramValue(param.value) };
+	}
+	if (when === "nonEmpty") {
+		const raw = ctx[param.setting];
+		// Booleans: only `true` is "non-empty"; `false`/missing means omit the field.
+		if (typeof raw === "boolean") return raw === true ? { key, value: true } : null;
+		const value = str(raw);
+		if (value === "") return null;
+		return { key, value };
+	}
+	if (when === "keyed") {
+		return ctx.keyed === true ? { key, value: paramValue(param.value) } : null;
+	}
+	if (when === "keyless") {
+		return ctx.keyed !== true ? { key, value: paramValue(param.value) } : null;
+	}
+	return null;
+}
+
+/** Push one source, deduped by url, only when it has a usable url. */
+function pushSource(sources, seen, item, title, snippet, publishedAt) {
+	const url = str(item.url ?? item.link ?? item.id);
+	if (url === "" || seen.has(url)) return;
+	seen.add(url);
+	sources.push({
+		url,
+		...str(title).length > 0 ? { title } : {},
+		...str(snippet).length > 0 ? { snippet } : {},
+		...str(publishedAt).length > 0 ? { publishedAt } : {}
+	});
+}
+
+/**
+ * Normalize a provider response into a `WebSearchResult` using a lenient
+ * (宽容) parser: the results array is located in the first non-empty of
+ * `organic_results` / `organic` → `web.results` → `results`, and per-item
+ * fields accept the common aliases (`url`/`link`, `content`/`snippet`/
+ * `description`/`text`, `published_date`/`date`/`page_age`/`publishedDate`).
+ * The `response` hint only influences which answer-style block becomes
+ * `content`.
+ * @param json - the parsed response body.
+ * @param response - the response-shape hint (`tavily`/`brave`/`exa`/`serper`).
+ */
+function mapCustomResponse(json, response) {
+	if (json === null || typeof json !== "object") throw new WebError("The provider returned a non-object response body", "WEB_PROVIDER_ERROR");
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [];
+	const hint = str(response) || "tavily";
+	let results = null;
+	// Position of the results array, ordered by the common providers:
+	// Serper/Scavio/SerpApi → `organic_results` / `organic`;
+	// Firecrawl → `data.web` (v2) or bare `data` array (v1);
+	// Brave → `web.results`; Tavily/Exa/SearXNG → `results`.
+	if (hint === "firecrawl") {
+		results = Array.isArray(json?.data?.web) ? json.data.web : Array.isArray(json.data) ? json.data : null;
+	} else if (hint === "serper" || hint === "serpapi" || hint === "scavio") {
+		results = Array.isArray(json.organic_results) ? json.organic_results : Array.isArray(json.organic) ? json.organic : null;
+	} else {
+		results = Array.isArray(json.organic) ? json.organic : null;
+	}
+	if (results === null || results.length === 0) {
+		results = Array.isArray(json?.web?.results) ? json.web.results : null;
+	}
+	if (results === null || results.length === 0) {
+		results = Array.isArray(json.results) ? json.results : [];
+	}
+	for (const item of results) {
+		if (item === null || typeof item !== "object") continue;
+		const snippet = str(item.content).length > 0
+			? item.content
+			: str(item.snippet).length > 0
+				? item.snippet
+				: str(item.description).length > 0
+					? item.description
+					: str(item.text).length > 0
+						? item.text
+						: Array.isArray(item.highlights) && str(item.highlights[0]).length > 0
+							? item.highlights[0]
+							: Array.isArray(item.extra_snippets) && str(item.extra_snippets[0]).length > 0
+								? item.extra_snippets[0]
+								: "";
+		pushSource(sources, seen, item, item.title, snippet, item.published_date ?? item.date ?? item.page_age ?? item.publishedDate);
+	}
+	const answer = str(json.answer).length > 0
+		? json.answer
+		: str(json.answerBox?.answer).length > 0
+			? json.answerBox.answer
+			: str(json.knowledgeGraph?.description).length > 0
+				? json.knowledgeGraph.description
+				: str(json.knowledge_graph?.description).length > 0
+					? json.knowledge_graph.description
+					: "";
+	return {
+		...answer.length > 0 ? { content: answer } : {},
+		sources,
+		truncated: false
+	};
+}
+
+/**
+ * Generic REST backend. `resolveOptions` returns a projection with `baseURL`,
+ * `method`, `path`, `queryIn`, `queryParam`, `countParam`, `auth`, `response`,
+ * `params`, `keyed`, and optional `apiKey` / `resolveApiKey`.
+ */
+export class RestSearchProvider {
+	constructor(id, resolveOptions, hooks) {
+		this.id = id;
+		this.resolveOptions = resolveOptions;
+		this.hooks = hooks ?? {};
+		this.cachedProxy = void 0;
+		this.cachedDispatcher = void 0;
+	}
+
+	available() {
+		const options = this.resolveOptions();
+		if (options?.baseURL == null || !URL.canParse(options.baseURL)) return false;
+		const auth = options.auth ?? { type: "none" };
+		if (auth.type === "none") return true;
+		return (options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0;
+	}
+
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		throwIfSearchAborted(signal);
+		if (options?.baseURL == null || !URL.canParse(options.baseURL)) {
+			throw new WebError(`Provider "${this.id}" has no usable endpoint`, "WEB_PROVIDER_ERROR");
+		}
+		const auth = AUTH_TYPES.has(options.auth?.type) ? options.auth : { type: "none" };
+		const method = options.method === "GET" ? "GET" : "POST";
+		const queryIn = options.queryIn === "query" ? "query" : "body";
+		const queryParam = str(options.queryParam) || "query";
+		const countParam = str(options.countParam) || "max_results";
+		const responseHint = str(options.response) || "tavily";
+		const count = Math.min(request.maxResults ?? options.maxResults ?? 8, MAX_RESULTS_CAP);
+
+		let apiKey;
+		if (auth.type !== "none") {
+			apiKey = await resolveApiKey(options, signal, `Provider "${this.id}" has no API key for "${options.apiKeyEnv ?? options.apiKeyRef ?? "key"}"; store it through the credentials service, export it in the launching environment, or fill it in the settings card`);
+			throwIfSearchAborted(signal);
+		}
+
+		// Build query-string params (GET) or JSON body (POST).
+		const baseURL = options.baseURL.replace(/\/+$/u, "");
+		const path = str(options.path) || "";
+		let endpoint = baseURL + (path === "" ? "" : "/" + path.replace(/^\/+/u, ""));
+		const query = {
+			[queryParam]: request.query
+		};
+		if (countParam !== "") query[countParam] = String(count);
+		const keyed = options.keyed === true;
+		for (const param of options.params ?? []) {
+			const resolved = resolveParam(param, { keyed, ...options.settings ?? {} });
+			if (resolved !== null) query[resolved.key] = resolved.value;
+		}
+
+		const headers = {
+			accept: "application/json",
+			"user-agent": USER_AGENT
+		};
+		let body = void 0;
+		if (method === "GET") {
+			const params = new URLSearchParams();
+			for (const [key, value] of Object.entries(query)) params.set(key, value);
+			// SerpApi: the key rides the query string too.
+			if (auth.type === "query") params.set(str(auth.param) || "api_key", apiKey);
+			endpoint = `${endpoint}${endpoint.includes("?") ? "&" : "?"}${params.toString()}`;
+		} else {
+			headers["content-type"] = "application/json";
+			body = JSON.stringify(query);
+		}
+
+		// Auth headers.
+		if (auth.type === "bearer") headers["authorization"] = `Bearer ${apiKey}`;
+		else if (auth.type === "header") headers[str(auth.header) || "x-api-key"] = apiKey;
+		else if (auth.type === "query") {
+			/* handled above for GET; POST with query auth is unsupported by design */
+		}
+
+		// Keyless-mode headers (Tavily x-tavily-access-mode).
+		const keylessHeaders = options.keylessHeaders ?? {};
+		const keylessWhen = options.keylessHeaderWhen ?? "";
+		if (keylessWhen === "keyless" && keyed === false) Object.assign(headers, keylessHeaders);
+		else if (keylessWhen === "keyed" && keyed === true) Object.assign(headers, keylessHeaders);
+		else if (keylessWhen === "" || keylessWhen === "always") Object.assign(headers, keylessHeaders);
+
+		const dispatcher = this.dispatcher(options);
+		let httpResponse;
+		try {
+			httpResponse = await fetch(endpoint, {
+				method,
+				redirect: "error",
+				headers,
+				...(body !== void 0 ? { body } : {}),
+				...signal !== void 0 ? { signal } : {},
+				...dispatcher !== void 0 ? { dispatcher } : {}
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`Provider "${this.id}" request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+
+		this.hooks.onRateLimit?.(httpResponse.headers);
+		if (!httpResponse.ok) {
+			let message = `Provider "${this.id}" API error (HTTP ${httpResponse.status})`;
+			try {
+				const parsed = await httpResponse.json();
+				const detail = parsed?.detail?.error ?? parsed?.error ?? parsed?.message ?? parsed?.search_metadata?.error;
+				if (typeof detail === "string" && detail.length > 0) message = detail;
+				else if (typeof detail === "object" && detail != null && typeof detail.message === "string") message = detail.message;
+			} catch {
+				/* non-JSON error body — keep the status-line message */
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+
+		try {
+			const json = await httpResponse.json();
+			if (responseHint === "tavily" && typeof this.hooks.onUsage === "function") {
+				const credits = Number(json?.usage?.credits);
+				if (Number.isFinite(credits) && credits >= 0) this.hooks.onUsage(credits);
+			}
+			return mapCustomResponse(json, responseHint);
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			if (error instanceof WebError) throw error;
+			throw new WebError(`Provider "${this.id}" returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+
+	/** Cached undici ProxyAgent keyed by the current proxy URL. */
+	dispatcher(options) {
+		const proxy = options?.proxy;
+		if (proxy === void 0 || proxy.length === 0) return void 0;
+		if (this.cachedProxy === proxy) return this.cachedDispatcher;
+		if (this.cachedDispatcher !== void 0) {
+			this.cachedDispatcher.close?.().catch(() => {});
+		}
+		this.cachedProxy = proxy;
+		this.cachedDispatcher = new ProxyAgent(proxy);
+		return this.cachedDispatcher;
+	}
+}
+
+/**
+ * Project a provider table row + plugin section into backend options consumed
+ * by `RestSearchProvider`. `resolveSecret(ctx, ...)` supplies `apiKey` /
+ * `resolveApiKey` when the provider needs a key.
+ *
+ * @param {string} ctx - plugin context (for credential/env resolution).
+ * @param {object} row - the provider metadata row (`lib/providers.js`).
+ * @param {object} opts - `{ config, settings, keyed, keySource }`.
+ * @returns backend options for one search.
+ */
+export function resolveRestProvider(ctx, row, opts) {
+	const { config, settings } = opts;
+	const auth = row.auth ?? { type: "none" };
+	const keyed = opts.keyed === true;
+	const base = {
+		baseURL: row.baseURL,
+		method: row.method ?? "POST",
+		path: row.path ?? "",
+		queryIn: row.queryIn ?? "body",
+		queryParam: row.queryParam ?? "query",
+		countParam: row.countParam ?? "max_results",
+		auth,
+		response: row.response ?? "tavily",
+		params: row.params ?? [],
+		keyed,
+		keylessHeaders: row.keylessHeaders ?? {},
+		keylessHeaderWhen: row.keylessHeaderWhen ?? "",
+		settings,
+		maxResults: config.maxResults ?? 8
+	};
+	if (auth.type === "none") return base;
+	const keySource = opts.keySource ?? {};
+	return {
+		...base,
+		...resolveSecret(ctx, {
+			literal: keySource.literal,
+			envName: keySource.envName ?? row.apiKeyRef ?? ""
+		})
+	};
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-web-search-plugin",
-  "version": "0.2.1",
-  "description": "Unified web search for the DeepSeek Harness seam (ctx.web): DeepSeek (official), Tavily, and Brave backends with an in-browser selector",
+  "version": "0.3.0",
+  "description": "Unified web search for the DeepSeek Harness seam (ctx.web): DeepSeek (official), Tavily, Brave, Serper, SerpApi, Exa, SearXNG, Scavio, and Firecrawl backends",
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",
@@ -53,7 +53,7 @@
     }
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/shared.js && node --check lib/tavily.js && node --check lib/brave.js && node --check lib/deepseek.js && node --check lib/usage.js"
+    "check": "node --check lib/index.js && node --check lib/client.js && node --check lib/shared.js && node --check lib/providers.js && node --check lib/rest.js && node --check lib/tavily.js && node --check lib/brave.js && node --check lib/deepseek.js && node --check lib/usage.js"
   },
   "dependencies": {
     "undici": "^6.21.0"