👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
Add macOS SkyLight background click
目标
为 click 增加显式 click_method=sky_click,让 macOS 能够通过 SkyLight 私有 SPI 向当前 snapshot 对应的目标进程和窗口投递 Chromium-compatible 后台左键点击,同时保持真实鼠标、前台 app、窗口层级和既有 auto 行为不变。
范围
- 包含:
- macOS SkyLight 符号动态解析、窗口定向事件字段、off-window primer 和真实点击序列。
- macOS
click_method路由、参数校验、窗口身份校验和诊断错误。 - Windows / Linux 公共枚举同步,以及显式 unsupported 结果。
- Swift / Go 单元测试、skill usage、架构、安全、可靠性与 history 文档。
- 不包含:
- 修改
auto路由或让现有app_post自动升级为 SkyLight。 SLPSSetFrontProcessWithOptionsforeground assist、跨 Space snapshot、隐藏或最小化窗口恢复。- Chromium 网页右键、Canvas / Unity / Blender 等只接受全局 HID 的 surface。
- 发布、打 tag、提交或推送远端。
- 修改
背景
- 相关文档:
docs/ARCHITECTURE.md、docs/SECURITY.md、docs/RELIABILITY.md、skills/open-computer-use/references/usage.md。 - 相关代码路径:
ComputerUseService.click、InputSimulation.clickTargeted、AccessibilitySnapshot.AppSnapshot、三平台click_methodparser / schema。 - 已知约束:显式方法不能静默 fallback;目标窗口必须来自当前 snapshot;私有 SPI 必须通过
dlopen/dlsym运行时探测;第一版只承诺同一 Space 内仍为 on-screen 的遮挡窗口。
风险
- 风险:SkyLight 函数和 raw event field 都是未公开 ABI,可能随 macOS 更新失效或崩溃。
- 缓解方式:集中封装函数签名和字段、缺符号时 fail closed,并在 macOS 14 / 15 / 26 与签名 app 制品上验证。
- 风险:SkyLight 与公开
postToPid双投递可能在某些非 Chromium surface 产生重复动作。 - 缓解方式:
sky_click保持显式且不进入auto,用单次计数 fixture 检查重复投递;若出现重复则把内部 post policy 收敛为 SkyLight-only。 - 风险:过期 snapshot 的 window id 可能已被销毁或复用。
- 缓解方式:投递前检查
CGWindowID的 owner pid 与 on-screen 状态,不匹配时要求重新执行get_app_state。 - 风险:primer 坐标或不支持的鼠标类型命中意外目标。
- 缓解方式:primer 同时使用 off-window screen/local 坐标;第一版只接受左键和 1–2 次点击。
里程碑
- 实现 SkyLight SPI、纯事件 recipe 与 macOS 显式路由。
- 同步三平台协议、测试和使用文档。
- 运行单元、跨平台、skill、smoke 与本地能力验证,完成 history 后归档计划。
验证方式
- 命令:
swift build、swift test。 - 命令:
(cd apps/OpenComputerUseWindows && go test ./...)。 - 命令:
(cd apps/OpenComputerUseLinux && go test ./...)。 - 命令:
npm run package:skill、./scripts/run-tool-smoke-tests.sh。 - 命令:
OPEN_COMPUTER_USE_RUN_SKY_CLICK_LIVE_TEST=1 swift test --filter SkyClickLiveTests(隔离 Chrome profile + 本地页面)。 - 手工检查:
tools/list三平台均暴露sky_click,Windows / Linux 在 snapshot lookup 前返回 unsupported。 - 观测检查:macOS 缺失 SkyLight capability、错误 window owner、非左键或超出双击范围时不发送事件;成功路径不调用
.cghidEventTap或 app activation。 - 实机检查:Chrome 按钮在被其他窗口完全遮挡时只触发一次,前台 PID、真实 cursor position 和目标窗口 z-order 不变。
进度记录
- 完成文章、Cua Driver、yabai 与 OCU 现有输入路径的源码调研。
- 完成 SkyLight SPI 与 macOS
sky_click路由。 - 完成跨平台协议、测试和文档。
- 完成自动化验证与受控实机验证。
- 完成 history 并归档 execution plan。
决策记录
- 2026-07-22:公共参数使用
click_method=sky_click,保持显式 macOS-only;Windows / Linux 返回稳定 unsupported。 - 2026-07-22:第一版不修改
auto,也不引入会 raise / 切 Space 的SLPSSetFrontProcessWithOptions。完全遮挡 Chrome 实测证明只用SLEventPostToPid不足,因此按文章与 yabai pattern 加入可恢复的SLPSPostEventRecordToAppKit-active 切换。 - 2026-07-22:事件 recipe 以当前 Cua Driver Chromium 路径为基线,包含 window-local 坐标、PID/window 字段、move primer、off-window primer 和 click-group id。
- 2026-07-22:
CGEventSetWindowLocation的动态函数指针按 Cua Rust bridge 的(CGEventRef, double, double)标量 ABI 声明,并用无投递的 runtime test 验证字段写入,避免依赖 SwiftCGPoint聚合参数推断。 - 2026-07-22:focus-without-raise begin/restore 各自保留 40ms event-record 间隔,真实 mouse-up 后保留 100ms renderer settle;受控 Chrome 页面验证单次触发、前台 PID、真实 cursor 和 z-order 均不变。