Midscene 仓库中的 AGENTS.md/CLAUDE.md面向 AI 编码 Agent 的工程约定体系解析【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene本篇技术指南以 Midscene 仓库根目录下的CLAUDE.md软链接指向AGENTS.md这一 Agent 规范文档为主体完整拆解其中定义的设计原则、默认工作流、变更规则、提交/PR 规则、文档国际化约束与验证策略。读完本文你将掌握在 Midscene 这类 pnpm Nx monorepo 中人与 AI Agent 如何以同一份指令文件协同开发从 Node/pnpm 版本约束、最小化 Nx 目标验证到 Conventional Commits scope 的自动推导机制都能得到源码级佐证。一、CLAUDE.md 的单一事实源设计一个软链接背后的约定仓库根目录下的CLAUDE.md并不是一个独立文件而是一个指向AGENTS.md的软链接CLAUDE.md - AGENTS.mdAGENTS.md开篇即声明了这一设计意图Canonical instructions for coding agents in this repository.CLAUDE.mdshould point here instead of duplicating rules.这是一个值得借鉴的做法规范只维护一份不同的 Agent 入口Claude Code 读CLAUDE.md其他 Agent 读AGENTS.md通过软链接共享同一事实源避免两份规则随时间漂移。AGENTS.md的内容组织为六个部分设计原则Design Principles、默认工作流Default Workflow、真正重要的变更规则Change Rules That Actually Matter、提交与 PR 规则、文档与国际化Docs And I18n含升级推荐模型专项小节以及验证指引Validation Guidance。以下逐节展开并用仓库实际文件印证每条规则。二、设计原则错误处理、序列化兼容性与日志规范文档第一部分给出三条贯穿全仓库的设计原则每一条都有明确的源码落点。2.1 出错即抛错而不是返回空值Throw errors instead of returning blank values when something goes wrong.这条原则要求异常路径显式抛出错误避免调用方拿到null/空对象后在更下游才暴露问题。在packages/core/src/errors.ts等文件中可以看到集中定义的错误类型供各层抛错使用。2.2 报告 Dump 序列化格式不需要向后兼容Report dump serialization format (ScreenshotRef,ReportActionDumpJSON) does not need backward compatibility with older formats.这条原则明确了 Midscene 报告数据格式的一个工程决策旧报告文件是可丢弃的产物可以随时重新生成因此修改序列化 schema 时不需要保留旧格式兼容垫片shim。从源码结构看这两个类型确实定义在报告 dump 层ScreenshotRef接口定义在 packages/core/src/dump/image-reference.ts并配套了normalizeScreenshotRef等解析函数ReportActionDump类定义在 packages/core/src/dump/report-action-dump.ts报告 HTML 注入逻辑generateAgentReportComment位于 packages/core/src/dump/html-utils.ts。这一决策大幅降低了报告格式的演进成本改 schema 时不必为旧文件写迁移代码只要保证新报告能生成即可。2.3 警告日志优先使用getDebug(topic, { console: true })For warning logs in package code, prefergetDebug(topic, { console: true })over directconsole.warn(...)so console output and Midscene log files stay aligned.这条规则的目的是让控制台输出与 Midscene 日志文件保持对齐。其底层实现在 packages/shared/src/logger.ts 中export function getDebug( topic: string, options?: { console?: boolean }, ): DebugFunction { // ... if (withConsole) { const baseFn getDebug(topic); const wrapper (...args: unknown[]): void { baseFn(...args); // 写入 Midscene 日志文件 debug 通道 try { console.warn([Midscene], ...args); // 同时输出到控制台 } catch { // Packaged Electron apps can have closed stdio streams. } }; debugInstances.set(cacheKey, wrapper); }从源码可以看到console: true选项生成的函数会先走基础日志链路Node 环境下写文件见writeLogToFile再追加一条带[Midscene]前缀的console.warn外层的try/catch专门处理打包后 Electron 应用 stdio 流可能关闭的情况保证日志失败不会击溃调用方。仓库中已有大量遵循该约定的用法例如 packages/shared/src/agent-tools/chrome-path.ts 中的getDebug(agent-tools:chrome-path, { console: true })。三、默认工作流pnpm、版本约束与最小化验证Default Workflow 一节定义了 Agent 在本仓库中的标准操作姿势其中每条都可以与仓库实际配置交叉验证。3.1 禁止强制推送只使用 pnpmNEVER force push anything unless you are explicitly told to do so. Usepnpmonly.3.2 Node 与 pnpm 版本约束已在 package.json 中固化文档要求工作区需要 Node^20.19.0 || ^22.12.0 || 24.0.0和 pnpm9.3.0。这与根目录 package.json 的engines字段完全一致engines: { pnpm: 9.3.0, node: ^20.19.0 || ^22.12.0 || 24.0.0 }, packageManager: pnpm9.3.0而 CONTRIBUTING.md 中给出的环境搭建建议推荐 Node 20.19.0、用 corepack 启用 pnpm、pnpm install会通过prepare脚本借助 nx 构建所有包也与此呼应。3.3 本地开发前先读 CONTRIBUTING.mdReadCONTRIBUTING.mdbefore local development. Dev/build workflows, app-local dev servers, and report rebuild troubleshooting are maintained there to avoid duplication.这体现了指令文件只写决策、细节外链的拆分策略AGENTS.md不重复开发流程细节而是指向 CONTRIBUTING.md。后者包含 Repo Map各包职责、常用命令pnpm install、pnpm run lint、npx nx build/test project、AI 测试npx nx test:ai midscene/core等。3.4 提交前跑 lint代码改动跑最小相关 Nx 目标Before creating a commit or updating a PR, runpnpm run lintfrom the repository root. For code changes, run the smallest relevant Nx target for each touched project instead of defaulting to full monorepo validation.根目录 package.json 中lint脚本的具体实现是lint: npx biome check . --diagnostic-levelinfo --no-errors-on-unmatched --fix即仓库统一用 Biome 做 lint 自动修复。最小相关 Nx 目标意味着只改packages/core时跑npx nx test core这一类聚焦目标而不是pnpm test后者是nx run-many --targettest --verbose会跑全部项目。这一策略与 monorepo 中 nx 的依赖图缓存机制配套避免为小改动付出全仓验证的时间成本。3.5 AI 测试需要模型相关环境变量AI tests require some environment variables likeMIDSCENE_MODEL_BASE_URLto be set.从源码结构看模型配置的统一解析逻辑位于 packages/shared/src/env/parse-model-config.ts其内部同样通过getDebug(ai:config)输出配置解析过程——这也再次印证了第二节日志规范的落地方式。四、变更规则测试策略与自食用dogfooding的 e2e 保护Change Rules That Actually Matter 一节是全文最有立场的部分规定了四条硬性约束。4.1 行为变化必须带测试且从最近的单元测试套件开始Add or update tests when behavior changes. Start with the nearest unit test suite; use AI tests or e2e only when the change actually depends on model behavior or browser/device integration.这条规则建立了测试成本阶梯单元rstest/vitest 单测→ AI 测试依赖模型→ e2e依赖浏览器/设备集成只有变更真正依赖对应层级的行为时才升级到更重的层级。这与根目录 package.json 中的脚本分级一致test单测、test:ai针对midscene/core、midscene/web、midscene/cli三个项目的 AI 测试、e2e/e2e:report/e2e:visualizer等。4.2 报告 App 的 e2e 是 Midscene 能力的自食用测试禁止降级为纯 DOM 断言Report app e2e tests underapps/report/e2eare also dogfooding Midscenes AI capabilities. Do not stabilize them by replacing coreaiAssert,aiTap,aiHover, or similar coverage with raw DOM-onlyjavascriptchecks unless the test is explicitly meant to validate DOM plumbing.这是全文最具特色的规则之一apps/report/e2e下的用例如 apps/report/e2e/report-single.yaml、report-merged.yaml、timeline-interaction.yaml等本身就在用 Midscene 的视觉 AI 能力测试 Midscene 的报告页面。规则明确禁止为了消除 flaky而把aiAssert偷换成javascript节点的纯 DOM 检查——那样做虽然能变稳但会让仓库失去对自身核心能力的真实验证。规则还给出唯一正确的排障方向Forapps/report/e2e/report-single.yaml, keep the report loading assertions onaiAssert; if they are flaky, improve the prompt, timing, or fixture while preservingaiAssertcoverage.即不稳定时应该改 prompt、调时序、修 fixture而不是砍掉 AI 覆盖。4.3 禁止手改生成产物改共享包必须做聚焦构建不得手工编辑dist/与apps/site/doc_build/下的生成输出修改共享包或导出入口时完成前必须对受影响项目跑一次聚焦构建如npx nx build project保证导出/构建链路没被破坏。五、提交与 PR 规则Conventional Commits 的 scope 推导机制Commit And PR Rules 一节规定了提交信息规范其中最有工程含量的是 scope 枚举的来源以及两个目录名 ≠ 发布名/项目名的显式提醒。5.1 scope 必须存在且来自目录结构Commits must follow Conventional Commits with a required scope. Scope values come from directory names underapps/andpackages/, plus shared scopes incommitlint.config.js.这段描述可以直接在 commitlint.config.js 中逐行对上// 读取 apps/ 与 packages/ 下的子目录名作为 scope const appsScopes getSubdirectories(path.join(__dirname, apps)); const packagesScopes getSubdirectories(path.join(__dirname, packages)); const allScopes [ // basic scopes手工维护的共享 scope workflow, llm, playwright, puppeteer, blog, bridge, recorder, // 自动从目录结构推导的 scope ...appsScopes, ...packagesScopes, ]; module.exports { extends: [commitlint/config-conventional], rules: { scope-enum: [0, always, uniqueScopes], // 0 警告级 scope-empty: [2, never], // 2 错误级禁止空 scope header-max-length: [2, always, 300], }, };可以注意到两个细节scope 枚举是活的——apps/或packages/下新增一个目录commit scope 自动扩展无需改配置规则级别设计上scope-empty是错误级必须写 scope而scope-enum被设为 0警告级——即必须有 scope是硬约束scope 是否在枚举内作为提示给共享 scope 之外的临时用法留出空间。5.2 两个必须记住的不匹配web-integration目录 ↔midscene/web包名packages/web-integration/package.json 的name是midscene/web但提交时必须使用目录名web-integration作为 scopeapps/site目录 ↔doc项目名apps/site/package.json 的name是doc即 Nx 项目名为doc而非site提交时应使用site作为 scope。CONTRIBUTING.md 的 Repo Map 中同样提醒了第二点apps/site: documentation site. The Nx project name isdoc, notsite. 这类目录名/包名/Nx 项目名三方不一致的情况正是这份 Agent 指令存在的价值之一把只在老成员脑子里的坑显性化。5.3 PR 摘要必须列出实际执行过的验证命令In PR summaries, list the actual validation commands you ran.这条规则要求 PR 描述与真实验证动作一致杜绝声称跑过测试但实际没跑也为 Code Review 提供了可复核的验证清单。六、文档与国际化双语同步与推荐模型升级的传播路径Docs And I18n 一节规定了文档的维护纪律并单列了一个升级推荐模型的专项流程。6.1 用户文档默认双语文档默认按双语维护改README.md必须在同一变更中更新 README.zh.md改apps/site/docs/en/**要检查并同步apps/site/docs/zh/**下对应文件反之亦然中英文目录树并非完全镜像——若对应文件不存在需自行决定是补上还是在最终总结中说明这是有意留空编辑站点文案前先读 apps/site/agents.md其中已记录术语约束。apps/site/agents.md 中的关键约束包括API Key在中文中保持不翻译不写成凭证Agent指 AI Agent / Midscene Agent 时保持原样不要翻译成代理Device 生命周期规范每个 Device 实例只能归属一个 AgentAgent.destroy()会调用Device.destroy()文档示例不得把同一 Device 传给多个 Agent提示框样式统一用:::info风险/错误才用:::warning/:::danger写作风格上明确反对营销腔与评价先行的空话完美契合极高的扩展上限一类表达应删除要求用机制、约束和示例说话。6.2 升级推荐模型先改事实源再传播到营销位该小节规定模型推荐的事实源是两份 mdx 文档apps/site/docs/en/model-strategy.mdx 与 apps/site/docs/zh/model-strategy.mdxapps/site/docs/en/model-common-config.mdx 与 apps/site/docs/zh/model-common-config.mdx当推荐模型或版本变化时文档举例qwen3-vl→qwen3.x、gemini-3-flash→gemini-3.5-flash先更新策略/配置文档再把新模型名传播到所有宣传支持模型列表的位置README.md与README.zh.md的 Driven by Visual Language Model 小节apps/site/docs/en/introduction.mdx与apps/site/docs/zh/introduction.mdx的同名小节。并明确两条边界changelog.mdx中的历史性引用保持不动faq.md里新模型优于旧模型的示例对比原样保留。当前 README.md 的模型列表段落支持Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS等多模态模型即处于这条传播链的末端。这条规则的意义在于模型名在仓库中散落在事实源文档 4 个宣传位 2 个历史文件共 8 处人工维护极易出现README 已改、introduction 忘改之类的漂移而显式列出完整传播清单可以消除这类遗漏。七、验证指引按变更范围选择验证强度Validation Guidance 一节给出了三档验证策略与第三节的最小相关 Nx 目标一脉相承变更类型验证动作仅改文档通常pnpm run lint即可单包代码变更pnpm run lint 最小相关的npx nx test project若导出/构建链路有变再补npx nx build project跨包运行时或构建系统变更跑pnpm run lint并明确声明更广泛的验证是否仍待完成第三档尤其体现对 AI Agent 的要求当验证范围超出本次能完成的部分时不允许沉默必须显式声明欠账——这是把诚实报告验证状态变成了硬性规则。八、小结这份 Agent 规范文件的设计模式回看 AGENTS.md即CLAUDE.md指向的内容它示范了一种可复用的仓库级 AI 协作规范写法单一事实源CLAUDE.md软链接到AGENTS.md规则只维护一份决策与细节分离本文档只写必须怎么做开发流程细节外链CONTRIBUTING.md术语约束外链apps/site/agents.md规则可被仓库文件验证版本约束对得上package.json的enginesscope 规则对得上commitlint.config.js日志规则对得上packages/shared/src/logger.ts的实现显式记录坑目录名/包名/项目名不一致、e2e 不许降级为 DOM 断言、模型名传播清单都是把隐性知识显性化验证状态必须诚实跨包变更允许验证欠账但必须明说。对于同样希望让 AI Agent 参与日常开发的 monorepo 项目这套原则 工作流 变更规则 提交规则 验证分级的结构是一个直接可参考的模板。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考