Agent Zero 远程主机桌面控制computer_use_remote 工具全解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文以_a0_connector插件的 agent.system.tool.computer_use_remote.md 提示词文档为主体结合插件源码工具实现、WebSocket 运行时、提示词门控与配套技能host-computer-use 系列系统讲解 Agent Zero 如何通过computer_use_remote工具驱动用户本机桌面包括启用前提、行动契约、会话与能力模型、结构化工件定位、视觉验证纪律、后端技能矩阵与错误恢复流程。读完本文你将掌握这一 Beta 级桌面控制工具的全部行动语义、参数用法与源码级工作原理。一、工具定位唯一的宿主桌面控制通道computer_use_remote是 Agent Zero 中面向用户本机host/local桌面的远程控制工具。它的核心特征是由 A0 CLI 或 Launcher Host 网关桥接只有当已连接的 A0 CLI 或 Launcher Host 网关宣告启用了 Computer Use/computer-use on且不需要重新武装re-arm时该工具才会在提示词中显示运行时门控工具真正执行时会再次检查可用性、后端支持、信任模式、宿主桥接存在性、本地启用状态与 re-arm 状态而非仅凭提示词中的出现与否作用域是会话而非聊天Computer Use 的启用状态绑定到当前 CLI 会话或 Launcher Host 访问租约access lease而不是绑定到单个聊天上下文chat context。文档明确给出了工具的使用边界agent.system.tool.computer_use_remote.md适用宿主桌面 UI 检视、截屏、后端支持时的后台安全窗口/元素操作、点击、滚动、打字、按键与状态检查不适用普通网页导航或宿主浏览器控制——网页任务应使用browser工具除非浏览器自动化无法表达该任务严禁替代linux-desktop技能、Agent Zero Desktop/Xpra 表面、desktopctl.sh、code_execution_tool、Docker/服务器 shell 命令都不能用于宿主屏幕操作因为它们只能看到 Agent Zero 内部运行时无法看到或控制用户宿主屏幕复杂桌面任务先加载并遵循host-computer-use技能再继续。从源码看该提示词通过 remote_tool_prompts.py 中的REMOTE_TOOL_PROMPTS字典注册并由should_include_remote_tool_prompt/remote_tool_prompt_availability做按上下文门控只有当ws_runtime.computer_use_metadata_for_sid(sid)报告supported、enabled且status ! rearm required时computer_use_remote的提示词才会注入模型上下文避免在不可用环境下诱导 Agent 误用。二、启用前提与作用域/computer-use on与 re-arm文档规定当工具报告以下情况时Agent 必须停止并请用户处理而不是自行绕过没有 CLI/Launcher 宿主桥接Computer Use 被禁用返回COMPUTER_USE_REARM_REQUIRED。对应的用户侧操作是在使用 Launcher Host 访问时在 A0 Launcher 聊天中运行/computer-use on使用 A0 CLI 时在 CLI 中运行/computer-use on并批准任何宿主权限提示。源码印证了这一机制computer_use_remote.py 在execute入口先通过select_computer_use_target_sid(context_id)寻找可用宿主找不到即返回“没有连接的 CLI 宣告启用本地 Computer Use”的错误随后检查computer_use_metadata_for_sid(sid)的status若为rearm required则直接返回COMPUTER_USE_REARM_REQUIRED错误并明确要求用户重新武装、不要重试或使用截屏回退。运行时元数据的完整定义见 ws_runtime.py 中的ComputerUseMetadata数据类它承载了supported、enabled、trust_mode、status、last_error、restore_token_present、artifact_root、backend_id、backend_family、features、contract_version、capabilities等字段——这就是工具每次调用前“运行时检查”所依据的事实来源。store_sid_computer_use_metadata在连接建立时由 CLI 上报并落库select_computer_use_target_sid只选择supported and enabled的会话。三、工具契约行动action与参数工具的标准调用形式如下文档原例{ tool_name: computer_use_remote, tool_args: { action: status } }必填参数参数取值说明actionstart_session、status、capture、list_windows、get_window_state、element_action、move、click、scroll、key、type、stop_session后端技能可额外文档化后端专属 action 值源码 computer_use_remote.py 中的_SUPPORTED_ACTIONS集合在此基础上还包含ax_snapshot、ax_action、uia_snapshot、uia_action四类后端结构化工件行动分别对应 Linux AT-SPI 与 Windows UIAaction不在集合内时工具会直接返回错误提示。各行动的可选参数行动可选参数说明start_sessionsession_id会话返回后用于后续行动get_window_statepid、window_id定位原生窗口element_actionpid、window_id、element_index、operation、dispatch定位元素并执行操作operationinvoke、press、set_value、focus或后端专属操作元素级操作dispatchbackground、auto、foregroundelement_action优先backgroundmove/clickx、y归一化[0,1]全局屏幕坐标clickbuttonleft/right/middle、count点击键与次数scrolldx、dy滚动量keykey或keys按键值typetext、submit、window_id输入文本Linux 目标验证输入还需window_idsubmit为 Enter 后是否提交list_windowsinclude_hidden、include_offscreen、max_windows窗口列表过滤源码_build_payload支持get_window_statemode、max_depth、max_nodes窗口树深度与节点上限_build_payload的实现细节值得注意computer_use_remote.pyclick的count会被_coerce_int强制为整数默认 1button默认leftscroll兼容delta_x/delta_y别名默认 0key优先keys可传列表其次key支持分隔组合键如alttabtype支持submit布尔标志与目标window_idelement_action支持path、name、value、text、target对象与selectorax_action/uia_action支持target含role/title等语义字段、path、operation、value、text、selector。四、会话、状态与能力模型文档规定了一套清晰的会话纪律start_session先行任何屏幕驱动任务前先调用status只看状态不开启会话时用于查询capture只截屏不需要伴随行动时获取屏幕stop_session收尾桌面任务完成后结束会话。status/start_session的结果中应读取backend_id、backend_family、features以及结构化的capabilities对象。权威的跨平台契约是capabilities中的四个字段capabilities.identity.pid支持按进程 ID 定位capabilities.identity.window_id支持按窗口 ID 定位capabilities.identity.element_index支持按元素索引定位capabilities.dispatch.background支持原生后台分发循环。features用于后端专属的细化与技能选择。源码中_format_status会输出status、trust_mode、backend_id/backend_family、contract_version、features与active_contexts_backend_skill_hint则依据backend_id、backend_family与特征集合自动提示加载对应的后端技能。当能力报告支持原生窗口、窗口状态、元素索引与后台分发时文档要求优先采用结构化工件定位循环list_windows - get_window_state - element_action(dispatch: background)只有不具备结构化支持时才退回到基于最新截屏的归一化全局屏幕坐标的交互式坐标操作。五、视觉验证纪律行动即尝试截屏才算数文档用整段篇幅强调一个核心原则状态变更行动会自动附加一张新鲜截屏除非后端返回确定性的结构后台结果但按键、点击、滚动、打字都只是“尝试”而非“成功”前台回退同样如此。在声明目标结果达成之前必须检查最新附加的截屏或在不明确/未变化时做一次显式capture。具体规则包括工具说附加了截屏但模型无法真正查看图像时停止并报告“视觉验证不可用”不得基于假定的宿主状态继续行动type结果只证明键盘事件已发送除非它同时报告focus_verifiedtrue且带有目标window_id一次element_action若报告background_unavailable仅当对用户/任务可接受时才使用dispatch: auto或foreground。源码实现了这一纪律_AUTO_CAPTURE_ACTIONS集合定义了触发自动截屏的行动start_session、element_action、ax_action、uia_action、move、click、scroll、key、type_maybe_attach_latest_capture在行动成功后按行动类型等待不同的settle 延迟如click0.35s、scroll0.35s、type0.25s、submit0.45s、alttab/super组合键 0.45s再以fresh: true的capture请求拉取新鲜画面截屏通过chat_media.save_image_file或save_image_base64存入screenshots分类来源computer-use单张上限MAX_CAPTURE_ARTIFACT_SIZE_BYTES25 MB并估算CAPTURE_TOKENS_ESTIMATE1500 tokens计入上下文_record_capture会输出坐标空间声明coordinatesnormalized_global_screen [0,1]历史中先前的截屏消息会被_prune_prior_capture_history标记为[image reference superseded]并清零 summary避免陈旧图像干扰判断。六、Linux 专用流程验证聚焦与目标验证输入当 Linux 后端宣告verified-window-focus与target-verified-keyboard-input时文档给出了严格流程从list_windows取一个真实的 frame/window用get_window_state检视它用前台element_action聚焦其窗口元素仅当聚焦结果报告focus_verifiedtrue后才继续type且把同一个window_id传给type绝不通过press应用/框架/窗口节点来激活窗口。配套技能 host-computer-use-linux/SKILL.md 进一步补充了 Linux 细节AT-SPI 结构特性atspi-tree-snapshot、atspi-structural-targeting、atspi-element-action、atspi-set-value使用ax_snapshot检视 AT-SPI 树可传window_id、max_depth、max_nodes限定预算用ax_action执行press/focus/set_value真后台分发在 Linux 上依赖合成器、工具包与应用除非结果明确报告actual_dispatchbackground否则不得声称后台安全Linux 文本注入是目标守卫的必须传同一验证激活的window_id若返回COMPUTER_USE_WINDOW_REQUIRED或COMPUTER_USE_TARGET_NOT_FOCUSED不得全局打字或替换其他应用目标若 AT-SPI 树过浅按“应用原生/浏览器工具 → 可靠键盘路径 → 新鲜截屏上的归一化坐标点击”的顺序回退。七、后端技能矩阵按能力选择不跨后端套用文档强调某些行动是后端专属的只在其后端技能中有文档。当status/start_session报告后端专属特性或要求加载后端技能时必须先加载并遵循该技能再使用后端专属行动不得把一个后端的指导套用到另一个后端。仓库提供了完整的后端技能矩阵后端判定信号技能结构机制Linux/Waylandbackend_id为wayland/x11/linuxbackend_family为linux或含atspi-*特性host-computer-use-linux/SKILL.mdAT-SPIax_snapshot/ax_actionmacOSbackend_id/backend_family为macos或含accessibility-*特性host-computer-use-macos/SKILL.mdAccessibilityax_snapshot/ax_actionWindowsbackend_id/backend_family为windows或含uia-*特性host-computer-use-windows/SKILL.mdUI Automationuia_snapshot/uia_actionmacOS 技能要点结构特性accessibility-tree-snapshot、accessibility-structural-targeting、accessibility-element-clickax_action操作press按钮/菜单项/复选框、focus、set_value传value/text除非结果明确说actual_dispatchbackground不得假设后台执行background_unavailable时仅在可接受前台控制时使用前台分发权限方面Screen Recording 影响截屏Accessibility/Input Monitoring 影响结构定位与输入返回COMPUTER_USE_REARM_REQUIRED/COMPUTER_USE_APPROVAL_REQUIRED时立即停止并让用户重新武装。Windows 技能要点结构特性含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_id)→element_action(element_index, dispatch: background)uia_action操作更丰富invoke、focus_window、minimize、restore、maximize、focus、set_value、click仅当快照显示 click 可用且无结构操作匹配、close仅当用户明确要求关闭节点提供invoke时用invoke而非click窗口聚焦/隐藏/恢复/最大化用窗口管理操作不点击标题栏按钮会话注意Windows 桌面捕获与 UIA 依赖 A0 CLI 所在交互式桌面会话远程桌面、VM 控制台、UAC 弹窗、提权应用、锁屏、最小化/断开的 RDP 会话与服务会话都可能导致捕获或 UIA 不可用几何注意Windows 捕获可覆盖多显示器虚拟桌面并含负坐标原点应使用 capture/session 的origin_x、origin_y、width、height作为坐标空间[0,1]归一化坐标只相对该虚拟屏幕。源码中_backend_skill_hintcomputer_use_remote.py正是依据上述特征集合自动生成“请先加载host-computer-use-linux/-macos/-windows”的提示实现了文档规则在代码层面的落地。八、核心工作流与操作规则综合文档与 host-computer-use/SKILL.md推荐的端到端流程如下start_session开启会话读元数据解析返回的backend_id、backend_family、features、contract_version、capabilities任务需要后端专属能力时加载对应后端技能结构化优先以后端宣告的capabilities为准而不是猜测操作系统名用capabilities.identity.*与capabilities.dispatch.background作为可移植后台循环契约后端支持原生窗口列表时先list_windows再考虑坐标后端支持窗口状态与元素索引时对目标pid/window_id执行get_window_state随后默认element_actiondispatch: backgroundelement_action报告background_unavailable时仅在可接受前台控制时切换auto/foreground后端宣告已验证窗口聚焦时仅用前台element_action的focus操作激活窗口并要求focus_verifiedtrue绝不用press激活应用/框架/窗口节点后端宣告目标验证键盘输入时把验证激活的window_id传给type缺失、未激活或不可验证的目标必须 fail closed最终成功判定只依据最新截屏或确定性结构结果不依据记忆、聊天日志、侧栏、工具摘要或状态文本交互式行动后自动附加新鲜截屏先检视再声明成功用status查询状态不开启会话用capture单独取屏任务完成调用stop_session。操作规则方面文档与技能还要求键盘优先优先用key/type与键盘可达路径快捷键、命令面板、菜单加速键、地址/搜索栏、焦点遍历指针滚动优先page_down/page_up/space/shiftspace/方向键/home/endscroll用于目标窗格已激活或键盘无法到达move/click是结构定位、键盘、浏览器与应用原生工具都无法到达时的最后手段submittrue只用于 URL 或导航式输入普通文本域先type再单独发enter菜单/弹窗打开时视为活跃 UI优先键盘导航而非按坐标点击小行若点击关掉了菜单却未产生预期 UI视该次尝试失败同一方法已失败两次且无可见进展时更换策略不要重复相同参数重试失败调用文档明确错误后不得以完全相同参数重复同一行动控制信号用户说stop、pause、abort、hold、dont continue等立即暂停未经用户明确恢复不得再使用 computer-use 工具。九、错误处理与 re-arm 恢复流程文档规定若 Computer Use 调用返回错误不要以相同参数重复同一行动要么报告错误要么仅在任务仍需要时采用实质不同的安全恢复手段。关键错误码与恢复路径错误码 / 状态含义处置COMPUTER_USE_REARM_REQUIRED/statusrearm required后端已配置但未武装停止所有 computer-use 序列不重试start_session、不capture、不用 shell/视觉/截屏回退请用户运行/computer-use on并批准权限COMPUTER_USE_APPROVAL_REQUIRED需要平台权限批准同上请用户批准宿主权限提示COMPUTER_USE_AX_UNAVAILABLELinux 无障碍不可用请用户修复桌面无障碍/会话状态COMPUTER_USE_CAPTURE_UNAVAILABLE/COMPUTER_USE_UIA_UNAVAILABLEWindows 捕获/UIA 不可用请用户修复 Windows 桌面会话源码中_format_error对COMPUTER_USE_REARM_REQUIRED与COMPUTER_USE_APPROVAL_REQUIRED统一输出“停止使用 computer_use_remote请用户重新武装不要重试、不要用截屏回退”的指引_format_status在status rearm required时同样附加 re-arm 指引。技能文档进一步要求不得用服务器截屏、Docker 命令、linux-desktop/Xpra 技能或code_execution_tool绕过权限或宿主可见性失败。十、源码级原理一次调用的完整链路从 computer_use_remote.py 可以还原一次computer_use_remote调用的完整链路参数校验action不在_SUPPORTED_ACTIONS中则直接报错目标选择select_computer_use_target_sid(context_id)从订阅了当前上下文的候选会话中挑选supported and enabled的 CLI/Launcher 宿主候选排序逻辑见 ws_runtime.py 的_candidate_sids_for_context_locked优先订阅当前上下文的会话其次是活跃 Launcher 网关最后是全局未订阅会话re-arm 检查computer_use_metadata_for_sid(sid)的status为rearm required时短路返回载荷构建_build_payload按行动组装op_id、context_id、action与各行动专属参数WebSocket 分发_dispatch_payload通过store_pending_computer_use_op注册待完成操作含事件循环与 future经get_shared_ws_manager().emit_to向目标 sid 发送connector_computer_use_op事件随后asyncio.wait_for等待结果超时COMPUTER_USE_OP_TIMEOUT180 秒CLI 侧结果通过resolve_pending_computer_use_op回填 future见 ws_runtime.py自动截屏行动成功且属于_AUTO_CAPTURE_ACTIONS时按行动类型的 settle 延迟后发起fresh: true的capture并将截屏写入历史估算约 1500 tokens旧截屏标记为已被替代结果格式化_extract_result按行动输出人类可读结果——start_session输出session_id与分辨率、list_windows输出窗口明细含window_id、pid、app、title、frame、状态标志超 40 个截断、get_window_state/ax_snapshot/uia_snapshot输出带element_index/path/role/frame/actions/states/text的结构树轮廓最多 80 行、type依据focus_verified与window_id区分“验证目标”与“仅全局发送”连接异常ConnectionNotFoundErrorCLI 已断开、asyncio.TimeoutError180 秒未返回均有专属错误消息。值得一提的细节element_action的自动截屏会检查actual_dispatch若为background/none结构后台结果则不再附加截屏——这与文档“除非后端返回确定性的结构后台结果”的规定完全一致。十一、实战建议与使用边界总结实战要点把host-computer-use技能作为复杂桌面工作流的前置加载项涉及后端专属结构行动时再按status/start_session报告的后端与特性加载host-computer-use-linux/-macos/-windows以capabilities而非 OS 名称作为能力判断依据能走list_windows - get_window_state - element_action结构化后台循环就绝不先点坐标每一次状态变更后先看新鲜截屏再断言成功看不到截屏就停止并报告视觉验证不可用键盘优先、结构优先、submittrue仅限导航输入同一失败不重复连续两次无进展就换策略遇COMPUTER_USE_REARM_REQUIRED立即停止并引导用户/computer-use on绝不绕行。边界提醒文档原话要点网页与宿主浏览器请用browser工具computer_use_remote只承接浏览器工具无法表达桌面/浏览器界面任务宿主桌面控制唯一路径是computer_use_remote不得以linux-desktop、Xpra、desktopctl.sh、code_execution_tool、Docker/server shell 替代后端专属行动只有在对应后端宣告匹配特性后才可用参数名存在不意味着能力存在用户干预是最高优先级控制信号stop/pause/abort等指令出现立即暂停。相关资源索引工具提示词原文agent.system.tool.computer_use_remote.md工具实现computer_use_remote.pyWebSocket 运行时与元数据ws_runtime.py提示词门控remote_tool_prompts.py通用技能host-computer-use/SKILL.md后端技能host-computer-use-linux/SKILL.md、host-computer-use-macos/SKILL.md、host-computer-use-windows/SKILL.md提示词门控测试test_a0_connector_prompt_gating.py、行动契约测试test_tool_action_contracts.py【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考