ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Agent Zero Windows 主机桌面控制实战:computer_use_remote 的 UIA 结构定位、会话限制与截图校验指南

Agent Zero Windows 主机桌面控制实战:computer_use_remote 的 UIA 结构定位、会话限制与截图校验指南 Agent Zero Windows 主机桌面控制实战computer_use_remote 的 UIA 结构定位、会话限制与截图校验指南【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文面向通过 Agent Zero 的 A0 Connector_a0_connector插件连接 Windows 宿主机的场景系统讲解computer_use_remote工具在 Windows 后端下的完整用法如何识别 Windows UI AutomationUIA能力、如何使用list_windows→get_window_state→element_action的后台优先循环、如何通过uia_snapshot/uia_action进行结构化的控件定位与操作以及 RDP、UAC、锁定屏幕等 Windows 会话限制和几何坐标约束。读完本文你将能够在 Windows 宿主机上安全、可靠地驱动原生桌面 UI并正确理解UIA 动作只是尝试、不是证据这一核心验证原则。本文是host-computer-use-windows技能文档plugins/_a0_connector/skills/host-computer-use-windows/SKILL.md的完整展开并以该技能所属的 A0 Connector 插件 中computer_use_remote工具的源码与测试作为佐证。一、技能定位何时加载 host-computer-use-windowshost-computer-use-windows是 Agent Zero 针对 Windows 宿主机后端的后端专属技能。它不是一个独立入口而是通用技能 host-computer-use/SKILL.md 的 Windows 补充层遵循先加载通用技能、再按后端加载专属技能的分层设计。加载该技能的前提是computer_use_remote的status或start_session返回结果中报告backend_family或backend_id为windows或者features中包含uia-tree-snapshot、uia-structural-targeting等 Windows UI Automation 特征。从工具源码看这一判定逻辑在 computer_use_remote.py 的_backend_skill_hint中落地当backend_id windows或backend_family windows或 features 命中uia-tree-snapshot/uia-structural-targeting/uia-element-action/uia-window-management任一特征时start_session/status的结果会附带提示Load skillhost-computer-use-windows。测试用例 tests/test_a0_connector_prompt_gating.py 也验证了Windows 技能内容含uia_snapshot、uia_action、focus_window、minimize、invoke优先于click等规则会被注入提示词且这些后端专属 action 不会出现在通用技能中。明确的边界约束该技能不适用于 Linux、macOS、Xpra、Docker 或纯浏览器任务。如果后端不是 Windows或不声明任何 UIA 支持则跳过 UIA 动作回到通用host-computer-use规则。同理Windows 的技能规则也不得反向套用到 Linux对应 host-computer-use-linux/SKILL.md或 macOS对应 host-computer-use-macos/SKILL.md后端——每个后端的结构树体系AT-SPI / AX / UIA彼此独立。二、Windows UIA 能力特征与选择依据Windows 后端可能在其 capabilities / features 中声明以下结构性 UI Automation 特征特征名含义uia-tree-snapshot支持 UIA 结构树快照对应uia_snapshot动作uia-structural-targeting支持基于结构的语义定位而非像素坐标uia-element-action支持对 UIA 元素的调用对应uia_actionuia-window-management支持focus_window/minimize/restore/maximize等窗口管理操作native-window-list支持原生顶层窗口列表对应list_windowswindow-state支持获取目标窗口的可访问性状态树对应get_window_stateelement-index-targeting支持用稳定的element_index定位元素对应element_actionbackground-dispatch支持后台分发不抢占前台焦点foreground-dispatch-fallback支持在后台不可用时回退到前台分发当这些特征存在时应优先采用后台结构定位而非像素点击尤其是针对命名控件按钮buttons、菜单项menu items、文本字段text fields、对话框dialogs、工具栏项toolbar items、浏览器地址栏browser address bars、输入框composer fields以及列表行list rows。从 computer_use_remote.py 的_SUPPORTED_ACTIONS可以看到工具层对 Windows 专属动作uia_snapshot、uia_action与通用动作list_windows、get_window_state、element_action是并列支持的且uia_action与element_action都位于_AUTO_CAPTURE_ACTIONS集合中——即执行后会自动附带一张新鲜截图用于校验。此外_SETTLE_DELAY_UIA_ACTION 0.25表明每次 UIA 动作后工具会等待约 0.25 秒再抓取验证截图。三、首选操作循环list_windows → get_window_state → element_action在 Windows 后端声明了窗口列表、窗口状态和元素索引能力时首选的后台安全循环与通用技能一致共四步调用list_windows找到目标原生窗口返回窗口的window_id、pid、标题、角色、frame 等信息以目标pid和/或window_id调用get_window_state获取该窗口的可访问性状态树其中包含当前状态下的稳定element_index使用返回的element_index调用element_action并设置dispatch: background后台分发优先如果后端报告background_unavailable仅在前台控制可接受的前提下切换到dispatch: auto或dispatch: foreground。典型请求示例{ tool_name: computer_use_remote, tool_args: { action: element_action, window_id: uia-hwnd:123456, element_index: 7, operation: invoke, dispatch: background } }源码中对element_action的参数透传pid、window_id、element_index、path、operation、name、dispatch、value、text、submit、target、selector在_build_payload中均有对应处理结果格式化_format_element_action会明确区分requested_dispatch与actual_dispatch若后台不可用会返回background_unavailable并提示改用auto/foreground若发生了前台回退则标记foreground_fallback_usedtrue。也就是说是否真正后台执行以结果中的actual_dispatch为准这与 Linux 技能中不得声称后台安全除非显式返回actual_dispatchbackground的纪律一致。四、UIA 结构树快照uia_snapshot当较新的window-state循环不可用时使用uia_snapshot来检视有界bounded的 Windows UI Automation 树{ tool_name: computer_use_remote, tool_args: { action: uia_snapshot, max_depth: 4, max_nodes: 200 } }快照返回的信息包括元素路径element paths、角色roles、名称/标题names/titles、自动化 IDautomation IDs、类名class names、可选的 Terminator 风格选择器selectors、frame、启用/聚焦状态enabled/focused state、可用动作actions以及子节点child nodes。从 computer_use_remote.py 的_format_uia_snapshot与_structural_node_line实现可以看到快照文本的组织方式每个节点一行展示element_index若存在、path、role、首选的名称字段title/name/automation_id/class_name 取其一、frame、actions最多列 6 个、states最多 8 个与text。_structural_tree_outline会把树按缩进逐层展开超过 80 行即截断并提示request a narrower max_depth/max_nodes。关键原则快照用于选择元素而不是最终的可视化证明。目标选定后所有状态变更动作仍需依靠动作后附带的新鲜截图来判断结果。五、UIA 结构化动作uia_action当需要执行结构化动作时使用uia_action通过语义化的target角色 标题等而非像素坐标定位{ tool_name: computer_use_remote, tool_args: { action: uia_action, target: { role: Button, title: OK }, operation: invoke } }支持的 operationinvoke激活按钮、菜单项、复选框等类似控件focus_window恢复并将所属顶层窗口带到前台minimize/restore/maximize改变所属顶层窗口状态不要点击标题栏按钮focus在激活窗口后聚焦文本字段或可聚焦元素set_value设置文本/值需传value或textclick仅当快照表明 click 是可用动作、且没有合适的结构化操作时才通过 Windows UIA 封装执行点击close仅当用户明确要求关闭该应用/窗口时关闭所属顶层窗口。定位targeting选项当控件具有稳定的角色 标题/名称、自动化 ID、类名、句柄、进程 ID、框架 ID 或选择器时优先使用语义化target使用最近一次uia_snapshot返回的path时仅在 UI 未变化的前提下有效可以传快照给出的selector或target.selector例如role:Button name:OK若动作报告歧义ambiguity重新拍摄快照用角色 标题/名称/自动化 ID/类名收窄目标若动作报告找不到目标missing target先重新拍摄快照再考虑坐标方案。动作选择纪律优先采用目标节点列出的动作如果节点提供invoke就用invoke而不是click当后端声明element-index-targeting时优先用element_action而非uia_action——它保持了后台优先的分发契约窗口聚焦、隐藏、恢复、最大化等操作用focus_window/minimize/restore/maximize不要点击标题栏按钮向应用输入文本时先结构化聚焦应用/窗口如需再对目标字段执行set_value。全局type结果只证明按键已发出不能证明落到了预期控件窗口操作、导航、菜单开合、对话框切换或其他布局变化之后必须重新拍摄uia_snapshot再复用 path像素级click只在结构化 UIA、键盘、浏览器和应用原生方案都不适用时使用且必须基于一张新鲜截图、目标无歧义。上述invoke优先于click等规则被 tests/test_a0_connector_prompt_gating.py 明确断言确保 Windows 技能注入的提示词内容与文档一致。核心纪律UIA 动作是尝试attempts不是证据proof。状态变更动作后工具会自动附带一张新鲜截图对应源码中_AUTO_CAPTURE_ACTIONS包含uia_action以及_maybe_attach_latest_capture中的_SETTLE_DELAY_UIA_ACTION延迟与fresh: True抓取逻辑。在声称请求的结果已达成之前必须先检查这张截图。六、Windows 会话限制Session CaveatsWindows 的桌面捕获与 UI Automation 依赖 A0 CLI 运行所在的交互式桌面会话。以下场景可能导致捕获或 UIA 访问不可用远程桌面Remote Desktop会话VM 控制台VM consolesUAC 提权提示UAC prompts提权应用elevated apps锁定屏幕locked screens最小化或断开的 RDP 会话minimized/disconnected RDP sessions以服务方式运行services。当computer_use_remote返回以下任一信号时立即停止并请用户重新武装re-arm或修复 Windows 桌面会话COMPUTER_USE_REARM_REQUIREDCOMPUTER_USE_APPROVAL_REQUIREDCOMPUTER_USE_CAPTURE_UNAVAILABLECOMPUTER_USE_UIA_UNAVAILABLEstatusrearm required严禁用服务器截图、Docker 命令、linux-desktop或浏览器回退来绕过权限/会话失败。源码层面_format_error对COMPUTER_USE_REARM_REQUIRED与COMPUTER_USE_APPROVAL_REQUIRED统一输出Stop using computer_use_remote for now; ask the user to re-arm Computer Use with/computer-use on... and approve the platform permission prompt并且_extract_result之前execute方法内还会在metadata.status rearm required时直接短路返回拒绝继续执行任何动作。这与通用技能 host-computer-use/SKILL.md 的不要重试start_session、不要调用capture、不要用 shell/vision/screenshot 回退绕过的硬性要求完全一致。七、几何与坐标系多显示器与负原点Windows 捕获可以使用虚拟桌面virtual desktop其中可能包含多个显示器且原点可能为负值。坐标处理规则如下以捕获/会话返回的origin_x、origin_y、width、height作为坐标系空间归一化[0,1]坐标仅相对于该虚拟屏幕使用。这意味着不能把某个单一显示器当作全局坐标系move/click的x、y归一化[0,1]全局屏幕坐标必须基于最近一次捕获提供的虚拟屏幕范围来计算。通用技能的参数契约agent.system.tool.computer_use_remote.md同样强调交互式坐标动作应使用来自最近一次捕获的归一化全局屏幕坐标。在 Windows 多显示器 负原点布局下尤其不要假设坐标从(0,0)开始。八、端到端工作流示例结合上述全部规则一个典型的 Windows 桌面任务例如在记事本中定位并点击帮助菜单项流程如下status确认后端为windowsfeatures 包含uia-*系列 → 加载host-computer-use-windowsstart_session开启会话读取session_id、backend_id、features、capabilitieslist_windows找到目标窗口如无标题 - 记事本记录window_id与pidget_window_state传pid与/或window_id获取窗口状态树与稳定element_indexelement_action传element_index与dispatch: background执行invoke若返回background_unavailable按需改用auto/foreground状态变更后检查工具自动附带的新鲜截图确认 UI 变化若截图缺失或无法查看停止并报告视觉校验不可用不得基于假设状态继续任务完成后stop_session关闭会话。整个过程遵循最新截图或确定性的结构化结果才算证据的规则键盘事件、点击、滚动、键入以及前台回退都是尝试而非成功只有截图可见地确认了目标结果才能声称动作成功。九、小结host-computer-use-windows技能为 Agent Zero 在 Windows 宿主机上的桌面控制提供了三条核心纪律结构优先声明了 UIA 能力就用list_windows→get_window_state→element_action或uia_snapshot→uia_action的结构化路径把像素点击降级为最后手段后台优先默认dispatch: background仅在显式报告不可用且前台控制可接受时才切换是否真正后台以结果的actual_dispatch为准证据优先UIA 动作只是尝试必须用动作后附带的新鲜截图或确定性的结构化结果验证遇到 re-arm / approval / capture / UIA 不可用信号立即停止并向用户求助绝不绕过。想进一步深入可阅读通用技能 host-computer-use/SKILL.md核心循环与操作纪律、工具契约文档 agent.system.tool.computer_use_remote.md、工具实现 computer_use_remote.py动作白名单、自动截图与 re-arm 短路逻辑以及测试 test_a0_connector_prompt_gating.py技能注入与内容断言。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表