Motrix 提交质量门禁每次提交前的必备检查与按变更类型选择验证手段【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文基于 Motrix 仓库的提交与质量规则 .claude/rules/commit-and-quality.md 展开系统讲解该项目每次提交前必须通过三道自动检查 按变更类型追加专项检查的质量门禁体系包括三条必跑命令边界检查、Biome lint、TypeScript 类型检查的准确用法与纪律要求以及行为测试、E2E、i18n、文件命名、插件 Schema 对齐、第三方声明、Rust 原生宿主、打包发布等八类变更各自对应的专项检查命令。读完本文你可以完整复现 Motrix 的提交前验证流程并理解每条检查脚本背后的实现机制。每次提交前必须通过的三道检查规则文档的核心要求非常明确在提交之前运行全部三条命令并修复所有失败项不允许先提交后修pnpm run check:boundaries pnpm run lint pnpm exec tsc --noEmit这三条命令在 package.json 中均有对应定义下面逐一结合源码讲解它们的实际行为与注意事项。check:boundaries架构分层的自动基线check:boundaries对应脚本 scripts/check-boundaries.mjs它通过grep -rnE对指定目录做导入模式扫描共内置 9 条硬规则源码中的rules数组覆盖 .claude/rules/architecture.md 中定义的层级矩阵的核心约束例如规则标签扫描目录模式要点core must not import electronsrc/core/from []electron[]core must not import fastifysrc/core/from []?fastifyshared must not use Node-specific APIs or globalssrc/shared/node:前缀导入、process.、NodeJS.全局renderer must not import core or mainsrc/renderer/路径含core/或main/的导入server must not import electronsrc/server/from []electron[]server must not import src/mainsrc/server/main/或src/main/导入production source must not reference deployment staging contractssrc/electron-runtime-dependencies.json、.motrix-*-stage.json、dist/(electron|server)-app等部署期契约add-task UI must not import transport or protocol commandssrc/renderer/components/add-task/对renderer/lib/transport、shared/protocol/commands的导入白名单排除use-external-hdration.ts、drop-zone.tsx、add-task-form.tsx三个 IPC 感知文件web-services must not reference Electron-only command symbolssrc/renderer/platform/web-services.tsPickSaveDir、CloseCurrentWindow、ResizeWindow、ShowMainWindow脚本的判定逻辑值得注意grep退出码 1无匹配视为[PASS]退出码 0 时先经filterOutExceptions按文件后缀过滤白名单文件再决定 PASS/FAIL命中违规会打印path:line:content明细并以退出码 1 终止。个别规则支持except白名单这正是文档强调check:boundaries只是自动基线不是完整的架构证明的原因——并非每条架构例外都能被机器强制因此规则同时要求开发者在提交前对照 architecture.md 人工复查本次改动引入的导入。lint与 CI 完全同构的 Biome 检查pnpm run lint在 package.json 中定义为biome check .即对整个仓库执行 Biome 检查。文档对此有两条强约束不得用更窄的路径列表替代——它必须与 CI 运行的命令完全一致不得用管道方式丢弃其退出码例如pnpm run lint | tee log.txt这类写法会让管道以tee的退出码为准掩盖 lint 失败。检查行为由 biome.json 统一配置关键配置包括格式化2 空格缩进、80 列行宽、LF 换行JS 单引号、JSX 双引号、分号asNeeded、尾逗号es5Lint启用recommended预设并打开react与test两个 domains 的recommended规则文件命名useFilenamingConvention设为error级强制源码文件名为 kebab-case例外覆盖overrides**/components/ui/**关闭noDangerouslySetInnerHtml与noArrayIndexKey所有*.test.ts/tsx、*.spec.ts/tsx及测试目录关闭noNonNullAssertion与noExplicitAny两个 registry fixture JSON 关闭格式化。另外启用vcs.useIgnoreFile尊重.gitignore与assist的organizeImports。也就是说pnpm run lint一条命令同时校验格式、导入排序、lint 规则与文件命名约定这就是它能作为提交门禁的原因。tsc --noEmit全量类型检查第三条pnpm exec tsc --noEmit使用仓库根 tsconfig.json 对整个工程做只检查、不产物的类型校验devDependencies 中固定了typescript版本确保本次改动不引入任何类型错误后再进入版本库。暂存与差异检查纪律文档对提交操作本身也规定了纪律防止检查过了但提交的不是同一份内容只git add你打算提交的文件或 hunk提交前检查git diff --staged运行git diff --cached --check检测空白字符、冲突标记等低级问题不要因为某个 CI job 是 non-blocking 的就故意隐瞒失败——非阻塞不等于可以忽略。按变更类型追加的专项检查三道必过检查是底座文档的 Change-Specific Checks 一节则要求凡与本次变更匹配的检查一条都不能少。完整映射如下表变更类型需要运行的检查行为或逻辑改动针对改动的测试pnpm exec vitest run test-path大范围横切改动用pnpm test浏览器 / Electron 用户流受影响流程有 E2E 覆盖时运行pnpm test:e2e语言资源或 i18n 行为pnpm run check:i18n新增或重命名文件pnpm run check:file-names插件 manifest 契约或motrix/plugin-manifest-schemapnpm run check:schema-parity依赖、打包资产或许可证元数据pnpm run check:third-party-notices原生宿主Rust见下方 cargo 三连打包或发布代码运行tests/scripts/下对应聚焦测试及相关 verifier下面对每个专项的实现做源码级展开。行为 / 逻辑改动Vitest 聚焦测试仓库使用 Vitestpnpm test即vitest run并带pretest钩子node scripts/ensure-native-abi.mjs node确保better-sqlite3等原生模块 ABI 与当前 Node 匹配。聚焦跑测试时直接用pnpm exec vitest run test-path只有当改动是大范围横切例如动了src/core/中多处共享逻辑时才升级到全量pnpm test。浏览器 / Electron 用户流Playwright E2Epnpm test:e2e对应playwright testpackage.json其pretest:e2e钩子会先ensure:electron-runtime并执行ensure-native-abi.mjs electron保证 Electron 运行时与原生 ABI 就绪。测试用例位于 e2e/ 目录如 e2e/task-lifecycle.spec.ts、e2e/add-task.spec.ts运行环境由 playwright.config.ts 配置。注意触发条件是受影响流程存在 E2E 覆盖时——改动了有对应 spec 的用户流就必须跑不能以改动很小为由跳过。i18n / 语言资源check:i18npnpm run check:i18n实际是node --import tsx scripts/check-i18n.mjs实现见 scripts/check-i18n.mjs。它默认以 src/shared/constants/locales.ts 中的SUPPORTED_LOCALES目录为基准、src/shared/locales/ 为资源目录检查项包括目录与文件一一对应目录有 locale 但缺 JSON 文件、或有文件但未注册均报错将所有标量 key 扁平化后以 fallback locale 为参照逐 locale 比对逻辑 key 集合缺失/多余都会列出复数族完整性基于Intl.PluralRules的cardinal类别校验每个 locale 必需的_zero/_one/_two/_few/_many/_other变体是否齐全、是否存在该 locale 不支持的类别并禁止 base key 与复数变体混用插值占位符一致性解析{{value}}、{{- value}}、{{value, format}}三种 i18next 形态跨 locale 比对同一逻辑 key 的占位符集合是否一致。全部通过时输出类似check:i18n passed: N locales, M logical translation keys.。该脚本也接受--catalog-module/--locales-dir参数覆盖默认路径可用--help查看。新增 / 重命名文件check:file-namesscripts/check-file-names.mjs 通过git ls-files --cached --others --exclude-standard扫描 Git 可见文件按扩展名套用命名约定.ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts/.css/.scss→ 主文件名必须为 kebab-case^[a-z0-9](?:-[a-z0-9])*$.py/.rs→ snake_case例外src/bin/下的 Cargo 二进制允许 kebab-caseCargo 惯例docs/与graphify-out/前缀整体排除。这与 biome.json 中useFilenamingConvention规则互为补充Biome 管的是被 lint 到的源码文件而check:file-names直接以 Git 索引为准覆盖 BiomeignoreUnknown放过的文件确保新增/重命名文件不会被遗漏。插件 manifest 契约check:schema-paritypnpm run check:schema-parity对应 scripts/check-schema-parity.mjs其设计意图在脚本头部注释中写得很清楚真正的 schema 位于外部发布的motrix/plugin-manifest-schema包宿主侧 src/core/plugin/manifest/schema.ts 必须保持纯再导出——脚本要求该文件包含export * from motrix/plugin-manifest-schema且去掉注释与该行后不得残留任何实质内容例如私自引入 zod 定义、本地类型都算 drift 失败。脚本注释还给出了修复方向出现 drift 时不要往 facade 里抄 schema 代码而是修改上游包并升级依赖版本。依赖 / 资产 / 许可证元数据check:third-party-noticespnpm run check:third-party-notices的定义是见 package.jsonpnpm run ensure:electron-runtime node scripts/generate-third-party-notices.mjs --check \ vitest run tests/check-third-party-notices.test.ts tests/generate-third-party-notices.test.ts即先用 scripts/generate-third-party-notices.mjs 的--check模式比对 THIRD_PARTY_NOTICES.md及 THIRD_PARTY_NOTICES.zh-CN.md是否与依赖/资产现状一致再跑对应的两个聚焦测试。因此凡是动package.json依赖、内置打包资产或许可证元数据的提交都必须通过它避免第三方声明与实际分发内容脱节。原生宿主 Rust 代码改动 packages/native-host/ 下的 Rust 代码时规则要求运行针对该包 manifest 的三连--locked保证锁定依赖不变cargo 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对应源码位于 packages/native-host/src/如broker_protocol.rs、endpoint.rs、launcher.rs等集成测试在 packages/native-host/tests/如host_integration.rs、flatpak_broker_integration.rs。-D warnings意味着 Clippy 警告直接视为错误与该包作为浏览器原生消息宿主native messaging host的严格质量要求一致。打包 / 发布代码改动打包或发布相关脚本scripts/ 下的 staging、verify、assemble 系列时要求运行 tests/scripts/ 下的对应聚焦测试和相应 verifier如verify-electron-package、verify-server-package、verify-appimage-artifact等并且对于check:update-artifacts即 scripts/verify-update-artifacts.mjs这类检查遵循 workflow 提供的参数不要自行拼造。发布链路的总体政策tag、签名、平台构建门控在 .claude/rules/git-workflow.md 的 Release Safety 一节有专门约束可与本文配套阅读。biome --write 的正确用法文档最后一条规则pnpm exec biome check --write .只能用于已审查reviewed、可自动修复的问题并且修复后必须重新运行上面三道必过检查确认没有引入新问题。换言之--write不是一键救火而是修复手段之一门禁本身仍然以只读检查命令的结果为准。小结这套门禁的设计取向从规则文档与脚本实现可以归纳出 Motrix 提交质量门禁的三个取向CI 同构本地必跑命令与 CI 完全一致biome check .且禁止管道丢弃退出码、禁止非阻塞 job 掩盖失败保证本地过了等价于CI 能过分层兜底check:boundaries是自动基线而非架构证明人工需对照 architecture.md 复查变更导入按变更面追加验证八类专项检查各自有独立的脚本实现与测试兜底如 i18n 的Intl.PluralRules复数校验、schema 纯 facade 漂移检测、文件命名对 Git 索引的直接扫描开发者按本次改动范围取并集执行即可。配合 .claude/rules/git-workflow.md 中的 Conventional Commits 规范type(scope): summarytype 限feat/fix/refactor/perf/test/docs/chore/ci/style与分支、PR 政策commit-and-quality.md构成 Motrix 从写完代码到合入 main的完整质量闭环。【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考