Cua Driver 第二次 E2E 收敛310 个提交的巨型 PR 如何被拆解为 72 个可评审落地堆栈【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua本文基于仓库内的历史执行计划 pr-2161-landing-plan.md 展开并结合 e2e-convergence-journal.md、cua-driver-testkit 源码与 CI 脚本还原一次真实的大型跨平台 E2E 收敛工程一个累积了 310 个提交、229 个文件、24,821/−17,033 行的长命分支如何被重新切分成 7 个功能 PR 加 2 个旁路 PR逐层落地到main。读完本文你将掌握一套可用于同类场景的巨型 PR 治理方法论范围白名单与保留队列、基于最终树的二进制补丁转移配方、历史证据与新鲜门槛的区分、共享文件冲突处理规则以及收尾时的树形对等审计。该计划文件开头明确标注Historical execution plan——它记录的是原草稿如何被拆分并落地的过程不再是当前测试或平台支持的参考当前的支持矩阵以 platform-support.mdx 与 action-support.md 为准。本文讨论的正是这份过程记录所蕴含的工程方法本身。背景为什么 310 个提交的长命分支不能直接合并第一波拆分已经落地剩下的只是第二波收敛增量仓库维护者此前已经用 #2135 拆分计划把第一波工作分拆为 #2138–#2154 落地。此后codex/link-e2e-videos这个长命分支源 PR #2161草稿状态继续累积了第二波收敛增量310 个提交中大量提交在反复改写同一批文件如recording.rs、E2E workflow分支历史本身已不可逐提交评审。计划给出的核心判断是决定不合并 #2161而是把它的增量重新落地为一组从当前main切出的 7 个全新 PR 堆栈。每个新 PR 针对自己拥有的路径集合从最终状态补丁构建而不是通过 cherry-pick 提交、也不是用整个文件盲目覆盖main。为什么 cherry-pick 在这里是错误工具310 个提交反复重写同一批文件cherry-pick 序列会互相冲突并且会复现大量死掉的中间状态。分支的最终树才是被评审过的产物按路径做有范围的二进制补丁能保留其最终的增、改、删、重命名意图同时又强制与更新的main产生冲突并显式解决。分支里还混有 Cua Driver 收敛范围之外的工作TypeScript 工具链迁移、Docker 清理它们需要独立的评审与回滚边界快照中生成的 Lume 0.3.14 文档也不得回放最终文档 PR 要从当前 Lume 0.3.15 源码重新生成。为什么是 7 个 PR7 这个数字正好贴合自然的接缝一个共享基础类型化证据 testkit所有后续 PR 都依赖它编译、三个平台孤岛互不重叠的 crate、两个存在真实依赖链的 Linux 显示后端后续 PR以及一个文档/清理收尾 PR。更少会退化成不可评审的整体更多则会把Cargo.toml、platform-linux/src/lib.rs这类共享文件拆出更多碎片评审收益却不会增加。落地结果8 次合并与一次审计修正计划文件的开头就给出了完整落地记录这是计划 vs 结果的对照表计划切片落地 PR结果Docker 清理旁路#2177合并为8cfdd416TypeScript 工具链旁路#2178合并为dd0102eb1/7 类型化 E2E 基础#2179合并为107915af共享 fixture 日志修正#2181合并为2df3fbd2/7 Windows 收敛#2180合并为88f88e1b114/114 接受行3/7 macOS 收敛#2183合并为1d0ff7cc133/133 接受行4-5/7 Linux X11 与 Wayland 收敛#2182合并为51a8e259X11 与 Sway 均 108/108 接受行6/7 Nix 整合#2184替换 PR最终精确运行记录在收敛日志中7/7 文档与替换清理本次替换 PR平台真相、贡献者指引、发布接线、过时 fixture 移除、源码生成的 Lume 0.3.15 引用一个值得注意的适应性调整原始七片设计把 Linux X11 与 Wayland 分开最终却合并为 #2182 一次落地因为两者的最终修复共享同一 Linux 后端与同一精确验证源。共享 fixture 的小修正#2181则单独落地以保持基础 PR 的可评审性。合并后的审计修正堆栈落地后一次独立的冻结树评审发现了一个共享文件遗漏protocol_schema_test.rs只保留了 Windows 的 delivery/scope 断言丢掉了 Linux 断言和 Linux 特有的set_agent_cursor_motion应用值检查。后续修正恢复了冻结的跨平台契约并让 Windows 单元 CI 真正执行该 schema 测试此前只编译不执行。原 parity 注释声称该文件是有意整合的说法是错误的——没有任何驱动实现或已接受的 E2E 矩阵行为因此丢失。范围治理严格白名单、保留队列与覆盖不变式严格全局白名单7-PR 堆栈范围内的路径被严格限定在libs/cua-driver/rust/**crates、tests、Skills、Cargo.toml、Cargo.lock、READMElibs/cua-driver/tests/**、libs/cua-driver/docs/**、README.md、scripts/**、wayland-helper/**scripts/ci/**与nix/cua-driver/**、flake.nix一组明确的 GitHub workflowe2e-rust-windows.yml、e2e-rust-linux.yml、e2e-rust-linux-wayland.yml、ci-rust-linux.yml、ci-rust-windows.yml、ci-nix-linux.yml、cd-rust-cua-driver.yml、ci-release-reminder.yml以及被删除的ci-cua-driver-interactive-linux.yml、nix-build.yml、nix-screenshot.yml、nix-wayland.ymldocs/content/docs/concepts/{how-cua-driver-is-validated.mdx,index.mdx,meta.json}与docs/content/docs/reference/cua-driver/**根文档README.md、CONTRIBUTING.md、Development.md、TESTING.md保留队列被排除在 7 个 PR 之外的工作三块工作不属于 Cua Driver 收敛范围被放入保留队列旁路 ADocker 清理删除根目录过时的Dockerfile与.dockerignore从当前main单独发一个两文件 PR。旁路 BTypeScript 工具链让 TypeScript workspace 拥有自己的 pnpm 配置、typecheck 前先构建 core、生成物不进格式化涉及package-lock.json、libs/typescript/package.json、.pre-commit-config.yaml等六个文件。生成器适配Lume 文档docs/content/docs/reference/lume/{cli-reference,http-api}.mdx必须从当前 0.3.15 源码重新生成绝不回放快照中的 0.3.14 字节。分离强制每个堆栈分支在 push 前必须运行下面这条命令并得到空输出确保没有旁路文件混入 Cua Driver PRgit diff --name-only origin/main...HEAD | grep -E -x \ (Dockerfile|\.dockerignore|package-lock\.json|\.pre-commit-config\.yaml|libs/typescript/.*|\.github/workflows/(ci-lint-typescript|claude-auto-fix)\.yml|docs/content/docs/reference/lume/.*)覆盖不变式git diff --name-status origin/main...codex/link-e2e-videos中的每一个文件都必须恰好属于一个堆栈 PR、旁路 PR或被 main 演进取代。执行中发现任何无主或双主文件立即停下并先修订本计划。第 7 节会机械地验证这一不变式。7 个 PR 的分层设计职责、拥有路径与新鲜门槛堆栈使用统一前缀codex/conv2-0N-slugPR 标题为 conventional-commit 风格并带(conv2 N/7)后缀全部 squash-merge正文都链接 #2161 与本计划。PR 1类型化证据基础conv2-01-typed-evidence落地类型化 testkitjournal/observer/sentinel/E2E 结果类型、cua-e2e-report二进制、核心录制重构、共享场景目录、跨平台 fixture 更新与证据链接脚本——一切后续 PR 都编译依赖它。拥有路径包括整个cua-driver-testkitcrate含 cfg 门控的windows_setup.rs、cua-driver-core的cdp.rs/recording.rs/recording_tools.rs/tool.rs、跨平台测试的重命名与新增capture_contract_test.rs、cross_platform_behavior_test.rs、e2e_environment_preflight_test.rs、protocol_schema_test.rs以及删除5 个已被取代的 modality 测试它们消费旧 testkit APIPR 1 之后无法编译。Cargo.lock通过cargo check重新生成绝不复制。PR 2Windows 收敛conv2-02-windowsWindows 平台修复输入注入、WGC 采集、UIA 缓存、录制钩子、类型化 Windows E2E 测试、sandbox/runner 与 CI 接线并退役focus-monitor-wincrate。新增agent_cursor_windows_test.rs、desktop_scope_windows_test.rs、launch_windows_test.rs删除已被取代的guard_ux_test.rs。工作区rust/Cargo.toml中的一行成员移除也归此 PR手工编辑。PR 3macOS 收敛conv2-03-macosmacOS AX/输入/tool 修复类型化 macOS 套件桌面作用域、已安装应用启动、TextEditfixture 与 smoke 更新以及自托管 runner 的 E2E 脚本。注意增量中没有 macOS E2E GitHub workflow——脚本在自托管/本地 runner 上调用。PR 4Linux 核心与 X11 收敛conv2-04-linux-x11Linux 平台核心AT-SPI、输入投递、overlay、健康报告、录制钩子、X11 路径、类型化桌面作用域套件、X11 E2E 脚本与 workflow退役交互式 Linux workflow。platform-linux/src/lib.rs只做hunk 级修改仅添加pub mod recording_hooks;一行。PR 5Wayland 后端收敛conv2-05-waylandWayland 后端ext-toplevel、sway IPC、portal 截图、持久虚拟指针、libei、共享的嵌套注入协议代码、Wayland 视频、portal-libei → portal-input portal-capture特性拆分、Wayland E2E workflow/脚本、GNOME helper 扩展并把portal-input送进发布二进制。这些模块今天都真实存在于 wayland/ 下ext_toplevel.rs、sway_ipc.rs、persistent_vptr.rs、portal_screenshot.rs、libei.rs、shell_helper.rs等。嵌套注入路线在 PR 6 打包并验证其拥有的 compositor 环境之前保持休眠/实验状态。PR 6嵌套 compositor / Nix 整合conv2-06-nix重写flake.nix与 nix/cua-driver/package.nix使用新特性名、嵌套 compositor 补丁、删除 21 个已被取代的.nix测试文件与三个独立 nix workflow统一收拢到ci-nix-linux.yml。PR 7文档与替换清理conv2-07-docs-cleanup落地描述收敛后状态的全部文档删除类型化证据管线取代的旧录制/fixture 语料接线发布提醒校验清单并解决main上唯一的冲突docs/content/docs/concepts/meta.json。同时整目录删除linux-container/**5 文件、modality-recordings/**16 文件、vision-agent-test/**2 文件三组旧 fixture。共享文件冲突处理规则路径不相交的所有权消除了绝大多数冲突但共享文件需要明确规则共享文件涉及 PR规则rust/Cargo.lock1、2、4、53 视依赖而定绝不整文件复制最终态每个 PR 手改 manifest 后经cargo check --workspace重新生成对等审计用cargo tree做语义比较而非逐字节比较rust/Cargo.toml工作区仅 PR 2增量仅为focus-monitor-win成员移除PR 2 手改那一行crates/cua-driver-testkit/**仅 PR 1整个 crate含 cfg 门控的windows_setup.rs随 PR 1 落地lib.rs处于最终态且处处可编译crates/platform-linux/src/lib.rsPR 4、5hunk 拆分PR 4 加pub mod recording_hooks;PR 5 加pub mod video_wayland;谁也不整文件 checkoutcrates/platform-linux/Cargo.toml、crates/cua-driver/Cargo.toml仅 PR 5已验证两文件增量全部是 portal 特性拆分platform-linux/src/wayland/mod.rs仅 PR 5全部 Wayland 模块接线归 PR 5共享场景目录scenarios.json仅 PR 1最终态超集随 PR 1 落地平台 PR 需要目录修正时须在 PR 1 落地前修订 PR 1而不是在自己的 PR 里改tests/fixtures/README.md、scripts/ci/README.md仅 PR 7记录 PR 1-5 的增与 PR 7 的删允许合并间隙中暂时超前/滞后workflow 文件每文件单一所有者一个 workflow 绝不分属两个 PRdocs/content/docs/concepts/meta.json仅 PR 7main上唯一的冲突手工合并把 #2161 的意图新增页面条目应用到当前 main 的文件上绝不git checkout分支版本堆栈整体的与 main 冲突策略每个分支都从当前origin/main新鲜切出并按路径转移最终态因此唯一可能出现的冲突就是 #2161 分叉后main上又改过的文件。转移前对比git diff origin/main...codex/link-e2e-videos --name-only -- owned paths与git log origin/main --sincebranch-point -- owned paths任何在main上有新历史的路径都按meta.json的方式手工合并并在 PR 正文注明。转移配方与通用新鲜门槛每 PR 的通用转移配方从干净 worktree 出发把owned paths替换为该 PR 的显式文件清单目录同时含旁路或共享文件时禁用宽目录git fetch origin git switch -c codex/conv2-0N-slug origin/main # 保留 #2161 最终态的增/改/删/重命名意图与当前 main 树做三方合并 SNAPSHOT_BASE$(git merge-base origin/main codex/link-e2e-videos) git diff --binary --find-renames $SNAPSHOT_BASE codex/link-e2e-videos -- \ owned paths | git apply --3way --index # 共享文件 hunk见上节手工编辑不要 checkout 整个文件 cd libs/cua-driver/rust cargo check --workspace # 诚实重新生成 Cargo.lock通用新鲜门槛凡触及libs/cua-driver/rust的 PRcargo fmt --all --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace # 宿主机可运行的子集 cargo test --workspace --no-run # 证明 e2e/平台测试仍可编译历史证据 vs 新鲜门槛——支配性规则历史证据 #2161 / 收敛分支上的 CI 运行以及 e2e-convergence-journal.md 中的运行记录。它证明最终树曾经作为一个整体工作过可写进 PR 描述供评审者参考。新鲜门槛 在每个新堆栈分支的头 SHA 上实际执行的命令/workflow 运行。只有这些才允许合入门槛。历史证据永远不能替代新鲜门槛——因为每个堆栈 PR 都是收敛分支上从未存在过的树状态有基础无平台、有 X11 无 Wayland……。依赖图与顺序落地流程PR 1 合并后PR 2、3、4 可并行准备与评审PR 5–7 严格串行于各自父节点之后旁路 A/B 相互独立可在 #2161 关闭前任意时刻落地。顺序落地流程要点每个 PR 从当前origin/main切出绝不从兄弟堆栈分支切执行转移配方旁路分离 grep 输出必须为空在 PR 正文附上 workflow 运行链接/命令输出并把历史证据明确标注为历史——已被上方新鲜运行取代。评审后 squash-merge下一个 PR 从新的main重新切出再跑一次最终态转移成本低且按构造无冲突——优先重切而非 rebase在 #2161 上留言进度 conv2 N/7 landed as #NNNN。新鲜门槛失败在该堆栈分支上修复这正是拆分的目的若修复属于更早的层先向该层落地 follow-up。绝不允许用拉入旁路文件的方式修一个 Cua Driver PR。收尾最终白名单树形对等审计PR 7 合并后从最新 checkout 执行三类验证。首先是对等性对第 2.1 节每个路径main必须等于 #2161 的树git fetch origin git diff origin/main codex/link-e2e-videos -- \ libs/cua-driver nix/cua-driver flake.nix scripts/ci \ .github/workflows/e2e-rust-windows.yml .github/workflows/e2e-rust-linux.yml \ .github/workflows/e2e-rust-linux-wayland.yml .github/workflows/ci-rust-linux.yml \ .github/workflows/ci-rust-windows.yml .github/workflows/ci-nix-linux.yml \ .github/workflows/cd-rust-cua-driver.yml .github/workflows/ci-release-reminder.yml \ .github/scripts/tests/test_cua_driver_release_wiring.py \ docs/content/docs/concepts docs/content/docs/reference/cua-driver \ README.md CONTRIBUTING.md Development.md TESTING.md允许的残余差异恰好三类其他任何差异都意味着漏文件并阻塞关闭 #2161libs/cua-driver/rust/Cargo.lock——重新生成两棵树用cargo tree --workspace语义比较docs/content/docs/concepts/meta.json——相对更新的main手工合并落地过程中有意适配的文件——每个都必须在 #2161 最终评论的适配台账中登记一行所属堆栈 PR 提交 确切理由main 推进了这类笼统例外不可接受。其次验证旁路对等两个旁路合并后应输出为空并确认 Lume 引用保留的是当前源生成的 0.3.15 而非快照的 0.3.14git diff --name-only origin/main codex/link-e2e-videos -- \ Dockerfile .dockerignore package-lock.json .pre-commit-config.yaml \ libs/typescript .github/workflows/ci-lint-typescript.yml \ .github/workflows/claude-auto-fix.yml # 两个旁路合并后期望为空台账登记的适配除外 rg -n Version: 0\.3\.15|Documented against Lume \*\*0\.3\.15\*\* \ docs/content/docs/reference/lume/{cli-reference,http-api}.mdx最后验证覆盖不变式把增量文件清单与第 3 节所有权清单 第 2.2 节保留队列取并集必须 1:1 吻合git diff --name-only origin/main...codex/link-e2e-videos | sort /tmp/delta.txt # 与第 3 节所有权列表 第 2.2 节的并集对比必须一一对应审计输出作为 #2161 的最终评论归档。处置以已关闭而非已合并收尾当所有替换收敛 PR、旁路 #2177/#2178 均已合并审计运行且残余差异限定在三类之内Lume 两条路径登记为源码生成的 0.3.15 适配且关闭评论把 #2161 的每个主题映射到落地 PR/旁路 PR/被 main 取代的记录之后以closed, not merged关闭 #2161。codex/link-e2e-videos分支的删除要等三件事关闭满 30 天且无 parity 回归不早于 2026-08-11首个 post-landing cua-driver 发布在收敛 workflow 上绿灯通过ci-release-reminder校验清单白名单上的最终git diff重跑仍干净。在此之前分支保留作为 parity 审计与堆栈 PR 中历史证据链接的取证参考。这套体系在仓库中的今天类型化证据管线的源码证据计划中 PR 1 落地的类型化证据 testkit今天就是仓库里实实在在的 cua-driver-testkit crate。它把整个 E2E 收敛的核心思想固化成了可执行的类型与校验逻辑类型化的场景契约在 e2e.rs 中每个测试单元cell被建模为CaseSpec包含PlatformWindows/macOS/Linux、DisplayServerWin32/Quartz/X11/Wayland、TargetingAX/PX/Page、Deliverybackground/foreground、Scopewindow/desktop与DriverRoute等维度。DriverRoute枚举把驱动内部真实的数据投递路径显式化Windows 的WindowsTargetedInjection/WindowsSendInput/PostMessage/UiaInvokemacOS 的MacosCgEventPid/MacosCgEventHidLinux 的LinuxAtSpiAction/LinuxXTest/LinuxLibei/LinuxCuaCompositorInjecte2e.rs。独立的成功判定oracleOracleKind区分FixtureState、AxState、Pixels、Focus、ZOrder、Cursor、NoLeakedInput、Protocole2e.rs这正是计划所强调的独立 oracle 定义成功——一个ok响应如果没有应用侧的状态变化仍然是失败。CaseSpec::validate会强制校验refusal 契约只允许 background delivery、必须声明结构化拒绝码、且必须携带 Focus/ZOrder/NoLeakedInput 三类副作用 oraclee2e.rs。结构化拒绝码RefusalCodebackground_unavailable、background_occluded、background_uipi_blocked等e2e.rs让诚实拒绝成为一等公民——拒绝只有当精确代码符合预期且桌面状态未变时才判过。报告器cua-e2e-reportbin/cua-e2e-report.rs 是计划中提到的 CLI 二进制读取--declarations/--results/--environment三个 JSONL可选--artifact-root校验证据产物与--require-video强制视频证据环境记录冲突、schema 不支持或EnvironmentStatus::Error都会直接失败环境错误以退出码 2 结束拒绝环境失败悄悄变成缩水绿矩阵。证据链接脚本scripts/ci/link-e2e-evidence.sh 用 awk 把摘要表的每个行为行与所属 lane 的工件 URL 链接起来对应计划里每行证据链接到所属工件的要求。配套的 test-matrix.md 与 test-harnesses-guide.md 则把两层测试模型写成了日常贡献指引单元/协议测试回答驱动是否做出了确定性决策harness E2E 测试回答动作是否真的到达真实桌面表面。两篇文档都反复强调Rust 测试是真相来源Python 测试、旧 shell runner 与历史录制脚本不属于规范 E2E 路径规范命令无套件选择器Linux 为scripts/ci/linux/run-rust-e2e.shWindows 为scripts/ci/windows/run-rust-e2e.ps1 -RequireGuimacOS 为libs/cua-driver/tests/runners/macos-lume/run-all.sh。收敛日志 e2e-convergence-journal.md 中的 Validation Snapshot 记录了最终接受证据Windows 114 行93 投递 21 精确拒绝、macOS 133 行、Linux X11 与 Sway 各 108 行、Nix 源码三检查全绿——这些数字与计划落地结果表一一对应。文档 how-cua-driver-is-validated.mdx 将同一模型表述为协议正确性与桌面观测行为是两种不同的证据。方法论总结巨型 PR 治理的可迁移要点只落增量不落历史长命分支唯一可评审的产物是最终树310 个互相改写的提交不应成为评审负担。按路径拥有强制覆盖不变式每个文件恰好一个所有者无主/双主立即叫停共享文件用 hunk 拆分、语义比较、手改生成物等方式隔离。历史证据与新鲜门槛分离历史证据只作上下文合入门槛必须在每个新分支头 SHA 上重跑。旁路队列保护主题边界范围外工作拿到独立 PR 与独立回滚边界用机械 grep 强制分离。回滚边界随 PR 定义每个 PR 都写明revert 恢复什么、依赖哪些后续 PR让任意子集可安全回退。收尾审计取代相信流程树形对等审计 适配台账 覆盖不变式三连验证只允许三类可解释残余差异。对于正在处理超长 PR 分支、跨平台测试收敛或大型重构落地的团队pr-2161-landing-plan.md 连同它产出的 e2e-convergence-journal.md 与 cua-driver-testkit 源码是一份可以直接参考的完整工程档案。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考