UFO² 数据收集服务器详解MCP 框架驱动的只读观测层与 UICollector 实战指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO导读本文深入解析 UFO² 框架中的数据收集服务器Data Collection Servers—— 一类由框架自动调用、为 LLM 构建观察上下文的只读 MCP 服务器。你将理解它与可被 LLM 主动选择的 Action Servers 的本质区别、工具键与配置体系掌握内置 UICollector 的 8 个观测工具及其源码实现原理并学会通过config/ufo/mcp.yaml为 HostAgent / AppAgent 正确配置观测层最终在观察—推理—执行—验证的 Agent 循环中落地一套稳健、高性能的 UI 状态采集方案。上图展示了 UFO² 中 MCP 服务器层与 AppAgent 的协作关系Shared GUI MCP Server 承载共享的 GUI 观测与自动化能力App-Level API MCP Servers 为不同应用Edge、Outlook、PowerPoint 等提供专属工具而数据收集服务器正是这一架构中负责读取系统状态的只读部分。一、什么是数据收集服务器框架驱动的眼睛Data Collection Servers提供一组只读工具用于观察并检索系统状态而不修改任何状态。它们是 Agent 在采取行动之前理解当前环境的关键前提。与可被 LLM 主动选择的 Action Servers 不同数据收集服务器具有三个核心定位Framework-Driven框架驱动由 UFO² 框架自动调用用于采集截图、UI 控件、系统信息等上下文Observation Purpose观察用途采集结果被拼装进 LLM 的观察提示词observation prompt作为决策依据Not in Tool List不在工具列表中这些工具不会作为可选动作呈现给 LLMAgent 无法选择它们。只有 Action Servers动作服务器才是 LLM 可选中的。关于动作服务器的完整说明可参考 Action Servers。数据收集在 Agent 执行流程中的位置如下数据收集服务器的五大特性特性说明❌无副作用不会修改系统状态只读取信息✅可安全重试可被多次调用而无任何风险✅幂等相同输入始终产生相同输出仅观察仅为决策提供信息框架调用不可被 LLM Agent 选择这一设计遵循了 MCP 架构中的关注点分离原则详见 MCP OverviewAgent 决定做什么高层规划MCP 服务器实现怎么做底层执行Computer 负责二者之间的路由。二、Tool Type 标识符与工具键格式所有数据收集工具使用统一的工具类型标识符tool_type data_collection工具键tool_key遵循如下格式tool_key data_collection::{tool_name} # 示例 data_collection::take_screenshot data_collection::get_window_list data_collection::get_control_info在源码层工具键被Computerufo/client/computer.py用于将来自 Agent 的Command路由到具体的 MCP 服务器工具上_data_collection_namespaces data_collection、_action_namespaces action。这意味着框架在构建观察上下文时只会在data_collection命名空间下寻找并执行工具而action命名空间的工具则仅作为 LLM 可选项暴露在提示词中。三、内置数据收集服务器UICollector 完全解析3.1 服务器信息总览UICollector是 UFO² 内置的数据收集 MCP 服务器负责收集 UI 元素信息与截图为 LLM 决策构建观察上下文。属性值NamespaceUICollectorServer NameUFO UI Data MCP ServerPlatformWindows基于 pywinautoBackendUIAutomation (UIA) 或 Win32Tool Typedata_collectionTool Key Formatdata_collection::{tool_name}DeploymentLocal进程内AgentHostAgent、AppAgentLLM-Selectable❌ 否框架自动调用该服务器共提供8 个工具涵盖截图、窗口列表、控件信息与 UI 树等观测能力。完整工具文档参见 UICollector Full Documentation。3.2 八个观测工具详解① get_desktop_app_info —— 枚举桌面应用窗口获取桌面上所有可见应用窗口的列表窗口名、类型、标识符是 UI 自动化工作流中典型的第一步。参数参数类型必填默认值说明remove_emptybool否True是否移除无可见内容的窗口refresh_app_windowsbool否True是否刷新应用窗口列表返回List[Dict[str, Any]]每个窗口信息字典包含{ id: str, # 唯一窗口标识如 1、2、3 name: str, # 窗口标题/文本 type: str, # 控件类型如 Window、Pane kind: str # 目标类型window }在源码实现中ufo/client/mcp/local_servers/ui_mcp_server.py当refresh_app_windowsTrue时会调用ui_state.control_inspector.get_desktop_app_dict(remove_emptyremove_empty)实时刷新窗口字典否则复用缓存在ui_state.last_app_windows中的结果——这正是下文缓存结果最佳实践的直接实现。② get_desktop_app_target_info —— 结构化窗口目标信息与get_desktop_app_info类似但返回TargetInfo对象而非普通字典为框架内部使用提供更结构化的窗口表示。属性包括id、name、type、kindTargetKind.WINDOW。③ get_app_window_info —— 获取当前选中窗口的详细信息检索当前激活/选中窗口的指定字段。必须先通过select_application_windowHostUIExecutor 的动作工具选中窗口再调用本工具。参数field_list: List[str]必填常见可用字段字段含义control_text窗口标题/文本control_type控件类型如 Windowcontrol_rect包围矩形坐标process_id进程 IDclass_name窗口类名is_visible可见状态is_enabled启用状态返回Dict[str, Any]字段名到值的映射。若未选中窗口源码会抛出ToolError(No window is selected please select a window first.)ui_mcp_server.py。④ get_app_window_controls_info —— 枚举窗口内全部 UI 控件扫描当前选中窗口返回所有可交互控件按钮、文本框等的信息是理解该窗口可执行哪些操作的关键工具。参数field_list: List[str]必填常见字段label控件标识、control_text控件文本、control_typeButton/Edit 等、control_rect、is_enabled、is_visible。返回List[Dict[str, Any]]。⑤ get_app_window_controls_target_info —— 结构化控件目标信息与get_app_window_controls_info类似但返回TargetInfo对象kindTargetKind.CONTROL含source: uia供框架内部消费。⑥ capture_window_screenshot —— 捕获当前选中窗口截图截取当前活动窗口返回base64 编码的 PNG 图像数据是支撑 LLM 视觉能力的关键工具。参数无。返回strbase64 PNG 字符串。错误处理截图失败时返回错误字符串Error: No window selected Error capturing screenshot: {error_details}⑦ capture_desktop_screenshot —— 捕获桌面/主屏幕截图截取整个桌面环境可选所有显示器或仅主屏。参数all_screens: bool可选默认True——True截取所有屏幕False仅主屏。返回strbase64 PNG 图像数据。⑧ get_ui_tree —— 获取完整 UI 树结构检索窗口中全部 UI 元素的层级结构树深入洞察窗口布局与控件关系。参数无。返回Dict[str, Any]嵌套字典表示的控件层级{ control_type: Window, name: Calculator, children: [ {control_type: Pane, name: Display, children: [...]}, {control_type: Button, name: 1} ] }错误处理失败时返回错误字典{error: No window selected}或{error: Error getting UI tree: {details}}。3.3 源码实现原理单例状态 工厂注册从源码结构看UICollector 的底层实现包含两个关键设计ufo/client/mcp/local_servers/ui_mcp_server.py单例 UI 状态UIServerState数据服务器与动作服务器共享同一个单例状态对象包括photographer截图门面对应PhotographerFacade、control_inspector控件检查门面对应ControlInspectorFacade、selected_app_window当前选中窗口由 HostUIExecutor 设置、last_app_windows桌面窗口缓存以及control_dict控件 ID 到控件对象的映射。这保证了HostUIExecutor 选中窗口 → UICollector 读取该窗口的跨服务器协调。窗口/控件还会被转换为WindowInfo/ControlInfo结构化对象定义见 aip/messages.py。工厂注册MCPRegistry数据服务器通过装饰器注册进注册表MCPRegistry.register_factory_decorator(UICollector) def create_data_mcp_server(*args, **kwargs) - FastMCP: # 获取单例 UI 状态 ui_state UIServerState() data_mcp FastMCP(UFO UI Data MCP Server) # ... 注册 8 个 data_mcp.tool() 工具MCPRegistryufo/client/mcp/mcp_registry.py支持实例注册与工厂延迟初始化两种模式register_factory注册工厂函数get()时若实例不存在则通过工厂创建实现了懒加载。配置文件中type: local的服务器正是从该注册表获取实例并在 Agent 进程内运行的。3.4 快速上手示例直接使用aip.messages.Command构造数据收集命令aip是 UFO² 的 Agent Interaction Protocol 实现参见 AIP Messagesfrom aip.messages import Command # 截取活动窗口截图 screenshot_cmd Command( tool_nametake_screenshot, tool_typedata_collection, parameters{ region: active_window, save_path: screenshots/current.png } ) # 获取所有窗口列表 windows_cmd Command( tool_nameget_window_list, tool_typedata_collection, parameters{} )更贴近当前仓库的实际调用方式是通过computer.run_actions([...])提交MCPToolCall例如调用 UICollector 的capture_desktop_screenshotresult await computer.run_actions([ MCPToolCall( tool_keydata_collection::capture_desktop_screenshot, tool_namecapture_desktop_screenshot, parameters{all_screens: True} ) ]) # 返回 base64 字符串iVBORw0KGgoAAAANSUhEUgAA...四、配置详解让观测层接入 Agent数据收集服务器统一在config/ufo/mcp.yaml中配置采用分层 YAML 结构AgentName → SubType → tool_typedata_collection / action→ Server List。完整字段说明可参考 MCP Configuration Guide。4.1 三种典型配置基础配置HostAgent 默认HostAgent: default: data_collection: - namespace: UICollector type: local start_args: [] reset: false多服务器配置同一观测类型挂载多个服务器HostAgent: default: data_collection: - namespace: UICollector type: local reset: false按应用定制配置AppAgent 子类型覆盖AppAgent: WINWORD.EXE: data_collection: - namespace: UICollector type: local reset: false # 在文档间切换时不重置 EXCEL.EXE: data_collection: - namespace: UICollector type: local reset: true # 在表格间切换时重置4.2 配置字段速查字段类型必填说明namespacestring✅服务器唯一标识如UICollectortypestring✅部署类型local/http/stdioresetboolean❌是否在任务/上下文切换时重置服务器状态默认falsestart_argsarray❌传给服务器工厂函数的初始化参数对于type: http的远程服务器还需配置host主机名或 IP、port端口、pathMCP 端点路径如/mcptype: stdio则需配置command、env、cwd等子进程字段。数据收集服务器在仓库默认配置中均使用type: local进程内运行无 IPC 开销而远程场景如 HardwareCollector、MobileDataCollector可切换为 HTTP 部署——远程部署细节见 Remote Servers。4.3 仓库默认配置全貌仓库根目录下的 config/ufo/mcp.yaml 展示了全部 Agent 的实际数据收集配置HostAgent: default: data_collection: - namespace: UICollector type: local start_args: [] reset: false # 切换到新计算机时是否重置 MCP 服务器 AppAgent: default: data_collection: - namespace: UICollector type: local start_args: [] reset: false # WINWORD.EXE / EXCEL.EXE / POWERPNT.EXE / explorer.exe 各自挂载 UICollector HardwareAgent: default: data_collection: - namespace: HardwareCollector type: http host: localhost port: 8006 path: /mcp reset: false MobileAgent: default: data_collection: - namespace: MobileDataCollector type: http host: localhost port: 8020 path: /mcp auth: ${UFO_MCP_API_KEY} # 密钥通过环境变量注入 reset: false可见Windows 桌面侧的 UI 观测统一复用UICollectorlocal而跨平台硬件观测HardwareCollector、Android 设备观测MobileDataCollector则采用 HTTP 远程模式并且支持用${UFO_MCP_API_KEY}这类环境变量管理认证凭据避免把密钥硬编码进配置文件。五、最佳实践行动前先观察Call Before Action永远在执行动作之前采集数据做出有依据的决策。源码中processing_context.py将DATA_COLLECTION列为 Agent 处理管线的独立阶段ufo/agents/processors/context/processing_context.py与LLM_INTERACTION、ACTION_EXECUTION等阶段并列从流程层面强制了先观察后决策。缓存结果Cache Results当状态未变化时可缓存采集结果以提升性能。get_desktop_app_info的refresh_app_windowsFalse参数正是为此设计——源码中该分支会直接复用ui_state.last_app_windows跳过重新枚举ui_mcp_server.py。优雅处理失败Handle Failures Gracefully窗口关闭或控件消失会导致采集失败务必实现错误处理。典型模式是先检查返回内容中是否含errorwindow_info await computer.run_actions([ MCPToolCall(tool_keydata_collection::get_app_window_info, ...) ]) if error in window_info[0].content[0].text: # 未选中窗口先执行 select_application_window...最小化截图调用Minimize Screenshot Calls截图是昂贵操作——拍一张图分析多次而非反复拍摄。每次截图都伴随 base64 编码与图像数据传输调用次数应控制到最低。使用合适的区域Use Appropriate Regions选择包含所需信息的最小区域如 active window 而非 full screen缩小截图与扫描范围。按需取字段Selective Field Retrievalfield_list只请求当前真正需要的字段。请求过多字段如一次性要 8 个字段会拖慢控件信息处理违背性能原则。六、常见用例UI 元素检测UI Element Detection通过get_desktop_app_infoget_app_window_controls_info发现窗口与控件为自动化定位目标。屏幕监控Screen Monitoring周期性capture_desktop_screenshot/capture_window_screenshot驱动事件型自动化如界面变更检测。系统健康检查System Health Check在执行重型任务前通过观测工具检查系统资源状态。七、错误处理数据收集工具常见错误及应对策略错误原因解决方案WindowNotFoundError目标窗口已关闭先检查窗口是否存在ControlNotFoundError控件不可访问换用其他识别方式UIA ↔ Win32ScreenshotFailedError显卡驱动问题换用不同区域重试TimeoutError操作耗时过长增大超时或简化查询在框架层面所有 MCP 工具在Computer的线程池中执行ThreadPoolExecutor(max_workers10)并受 6000 秒工具超时保护ufo/client/computer.py超时的工具会被取消并返回超时错误从而避免阻塞主事件循环与 WebSocket 连接。八、性能考量截图优化善用region/all_screens参数只捕获所需区域并行数据采集相互独立的采集可并行执行Computer的线程池支持并发工具执行缓存状态未变化时复用缓存refresh_app_windowsFalse、last_app_windows。九、与 Agent 的集成Observe → Reason → Act → Verify 循环数据收集服务器通常用于 Agent 执行的观察阶段。仓库中 AppAgent 的处理策略ufo/agents/processors/strategies/app_agent_processing_strategy.py会在构建 LLM 观察提示词时自动构造tool_typedata_collection的Command依次调用capture_window_screenshot、get_app_window_info、get_ui_tree等工具这正是文档所强调的框架自动调用、LLM 不选择的落地形态。Agent 的标准执行循环如下# Agent 执行循环Observe → Reason → Act → Verify while not task_complete: # 1. Observe: 收集当前状态 screenshot await data_collection_server.take_screenshot() # 2. Reason: Agent 基于观察结果决定下一步动作 next_action agent.plan(screenshot) # 3. Act: 执行动作Action ServerLLM 可选 result await action_server.execute(next_action) # 4. Verify: 再次观察验证动作效果 new_screenshot await data_collection_server.take_screenshot()完整的观察 → 行动 → 验证模式可参考 Action Servers 中的 Integration with Data Collection 章节以及 Computer工具执行层、HostAgent 概览 与 AppAgent 概览。十、相关文档与关键要点UICollector Full Documentation —— 全部工具参数与示例Action Servers —— 可改变状态、由 LLM 选择的执行工具Configuration Guide —— MCP 分层配置完整参考Local Servers —— 内置本地 MCP 服务器清单Remote Servers —— HTTP/Stdio 远程部署MCP Overview —— MCP 高层架构Computer —— MCP 工具执行层核心源码ufo/client/mcp/local_servers/ui_mcp_server.py、ufo/client/mcp/mcp_registry.py、ufo/client/computer.py默认配置config/ufo/mcp.yaml核心要点回顾数据收集服务器是只读、可安全重试的观测层始终先观察后行动为决策提供依据状态未变化时缓存结果以提升性能用重试与回退逻辑优雅处理错误用合适的区域与并行采集换取性能完整细节请见 UICollector 文档。【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
