企业官网建设流程全解析

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 必须停止并请用户处理，而不是自行绕过：

1. 没有 CLI/Launcher 宿主桥接；
2. Computer Use 被禁用；
3. 返回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" } }

必填参数

源码 computer_use_remote.py 中的_SUPPORTED_ACTIONS集合在此基础上还包含ax_snapshot、ax_action、uia_snapshot、uia_action四类后端结构化工件行动（分别对应 Linux AT-SPI 与 Windows UIA），action不在集合内时工具会直接返回错误提示。

各行动的可选参数

_build_payload的实现细节值得注意（computer_use_remote.py）：

• click的count会被_coerce_int强制为整数，默认 1；button默认left；
• scroll兼容delta_x/delta_y别名，默认 0；
• key优先keys（可传列表），其次key（支持+分隔组合键，如"alt+tab"）；
• type支持submit布尔标志与目标window_id；
• element_action支持path、name、value、text、target对象与selector；
• ax_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_verified=true且带有目标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、alt+tab/super组合键 0.45s），再以fresh: true的capture请求拉取新鲜画面；
• 截屏通过chat_media.save_image_file或save_image_base64存入screenshots分类（来源computer-use），单张上限MAX_CAPTURE_ARTIFACT_SIZE_BYTES（25 MB），并估算CAPTURE_TOKENS_ESTIMATE（1500 tokens）计入上下文；
• _record_capture会输出坐标空间声明coordinates=normalized_global_screen [0,1]；
• 历史中先前的截屏消息会被_prune_prior_capture_history标记为[image reference superseded]并清零 summary，避免陈旧图像干扰判断。

六、Linux 专用流程：验证聚焦与目标验证输入

当 Linux 后端宣告verified-window-focus与target-verified-keyboard-input时，文档给出了严格流程：

1. 从list_windows取一个真实的 frame/window；
2. 用get_window_state检视它；
3. 用前台element_action聚焦其窗口元素；
4. 仅当聚焦结果报告focus_verified=true后才继续type，且把同一个window_id传给type；
5. 绝不通过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_dispatch=background，否则不得声称后台安全；
• Linux 文本注入是目标守卫的：必须传同一验证激活的window_id，若返回COMPUTER_USE_WINDOW_REQUIRED或COMPUTER_USE_TARGET_NOT_FOCUSED，不得全局打字或替换其他应用目标；
• 若 AT-SPI 树过浅，按“应用原生/浏览器工具 → 可靠键盘路径 → 新鲜截屏上的归一化坐标点击”的顺序回退。

七、后端技能矩阵：按能力选择，不跨后端套用

文档强调：某些行动是后端专属的，只在其后端技能中有文档。当status/start_session报告后端专属特性或要求加载后端技能时，必须先加载并遵循该技能，再使用后端专属行动；不得把一个后端的指导套用到另一个后端。

仓库提供了完整的后端技能矩阵：

macOS 技能要点：

• 结构特性accessibility-tree-snapshot、accessibility-structural-targeting、accessibility-element-click；
• ax_action操作：press（按钮/菜单项/复选框）、focus、set_value（传value/text）；
• 除非结果明确说actual_dispatch=background，不得假设后台执行；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_hint（computer_use_remote.py）正是依据上述特征集合自动生成“请先加载host-computer-use-linux/-macos/-windows”的提示，实现了文档规则在代码层面的落地。

八、核心工作流与操作规则

综合文档与 host-computer-use/SKILL.md，推荐的端到端流程如下：

1. start_session开启会话；
2. 读元数据：解析返回的backend_id、backend_family、features、contract_version、capabilities，任务需要后端专属能力时加载对应后端技能；
3. 结构化优先：以后端宣告的capabilities为准，而不是猜测操作系统名；用capabilities.identity.*与capabilities.dispatch.background作为可移植后台循环契约；
4. 后端支持原生窗口列表时，先list_windows再考虑坐标；
5. 后端支持窗口状态与元素索引时，对目标pid/window_id执行get_window_state，随后默认element_action+dispatch: "background"；
6. element_action报告background_unavailable时，仅在可接受前台控制时切换auto/foreground；
7. 后端宣告已验证窗口聚焦时，仅用前台element_action的focus操作激活窗口，并要求focus_verified=true，绝不用press激活应用/框架/窗口节点；
8. 后端宣告目标验证键盘输入时，把验证激活的window_id传给type；缺失、未激活或不可验证的目标必须 fail closed；
9. 最终成功判定只依据最新截屏或确定性结构结果，不依据记忆、聊天日志、侧栏、工具摘要或状态文本；
10. 交互式行动后自动附加新鲜截屏，先检视再声明成功；
11. 用status查询状态（不开启会话），用capture单独取屏；
12. 任务完成调用stop_session。

操作规则方面，文档与技能还要求：

• 键盘优先：优先用key/type与键盘可达路径（快捷键、命令面板、菜单加速键、地址/搜索栏、焦点遍历），指针滚动优先page_down/page_up/space/shift+space/方向键/home/end；
• scroll用于目标窗格已激活或键盘无法到达；move/click是结构定位、键盘、浏览器与应用原生工具都无法到达时的最后手段；
• submit=true只用于 URL 或导航式输入，普通文本域先type再单独发enter；
• 菜单/弹窗打开时视为活跃 UI，优先键盘导航而非按坐标点击小行；若点击关掉了菜单却未产生预期 UI，视该次尝试失败；
• 同一方法已失败两次且无可见进展时更换策略，不要重复相同参数重试失败调用（文档明确：错误后不得以完全相同参数重复同一行动）；
• 控制信号：用户说stop、pause、abort、hold、don't continue等立即暂停，未经用户明确恢复不得再使用 computer-use 工具。

九、错误处理与 re-arm 恢复流程

文档规定，若 Computer Use 调用返回错误：不要以相同参数重复同一行动，要么报告错误，要么仅在任务仍需要时采用实质不同的安全恢复手段。

关键错误码与恢复路径：

源码中_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调用的完整链路：

1. 参数校验：action不在_SUPPORTED_ACTIONS中则直接报错；
2. 目标选择：select_computer_use_target_sid(context_id)从订阅了当前上下文的候选会话中挑选supported and enabled的 CLI/Launcher 宿主（候选排序逻辑见 ws_runtime.py 的_candidate_sids_for_context_locked：优先订阅当前上下文的会话，其次是活跃 Launcher 网关，最后是全局未订阅会话）；
3. re-arm 检查：computer_use_metadata_for_sid(sid)的status为rearm required时短路返回；
4. 载荷构建：_build_payload按行动组装op_id、context_id、action与各行动专属参数；
5. 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_TIMEOUT（180 秒）；CLI 侧结果通过resolve_pending_computer_use_op回填 future（见 ws_runtime.py）；
6. 自动截屏：行动成功且属于_AUTO_CAPTURE_ACTIONS时，按行动类型的 settle 延迟后发起fresh: true的capture，并将截屏写入历史（估算约 1500 tokens），旧截屏标记为已被替代；
7. 结果格式化：_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区分“验证目标”与“仅全局发送”；
8. 连接异常：ConnectionNotFoundError（CLI 已断开）、asyncio.TimeoutError（180 秒未返回）均有专属错误消息。

值得一提的细节：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结构化后台循环就绝不先点坐标；
• 每一次状态变更后先看新鲜截屏再断言成功；看不到截屏就停止并报告视觉验证不可用；
• 键盘优先、结构优先、submit=true仅限导航输入；同一失败不重复，连续两次无进展就换策略；
• 遇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.py
• WebSocket 运行时与元数据：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