Motrix 架构解析：宿主无关的产品核心、双传输契约与引擎适配器边界

本文基于 Motrix 仓库中的架构边界规则文档（.claude/rules/architecture.md），结合仓库源码实现，讲解这套下载管理器如何在 Electron 桌面端与 Node/Docker 服务端两种宿主形态之间维持同一套产品核心：包括分层依赖矩阵、机器可执行的硬性边界检查、面向渲染层的 ElectronTransport / HttpWsTransport 双传输契约，以及把 aria2 隔离在 EngineAdapter 边界背后的引擎适配设计。读完后，你将理解 Motrix「核心可替换、宿主可互换」的工程约束是如何在目录结构、协议常量和自动化脚本三个层面落地的。

设计目标：宿主无关的产品核心

架构文档开宗明义：Motrix 把产品核心（任务管理、设置、插件、通知、统计等）保持为宿主无关（host-neutral），使其既能运行在 Electron 外壳后面，也能运行在 Node 服务端后面，并且在未来能够被新的下载引擎替换。这一目标决定了整份规则文档的四条主线：

1. 一套分层依赖矩阵（Layer Matrix），规定每个目录能依赖什么；
2. 一组硬性边界（Hard Boundaries），禁止核心层触碰任何宿主 API；
3. 一份双传输契约（Dual Transport Contract），让同一份渲染层代码在桌面与浏览器两种环境下工作；
4. 一个引擎适配器边界（Engine Adapter），让产品代码从不直接面对 aria2 的 RPC 类型。

分层依赖矩阵：六个目录各司其职

架构文档给出的分层矩阵如下，它规定了每个顶层目录的职责与允许的依赖方向：

目录	角色	允许的依赖
src/renderer/	Electron/浏览器前端	@shared/、renderer 本地模块
src/core/	宿主无关的产品核心	@shared/、宿主无关的 Node/外部库
src/main/	Electron 外壳与 IPC	@core/、@shared/、Electron
src/preload/	Electron 桥接层	纯 @shared/ 协议值/类型、Electron
src/server/	Node/Docker 外壳	@core/、@shared/、服务端库
src/shared/	跨层契约	仅纯 schema、常量、数据与工具

依赖方向呈典型的「洋葱」形状：src/main/ 与 src/server/ 是两个平行的宿主外壳，各自向内依赖 src/core/，而 src/core/ 只向下依赖 src/shared/。渲染层（src/renderer/）则被完全隔离在外壳之外——它不能看到 core、main 或 server，只能通过传输抽象与宿主通信。

仓库中各目录的实际代码印证了这一划分。以服务端入口 src/server/index.ts 为例，它直接导入 @core/engine/aria2/*、EngineSupervisor、EventBus 等核心模块来组装无 Electron 的应用实例；而桌面端则由 src/main/ 下的 IPC 处理器完成同样的组装。两条装配路径共享同一个核心，这正是「宿主无关」的直观体现。

硬性边界与自动化检查 check:boundaries

架构文档列出的硬性边界如下：

• src/core/ 绝不导入 Electron，也绝不导入 src/main/；
• src/renderer/ 绝不导入 src/core/、src/main/ 或 src/server/；
• src/server/ 绝不导入 Electron 或 src/main/；
• src/shared/ 绝不导入任何应用层，且不含 IO、定时器、网络访问、Electron API 或 Node 专用 API；
• 生产代码绝不导入 src/test-utils/；生成的内置插件产物绝不作为源码使用。

文档同时提醒：pnpm run check:boundaries 只是自动化基线，并非所有例外都是机器强制的，改动的 import 还必须对照矩阵进行人工审查。这一点值得展开，因为它决定了阅读边界规则时不能只看脚本。

机器强制的规则集

pnpm run check:boundaries 由 scripts/check-boundaries.mjs 实现（对应 package.json 中的 check:boundaries 脚本）。它的实现思路很朴素：对每个规则目录运行一次 grep -rnE 正则扫描（仅扫描 .ts/.tsx），无匹配或匹配全部落在白名单文件内即 [PASS]，否则打印违规行并以非零码退出。当前机器强制的规则集共 9 条：

1. core 不得导入 electron：扫描 src/core/ 中 from 'electron'；
2. core 不得导入 fastify：扫描 src/core/ 中 @?fastify——防止宿主服务端的 Web 框架渗入核心层；
3. shared 不得使用 Node 专用 API 或全局对象：同时拦截 node: 前缀的 import/require、process. 与 NodeJS. 命名空间；
4. renderer 不得导入 core 或 main：扫描 src/renderer/ 中任何含 core/ 或 main/ 的导入路径；
5. server 不得导入 electron：扫描 src/server/ 中 from 'electron'；
6. server 不得导入 src/main：扫描 @main/ 或指向 src/main/ 的导入；
7. 生产源码不得引用部署暂存契约：拦截 electron-runtime-dependencies.json、server-runtime-dependencies.json、.motrix-package-stage.json、dist/(electron|server)-app 等打包期文件名——保证运行时源码不耦合发布流程；
8. add-task UI 不得直接导入传输层或协议命令：src/renderer/components/add-task/ 内禁止导入 @renderer/lib/transport 或 @shared/protocol/commands，仅豁免 use-external-hydration.ts、drop-zone.tsx、add-task-form.tsx 三个 IPC 感知文件——这是把「命令调用」收敛到少数入口的细粒度治理规则；
9. web-services 不得引用 Electron-only 命令符号：在 src/renderer/platform/web-services.ts 中拦截 PickSaveDir、CloseCurrentWindow、ResizeWindow、ShowMainWindow，防止 Web 传输路径意外依赖只存在于桌面端的窗口操作命令。

脚本还支持每规则的 except 文件白名单（filterOutExceptions 按路径后缀过滤匹配行），这正是文档所说「并非所有例外都机器强制」的另一面：机器负责兜底，矩阵负责裁决。

另外，第 7 条规则说明边界治理已经延伸到「源码与构建系统之间」：scripts/ 下存在 electron-runtime-dependencies.json、server-runtime-dependencies.json、stage-electron-app.mjs、stage-server-app.mjs 等构建期文件，而生产源码被禁止反向引用它们，确保两种宿主各自的打包暂存物不会泄漏进共享代码。

双传输契约：一套渲染层，两种宿主

架构文档给出的传输契约拓扑是：

Electron: renderer -> ElectronTransport -> preload -> main IPC -> core
Browser:  renderer -> HttpWsTransport -> server RPC/events -> core

关键点在于：同一份面向渲染层的传输契约同时服务于两个宿主。事件从 core 发出后，经由选定的外壳和传输原路返回，因此渲染层状态不能依赖任何宿主专属通道。

传输选择的编译期分叉

契约的落点在 src/renderer/lib/transport/index.ts，全部实现只有 10 行：

function createTransport(): Transport {
  if (__MOTRIX_TARGET__ === 'electron') return new ElectronTransport()
  return new HttpWsTransport(globalThis.location?.origin ?? '')
}
export const transport: Transport = createTransport()

__MOTRIX_TARGET__ 是一个构建期注入的全局常量，在 src/renderer/env.d.ts 中声明为 'electron' | 'web'。也就是说，Electron 与 Web 两个构建产物在编译期就各自固化了传输实现，运行期不存在动态探测——这与仓库中 vite.electron.config.ts / vite.renderer.web.config.ts 等多入口 Vite 配置相一致。

Transport 接口

传输抽象定义在 src/renderer/lib/transport/types.ts，核心方法只有四个：

export interface Transport {
  invoke(channel: AnyChannel, ...args: unknown[]): Promise<unknown>
  on(channel: EventChannel, cb: EventListener): void
  off(channel: EventChannel, cb: EventListener): void
  onConnectionChange?(cb: TransportConnectionListener): () => void
  platform: NodeJS.Platform | 'web'
}

其中 onConnectionChange 被刻意设计为可选：Electron IPC 没有渲染层可感知的连接生命周期，而 Web 传输（HTTP 请求 + WebSocket 事件流）需要暴露 connecting/connected/disconnected 状态机供 UI 处理断线重连。platform 字段则让同一份功能代码能在行为分叉点（例如保存目录选择只存在于桌面端）做受控的宿主能力判断。

命令与事件的命名空间

契约还规定：所有通道名一律来自 src/shared/protocol/，使用 Commands、Queries、Events 及其 Bridge* 对应物，而不是裸字符串。这在 src/shared/protocol/commands.ts 中直接可见——Commands 是一个字面量常量表，例如 CreateDownload: 'command:createDownload'、RetryTasks: 'command:retryTasks' 等，同目录下还有 queries.ts、events.ts、bridge.ts（面向浏览器扩展桥接的 Bridge* 命名空间）以及配套的 handler-types.ts 类型约束。

把通道名收口到 src/shared/ 还有一个结构性收益：Transport 的参数类型 AnyChannel、EventChannel 都是从 @shared/protocol/ 导出的联合类型，因此渲染层如果引用了一个不存在的通道名，类型系统会直接报错；而渲染层被边界规则禁止导入 @core/，所以 @shared/ 实际上就是渲染层与两个外壳之间唯一的契约面。这也解释了文档对 preload 的限制——它只能承载纯 @shared/ 协议值/类型与 Electron，不能成为第二套契约面。

文档中「功能代码停留在这些抽象之后」在检查脚本里同样有对应物：第 8、9 条规则分别管住 add-task 表单与 Web 服务适配层，防止功能组件绕过 transport.invoke(Commands.X) 直接摸底层通道或 Electron-only 符号。

引擎适配器边界：产品代码不碰 aria2

架构文档的最后一条主线：产品级代码一律面向 src/core/engine/engine-adapter.ts 中定义的 EngineAdapter 接口编程，绝不直接引用 aria2 的 RPC 类型；具体引擎在适配器边界处完成翻译；EngineSupervisor 是引擎启动、停止与重启生命周期的唯一所有者。

EngineAdapter：引擎中立的接口面

EngineAdapter 是约 900 行接口定义中最重要的部分，覆盖了下载管理所需的全部能力：连接管理（connect/disconnect/getCapabilities/getFeatureReport）、任务操作（createDownload、pauseTask、resumeTask、removeTask、forceRemoveTask、changeOption、changePosition）、状态查询（getTaskStatus、getTaskFiles、getTaskPieces、getTaskPeers、getGlobalStats）、历史与恢复（getHistoryCount、searchHistory、requeueFromHistory、exportSession、listActiveAndWaiting、listStopped），以及三个 aria2.onXxx 语义的订阅方法。

这个接口体现「引擎中立」的方式很有代表性：

• 参数形状是产品语义而非引擎语义。例如 CreateDownloadParams 暴露的是 connections、resumePolicy（none | checkpoint | sequential-prefix）、prioritizePreviewPieces 等产品策略字段，注释明确写着「具体的适配器负责把它翻译成目标引擎的选项」；而 aria2 特有的 select-file 1-based 索引换算也被明确标注为「create 路径在调用前完成换算，适配器原样序列化给引擎」。
• 能力探测代替硬编码。getFeatureReport() 返回连接时探测到的 EngineFeatureReport（版本、hasBtSeedUnverified、hasSqlitePersistence 等运行时能力标志），且约定 connect() 之前返回保守默认值——上层据此降级而非报错。
• 错误语义显式化。如 getHistoryCount 明确说明引擎需以 SQLite3 持久化模式启动，否则原始 RPC 错误（"SQLite3 persistence is not enabled"）会原样抛出。

接口中仍有少量 aria2 语汇残留（如 removeDownloadResult、exportSession 的注释直接提到 aria2 input-file），这是当前唯一具体引擎为 aria2 的历史痕迹；但从接口整体结构看，文档声称的「可被未来引擎替换」是有具体支撑的——替换工作被收敛在 src/core/engine/aria2/ 目录内的一个适配器实现上。

EngineSupervisor：生命周期唯一所有者

EngineSupervisor 与具体适配器协作，集中承担引擎进程管理。从其源码常量可以看出监督策略：ENGINE_READY_TIMEOUT_MS = 15_000（引擎冷启动含进程拉起与 RPC 连接重试约 5 秒，15 秒是安全余量）、退避参数 BACKOFF_BASE = 1_000 / BACKOFF_MAX = 30_000 / MAX_RESTARTS = 5、HEALTH_CHECK_INTERVAL = 30_000、MAX_CONSECUTIVE_FAILURES = 3，以及一组 HOT_ENGINE_OPTIONS 映射表（把产品设置键映射到 aria2 的 max-concurrent-downloads、split、seed-ratio 等选项，用于热更新判断）。

Supervisor 还负责失败归因与恢复建议：它从 @shared/types/engine 导入 EngineFailureReason、EngineRecoveryAction、EngineRecoveryRecommendation 等类型，并通过 EventBus 把引擎故障事件（如 EngineFailurePayload）发布出去，交由 src/core/notifications/ 下的失败订阅者转成用户通知——这正是「宿主无关核心」内部事件流的一个缩影：无论引擎跑在 Electron 主进程还是 Docker 容器里，诊断与恢复逻辑都是同一份。

为什么这一层如此重要

把引擎隔离在适配器边界之后，与分层矩阵是互相咬合的：EngineAdapter 位于 src/core/，只依赖 @shared/ 中的类型；src/server/index.ts 与 Electron 宿主各自实例化 Aria2Adapter + EngineSupervisor，但产品层（任务恢复、限速、媒体分段下载等）看到的永远只是 EngineAdapter。于是「换引擎」不需要触碰渲染层契约，也不需要改变两个宿主的装配方式——这与文档开头的「remain replaceable by a future engine」形成了完整的证据链。

小结：边界如何在三层落地

Motrix 的这套架构约束可以在三个层面交叉验证：

• 目录与导入层：分层矩阵 + pnpm run check:boundaries 的 9 条 grep 规则（scripts/check-boundaries.mjs）+ 人工审查矩阵作为兜底；
• 渲染层契约：Transport 四方法接口、__MOTRIX_TARGET__ 编译期分叉、src/shared/protocol/ 通道常量表（src/shared/protocol/commands.ts 等）；
• 引擎边界：EngineAdapter 引擎中立接口（src/core/engine/engine-adapter.ts）+ EngineSupervisor 生命周期唯一所有权（src/core/engine/engine-supervisor.ts）。

对维护者而言，实操要点是：新增 import 前先对照分层矩阵判断合法性，再跑一遍 pnpm run check:boundaries 确认机器规则不报红；对渲染层新功能，一切命令/事件都走 transport.invoke(Commands.X) / transport.on(Events.X)；对引擎相关改动，把引擎特定逻辑压进 src/core/engine/aria2/ 适配器内部，保持 EngineAdapter 接口的产品语义不被污染。