Agent Zero host-computer-use 技能指南通过 A0 CLI 桥接实现宿主机桌面远程控制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的_a0_connector插件提供了一条连接宿主机host/local computer与 Docker 化 Agent Zero 运行时的通道而host-computer-use技能正是解锁这条通道上computer_use_remote工具的钥匙。本文完整解析该技能的工具契约、核心循环、三大桌面后端Linux/Wayland AT-SPI、macOS AX、Windows UIA的结构化定位方式、边界规则与证据验证纪律并深入源码揭示自动截图、settle 延迟与 re-arm 信号处理等底层实现帮助读者安全、准确地驱动用户真实桌面的原生应用界面。技能定位何时加载与使用host-computer-use是 plugins/_a0_connector/skills/host-computer-use/SKILL.md 定义的 Beta 技能其 frontmatter 明确了触发词triggerscomputer use、host computer、host desktop、local computer、my screen、Ubuntu Wayland desktop等。凡是涉及用户宿主机/本地电脑的屏幕截图、界面检查、菜单、原生应用 UI、OS 级点击、滚动、输入或需要检查computer_use_remote状态的任务都应加载本技能后再调用工具。需要特别区分两类桌面宿主机桌面host desktop用户真实运行的 Windows/macOS/Linux 桌面由本技能 computer_use_remote负责。Agent Zero 内部桌面internal Agent Zero Desktop运行在 Agent Zero 运行时内的 Linux Desktop/Xpra 表面对应linux-desktop技能、desktopctl.sh等路径无法看到宿主机屏幕。原文档明确划定了三条边界任何情况下都不得跨界替代场景正确路径禁止的替代路径宿主机屏幕操作截图/点击/输入/桌面状态computer_use_remote经 A0 CLI 或 Launcher host gatewaylinux-desktop、Xpra、desktopctl.sh、code_execution_tool、Docker/服务端 shell宿主浏览器控制browser工具Browser 插件自动选择 Docker 或 A0 CLI 宿主浏览器运行时computer_use_remote、code_execution_remote、xdg-open、sensible-browser、Pythonwebbrowser.open宿主机 shell 执行单独加载host-code-execution技能与桌面控制混为一谈对于纯浏览器任务优先使用browser工具——它通常比截屏驱动的桌面控制更可靠且更省 token。若宿主浏览器设置失败或提示远程调试应引导用户在浏览器中打开chrome://inspect/#remote-debugging、开启 Allow remote debugging for this browser instance、运行/browser host on后重试。若computer_use_remote不可用、被禁用或需要重新武装re-arm必须停下并请用户执行/computer-use onLauncher Host 访问时在 A0 Launcher 聊天中执行否则在 A0 CLI 中执行并批准平台权限提示。工具契约computer_use_remote 动作与参数使用前必须调用start_session。基础调用格式{ tool_name: computer_use_remote, tool_args: { action: start_session } }工具要求在每次调用中提供action其合法取值在源码 plugins/_a0_connector/tools/computer_use_remote.py 中以_SUPPORTED_ACTIONS集合固化与技能文档完全一致start_session、status、capture、list_windows、get_window_state、element_action、move、click、scroll、key、type、stop_session后端技能可补充ax_snapshot、ax_action、uia_snapshot、uia_action等后端专属动作。若action非法工具直接返回错误提示不发起任何远端调用。各动作的参数契约如下action必填取值见上后端技能可能额外声明后端专属 action仅当后端元数据明确宣告支持且已加载对应后端技能时才可使用。session_idstart_session之后可选传入。list_windows后端支持时返回原生顶层窗口记录含window_id、pid、app、title、frame、active/focused/visible等标志。get_window_state传入pid和/或window_id返回目标窗口的可访问性树accessibility tree其中包含当前状态下稳定的element_index值。element_action传入最近一次get_window_state返回的element_index可选operation、value/text、dispatch。dispatchbackground、auto或foreground元素动作默认background。movex、y归一化到[0,1]全局屏幕坐标。click可选x、y可选buttonleft/right/middle可选count。scrolldx、dy。keykey或keys。typetext可选submit布尔值。type的submittrue只应用于 URL 或导航式输入输入后立即触发 Enter普通文本字段不要用submittrue应先type如需再单独发送enter。工具的可用性检查是运行时完成的源码execute()首先通过select_computer_use_target_sid()查找已启用本地 Computer Use 且处于可信模式的已连接 CLIcomputer_use_remote.py若没有任何已连接 CLI 宣告启用直接返回提示Enable it in the CLI and choose a trust mode first而不会回退到服务端环境。若 CLI 元数据中status为rearm required则立即返回COMPUTER_USE_REARM_REQUIRED错误。核心循环从会话启动到证据验证技能文档规定了 12 步核心循环这是宿主机桌面控制的标准操作流程先调用start_session。读取返回的backend_id、backend_family、features、contract_version、capabilities当任务需要后端专属能力时加载对应的后端 Computer Use 技能。优先依赖结构化的capabilities对象而非根据 OS 名猜测。capabilities.identity.pid、capabilities.identity.window_id、capabilities.identity.element_index、capabilities.dispatch.background是原生后台循环的可移植契约。若后端通过 capabilities 或native-window-list宣告支持原生窗口列表先调用list_windows再使用坐标。若后端宣告支持窗口状态与 element-index 定位capabilities 或 features对目标pid/window_id调用get_window_state随后使用element_actiondispatch默认background。若element_action报告background_unavailable仅当用户/任务可接受前台控制时才改用dispatch: auto或dispatch: foreground。后端宣告已验证窗口焦点verified window focus时仅用前台element_action的focus操作激活窗口且要求focus_verifiedtrue绝不用press作用于应用/框架/窗口节点来激活。后端宣告目标验证键盘输入target-verified keyboard input时将已验证的活动window_id传给type目标缺失、非活动或不可验证时必须 fail closed拒绝输入。最终成功与否以最新截图或确定性的结构化结果为准不凭记忆判断。交互动作执行后会自动附带一张新截图先检查截图再声称目标结果已达成。仅查询状态用status不启动会话。仅需额外截图、不执行动作时用capture。源码佐证自动截图与 settle 延迟核心循环中的交互动作自动附带新截图在工具实现中有完整支撑。_AUTO_CAPTURE_ACTIONS集合computer_use_remote.py覆盖start_session、element_action、ax_action、uia_action、move、click、scroll、key、type——即所有可能改变桌面状态的动作。动作成功后工具会按动作类型等待不同的 settle 延迟_SETTLE_DELAY_*常量computer_use_remote.pystart_session0.2s、move0.1s、click0.35s、scroll0.35s、ax_action/uia_action0.25s、type0.25s、type(..., submittrue)0.45skey则按按键组合细分含super或alttab时 0.45s全局焦点切换仅enter时 0.3s其余 0.2s。随后以fresh: True、fresh_timeout_seconds: 0.45发起一次capture将最新画面附加到工具结果中computer_use_remote.py。截图以聊天媒体制品保存category 为screenshots、source 为computer-use单张上限 25 MiB并估算约 1500 token 计入历史。值得注意的细节element_action若返回actual_dispatchbackground或none说明是确定性的结构化后台结果不会附加截图——这正对应核心循环第 9 条最新截图或确定性结构化结果的双重判据。截图与历史管理也有专门处理_prune_prior_capture_history()会在新截图写入后将之前的历史截图消息内容替换为[image reference superseded]避免多轮桌面操作导致视觉上下文无界膨胀。后端技能按平台选择结构化定位方案start_session/status返回的backend_family、backend_id与features是选择后端技能的判据工具源码中的_backend_skill_hint()computer_use_remote.py会在会话启动时自动提示应加载的后端技能后端判据backend_id / backend_family / features需加载的技能Linux/Waylandwayland、x11、linux/linux/atspi-tree-snapshot、atspi-structural-targeting、atspi-element-action、atspi-set-valuehost-computer-use-linuxmacOSmacos/macos/accessibility-tree-snapshot、accessibility-structural-targetinghost-computer-use-macosWindowswindows/windows/uia-tree-snapshot、uia-structural-targeting、uia-element-action、uia-window-managementhost-computer-use-windows关键原则后端专属动作不能因为参数名在通用契约中存在就使用。除非连接的 CLI 宣告了对应 feature一律视为不可用。LinuxAT-SPI 结构化定位Linux 后端可宣告atspi-tree-snapshot、atspi-structural-targeting、atspi-element-action、atspi-set-value四个 AT-SPI 结构化 feature。存在时对命名按钮、菜单项、文本字段、对话框、工具栏项、标签页和应用窗口应优先结构化定位而非像素点击。若后端同时宣告native-window-list、window-state、element-index-targeting、background-dispatch优先走通用后台循环list_windows→get_window_state→element_action否则使用 AT-SPI 快照/动作流程{ tool_name: computer_use_remote, tool_args: { action: ax_snapshot, window_id: window_id from list_windows, max_depth: 4, max_nodes: 200 } }ax_snapshot返回路径、角色、名称/标题、描述、框架、状态、动作、文本预览、值与子节点用于选择目标而非作为最终视觉证据。已知window_id时必须传入避免无关应用消耗节点预算。{ tool_name: computer_use_remote, tool_args: { action: ax_action, target: { role: push button, title: OK }, operation: press } }支持的操作press激活按钮/菜单项/标签/复选框等动作承载节点绝不用于应用/框架/窗口节点、focus输入前聚焦可聚焦节点、set_value在可编辑节点设置文本/值传value或text。定位选项优先语义化target稳定的 role title/name/description/text/state/actionpath仅在 UI 未变化时使用最近一次ax_snapshot的返回动作报告歧义时重新快照并收窄 roletitle报告目标缺失时先新快照再考虑坐标。Wayland 注意事项每次状态改变动作后必须用截图取证——AT-SPI 动作与键盘事件只是尝试而非证明Wayland 焦点在活动窗口变化时可能拒绝或重定向输入。除非工具结果明确返回actual_dispatchbackground不得声称 Linux 动作是后台安全的。要将 Linux 窗口置前应从get_window_state定位其 frame/window 元素用element_action、focus操作、dispatch: foreground或auto且仅当结果返回focus_verifiedtrue才继续——被接受的 AT-SPI 调用若没有活动/焦点状态不算激活证明。Linux 文本注入受目标保护必须把已验证的活动window_id传给type若工具返回COMPUTER_USE_WINDOW_REQUIRED或COMPUTER_USE_TARGET_NOT_FOCUSED不要全局输入也不要替换为其他应用目标。GNOME/Wayland 常用快捷键均为尝试SuperH隐藏活动窗口、AltTab切换应用、CtrlL聚焦浏览器地址栏、CtrlT新建标签页文本落错应用时停下并从capture或ax_snapshot重新评估不得基于假定焦点继续输入。部分应用 AT-SPI 树很浅需其自身开启辅助功能支持此时按顺序回退应用原生/浏览器工具 → 可靠键盘路径 → 基于新截图的归一化坐标点击。macOSAX 结构化定位macOS 后端可宣告accessibility-tree-snapshot、accessibility-structural-targeting、accessibility-element-click。存在时优先结构化定位命名控件按钮、菜单项、文本字段、sheet、告警、工具栏项、侧栏行若同时宣告native-window-list、window-state、element-index-targeting、background-dispatch优先通用后台循环。ax_snapshot可传max_depth/max_nodes默认例为 4/200返回前置应用有界辅助功能树含元素路径、角色、标签、框架、启用/聚焦状态、动作与子节点ax_action支持press按钮/菜单项/复选框等、focus文本字段或可聚焦元素、set_value传value或text{ tool_name: computer_use_remote, tool_args: { action: ax_action, target: { role: AXButton, title: OK }, operation: press } }macOS 同样遵循AX 动作是尝试而非证明除非结果明确actual_dispatchbackground不得假定后台完成background_unavailable时仅在前台控制可接受时使用前台分发。窗口操作常用快捷键CommandH隐藏活动应用、CommandM最小化活动窗口执行后必须检查新截图窗口的关闭/最小化/全屏按钮若在 AX 树中可访问优先ax_snapshotax_action而非小坐标点击。权限方面macOS 的Screen Recording影响截图Accessibility / Input Monitoring影响结构化定位与输入出现COMPUTER_USE_REARM_REQUIRED、COMPUTER_USE_APPROVAL_REQUIRED或statusrearm required时立即停止请用户运行/computer-use on并批准系统弹窗。WindowsUIA 结构化定位Windows 后端宣告的 feature 最丰富uia-tree-snapshot、uia-structural-targeting、uia-element-action、uia-window-management、native-window-list、window-state、element-index-targeting、background-dispatch、foreground-dispatch-fallback。存在时对命名控件按钮、菜单项、文本字段、对话框、工具栏项、浏览器地址栏、编辑器字段、列表行优先后台结构化定位。首选循环list_windows找到目标原生窗口get_window_state传目标pid和/或window_idelement_action传返回的element_indexdispatch: background后端报告background_unavailable时才切换auto/foreground。{ tool_name: computer_use_remote, tool_args: { action: element_action, window_id: uia-hwnd:123456, element_index: 7, operation: invoke, dispatch: background } }当新的 window-state 循环不可用时用uia_snapshot检查有界 UIA 树max_depth/max_nodes默认 4/200返回元素路径、角色、名称/标题、automation ID、类名、可选 Terminator 风格 selector、框架、状态、动作与子节点。uia_action支持的操作比前两者更丰富invoke激活按钮/菜单项/复选框等控件focus_window恢复并把所属顶层窗口带到前台minimize、restore、maximize改变所属顶层窗口状态不点标题栏按钮focus激活窗口后聚焦文本字段或可聚焦元素set_value设置文本/值传value或textclick仅当快照显示 click 是可用动作且无结构化操作适配时通过 UIA 包装点击元素close仅当用户明确要求关闭该应用/窗口时关闭所属顶层窗口。{ tool_name: computer_use_remote, tool_args: { action: uia_action, target: { role: Button, title: OK }, operation: invoke } }动作选择纪律优先节点列出的动作节点提供invoke就用invoke而非click后端宣告element-index-targeting时优先element_action保持 background-first 分发契约窗口聚焦/隐藏/恢复/最大化用focus_window/minimize/restore/maximize而非点击标题栏应用内输入先结构化聚焦窗口再对目标字段set_value——全局type结果只证明按键已发送不证明落入目标控件窗口操作、导航、菜单开合、对话框切换等布局变化后复用path前必须重新uia_snapshot像素click仅在结构化 UIA、键盘、浏览器、应用原生方案都不适配时且基于目标清晰的新截图才使用。Windows 会话注意桌面捕获与 UIA 依赖 A0 CLI 运行所在的交互式桌面会话。远程桌面、VM 控制台、UAC 弹窗、提权应用、锁屏、最小化/断开的 RDP 会话、服务会话都可能阻断捕获或 UIA 访问。出现COMPUTER_USE_REARM_REQUIRED、COMPUTER_USE_APPROVAL_REQUIRED、COMPUTER_USE_CAPTURE_UNAVAILABLE、COMPUTER_USE_UIA_UNAVAILABLE或statusrearm required时立即停止请用户修复 Windows 桌面会话不得用服务端截图、Docker 命令、linux-desktop或浏览器回退绕过。几何坐标Windows 捕获可能使用包含多显示器与负原点的虚拟桌面必须以捕获/会话返回的origin_x、origin_y、width、height作为坐标空间归一化[0,1]坐标仅相对该虚拟屏有效。运行纪律证据验证与操作守则技能文档的Operating Rules是一套严格的证据与操作纪律是防止 Agent 在宿主机上盲操作的核心约束只有最新截图或确定性的工具结果才算证据。工具结果声称附了截图但实际看不到图像时停止并报告视觉验证不可用不得基于假定的宿主机状态继续下一个动作。后端宣告支持时优先后台安全原生循环list_windows→get_window_state→element_action。超出宣告的结构化辅助功能支持范围时使用归一化全局屏幕坐标运行时未明确宣告的 window id、element index、后台安全输入、语义点击目标一律不假设。dispatch: foreground视为对用户可见桌面的有意控制仅在判定后台动作不可用或不合适后使用。优先可访问性与语义 UI 路径快捷键、命令面板、菜单加速键、地址/搜索栏、焦点遍历等键盘可达控件有可靠键盘路径时优先key和type而非指针动作。菜单/弹窗打开时视为活动 UI优先键盘导航而非按坐标点击小的瞬态行若点击关掉了菜单/弹窗却没出现预期 UI视为失败。同一方法已连续失败两次且无可见进展切换策略而非重复。不得从聊天日志、侧栏、工具摘要或状态文本推断焦点或任务完成任何状态改变动作必须由最新截图可见确认后才可声称成功。type结果仅在报告focus_verifiedtrue且带目标window_id时确认落点否则只证明全局键盘事件已发送。通过该工具做浏览器导航任务仅当浏览器内容区可见地显示目标页面/结果时才可声称成功。状态改变动作后附加截图看起来没变化先用一次显式capture验证再决定是否重复动作。指针与滚动键盘滚动优先page_down、page_up、space、shiftspace、方向键、home、end。目标窗格已活动或键盘滚动无法命中时用scroll。move与click是最后手段——仅用于后端结构化定位、键盘、浏览器、应用原生工具都无法触达的控件点击前确保最新截图使目标无歧义一次有意的点击后基于新截图重新评估。控制信号与 re-arm 协议用户干预是最高优先级控制信号用户说stop、pause、abort、hold、dont continue或等效表达立即停止且直到用户明确恢复前不得再使用 computer-use 工具。任何工具结果包含COMPUTER_USE_REARM_REQUIRED或statusrearm required时立即终止 computer-use 序列不重试start_session、不调用capture、不用 shell/视觉/截图回退绕过。含义是已连接宿主机配置了 Computer Use但安装的桌面控制后端未武装armed。正确做法是告知用户运行/computer-use onLauncher Host 访问时在 A0 Launcher 聊天否则在 A0 CLI并批准可能出现的平台权限弹窗。该协议在源码层有双重保障execute()入口在分发前检查 CLI 元数据statuscomputer_use_remote.py_format_error()则对COMPUTER_USE_REARM_REQUIRED/COMPUTER_USE_APPROVAL_REQUIRED统一输出标准化的 re-arm 指引computer_use_remote.py。运行时门控技能何时对 Agent 可见computer_use_remote并非始终出现在工具列表中其可见性受运行时门控约束。工具提示词文档 plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md 说明当连接的 A0 CLI 或 Launcher host gateway 宣告启用 Computer Use/computer-use on且无需 re-arm 时才展示。启用状态作用于当前 CLI 会话或 Launcher Host 访问租约而非单个聊天上下文——测试 tests/test_a0_connector_prompt_gating.py 中的test_computer_use_remote_prompt_is_cli_session_wide_not_context_scoped专门验证了这一语义。测试文件同样验证了门控的关键分支tests/test_a0_connector_prompt_gating.py无启用的 Computer Use 元数据时工具提示被隐藏statusrearm required时提示被隐藏对应工具入口的 re-arm 拦截启用后提示中才出现tool_name: computer_use_remote与### computer_use_remote段落。另有test_computer_use_remote_prompt_requires_visual_verification_after_actions验证提示词强制要求动作后视觉验证——与技能文档的只有最新截图或确定性工具结果才算证据一致。前置条件A0 CLI 宿主桥接使用本技能前需先建立 A0 CLI 桥接。setup-a0-cli 技能 的指导要点是a0运行在用户宿主机上Agent Zero 留在 Docker/沙箱中。全新安装时先确认宿主 OSmacOS/Linux 终端curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | shWindows PowerShellirm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex安装后在普通电脑终端而非容器内运行a0它会打开宿主选择器并尽量自动发现本地 Docker 实例需要手动输入时使用用户当前打开 Agent Zero 的确切 URL含实际端口不得臆测或套用文档示例端口隧道 URL 原样粘贴、无需追加端口。连接器返回404通常意味着运行中的 Agent Zero 构建缺少内置_a0_connector需更新 Agent Zero。安装脚本不可达但uv可用时可用uv tool install --upgrade githttps://github.com/agent0ai/a0-connector安装发现失败时先向用户要确切 URL必要时再建议 Flare TunnelSettings External Services Flare Tunnel→Create Tunnel→ 将 HTTPS URL 粘贴进a0。总结host-computer-use技能把 Agent Zero 的桌面控制能力从内部沙箱扩展到用户真实宿主机通过 A0 CLI/Launcher host gateway 桥接调用computer_use_remote。其工程精髓在于三层设计可移植契约capabilities.identity.*与dispatch.background决定后台原生循环是否可用、后端感知按backend_family/features自动提示加载 Linux AT-SPI、macOS AX、Windows UIA 专项技能、证据纪律自动附带新鲜截图 仅以截图或确定性结构化结果定论 re-arm 时无条件停止。配合源码中 180 秒操作超时、按动作定制的 settle 延迟、截图历史剪枝与运行时门控这套方案为Agent 操作真实桌面提供了既激进又克制的安全边界。建议任何准备使用该技能的 Agent 先完整阅读 host-computer-use 及对应平台后端技能再接入真实桌面环境。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero host-computer-use 技能指南：通过 A0 CLI 桥接实现宿主机桌面远程控制
Agent Zero host-computer-use 技能指南通过 A0 CLI 桥接实现宿主机桌面远程控制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的_a0_connector插件提供了一条连接宿主机host/local computer与 Docker 化 Agent Zero 运行时的通道而host-computer-use技能正是解锁这条通道上computer_use_remote工具的钥匙。本文完整解析该技能的工具契约、核心循环、三大桌面后端Linux/Wayland AT-SPI、macOS AX、Windows UIA的结构化定位方式、边界规则与证据验证纪律并深入源码揭示自动截图、settle 延迟与 re-arm 信号处理等底层实现帮助读者安全、准确地驱动用户真实桌面的原生应用界面。技能定位何时加载与使用host-computer-use是 plugins/_a0_connector/skills/host-computer-use/SKILL.md 定义的 Beta 技能其 frontmatter 明确了触发词triggerscomputer use、host computer、host desktop、local computer、my screen、Ubuntu Wayland desktop等。凡是涉及用户宿主机/本地电脑的屏幕截图、界面检查、菜单、原生应用 UI、OS 级点击、滚动、输入或需要检查computer_use_remote状态的任务都应加载本技能后再调用工具。需要特别区分两类桌面宿主机桌面host desktop用户真实运行的 Windows/macOS/Linux 桌面由本技能 computer_use_remote负责。Agent Zero 内部桌面internal Agent Zero Desktop运行在 Agent Zero 运行时内的 Linux Desktop/Xpra 表面对应linux-desktop技能、desktopctl.sh等路径无法看到宿主机屏幕。原文档明确划定了三条边界任何情况下都不得跨界替代场景正确路径禁止的替代路径宿主机屏幕操作截图/点击/输入/桌面状态computer_use_remote经 A0 CLI 或 Launcher host gatewaylinux-desktop、Xpra、desktopctl.sh、code_execution_tool、Docker/服务端 shell宿主浏览器控制browser工具Browser 插件自动选择 Docker 或 A0 CLI 宿主浏览器运行时computer_use_remote、code_execution_remote、xdg-open、sensible-browser、Pythonwebbrowser.open宿主机 shell 执行单独加载host-code-execution技能与桌面控制混为一谈对于纯浏览器任务优先使用browser工具——它通常比截屏驱动的桌面控制更可靠且更省 token。若宿主浏览器设置失败或提示远程调试应引导用户在浏览器中打开chrome://inspect/#remote-debugging、开启 Allow remote debugging for this browser instance、运行/browser host on后重试。若computer_use_remote不可用、被禁用或需要重新武装re-arm必须停下并请用户执行/computer-use onLauncher Host 访问时在 A0 Launcher 聊天中执行否则在 A0 CLI 中执行并批准平台权限提示。工具契约computer_use_remote 动作与参数使用前必须调用start_session。基础调用格式{ tool_name: computer_use_remote, tool_args: { action: start_session } }工具要求在每次调用中提供action其合法取值在源码 plugins/_a0_connector/tools/computer_use_remote.py 中以_SUPPORTED_ACTIONS集合固化与技能文档完全一致start_session、status、capture、list_windows、get_window_state、element_action、move、click、scroll、key、type、stop_session后端技能可补充ax_snapshot、ax_action、uia_snapshot、uia_action等后端专属动作。若action非法工具直接返回错误提示不发起任何远端调用。各动作的参数契约如下action必填取值见上后端技能可能额外声明后端专属 action仅当后端元数据明确宣告支持且已加载对应后端技能时才可使用。session_idstart_session之后可选传入。list_windows后端支持时返回原生顶层窗口记录含window_id、pid、app、title、frame、active/focused/visible等标志。get_window_state传入pid和/或window_id返回目标窗口的可访问性树accessibility tree其中包含当前状态下稳定的element_index值。element_action传入最近一次get_window_state返回的element_index可选operation、value/text、dispatch。dispatchbackground、auto或foreground元素动作默认background。movex、y归一化到[0,1]全局屏幕坐标。click可选x、y可选buttonleft/right/middle可选count。scrolldx、dy。keykey或keys。typetext可选submit布尔值。type的submittrue只应用于 URL 或导航式输入输入后立即触发 Enter普通文本字段不要用submittrue应先type如需再单独发送enter。工具的可用性检查是运行时完成的源码execute()首先通过select_computer_use_target_sid()查找已启用本地 Computer Use 且处于可信模式的已连接 CLIcomputer_use_remote.py若没有任何已连接 CLI 宣告启用直接返回提示Enable it in the CLI and choose a trust mode first而不会回退到服务端环境。若 CLI 元数据中status为rearm required则立即返回COMPUTER_USE_REARM_REQUIRED错误。核心循环从会话启动到证据验证技能文档规定了 12 步核心循环这是宿主机桌面控制的标准操作流程先调用start_session。读取返回的backend_id、backend_family、features、contract_version、capabilities当任务需要后端专属能力时加载对应的后端 Computer Use 技能。优先依赖结构化的capabilities对象而非根据 OS 名猜测。capabilities.identity.pid、capabilities.identity.window_id、capabilities.identity.element_index、capabilities.dispatch.background是原生后台循环的可移植契约。若后端通过 capabilities 或native-window-list宣告支持原生窗口列表先调用list_windows再使用坐标。若后端宣告支持窗口状态与 element-index 定位capabilities 或 features对目标pid/window_id调用get_window_state随后使用element_actiondispatch默认background。若element_action报告background_unavailable仅当用户/任务可接受前台控制时才改用dispatch: auto或dispatch: foreground。后端宣告已验证窗口焦点verified window focus时仅用前台element_action的focus操作激活窗口且要求focus_verifiedtrue绝不用press作用于应用/框架/窗口节点来激活。后端宣告目标验证键盘输入target-verified keyboard input时将已验证的活动window_id传给type目标缺失、非活动或不可验证时必须 fail closed拒绝输入。最终成功与否以最新截图或确定性的结构化结果为准不凭记忆判断。交互动作执行后会自动附带一张新截图先检查截图再声称目标结果已达成。仅查询状态用status不启动会话。仅需额外截图、不执行动作时用capture。源码佐证自动截图与 settle 延迟核心循环中的交互动作自动附带新截图在工具实现中有完整支撑。_AUTO_CAPTURE_ACTIONS集合computer_use_remote.py覆盖start_session、element_action、ax_action、uia_action、move、click、scroll、key、type——即所有可能改变桌面状态的动作。动作成功后工具会按动作类型等待不同的 settle 延迟_SETTLE_DELAY_*常量computer_use_remote.pystart_session0.2s、move0.1s、click0.35s、scroll0.35s、ax_action/uia_action0.25s、type0.25s、type(..., submittrue)0.45skey则按按键组合细分含super或alttab时 0.45s全局焦点切换仅enter时 0.3s其余 0.2s。随后以fresh: True、fresh_timeout_seconds: 0.45发起一次capture将最新画面附加到工具结果中computer_use_remote.py。截图以聊天媒体制品保存category 为screenshots、source 为computer-use单张上限 25 MiB并估算约 1500 token 计入历史。值得注意的细节element_action若返回actual_dispatchbackground或none说明是确定性的结构化后台结果不会附加截图——这正对应核心循环第 9 条最新截图或确定性结构化结果的双重判据。截图与历史管理也有专门处理_prune_prior_capture_history()会在新截图写入后将之前的历史截图消息内容替换为[image reference superseded]避免多轮桌面操作导致视觉上下文无界膨胀。后端技能按平台选择结构化定位方案start_session/status返回的backend_family、backend_id与features是选择后端技能的判据工具源码中的_backend_skill_hint()computer_use_remote.py会在会话启动时自动提示应加载的后端技能后端判据backend_id / backend_family / features需加载的技能Linux/Waylandwayland、x11、linux/linux/atspi-tree-snapshot、atspi-structural-targeting、atspi-element-action、atspi-set-valuehost-computer-use-linuxmacOSmacos/macos/accessibility-tree-snapshot、accessibility-structural-targetinghost-computer-use-macosWindowswindows/windows/uia-tree-snapshot、uia-structural-targeting、uia-element-action、uia-window-managementhost-computer-use-windows关键原则后端专属动作不能因为参数名在通用契约中存在就使用。除非连接的 CLI 宣告了对应 feature一律视为不可用。LinuxAT-SPI 结构化定位Linux 后端可宣告atspi-tree-snapshot、atspi-structural-targeting、atspi-element-action、atspi-set-value四个 AT-SPI 结构化 feature。存在时对命名按钮、菜单项、文本字段、对话框、工具栏项、标签页和应用窗口应优先结构化定位而非像素点击。若后端同时宣告native-window-list、window-state、element-index-targeting、background-dispatch优先走通用后台循环list_windows→get_window_state→element_action否则使用 AT-SPI 快照/动作流程{ tool_name: computer_use_remote, tool_args: { action: ax_snapshot, window_id: window_id from list_windows, max_depth: 4, max_nodes: 200 } }ax_snapshot返回路径、角色、名称/标题、描述、框架、状态、动作、文本预览、值与子节点用于选择目标而非作为最终视觉证据。已知window_id时必须传入避免无关应用消耗节点预算。{ tool_name: computer_use_remote, tool_args: { action: ax_action, target: { role: push button, title: OK }, operation: press } }支持的操作press激活按钮/菜单项/标签/复选框等动作承载节点绝不用于应用/框架/窗口节点、focus输入前聚焦可聚焦节点、set_value在可编辑节点设置文本/值传value或text。定位选项优先语义化target稳定的 role title/name/description/text/state/actionpath仅在 UI 未变化时使用最近一次ax_snapshot的返回动作报告歧义时重新快照并收窄 roletitle报告目标缺失时先新快照再考虑坐标。Wayland 注意事项每次状态改变动作后必须用截图取证——AT-SPI 动作与键盘事件只是尝试而非证明Wayland 焦点在活动窗口变化时可能拒绝或重定向输入。除非工具结果明确返回actual_dispatchbackground不得声称 Linux 动作是后台安全的。要将 Linux 窗口置前应从get_window_state定位其 frame/window 元素用element_action、focus操作、dispatch: foreground或auto且仅当结果返回focus_verifiedtrue才继续——被接受的 AT-SPI 调用若没有活动/焦点状态不算激活证明。Linux 文本注入受目标保护必须把已验证的活动window_id传给type若工具返回COMPUTER_USE_WINDOW_REQUIRED或COMPUTER_USE_TARGET_NOT_FOCUSED不要全局输入也不要替换为其他应用目标。GNOME/Wayland 常用快捷键均为尝试SuperH隐藏活动窗口、AltTab切换应用、CtrlL聚焦浏览器地址栏、CtrlT新建标签页文本落错应用时停下并从capture或ax_snapshot重新评估不得基于假定焦点继续输入。部分应用 AT-SPI 树很浅需其自身开启辅助功能支持此时按顺序回退应用原生/浏览器工具 → 可靠键盘路径 → 基于新截图的归一化坐标点击。macOSAX 结构化定位macOS 后端可宣告accessibility-tree-snapshot、accessibility-structural-targeting、accessibility-element-click。存在时优先结构化定位命名控件按钮、菜单项、文本字段、sheet、告警、工具栏项、侧栏行若同时宣告native-window-list、window-state、element-index-targeting、background-dispatch优先通用后台循环。ax_snapshot可传max_depth/max_nodes默认例为 4/200返回前置应用有界辅助功能树含元素路径、角色、标签、框架、启用/聚焦状态、动作与子节点ax_action支持press按钮/菜单项/复选框等、focus文本字段或可聚焦元素、set_value传value或text{ tool_name: computer_use_remote, tool_args: { action: ax_action, target: { role: AXButton, title: OK }, operation: press } }macOS 同样遵循AX 动作是尝试而非证明除非结果明确actual_dispatchbackground不得假定后台完成background_unavailable时仅在前台控制可接受时使用前台分发。窗口操作常用快捷键CommandH隐藏活动应用、CommandM最小化活动窗口执行后必须检查新截图窗口的关闭/最小化/全屏按钮若在 AX 树中可访问优先ax_snapshotax_action而非小坐标点击。权限方面macOS 的Screen Recording影响截图Accessibility / Input Monitoring影响结构化定位与输入出现COMPUTER_USE_REARM_REQUIRED、COMPUTER_USE_APPROVAL_REQUIRED或statusrearm required时立即停止请用户运行/computer-use on并批准系统弹窗。WindowsUIA 结构化定位Windows 后端宣告的 feature 最丰富uia-tree-snapshot、uia-structural-targeting、uia-element-action、uia-window-management、native-window-list、window-state、element-index-targeting、background-dispatch、foreground-dispatch-fallback。存在时对命名控件按钮、菜单项、文本字段、对话框、工具栏项、浏览器地址栏、编辑器字段、列表行优先后台结构化定位。首选循环list_windows找到目标原生窗口get_window_state传目标pid和/或window_idelement_action传返回的element_indexdispatch: background后端报告background_unavailable时才切换auto/foreground。{ tool_name: computer_use_remote, tool_args: { action: element_action, window_id: uia-hwnd:123456, element_index: 7, operation: invoke, dispatch: background } }当新的 window-state 循环不可用时用uia_snapshot检查有界 UIA 树max_depth/max_nodes默认 4/200返回元素路径、角色、名称/标题、automation ID、类名、可选 Terminator 风格 selector、框架、状态、动作与子节点。uia_action支持的操作比前两者更丰富invoke激活按钮/菜单项/复选框等控件focus_window恢复并把所属顶层窗口带到前台minimize、restore、maximize改变所属顶层窗口状态不点标题栏按钮focus激活窗口后聚焦文本字段或可聚焦元素set_value设置文本/值传value或textclick仅当快照显示 click 是可用动作且无结构化操作适配时通过 UIA 包装点击元素close仅当用户明确要求关闭该应用/窗口时关闭所属顶层窗口。{ tool_name: computer_use_remote, tool_args: { action: uia_action, target: { role: Button, title: OK }, operation: invoke } }动作选择纪律优先节点列出的动作节点提供invoke就用invoke而非click后端宣告element-index-targeting时优先element_action保持 background-first 分发契约窗口聚焦/隐藏/恢复/最大化用focus_window/minimize/restore/maximize而非点击标题栏应用内输入先结构化聚焦窗口再对目标字段set_value——全局type结果只证明按键已发送不证明落入目标控件窗口操作、导航、菜单开合、对话框切换等布局变化后复用path前必须重新uia_snapshot像素click仅在结构化 UIA、键盘、浏览器、应用原生方案都不适配时且基于目标清晰的新截图才使用。Windows 会话注意桌面捕获与 UIA 依赖 A0 CLI 运行所在的交互式桌面会话。远程桌面、VM 控制台、UAC 弹窗、提权应用、锁屏、最小化/断开的 RDP 会话、服务会话都可能阻断捕获或 UIA 访问。出现COMPUTER_USE_REARM_REQUIRED、COMPUTER_USE_APPROVAL_REQUIRED、COMPUTER_USE_CAPTURE_UNAVAILABLE、COMPUTER_USE_UIA_UNAVAILABLE或statusrearm required时立即停止请用户修复 Windows 桌面会话不得用服务端截图、Docker 命令、linux-desktop或浏览器回退绕过。几何坐标Windows 捕获可能使用包含多显示器与负原点的虚拟桌面必须以捕获/会话返回的origin_x、origin_y、width、height作为坐标空间归一化[0,1]坐标仅相对该虚拟屏有效。运行纪律证据验证与操作守则技能文档的Operating Rules是一套严格的证据与操作纪律是防止 Agent 在宿主机上盲操作的核心约束只有最新截图或确定性的工具结果才算证据。工具结果声称附了截图但实际看不到图像时停止并报告视觉验证不可用不得基于假定的宿主机状态继续下一个动作。后端宣告支持时优先后台安全原生循环list_windows→get_window_state→element_action。超出宣告的结构化辅助功能支持范围时使用归一化全局屏幕坐标运行时未明确宣告的 window id、element index、后台安全输入、语义点击目标一律不假设。dispatch: foreground视为对用户可见桌面的有意控制仅在判定后台动作不可用或不合适后使用。优先可访问性与语义 UI 路径快捷键、命令面板、菜单加速键、地址/搜索栏、焦点遍历等键盘可达控件有可靠键盘路径时优先key和type而非指针动作。菜单/弹窗打开时视为活动 UI优先键盘导航而非按坐标点击小的瞬态行若点击关掉了菜单/弹窗却没出现预期 UI视为失败。同一方法已连续失败两次且无可见进展切换策略而非重复。不得从聊天日志、侧栏、工具摘要或状态文本推断焦点或任务完成任何状态改变动作必须由最新截图可见确认后才可声称成功。type结果仅在报告focus_verifiedtrue且带目标window_id时确认落点否则只证明全局键盘事件已发送。通过该工具做浏览器导航任务仅当浏览器内容区可见地显示目标页面/结果时才可声称成功。状态改变动作后附加截图看起来没变化先用一次显式capture验证再决定是否重复动作。指针与滚动键盘滚动优先page_down、page_up、space、shiftspace、方向键、home、end。目标窗格已活动或键盘滚动无法命中时用scroll。move与click是最后手段——仅用于后端结构化定位、键盘、浏览器、应用原生工具都无法触达的控件点击前确保最新截图使目标无歧义一次有意的点击后基于新截图重新评估。控制信号与 re-arm 协议用户干预是最高优先级控制信号用户说stop、pause、abort、hold、dont continue或等效表达立即停止且直到用户明确恢复前不得再使用 computer-use 工具。任何工具结果包含COMPUTER_USE_REARM_REQUIRED或statusrearm required时立即终止 computer-use 序列不重试start_session、不调用capture、不用 shell/视觉/截图回退绕过。含义是已连接宿主机配置了 Computer Use但安装的桌面控制后端未武装armed。正确做法是告知用户运行/computer-use onLauncher Host 访问时在 A0 Launcher 聊天否则在 A0 CLI并批准可能出现的平台权限弹窗。该协议在源码层有双重保障execute()入口在分发前检查 CLI 元数据statuscomputer_use_remote.py_format_error()则对COMPUTER_USE_REARM_REQUIRED/COMPUTER_USE_APPROVAL_REQUIRED统一输出标准化的 re-arm 指引computer_use_remote.py。运行时门控技能何时对 Agent 可见computer_use_remote并非始终出现在工具列表中其可见性受运行时门控约束。工具提示词文档 plugins/_a0_connector/prompts/agent.system.tool.computer_use_remote.md 说明当连接的 A0 CLI 或 Launcher host gateway 宣告启用 Computer Use/computer-use on且无需 re-arm 时才展示。启用状态作用于当前 CLI 会话或 Launcher Host 访问租约而非单个聊天上下文——测试 tests/test_a0_connector_prompt_gating.py 中的test_computer_use_remote_prompt_is_cli_session_wide_not_context_scoped专门验证了这一语义。测试文件同样验证了门控的关键分支tests/test_a0_connector_prompt_gating.py无启用的 Computer Use 元数据时工具提示被隐藏statusrearm required时提示被隐藏对应工具入口的 re-arm 拦截启用后提示中才出现tool_name: computer_use_remote与### computer_use_remote段落。另有test_computer_use_remote_prompt_requires_visual_verification_after_actions验证提示词强制要求动作后视觉验证——与技能文档的只有最新截图或确定性工具结果才算证据一致。前置条件A0 CLI 宿主桥接使用本技能前需先建立 A0 CLI 桥接。setup-a0-cli 技能 的指导要点是a0运行在用户宿主机上Agent Zero 留在 Docker/沙箱中。全新安装时先确认宿主 OSmacOS/Linux 终端curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | shWindows PowerShellirm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex安装后在普通电脑终端而非容器内运行a0它会打开宿主选择器并尽量自动发现本地 Docker 实例需要手动输入时使用用户当前打开 Agent Zero 的确切 URL含实际端口不得臆测或套用文档示例端口隧道 URL 原样粘贴、无需追加端口。连接器返回404通常意味着运行中的 Agent Zero 构建缺少内置_a0_connector需更新 Agent Zero。安装脚本不可达但uv可用时可用uv tool install --upgrade githttps://github.com/agent0ai/a0-connector安装发现失败时先向用户要确切 URL必要时再建议 Flare TunnelSettings External Services Flare Tunnel→Create Tunnel→ 将 HTTPS URL 粘贴进a0。总结host-computer-use技能把 Agent Zero 的桌面控制能力从内部沙箱扩展到用户真实宿主机通过 A0 CLI/Launcher host gateway 桥接调用computer_use_remote。其工程精髓在于三层设计可移植契约capabilities.identity.*与dispatch.background决定后台原生循环是否可用、后端感知按backend_family/features自动提示加载 Linux AT-SPI、macOS AX、Windows UIA 专项技能、证据纪律自动附带新鲜截图 仅以截图或确定性结构化结果定论 re-arm 时无条件停止。配合源码中 180 秒操作超时、按动作定制的 settle 延迟、截图历史剪枝与运行时门控这套方案为Agent 操作真实桌面提供了既激进又克制的安全边界。建议任何准备使用该技能的 Agent 先完整阅读 host-computer-use 及对应平台后端技能再接入真实桌面环境。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考