概览

dsh-web-search-router

Priority-ordered multi-provider web_search router for DeepSeek Harness with automatic fallback.

README / ZH

插件文档

dsh-web-search-router

面向 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#<commit-or-tag>

随包 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 规则

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

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

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

开发

npm test

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

安全

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

License

MIT

dsh-web-search-router