Motrix 工程规范全解基于 CLAUDE.md 的双宿主架构边界、核心命令与 AI Agent 协作规则【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/MotrixMotrixMotrix Turbo是一个同时运行在 Electron 桌面端与 Node/Web 服务端的完整下载管理器。本文以仓库根目录的 CLAUDE.md 为骨架完整解读它定义的仓库定位、核心命令、架构边界与规则路由机制并结合 package.json、scripts/check-boundaries.mjs 与 src/shared/protocol/commands.ts 等源码证据说明这些规范是如何被脚本和类型契约落地成可执行、可验证的工程约束的。读完本文你将掌握 Motrix 的目录分层、双传输契约、提交质量门禁以及 AI Agent 在该仓库协作时的规则加载顺序。CLAUDE.md 在仓库中的定位CLAUDE.md 是 Motrix 的 AI Agent 权威指引文件开篇给出两条仓库级事实项目形态Motrix Turbo 是 Electron Node/Web 下载管理器。src/core/必须保持宿主中立host-neutral以便同一份产品核心既能被 Electron 壳复用也能被 Node 服务端壳独立替换。分支策略开发在main分支进行master是冻结的遗留分支对应旧版 Electron 22 / Vue 2 应用。所有分支创建与 PR 目标只能是main绝不能指向master。仓库中的 AGENTS.md 进一步说明Claude Code 规则是唯一的规范来源Codex 等其他 Agent 直接继承而不再维护第二份副本。它规定了 Agent 在检查或修改文件前必须依次读取CLAUDE.md所有不带pathsfrontmatter 的全局.claude/rules/*.md规则所有paths模式与待检查/修改文件相匹配的规则。冲突解决顺序为当前用户指令 AGENTS.mdCLAUDE.md 匹配的.claude/rules/*.md Agent 默认行为并要求更新 Claude 规范规则而不是重复维护指引。这种单一事实源 按路径按需加载的设计是本文后面规则路由一节的核心。核心命令一览CLAUDE.md 给出的命令表是仓库日常开发的入口这里完整继承并结合 package.json 的scripts字段补充实际执行内容命令用途实际执行内容来自 package.jsonpnpm startElectron 开发运行器node scripts/dev.mjs且prestart会先执行ensure:electron-runtime与ensure-native-abi.mjs electronpnpm start:server已构建的 Node/Web 服务端MOTRIX_SKIP_ELECTRON_REBUILD1 node dist/server/index.mjspnpm test全量 Vitest 套件vitest runpretest先跑ensure-native-abi.mjs nodepnpm exec vitest run test-path单测聚焦运行针对单个测试路径pnpm run lintBiome 全仓检查biome check .由biome.json限定范围pnpm exec tsc --noEmit类型检查TypeScript 编译期检查不产出文件pnpm build桌面端生产构建依次执行build:builtin、build:native-host、build:electron后者含 main/preload/worker/renderer 四个 vite 构建pnpm build:serverNode/Web 生产构建build:builtinbuild:legal server/worker/renderer-web 三个 vite 构建pnpm test:e2ePlaywright 端到端套件playwright testpretest:e2e先确保 Electron 运行时与 Electron ABICLAUDE.md 还强调两条执行纪律使用pnpm exec而不是npx。仓库锁定packageManager: pnpm11.22.0用 pnpm 调用可保证依赖解析与锁文件一致。权威提交门禁是 .claude/rules/commit-and-quality.md它规定了每次提交前必须通过的三项检查见下文提交质量门禁。从package.json的依赖表可以看到这套命令背后的技术栈规模Electron 43、React 19、Vite 8、Vitest 4、Playwright、Fastify、better-sqlite3、quickjs-emscripten插件沙箱、zod契约校验等pnpm build/pnpm build:server分别对应桌面与 Web 两条交付链路。架构边界四条硬性约束CLAUDE.md 的 Architecture Boundaries 一节是整个文档最核心的部分逐条列出四条不可违反的依赖方向src/core/绝不导入electron或src/main/src/renderer/绝不导入src/core/、src/main/或src/server/渲染层与后端通信必须经由renderer/lib/transport并使用共享协议常量src/shared/只包含纯跨层契约与描述性运行时数据不允许 IO、定时器、网络、Electron API 或任何 Node 特有 API一律使用src/shared/protocol/导出的Commands、Queries、Events及其Bridge*对应物禁止使用裸传输通道字符串。自动化边界检查check-boundaries.mjs这些约束并非仅靠自觉。scripts/check-boundaries.mjs 用一组grep -rnE规则做机器化兜底例如core must not import electron在src/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服务端壳与 Electron 主进程彻底隔离还有一条 UI 级规则src/renderer/components/add-task/组件不得直接导入renderer/lib/transport或shared/protocol/commands仅放行三个 IPC 感知文件use-external-hydration.ts、drop-zone.tsx、add-task-form.tsx把谁有权发起 IPC收敛到极少数入口。脚本对每条规则输出[PASS]/[FAIL]任一失败即以非零码退出。需要留意的是.claude/rules/architecture.md 明确指出该脚本只是自动化基线并非完整的架构证明——部分例外不是机器强制的改动导入时仍需对照规则矩阵人工审查。完整分层矩阵与双传输契约.claude/rules/architecture.md 在 CLAUDE.md 四条边界的基础上给出了更完整的分层矩阵目录角色允许的依赖src/renderer/Electron/浏览器前端shared/、渲染层本地模块src/core/宿主中立的产品核心shared/、宿主中立的 Node/外部库src/main/Electron 壳与 IPCcore/、shared/、Electronsrc/preload/Electron 桥纯shared/协议值/类型、Electronsrc/server/Node/Docker 壳core/、shared/、服务端库src/shared/跨层契约仅纯 schema、常量、数据与工具函数该规则文件还解释了同构前端 双宿主的关键机制——双传输契约Electron: renderer - ElectronTransport - preload - main IPC - core Browser: renderer - HttpWsTransport - server RPC/events - core在源码中可以逐一印证渲染层的 src/renderer/lib/transport/electron.ts 与 src/renderer/lib/transport/http-ws.ts 正是两条传输实现的落点src/server/下则有配套的 HTTP/WS 桥接模块。规则强调window.motrix的直接访问仅限于 Electron 传输实现与窄范围的平台适配器特性代码必须留在抽象之后事件通过所选择的壳与传输返回因此渲染层状态不能依赖任何宿主特定通道。协议常量禁止裸通道字符串第四条边界在 src/shared/protocol/commands.ts 中有直接体现——所有命令通道名集中定义为常量对象例如export const Commands { CreateDownload: command:createDownload, PauseTask: command:pauseTask, ResumeTask: command:resumeTask, RemoveTasks: command:removeTasks, UpdateSettings: command:updateSettings, RestartEngine: command:restartEngine, // ... }src/shared/protocol/目录下还有配套的queries.ts、events.ts、bridge.tsBridge*通道以及带测试的errors.ts、forwardable-events.ts、handler-types.ts。这种集中式通道表让 IPC 两端Electron 主进程与 HTTP/WS 服务端共享同一份词汇表任何新增命令都必须先进入契约层再被两个壳分别注册处理器。引擎适配器边界同一条架构规则还规定了产品层与下载引擎之间的隔离产品级代码一律面向 src/core/engine/engine-adapter.ts 中的EngineAdapter接口而不是直接依赖 aria2 RPC 类型具体引擎在适配器边界处做翻译。EngineSupervisor位于src/core/engine/是引擎启动、停止、重启生命周期的唯一持有者。这正是 CLAUDE.md 开头核心必须宿主中立、可被未来引擎独立替换这一设计意图在引擎层的延伸。提交质量门禁.claude/rules/commit-and-quality.md 是 CLAUDE.md 指定的权威提交门禁分为两部分。每次提交必跑三项检查失败必须修复后才能提交pnpm run check:boundaries pnpm run lint pnpm exec tsc --noEmit其中pnpm run lint即biome check .范围由biome.json约束与 CI 运行的是同一条命令——规则明确要求不要换成更窄的路径列表也不允许用管道等方式丢弃其退出码。暂存文件后还需检查git diff --staged并运行git diff --cached --check不得因 CI 任务非阻塞而掩盖失败。按变更类型附加的检查行为/逻辑变更pnpm exec vitest run test-path聚焦测试跨切面改动用pnpm test浏览器/Electron 用户流受影响流程有 E2E 覆盖时跑pnpm test:e2e国际化资源或 i18n 行为pnpm run check:i18n新增或重命名文件pnpm run check:file-names插件 manifest 契约pnpm run check:schema-parity依赖、打包资源或许可证元数据pnpm run check:third-party-notices原生宿主 Rustpackages/native-hostcargo fmt --check、cargo clippy -D warnings、cargo test --locked三件套打包/发布代码跑tests/scripts/下对应聚焦测试与验证脚本。只有针对已审查过的、可自动修复的问题才允许使用pnpm exec biome check --write .且之后必须重跑完整门禁。分支、提交与发布纪律CLAUDE.md 只给出开发在main、master已冻结的原则.claude/rules/git-workflow.md 把它展开为完整规范提交信息英文 Conventional Commits格式type(optional-scope): imperative summary允许类型feat/fix/refactor/perf/test/docs/chore/ci/style摘要小写、无句号、小于 72 字符必要时加 body 与BREAKING CHANGE:脚注不得自动添加 AI 署名或 co-author trailer。分支从当前main拉出命名type/snake_case_topic_YYYYMMDD可含 issue 号禁止直接推送或强推mainrebase 前只 rebase 私有特性分支到mainrebase 后用git push --force-with-lease更新自己的分支。PR保持聚焦标题遵循 Conventional Commits描述说明改了什么、为什么、如何验证默认 squash 合并仅当发布、热修或需要保留提交级历史时才用普通合并合并后删除分支。发布安全以仓库内 workflow 与脚本为发布权威——package.json使用严格 SemVer创建受保护的vpackage-version标签标签与包版本必须一致支持 stable 与 beta 两个渠道标签推送触发发布 workflow只有平台构建、隔离签名/收尾任务、签名检查、包验证、制品装配与更新产物校验全部通过后才能发布macOS 要求签名与公证Windows 在缺少 Authenticode 密钥时可显式以无签名收尾并在发布说明中披露。构建产物与原生 ABI 约束.claude/rules/electron-vite.md 补充了 CLAUDE.md 中pnpm build/pnpm build:server背后的硬性产物契约目标输出Electron maindist/main/index.cjspreloaddist/preload/preload.cjsQuickJS workerdist/core/plugin/host/quick-js-worker.cjsElectron rendererdist/renderer/Node server 与 CLIdist/server/index.mjs、dist/server/motrix-admin.mjs浏览器 rendererdist/renderer-web/由于package.json声明了type: modulemain、preload、worker 产物必须保持.cjs服务端产物保持.mjsmain字段当前为dist/main/index.cjs必须与 main 产物一致。此外该规则还约定pnpm 配置集中在pnpm-workspace.yaml保持nodeLinker: hoistedElectron 43 不依赖pnpm install自动拉取二进制本地流程必须先跑pnpm run ensure:electron-runtimebetter-sqlite3这类原生模块必须匹配活动 ABI——测试用 Node ABIElectron 与 E2E 用 Electron ABI由scripts/ensure-native-abi.mjs的prestart/pretest/pretest:e2e钩子保障服务端 Docker 镜像刻意不含 pnpm 与构建工具链禁止运行时本地重编原生模块。规则路由按需加载的 .claude/rules 体系CLAUDE.md 末尾的 Rule Routing 一节定义了规则加载机制没有pathsfrontmatter 的规则是全局规则带路径作用的规则只在其模式匹配到正在检查或修改的文件时才加载。路由表如下规则文件作用范围commit-and-quality.md必查项与按变更类型的验证git-workflow.md提交、分支、PR 与发布language-and-docs.md语言与公开/私有文档architecture.md分层边界与传输流electron-vite.md构建、打包、原生 ABI 与 pnpmcode-style.mdTypeScript、React、CSS 与文件命名renderer.md渲染层状态、组件、表单与传输panel-layout.md视口高度与滚动布局i18n.md语言目录与用户可见文案domain-model.md共享领域类型、校验与错误plugins.md插件沙箱、能力与内置插件plugin-registry.md注册表兼容性与安装完整性bridge.mdMDXP 配对、分发与传输从 frontmatter 结构看这条路由机制是可直接观察的architecture.md与electron-vite.md都带有paths列表如[src/**/*.ts, src/**/*.tsx, scripts/check-boundaries.mjs]而commit-and-quality.md、git-workflow.md没有paths字段属于全局规则。AGENTS.md补充了运行时语义作用域扩大时要加载新匹配的规则但不要默认加载不相关的路径作用规则——这既控制 Agent 的上下文成本也避免无关规则干扰当前变更。小结CLAUDE.md 虽短却是 Motrix 仓库工程体系的总纲它用 9 条 pnpm 命令定义了开发入口用 4 条架构边界锁定了shared/core/renderer/main/server/preload六层目录的依赖方向并用规则路由表把 13 份细则按文件作用域分发。这些纸面约束在仓库中都有可执行的对应物——scripts/check-boundaries.mjs 把导入方向变成 grep 规则src/shared/protocol/commands.ts 把通道字符串收敛为共享常量prestart/pretest钩子把 ABI 匹配变成脚本前置条件commit-and-quality.md把三项检查变成提交前置门禁。理解并遵循这套文档—脚本—契约三位一体的规范是向 Motrix 贡献代码或驱动 AI Agent 协作的前提。【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考