解析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，每个引擎用一张"名片"描述自己的能力：

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

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

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

进程内 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）按以下顺序组装"引擎链"：

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 条带来源的排序结果，模型据此作答：

想接入新引擎？写一个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 中的完整使用方式。