拓冰网站定制 
Open Computer Use 跨平台内幕Windows UI Automation 与 Linux AT-SPI 双 Runtime 实现完整指南【免费下载链接】open-codex-computer-use Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-useOpen Computer Use是一个开源的 Computer Use 方案目标是让 AI Agent 像人一样操作桌面应用。它最有趣的地方在于跨平台双 runtime 架构Windows 侧通过UI AutomationUIA Win32 窗口消息Linux 侧通过AT-SPI2 D-Bus两套实现共用同一组 9 个标准工具list_apps、get_app_state、click、perform_secondary_action、scroll、drag、type_text、press_key、set_value让同一个 MCP Server 在不同操作系统上表现一致。下面这篇指南带你完整看懂这两条技术路线的设计思路、关键代码与能力边界。一、统一外壳Go 负责协议嵌入脚本负责系统能力两个 runtime 都遵循同一个分层模式层WindowsLinux协议外壳Go CLI / MCP Serverapps/OpenComputerUseWindows/main.goGo CLI / MCP Serverapps/OpenComputerUseLinux/main.go系统 bridge嵌入式 PowerShell 脚本apps/OpenComputerUseWindows/runtime.ps1嵌入式 Python 脚本apps/OpenComputerUseLinux/runtime.py系统接口UI Automation.NET API Win32 PostMessage/SendMessageAT-SPI2经 D-Bus AT-SPI 事件合成交付形态open-computer-use.exe随 npm 包内置分发open-computer-use二进制随 npm 包内置分发这个设计的关键取舍是用 Go 稳定协议面、参数校验和 snapshot 缓存把操作桌面这件高度平台相关的事交给系统原生能力。Go 侧通过go:embed把脚本内嵌进二进制执行工具调用时临时落盘并拉起powershell.exe或python3一次操作 30 秒超时保护。这样交付物是一个独立可执行文件不依赖 Swift、Node 或外部 SDK 安装。小提示仓库里还有experiments/CursorMotion、experiments/StandaloneCursor这类实验模块用来研究官方光标轨迹的还原属于 macOS 主线能力Windows/Linux runtime 目前不带视觉光标覆盖层——这是理解两条 runtime 能力边界时的重要前提。二、Windows RuntimeUIA 优先窗口消息兜底2.1 快照一棵带索引的元素树get_app_state的执行路径非常清晰见 runtime.ps1 中的Build-Snapshot定位应用Resolve-App按 PID、进程名支持notepad.exe这类写法、窗口标题匹配Get-Process中的顶层窗口进程构建无障碍树从主窗口句柄取AutomationElement用FindAll(Children)递归遍历为每个元素分配index、runtimeId、automationId、name、controlType、frame等字段同时渲染成人类可读的缩进树截图用System.Drawing的CopyFromScreen捕获窗口区域转 Base64 PNG 随结果返回附加上下文焦点元素摘要FocusedElement与选中文本TextPattern.GetSelection一并带回。渲染预算与 macOS 主线对齐默认1200 节点 / 64 层深度文本默认截断 500 字符均可通过max_tree_nodes、max_tree_depth、text_limit覆盖。2.2 点击的三级路由click_methodWindows 侧click支持四种实际可用的click_method路由逻辑在 runtime.ps1 的click分支里auto默认元素支持时先走 UIA 语义点击InvokePattern→SelectionItemPattern.Select→TogglePattern.Toggle失败再退到窗口消息点击accessibility强制 UIA pattern要求element_indexapp_post强制走 Win32 路径——PostMessage发送WM_MOUSEMOVEWM_LBUTTONDOWN/UP坐标先经ScreenToClient转为窗口客户区坐标global/sky_click分别对应 macOS 能力Windows 上会在快照查询前明确返回 unsupported不做静默降级。drag是 12 步线性插值的WM_MOUSEMOVE序列scroll优先ScrollPattern、兜底WM_MOUSEWHEEL/WM_MOUSEHWHEEL每页 120 刻度press_key把ctrla这类组合键拆成虚拟键码依次PostMessage。2.3 不抢焦点默认保守策略这是 Windows runtime 最值得注意的设计决策记录见 20260422-windows-computer-use-runtime.md找不到应用时不会自动启动除非显式设置OPEN_COMPUTER_USE_WINDOWS_ALLOW_APP_LAUNCH1SetFocus二级动作默认禁用避免抢走用户前台焦点type_text默认优先对可写文本控件的子 HWND 发EM_SETSELEM_REPLACESEL后台消息Notepad 实测前台窗口全程不变可能触发前台激活的 UIAValuePattern.SetValue回退被关在OPEN_COMPUTER_USE_WINDOWS_ALLOW_UIA_TEXT_FALLBACK1后面。一句话总结UIA pattern 优先窗口消息 best-effort前台抢占行为全部显式 opt-in。三、Linux RuntimeAT-SPI2 语义动作为王3.1 环境门槛必须在桌面会话里AT-SPI2 经由 D-Bus 暴露应用的无障碍树、动作、可编辑文本和 Value 接口——这是 Linux 上最接近 macOS AX 的能力。Python bridge 入口runtime.py 的require_desktop_session会先检查XDG_RUNTIME_DIR和DBUS_SESSION_BUS_ADDRESS缺失时 Go 外壳会尝试从/run/user/uid和桌面进程自动发现当前用户的会话环境纯 SSH tty 则明确报错而不是把 session 问题误判成 AT-SPI 逻辑失败。3.2 快照与元素定位应用发现遍历Atspi.get_desktop(0)的子节点按应用名、窗口标题、PID 匹配主窗口选择优先ACTIVE状态、其次SHOWING的顶层窗口树渲染与 Windows 侧相同的index / role / name / value / frame格式用子节点下标路径runtimeId记录元素位置元素找回先按路径resolve_path直接定位失败再用accessible_id、namerole、roleframe 容差匹配三级回退截图GDK 根窗口捕获检测到全黑采样直接省略图片块——因为 GNOME Wayland 下 compositor 可能拒绝捕获黑图比没图更有误导性。一个有趣的工程细节GNOME Text Editor 的 AT-SPI 树深度远超 Windows 侧沿用的 16 层所以 Linux bridge 把遍历深度单独放宽到 64与 macOS/Windows 当前统一的 1200 节点预算一致。3.3 输入合成明确标注 best-effortLinux 侧的能力边界与 Windows 不同工具Linux 实现clickaccessibility/auto优先do_action匹配click/press/activate等语义动作名兜底 AT-SPI 鼠标事件合成type_text优先找EditableText接口直接insert_text失败再退键盘事件合成set_valueEditableText.set_text_contents或Value.set_current_valuescrollPage_Up/Down、Left/Right键合成drag/ 坐标clickAtspi.generate_mouse_event屏幕坐标事件注意 runtime.py 中click_method的路由app_post直接 unsupported——因为 AT-SPI没有等价于 Win32 的按进程定向投递鼠标事件模型global则要求全局指针环境变量授权因为事件合成可能移动系统指针、改变前台焦点。MCP instructions 里也如实写明coordinate mouse and key synthesis are best-effort fallbacks and are not a universal Wayland background input model。四、双 Runtime 对照与常见坑维度Windows (UIA)Linux (AT-SPI2)主接口UI Automation patternAT-SPI action / EditableText / Value后台输入兜底Win32PostMessage/SendMessage按窗口定向AT-SPI 事件合成屏幕级best-effortapp_post支持HWND 消息不支持无进程定向模型global不支持支持需环境变量授权运行前提已登录桌面会话SSH/service 里看不到顶层窗口已登录桌面会话需 session bus 环境已知短板Electron/WinUI/UWP 对后台消息行为不一GNOME Wayland 截图可能黑图坐标输入非通用后台模型排查顺序建议先确认命令运行在桌面用户会话里list_apps是否为空再用snapshot app区分是 session/环境问题和 AT-SPI/UIA 树问题。五、快速上手# Windows已登录桌面 open-computer-use.exe call list_apps open-computer-use.exe call get_app_state --args {app:notepad} open-computer-use.exe call --calls [{tool:type_text,args:{app:notepad,text:hello}}] # LinuxUbuntu GNOME 桌面会话内 open-computer-use call list_apps open-computer-use call get_app_state --args {app:gnome-text-editor} open-computer-use mcp # 作为 MCP Server 接入 Agentcall --calls会在同一进程内顺序执行并复用上一轮 snapshot 的element_index元数据相邻成功操作默认间隔 1 秒——这保证了先get_app_state再操作的两步模式在脚本里也能稳定工作。六、延伸阅读架构总览docs/ARCHITECTURE.md第 6、7 节专门讲 Windows/Linux RuntimeWindows 执行计划与决策记录docs/exec-plans/active/20260422-windows-computer-use-runtime.mdLinux 执行计划与决策记录docs/exec-plans/active/20260422-linux-computer-use-runtime.mdWindows 源码目录apps/OpenComputerUseWindows/Linux 源码目录apps/OpenComputerUseLinux/质量与能力边界说明docs/QUALITY_SCORE.md总结Open Computer Use 的跨平台答案不是移植一套输入模拟而是每个平台找最像 AX 的语义层UIA / AT-SPI2做主路径把物理输入降级为标注清楚的兜底。理解这两条 runtime 的分层与 opt-in 开关你就能在 Windows 和 Linux 上把 Computer Use 工具稳定地接入自己的 Agent。【免费下载链接】open-codex-computer-use Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Open Computer Use 跨平台内幕：Windows UI Automation 与 Linux AT-SPI 双 Runtime 实现完整指南
Open Computer Use 跨平台内幕Windows UI Automation 与 Linux AT-SPI 双 Runtime 实现完整指南【免费下载链接】open-codex-computer-use Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-useOpen Computer Use是一个开源的 Computer Use 方案目标是让 AI Agent 像人一样操作桌面应用。它最有趣的地方在于跨平台双 runtime 架构Windows 侧通过UI AutomationUIA Win32 窗口消息Linux 侧通过AT-SPI2 D-Bus两套实现共用同一组 9 个标准工具list_apps、get_app_state、click、perform_secondary_action、scroll、drag、type_text、press_key、set_value让同一个 MCP Server 在不同操作系统上表现一致。下面这篇指南带你完整看懂这两条技术路线的设计思路、关键代码与能力边界。一、统一外壳Go 负责协议嵌入脚本负责系统能力两个 runtime 都遵循同一个分层模式层WindowsLinux协议外壳Go CLI / MCP Serverapps/OpenComputerUseWindows/main.goGo CLI / MCP Serverapps/OpenComputerUseLinux/main.go系统 bridge嵌入式 PowerShell 脚本apps/OpenComputerUseWindows/runtime.ps1嵌入式 Python 脚本apps/OpenComputerUseLinux/runtime.py系统接口UI Automation.NET API Win32 PostMessage/SendMessageAT-SPI2经 D-Bus AT-SPI 事件合成交付形态open-computer-use.exe随 npm 包内置分发open-computer-use二进制随 npm 包内置分发这个设计的关键取舍是用 Go 稳定协议面、参数校验和 snapshot 缓存把操作桌面这件高度平台相关的事交给系统原生能力。Go 侧通过go:embed把脚本内嵌进二进制执行工具调用时临时落盘并拉起powershell.exe或python3一次操作 30 秒超时保护。这样交付物是一个独立可执行文件不依赖 Swift、Node 或外部 SDK 安装。小提示仓库里还有experiments/CursorMotion、experiments/StandaloneCursor这类实验模块用来研究官方光标轨迹的还原属于 macOS 主线能力Windows/Linux runtime 目前不带视觉光标覆盖层——这是理解两条 runtime 能力边界时的重要前提。二、Windows RuntimeUIA 优先窗口消息兜底2.1 快照一棵带索引的元素树get_app_state的执行路径非常清晰见 runtime.ps1 中的Build-Snapshot定位应用Resolve-App按 PID、进程名支持notepad.exe这类写法、窗口标题匹配Get-Process中的顶层窗口进程构建无障碍树从主窗口句柄取AutomationElement用FindAll(Children)递归遍历为每个元素分配index、runtimeId、automationId、name、controlType、frame等字段同时渲染成人类可读的缩进树截图用System.Drawing的CopyFromScreen捕获窗口区域转 Base64 PNG 随结果返回附加上下文焦点元素摘要FocusedElement与选中文本TextPattern.GetSelection一并带回。渲染预算与 macOS 主线对齐默认1200 节点 / 64 层深度文本默认截断 500 字符均可通过max_tree_nodes、max_tree_depth、text_limit覆盖。2.2 点击的三级路由click_methodWindows 侧click支持四种实际可用的click_method路由逻辑在 runtime.ps1 的click分支里auto默认元素支持时先走 UIA 语义点击InvokePattern→SelectionItemPattern.Select→TogglePattern.Toggle失败再退到窗口消息点击accessibility强制 UIA pattern要求element_indexapp_post强制走 Win32 路径——PostMessage发送WM_MOUSEMOVEWM_LBUTTONDOWN/UP坐标先经ScreenToClient转为窗口客户区坐标global/sky_click分别对应 macOS 能力Windows 上会在快照查询前明确返回 unsupported不做静默降级。drag是 12 步线性插值的WM_MOUSEMOVE序列scroll优先ScrollPattern、兜底WM_MOUSEWHEEL/WM_MOUSEHWHEEL每页 120 刻度press_key把ctrla这类组合键拆成虚拟键码依次PostMessage。2.3 不抢焦点默认保守策略这是 Windows runtime 最值得注意的设计决策记录见 20260422-windows-computer-use-runtime.md找不到应用时不会自动启动除非显式设置OPEN_COMPUTER_USE_WINDOWS_ALLOW_APP_LAUNCH1SetFocus二级动作默认禁用避免抢走用户前台焦点type_text默认优先对可写文本控件的子 HWND 发EM_SETSELEM_REPLACESEL后台消息Notepad 实测前台窗口全程不变可能触发前台激活的 UIAValuePattern.SetValue回退被关在OPEN_COMPUTER_USE_WINDOWS_ALLOW_UIA_TEXT_FALLBACK1后面。一句话总结UIA pattern 优先窗口消息 best-effort前台抢占行为全部显式 opt-in。三、Linux RuntimeAT-SPI2 语义动作为王3.1 环境门槛必须在桌面会话里AT-SPI2 经由 D-Bus 暴露应用的无障碍树、动作、可编辑文本和 Value 接口——这是 Linux 上最接近 macOS AX 的能力。Python bridge 入口runtime.py 的require_desktop_session会先检查XDG_RUNTIME_DIR和DBUS_SESSION_BUS_ADDRESS缺失时 Go 外壳会尝试从/run/user/uid和桌面进程自动发现当前用户的会话环境纯 SSH tty 则明确报错而不是把 session 问题误判成 AT-SPI 逻辑失败。3.2 快照与元素定位应用发现遍历Atspi.get_desktop(0)的子节点按应用名、窗口标题、PID 匹配主窗口选择优先ACTIVE状态、其次SHOWING的顶层窗口树渲染与 Windows 侧相同的index / role / name / value / frame格式用子节点下标路径runtimeId记录元素位置元素找回先按路径resolve_path直接定位失败再用accessible_id、namerole、roleframe 容差匹配三级回退截图GDK 根窗口捕获检测到全黑采样直接省略图片块——因为 GNOME Wayland 下 compositor 可能拒绝捕获黑图比没图更有误导性。一个有趣的工程细节GNOME Text Editor 的 AT-SPI 树深度远超 Windows 侧沿用的 16 层所以 Linux bridge 把遍历深度单独放宽到 64与 macOS/Windows 当前统一的 1200 节点预算一致。3.3 输入合成明确标注 best-effortLinux 侧的能力边界与 Windows 不同工具Linux 实现clickaccessibility/auto优先do_action匹配click/press/activate等语义动作名兜底 AT-SPI 鼠标事件合成type_text优先找EditableText接口直接insert_text失败再退键盘事件合成set_valueEditableText.set_text_contents或Value.set_current_valuescrollPage_Up/Down、Left/Right键合成drag/ 坐标clickAtspi.generate_mouse_event屏幕坐标事件注意 runtime.py 中click_method的路由app_post直接 unsupported——因为 AT-SPI没有等价于 Win32 的按进程定向投递鼠标事件模型global则要求全局指针环境变量授权因为事件合成可能移动系统指针、改变前台焦点。MCP instructions 里也如实写明coordinate mouse and key synthesis are best-effort fallbacks and are not a universal Wayland background input model。四、双 Runtime 对照与常见坑维度Windows (UIA)Linux (AT-SPI2)主接口UI Automation patternAT-SPI action / EditableText / Value后台输入兜底Win32PostMessage/SendMessage按窗口定向AT-SPI 事件合成屏幕级best-effortapp_post支持HWND 消息不支持无进程定向模型global不支持支持需环境变量授权运行前提已登录桌面会话SSH/service 里看不到顶层窗口已登录桌面会话需 session bus 环境已知短板Electron/WinUI/UWP 对后台消息行为不一GNOME Wayland 截图可能黑图坐标输入非通用后台模型排查顺序建议先确认命令运行在桌面用户会话里list_apps是否为空再用snapshot app区分是 session/环境问题和 AT-SPI/UIA 树问题。五、快速上手# Windows已登录桌面 open-computer-use.exe call list_apps open-computer-use.exe call get_app_state --args {app:notepad} open-computer-use.exe call --calls [{tool:type_text,args:{app:notepad,text:hello}}] # LinuxUbuntu GNOME 桌面会话内 open-computer-use call list_apps open-computer-use call get_app_state --args {app:gnome-text-editor} open-computer-use mcp # 作为 MCP Server 接入 Agentcall --calls会在同一进程内顺序执行并复用上一轮 snapshot 的element_index元数据相邻成功操作默认间隔 1 秒——这保证了先get_app_state再操作的两步模式在脚本里也能稳定工作。六、延伸阅读架构总览docs/ARCHITECTURE.md第 6、7 节专门讲 Windows/Linux RuntimeWindows 执行计划与决策记录docs/exec-plans/active/20260422-windows-computer-use-runtime.mdLinux 执行计划与决策记录docs/exec-plans/active/20260422-linux-computer-use-runtime.mdWindows 源码目录apps/OpenComputerUseWindows/Linux 源码目录apps/OpenComputerUseLinux/质量与能力边界说明docs/QUALITY_SCORE.md总结Open Computer Use 的跨平台答案不是移植一套输入模拟而是每个平台找最像 AX 的语义层UIA / AT-SPI2做主路径把物理输入降级为标注清楚的兜底。理解这两条 runtime 的分层与 opt-in 开关你就能在 Windows 和 Linux 上把 Computer Use 工具稳定地接入自己的 Agent。【免费下载链接】open-codex-computer-use Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考