👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
架构总览
这个仓库当前已经从模板收敛成一个本地 computer-use 项目。主线仍是 Swift 实现的 macOS automation MCP server,同时新增了实验性的 Windows 和 Linux runtime,用独立 Go 二进制暴露同一组 9 个 native Computer Use tools;Codex plugin 再在 native MCP 之上增加持久 Node.js REPL,向模型暴露 js / js_reset。
当前目录结构
apps/OpenComputerUse主入口,负责mcp、doctor、list-apps、snapshot、call、turn-ended等 CLI 命令,以及-h/--help/-v/--version这类全局参数;不带参数启动时会先检查权限,只有缺失时才进入无 Dock 图标的 app 模式权限引导窗口,doctor也只会在检测到缺失权限时拉起这套 onboarding UI。apps/OpenComputerUseFixture本地 GUI fixture app,用来承载低风险、可预测的点击/输入/滚动/拖拽验证路径。apps/OpenComputerUseSmokeSuite端到端 smoke runner,会拉起 fixture 和 MCP server,并通过 JSON-RPC 真实调用 9 个 tools;同时也支持单独的 visual cursor idle smoke,用跨进程 observation file 断言等待下一次 move 时是 anchored tip + tiny rotate wobble,而不是横向漂移。apps/OpenComputerUseWindows实验性 Windows runtime。它不依赖 Swift 或.appbundle,Go CLI/MCP 入口会嵌入 PowerShell UI Automation bridge,构建产物是open-computer-use.exe,并随已有 npm 包的dist/windows/<arch>/bundled artifacts 分发。apps/OpenComputerUseLinux实验性 Linux runtime。它不依赖 Swift 或.appbundle,Go CLI/MCP 入口会嵌入 Python AT-SPI bridge,构建产物是open-computer-use,并随已有 npm 包的dist/linux/<arch>/bundled artifacts 分发。packages/OpenComputerUseKit核心库,包含:- MCP stdio transport 与 tool registry
- app discovery
- Accessibility / 窗口 snapshot
- 键鼠输入模拟
- software cursor overlay
- fixture test bridge
experiments/CursorMotion独立的 Swift cursor motion lab,用于试验Bezier + arc + spring参数模型、调参 UI 和独立渲染,不直接耦合主 MCP runtime。experiments/StandaloneCursor新的独立 Swift cursor viewer,直接复用scripts/cursor-motion-re/official_cursor_motion.py里收敛出来的候选路径、score 与 raw spring timeline,用来观察更贴近 binary lift 的表现。scripts/仓库级自动化命令,包括 smoke test、.app打包入口、Windows.exe/ Linux binary 构建入口、npm 分发脚本、GitHub Release direct-download archive 打包、scripts/node-repl/的 JS REPL adapter 与 npm CLI controller,以及scripts/computer-use-cli/这个用于探测官方 bundledcomputer-use的 Go helper。skills/面向 agent runtime 的可安装 skill。当前skills/open-computer-use/SKILL.md只作为轻量入口和目录,安装、MCP/CLI 使用、排障等细节拆到相邻references/文件里按需加载;scripts/package-skill.sh负责校验并打包.zip/.skill制品。docs/逆向分析、执行计划、history 和项目约束。
运行分层
1. App Mode 层
OpenComputerUse默认 app 模式会拉起PermissionOnboardingApp。- app bundle 以
LSUIElementagent-style 形态运行,默认不在 Dock 暴露常驻图标,但仍可按需显示权限窗口。 - 当用户从终端执行 macOS 版
open-computer-use mcp、doctor、call、snapshot或list-apps时,CLI 会先通过 LaunchServices 启动同一个.appbundle 的隐藏 app agent,并通过用户临时目录下的 Unix domain socket 转发请求;真正调用 Accessibility、ScreenCaptureKit 和动作 tools 的进程始终是Open Computer Use.app,不是 iTerm / Terminal / Node launcher。默认 Socket 文件名保持历史兼容;嵌入式宿主可设置OPEN_COMPUTER_USE_AGENT_SOCKET_NAMESPACE,使其使用 namespace 摘要对应的私有 Socket,避免与其他 OCU bundle 共用 Agent。 - CLI 与 MCP proxy 会把调用进程中
OPEN_COMPUTER_USE_*前缀的环境变量随请求转发给 app agent,并只在该请求执行期间临时覆盖 agent 环境;这让click_method=global的进程级安全门和 debug 开关在 app-agent 架构下仍按调用方配置生效。 - 主窗口负责渲染
Accessibility/Screen & System Audio Recording两类权限卡片、Allow/Done状态和 relaunch 后的状态收敛;当两项权限都已完成时会自动关闭,不再要求用户手动退出。 - 辅助 drag panel 会跳转到对应的
System Settings页面;点击Allow后,panel 会从主窗口里的按钮位置做一段 spring + curved frame 的入场,再落到System Settings内容区下沿。panel 默认保持在窗口右侧内容区下方居中并固定贴近窗口底边,不再依赖实时扫描权限页内部+ / -控件行;窗口层级上会显式排在当前System Settings窗口之上,避免被权限列表内容盖住,同时尽量减少对系统设置自身滚动区域的干扰。panel 内也补了显式返回按钮,允许用户中断当前 guidance、回到 onboarding 主窗口重新选择权限步骤。 - 权限状态会合并 TCC 持久授权记录与当前 app 进程的 runtime preflight:TCC 中任一匹配 client 已授权即可视为 granted,避免 CLI 子进程与 GUI app 对授权状态看到不一致的结果;如果当前
.app进程已经通过AXIsProcessTrusted()/CGPreflightScreenCaptureAccess(),也会立即视为 granted,避免 stale 或不匹配的 TCC path 记录让 onboarding 浮层继续停留。正式 release 仍以 CI 打出来的Open Computer Use.app为准,而本地 debug/dev 打包现在显式命名为Open Computer Use (Dev).app,并在 dev bundle 运行时优先认当前 dev 副本,避免系统设置里出现两个完全同名的条目。
2. MCP 层
- 面向 MCP host 的外部 transport 仍是
stdio;macOS 终端 CLI 到.appapp agent 之间额外有一层本地 Unix domain socket 代理,用来保证真实 automation 运行在 app bundle 权限身份下。 - 当
OPEN_COMPUTER_USE_VISUAL_CURSOR未被显式关闭时,mcp命令会切到一个最小 AppKit runtime:主线程保留 event loop 承载 overlay UI,stdio server 仍在后台线程串行读取与响应。 - 请求 framing 采用一行一个 JSON-RPC message。
- 当前支持的 method:
initializenotifications/initializednotifications/turn-endedpingtools/listtools/call
notifications/turn-ended是开源版显式的 turn boundary hook;收到后会清理当前进程里的 visual cursor overlay、occlusion keep-alive 和 agent display。CLIopen-computer-use turn-ended [payload]也会通过 macOS distributed notification 通知正在运行的 AppKit MCP / app-agent 进程执行同一类清理,用于接 Codex legacy notify 的 after-agent payload。stdio server 退出和 app-agent client connection 关闭也会执行该 session cleanup。
3. Tool Service 层
ComputerUseService负责把 Computer Use tool 请求映射到本地能力,ComputerUseToolDispatcher则把 native tool 的参数解析与 service 方法分发收敛成 MCP server 和open-computer-use call共用的一层。- Codex plugin 的
.mcp.json默认不再把 native tools 直接暴露给模型,而是启动scripts/node-repl/open-computer-use-repl.mjs。adapter 以 child MCP client 连接同一个 native runtime,并只对外列出js/js_reset;JavaScript 通过异步 app-bound API(cua.getApp(...)、app.click(...)、app.getAXState()等)调用 native tools。 - REPL 使用 Node.js 自带的 evaluator,因此保留 top-level
await和跨调用 lexical bindings;真正执行代码的 kernel 位于 Worker 中,超时会终止 Worker 并重建干净 session,避免while (true)挂死 MCP transport。 - npm launcher 还直接提供
ocu js和ocu repl:前者为一次性 Worker/native MCP session,后者在当前终端内保留同一个 session 和 binding;两者退出后都会关闭 Worker 与 native MCP child。ocu capabilities [--json]在不启动 native MCP 的情况下报告 Node、adapter、kernel 和当前平台 native artifact 是否齐全。help 始终显示 code-first 命令并标记 availability,不按环境动态隐藏接口。 - npm bin 当前本身通过
#!/usr/bin/env node启动,因此完全没有 Node 的 shell 无法进入 help/capability 检测;launcher 启动后会复用process.execPath,不会再次从 PATH 解析 Node。若未来要求零 Node 前置,应把最外层入口替换成 native bootstrap 或随包分发 Node。 - 这是增量迁移:
open-computer-use mcp仍是原生 9-tool compatibility surface,已有 CLI、其他 MCP host 和 smoke 不需要切换。 list_apps通过 Spotlight metadata query 拉取标准 application 目录里的 app bundle,并读取kMDItemUseCount/kMDItemLastUsedDate_Ranking这类系统元数据;再与NSWorkspace的运行态 app 合并,输出“当前运行中 + 近 14 天用过”的视图。get_app_state优先走真实 AX / 窗口截图;真实 app 必须同时有未最小化的AXWindow和可匹配的 on-screenCGWindow。如果目标 app 只是隐藏或暂时没有 on-screen window,会先 best-effort unhide / activate /open -b/AXRaise并短暂重试,以贴近官方computer-use会把 Lark / Electron 窗口拉回再采集的行为;恢复后仍无法匹配时返回官方风格的Apple event error -10005: cgWindowNotFound,不再把 application 根节点或无截图窗口伪装成可操作状态。当目标是仓库内 fixture app 时,回退到 fixture 导出的合成状态。真实 AX tree 默认在 macOS、Linux、Windows 上最多渲染 1200 个节点、64 层深度;显式get_app_state/snapshot可通过max_tree_nodes/max_tree_depth覆盖预算,action tools 的刷新结果仍使用默认预算。snapshot 文本默认截断到 500 字符;显式get_app_state/snapshot可通过text_limit正整数或"max"覆盖,action tools 的刷新结果仍使用 500 字符默认值。对 Electron/WebView 这类深层 UI 会压缩空AXGroup/AXUnknownwrapper、过滤AXScrollToVisible噪音和空字符串属性,避免 action-critical 的输入框被无语义容器挤出节点预算;但通用节点中的AXPress/AXConfirm/AXOpen子节点会形成文本摘要边界,避免多个可点击选项被合并成一个 container。这类动作节点如果 frame 有效、尺寸紧凑且不包含带 URL 的AXLink后代,会保留为带窗口相对Frame的button,并用短文本后代作为按钮摘要,让 icon-only 和文字 Web 控件都能获得可区分的element_index;包含带 URL 的AXLink后代时保留通用 wrapper 和链接子节点,避免导航链接被摘要吞掉。对原生 open panel / Finder column view 这类把内容放在AXContents/AXVisibleChildren里的控件,也会把可见文件项纳入元素树。- MCP 的 9 个核心 tools 的 description / input schema 按官方
computer-use文案和参数面收敛,macOS 额外提供query,尽量减少 host 侧提示词和 tool surface 偏差。 - JS REPL 的 API 和当前官方 code-first 形态对齐到异步 app binding,而不是把离散 tools 简单包成同步函数。snapshot 的
windowPlacement以及 keyboard action 的keyMethod会转换成 native tool 的 snake_case 参数。实现不复制或运行 proprietary@oai/*package;协议和行为记录在docs/references/js-repl.md。 open-computer-use call <tool> --args '{...}'会直接输出 MCP-style JSON result;open-computer-use call --calls '[...]'/--calls-file <path>会在同一进程里顺序执行 JSON 数组里的 tool calls,并复用同一个ComputerUseService内存态,因此get_app_state之后的 action tool 可以继续使用同一轮 snapshot 的element_index。序列执行默认会在成功的相邻操作之间 sleep 1 秒,也可以用--sleep <seconds>覆盖;遇到isError=true的 tool result 后停止。- 对真实 app 的
get_app_state/ action tool 入口,当前只保留一层密码管理器 bundle denylist:bundle-id 直传时直接返回 safety denial;名称匹配时默认不解析到这些 app。终端、Chrome / Atlas 和系统组件不再属于内置阻止目标。 - 普通 app 的 element frame 当前按“窗口左上角为原点”的 window-relative 坐标输出,便于后续把
element_index和截图坐标统一到同一套参考系。 - 三个平台的显式
get_app_state均支持include_ax/include_screenshot,默认 true,至少保留一项。JS 对应includeAX/includeScreenshot,CLI snapshot 提供同名连字符参数。关闭 AX 跳过树、焦点和选区,并使旧快照 / 查询索引及别名失效;关闭截图跳过捕获与编码,元素操作仍可用,截图坐标操作须重新获取图片。参数经 macOS app agent 转发;不改变动作回读,也不做自动图片去重。见 按需观察。 - macOS 额外提供
query和select_text,当前 native surface 为 11 个工具;Linux / Windows 仍为 9 个核心工具。JSapp.selectText(elementIndex, text, {prefix?, suffix?, selection?})复用快照或 query 索引,支持选中文字及前后光标。按字面文本和 UTF-16 定位、拒绝歧义;写入前及返回前检查会话,验证文本未变且实际选区等于请求,即使关闭完整回读也不能省略验证。失败通过 nativeisError/ JS 异常传出;结果刷新使用 read-only recovery,不通过激活、键盘或真实指针补救。 click/set_value在执行真实动作前后,会额外驱动一层透明SoftwareCursorOverlaywindow:两者的移动阶段现在共用一条 heading-driven 的官方风格 motion 内核,显式把“当前 cursor 朝向”和“最终 resting pose”一起喂给选路器,优先生成需要时先掉头、再沿车头方向推进的 C 形/单侧大弧轨迹;首次显示时按官方 binary 的 fresh state 从 AppKit 全局(0,0)window origin 生成起点,后续动作继续复用上一帧 visible tip。真正显示出来的 cursor 不再直接等于 path sample,而是经过一层独立的 visual dynamics 状态,把 visible tip、velocity、angle 和 fog/offset 持续推进。click结尾会衔接 click pulse 和更明显但仍然很小的 rotate wobble,set_value则只做 settle / idle,不给 pulse;两者收尾后会在目标点继续保持 idle 状态,等待下一次动作时 tip 保持 anchored、只保留可感知的小角度摆动;只有连续 30 秒没有新动作时才做 cleanup,这样连续 tool call 不会反复从 fresh(0,0)起步;如果宿主在任务 / turn 结束时发出turn-ended,cursor 会立即消失并清掉本轮位置状态。- overlay 用目标点相对窗口的锚点跟随窗口移动;行进、settle、点击反馈和 idle 都读取最新缓存帧,发现位置变化时直接重定位可见 tip 并清掉旧速度。窗口帧在后台串行读取,最多 30 Hz、同时最多一个请求,避免 AX 阻塞渲染线程;优先读取快照持有的 AX 窗口,仅在没有 AX 元素时使用窗口列表,读取失败保留最后有效帧。只保留当前窗口的追踪状态,reset / idle 超时后释放;这层跟随只调整显示位置,输入投递仍走既有路径。
- overlay 的 visual style 不再自己从官方 app bundle 裁
SoftwareCursor小图;主 MCP runtime 现在和CursorMotion一样优先渲染仓库里沉淀的official-software-cursor-window-252.pngbaseline,只有资源缺失时才退回OpenComputerUseKit内部的程序化 pointer/fog fallback。命中点 anchor 仍固定在126x126画布里的同一组 tip-offset 上;glyph 自身的 neutral heading 继续沿用CursorMotion/ 官方 baseline 的-3π/4。主 runtime overlay window 按 AppKit 全局坐标移动,因此在把 AX /CGWindowList产出的 y-down screen-space 点击目标喂给 overlay 之前,会先转换成对应屏幕的 AppKit 全局坐标;路径选路用屏幕上实际可见的 AppKit forward heading,进入 visual dynamics / render state 前则把 velocity 的 y 轴翻回 CursorMotion 的 y-down screen state,再交给 AppKit 绘制层做角度和dy翻转。程序化 fallback 保留 neutral artwork correction,把它的天然轮廓轴对齐到CursorMotion/ 官方 baseline 的-3π/4forward 方向,但不让实验线依赖 runtime 代码。 - overlay 的层级不再固定
.floating;现在会跟随 snapshot 命中的目标 window id / layer,把自己排到该目标 window 之上,而不是粗暴压到所有前台 app 最上层。 - overlay 的曲线路径不再只按固定 Bezier 模板生成;当前主线采用 reverse-engineering 约束下的 heading-driven candidate 族,候选只保留
direct/turn/brake/orbit这些能稳定产出单侧主弧的 family,并继续保留 target-window 命中策略作为同类候选间的 tie-break。原始 binary lift 恢复出来的20条路径和 score 仍然保留在独立的StandaloneCursorviewer / Python 重建脚本里,用于对照分析,不再直接作为 runtime 默认 chooser。 - overlay 的 progress 曲线也不再是固定
easeInOut;主线现在复用官方response=1.4、dampingFraction=0.9、dt=1/240的 spring/VelocityVerlet形状,默认 move 时长对齐已恢复出的 close-enough endpoint-lock 时间343 / 240 = 1.4291667s,不再按路径距离额外压缩。 - overlay 不再依赖临时
terminal settle补丁来修尾;主线现在统一改成“路径层给目标点,visual dynamics 层给可见姿态”的双层模型,所以 move 末段、pulse 和 idle 共用同一套状态,不会再出现 endpoint 锁住后只剩原地翻角的收尾。 - overlay 的渲染输入也从单一
rotation扩展成rotation + cursorBodyOffset + fogOffset + fogScale,让速度滞后能真正体现在画面上,而不是只存在于主循环内部状态;其中rotation现在按二进制里SoftwareCursorStyle.angle + CursorView._animatedAngleOffsetDegrees的分层去近似,不再把“跟随运动方向的主朝向”和“小幅 wiggle offset”压成同一个受限小角度。 - 动作型 tools 对普通 app 采用“非侵入优先,物理指针路径显式 opt-in”策略:
perform_secondary_action只执行目标元素已经暴露出来的 AX action;Safari 这类 AppKit custom action descriptor(例如Name:close tab ...)会显示为短名称并准确映射回过滤后的原始 AX action,避免 raw/rendered action 错配;短名称与其他显示名称或任一其他原始 AX action(包括被过滤的动作,忽略大小写)冲突时保留完整 descriptor,保证输出 selector 不被原始动作精确匹配抢占;无效或歧义 action 返回官方风格的... is not a valid secondary action for ...,fixture 的Raise路径也不再为了测试去准备全局物理指针输入set_value会先用AXUIElementIsAttributeSettable(kAXValueAttribute)判断目标是否真的是可设置值元素,只有 settable 时才调用AXUIElementSetAttributeValue;不可设置时返回官方风格的 non-settable 错误,不退到键盘输入、剪贴板或未公开的文本替换接口click.click_method是开源版的可选扩展,支持auto(默认)、accessibility、app_post、sky_click和global。未传参数时继续使用原有自动路由;显式模式不会静默 fallback 到其他实现。accessibility只接受element_index;其余 mouse 路径可以使用element_index的计算落点或原始x/y坐标。- element-targeted
click的auto左键路径会先试原生列表的AXSelectedChildren选择,再试AXPress/AXConfirm/AXOpen这类真正语义化的激活动作;如果目标本身不可点,还会继续尝试其子孙 AX 元素(例如 Finder sidebar row 下面暴露AXOpen的 cell)和命中点附近的 AX hit-test 结果,最后进入现有 non-AX 分支:未开启全局指针环境变量时使用postToPid定向鼠标事件,开启时直接使用全局 HID 事件。AXRaise/kAXMainAttribute/kAXFocusedAttribute这类 activation-only fallback 只允许窗口级元素使用,避免普通静态文本或容器把“获得焦点”误报成“点击已处理”;click_count > 1也会优先重复可用的 AX action。 - 显式
click_method=accessibility只执行上述 AX 语义动作;显式click_method=app_post绕过 AX 候选和后代扫描,直接通过CGEvent.postToPid向目标进程发送mouseMoved/ down / up;显式click_method=sky_click只在 macOS 接受左键单击/双击,它验证当前 snapshot 的CGWindowID仍为同一 PID 所有且 on-screen,仅通过SLPSPostEventRecordTo让目标应用短暂进入 synthetic-active 状态,绝不向真实前台应用发送 defocus record,再按 Chromium-compatible recipe 发送 target move、(-1,-1)primer 和真实 down/up。每个鼠标事件同时经动态解析的SLEventPostToPid与公开postToPid投递,并带 window-local location、PID/window 和 click-group 字段;renderer settle 后只撤销目标的 synthetic-active 状态。sky_click的 action-result snapshot 刷新也禁止 activate /AXRaise恢复,目标状态瞬时不可读时直接失败。它不改变auto,任一步失败也不 fallback。显式click_method=global同样绕过 AX,但通过.cghidEventTap发送系统级指针事件。global还必须设置OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1,否则在移动 visual cursor 或发送输入前拒绝请求。 get_app_state解析目标窗口时先看 on-screen 窗口,再退到所有窗口,所以位于其他 Space 的窗口不会触发 activate / raise 恢复;拍到未被遮挡的窗口后会关闭它的 WindowServer occlusion 通知(WindowOcclusionKeepAlive),之后被遮挡或切换 Space 时 Chromium / Electron / WebKit 仍保留页面与AXWebArea。keep-alive 保存 SPI 返回的原始开关状态,并在 turn-ended、MCP/app-agent connection 关闭、server 正常关闭或进程退出时恢复;恢复失败的记录保留到后续重试。因为 snapshot 会维护该状态,macOSget_app_state不声明readOnlyHint。Chromium 系 app 的 web AX tree 是懒加载的,窗口可见时最多重走 3 秒,被遮挡时在 tree 末尾追加说明。sky_click不再要求窗口 on-screen。详见docs/references/macos-window-visibility-and-spaces.md。- 窗口截图主路径是 WindowServer 的
SLSHWCaptureWindowList(任何 Space、被遮挡均可,15–45 ms),ScreenCaptureKit 为 fallback;AX root window 通过_AXUIElementGetWindow直接绑定CGWindowID。输入 recipe 的固定间隔都是环境变量可调的校准旋钮,默认值来自基准测试(见docs/references/macos-window-visibility-and-spaces.md)。 get_app_state.window_placement是开源版的可选扩展:keep(默认)、agent_display、restore。agent_display通过AgentDisplay+packages/OpenComputerUseVirtualDisplayShim创建 agent 专用 virtual display,用 AX 位置把目标窗口的 frame 移过去(不激活、不抬升),让已被遮挡或在其他 Space 的窗口对其 app 真正可见;restore按 app PID 恢复当前 runtime 停放的全部窗口,session cleanup 或进程退出也会恢复全部窗口并销毁显示器。恢复失败时保留原位置记录和 virtual display,避免把未恢复窗口误记为成功并允许后续重试;已关闭的窗口则直接清除记录。shim 捕获私有 KVC/selector 的 Objective-C exception,并把不兼容系统收敛为创建失败。Windows / Linux 对非keep值返回 unsupported。type_text.key_method/press_key.key_method是开源版的可选扩展,支持auto(默认)和 macOS-only 的sky_key。sky_key复用sky_click的 target-only synthetic-active record,再投递 yabai 的 make-key-window record 让目标 app 在进程内把当前 snapshot 窗口设为 key window,之后走现有CGEvent.postToPid键盘路径;带cmd的单字符组合键改为在目标 AX 菜单栏找到对应菜单项并AXPress。它不要求窗口 on-screen(可用于其他 Space),但对隐藏 app fail closed;action-result snapshot 与sky_click一样使用 read-only recovery policy。- 对 renderer 合成的 summary
text行,click不再默认点击父容器中心;这类元素使用左侧安全锚点。对普通 row/container/text 的后代候选,也会过滤右侧紧凑 hover action(例如 Lark / Electron 会话列表里的“完成”勾),避免把主行点击误操作成 side action;Electron/Lark 这类 app 的 WebArea 合成文本会优先寻找紧邻的行级AXPress祖先并静默执行,避免用物理鼠标点行。浏览器 WebArea(例如 Chrome/GitHub)不走这条 Electron-scoped 行级祖先点击优化,仍保留通用 link/container 点击路径。命中点如果只反查到覆盖整页的 Electron/WebArea 级 AX 元素,不再继续扫描整个大容器的子孙候选,避免一次行点击被远处的可点击元素截走。 AXUIElementCopyElementAtPosition做坐标命中,尽量把 coordinate click 反解成可操作 AX 元素CGEvent.postToPid定向发送键盘事件,避免为了type_text/press_key抢前台;type_text会把文本按 Unicode extended grapheme cluster 聚合成小批量keyboardSetUnicodeString事件,避免中文标点、emoji / 代理对和组合字符被逐个 UTF-16 code unit 拆开后在 Electron 富文本输入框里乱序或变形。如果当前 focused element 的AXValue可设置,type_text会优先按可编辑内容追加并写回AXValue,这覆盖 Feishu / Electron 富文本输入框不可靠接收后台键盘事件的场景,并会过滤已知占位提示,避免把 placeholder 拼进草稿;如果当前 focused element 不是可编辑文本目标,type_text会报错要求先 click 文本输入区或使用set_value,不再把无效果的后台键盘投递当成成功;press_key的 xdotool parser 覆盖官方 binary key table 里常见的BackSpace、Page_Up、Prior/Next、F1...F12和KP_*aliasscroll.pages对齐官方1.0.755的numberschema,支持小数页数;整数页且目标暴露AXScroll*ByPage时优先走 AX action,否则用CGEvent.postToPid向目标进程定向发送 scroll eventdrag仍是 coordinate-only API,但默认不再使用全局.cghidEventTapmouse event;默认改为CGEvent.postToPid定向发送 mouse move / down / dragged / up 事件,避免移动用户真实硬件光标;这些 coordinate tool 的x/y先按 screenshot pixel 坐标解释,再依据截图像素尺寸与目标 window bounds 的比例映射回 window point / Quartz global 坐标,避免 Retina 窗口上把 2x 像素误当成 1x point 导致点击落到错误位置click/scroll/drag在环境变量未开启的默认配置下不会走全局.cghidEventTap,因此不会移动或抢占用户真实鼠标;OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1是全局指针能力的进程级安全门,显式click_method=global仍必须通过这层授权。默认路径不再为了 fallback 调用NSRunningApplication.activate。drag的结果会在 snapshot 文本之后、截图之前附带一条Drag delivered via ...文本项,说明本次走的是app_post定向投递还是全局指针路径;默认路径下同时说明postToPid事件不经过 window server,因此无法驱动窗口移动、文本拖选、Finder 拖放这类 window server 拖拽会话。drag的 tool description 也同步说明了这一限制和对应环境变量。显式开启全局路径后,拖拽使用默认 event source 向 HID tap 投递,按距离插值并为每步写入位移 delta;macOS 26+ 的 down / dragged / up 还会共享一个手势事件编号,使 window server 能识别窗口移动、文本拖选和 Finder 拖放所需的真实拖拽会话
4. Fixture Bridge
OpenComputerUseFixture会把自己的窗口与元素状态写到临时 JSON 文件。- 对 fixture 的
get_app_state和少量测试专用动作,会通过FixtureBridge走显式 command 通道。 - 这个 bridge 只服务于仓库内 deterministic smoke path,不是面向真实第三方 app 的能力边界。
- 因为 SwiftPM 裸 executable 形式启动的 fixture 没有稳定的 bundle identifier,
list_apps会仅对OpenComputerUseFixture注入一个内部 synthetic identifier,保证 smoke suite 仍能覆盖list_apps,普通第三方 app 仍按真实 bundle id 输出。
5. Cursor Lab
StandaloneCursor是一个新的独立 SwiftUI/AppKit demo target,可通过swift run StandaloneCursor本地启动。- 这条线优先验证 Python 重建脚本已经收敛出来的核心:
20条候选路径、measure + score、prefer in-bounds then lowest-score选路,以及response=1.4/dampingFraction=0.9/dt=1/240的 raw spring timeline。 - 当前它刻意不引入 speculative 的 wall-clock duration 映射,也不复用
CursorMotion里更偏视觉手感试验的 pose dynamics。 CursorMotion是一个单独的 SwiftUI demo target,可通过swift run CursorMotion本地启动。- 这条线优先验证 motion model 本身:当前主线是 heading-driven 的 turn / brake / orbit / direct candidate 族、spring progress、独立 visual dynamics 和 debug UI;moving 阶段真正画出来的箭头角度会持续跟随 visual dynamics 的主 heading,接近停住后再平滑回到默认 resting pose,并在 idle 阶段保留原地小摆角。
- lab 的 cursor 视觉继续以
scripts/render-synthesized-software-cursor.swift为参考:优先使用仓库里保存的官方252x252runtime baseline 图,缺失时再退回脚本里的 procedural pointer/fog 近似;settle 态也改成中心固定的小幅摆角,而不是继续沿 XY 轻微漂移。 - 当前它不接真实 tool call,也不回写主
SoftwareCursorOverlay,目的是把实验噪音与产品行为边界隔离开。
6. Windows Runtime
- Windows runtime 位于
apps/OpenComputerUseWindows,以 Go 维护 CLI、call --callssequence、MCP JSON-RPC、tool schema 和进程内 snapshot cache。 - 构建入口是
scripts/build-open-computer-use-windows.sh --arch arm64|amd64,默认输出到dist/windows/<arch>/open-computer-use.exe;npm release package 会把两个 Windows artifact 内置到已有 root/alias packages,Node launcher 按process.platform/process.arch自动选择。 - Go runtime 通过
go:embed带上runtime.ps1,执行 tool call 时临时落盘并调用 Windows PowerShell。PowerShell bridge 使用System.Windows.Automation做 app/window/element discovery、tree rendering、UIA pattern action、ValuePattern set value 和 ScrollPattern scroll;当目标 app 不暴露对应 pattern 时,fallback 到PostMessage/SendMessage形式的 Win32 window message。PowerShell 进程启动时会通过SetProcessDpiAwarenessContext/SetThreadDpiAwarenessContext对齐到物理坐标空间,因为操作文件里的windowBounds和 UIA frame 都是物理像素,而 DPI-unaware 进程的GetSystemMetrics/GetWindowRect返回的是虚拟化尺度。 - Windows runtime 默认只连接已经运行的 app,不会在
get_app_state找不到进程时自动Start-Process,也不会默认允许SetFocussecondary action;这两条前台抢占路径分别需要OPEN_COMPUTER_USE_WINDOWS_ALLOW_APP_LAUNCH=1和OPEN_COMPUTER_USE_WINDOWS_ALLOW_FOCUS_ACTIONS=1显式打开。type_text默认优先对可写文本控件的 child HWND 发送EM_SETSEL/EM_REPLACESEL,不再默认走可能触发前台激活的 UIAValuePattern.SetValuefallback;需要旧行为时必须设置OPEN_COMPUTER_USE_WINDOWS_ALLOW_UIA_TEXT_FALLBACK=1。UIA pattern 和 Win32 message fallback 本身仍是 best-effort:很多控件可以在后台响应,但 Windows 没有一套对所有 GUI toolkit 都等价于 macOS AX 的后台键鼠输入模型。 - Windows screenshot 会先检查主窗口可见、未最小化、未被 DWM cloaked、与 virtual screen 相交,并要求窗口宽高至少 64 像素且面积至少 20,000 像素;
list_apps也只列出通过这组可捕获性检查的窗口。PowerShell bridge 通过后,Go 层还会解码 PNG header 并用同一尺寸门槛复核。任一检查失败时 snapshot 仍可返回 UI Automation tree,但省略 MCPimageblock;coordinate click / drag 会明确失败,element-targeted action 仍可尝试。实现不会为退化窗口放大、补边或生成占位截图。窗口与 virtual screen 的交集判断在物理坐标下进行,因此在 125% / 150% 缩放且窗口完全位于虚拟化屏幕之外时不会误判为不可捕获。 - 这 9 个 tool 的协议面与 macOS 主线保持一致:
list_apps、get_app_state、click、perform_secondary_action、scroll、drag、type_text、press_key、set_value。其中 element-targeted action 会优先复用上一轮get_app_state的 runtime id / automation metadata,coordinate action 使用 screenshot/window-relative 坐标。 - Windows
click_method=accessibility使用 UIA,app_post始终使用 HWND 消息。click_method=global要求OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1;开启后,auto 点击及 scroll 的 UIA 失败回退、drag 也可使用真实指针。press_key的 auto 始终使用窗口消息,真实按键需显式key_method=global及同一环境开关。物理输入通过 SendInput 检查返回值、finally 释放按键 / 鼠标,核对观察的 PID / HWND、最新几何、前台及坐标命中窗口;普通 SetForegroundWindow 失败就拒绝,不模拟 Alt 强行抢前台。macOS-only sky_click / sky_key 继续明确拒绝。见 Windows 输入说明。 - Windows UI Automation 需要运行在已登录用户的桌面 session 里。通过 SSH 作为脱离桌面的后台进程运行时,PowerShell 可以启动并返回 JSON,但系统可能不给它暴露顶层窗口;这种情况下
list_apps会是空,get_app_state可能返回appNotFound(...)。 - Windows 已有独立 WPF 观察 fixture 和 Windows PR smoke,覆盖观察、滚动、物理输入及截图边界。其余工具 / toolkit 覆盖,以及 visual cursor overlay、installer/onboarding、code signing 仍待补齐。后续 TODO 记录在
docs/exec-plans/active/20260422-windows-computer-use-runtime.md。
7. Linux Runtime
- Linux runtime 位于
apps/OpenComputerUseLinux,以 Go 维护 CLI、call --callssequence、MCP JSON-RPC、tool schema 和进程内 snapshot cache。 - Linux 支持与 macOS 一致的
OPEN_COMPUTER_USE_ACTION_READ_BACK:默认保持动作后等待并返回完整快照;设置为0、false、no或off(忽略大小写与首尾空白)时,成功动作只返回ok,跳过回读等待、AX、焦点/选区和截图采集,也不覆盖最后一次显式观察的索引缓存。REPL adapter 已自动设置此开关;调用方应在需要观察时显式调用get_app_state/getAXState(),并在界面变化后刷新索引。ok仅表示动作调用完成,不代表界面已完成更新或任务成功。显式观察不受开关影响,仍返回完整快照。 - 构建入口是
scripts/build-open-computer-use-linux.sh --arch arm64|amd64,默认输出到dist/linux/<arch>/open-computer-use;npm release package 会把两个 Linux artifact 内置到已有 root/alias packages,Node launcher 按process.platform/process.arch自动选择。 - Go runtime 通过
go:embed带上runtime.py,执行 tool call 时临时落盘并调用python3。Python bridge 使用 GNOME/GObject Introspection 暴露的 AT-SPI2 接口做 app/window discovery、accessibility tree rendering、semantic action、editable text、value set,以及 best-effort 的 key/mouse fallback;文本能力通过Accessible.get_interfaces()检测Text/EditableText,不依赖不同 PyGObject 版本未必存在的便捷属性。 - Linux 上最接近 macOS AX 的是 AT-SPI2/D-Bus accessibility,而不是一套统一的后台键鼠输入模型。第一版优先使用元素暴露的 AT-SPI action、EditableText 和 Value 接口;coordinate
click/drag与press_key使用 AT-SPI event synthesis fallback,在 Wayland 下只能按 best-effort 处理。press_key的具名键以 keysym 配合KeySynthType.SYM发送,修饰键以 X modifier mask 配合LOCKMODIFIERS/UNLOCKMODIFIERS保持;PRESS/RELEASE/PRESSRELEASE只接受硬件 keycode,不能传 keysym。 - Linux runtime 需要运行在已登录桌面用户 session 里。缺少
XDG_RUNTIME_DIR、DBUS_SESSION_BUS_ADDRESS或 display 环境时,Go runtime 会在启动 Python AT-SPI bridge 前尝试从/run/user/<uid>和常见桌面进程自动发现当前用户的 session bus、display / Wayland 值;纯 SSH tty 如果找不到已登录桌面 session,可以启动二进制,但不能直接 inspect 或操作 GUI session。 get_app_state的 accessibility tree 在 GTK/GNOME app 上可能很深,Linux bridge 使用与 macOS / Windows 一致的 1200 节点、64 层默认 tree budget,并支持显式提高max_tree_nodes/max_tree_depth。截图通过 GDK root window best-effort capture;GNOME Wayland 可能返回黑图,bridge 会检测全黑采样并省略 image block。- 焦点摘要和选区在快照已经选定的窗口里共用一次查找,分别受
max_tree_nodes/max_tree_depth约束;到深度边界后不再读取下一层子节点,查找未完成时追加明确提示。选中文字使用标准 AT-SPIget_n_selections/get_selection接口读取。实现与隔离 GTK 验证见 Linux 焦点查找。 OPEN_COMPUTER_USE_LINUX_LIGHTWEIGHT_HIDDEN=1可省略明确非 SHOWING 节点的位置、值等详情,保留节点、索引及子树;默认关闭,未知状态继续完整读取。使用方式与真实 GTK 验证见 Linux 隐藏控件详情。- 这 9 个 tool 的协议面与 macOS / Windows 保持一致:
list_apps、get_app_state、click、perform_secondary_action、scroll、drag、type_text、press_key、set_value。其中 element-targeted action 会优先复用上一轮get_app_state的 runtime path metadata,coordinate action 使用 screenshot/window-relative 坐标。 - Linux
click_method=accessibility映射到 AT-SPI action,global映射到 AT-SPI mouse synthesis 并要求全局指针环境变量;AT-SPI 没有等价的进程定向 mouse dispatch,因此app_post和 macOS-only 的sky_click会在 snapshot lookup 前明确返回 unsupported,key_method=sky_key也一样。auto仍保持 AT-SPI action 优先、mouse synthesis fallback 的现有行为。 - Linux 动作回读已有独立 GTK fixture,可在私有 D-Bus / Xvfb 中通过 native MCP 复测;运行方式见 Linux 动作回读。当前 Linux 侧仍是功能性第一版:没有 visual cursor overlay、没有 installer/desktop entry,也没有覆盖全部工具的 Linux fixture。后续 TODO 记录在
docs/exec-plans/active/20260422-linux-computer-use-runtime.md。
macOS Locked Use 实验
locked-use status [--json]和doctor增加只读 session / Input Monitoring / 插件诊断,由 app agent 提供真实 runtime 权限状态。doctor --json保持纯权限 JSON,不弹权限引导;定向 AXquery在读取前和返回结果前检查会话与当前租约。- 真实窗口 snapshot、缓存复用与事件投递检查当前控制台 session;锁屏或未知 / 切换用户状态明确拒绝。fixture 不属于真实桌面,继续支持 headless 测试。
LockedUseStateMachine是由独立 Broker 串行驱动的纯保护策略,覆盖一次性许可、租约、guardian heartbeat、接管和重锁确认;已接入管理员显式启用的 unlock 事务,受保护 legacy 闭环已实测,完整生产证据仍待完成。experiments/LockedUse与独立脚本提供 deny-only Authorization 插件 ABI / 系统加载探针(仅独立 right),完整管理员验证组件另在 screensaver 授权链登记自定义分支并保留系统认证 fallback。独立OCUGuardian测试 app 先用共享的DisplayShieldSurface做不锁屏 / 不操作的 15 秒品牌遮罩 preview(倒计时仅记录到日志),再用 child watchdog rehearsal 验证输入接管、重锁、遮挡窗口 AX / ScreenCaptureKit 及只读 loginwindow 结构。新增签名 Broker、remote 机制、锁屏 Guardian 和安装入口仍处于验证阶段,普通 enable 安装服务并申请权限,服务启动仍严格验证同团队组件签名。LockedUseNative读取 Unix socket 的内核 audit token;LockedUsePeerIdentity验证动态进程签名;LockedUseClientApprovals从 root 所有、不可由普通用户写入的目录加载批准记录;LockedUsePermitRegistry管理绑定会话的一次性 32-byte 许可。Broker IPC 通过 SCM_RIGHTS 验证原生 CLI client 并隔离 agent / guardian / Apple helper / observer / admin 角色;app agent 按连接管理租约与排空。安装入口保留认证 fallback 并登记当前用户的同团队组件。历史验证报告保留为研发证据,正常启用不以报告为门槛;完整故障矩阵仍需继续实测。详细边界见 Locked Use。
关键边界
- 开源版当前不复刻官方闭源实现里的 caller signing、私有 IPC、完整 overlay choreography 和 plugin 自安装逻辑。
- 因为官方
SkyComputerUseClient带有宿主侧 launch constraints,普通 stdio MCP client 在本机上可能被系统直接杀掉;如果要探测官方 bundledcomputer-use,scripts/computer-use-cli的 app-server 模式现在只适合做工具清单和协议面观察。官方1.0.755的真实 tool call 还会经过 service-side sender authorization / active IPC client 追踪,外部 raw helper 即使走已签名 Codex binary,也可能返回Sender process is not authenticated;需要真实使用官方工具时应走正常 Codex agent/tool 调用链,开源版则继续提供可直连的open-computer-useMCP server。 - 当前权限引导已经具备可运行 app、深链、拖拽辅助,以及一版更接近官方的 accessory panel 入场动画和返回 affordance;点击链路也已经补上独立 visual cursor、官方 asset fallback 和相对目标 window 的排序逻辑,并且在 overlay 可见期间会持续重申“排在目标 window 之上”,避免用户手动激活目标 app 后 cursor 被目标窗口重新盖住;但整体还没有完全复刻官方那套嵌入式 choreography / host 集成 / session approval 体验。
- screenshot 当前通过
ScreenCaptureKit捕获目标窗口,并以 MCPimagecontent block 的 base64 PNG(默认)或配置的 JPG/WebP 返回,不再把普通 app 截图落盘到仓库或临时目录;编码前会按配置的最大长边等比例缩小,或按超限策略与最小总像素数门槛省略截图,同时 coordinate tools 继续按实际返回的 screenshot pixel 尺寸映射坐标;单次 ScreenCaptureKit capture 会设置超时,超时后省略 image block 而不是卡住整个get_app_state。 - 会话状态现在是进程内内存态,保存每个 app 最近一次 snapshot 和 element index 映射。
主要验证路径
- 单元测试:
swift test - JS REPL 与 CLI contract:
node --test scripts/node-repl/*.test.mjs - standalone cursor 构建:
swift build --product StandaloneCursor - cursor lab 构建:
swift build --product CursorMotion - 端到端 smoke:
./scripts/run-tool-smoke-tests.sh(标准 9-tool smoke + visual cursor idle smoke;脚本默认以 headless 模式启动内部 fixture,避免在用户桌面弹出测试窗口) - app 打包:
./scripts/build-open-computer-use-app.sh debug - 权限 onboarding 端到端回归:
./scripts/run-permission-onboarding-e2e.sh(需要当前 macOS 对被测open-computer-use已授予 Accessibility 与 Screen Recording;默认禁用 app-agent proxy 来测试当前 CLI 运行态,可用OPEN_COMPUTER_USE_E2E_CLI=/path/to/open-computer-use指定被测 CLI,或用OPEN_COMPUTER_USE_E2E_DISABLE_APP_AGENT_PROXY=0显式覆盖默认代理行为) - npm staging:
node ./scripts/npm/build-packages.mjs - release tgz:
./scripts/release-package.sh - skill 打包:
npm run package:skill - Windows runtime 单测:
(cd apps/OpenComputerUseWindows && go test ./...)(包含scroll请求必须携带windowBounds、global开关门控以及 runtime.ps1 全局输入守卫的回归用例) - Windows exe 构建:
./scripts/build-open-computer-use-windows.sh --arch arm64 - Linux runtime 单测:
(cd apps/OpenComputerUseLinux && go test ./...) - Linux binary 构建:
./scripts/build-open-computer-use-linux.sh --arch arm64 - 对比样本:
artifacts/tool-comparisons/20260417-focus-behavior/ - 手工诊断:
open-computer-use doctoropen-computer-use snapshot <app>open-computer-use call list_appsopen-computer-use call --calls '[{"tool":"get_app_state","args":{"app":"TextEdit"}}]'
用户配置
macOS screenshot 在每轮捕获读取用户 JSON 配置,优先级为 ENV > 文件 > 默认值。npm launcher 提供 ocu config 查看、set、reset 和 path;支持 PNG/JPG/WebP、JPEG 质量、最大长边/超限缩小策略、最小总像素数丢弃与 SCK 超时,保留 hardware capture 优先路径。app-agent 按请求转发解析后的配置路径并清除未提供的 image 环境,防止常驻值污染。见中文配置说明与English。
截图像素丢弃门槛按 width×height 计算,低于(不含等于)门槛不返回 image,但保留 AX 和原因;配置省略截图后拒绝坐标输入。WebP 无损编码通过固定版本 libwebp 静态链接,随 app/npm 制品带上许可文本。
定向 AX 查询
macOS 在原有 9 个工具之外新增 query,按文字或角色查找目标窗口的 AX 元素,不截图、不渲染完整树。Windows/Linux 保持原来的 9 个工具。查询只解析已运行的应用,使用有界 BFS(默认 500 个节点、最多 5000 个,2 秒协作式遍历截止时间),返回匹配项和完整性元数据。字符串和子节点分页同样有界,AX 读取错误会标记结果不完整。
查询索引属于当前 native 会话,最多保留 5000 个、120 秒过期,结束会话时清理且永不复用。元素操作前核对进程身份、窗口归属、查询条件和最新几何;任何验证失败都要求重新查询,不使用旧坐标。JS cua.getApp(name, { initialState: false }) 可跳过初始快照,app.query() 返回结构化结果。详见查询说明。
结构化权限查询
macOS doctor --json 在 CLI 和 app-agent proxy 路径复用 PermissionDiagnostics,只输出一份 JSON 快照,不打开 onboarding。字段为 platform: "macos"、accessibilityTrusted、screenCaptureGranted、allGranted 和 missingPermissions(accessibility / screenRecording)。缺权限仍退出 0,宿主应读取 allGranted 并重新查询授权变化。此状态延续系统 API/TCC 合并诊断语义,并非操作成功证明;Linux/Windows 明确拒绝该权限查询模式。普通 doctor 保留文本输出与权限引导。
Locked Use’s non-UI authorization mechanism is registered with ,privileged and restricted to Apple's root authorizationhosthelper peers. A separate load-check right must return a fixed extractable context marker before the installer attaches the remote branch to system.login.screensaver; signature checks and a denied AuthorizationCopyRights result alone do not prove host compatibility. The original native fallback is preserved.
The load-check grants only its isolated right, with shared=false and a fresh AuthorizationRef that is destroyed afterwards. authd does not export context on a denied result. It reads/writes no credentials and never evaluates system.login.screensaver; successful marker export is required before installation changes that policy.