Motrix 贡献者指南开发环境搭建、分层架构边界与提交前验证门禁【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文以 Motrix 仓库的 CONTRIBUTING.md 为主体完整还原参与该开源下载管理器的全流程从开发环境搭建Git、Node.js 22、pnpm 版本锁定、独立用户数据目录的 dev 运行时到 renderer/main/server/core/shared 分层架构与传输协议约定再到提交前必须通过的check:boundaries、lint、类型检查等验证门禁与分支/提交/PR 规范。读完后你可以独立完成一次符合项目标准的贡献提交并理解其架构约束在源码层面如何被自动检查强制落地。选择正确的贡献渠道Motrix 接受代码、测试、文档、翻译、issue 报告和设计反馈等多种形式的贡献。在提交之前项目明确要求创建新报告前先检索已打开和已关闭的 issues避免重复可复现的 bug 和聚焦的功能请求使用仓库的 issue 表单支持类问题、使用指导以及尚未成熟的想法应放到 GitHub Discussions 而非 issue重大功能、架构变更、新依赖和破坏性变更需要先讨论再投入实现每个 issue 和 PR 只聚焦一个问题或一项能力。参与本项目受 行为准则 约束疑似安全漏洞必须按 安全策略 私下报告严禁在公开的 issue、讨论或 PR 中披露。准备开发环境工具链与版本锁定开发需要 Git、Node.js 22 或更高版本以及package.json中packageManager字段声明的 pnpm 版本。查看 package.json 可知当前锁定为pnpm11.22.0建议通过corepack或pnpm self-update对齐该版本避免锁文件协议不一致导致的安装差异。克隆、安装与启动没有写权限时先 Fork 仓库然后克隆自己的 fork 并安装依赖git clone https://github.com/your-account/Motrix.git cd Motrix pnpm install pnpm startpnpm start并非直接拉起 Electron。查看 package.json 中的脚本链可以发现start前会执行prestart即ensure:electron-runtime加 scripts/ensure-native-abi.mjs针对 electron 目标重建better-sqlite3等原生模块的 ABI随后由 scripts/dev.mjs 接管整个开发运行时。从 dev.mjs 的头部注释可以看到它的职责先通过pnpm run build:builtin把内置插件打包到dist/builtin-plugins源码注释明确指出缺失该目录时 bilibili/youtube 链接会退化为普通 HTTP 下载在固定端口默认 5173可用VITE_DEV_PORT覆盖启动 renderer 的 Vite dev server以 watch 模式构建 main 和 preload 两份 bundle两者首次产出后才注入VITE_DEV_SERVER_URL启动 Electron后续 main/preload 重新构建后自动重启 Electronrenderer 侧热更新由 Vite HMR 完成无需重启。用户数据目录隔离dev 不污染正式版数据文档说明pnpm start默认使用独立的用户数据目录通常是Motrix-dev。这一行为的确切实现在 src/main/platform/services.tsconst isDev !app.isPackaged const userDataOverride process.env.MOTRIX_USER_DATA const defaultUserDataDir app.getPath(userData) const userDataDir userDataOverride || (isDev ? ${defaultUserDataDir}-dev : defaultUserDataDir)即开发态下目录在默认 userData 路径后追加-dev后缀。若要指定其他目录在运行pnpm start前设置MOTRIX_USER_DATA为绝对路径即可src/main/platform/services.test.ts 中的测试证实了相关契约MOTRIX_USER_DATA在开发态优先于-dev默认值空字符串值会被忽略回落到默认行为打包后非开发态的MOTRIX_USER_DATA同样生效相对路径会在创建目录前被直接拒绝抛出MOTRIX_USER_DATA must be an absolute path。此外dev 模式还会把extra资源目录解析为项目根下的extra/如 extra/aria2.conf打包后则来自process.resourcesPath/extra。分支策略与分支命名开发分支必须基于最新的main创建PR 也以main为目标遗留的master分支只保留 v1 代码库且已冻结不要向它提交任何新变更分支名格式为type/snake_case_topic_YYYYMMDD有对应 issue 时可在主题前加 issue 编号例如fix/1970_conduct_links_20260826。理解分层架构Motrix Turbo 在两个应用外壳Electron 桌面应用与 Node/Web 服务器背后共享一个宿主无关host-neutral的产品核心同一套 renderer 代码在两种宿主中运行。这种分离保证产品行为可复用、Electron 关注点不会泄漏进服务端并允许下载引擎在稳定适配器之后被替换。各层职责与依赖边界目录职责依赖边界src/renderer/共享的 Electron/浏览器用户界面只导入shared/和 renderer 本地模块产品行为统一经renderer/lib/transport访问src/preload/狭窄的 Electron context bridge使用 Electron 和src/shared/中的纯协议值/类型不含产品行为src/main/Electron 外壳、IPC、窗口、菜单与系统集成可组合src/core/、src/shared/和 Electron 特定适配器src/server/Node/Docker 外壳、HTTP/WebSocket 端点与服务端平台集成可组合src/core/、src/shared/与服务端库禁止导入 Electron 或src/main/src/core/宿主无关的应用服务、领域行为、引擎编排与插件策略可用src/shared/和宿主无关库禁止导入任一应用外壳src/shared/跨层 schema、协议常量、类型、locale 数据与纯工具不得包含 I/O、定时器、网络访问、Electron API 或 Node 特定 APIpackages/native-host/供浏览器扩展配对接入的独立 Rust native-messaging 宿主通过已发布的 bridge 契约通信不依赖系统 Node.js 或 Electronsrc/test-utils/仅供测试的 fixtures 与 helpers严禁被生产代码导入这套边界在仓库目录结构中可以一一对应例如src/server/下是 Fastify 路由与 src/server/http/、src/server/bridge/ 等服务端实现而src/core/下则是 download、engine、plugin、session 等宿主无关领域模块。传输与协议流renderer 在两种宿主下使用同一套 command、query、event 契约Electron: renderer - ElectronTransport - preload - main IPC - core Browser: renderer - HttpWsTransport - server RPC/events - core从源码结构看这个契约确实被物理落实传输层实现在 src/renderer/lib/transport/electron.ts与http-ws.ts分别对应两条链路renderer 功能代码只应经由该模块访问产品行为直接访问window.motrix仅限于 Electron 传输层和窄范围的平台适配器通道名与 payload 契约集中在 src/shared/protocol/commands.ts、queries.ts、events.ts及bridge.ts应使用Commands、Queries、Events及其Bridge*常量而非裸通道字符串。引擎、Bridge 与插件边界产品级代码面向 src/core/engine/engine-adapter.ts 中定义的EngineAdapter接口。从源码可以看到该接口刻意保持“引擎中立”例如AddTorrentParams中注释说明 16 位十六进制 GID、1-based 文件索引、checkIntegrity语义等均由具体 aria2 适配器负责翻译。aria2 RPC 类型与转换逻辑留在具体 aria2 适配器内而引擎生命周期由 src/core/engine/engine-supervisor.ts 中的EngineSupervisor独占管理。MDXP 协议基于 HTTP 与 WebSocket 上的 JSON-RPC 2.0。motrix/mdxp包见 package.json 依赖motrix/mdxp^0.5.0是 wire schema、方法常量、错误码与连接行为的唯一事实来源不得在本地重复实现这些契约。宿主无关的插件状态、策略、安装、能力与沙箱编排位于 src/core/plugin/Electron 与 Node/Docker 的接线分别在 src/main/plugin/ 和 src/server/plugin/。插件 guest 代码在独立的 QuickJS worker 中运行对应quickjs-emscripten依赖只能通过类型化能力桥typed capability bridge触达宿主行为新增宿主特定能力时必须在两个能力宿主中都实现并测试。边界检查的自动化落地文档要求任何导入或层职责变化时都运行pnpm run check:boundaries。该脚本对应 scripts/check-boundaries.mjs其规则表L4-L52正是上述架构边界的机械化表达例如core must not import electronsrc/core/内禁止from electroncore must not import fastifysrc/core/内禁止 fastify 导入shared must not use Node-specific APIs or globalssrc/shared/内禁止node:导入、动态import(node:...)、process.与NodeJS.命名空间renderer must not import core or mainsrc/renderer/内禁止直接导入 core/main 层server must not import electron、server must not import src/main。脚本通过grep -rnE逐条检查支持按文件白名单豁免任一条失败即以非零码退出。文档同时提醒自动化检查只是基线不能替代对依赖方向的人工审查。遵循实现规范代码与文件代码、注释、标识符、文件名、commit message 与 PR 标题一律使用英文JavaScript/TypeScript/TSX/样式文件使用kebab-case命名与仓库现状一致如 engine-supervisor.ts、http-ws.ts类型专用导入使用import typeNode.js 内建模块使用node:前缀优先使用已配置的 alias 而非深层相对导入但需确认该 alias 在目标运行时可用行为变更必须伴随新增或更新测试生产代码不得依赖测试 helper 或生成的构建产物。用户可见文本与国际化所有用户可见的应用与运维文本必须走既有 i18next 资源仓库依赖i18next与react-i18next禁止硬编码界面字符串新增或变更翻译 key 时必须更新每一个已注册 locale且各 locale 的占位符集合必须完全一致。从 src/shared/locales/ 可见当前注册的 locale 为en-US.json、zh-CN.json与zh-TW.json三个编辑英文/简体中文文档对中的一份时同一变更中必须同步另一份保持标题、命令、路径与示例对齐同时允许各版本使用地道表达禁止提交凭据、私有 URL、个人路径、私有计划、本地生成的状态或无关变更。提交信息使用 Conventional Commits 格式type(optional-scope): imperative summary允许的 type 为feat、fix、refactor、perf、test、docs、chore、ci、style。summary 用小写开头、结尾不加句号、控制在 72 字符以内动机不明显时补充 body适用时添加BREAKING CHANGE:footer。验证门禁每次提交前必须运行以下三项强制门禁pnpm run check:boundaries pnpm run lint pnpm exec tsc --noEmit其中lint对应 package.json 的biome check .配套lint:fix、format脚本test对应vitest runtest:e2e对应playwright test。然后按变更类型运行匹配的检查行为或逻辑变更运行聚焦的 Vitest 测试跨切面大范围改动运行pnpm test覆盖浏览器或 Electron 用户流程pnpm test:e2elocale 资源或国际化行为pnpm run check:i18n实现为 scripts/check-i18n.mjs新增或重命名文件pnpm run check:file-names对应 scripts/check-file-names.mjs插件 manifest 契约pnpm run check:schema-parity依赖、打包资产或 license 元数据pnpm run check:third-party-noticesnative-host Rust 代码运行下面一组 cargo 命令。native-host 的验证命令针对 packages/native-host/Cargo.tomlcargo fmt --manifest-path packages/native-host/Cargo.toml --all -- --check cargo clippy --manifest-path packages/native-host/Cargo.toml --all-targets --locked -- -D warnings cargo test --manifest-path packages/native-host/Cargo.toml --locked --all-targets-D warnings表示 clippy 警告即失败--locked保证不漂移Cargo.lock。最后审查最终 diff、运行git diff --check并在 PR 中如实记录执行过的命令与结果不得压制失败或丢弃命令退出码。提交 Pull Request目标分支为main关联相关 issue同时说明问题本身与所选方案完整填写 PR 模板包含确切的验证命令、环境与结果可见界面变更必须附截图或录屏生成文件与依赖变更严格限制在 PR 所需范围内以追加 commit 的方式回应 review 意见维护者合并时通常会对 feature PR 做 squash。许可证与第三方声明贡献以仓库的 MIT License 被接受第三方资产可能有不同条款记录在 THIRD_PARTY_NOTICES.md 中对应 THIRD_PARTY_LICENSES/ 下维护的各组件许可文本。涉及依赖或许可元数据变更时记得运行pnpm run check:third-party-notices门禁保持其同步。【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Motrix 贡献者指南：开发环境搭建、分层架构边界与提交前验证门禁
Motrix 贡献者指南开发环境搭建、分层架构边界与提交前验证门禁【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文以 Motrix 仓库的 CONTRIBUTING.md 为主体完整还原参与该开源下载管理器的全流程从开发环境搭建Git、Node.js 22、pnpm 版本锁定、独立用户数据目录的 dev 运行时到 renderer/main/server/core/shared 分层架构与传输协议约定再到提交前必须通过的check:boundaries、lint、类型检查等验证门禁与分支/提交/PR 规范。读完后你可以独立完成一次符合项目标准的贡献提交并理解其架构约束在源码层面如何被自动检查强制落地。选择正确的贡献渠道Motrix 接受代码、测试、文档、翻译、issue 报告和设计反馈等多种形式的贡献。在提交之前项目明确要求创建新报告前先检索已打开和已关闭的 issues避免重复可复现的 bug 和聚焦的功能请求使用仓库的 issue 表单支持类问题、使用指导以及尚未成熟的想法应放到 GitHub Discussions 而非 issue重大功能、架构变更、新依赖和破坏性变更需要先讨论再投入实现每个 issue 和 PR 只聚焦一个问题或一项能力。参与本项目受 行为准则 约束疑似安全漏洞必须按 安全策略 私下报告严禁在公开的 issue、讨论或 PR 中披露。准备开发环境工具链与版本锁定开发需要 Git、Node.js 22 或更高版本以及package.json中packageManager字段声明的 pnpm 版本。查看 package.json 可知当前锁定为pnpm11.22.0建议通过corepack或pnpm self-update对齐该版本避免锁文件协议不一致导致的安装差异。克隆、安装与启动没有写权限时先 Fork 仓库然后克隆自己的 fork 并安装依赖git clone https://github.com/your-account/Motrix.git cd Motrix pnpm install pnpm startpnpm start并非直接拉起 Electron。查看 package.json 中的脚本链可以发现start前会执行prestart即ensure:electron-runtime加 scripts/ensure-native-abi.mjs针对 electron 目标重建better-sqlite3等原生模块的 ABI随后由 scripts/dev.mjs 接管整个开发运行时。从 dev.mjs 的头部注释可以看到它的职责先通过pnpm run build:builtin把内置插件打包到dist/builtin-plugins源码注释明确指出缺失该目录时 bilibili/youtube 链接会退化为普通 HTTP 下载在固定端口默认 5173可用VITE_DEV_PORT覆盖启动 renderer 的 Vite dev server以 watch 模式构建 main 和 preload 两份 bundle两者首次产出后才注入VITE_DEV_SERVER_URL启动 Electron后续 main/preload 重新构建后自动重启 Electronrenderer 侧热更新由 Vite HMR 完成无需重启。用户数据目录隔离dev 不污染正式版数据文档说明pnpm start默认使用独立的用户数据目录通常是Motrix-dev。这一行为的确切实现在 src/main/platform/services.tsconst isDev !app.isPackaged const userDataOverride process.env.MOTRIX_USER_DATA const defaultUserDataDir app.getPath(userData) const userDataDir userDataOverride || (isDev ? ${defaultUserDataDir}-dev : defaultUserDataDir)即开发态下目录在默认 userData 路径后追加-dev后缀。若要指定其他目录在运行pnpm start前设置MOTRIX_USER_DATA为绝对路径即可src/main/platform/services.test.ts 中的测试证实了相关契约MOTRIX_USER_DATA在开发态优先于-dev默认值空字符串值会被忽略回落到默认行为打包后非开发态的MOTRIX_USER_DATA同样生效相对路径会在创建目录前被直接拒绝抛出MOTRIX_USER_DATA must be an absolute path。此外dev 模式还会把extra资源目录解析为项目根下的extra/如 extra/aria2.conf打包后则来自process.resourcesPath/extra。分支策略与分支命名开发分支必须基于最新的main创建PR 也以main为目标遗留的master分支只保留 v1 代码库且已冻结不要向它提交任何新变更分支名格式为type/snake_case_topic_YYYYMMDD有对应 issue 时可在主题前加 issue 编号例如fix/1970_conduct_links_20260826。理解分层架构Motrix Turbo 在两个应用外壳Electron 桌面应用与 Node/Web 服务器背后共享一个宿主无关host-neutral的产品核心同一套 renderer 代码在两种宿主中运行。这种分离保证产品行为可复用、Electron 关注点不会泄漏进服务端并允许下载引擎在稳定适配器之后被替换。各层职责与依赖边界目录职责依赖边界src/renderer/共享的 Electron/浏览器用户界面只导入shared/和 renderer 本地模块产品行为统一经renderer/lib/transport访问src/preload/狭窄的 Electron context bridge使用 Electron 和src/shared/中的纯协议值/类型不含产品行为src/main/Electron 外壳、IPC、窗口、菜单与系统集成可组合src/core/、src/shared/和 Electron 特定适配器src/server/Node/Docker 外壳、HTTP/WebSocket 端点与服务端平台集成可组合src/core/、src/shared/与服务端库禁止导入 Electron 或src/main/src/core/宿主无关的应用服务、领域行为、引擎编排与插件策略可用src/shared/和宿主无关库禁止导入任一应用外壳src/shared/跨层 schema、协议常量、类型、locale 数据与纯工具不得包含 I/O、定时器、网络访问、Electron API 或 Node 特定 APIpackages/native-host/供浏览器扩展配对接入的独立 Rust native-messaging 宿主通过已发布的 bridge 契约通信不依赖系统 Node.js 或 Electronsrc/test-utils/仅供测试的 fixtures 与 helpers严禁被生产代码导入这套边界在仓库目录结构中可以一一对应例如src/server/下是 Fastify 路由与 src/server/http/、src/server/bridge/ 等服务端实现而src/core/下则是 download、engine、plugin、session 等宿主无关领域模块。传输与协议流renderer 在两种宿主下使用同一套 command、query、event 契约Electron: renderer - ElectronTransport - preload - main IPC - core Browser: renderer - HttpWsTransport - server RPC/events - core从源码结构看这个契约确实被物理落实传输层实现在 src/renderer/lib/transport/electron.ts与http-ws.ts分别对应两条链路renderer 功能代码只应经由该模块访问产品行为直接访问window.motrix仅限于 Electron 传输层和窄范围的平台适配器通道名与 payload 契约集中在 src/shared/protocol/commands.ts、queries.ts、events.ts及bridge.ts应使用Commands、Queries、Events及其Bridge*常量而非裸通道字符串。引擎、Bridge 与插件边界产品级代码面向 src/core/engine/engine-adapter.ts 中定义的EngineAdapter接口。从源码可以看到该接口刻意保持“引擎中立”例如AddTorrentParams中注释说明 16 位十六进制 GID、1-based 文件索引、checkIntegrity语义等均由具体 aria2 适配器负责翻译。aria2 RPC 类型与转换逻辑留在具体 aria2 适配器内而引擎生命周期由 src/core/engine/engine-supervisor.ts 中的EngineSupervisor独占管理。MDXP 协议基于 HTTP 与 WebSocket 上的 JSON-RPC 2.0。motrix/mdxp包见 package.json 依赖motrix/mdxp^0.5.0是 wire schema、方法常量、错误码与连接行为的唯一事实来源不得在本地重复实现这些契约。宿主无关的插件状态、策略、安装、能力与沙箱编排位于 src/core/plugin/Electron 与 Node/Docker 的接线分别在 src/main/plugin/ 和 src/server/plugin/。插件 guest 代码在独立的 QuickJS worker 中运行对应quickjs-emscripten依赖只能通过类型化能力桥typed capability bridge触达宿主行为新增宿主特定能力时必须在两个能力宿主中都实现并测试。边界检查的自动化落地文档要求任何导入或层职责变化时都运行pnpm run check:boundaries。该脚本对应 scripts/check-boundaries.mjs其规则表L4-L52正是上述架构边界的机械化表达例如core must not import electronsrc/core/内禁止from electroncore must not import fastifysrc/core/内禁止 fastify 导入shared must not use Node-specific APIs or globalssrc/shared/内禁止node:导入、动态import(node:...)、process.与NodeJS.命名空间renderer must not import core or mainsrc/renderer/内禁止直接导入 core/main 层server must not import electron、server must not import src/main。脚本通过grep -rnE逐条检查支持按文件白名单豁免任一条失败即以非零码退出。文档同时提醒自动化检查只是基线不能替代对依赖方向的人工审查。遵循实现规范代码与文件代码、注释、标识符、文件名、commit message 与 PR 标题一律使用英文JavaScript/TypeScript/TSX/样式文件使用kebab-case命名与仓库现状一致如 engine-supervisor.ts、http-ws.ts类型专用导入使用import typeNode.js 内建模块使用node:前缀优先使用已配置的 alias 而非深层相对导入但需确认该 alias 在目标运行时可用行为变更必须伴随新增或更新测试生产代码不得依赖测试 helper 或生成的构建产物。用户可见文本与国际化所有用户可见的应用与运维文本必须走既有 i18next 资源仓库依赖i18next与react-i18next禁止硬编码界面字符串新增或变更翻译 key 时必须更新每一个已注册 locale且各 locale 的占位符集合必须完全一致。从 src/shared/locales/ 可见当前注册的 locale 为en-US.json、zh-CN.json与zh-TW.json三个编辑英文/简体中文文档对中的一份时同一变更中必须同步另一份保持标题、命令、路径与示例对齐同时允许各版本使用地道表达禁止提交凭据、私有 URL、个人路径、私有计划、本地生成的状态或无关变更。提交信息使用 Conventional Commits 格式type(optional-scope): imperative summary允许的 type 为feat、fix、refactor、perf、test、docs、chore、ci、style。summary 用小写开头、结尾不加句号、控制在 72 字符以内动机不明显时补充 body适用时添加BREAKING CHANGE:footer。验证门禁每次提交前必须运行以下三项强制门禁pnpm run check:boundaries pnpm run lint pnpm exec tsc --noEmit其中lint对应 package.json 的biome check .配套lint:fix、format脚本test对应vitest runtest:e2e对应playwright test。然后按变更类型运行匹配的检查行为或逻辑变更运行聚焦的 Vitest 测试跨切面大范围改动运行pnpm test覆盖浏览器或 Electron 用户流程pnpm test:e2elocale 资源或国际化行为pnpm run check:i18n实现为 scripts/check-i18n.mjs新增或重命名文件pnpm run check:file-names对应 scripts/check-file-names.mjs插件 manifest 契约pnpm run check:schema-parity依赖、打包资产或 license 元数据pnpm run check:third-party-noticesnative-host Rust 代码运行下面一组 cargo 命令。native-host 的验证命令针对 packages/native-host/Cargo.tomlcargo fmt --manifest-path packages/native-host/Cargo.toml --all -- --check cargo clippy --manifest-path packages/native-host/Cargo.toml --all-targets --locked -- -D warnings cargo test --manifest-path packages/native-host/Cargo.toml --locked --all-targets-D warnings表示 clippy 警告即失败--locked保证不漂移Cargo.lock。最后审查最终 diff、运行git diff --check并在 PR 中如实记录执行过的命令与结果不得压制失败或丢弃命令退出码。提交 Pull Request目标分支为main关联相关 issue同时说明问题本身与所选方案完整填写 PR 模板包含确切的验证命令、环境与结果可见界面变更必须附截图或录屏生成文件与依赖变更严格限制在 PR 所需范围内以追加 commit 的方式回应 review 意见维护者合并时通常会对 feature PR 做 squash。许可证与第三方声明贡献以仓库的 MIT License 被接受第三方资产可能有不同条款记录在 THIRD_PARTY_NOTICES.md 中对应 THIRD_PARTY_LICENSES/ 下维护的各组件许可文本。涉及依赖或许可元数据变更时记得运行pnpm run check:third-party-notices门禁保持其同步。【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考