解析ModSearch引擎注册表:6个SearchEngine接口如何实现零配置角色化调度

原创2026-10-28 17:49:461,720 阅读

解析ModSearch引擎注册表:6个SearchEngine接口如何实现零配置角色化调度

ModSearch 是一款免费、免注册、免 API Key 的联网搜索插件,为没有原生联网能力的模型补上搜索、抓取和 X 查询能力。这篇文章带你从源码解析它的引擎注册表:6 个 SearchEngine 接口如何覆盖"网页搜索 / 页面抓取 / X 检索"三种任务,并通过角色化调度实现开箱即用、自动降级。

ModSearch工作流:无联网能力的模型经modsearch skill分发到网页搜索、读页面、X检索,最终输出结构化JSON证据

🧭 一图看懂:注册表与调度器各管一摊

ModSearch 的引擎体系由两个文件协作完成,分工非常清晰:

  • 引擎注册表:src/providers/index.ts —— 登记所有引擎,定义 SearchEngine 接口、别名映射和每个角色(Role)的默认优先级。
  • 角色化调度器:src/router.ts —— 源码注释写得很直白:"所有关于哪个来源运行、哪个引擎服务的决策都在这里,代码库其他任何地方都不挑选引擎"。

换句话说:注册表回答"有哪些引擎、谁会什么",调度器回答"这次任务派给谁、失败了换谁"。

六个SearchEngine接口全盘点

SearchEngine 接口定义在 src/providers/index.ts#L62-L79,每个引擎用一张"名片"描述自己的能力:

字段 作用
name / roles 引擎名称与能承担的角色(search / fetch / social)
isAvailable 当前机器上是否可用(装没装、配没配 Key)
requirement 给人类看的一句话:"还缺什么才能启用我"
execute 或 buildInvocation + parseOutput 两种执行契约(见下文)
defaultModel / describeFailure 默认模型、把非零退出码翻译成可操作提示

妙处在于接口抽象出了两种执行方式,让"进程内调 API"和"拉起子进程跑 Agent"两类引擎共用同一条调度链路:

  • 进程内引擎(Firecrawl、Tavily、Exa、local)实现 execute,直接用内置 HTTP 客户端打 REST API 或本地抓取;
  • 子进程引擎(Antigravity CLI、Grok Build)实现 buildInvocation + parseOutput,负责拼 CLI 命令并解析 JSON 输出。

六个引擎的完整名录如下(注册表见 src/providers/index.ts#L81-L95):

引擎 别名 角色 启用条件 实现文件
Firecrawl firecrawl search + fetch 零门槛,免 Key 免费额度 src/providers/firecrawl.ts
Antigravity CLI antigravity-cli、agy search + fetch 安装 CLI 并登录一次(免费、无 Key) src/providers/antigravity.ts
Tavily tavily search 配置 API Key(每月 1,000 免费额度) src/providers/tavily.ts
Exa exa search 配置 API Key src/providers/exa.ts
Grok Build grok-cli、grok social(X 检索) 安装 Grok Build 并用 SuperGrok / X Premium 登录 src/providers/grok.ts
local local、http、direct fetch 永远可用,零依赖 src/providers/httpFetch.ts

进程内 REST 引擎:搜索主力

  • Firecrawl 是默认首选:不带 Key 也能用(免费免注册额度),既能搜索,又能在云端跑真实浏览器抓取 JS 重度渲染页面,是"零配置承诺"的核心。
  • Tavily / Exa 是需要 Key 的备胎:只支持搜索,Key 耗尽或限流时会被冷却机制暂时靠后。

子进程 Agent 引擎:能"思考"的搜索

Antigravity CLI 是少数兼具 search + fetch 的 Agent 引擎,会综合多个来源并给出带引用的答案,但每周配额较小,所以排在 Firecrawl 之后。

Grok Build 是 X(推特)检索的唯一入口——因为只有 xAI 能看到 X 站内内容。它通过登录态判断可用性(src/providers/grok.ts#L48-L50),不可用时调度器会自动把 X 问题降级到网页搜索。

本地直抓兜底:永远在场的 local 引擎

local 引擎就是"打开 URL、剥离 HTML、还你正文"的朴素 HTTP 抓取,没有 LLM、没有 Key、没有配额(isAvailable: () => true)。它的质量不高(JS 渲染页面会偏薄),但保证任何机器上 fetch 角色至少有一个引擎可用。

角色化调度:search / fetch / social 三个角色

ModSearch 把任务抽象为三种角色(src/config.ts#L17):search(搜网页)、fetch(抓页面)、social(搜 X)。每个角色有一张"最佳优先"名单:

search: firecrawl → antigravity-cli → tavily → exa
fetch:  firecrawl → antigravity-cli → local
social: grok-cli

源码中的排序逻辑写得很清楚:Firecrawl 领头的理由就是"裸机免注册就能跑,兑现零配置承诺";而 fetch 链条末尾永远补上 local 兜底(FETCH_FLOOR,见 src/providers/index.ts#L101-L117)。

在 DeepSeek Harness 的插件设置卡里,你可以看到这些引擎的开关与首选配置——勾选的引擎才会参与故障转移:

DeepSeek Harness中ModSearch插件的引擎设置卡片:首选引擎、API密钥与可自动引用的引擎列表

引擎链怎么选:planRole 的四步决策

调度核心 planRole(src/router.ts#L106-L188)按以下顺序组装"引擎链":

  1. 显式 --engine 是硬指定:链里只放这一个引擎,没有回退——它坏了就大声失败,绝不偷偷烧掉别的引擎的配额。
  2. 配置文件里的 engine 是软偏好:名字写错会提示并自动改选,被 engines.<name>.enabled 关闭则跳过。
  3. 按角色默认优先级补链:依次加入可用且启用的引擎。
  4. fetch 角色追加 local 兜底:除非用户显式关掉这个"地板"。

每一步都只追加"当前真的可用"的引擎(isAvailable 过滤),所以一台什么都没装的新机器,链条会自动收缩成"Firecrawl(免 Key)→ local"这样的最小可用组合。

容错降级:冷却重排与 X 源保底

冷却重排(src/router.ts#L195-L217):某个引擎因限流/配额耗尽进入冷却后,不会被踢出链条,而是被稳定地挪到链尾,健康引擎先试;结果里还会附一条 note 说明"某引擎冷却到何时"。

X 源保底:当查询被识别为 X 话题("推特""发推""x.com"等模式)时,来源锁定为 x;若 Grok 不可用:

  • 网页没被同时请求 → X 槽位直接改用网页引擎链回答,并附带 X_DEGRADE_NOTE,明确告诉模型"这是二手信息,网页看不到 X 站内";
  • 网页已在计划中 → 不再重复发起同样的搜索,而是输出一个显式标记 unavailable 的空条目,避免机器消费者误以为"X 已覆盖"。

一次真实搜索的效果如下,Firecrawl 返回 8 条带来源的排序结果,模型据此作答:

ModSearch网页搜索演示:模型调用一次搜索,Firecrawl返回带来源的AI新闻结果并汇总作答

想接入新引擎?写一个SearchEngine对象即可

扩展新搜索引擎的成本很低:

  1. 实现 src/providers/index.ts#L62-L79 定义的 SearchEngine 接口(选 execute 或 buildInvocation + parseOutput 其一);
  2. 在 ENGINES 注册表中登记(可加别名);
  3. 按需要把它加入 ROLE_PREFERENCE 对应角色的优先级列表。

调度、冷却、降级、密钥脱敏(apiKeySecrets)全部自动继承,无需改动路由逻辑。

总结

  • 注册表(src/providers/index.ts):6 个引擎、统一接口,进程内 API 与子进程 Agent 两种执行方式无缝共存;
  • 角色化调度(src/router.ts):search / fetch / social 三张优先级名单 + fetch 的 local 兜底,保证零配置也能跑;
  • 硬指定与软偏好分离:--engine 强制、配置文件偏好、角色默认值三层规则互不干扰;
  • 容错不静默:冷却引擎靠后但保留,X 降级必带说明,结果永远可解释。

想进一步动手,可以从 docs/dsh.md 与 skills/modsearch/SKILL.md 入手,了解 ModSearch 在 Harness 中的完整使用方式。

登录后查看全文
modsearch