👾 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
Visual Cursor Overlay
目标
让 open-computer-use 在 click 路径上具备一套可见的软件 cursor overlay:点击前能沿曲线移动到目标点、点击时有明确的视觉反馈、点击后可以短暂停留并做轻微 idle sway,随后自动隐藏,同时继续保持当前 AX 优先、尽量不抢焦点的执行策略。
范围
- 包含:
- 为
mcp模式补一个可承载 AppKit overlay 的主线程 runtime。 - 实现独立透明窗口的软件 cursor overlay。
- 把
click路径接到 overlay,但不改变现有 AX 优先 / HID fallback 的决策。 - 增加必要测试,并同步 README、架构文档和 history。
- 不包含:
- 本轮不复刻官方闭源 cursor 的私有素材、完整 choreography 或私有事件注入链路。
- 本轮不把 drag、scroll、键盘输入全部接入统一 overlay。
背景
- 相关文档:
docs/ARCHITECTURE.mddocs/REPO_COLLAB_GUIDE.mddocs/references/codex-computer-use-reverse-engineering/software-cursor-overlay.mddocs/PLANS_GUIDE.md- 相关代码路径:
apps/OpenComputerUse/Sources/OpenComputerUse/OpenComputerUseMain.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/ComputerUseService.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/InputSimulation.swift- 已知约束:
- 当前
mcp模式是同步readLine()主循环,没有长期运行的 AppKit event loop。 - 官方实现已有独立
Software Cursor窗口和 Bezier motion 证据,但开源版目前没有 overlay UI。 - 点击路径已经做过 AX 优先收敛,新增 overlay 不能把这层行为边界改坏。
风险
- 风险:为了跑 overlay 而改动
mcpruntime,可能影响现有 stdio 读写稳定性。 - 缓解方式:保留最小变更面;只在 visual cursor 开启时切到 AppKit runtime,并让 stdin 读取仍保持串行。
- 风险:overlay 的 AppKit UI 可能干扰 smoke suite 或普通 app 点击命中。
- 缓解方式:overlay window 设为透明、忽略鼠标事件,并给 smoke suite 留显式关闭开关。
- 风险:视觉动画与真实动作不同步,反而让用户更困惑。
- 缓解方式:把 overlay 明确设计成“视觉提示层”,动作仍按现有 AX/HID 路径执行,并让点击脉冲只围绕最终目标点展开。
里程碑
- Runtime 与 overlay 基础设施落地。
click路径接入 visual cursor。- 验证、文档同步与归档。
验证方式
- 命令:
swift test./scripts/run-tool-smoke-tests.sh- 当前结果:
swift test通过。./scripts/run-tool-smoke-tests.sh仍然卡在既有list_apps/fixture 约束:当前AppDiscovery.listCatalog()只收敛带 bundle-id 的 user-facing app,而 smoke fixture 是直接运行的可执行文件,不会出现在这条输出里;这不是本轮 visual cursor 引入的回归。- 后续 follow-up 已继续收敛 cursor 尺寸、官方 asset fallback 和相对目标 window 的排序逻辑;该部分继续保持
swift test通过。 - 手工检查:
- 对一个真实 app 连续执行多次
click,确认 overlay 会在目标点附近短暂停留并做轻微 idle sway,随后自动消失。 - 在 AX action 命中场景下,确认点击后前台 app 不会被额外
activate。 - 观测检查:
CGWindowListCopyWindowInfo能看到open-computer-use进程下存在一个透明 overlay window。
进度记录
- 里程碑 1
- 里程碑 2
- 里程碑 3
决策记录
- 2026-04-17:优先实现“独立 overlay window + 曲线移动 + 点击脉冲 + idle sway”,不试图在这一轮复刻官方的全部私有 choreography。
- 2026-04-17:
mcp模式只在 visual cursor 开启时切到 AppKit runtime,避免把一整轮 runtime 重构强行施加到所有无 UI 场景。 - 2026-04-17:smoke 继续显式关闭 visual cursor;因为这条回归链路的目标是验证 tools 行为闭环,而不是验证 UI 动画本身。
- 2026-04-17:对于官方 bundle 资产,优先采用“运行时读取 + 本地处理后绘制”的方式,而不是把闭源图片直接 vendoring 到开源仓库里。