chendefine/dsh-web-search-aggregation

dsh-web-search-aggregation

English · npm · GitHub

DeepSeek Harness（DSH）双端插件：把内置 web_search 工具的搜索后端换成一条按优先级排序的聚合队列（AnySearch / TinyFish / Tavily / Brave / Exa / Firecrawl / Jina / SerpApi / Serper）——每个提供商可挂多个 API key 按轮转使用，任一次尝试失败自动落到下一个 key 或下一个提供商，第一个成功者生效。

特性

• 优先级队列，有序回退 —— 每次请求自上而下逐个尝试：第一个返回结果的生效，失败的条目自动落到下一个。顺序在配置页面中实时编辑；每个提供商最多入队一次。
• 多 key 池 + 轮转 —— 每个提供商只读一个凭据（ANYSEARCH_API_KEY / TINYFISH_API_KEY / TAVILY_API_KEY / BRAVE_SEARCH_API_KEY / EXA_API_KEY / FIRECRAWL_API_KEY / JINA_API_KEY / SERPAPI_API_KEY / SERPER_API_KEY），其值为该提供商全部 key 用 , 拼接。同一条目内的 key 按轮转顺序尝试（每成功一次前进一格），在池内分摊负载与配额。
• 开箱即用 —— AnySearch 允许匿名访问，没配任何 key 时队列即可完成搜索。出厂默认只是启用全部九家——先后顺序完全由你在卡片里编排；需 key 的条目在凭据就位前只是跳过。
• 预算受控 —— 每次尝试有独立超时（默认 10s，范围 1–60s），一个挂死的上游吃不掉工具层预算；60s 内仍可容纳 5–6 轮完整回退。
• 失败可读 —— 全部失败时错误信息逐条列出每次尝试（[2] tavily/TAVILY_API_KEY#1: 401 unauthorized; …）。队列为空抛 WEB_PROVIDER_UNAVAILABLE；调用方取消立即抛 WEB_ABORTED。
• 密钥卫生 —— key 明文绝不进日志、绝不出现在失败记录里（只引用 REF / REF#N 标签）；配置页面以打码 tag 展示，已存的值永不回显。
• 热配置 —— 「插件」页面（侧边栏 → 插件 → dsh-web-search-aggregation，dsh ≥ 0.1.7）：插件包首页直接展示完整配置表单（行内「配置」入口打开同一表单）；随时编辑队列、key、端点与超时，提交后对下一次搜索即时生效，无需重启。

工作原理

web_search (tool-web)
   └─ ctx.web.searchProvider = aggregated
        ├─ 队列（自上而下，首个成功者生效——顺序由用户编排）：
        │     anysearch · firecrawl · tavily · tinyfish · brave · exa · jina · serpapi · serper
        │       │   keys = 凭据值按 ',' 拆分          ← 每个提供商一个池
        │       │   无 key 的 AnySearch 条目允许匿名尝试
        │       └─ 每条目一个轮转游标（端点改动即重置）
        ├─ 每次尝试：adapter 请求，独立超时（默认 10s）
        └─ 全部失败 → WEB_PROVIDER_ERROR + 逐次尝试摘要

当前内置九个 adapter；接入下一个上游只需一个 adapter 模块加一行注册表。

环境要求

• DSH web profile（dsh web），Node.js ≥ 22.19——与 DSH 自身要求一致（^22.19.0 || >=24）。从 GitHub 源码安装会在安装时执行 prepare 构建，版本要求相同。
• 至少一个上游可达：默认队列不配任何凭据即可用（AnySearch 匿名）；Tavily / TinyFish / Brave / Exa / Firecrawl / Jina / SerpApi / Serper 条目需配各自 API key 才会参与。

安装

从 npm registry 安装（预构建产物，无需构建授权）：

dsh plugin --profile web add dsh-web-search-aggregation

从 GitHub 仓库安装（源码型，pnpm 会在安装时跑 prepare 构建；若 pnpm 拦截构建脚本，请在 profiles/web/pnpm-workspace.yaml 中放行该包）：

dsh plugin --profile web add github:chendefine/dsh-web-search-aggregation

或通过 DSH 插件市场（设置 → DSH插件市场）一键安装——本仓库带 dsh-plugin topic，会被自动收录。

bundle 插件加入 profile 层栈后需重启 dsh web 生效；卸载用 dsh plugin --profile web remove dsh-web-search-aggregation 后重启。

配置项

插件页面（侧边栏 → 插件）里 dsh-web-search-aggregation 卡片的「查看」直接落到插件包首页 —— 完整表单就展示在描述与组件行之间；组件行的「配置」入口打开的是同一表单。它实时编辑 web-search-aggregation 设置段（由插件条目的 Config schema 派生）：

API key 在每个条目上以打码 tag 管理：一次输入一个（+ 或回车加入），tag 顺序即保存与运行时读取的顺序。已存的 key 不回显，保存将整体替换该池；关闭全部 tag 再保存即清空凭据。每个提供商的 key 存于唯一固定凭据：

与其他 provider 插件组合

bundle patch 会整体替换 web seam 行的 config，因此最后应用的层决定最终的 searchProvider / fetchProvider 组合。本插件的 patch 只声明 searchProvider: aggregated——只认领搜索选择权，别的不碰。两个推论：

• 先装 dsh-web-fetch-playwright 再装本插件（或不装前者）时无需任何调整：未配置的 fetchProvider 会自动选中唯一注册的 fetch provider。

• 若另一插件的层在本插件之后应用并重置了 searchProvider，请在 profile 自己的 profiles/web/cordis.patch.yml 中固定组合选择——用户层压过所有 bundle 层：

  - id: web
    config:
      searchProvider: aggregated
      fetchProvider: playwright
  

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run（103 个单元测试，不联网）
pnpm build       # tsc 声明 + tsdown（宿主 ESM + 客户端 module-registration bundle）

仓库结构：

src/
├── index.ts               # 宿主入口：注册 provider（volatile Config 即设置段）
├── config.ts              # schemastery schema、默认值、队列归一化
├── provider.ts            # AggregatedSearchProvider：队列遍历、轮转、超时
├── keys.ts                # ',' 拼接 key 池词汇（解析/格式化/打码）
├── types.ts               # 队列条目、配置、单次尝试失败记录
├── adapters/              # AnySearch / Tavily / TinyFish / Brave / Exa / Firecrawl / Jina / SerpApi / Serper adapter + 共享 HTTP
└── client/                # 浏览器半端：插件页配置卡片、表单模型、多语言
tests/                     # config、keys/adapters、provider、client-controller

开发与发布流程见 CONTRIBUTING.md，安全模型与漏洞报告见 SECURITY.md。

安全边界

搜索词与 API key 只发往每个队列条目配置的端点（默认九家提供商的官方 API）。key 存于 DSH credentials 域——不落 settings 文件、不进日志、不回显客户端。失败记录与日志只引用打码标签（如 TAVILY_API_KEY#2），不含明文。除请求它的会话外，不保留任何结果数据。

许可证

MIT © 2026 chendefine