搜索提供方路由Kerberos255/dsh-web-search-router

dsh-web-search-router

English

面向 DeepSeek Harness 的多提供方 web_search 优先级路由插件。

插件只注册一个 DSH Web Search Provider：web-search-router。模型侧工具保持不变，Agent 仍然调用 DSH 内置的 web_search；Router 按设置顺序从上到下尝试提供方，第一个成功结果即返回。

功能

- 在 DSH Settings 中调整搜索提供方顺序、启用或停用提供方。
- 缺配置、请求失败、超时、限流、额度/余额耗尽时自动 fallback。
- 默认空结果继续尝试下一提供方。
- 临时网络/5xx 使用短冷却；429、quota/credit 类错误使用可配置冷却。
- 排序、启停、超时、冷却等非敏感设置保存到 DSH 官方 Settings namespace，并可热生效。
- API Key 只进入 DSH credentials / launch environment，Settings UI 不读取已保存的 Key 值。
- Provider 错误在写日志或向 Router 上层返回前会做脱敏处理。

支持的提供方

| 提供方 | 配置 |
| --- | --- |
| SearXNG | 在 Settings 填 Base URL；无需 API Key |
| DeepSeek Search | 默认 DEEPSEEK_API_KEY；可通过插件配置覆盖 credential ref / Base URL / model |
| Tavily | TAVILY_API_KEY |
| Brave Search | BRAVE_API_KEY |
| Exa | EXA_API_KEY |
| Firecrawl | FIRECRAWL_API_KEY |
| Parallel | PARALLEL_API_KEY |
| DuckDuckGo | 无 Key；作为 best-effort HTML 兜底 |

未配置的提供方会自动跳过。

兼容性

当前兼容目标：DSH 0.1.0-rc.6 与 0.1.1-rc.x，Node.js 20+。

DeepSeek Harness 仍处于 developer preview，后续可能出现破坏性兼容变更。建议安装时固定插件 commit/release，并在升级 DSH 后重新测试。

Agent Preset 要求

本插件负责的是搜索后端，不会额外注册一个新的模型工具。Agent preset 必须包含 DSH 内置 web_search（例如标准模式）。如果使用没有挂载 web_search 的极简 preset，模型不会调用本 Router。

安装

本地开发：

dsh plugin --profile web add link:/absolute/path/to/dsh-web-search-router

GitHub 公开后建议固定 commit 或 release：

dsh plugin --profile web add github:Kerberos255/dsh-web-search-router#

随包 cordis.patch.yml 使用通用默认配置：将 DSH 的 search provider 指向 web-search-router，并插入插件本身。

Settings

打开 设置 → 插件 → 插件配置 → Web Search Router，展开卡片后可进行：

- 调整提供方优先级；
- 启用/停用提供方；
- 配置 SearXNG；
- 写入或清除各提供方 API Key；
- 设置单提供方超时和冷却时间；
- 设置空结果是否继续下一项。

非敏感设置由 DSH 官方 Settings 保存到 $DSH_HOME/settings.yaml 的 web-search-router namespace。升级自旧版时，如果该 namespace 尚无用户层，插件会一次性读取旧的 $DSH_HOME/plugins/web-search-router.json 并迁移；旧文件随后不再参与运行。

Settings 写操作只允许 loopback。本插件通过 DSH credentials 写 Key；前端只读取“已配置/未配置”状态。

DeepSeek Search 高级配置

默认使用 DSH 官方 DeepSeek Search 配置。需要代理或兼容端点时，可由 profile 覆盖：

- id: web-search-router
config:
deepseekBaseURL: https://api.deepseek.com/anthropic/v1
deepseekModel: deepseek-v4-flash
deepseekApiKeyEnv: DEEPSEEK_API_KEY

Settings UI 会跟随实际 deepseekApiKeyEnv，不会把 DeepSeek Key 名称写死。

Fallback 规则

对每个已启用提供方，按顺序执行：

1. 未配置或仍在 cooldown 时跳过；
2. 按设置的单提供方超时执行；
3. 成功立即停止并返回；
4. 空结果按策略决定是否继续；
5. 失败则分类、设置必要的 cooldown，并尝试下一提供方。

如果调用方主动 abort，会立即向上抛出，不进行 fallback。

开发

npm test

公开测试覆盖路由顺序/fallback/cooldown、设置持久化及 Provider 请求/结果映射。依赖本机 DSH、真实凭证和本机路径的 live 测试不会进入公开仓库。

安全

- 不要提交 API Key 或 .env。
- 凭证值只在 Host 侧解析。
- Browser 只获得 credential ref 与配置状态，不会获得已保存 Key 值。
- Router 在日志和失败摘要中会脱敏 URL 以及疑似 key/token 字符串。

License

MIT