解析ModSearch引擎注册表:6个SearchEngine接口如何实现零配置角色化调度
解析ModSearch引擎注册表:6个SearchEngine接口如何实现零配置角色化调度
ModSearch 是一款免费、免注册、免 API Key 的联网搜索插件,为没有原生联网能力的模型补上搜索、抓取和 X 查询能力。这篇文章带你从源码解析它的引擎注册表:6 个 SearchEngine 接口如何覆盖"网页搜索 / 页面抓取 / X 检索"三种任务,并通过角色化调度实现开箱即用、自动降级。
🧭 一图看懂:注册表与调度器各管一摊
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 的插件设置卡里,你可以看到这些引擎的开关与首选配置——勾选的引擎才会参与故障转移:
引擎链怎么选:planRole 的四步决策
调度核心 planRole(src/router.ts#L106-L188)按以下顺序组装"引擎链":
- 显式
--engine是硬指定:链里只放这一个引擎,没有回退——它坏了就大声失败,绝不偷偷烧掉别的引擎的配额。 - 配置文件里的
engine是软偏好:名字写错会提示并自动改选,被engines.<name>.enabled关闭则跳过。 - 按角色默认优先级补链:依次加入可用且启用的引擎。
- 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 条带来源的排序结果,模型据此作答:
想接入新引擎?写一个SearchEngine对象即可
扩展新搜索引擎的成本很低:
- 实现 src/providers/index.ts#L62-L79 定义的
SearchEngine接口(选execute或buildInvocation+parseOutput其一); - 在
ENGINES注册表中登记(可加别名); - 按需要把它加入
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 中的完整使用方式。


