OmniRoute 路线图解析:从 3.8.x 稳定轨道到 4.0 模块化 AI 平台

本文基于仓库中的 ROADMAP.md 完整解读 OmniRoute 的版本路线:以"按版本门控而非按日期门控"(version-gated, not date-gated) 为核心原则,规划了从 3.8.50 到 3.8.59 的准备工作轨、3.9.0 LTS 锚点,以及 4.0 模块化平台的四阶段演进。读完本文,你将掌握 OmniRoute 每个阶段的版本目标、分支模型(stable/v3 / develop / main)的分工,以及作为贡献者如何针对不同类型的 PR 选择正确的目标分支。

版本轨道总览

路线图的核心主张是:OmniRoute 正在从一个单体路由器(monolithic router)演进为一个模块化 AI 平台——轻量核心引擎、类型化 SDK,其余一切均为可安装的模块与插件。路径贯穿一条稳定化轨道(3.8.50 → 3.8.59)、一个 LTS 锚点(3.9.0)和模块化的 4.0:

3.8.50 ─ 3.8.54   PREPARE   非破坏性结构准备(欢迎所有 PR)
3.8.55 ─ 3.8.59   VALIDATE  稳定化(仅 fixes / docs / i18n / providers)
3.9.0             LTS       stable/v3 分支 · 长期支持线
4.0.0-nightly/rc  MODULAR   核心 + SDK + 模块 + 市场(develop 分支)
4.0.0             GA        latest 切换到 v4 · v3 保持 LTS 支持

从当前仓库状态可以印证这条轨道正处于 Phase 1:根目录 package.json 中 "version": "3.8.51",恰好落在"PREPARE"区间的第二个版本上,说明路线图的版本表不是纸面规划,而是与实际发布节奏同步推进的。

Phase 1 — 准备阶段(3.8.50 → 3.8.54)

这一阶段做非破坏性的结构工作,目标是为模块化拆分去风险。每个版本收尾时都会运行一套强制的质量门(quality-gate battery),通过后才开放新一轮合并。

版本	聚焦点
3.8.50	release 分支上的 CI 安全网 · 死代码清理 · 社区报告的 catalog/topology bug 修复 · 贡献者"黄金路径"指南
3.8.51	Executor 注册表(in-place)· 端到端 provider-journey 契约测试成为 CI 门 · 官方 scoped-test 开发循环 · CI lane 整合(各 gate job 共享 install/setup,#8084)
3.8.52	combo.ts 拆分 · 路由策略注册表 · /v1/models 的统一模型目录契约 · release/** 与 main 的 PR 统一 CI 策略(#8084)
3.8.53	chatCore.ts 拆分 · headless 模式(OMNIROUTE_HEADLESS=1)· 本地候选构建/晋级循环
3.8.54	发布基础设施(休眠):channels、labels、PR 模板、merge queue · TIA 影子证据出清后,全量回归权限移交 merge queue(#8084)· 公开 feature-freeze 公告

其中 3.8.51 的"Executor 注册表"在仓库中已有实体证据:open-sse/executors/registry.ts 与 open-sse/executors/index.ts 构成了执行器注册体系,配套的 open-sse/executors/defaultResolver.ts 提供默认解析。从源码结构看,这正是"先把执行器从硬编码映射改为注册表"这一准备工作的落点——只有当执行器可以按名字注册与发现,4.0 阶段"providers as plugins"才不需要再改动核心代码。

配套的验证手段也已在仓库中:例如 tests/unit/executor-map-golden.test.ts 这类 golden/characterization 测试,用来在重构前后锁定行为不变——这正是 Phase 2 中"为每个抽取候选写 characterization 测试"的预演。

Phase 2 — 验证阶段(3.8.55 → 3.8.59)

外部功能 PR 在此暂停(打上 v4-feature 标签,v4 通道开放后重新指向 v4 通道)。修复、文档、i18n 与 provider 更新继续流入。

版本	聚焦点
3.8.55	为每个抽取候选编写 characterization 测试 · 耦合度复测
3.8.56	扩展 canary · 性能基线(heap、TTFB、build)
3.8.57	安全与合规审查 · 发布溯源(OIDC)演练
3.8.58	3.9.0 切版的完整 dry-run(分支、channels、forward-port)——包含 PR 预览制品 + build-once 晋级演练(#8084)
3.8.59	最终冻结 · 全量套件审计 · GO/NO-GO 决策

这一阶段的多个聚焦点在仓库中已有可对照的既有设施:

• 3.9.0 切版 dry-run:合并队列与手动"合并列车"(merge-train)的操作手册已固化在 docs/ops/MERGE_TRAIN.md 中,其中 queue 标签即合并批准、Mergify 自动二分红色批次、以及 npm run check:release-green 的按批次/按 tip 分层验证策略,都是 3.8.58 演练的直接对象。
• 构建/晋级循环:发布脚本目录 scripts/release/ 下已有 merge-train.sh(手动合并列车自动化)、verify-published.mjs(发布后校验)、sync-next-cycle.mjs(下一周期同步)等工具,与 3.8.53"本地候选构建/晋级循环"、3.8.54"merge queue"的规划一一对应。
• 真实环境验证:发布前对同型部署的 E2E 验证由 homologation 套件承担,见 docs/ops/HOMOLOGATION.md(npm run homolog,覆盖健康检查、临时 key 生命周期、SSE 流、真实 provider 冒烟与 UI 路由),它是 3.8.59"全量套件审计"的组成部分。
• OIDC 发布溯源:与 changelog 碎片聚合脚本 scripts/release/aggregate-changelog.mjs 同目录的发布工具链,构成了 3.8.57 发布溯源演练的基建。

Phase 3 — v3.9.0 LTS:长生命周期分支模型

3.8.59 之后,下一个版本是 3.9.0(不存在 3.8.60)。它建立了长生命周期分支模型:

• stable/v3 — LTS 线(3.9.x)。接收修复、安全补丁与 provider 更新。整个 v4 周期内,npm install omniroute(即 latest)始终停留在 v3。
• develop — v4 开发线,以 4.0.0-nightly.* 发布。
• main — v4 发布候选(next),最终是 GA。
• 合并到 stable/v3 的修复会自动 forward-port 到 develop,并完整保留贡献者署名(Co-authored-by)。

新功能进入 v4 通道;LTS 线以稳定为第一优先。

这条 LTS 模型是对现有发布模型的自然延伸。当前仓库已经采用"并行周期"(parallel-cycle)发布模型:活跃的 release/vX.Y.Z 分支承载日常开发,main 是发布线,不可变的 vX.Y.Z tag 标记"实际发布的比特",详见 docs/ops/BRANCHING_MODEL.md。从该文档的分支流转图(release/vX.Y.Z → squash-merge 到 main → 打 tag → 下一周期分支)可以推断,3.9.0 之后的 stable/v3 / develop / main 三线模型就是把"release 分支"的角色固化为长期存在的稳定线,而把原 main 的日常集成职责移交给 develop。

Phase 4 — v4.0:模块化平台

单体代码在 develop 上被有意拆解:

• @omniroute/core(npm 包名保持 omniroute)——只有引擎:/v1/*、路由、combo/fallback、providers。
• @omniroute/sdk — 一套类型化契约:hooks、扩展点、两阶段生命周期、UI 贡献。当前存在的五套扩展体系(plugins、CLI plugins、skills、MCP tools、A2A skills)收敛为一个声明式 manifest。
• 模块(@omniroute/mod-*) — cloud agents、流量检查(MITM)、evals、webhooks、memory、guardrails、observability 等从核心移出,各自拥有独立版本与生命周期。
• Providers 即插件 — 新增 provider 不再触碰核心代码。
• Marketplace — 一键安装并验证完整性(hash 固定、签名、沙箱)。v1 免费;后续有付费层,并向创作者分成。

发布节奏:4.0.0-nightly.* → 4.0.0-rc.N(生产环境浸泡)→ 4.0.0 GA,届时 latest 切换到 v4,v3 进入已宣布的 LTS 支持窗口。

核心永远是 MIT 协议且免费。

这一阶段的拆分目标与 Phase 1 的准备工作首尾呼应:executor 注册表(3.8.51)让 provider 可以注册而非硬编码,combo.ts / chatCore.ts 的拆分(3.8.52/3.8.53)先解耦最大体量模块,characterization 测试(3.8.55)保证拆分前后行为一致。仓库中现有的工作区结构(根 package.json 声明 workspaces: ["open-sse", "packages/browser-pool"],以及独立的 @omniroute/opencode-plugin / @omniroute/opencode-provider 包)表明多包布局的基建已经就位,4.0 的 @omniroute/mod-* 模块可以沿用同样的模式扩展。

贡献者指南:PR 应该指向哪个分支

路线图给出了按阶段变化的目标分支矩阵:

你提交的是…	当前目标	3.8.55 起	3.9.0 之后
Bug 修复 / 安全	活跃的 release/v3.8.x	不变	stable/v3
Provider 更新	活跃的 release/v3.8.x	不变	stable/v3
文档 / i18n	活跃的 release/v3.8.x	不变	stable/v3
新功能	活跃的 release/v3.8.x	挂起并打 v4-feature 标签	develop(v4)

各变更类型的完整黄金路径见 CONTRIBUTING.md;发布冻结(freeze)期间的重定向规则见 docs/ops/BRANCHING_MODEL.md。

支撑路线图的变更管理设施

路线图能"按版本门控"的前提,是变更历史本身可审计、无冲突。仓库用 changelog 碎片机制保证这一点:PR 从不直接编辑 CHANGELOG.md,而是向 changelog.d/ 下的 features/ / fixes/ / maintenance/ 三个目录各加一个 <PR号>-<slug>.md 碎片文件,发布时由 node scripts/release/aggregate-changelog.mjs 聚合进 CHANGELOG 并删除碎片,碎片格式由 npm run check:changelog-integrity 门控。由于两个 PR 永远不会触碰同一个文件,CHANGELOG 合并冲突在结构上被消除——当前 changelog.d/ 下已积累数百个碎片文件,直观体现了这条发布轨道的高吞吐状态。

小结

OmniRoute 的路线图是一次"先加固、再冻结、后拆分"的系统性演进:3.8.50–3.8.54 用注册表化、模块拆分与 CI 整合消除结构风险,3.8.55–3.8.59 用 characterization 测试、性能基线与安全审计完成验证,3.9.0 以 stable/v3 建立 LTS 锚点保住 latest 用户,4.0 才在 develop 上完成 core/SDK/模块/市场化的最终拆分。对读者而言,最实用的两条信息是:普通功能与修复在 3.8.55 之前全部指向活跃的 release/v3.8.x,之后功能 PR 会被挂起等待 v4 通道;而 latest 在整个 v4 周期内始终停在 v3 LTS,升级 v4 需要显式订阅 next / 4.0.0-nightly.* 通道。