UFO 项目 MobileAgent 三状态机深度解析CONTINUE / FINISH / FAIL 状态流转与 4 阶段处理流水线【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本篇技术指南聚焦于 UFO 开源仓库中MobileAgentAndroid 移动端任务执行代理的有限状态机FSM设计它以极简的 3 状态CONTINUE、FINISH、FAIL驱动移动端 UI 自动化任务的完整生命周期。读完本文你将掌握 MobileAgent 状态机的枚举定义、状态注册与查找机制、基于 LLM 决策的状态转移规则、CONTINUE 状态下 4 阶段处理流水线的底层实现以及状态机与 MCP Server、ADB 设备交互之间的协作方式可直接用于理解或二次开发移动端智能代理的调度逻辑。状态机架构概览MobileAgent 使用一个3 状态有限状态机FSM来管理 Android 设备上的任务执行流程。极简的状态集合在保证执行进度可追踪的同时维持了行为的简单性与可预测性。状态转移由LLM 的决策与动作执行结果共同驱动LLM 在每一轮交互中返回下一个状态标识Agent 据此推进或终止任务。关联阅读MobileAgent 架构总览架构与核心职责处理策略CONTINUE 状态下的 4 阶段处理流水线MCP 命令可用的移动端交互命令快速开始指南部署你的第一个移动端 Agent状态枚举定义状态机的状态集合定义在MobileAgentStatus枚举中实际实现在 ufo/agents/states/mobile_agent_state.pyclass MobileAgentStatus(Enum): Store the status of the mobile agent. FINISH FINISH CONTINUE CONTINUE FAIL FAIL状态语义CONTINUE任务进行中需要继续执行动作FINISH任务成功完成FAIL任务无法继续发生不可恢复错误状态注册与查找机制MobileAgent 的状态由MobileAgentStateManager管理它实现了Agent 状态注册表模式Agent State Registry Patternclass MobileAgentStateManager(AgentStateManager): _state_mapping: Dict[str, Type[MobileAgentState]] {} property def none_state(self) - AgentState: The none state of the state manager. return NoneMobileAgentState()从源码实现ufo/agents/states/basic.py可以看出该模式的关键设计注册装饰器所有 MobileAgent 状态类通过MobileAgentStateManager.register装饰器注册装饰器内部执行cls._state_mapping[state_class.name()] state_class将状态名映射到状态类单例管理器AgentStateManager继承SingletonABCMeta由SingletonMeta与ABCMeta组合而成保证整个进程中只有唯一的状态管理器实例惰性实例化get_state(status)在首次查询某状态时才创建状态对象并缓存到_state_instance_mapping未注册的未知状态名会回退到none_state保证了状态查找的健壮性。状态转移图整个状态机只有一条“执行主干”任务从[*]启动后进入CONTINUE在CONTINUE内部自循环迭代执行直到 LLM 判定完成→FINISH或发生不可恢复错误→FAIL。两个终止态中FAIL还会自动转移到FINISH以完成清理收尾流程。状态定义详解1. CONTINUE 状态活跃执行态用途MobileAgent 处理用户请求并执行移动端动作的核心活跃状态。MobileAgentStateManager.register class ContinueMobileAgentState(MobileAgentState): The class for the continue mobile agent state async def handle(self, agent: MobileAgent, context: Optional[Context] None): Execute the 4-phase processing pipeline await agent.process(context) def is_round_end(self) - bool: return False # Round continues def is_subtask_end(self) - bool: return False # Subtask continues classmethod def name(cls) - str: return MobileAgentStatus.CONTINUE.value属性值类型活跃Active执行处理器✓ 是4 阶段轮次结束否子任务结束否持续时间单轮下一个状态CONTINUE、FINISH、FAIL在 MobileAgent 类定义 中可以看到MobileAgent.__init__通过self.set_state(self.default_state)将初始状态设置为ContinueMobileAgentState即 Agent 一经创建就进入活跃执行态default_state属性直接返回ContinueMobileAgentState()实例。CONTINUE 状态下的行为流程数据收集阶段截取设备屏幕截图获取已安装应用列表收集当前屏幕 UI 控件生成带控件 ID 标注的注解截图LLM 交互阶段构造包含截图与控件信息的提示词获取 LLM 的下一步动作决策解析并校验响应动作执行阶段执行移动端动作点击、滑动、输入文本、启动应用等捕获执行结果记忆更新阶段用截图和动作结果更新记忆存储控件信息供下一轮使用状态判定分析 LLM 响应以确定下一个状态状态转移逻辑CONTINUE → CONTINUE任务需要更多动作才能完成例如需要跨多个屏幕导航CONTINUE → FINISHLLM 判定任务已完成例如成功填写表单并提交CONTINUE → FAIL遇到不可恢复错误例如必需应用未安装、多次尝试后仍找不到控件2. FINISH 状态成功终止态用途表示任务成功完成的状态。MobileAgentStateManager.register class FinishMobileAgentState(MobileAgentState): The class for the finish mobile agent state def next_agent(self, agent: MobileAgent) - MobileAgent: return agent def next_state(self, agent: MobileAgent) - MobileAgentState: return FinishMobileAgentState() # Remains in FINISH def is_subtask_end(self) - bool: return True # Subtask completed def is_round_end(self) - bool: return True # Round ends classmethod def name(cls) - str: return MobileAgentStatus.FINISH.value属性值类型终止Terminal执行处理器✗ 否轮次结束是子任务结束是持续时间永久下一个状态FINISH无转移行为特征向会话管理器Session Manager发出任务完成信号不再进行任何后续处理Agent 实例可以被终止截图与动作历史保留在记忆中可供查询进入 FINISH 状态的条件所有必需移动端动作已成功执行LLM 判定用户请求已得到满足目标 UI 状态已达成如表单已提交、信息已展示执行过程中未出现错误或异常3. FAIL 状态错误终止态用途表示因不可恢复错误导致任务失败的状态。MobileAgentStateManager.register class FailMobileAgentState(MobileAgentState): The class for the fail mobile agent state def next_agent(self, agent: MobileAgent) - MobileAgent: return agent def next_state(self, agent: MobileAgent) - MobileAgentState: return FinishMobileAgentState() # Transitions to FINISH for cleanup def is_round_end(self) - bool: return True # Round ends def is_subtask_end(self) - bool: return True # Subtask failed classmethod def name(cls) - str: return MobileAgentStatus.FAIL.value属性值类型终止错误执行处理器✗ 否轮次结束是子任务结束是持续时间转移到 FINISH下一个状态FINISH行为特征记录失败原因与上下文捕获最终截图用于调试转移到 FINISH 状态完成清理会话管理器收到失败状态进入 FAIL 状态的典型条件应用不可用必需应用未安装或无法启动控件未找到多次尝试后仍无法定位目标 UI 控件设备断开执行过程中 ADB 连接丢失权限被拒设备未授予所需权限超时动作执行耗时过长LLM 明确失败LLM 明确表示任务无法完成连续动作失败多个连续动作执行失败错误信息记录尽管 FAIL 是终止状态错误信息仍会被记录用于事后调试# Example error logging in FAIL state agent.logger.error(fMobile task failed: {error_message}) agent.logger.debug(fLast action: {last_action}) agent.logger.debug(fCurrent screenshot saved to: {screenshot_path}) agent.logger.debug(fUI controls at failure: {current_controls})状态转移规则转移决策逻辑状态转移由CONTINUE 状态中 LLM 的响应决定。LLM 返回的结构化响应中包含status字段Agent 据此更新自身状态并通过状态管理器解析出下一个状态对象# LLM returns status in response parsed_response { action: { function: click_control, arguments: {control_id: 5, control_name: Search}, status: CONTINUE # or FINISH or FAIL }, thought: Need to click the search button to proceed } # Agent updates its status based on LLM decision agent.status parsed_response[action][status] next_state MobileAgentStateManager().get_state(agent.status)在 mobile_agent_state.py 的MobileAgentState.next_state()基类方法中可以看到通用实现读取agent.status通过MobileAgentStateManager().get_state(status)按名称解析出对应的状态对象。这一设计将“LLM 返回的状态字符串”与“具体状态类实例”解耦新增状态只需注册新类即可。状态转移矩阵当前状态条件下一个状态触发场景CONTINUELLM 返回 CONTINUECONTINUE需要更多动作如跨多个屏幕导航CONTINUELLM 返回 FINISHFINISH任务完成如信息已找到并展示CONTINUELLM 返回 FAILFAIL不可恢复错误如必需控件不可用CONTINUE抛出异常FAIL系统错误如 ADB 断开FINISH任意FINISH无转移FAIL任意FINISH清理转移CONTINUE 状态的处理流水线4 阶段处理管线处于 CONTINUE 状态时MobileAgent 执行完整的 4 阶段流水线源码级流水线实现这 4 个阶段在 ufo/agents/processors/strategies/mobile_agent_strategy.py 中由多个策略类协作完成并通过depends_on/provides装饰器显式声明阶段间的数据依赖MobileScreenshotCaptureStrategy通过命令分发器向 MCP Server 发送capture_screenshot数据收集命令将返回的 base64 截图保存为action_step{session_step}.png文件路径为{log_path}action_step{session_step}.png并记录截图耗时MobileAppsCollectionStrategy调用get_mobile_app_target_info命令默认include_system_appsFalse即默认不包含系统应用获取已安装应用列表将返回的TargetInfo/字典统一转换为{id, name, package}结构供提示词使用获取失败时降级为空列表并记录警告MobileControlsCollectionStrategy调用get_app_window_controls_target_info命令获取当前屏幕控件对每个控件的rectbbox 格式[left, top, right, bottom]进行合法性校验要求right left且bottom top过滤无效控件后通过PhotographerFacade生成带控件标注框的注解截图action_step{session_step}_annotated.pngMobileLLMInteractionStrategy将安装应用、当前控件、干净截图、注解截图、黑板blackboard上下文与历史成功动作一并组装进提示词调用 LLM 并解析为结构化响应MobileActionExecutionStrategy解析parsed_response.action并执行移动端动作将执行结果绑定回动作对象生成ActionCommandInfo列表用于记忆追踪。这一阶段化的策略设计详见 处理策略文档正是 CONTINUE 状态await agent.process(context)调用的底层支撑。终止状态FINISH / FAIL终止状态不执行任何处理逻辑FINISH干净终止结果与截图可从记忆获取FAIL错误终止错误详情与最终截图被记录确定性控制流设计3 状态设计保证了执行过程的确定性与可追踪性行为可预测每条执行路径都有明确定义可调试状态转移伴随截图记录支持可视化调试可测试有限状态空间简化了测试覆盖可维护简洁的状态集合降低复杂度可视化可追踪每个状态的截图构成完整视觉执行历史与其他 Agent 的状态机对比Agent状态数复杂度视觉支持使用场景MobileAgent3极简✓ 截图Android 移动端自动化LinuxAgent3极简✗ 纯文本Linux CLI 任务执行AppAgent6中等✓ 截图Windows 应用自动化HostAgent7高✓ 截图桌面编排MobileAgent 的极简 3 状态设计体现了其聚焦的职责范围通过执行移动端 UI 动作来满足用户请求。与 LinuxAgent 类似它在保持极简状态集合的同时提供了视觉上下文支持简化状态机既避免了不必要的复杂性又保留了健壮的错误处理与完成检测能力对比可参考 overview.md 中的详细对照表。移动端特有设计考量基于截图的状态追踪与 LinuxAgent纯文本或 AppAgentWindows UI API不同MobileAgent 高度依赖截图来理解 UI 状态每个 CONTINUE 轮次都以一张全新的截图开始注解截图标注控件 ID支持精确交互截图存入记忆用于调试与分析视觉上下文帮助 LLM 理解当前 UI 状态控件缓存机制MobileAgent 缓存控件信息以降低 ADB 开销。该机制在 ufo/client/mcp/http_servers/mobile_mcp_server.py 的 MCP Server 中实现# Cache expiration times (seconds) self.apps_cache_duration 300 # 5 minutes for apps list self.controls_cache_duration 5 # 5 seconds for screen controls self.ui_tree_cache_duration 5 # 5 seconds for UI tree self.device_info_cache_duration 60 # 1 minute for device info核心要点控件缓存时长为5 秒超过即视为过期并重新抓取每次动作执行后控件缓存失效UI 很可能已变化控件字典支持按 ID 快速查找显著减少重复的 UI 树解析开销触控式交互MobileAgent 的状态推进由触控动作触发而非键盘命令Tap点击主要交互方式Swipe滑动滚动与手势操作Type输入文本输入需要控件处于聚焦状态Long-press长按呼出上下文菜单规划中实现细节与源码索引状态机核心实现位于ufo/agents/states/mobile_agent_state.py关键类均在 ufo/agents/states/mobile_agent_state.py 中MobileAgentStatus状态枚举CONTINUE、FINISH、FAILMobileAgentStateManager状态注册表与查找MobileAgentState抽象基类定义handle、next_agent、next_state、is_round_end、is_subtask_end等接口ContinueMobileAgentState活跃执行状态承载 4 阶段流水线FinishMobileAgentState成功完成状态FailMobileAgentState错误终止状态NoneMobileAgentState初始/未定义状态其name()返回空字符串next_state直接指向 FINISH状态机在整个 MobileAgent 生态中的协作链路可概括为MobileAgent定义于 ufo/agents/agent/customized_agent.py通过AgentRegistry.register(agent_nameMobileAgent, third_partyTrue, processor_clsMobileAgentProcessor)注册→ContinueMobileAgentState.handle()→agent.process(context)→ 各策略类 → MCP ServerADB 交互。仓库中的集成测试 tests/integration/test_mobile_mcp_server.py 演示了如何配置 MobileAgent 的数据收集与动作 MCP Server 并验证命令分发流程。下一步学习处理策略深入理解 CONTINUE 状态中执行的 4 阶段处理流水线MCP 命令探索移动端 UI 交互与应用管理命令架构总览返回 MobileAgent 架构全景快速开始部署你的第一个移动端 Agent作为 Galaxy 设备使用在多设备协同工作流中配置 MobileAgent【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考