尧图网页设计 
Midscene 开源贡献实战指南从 Monorepo 环境搭建、Nx 构建缓存到 Conventional Commits 与报告模板同步机制【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene本文基于 Midscene 仓库的官方贡献文档 CONTRIBUTING.md 展开系统讲解在 Midscene面向 E2E 测试的 GUI Agent 项目中完成一次完整贡献所需的全部技术能力pnpm corepack Nx 的 Monorepo 环境搭建、按包聚焦的构建与测试命令、Report 模板占位符错误的底层成因与修复手段、Biome 代码规范与 Conventional Commits 提交约束以及 Chrome 扩展的本地开发与加载方式。读完本文你可以独立完成从 fork 仓库到提交 PR 的全流程并理解仓库中构建、测试、发布各自动化环节背后的实现原理。一、环境搭建Fork、Node.js 与 pnpm 依赖安装1.1 Fork 与 clone贡献流程的第一步是把仓库 fork 到自己的账号再 clone 到本地。Midscene 是一个 pnpm workspace 驱动的 Monorepo工作区定义在 pnpm-workspace.yaml 中将apps/*与packages/*两类目录纳入同一个工作区管理packages: - apps/* - packages/*1.2 Node.js 版本要求官方推荐 Node.js 20.19.0可用以下命令检查当前版本node -v如果环境未安装 Node.js可使用 nvm 或 fnm 等版本管理器安装。通过 nvm 安装并切换 20.19.0 的示例# 安装 Node.js 20 LTS nvm install 20.19.0 --lts # 将 Node.js 20 设为默认版本 nvm alias default 20.19.0 # 切换到该版本 nvm use 20.19.0从根 package.json 的engines字段可以看到实际的版本约束与文档推荐值一致且有更宽的上限engines: { pnpm: 9.3.0, node: ^20.19.0 || ^22.12.0 || 24.0.0 }, packageManager: pnpm9.3.0这意味着 Node 22.12.0 与 Node 24 同样受支持packageManager字段则锁定了 corepack 应激活的 pnpm 版本。1.3 使用 corepack 启用 pnpm 并安装依赖corepack enable pnpm installpnpm install会完成三件事安装全部依赖在 Monorepo 内部包之间建立软链接运行prepare脚本构建所有包。这一行为可以对照根 package.json 中的脚本定义得到印证prepare: husky pnpm run build, build: nx run-many --targetbuild --excludedoc --verbose即prepare先通过 husky 初始化 git hooks再调用 Nx 的run-many对全仓执行build目标排除文档站doc。这里还隐含一个关键事实pnpm install完成后所有包实际上已经过一次完整构建。1.4 配置 Git 邮箱提交 PR 前请确认 GitHub 账号中已登记邮箱并检查 git 客户端配置git config --list | grep email按需设置全局或仓库级邮箱git config --global user.email SOME_EMAILexample.com git config user.email SOME_EMAILexample.com二、仓库地图Repo Map各包职责与包名对照贡献文档给出了仓库的结构总览这是理解后续所有构建与测试命令的前提目录npm 包名 / Nx 项目名职责packages/coremidscene/coreAgent 执行、规划、模型集成、设备抽象packages/web-integrationmidscene/webPlaywright/Puppeteer 集成主要的 Web E2E 测试覆盖packages/sharedmidscene/sharedMonorepo 共享工具packages/testmidscene/testMidscene Test可扩展的 YAML 测试框架与 Node SDKpackages/{android,ios,computer,harmony}midscene/android等平台运行时旁边配套对应的*-playground包packages/visualizer、apps/report—报告渲染与查看器 UIapps/siteNx 项目名为doc文档站注意命令中要用doc而不是siteapps/chrome-extension、apps/playground、apps/report、apps/recorder-form—用户侧应用其中midscene/core的导出面非常宽从 packages/core/package.json 的exports可以看到它同时暴露./agent、./yaml、./report、./device、./dump、./skill等多个子入口这正是 Repo Map 中agent 执行、规划、模型集成、设备抽象一句话描述的具体落点。常用命令速查安装依赖pnpm install代码检查pnpm run lint聚焦构建npx nx build project聚焦测试npx nx test projectWeb E2Enpx nx e2e midscene/webAI 测试npx nx test:ai midscene/core或npx nx test:ai midscene/web这些命令背后的统一入口是根 package.json 的 scripts例如test即nx run-many --targettesttest:ai则显式限定在midscene/core、midscene/web、midscene/cli三个项目上运行。三、开发工作流分支、构建与 Watch 模式3.1 新建分支建议在独立分支上开发便于后续发起 PRgit checkout -b MY_BRANCH_NAME3.2 构建单个包或全量构建# 只构建要修改的包 npx nx build midscene/web # 构建全部包 pnpm run build从 nx.json 可以看到build目标的缓存策略cache: true依赖^build即先构建上游依赖包输入包含项目自身的tsconfig.json、package.json、rslib/rsbuild配置与scripts/**输出声明为{projectRoot}/dist。这解释了为什么日常开发中npx nx build project通常很快——未变化的包会直接命中缓存。3.3 根级 dev 命令与单应用 dev 命令只有在需要 Monorepo 级别的 watch/构建联动时才使用根 dev 命令pnpm run dev根脚本实际执行的是dev: node scripts/dev-prepare.js nx run-many --targetbuild:watch --excludeandroid-playground,chrome-extension,midscene/report,doc --verbose --parallel6第一步的 scripts/dev-prepare.js 会完成三件准备工作若apps/report/dist/index.html不存在先执行npx nx build midscene/reportcore 的USE_DEV_REPORT模式需要它若apps/playground/dist/index.html不存在先构建 playground为packages/playground/static与packages/ios/static创建指向apps/playground/dist的符号链接已存在则跳过。如果只需调试单个应用直接启动该应用自己的 dev server 即可不必动用根 dev 命令cd apps/report pnpm run dev cd apps/site pnpm run dev cd apps/playground pnpm run dev cd apps/chrome-extension pnpm run dev四、Report 模板占位符问题从占位符机制到缓存陷阱的深度解析这是贡献文档中最具源码纵深的一节。Midscene 的midscene/core内嵌了一份完整的 Report HTML 模板以便在不依赖midscene/report运行时构建产物的情况下生成报告。而 Report 本身又依赖 Core因此 Core 源码中只保留占位符// packages/core/src/report-html-template.ts export const REPORT_HTML_TEMPLATE REPLACE_ME_WITH_REPORT_HTML;见 packages/core/src/report-html-template.ts。真正把报告 HTML 写入 Core 的 CJS/ESM 模板模块是由midscene/report:build负责的而 Core 自己的构建也会尽力best-effort同步一次已有的 Report HTML。4.1 unresolved placeholder 错误何时出现典型场景有二Core 先于 Report 构建例如 Report 尚未构建或构建失败apps/report/dist/index.html不存在Core 的尽力同步只能留下占位符模块磁盘上已存在占位符模块而一次命中缓存的 Core 构建跳过了本可替换占位符的同步钩子。两种情况下 Core 仍可正常加载但生成报告时会主动抛出该错误而不是产出一份无效报告。抛错的依据可以在 scripts/report-template-utils.mjs 中直接看到——validateReportHtml会拒绝包含魔法字符串REPLACE_ME_WITH_REPORT_HTML的模板并校验模板非空、不超过 3 MiB防止递归打包报告模板、包含唯一的!doctype html、包含idroot挂载点export const reportTemplateMagicString REPLACE_ME_WITH_REPORT_HTML; export const reportTemplateMaxBytes 3 * 1024 * 1024;4.2 Cannot find module ./report-html-template.js 错误何时出现Nx 不会把这两个模板模块保存/恢复到midscene/core:build的缓存里。这一点可以从 packages/core/package.json 的nx.targets.build.outputs中得到直接证据——两份模板模块被显式排除在缓存输出之外outputs: [ {projectRoot}/dist/**/*.*, !{projectRoot}/dist/lib/report-html-template.js, !{projectRoot}/dist/es/report-html-template.mjs ]因此该错误只在以下条件同时满足时出现(1) 本地已存在有效的 Core 构建缓存(2)packages/core/dist或其模板模块被删除但未清理缓存(3) 仅重建 Core 且构建从缓存恢复导致真实构建与同步钩子均未执行。被排除的模板模块不会被恢复加载 Core 随即失败。由于当前 CI 不恢复.nx/cache且pnpm clean会同时清掉缓存与 dist见根 package.json 的clean脚本rimraf --glob .nx/cache ... packages/*/dist ...这一场景在常规工作流中很少出现。4.3 修复方式两类错误都可以通过构建 Report 解决它会产出 HTML 与两份 Core 模板模块pnpm exec nx build midscene/report若apps/report/dist/index.html已存在、只需要修复 Core 侧的模板模块可直接同步pnpm --filter midscene/core sync-report-template该命令对应 packages/core/package.json 中的脚本node ../../scripts/sync-core-report-template.mjs其实现 scripts/sync-core-report-template.mjs 调用syncCoreReportTemplateModules()将校验后的 HTML 序列化为 CJSlib/report-html-template.js与 ESMes/report-html-template.mjs两个独立模块文件写回 Core 产物目录。4.4 FAQTemplate does not contain {{dump}} placeholder由于循环依赖问题必须执行整个仓库的完整构建流程来编译 Midscene 项目而不能单独编译midscene/core包。这一点与上文 4.1 中Core 先于 Report 构建的场景一脉相承报告模板、playground 静态资源都是跨包产物只有全量构建pnpm run build才能保证所有模板与静态资源就位。五、测试体系单元测试、AI 测试与 E2E 测试5.1 修改 AI 相关代码前的环境准备若要修改本仓库的 AI 相关代码需要在根目录创建.env文件OPENAI_API_KEYyour_token MIDSCENE_MODEL_NAMEqwen3-vl-plus5.2 添加与运行单元测试修 bug 或新增代码时应补充测试。单元测试用例放在PACKAGE_DIR/tests目录如 packages/core/tests、packages/shared/tests各包默认基于 rstest 运行例如 core 的脚本定义为test: rstest, test:ai: AITESTtrue rstest提交 PR 前运行pnpm run test # 包含 AI 相关特性的测试需要根目录 .env 文件 pnpm run test:ai也可以只跑单个包npx nx test midscene/web # AI 测试需要 .env npx nx test:ai midscene/web注意 nx.json 中test目标声明了cache: false即单元测试永远全量执行不会被 Nx 缓存跳过——这对保证回归检查的真实性很重要。5.3 运行 E2E 测试Midscene 使用 playwright 运行端到端测试使用 adb 在 Android 上运行端到端测试。运行 Playwright E2Epnpm run e2e针对指定项目npx nx e2e midscene/web从 packages/web-integration/package.json 的脚本定义可以看到e2e的底层实现以及报告与缓存变体的差异e2e: playwright test --configtests/playwright.config.ts, e2e:report: MIDSCENE_REPORTtrue playwright test --configtests/playwright.config.ts, e2e:cache: MIDSCENE_CACHEtrue playwright test --configtests/playwright.config.ts即MIDSCENE_REPORTtrue开启报告产出、MIDSCENE_CACHEtrue开启缓存路径的回归验证这也是根目录test:ai:alle2e e2e:cache e2e:report test:ai e2e:visualizer组合的由来。运行 adb 相关 E2E 前需先启动 adb server详见 packages/web-integration/README.mdcd packages/web-integration pnpm run test:ai -- adb六、代码规范Biome 与 commitlint 提交约束6.1 Lint仓库使用 Biome 统一 lint 与格式化pnpm run lint对应根脚本npx biome check . --diagnostic-levelinfo --no-errors-on-unmatched --fix配置见 biome.json。VS Code 用户可安装 Biome 扩展在编辑时实时查看问题。此外lint-staged会在提交前对暂存文件自动执行 Biomejson/css/js/ts/tsx 等与 Prettiermd/mdx/less/scss检查并对package.json执行依赖版本一致性校验pnpm run check-dependency-version。6.2 PR 标题与 Commit 信息格式Midscene 采用 Conventional Commits 规范用于自动化 changelog 生成并保持提交历史清晰type(scope): subject ^ ^ ^ || | |__ Subject: 简洁描述祈使句、小写 || |__________ Scope: 受影响的代码区域必填 |_______________ Type: 变更类型允许的 typefeat新功能、fix缺陷修复、refactor非 bug 非功能的代码改动、chore构建流程、辅助工具、文档生成等、docs纯文档perf、style、test、ci、build等其他规范类型也可接受。scope 必须非空。从 commitlint.config.js 可以看到scope 白名单由固定基础集合与apps/、packages/两个目录下的全部顶层目录名自动合并而成const allScopes [ // basic scopes workflow, llm, playwright, puppeteer, blog, bridge, recorder, // 自动从 apps/ 与 packages/ 目录名收集 ...appsScopes, ...packagesScopes, ];规则层面还要求scope-empty必须失败级别 2、header-max-length上限 300 字符。示例feat(bridge): add screenshot tool with element selectionfix(android): correct adb connection issue on windowsrefactor(llm): simplify prompt generation logicchore(workflow): update commitlint configurationdocs(bridge): clarify AgentOverChromeBridge usage不符合规则的提交会被 pre-commit/commitlint 钩子拒绝——这正是根 package.json 中commitlint/cli、commitlint/config-conventional与 commitizen 依赖的作用所在。七、版本、发布与 Chrome 扩展开发7.1 版本与发布所有 Midscene 包使用统一的固定版本号当前仓库版本为 1.12.6见根 package.json。Release notes 由 GitHub releases 自动生成。维护者发布新版本时通常走 CI 而非本地直发触发仓库的 release action生成 release notes。稳定版发布还会尝试从 CI 把打包好的 Chrome 扩展提交到 Chrome Web Store需要在仓库配置以下 secretsCHROME_WEB_STORE_PUBLISHER_IDCHROME_WEB_STORE_CLIENT_IDCHROME_WEB_STORE_CLIENT_SECRETCHROME_WEB_STORE_REFRESH_TOKEN若 Chrome Web Store 发布失败GitHub Release 与扩展 zip 仍会生成可从 release artifacts 下载 zip 后在 Web Store 后台手动上传。7.2 Chrome 扩展目录结构与开发流程apps/chrome-extension的关键子目录dist/构建输出、extension/打包后的扩展目录、scripts/构建与工具脚本、src/源码其中src/extension/是扩展特有代码、static/静态资源。开发流程先构建基础包pnpm run build启动开发模式cd apps/chrome-extension pnpm run dev构建扩展cd apps/chrome-extension pnpm run build加载扩展在 Chrome 中打开chrome://extensions/右上角启用开发者模式点击加载已解压的扩展程序选择apps/chrome-extension/dist目录。也可使用打包产物apps/chrome-extension/extension_output/midscene-extension-v{version}.zip稳定版发布时该 zip 就是 Web Store 发布作业使用的工件发布失败时同样可拿它手动上传。更详细的说明见 apps/chrome-extension/README.md。八、文档站构建GITHUB_TOKEN 与星数展示Midscene 文档位于 apps/site 目录。生产构建会拉取当前 GitHub 星数需要带鉴权的 GitHub API tokenGITHUB_TOKEN$(gh auth token) pnpm --filter doc build注意此处过滤名是doc即第二节 Repo Map 中强调的 Nx 项目名。文档站 dev server 不要求 token若 GitHub 不可达页面会渲染一个非数字占位符而不是显示过期的星数。九、小结一次完整贡献的技术检查清单综合以上各节一次面向 Midscene 的贡献可以按如下顺序落地nvm use 20.19.0或 22.12/24corepack enable pnpm install——首次安装即触发全仓构建git checkout -b branch按 Repo Map 定位目标包core / web-integration / android / site 等局部用npx nx build project、npx nx test project快速迭代跨包场景再回到pnpm run dev/pnpm run build遇报告模板占位符或模块缺失错误优先pnpm exec nx build midscene/report或pnpm --filter midscene/core sync-report-template修复理解其根源在于占位符 构建期替换 Nx 缓存排除三者组合证据见 packages/core/src/report-html-template.ts 与 scripts/report-template-utils.mjs;pnpm run lintpnpm run test涉及 AI 代码时先备好根目录.env再跑pnpm run test:ai与相关 e2e按 Conventional Commits 且带必填 scope 提交PR 标题同理交给 pre-commit 钩子校验。掌握这套流程后你对仓库内任何一个包的修改都能被构建、测试与提交规范体系完整地接住——这正是贡献文档所希望达到的可复制、可运行、可验证的效果。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene 开源贡献实战指南：从 Monorepo 环境搭建、Nx 构建缓存到 Conventional Commits 与报告模板同步机制
Midscene 开源贡献实战指南从 Monorepo 环境搭建、Nx 构建缓存到 Conventional Commits 与报告模板同步机制【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene本文基于 Midscene 仓库的官方贡献文档 CONTRIBUTING.md 展开系统讲解在 Midscene面向 E2E 测试的 GUI Agent 项目中完成一次完整贡献所需的全部技术能力pnpm corepack Nx 的 Monorepo 环境搭建、按包聚焦的构建与测试命令、Report 模板占位符错误的底层成因与修复手段、Biome 代码规范与 Conventional Commits 提交约束以及 Chrome 扩展的本地开发与加载方式。读完本文你可以独立完成从 fork 仓库到提交 PR 的全流程并理解仓库中构建、测试、发布各自动化环节背后的实现原理。一、环境搭建Fork、Node.js 与 pnpm 依赖安装1.1 Fork 与 clone贡献流程的第一步是把仓库 fork 到自己的账号再 clone 到本地。Midscene 是一个 pnpm workspace 驱动的 Monorepo工作区定义在 pnpm-workspace.yaml 中将apps/*与packages/*两类目录纳入同一个工作区管理packages: - apps/* - packages/*1.2 Node.js 版本要求官方推荐 Node.js 20.19.0可用以下命令检查当前版本node -v如果环境未安装 Node.js可使用 nvm 或 fnm 等版本管理器安装。通过 nvm 安装并切换 20.19.0 的示例# 安装 Node.js 20 LTS nvm install 20.19.0 --lts # 将 Node.js 20 设为默认版本 nvm alias default 20.19.0 # 切换到该版本 nvm use 20.19.0从根 package.json 的engines字段可以看到实际的版本约束与文档推荐值一致且有更宽的上限engines: { pnpm: 9.3.0, node: ^20.19.0 || ^22.12.0 || 24.0.0 }, packageManager: pnpm9.3.0这意味着 Node 22.12.0 与 Node 24 同样受支持packageManager字段则锁定了 corepack 应激活的 pnpm 版本。1.3 使用 corepack 启用 pnpm 并安装依赖corepack enable pnpm installpnpm install会完成三件事安装全部依赖在 Monorepo 内部包之间建立软链接运行prepare脚本构建所有包。这一行为可以对照根 package.json 中的脚本定义得到印证prepare: husky pnpm run build, build: nx run-many --targetbuild --excludedoc --verbose即prepare先通过 husky 初始化 git hooks再调用 Nx 的run-many对全仓执行build目标排除文档站doc。这里还隐含一个关键事实pnpm install完成后所有包实际上已经过一次完整构建。1.4 配置 Git 邮箱提交 PR 前请确认 GitHub 账号中已登记邮箱并检查 git 客户端配置git config --list | grep email按需设置全局或仓库级邮箱git config --global user.email SOME_EMAILexample.com git config user.email SOME_EMAILexample.com二、仓库地图Repo Map各包职责与包名对照贡献文档给出了仓库的结构总览这是理解后续所有构建与测试命令的前提目录npm 包名 / Nx 项目名职责packages/coremidscene/coreAgent 执行、规划、模型集成、设备抽象packages/web-integrationmidscene/webPlaywright/Puppeteer 集成主要的 Web E2E 测试覆盖packages/sharedmidscene/sharedMonorepo 共享工具packages/testmidscene/testMidscene Test可扩展的 YAML 测试框架与 Node SDKpackages/{android,ios,computer,harmony}midscene/android等平台运行时旁边配套对应的*-playground包packages/visualizer、apps/report—报告渲染与查看器 UIapps/siteNx 项目名为doc文档站注意命令中要用doc而不是siteapps/chrome-extension、apps/playground、apps/report、apps/recorder-form—用户侧应用其中midscene/core的导出面非常宽从 packages/core/package.json 的exports可以看到它同时暴露./agent、./yaml、./report、./device、./dump、./skill等多个子入口这正是 Repo Map 中agent 执行、规划、模型集成、设备抽象一句话描述的具体落点。常用命令速查安装依赖pnpm install代码检查pnpm run lint聚焦构建npx nx build project聚焦测试npx nx test projectWeb E2Enpx nx e2e midscene/webAI 测试npx nx test:ai midscene/core或npx nx test:ai midscene/web这些命令背后的统一入口是根 package.json 的 scripts例如test即nx run-many --targettesttest:ai则显式限定在midscene/core、midscene/web、midscene/cli三个项目上运行。三、开发工作流分支、构建与 Watch 模式3.1 新建分支建议在独立分支上开发便于后续发起 PRgit checkout -b MY_BRANCH_NAME3.2 构建单个包或全量构建# 只构建要修改的包 npx nx build midscene/web # 构建全部包 pnpm run build从 nx.json 可以看到build目标的缓存策略cache: true依赖^build即先构建上游依赖包输入包含项目自身的tsconfig.json、package.json、rslib/rsbuild配置与scripts/**输出声明为{projectRoot}/dist。这解释了为什么日常开发中npx nx build project通常很快——未变化的包会直接命中缓存。3.3 根级 dev 命令与单应用 dev 命令只有在需要 Monorepo 级别的 watch/构建联动时才使用根 dev 命令pnpm run dev根脚本实际执行的是dev: node scripts/dev-prepare.js nx run-many --targetbuild:watch --excludeandroid-playground,chrome-extension,midscene/report,doc --verbose --parallel6第一步的 scripts/dev-prepare.js 会完成三件准备工作若apps/report/dist/index.html不存在先执行npx nx build midscene/reportcore 的USE_DEV_REPORT模式需要它若apps/playground/dist/index.html不存在先构建 playground为packages/playground/static与packages/ios/static创建指向apps/playground/dist的符号链接已存在则跳过。如果只需调试单个应用直接启动该应用自己的 dev server 即可不必动用根 dev 命令cd apps/report pnpm run dev cd apps/site pnpm run dev cd apps/playground pnpm run dev cd apps/chrome-extension pnpm run dev四、Report 模板占位符问题从占位符机制到缓存陷阱的深度解析这是贡献文档中最具源码纵深的一节。Midscene 的midscene/core内嵌了一份完整的 Report HTML 模板以便在不依赖midscene/report运行时构建产物的情况下生成报告。而 Report 本身又依赖 Core因此 Core 源码中只保留占位符// packages/core/src/report-html-template.ts export const REPORT_HTML_TEMPLATE REPLACE_ME_WITH_REPORT_HTML;见 packages/core/src/report-html-template.ts。真正把报告 HTML 写入 Core 的 CJS/ESM 模板模块是由midscene/report:build负责的而 Core 自己的构建也会尽力best-effort同步一次已有的 Report HTML。4.1 unresolved placeholder 错误何时出现典型场景有二Core 先于 Report 构建例如 Report 尚未构建或构建失败apps/report/dist/index.html不存在Core 的尽力同步只能留下占位符模块磁盘上已存在占位符模块而一次命中缓存的 Core 构建跳过了本可替换占位符的同步钩子。两种情况下 Core 仍可正常加载但生成报告时会主动抛出该错误而不是产出一份无效报告。抛错的依据可以在 scripts/report-template-utils.mjs 中直接看到——validateReportHtml会拒绝包含魔法字符串REPLACE_ME_WITH_REPORT_HTML的模板并校验模板非空、不超过 3 MiB防止递归打包报告模板、包含唯一的!doctype html、包含idroot挂载点export const reportTemplateMagicString REPLACE_ME_WITH_REPORT_HTML; export const reportTemplateMaxBytes 3 * 1024 * 1024;4.2 Cannot find module ./report-html-template.js 错误何时出现Nx 不会把这两个模板模块保存/恢复到midscene/core:build的缓存里。这一点可以从 packages/core/package.json 的nx.targets.build.outputs中得到直接证据——两份模板模块被显式排除在缓存输出之外outputs: [ {projectRoot}/dist/**/*.*, !{projectRoot}/dist/lib/report-html-template.js, !{projectRoot}/dist/es/report-html-template.mjs ]因此该错误只在以下条件同时满足时出现(1) 本地已存在有效的 Core 构建缓存(2)packages/core/dist或其模板模块被删除但未清理缓存(3) 仅重建 Core 且构建从缓存恢复导致真实构建与同步钩子均未执行。被排除的模板模块不会被恢复加载 Core 随即失败。由于当前 CI 不恢复.nx/cache且pnpm clean会同时清掉缓存与 dist见根 package.json 的clean脚本rimraf --glob .nx/cache ... packages/*/dist ...这一场景在常规工作流中很少出现。4.3 修复方式两类错误都可以通过构建 Report 解决它会产出 HTML 与两份 Core 模板模块pnpm exec nx build midscene/report若apps/report/dist/index.html已存在、只需要修复 Core 侧的模板模块可直接同步pnpm --filter midscene/core sync-report-template该命令对应 packages/core/package.json 中的脚本node ../../scripts/sync-core-report-template.mjs其实现 scripts/sync-core-report-template.mjs 调用syncCoreReportTemplateModules()将校验后的 HTML 序列化为 CJSlib/report-html-template.js与 ESMes/report-html-template.mjs两个独立模块文件写回 Core 产物目录。4.4 FAQTemplate does not contain {{dump}} placeholder由于循环依赖问题必须执行整个仓库的完整构建流程来编译 Midscene 项目而不能单独编译midscene/core包。这一点与上文 4.1 中Core 先于 Report 构建的场景一脉相承报告模板、playground 静态资源都是跨包产物只有全量构建pnpm run build才能保证所有模板与静态资源就位。五、测试体系单元测试、AI 测试与 E2E 测试5.1 修改 AI 相关代码前的环境准备若要修改本仓库的 AI 相关代码需要在根目录创建.env文件OPENAI_API_KEYyour_token MIDSCENE_MODEL_NAMEqwen3-vl-plus5.2 添加与运行单元测试修 bug 或新增代码时应补充测试。单元测试用例放在PACKAGE_DIR/tests目录如 packages/core/tests、packages/shared/tests各包默认基于 rstest 运行例如 core 的脚本定义为test: rstest, test:ai: AITESTtrue rstest提交 PR 前运行pnpm run test # 包含 AI 相关特性的测试需要根目录 .env 文件 pnpm run test:ai也可以只跑单个包npx nx test midscene/web # AI 测试需要 .env npx nx test:ai midscene/web注意 nx.json 中test目标声明了cache: false即单元测试永远全量执行不会被 Nx 缓存跳过——这对保证回归检查的真实性很重要。5.3 运行 E2E 测试Midscene 使用 playwright 运行端到端测试使用 adb 在 Android 上运行端到端测试。运行 Playwright E2Epnpm run e2e针对指定项目npx nx e2e midscene/web从 packages/web-integration/package.json 的脚本定义可以看到e2e的底层实现以及报告与缓存变体的差异e2e: playwright test --configtests/playwright.config.ts, e2e:report: MIDSCENE_REPORTtrue playwright test --configtests/playwright.config.ts, e2e:cache: MIDSCENE_CACHEtrue playwright test --configtests/playwright.config.ts即MIDSCENE_REPORTtrue开启报告产出、MIDSCENE_CACHEtrue开启缓存路径的回归验证这也是根目录test:ai:alle2e e2e:cache e2e:report test:ai e2e:visualizer组合的由来。运行 adb 相关 E2E 前需先启动 adb server详见 packages/web-integration/README.mdcd packages/web-integration pnpm run test:ai -- adb六、代码规范Biome 与 commitlint 提交约束6.1 Lint仓库使用 Biome 统一 lint 与格式化pnpm run lint对应根脚本npx biome check . --diagnostic-levelinfo --no-errors-on-unmatched --fix配置见 biome.json。VS Code 用户可安装 Biome 扩展在编辑时实时查看问题。此外lint-staged会在提交前对暂存文件自动执行 Biomejson/css/js/ts/tsx 等与 Prettiermd/mdx/less/scss检查并对package.json执行依赖版本一致性校验pnpm run check-dependency-version。6.2 PR 标题与 Commit 信息格式Midscene 采用 Conventional Commits 规范用于自动化 changelog 生成并保持提交历史清晰type(scope): subject ^ ^ ^ || | |__ Subject: 简洁描述祈使句、小写 || |__________ Scope: 受影响的代码区域必填 |_______________ Type: 变更类型允许的 typefeat新功能、fix缺陷修复、refactor非 bug 非功能的代码改动、chore构建流程、辅助工具、文档生成等、docs纯文档perf、style、test、ci、build等其他规范类型也可接受。scope 必须非空。从 commitlint.config.js 可以看到scope 白名单由固定基础集合与apps/、packages/两个目录下的全部顶层目录名自动合并而成const allScopes [ // basic scopes workflow, llm, playwright, puppeteer, blog, bridge, recorder, // 自动从 apps/ 与 packages/ 目录名收集 ...appsScopes, ...packagesScopes, ];规则层面还要求scope-empty必须失败级别 2、header-max-length上限 300 字符。示例feat(bridge): add screenshot tool with element selectionfix(android): correct adb connection issue on windowsrefactor(llm): simplify prompt generation logicchore(workflow): update commitlint configurationdocs(bridge): clarify AgentOverChromeBridge usage不符合规则的提交会被 pre-commit/commitlint 钩子拒绝——这正是根 package.json 中commitlint/cli、commitlint/config-conventional与 commitizen 依赖的作用所在。七、版本、发布与 Chrome 扩展开发7.1 版本与发布所有 Midscene 包使用统一的固定版本号当前仓库版本为 1.12.6见根 package.json。Release notes 由 GitHub releases 自动生成。维护者发布新版本时通常走 CI 而非本地直发触发仓库的 release action生成 release notes。稳定版发布还会尝试从 CI 把打包好的 Chrome 扩展提交到 Chrome Web Store需要在仓库配置以下 secretsCHROME_WEB_STORE_PUBLISHER_IDCHROME_WEB_STORE_CLIENT_IDCHROME_WEB_STORE_CLIENT_SECRETCHROME_WEB_STORE_REFRESH_TOKEN若 Chrome Web Store 发布失败GitHub Release 与扩展 zip 仍会生成可从 release artifacts 下载 zip 后在 Web Store 后台手动上传。7.2 Chrome 扩展目录结构与开发流程apps/chrome-extension的关键子目录dist/构建输出、extension/打包后的扩展目录、scripts/构建与工具脚本、src/源码其中src/extension/是扩展特有代码、static/静态资源。开发流程先构建基础包pnpm run build启动开发模式cd apps/chrome-extension pnpm run dev构建扩展cd apps/chrome-extension pnpm run build加载扩展在 Chrome 中打开chrome://extensions/右上角启用开发者模式点击加载已解压的扩展程序选择apps/chrome-extension/dist目录。也可使用打包产物apps/chrome-extension/extension_output/midscene-extension-v{version}.zip稳定版发布时该 zip 就是 Web Store 发布作业使用的工件发布失败时同样可拿它手动上传。更详细的说明见 apps/chrome-extension/README.md。八、文档站构建GITHUB_TOKEN 与星数展示Midscene 文档位于 apps/site 目录。生产构建会拉取当前 GitHub 星数需要带鉴权的 GitHub API tokenGITHUB_TOKEN$(gh auth token) pnpm --filter doc build注意此处过滤名是doc即第二节 Repo Map 中强调的 Nx 项目名。文档站 dev server 不要求 token若 GitHub 不可达页面会渲染一个非数字占位符而不是显示过期的星数。九、小结一次完整贡献的技术检查清单综合以上各节一次面向 Midscene 的贡献可以按如下顺序落地nvm use 20.19.0或 22.12/24corepack enable pnpm install——首次安装即触发全仓构建git checkout -b branch按 Repo Map 定位目标包core / web-integration / android / site 等局部用npx nx build project、npx nx test project快速迭代跨包场景再回到pnpm run dev/pnpm run build遇报告模板占位符或模块缺失错误优先pnpm exec nx build midscene/report或pnpm --filter midscene/core sync-report-template修复理解其根源在于占位符 构建期替换 Nx 缓存排除三者组合证据见 packages/core/src/report-html-template.ts 与 scripts/report-template-utils.mjs;pnpm run lintpnpm run test涉及 AI 代码时先备好根目录.env再跑pnpm run test:ai与相关 e2e按 Conventional Commits 且带必填 scope 提交PR 标题同理交给 pre-commit 钩子校验。掌握这套流程后你对仓库内任何一个包的修改都能被构建、测试与提交规范体系完整地接住——这正是贡献文档所希望达到的可复制、可运行、可验证的效果。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考