企业官网建设流程全解析

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

【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/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/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-file1-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接口的产品语义不被污染。

【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix