企业官网建设流程全解析

Cua Driver 0.13.2 发布前稳定化实战：光标徽章、空间动作审计与跨平台认证体系

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

Cua Driver 是基于 Rust 的原生桌面与浏览器自动化运行时，通过 MCP、CLI 以及进程内 Python/TypeScript SDK 向终端中的 AI Coding Agent 提供跨平台操作能力。本文围绕仓库中 0.13.2-overnight-stabilization-plan.md 这一发布前稳定化计划展开，系统梳理其在 0.13.1 发布之后、0.13.2 正式发布之前需要完成的核心工作项：光标尺寸与会话徽章的修正、全量空间动作审计、macOS 认证流程的 hermetic 化、安装器基线核验、发布自动化恢复、Linux 进程控制静默成功修复，以及对应的跨平台验证矩阵与合并纪律。读完本文，你将掌握这套"稳定化而非发布"工程流程的完整组织方式，以及仓库中与光标渲染、会话徽章、动作分类相关的源码实现细节。

1. 计划定位：稳定化工作，不是一次发布操作

该计划的基线是已发布的 Cua Driver 0.13.1，源码基线锁定在origin/main的1e77ab5536eb88ca4cb7d3b6cc1fb51eea03f0e4。计划的核心边界非常明确：

• 目标：让main分支处于"随时可以打 0.13.2"的状态，但绝不创建、发布、推广或合并 0.13.2 版本，0.13.2 的正式发布由 Francesco 在次日负责。
• 性质：这是稳定性与正确性工作（stabilization and correctness work），而不是发布操作（release operation）。

计划列出了八条目标，可概括为四类：

1. 产品行为修正：缩小默认光标、修正会话徽章、审计每个空间动作使光标移动到动作目标；
2. 工程流程修复：落地 macOS 认证的 hermetic 化（PR #2660）、解决 0.13.1 周边最高影响的回归、恢复未来版本的自动发布流程；
3. 验证闭环：在 macOS、Windows、Linux 上对最终合并的mainSHA 做验证，并保留包括 GUI 行为视频在内的可审查证据；
4. 文档对齐：更新公开文档与安装后引导，使任何行为变化都有对应说明。

配套的执行日志 0.13.2-overnight-execution-journal.md 记录了实际执行进度与基线事实，其中明确指出：原工作树保留用户改动不动，执行工作树仅含本计划与日志；基线默认光标显示尺寸为 48 逻辑点；基线生产徽章使用纯深色背景；基线徽章标记用fill_rect绘制所以是方形的。

2. Definition of done：完成判定的完整清单

计划的"完成定义"是一份可核查的验收清单，任何一项不满足都不能宣布完成：

• 每个被接受的产品或工作流修复都通过聚焦的 PR 合入main；
• 生产光标在 macOS、Windows、Linux X11、Linux Wayland 上都更小；
• 会话徽章在短暂展示后淡出、使用约定的会话强调色渐变、包含圆形会话圆点；
• 每个受支持的空间动作要么把 Agent 光标移动到其解析出的目标，要么在文档中说明该动作为何没有空间目标；
• 空间动作审计具备契约测试和代表性 E2E 证据；
• PR #2660 与当前main同步、经评审、完全验证并合入；
• Issue #2655 需要两次连续的同 SHAmacOS 认证运行，且不依赖陈旧 worker 状态；
• 规范的 Cua Driver 安装器在任何源码构建验证开始前，先解析并安装已发布的 0.13.1 构件；
• 最终合并的mainSHA 通过相关的确定性 Linux 与 Windows CI；
• 在行为变更适用的平台（macOS、Windows、Linux X11、Linux Wayland）存在代表性桌面 E2E 证据；
• 每个 GUI 成功都由外部可观察效果证明，而不仅仅是ok: true——这条约束杜绝了"工具报告成功但实际无效果"的假阳性；
• 后台声明的焦点、z-order、真实光标、遮挡与输入隔离都有证据；
• 公开文档、生成参考、示例与安装后指引与最终行为一致；
• PR 标题与标签准确描述发布影响，并通过发布元数据校验；
• 不发生任何 release、tag、包发布、部署或 Release Please PR 合并；
• 执行日志记录最终mainSHA、已合并 PR、精确测试结果、构件、限制与剩余负责人。

3. 操作边界：稳定化期间的工作纪律

计划对执行过程设置了严格的边界，这些约束保证了多任务并行时不互相污染：

• 每个新的工作单元都从最新抓取的origin/main开始；
• 保留现有脏工作树，所有实现都使用干净分支或 worktree；
• 每个独立回归保持一个聚焦 PR；
• 只有在 PR 精确 head 具备所需测试与证据后才合并；
• 不绕过必要的人工评审或受保护分支规则；
• 不与独立积压或贡献者 PR 评审工作重叠；
• 改编提交的作品时保留外部贡献者署名；
• 不引入破坏性公共 API、CLI、SDK、协议或配置变更，除非先征询；
• 不弱化产品断言，也不把行为失败改称为环境失败；
• 公开构件不得包含凭据、私有基础设施细节、机器特定路径和原始会话数据；
• 使用 0.13.2-overnight-execution-journal.md 作为"活"的执行日志。

4. P0：光标尺寸、会话徽章与空间动作修正

这是整个计划中产品可见度最高的一项，包含四个已确认的产品需求：

1. 让默认光标可见地更小，同时在浅色与深色背景上保持可读性；
2. 会话名称徽章随光标出现，在短暂可读间隔后仅徽章淡出，光标可见性与闲置行为保持独立；
3. 让生产徽章与仓库 web harness 一致：会话强调色渐变背景、圆形会话色圆点、居中标签、紧凑间距与光标间隙、一致的 backing-scale 行为；
4. 审计每个公开动作，修复那些更新了语义图标但没有把 Agent 光标移动到解析目标的空间动作。

4.1 渲染器架构原则

实现层面的第一条原则是：把原生 Skia 渲染器当作生产事实来源（source of truth），web harness 只是视觉契约与评审面。这意味着仓库中的 web 端（tools/cursor-gallery）与 cursor-themes.md 里提到的静态 cursor gallery 只是审阅工具，真正的像素与时序都来自生产渲染器。

4.2 渲染器自有的徽章揭示时钟

计划要求新增"渲染器自有"的徽章揭示时钟，包含明确的 hold 与 fade 时长，并在会话标签首次设置以及新会话变得可见活跃时重置。这一设计在 render_state.rs 中落地为两个常量：

pub const SESSION_BADGE_HOLD_SECS: f64 = 2.0; pub const SESSION_BADGE_FADE_SECS: f64 = 0.4;

对应的session_badge_alpha()实现了一个平滑的 fade：hold阶段内保持 1.0，超过 2 秒后按fade * fade * (3 - 2*fade)（smoothstep）在 400ms 内从 1 过渡到 0。徽章淡出是确定性的、每个会话独立，并且只在徽章本身缺失时禁用。值得一提的是，session_badge_hovered允许真实指针悬停在合成光标上时临时重新揭示已淡出的徽章，但不会改变一次性揭示计时器——这正是计划"光标可见性与闲置行为保持独立"的源码体现。

4.3 徽章外观的契约级细节

session_badge.rs 中定义了徽章的完整布局常量，可直接对照计划中的视觉要求：

计划中"不要接受 Agent 控制的任意徽章颜色"在源码中通过两条机制落实：

• session_fill_rgba(session_id)（见 theme.rs）：匿名/默认光标固定为 Cua 蓝[94, 192, 232, 255]，命名会话则从 9 色调色板中稳定哈希出一个填充色，并发 Agent 因此视觉可区分，但不存在 Agent 可注入的颜色参数；
• paint_session_badge使用LinearGradient以会话填充色为基色构造三段渐变，浅色/深色变体被限定在固定区间内。

"圆形会话圆点"则通过rounded_rect路径（用贝塞尔常数 K=0.5522848 构造圆角矩形）替代原先fill_rect的方形标记实现，代码注释也明确记录了这一变更动机。徽章绘制在光标下方且不随光标朝向旋转。

4.4 会话标签的净化

由于会话标签来自外部，sanitize_session_label会在渲染前：移除控制字符、将连续空白折叠为单个 ASCII 空格、按 Unicode 标量计数截断到 28 字符并在超长时以…结尾。源码注释强调"运行时 key 与传输标识符绝不能传入此函数"，因为徽章只是显示元数据，会话所有权仍然使用私有运行时 key——渲染友好名称绝不会削弱会话隔离。

4.5 空间动作审计与移动语义

计划要求建立一个完整的动作-移动清单（action-motion inventory），每项包含：公开工具、语义动作、目标来源、预期移动、平台实现、外部 E2E oracle。至少要审计：

• click、double click、right click、drag、scroll；
• type text、set value、press key、hotkey；
• 浏览器侧的 click、drag、scroll、type、fill、press key、hotkey；
• navigation、app、transfer、record、system、observe 动作。

移动语义分成两类：

• 有空间目标（解析出坐标或元素边界）：在 dispatch 之前把 Agent 光标移动到目标，同时为后台投递保留真实指针；
• 无空间目标：光标保持在当前位置，仅在原地播放语义状态动画（例如向已聚焦的桌面应用输入文本）。

同时要求：每个带显式会话的分类公开工具都必须发出语义 begin/end 事件；新增平台聚焦测试证明空间动作在 dispatch 前发送了正确的 keyed move 命令；跑完仓库光标画廊并录制完整动作与修饰键序列；在四个平台上跑真实动作序列并独立验证应用效果、录制视频。

执行日志中的 Phase 1 记录了对这部分的具体落地：

• 共享原生与 GNOME 光标占用从 48 降到 42 逻辑点（theme.rs 中DISPLAY_SIZE: f32 = 42.0）；
• 引入独立的 2 秒 hold + 400ms fade 时钟；
• 把会话强调色渐变徽章移植进生产渲染器，矩形标记替换为圆形会话 orb；
• GNOME Shell 渲染器升级到 API 版本 7，保持相同尺寸、徽章与淡出行为；
• 空间 glide 或 click pulse 派发时保留活跃语义状态，text/scroll/drag 等状态不再被navigate或click覆盖；
• macOS/Windows 增加索引式与 token 寻址的文本移动；Linux 文本与值移动改用声明的会话光标而非匿名默认光标。

5. P0：让 macOS 认证流程 hermetic 化

跟踪项为 Issue #2655 与 PR #2660。背景是 macOS 认证运行依赖陈旧 worker 状态，导致结果不可复现。计划要求：

1. 把最新origin/mainrebase/merge 进 PR 分支且不丢失既有证据；
2. 重跑 shell 语法、ShellCheck、聚焦脚本测试、Rust 格式化与全部变更路径 CI；
3. 预检 macOS Lume 主机与 guest：主机与 guest 磁盘空间充足、已登录 GUI 会话、安装精确源码 SHA、TCC 身份与授权正确、无陈旧 daemon/socket/fixture/Cargo target/构建缓存归属问题、证据输出空间充足；
4. 在同一精确 PR SHA 上连续跑两遍完整 macOS 认证矩阵；
5. 每次运行都必须：创建运行自有的全新构建命名空间；自己负责 daemon 启动、权限模式、socket、watchdog、关闭与恢复；执行声明的每一行；保留初次尝试与允许的精确单元重试；记录行级截图、日志、视频与外部 oracle；成功或失败后都恢复正常 daemon；
6. 失败先分类再动手：产品失败→修产品行为并重启精确 head 验证；harness 失败→修 harness 但不弱化断言；环境失败→通过预检或独立系统证据证明后，在修复的代表性环境中重试；
7. 更新 PR body 记录最终精确 SHA 与两次连续运行链接；
8. 确认test(cua-driver)标题与no-release标签仍准确；
9. 评审与检查通过后合入；
10. 确认合并的 PR 关闭了 #2655。

仓库中的 macos-lume 测试运行器 与该流程配套，scripts/tests/test_macos_lume_runner.py 提供对应的脚本测试。

6. P0：验证已发布的安装器基线

跟踪项为 Issue #2654（0.13.0 安装器 404 的回归）。核心思路是先验证"已发布"基线，再谈新工作：

1. 验证规范的 Unix 与 Windows 安装器能解析已发布的 0.13.1 组件 tag；
2. 验证该组件 release 下存在预期的 macOS、Linux、Windows 构件；
3. 在每个平台执行一次全新安装与一次从先前支持版本的升级；
4. 验证：安装的可执行文件路径、cua-driver --version、源码或发布来源、daemon 启停、一次代表性 MCP 冒烟测试；
5. 如果 0.13.1 已解决 0.13.0 的 404，记录证据并关闭 #2654；
6. 任何规范路径仍失败，则在聚焦 PR 中修复并重跑全部安装器契约测试后再合并。

配套的安装器实现位于 scripts/install.sh、scripts/install.ps1，以及 scripts/_install-common.sh / scripts/_install-common.psm1，回归测试见 scripts/tests/install-windows-regression.ps1 与 scripts/tests/test_install_version_fallback.py。

7. P0：恢复未来版本的安全自动发布

跟踪项为 Issue #2662。要求恢复"Release Please PR 合并后"的正常发布路径：不可变组件 tag、必需的构建与验证依赖、GitHub release 发布、版本锁定的 PyPI 与 npm SDK 发布；同时：

• 保持 PR 评论与 checkbox 控件无法触发版本号提升或包发布；
• 保留人工恢复派发（recovery dispatch）但不作为常规路径；
• 为以下场景增加确定性 workflow 测试：合法组件 tag 推送、必需构建失败、tag 与 SHA 不匹配、禁用 PR 评论/checkbox 路径、显式恢复派发；
• 验证 workflow 时不创建tag、release 或包发布；
• 合并前必须通过发布元数据与 workflow 测试。

8. P0：修复 Linux 静默进程控制成功

跟踪项为 Issue #2661。这是典型的"工具报成功但无效果"假阳性问题，包含两个可复现缺陷：

• kill_app报告成功但进程仍存活；
• launch_app.launch_path留下挂起的 shell 子进程而未执行。

修复要求改变契约本身：

• kill_app必须验证目标已退出，否则返回结构化失败；
• PID 复用不能产生假成功；
• launch_path安全排空或重定向子进程管道；
• 启动完成具有有界、可观察的条件；
• 被遗弃的子进程必须被回收（reap）；
• 不支持的 sandbox 行为显式失败。

此外要求增加确定性单元与集成覆盖、跑代表性 Linux X11 与 Wayland E2E；只有当现有授权环境可用时才跑 gVisor 等价证明，否则明确声明 gVisor 仍未证明、不得宣称该平台已修复。合并的唯一前提是：产品不能再静默报告一个毫无效果的进程控制成功。

9. P1：COSMIC 无障碍广告与拖拽动画

9.1 不在 COSMIC 上启动屏幕阅读器（#2630）

计划要求：从源码与代表性 Linux 会话确认当前默认行为；对未知桌面优先采用安全默认——启用通用 AT-SPI 检查，但不宣称屏幕阅读器处于活动状态；为确实需要完整广告的环境保留显式覆盖开关；增加 GNOME、COSMIC、已知非 GNOME 桌面、混合桌面标识与未知桌面的回归测试；在 Linux Wayland 上验证 Orca 与 Speech Dispatcher 不启动、无障碍检查仍可用、代表性动作仍能完成；必要时更新 Linux 排障与无障碍文档。仓库的 Linux 支持技能文档 是此类说明的落点之一。

9.2 拖拽光标动画（#2625）

要求把拖拽动画为连续的点对点手势而非标准光标移动；保持生产光标紧凑、会话着色、浅深背景可读且跨平台一致；保留既有语义动作与投递修饰键；为拖拽开始、连续行进、到达目的地、释放、取消/拒绝增加确定性渲染或时间线测试；每个代表性平台至少验证一条前台与一条后台拖拽路径；在支持的平台录制短视频；更新光标个性化文档与预览 harness；并明确该变更与正确性、发布流程修复分开提交。

10. 跨平台验证矩阵

计划用一张矩阵定义"最小证明"标准，核心原则是：托管 CI 只能证明确定性构建与单元契约，当声明依赖焦点、z-order、TCC、合成器路由或可见光标行为时，真实交互桌面不可替代。

11. 文档与示例审计

产品 PR 稳定后，需审计公开教程、how-to、参考页、生成工具 schema、示例与安装后输出，并验证：

• 0.13.2 发布前，0.13.1 始终被描述为已安装基线，任何页面不得声称 0.13.2 可用；
• 安装器指引使用规范组件解析；
• 权限与会话示例与已发货契约一致；
• 光标个性化文档覆盖所需状态与拖拽时间线；
• Linux 无障碍指引解释安全广告默认值与覆盖开关；
• 在用户可操作的场景中记录进程控制错误与超时。

此外需用仓库自有生成器重新生成检查入库的参考，跑链接、格式、生成输出与敏感信息扫描，并把内部执行笔记排除在公开页面之外。仓库中的 cursor-themes.md 即是此类文档的典型代表，其中详细记载了 42 逻辑点生产占用、2 秒展示 + 400ms 淡出、hover 揭示、chip 淡出等行为。

12. PR 合并纪律与最终合并-main 认证

每个独立单元一个聚焦 PR，计划明确列出了 7 个单元：光标尺寸/徽章/动作移动正确性、#2660 macOS 认证 harness、#2662 发布自动化、#2661 Linux 进程控制、#2630 COSMIC 无障碍广告、#2625 拖拽动画（除非光标 PR 完全覆盖）、以及无法随产品 PR 落地的纯文档协调。并明确"不得为了减少 PR 数量而合并无关修复"。

每个 PR 的通用纪律包括：最终验证前立即与最新origin/main同步、检查最终变更文件与实时 PR 标题、保留贡献者署名、跑精确相关单元/集成/生成输出/平台检查、附精确 SHA 证据、回应评审、等待必需检查、完成度达标后才合并，并在开始依赖验证前确认main已含该合并。

最终认证阶段：抓取最终origin/main并记录精确 SHA；跑受影响的确定性 Rust、脚本、安装器契约、发布元数据、文档、Python SDK、TypeScript SDK 检查；跑受影响的 macOS/Windows/Linux X11/Wayland 代表性 E2E；验证规范 0.13.1 安装仍可用（源码构建测试必须报告其源码 SHA，不得与发布二进制混淆）；验证没有任何 tag、GitHub release、PyPI 版本、npm 版本或安装器内置版本被改为 0.13.2；最后发布内部就绪报告，包含已合并 PR 与 issue、最终mainSHA、各平台结果、视频与运行链接、受支持/拒绝/不可用/未证明单元，以及留给 Francesco 次日 0.13.2 发布的精确剩余工作。

13. 停止条件、升级条件与明确排除

计划允许在普通实现选择、测试失败、flaky 基础设施修复、文档变更与 PR 反馈范围内自主推进；孤立失败运行、VM 崩溃、磁盘写满、CI 超时等可恢复缺陷都不是停止理由，应保留证据、修复环境或实现后重试。只有以下情况才停下询问：

• 公共契约需要破坏性变更；
• 必需的代表性环境需要新的付费基础设施或凭据；
• 发现安全漏洞；
• 需要破坏性或不可逆的外部动作；
• 会发生 release、tag、部署或包发布；
• 受保护分支或必需人工评审阻止本可完成的合并。

明确排除项包括：创建或发布 0.13.2、合并 0.13.2 的 Release Please PR、常规积压清理、评审无关贡献者 PR、无回归驱动地重构 daemonless 架构、超出可复现 issue 需要地扩展权限策略、未经明确批准更改公共契约。这确保了稳定化窗口内所有改动都是"就事论事"的。

14. 收尾：可验证的工程方法论

从这份计划可以看到，一次高质量的发布前稳定化不是"修几个 bug"，而是一套完整的工程闭环：先锁定基线 SHA 与发布边界，用 Definition of Done 定义可核查的完成标准，用操作边界保护并行工作，用聚焦 PR 隔离变更，用同 SHA 重复认证消除环境偶发，用外部 oracle 取代ok: true假阳性，最后用文档审计和最终合并-main 认证封板。对读者而言，无论是维护 Cua Driver 本身，还是为任何跨平台 GUI 自动化项目制定发布前质量流程，这份文档与仓库中 cursor-overlay 渲染器的对应实现（session_badge.rs、render_state.rs、theme.rs）都是可直接对照学习的范本。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code