UFO AppAgent 命令系统深度解析基于 MCP 的动态命令发现、配置与执行全指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本篇技术指南以 UFO 项目中 AppAgent 的 MCP 命令系统为核心系统讲解应用级命令的架构设计、config/ufo/mcp.yaml配置细节、运行时命令发现机制以及从策略层到 MCP 服务器的完整执行调用链。读完本文你将掌握如何为不同应用程序Word、Excel、PowerPoint、资源管理器等装配数据采集与动作执行服务器理解 UI 自动化与原生 APICOM混合执行背后的原理并能基于仓库源码定位命令路由、工具注册与结果回传的每个关键环节。命令执行架构总览AppAgent 的应用级命令通过MCPModel Context Protocol模型上下文协议体系执行。命令并非硬编码在 Agent 代码中而是由 MCP 服务器动态提供经CommandDispatcher接口分发执行。整体架构如下动态命令机制AppAgent 的命令不是硬编码的而是在运行时从已配置的 MCP 服务器中动态发现。可用命令取决于三个因素MCP 服务器配置位于 config/ufo/mcp.yaml应用上下文例如当前操作的是 Word、Excel 还是 PowerPoint会决定加载哪些 COM 执行器已安装的 MCP 服务器形态支持local进程内 FastMCP、http远程 Streamable HTTP、stdio子进程标准输入输出三种部署类型下图展示了该混合架构在 UFO 项目中的实际形态共享 GUI MCP Server 提供跨应用的通用交互App-Level API MCP Servers 按应用隔离封装原生接口每个 AppAgent 通过 MCP 协议驱动对应应用MCP 服务器配置详解配置文件与结构AppAgent 的命令在config/ufo/mcp.yaml中配置。该文件的顶层结构以 Agent 名为键如HostAgent、AppAgent、ConstellationAgent、HardwareAgent、LinuxAgent、MobileAgent每个 Agent 下按子类型default或应用根名如WINWORD.EXE划分再按data_collection数据采集与action动作执行两个分组列出服务器列表。每个服务器条目包含以下字段字段说明适用类型namespace服务器命名空间是工具在tool_key中的标识前缀全部type服务器类型local进程内、http远程 HTTP、stdio标准输入输出全部start_args启动参数列表仅 stdio 使用如python脚本路径stdiohost/port/pathHTTP 服务器地址三要素最终拼成http://{host}:{port}{path}httpauthHTTP 认证信息支持${ENV_VAR}环境变量占位httpreset切换目标如切换文档/应用时是否重置服务器状态防止状态泄漏全部AppAgent 的默认配置与分应用配置# Default configuration for all applications AppAgent: default: data_collection: - namespace: UICollector type: local start_args: [] reset: false action: - namespace: AppUIExecutor type: local start_args: [] reset: false - namespace: CommandLineExecutor type: local start_args: [] reset: false # Application-specific configurations WINWORD.EXE: action: - namespace: AppUIExecutor type: local - namespace: WordCOMExecutor type: local reset: true # Reset on document switch EXCEL.EXE: action: - namespace: AppUIExecutor type: local - namespace: ExcelCOMExecutor type: local reset: true POWERPNT.EXE: action: - namespace: AppUIExecutor type: local - namespace: PowerPointCOMExecutor type: local reset: true explorer.exe: action: - namespace: AppUIExecutor type: local - namespace: PDFReaderExecutor type: local reset: true上述配置与仓库中 config/ufo/mcp.yaml 的实际内容一致。需要说明几点与默认配置的差异仓库中的分应用配置为每个应用显式保留了data_collection下的UICollector条目默认配置的简化写法同样生效reset缺省为falsereset: true的语义是当 Agent 切换到新的文档/应用时MCPServerManager.create_or_get_server会先对已存在的同名服务器调用reset()再复用该实例从而避免上一个文档的 COM 状态泄漏到当前文档见 ufo/client/mcp/mcp_server_manager.py。从源码实现看type字段与服务器类的映射关系定义在MCPServerManager._server_type_mapping中ufo/client/mcp/mcp_server_manager.py_server_type_mapping: Dict[str, Callable[[Dict[str, Any]], BaseMCPServer]] { http: HTTPMCPServer, local: LocalMCPServer, stdio: StdioMCPServer, }local进程内 FastMCP 实例从MCPRegistry注册表中按命名空间取回ufo/client/mcp/mcp_registry.pyhttp拼装 URL有auth时构造带认证的StreamableHttpTransport未解析的环境变量会被拒绝启动ufo/client/mcp/mcp_server_manager.pystdio以command start_args启动子进程传输。AppAgent 使用的 MCP 服务器清单服务器命名空间类型用途命令类别UICollectorUICollectorLocal数据采集截图捕获、控件检测、UI 树AppUIExecutorAppUIExecutorLocalUI 自动化鼠标点击、键盘输入、文本录入CommandLineExecutorCommandLineExecutorLocalShell 执行PowerShell、Bash 命令WordCOMExecutorWordCOMExecutorLocalWord 自动化文档创建、文本操作、格式编排ExcelCOMExecutorExcelCOMExecutorLocalExcel 自动化工作簿创建、数据录入、图表PowerPointCOMExecutorPowerPointCOMExecutorLocalPowerPoint 自动化演示文稿创建、幻灯片、形状PDFReaderExecutorPDFReaderExecutorLocalPDF 操作文本提取、页面导航当 AppAgent 操作特定应用Word、Excel、PowerPoint时除 UI 自动化命令外会自动加载额外的COM 执行器服务器以提供原生 API 访问这些服务器设置了reset: true防止文档间状态泄漏。从实现角度本地 MCP 服务器的模块位于 ufo/client/mcp/local_servers/其中ui_mcp_server.py、word_wincom_mcp_server.py、excel_wincom_mcp_server.py、ppt_wincom_mcp_server.py、pdf_reader_mcp_server.py均标注为Windows 专用在非 Windows 平台上ufo/client/mcp/local_servers/init.py 中的load_all_servers()会通过WINDOWS_ONLY_SERVERS集合将其跳过因此上述 AppAgent 的 UI/COM 命令能力仅在 Windows 环境下可用。CommandLineExecutor对应cli_mcp_server.py则是跨平台的Windows、Linux、macOS。命令发现机制列出可用命令AppAgent 在运行时通过list_tools元工具从各 MCP 服务器动态发现命令# Get all available tools from MCP servers result await command_dispatcher.execute_commands([ Command(tool_namelist_tools, parameters{}) ]) tools result[0].result # Returns list of all available commands with their schemaslist_tools在源码中实现在 ufo/client/computer.py它遍历计算机的_tools_registry支持按tool_typeaction/data_collection和namespace过滤并默认剔除元工具最终以 JSON 形式返回每个工具的完整信息tool_key、tool_name、namespace、input_schema、output_schema等。工具的注册与去重工具发现的核心依赖Computer.register_one_mcp_serverufo/client/computer.py对每个已启动的 MCP 服务器调用client.list_tools()为每个工具生成唯一的tool_key形如data_collection::tool_name或action::tool_name并将其连同MCPToolCall元信息含指向所属BaseMCPServer的引用写入_tools_registry。同一tool_key重复注册会被跳过并告警从而保证多服务器场景下命名空间的隔离。工具与命令的数据结构定义在 aip/messages.pyMCPToolCallaip/messages.py工具在注册表中的完整描述包含tool_key、tool_name、namespace、tool_type、input_schema/output_schema、parameters以及其所属的mcp_server实例Commandaip/messages.py一次具体的执行请求字段为tool_name、parameters、tool_typedata_collection或action、call_id。命令类别一览命令按用途分类类别服务器示例数据采集UICollectorcapture_window_screenshot、get_app_window_controls_target_info、get_ui_tree鼠标动作AppUIExecutorclick_input、click_on_coordinates、drag_on_coordinates、wheel_mouse_input键盘动作AppUIExecutorset_edit_text、keyboard_input数据检索AppUIExecutortexts、get_text文档 APIWordCOMExecutorcreate_document、insert_text、save_document表格 APIExcelCOMExecutorcreate_workbook、insert_data、create_chart演示 APIPowerPointCOMExecutorcreate_presentation、add_slide、insert_shapeShell 执行CommandLineExecutorexecute_command上述命令在仓库中均有对应实现与文档佐证例如capture_window_screenshot、get_app_window_controls_info、get_ui_tree等数据采集工具见 documents/docs/mcp/servers/ui_collector.md均返回 base64 编码的截图或结构化控件信息且多数工具要求先用select_application_window选定窗口click_input、set_edit_text等的底层实现在 ufo/automator/ui_control/controller.pyclick_input依据 API 名选择click或click_input执行原子操作、ufo/automator/ui_control/controller.pyset_edit_text会依据配置在set_text/set_edit_text/type_keys间切换并在录入后校验文本是否生效run_shell即表中的execute_command见 documents/docs/mcp/servers/command_line_executor.md实现上使用shlex.split()解析参数并以subprocess.Popen(..., shellFalse)启动杜绝 shell 注入命令链与内建命令不生效。命令执行流程完整调用链从源码结构看该链路的关键实现分三层BasicCommandDispatcherufo/module/dispatcher.py定义了execute_commands(commands, timeout6000)抽象接口并提供generate_error_results任何异常都会被封装为Result(statusFAILURE, error...)提示请重试或执行其他命令LocalCommandDispatcherufo/module/dispatcher.py是 AppAgent 本地执行的主要实现为每个命令生成uuid4形式的call_id通过ComputerManager/CommandRouter将命令连同当前 Agent 名、应用根名APPLICATION_ROOT_NAME、进程名APPLICATION_PROCESS_NAME路由到Computer并受asyncio.wait_for(..., timeout)超时保护WebSocketCommandDispatcherufo/module/dispatcher.py用于分布式场景将命令封装为ServerMessage(typeCOMMAND, statusCONTINUE)通过 AIP 的TaskExecutionProtocol.send_command下发以response_id关联asyncio.Future等待客户端回传ClientMessage.action_results。在Computer层ufo/client/computer.py工具调用会在独立的线程池执行器中运行ThreadPoolExecutor(max_workers10)每个调用在独立事件循环内通过fastmcp.Client完成call_tool并叠加_tool_timeout超时保护data_collection与action两类服务器在async_init时并行注册ufo/client/computer.py。示例执行一条 UI 命令from aip.messages import Command # Create command command Command( tool_nameclick_input, parameters{ id: 12, name: Export, button: left, double: False }, tool_typeaction, ) # Execute command results await command_dispatcher.execute_commands([command]) # Check result if results[0].status SUCCESS: print(fCommand executed: {results[0].result})results[0].status对应ResultStatus枚举aip/messages.py取值包括success、failure、skipped、noneResult结构体aip/messages.py还携带error、result、namespace、call_id等字段其中call_id与Command.call_id一一对应便于多命令批量执行时追踪每条命令的返回。关键动作命令的参数规格以click_input为例完整参数见 documents/docs/mcp/servers/app_ui_executor.md参数类型必填默认值说明idstr是-来自get_app_window_controls_info的控件 IDnamestr是-与 ID 匹配的控件名称buttonstr否left鼠标键left/right/middle/xdoublebool否False是否双击同类常用命令还包括click_on_coordinates窗口内相对坐标0.0-1.0点击、drag_on_coordinates两点间拖拽支持duration与key_hold、set_edit_texttext必填clear_current_text可选、keyboard_input支持{VK_CONTROL}c、{TAB 2}等按键序列、wheel_mouse_inputwheel_dist正数上滚、负数下滚、wait最多 300 秒等。Agent 系统配置设置除 MCP 服务器装配外AppAgent 的观测与窗口行为还受系统配置控制。文档给出的配置示例如下相关配置项属于系统配置体系完整选项见 documents/docs/configuration/system/overview.md 与 documents/docs/configuration/system/system_config.md# config/ufo/app_agent_config.yaml system: # Control detection backend control_backend: - uia # Windows UI Automation - omniparser # Vision-based detection # Screenshot settings save_full_screen: true # Also capture desktop save_ui_tree: true # Save UI tree JSON include_last_screenshot: true # Include previous step concat_screenshot: true # Concatenate clean annotated # Window behavior maximize_window: false # Maximize on selection show_visual_outline_on_screen: true # Draw red outline需要指出当前仓库的实际系统配置位于 config/ufo/system.yaml其中可直接验证的控件检测配置为CONTROL_BACKEND: [uia]注释说明可选uia与omniparser以及IOU_THRESHOLD_FOR_MERGE: 0.1合并控件框的 IoU 阈值。control_backend的选择直接决定底层控件检测通道uia走 Windows UI Automationui_mcp_server.py中BACKEND win32 if win32 in CONTROL_BACKEND else uia见 ufo/client/mcp/local_servers/ui_mcp_server.pyomniparser则为基于视觉的目标检测方案。上述截图与窗口行为相关配置项以文档描述为准实际生效路径以你本地安装的配置文件为准。配置资源与进阶阅读MCP 配置与服务器文档快速参考MCP 配置参考、MCP 概览配置指南MCP 配置指南、本地服务器、远程服务器、创建自定义 MCP 服务器服务器类型文档动作服务器、数据采集服务器各服务器详细文档服务器文档命令细节UICollectorUICollector 服务器截图、控件检测、UI 树命令AppUIExecutorAppUIExecutor 服务器带参数的 UI 自动化命令WordCOMExecutorWord COM 执行器Microsoft Word API 命令ExcelCOMExecutorExcel COM 执行器Microsoft Excel API 命令PowerPointCOMExecutorPowerPoint COM 执行器Microsoft PowerPoint API 命令PDFReaderExecutorPDF 读取执行器PDF 读取命令CommandLineExecutor命令行执行器Shell 命令执行注意具体命令的参数、名称与行为会随 MCP 服务器的演进而变化。请始终以各服务器专属文档作为最新的命令参考。架构与设计相关文档AppAgent 概览AppAgent 高层架构状态机命令何时被触发的状态机说明处理策略四阶段处理流水线中命令的实际应用HostAgent 命令桌面级命令混合动作MCP 命令系统架构控件检测UIA 与 OmniParser 后端命令分发器命令路由总结MCP 驱动所有命令均由 config/ufo/mcp.yaml 中配置的 MCP 服务器提供服务器类型支持local、http、stdio三种形态动态发现命令在运行时通过list_tools从各服务器注册表动态发现并以tool_key{tool_type}::{tool_name}全局去重应用定制Word、Excel、PowerPoint、资源管理器分别自动加载对应 COM 执行器reset: true防止文档间状态泄漏混合执行UI 自动化AppUIExecutor/UICollector与原生 APICOM 执行器命令可在同一任务内按需组合兼顾通用性与高保真控制可配置从服务器装配到控件检测后端CONTROL_BACKEND、截图与窗口行为均有丰富的配置选项文档完备每个服务器均有独立的命令参考文档可直接查阅。下一步建议审阅 MCP 配置MCP 配置参考浏览各服务器文档点击上文服务器表格中的链接获取命令细节理解命令在流程中的位置处理策略 展示了命令的实际应用学习命令触发时机状态机 说明了命令在何时被调度执行。【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考