手机智能体失败调试与恢复：Android AI 助手根因分析与最小重试手册

任务失败后的前五分钟

手机智能体失败调试与恢复的第一步，是先停下来。不要马上把整段任务重新说一遍，因为已经完成的外部效果可能会重复发生：短信可能已经发出，日历可能已经创建，设置可能已经改过，网页表单可能已经提交。先确认当前任务是只读查询、可逆设置，还是会影响他人或外部系统的动作。

AgentDebugX 论文把智能体调试组织成 Detect、Attribute、Recover、Rerun 四步，并提醒可见错误可能晚于真正根因。手机场景更需要这条原则：屏幕上显示“工具失败”，根因可能是联系人识别错、权限被撤销、应用不在前台、网络断开，或用户上一步没有确认。

前五分钟按这个顺序做：停止继续执行；记录原始目标；听取或查看最后一条可见结果；确认是否已经产生外部效果；保存当前屏幕和权限状态；只在明确安全时重试。涉及发送、拨号、付款、删除、修改设置和跨应用提交时，先把任务停在确认点。想理解为什么用户确认能提升手机智能体可信度，可以读AI 智能体审批体验：手机任务为什么需要可解释确认。

保存一份最小失败证据包

有用的证据包不需要暴露所有隐私。它应该让你或支持人员能重建“目标、轨迹、设备状态、失败结果”，同时删除密码、验证码、完整联系人、消息正文、地址、账号令牌和私密截图。截图很有帮助，但截图本身通常不够，因为它只能证明某一刻的界面状态。

建议保存六类信息：原始请求和期望结果；智能体已经执行到哪一步；最后一次工具调用或界面动作的结果；当前屏幕或应用状态；关键权限、网络、电量和锁屏状态；用户是否已经批准发送、拨号、提交或删除等动作。AgentDebugX 强调轨迹级理解对归因有价值，手机任务也一样：根因常常藏在早一步的参数、权限或界面状态里。

如果团队需要更完整的身份、权限和审计信息，可以参考AI 智能体身份、权限与审计日志：逐工具审批控制怎么落到手机 Agent，再按最小必要原则提交材料。

按层判断失败类型

手机智能体为什么失败，通常要按层判断，而不是只看一句错误提示。输入层失败表现为目标含糊、联系人重名、时间地点不完整。模型层失败表现为理解错意图、把只读查询变成操作、遗漏约束。能力路由失败表现为选错工具、没有找到合适技能，或该能力当前不适合自动执行。

上下文层失败很常见：当前屏幕不是用户以为的页面，应用被切到后台，弹窗挡住按钮，键盘占据焦点，通知改变了界面。权限层失败来自 Android 运行时权限。Android 运行时权限指南说明，权限应在使用时检查，用户可以拒绝、撤销或长期拒绝权限；应用还应在权限不可用时提供可理解的降级路径。

工具层失败包括参数不完整、前置条件不满足、外部应用返回异常、系统设置被厂商改动。界面层失败包括按钮标签变化、编号位置变化、滚动未到位。外部服务层失败包括网络断开、账号过期、短信服务不可用、地图或邮件服务限流。确认层失败则发生在用户没有批准、批准了错误对象，或在高影响动作前取消。

能力路由本身也有架构细节，想深入看 AutoAttach、Suggest、Fallback 如何影响工具选择，可以读AI 智能体能力路由指南：AutoAttach、Suggest、Fallback 如何选择 Android 工具。

找到最早的因果步骤

Attribute 的目标不是给最后一个报错贴标签，而是找到最早导致失败的因果步骤。做法是从表面错误往前倒推：最后失败的是工具、界面还是确认？它依赖哪个参数、权限、应用状态或外部服务？这些前置条件最早在哪一步变错？

先用只读检查验证前置条件。例如不要马上重发短信，而是先检查草稿是否存在、联系人是否正确、发送按钮是否已触发；不要重新创建日历，而是先查询是否已经有同名日程；不要重新调整系统设置，而是先读取当前状态。这样能减少重复外部效果。

根因描述要带置信度和备选项。好描述是：“联系人权限在工具调用时不可用，导致联系人匹配失败；备选可能是联系人名重名。”差描述是：“模型坏了。”AgentDebugX 的研究说明严格根因归因仍然困难，所以手机排障要保留备选解释，并用下一步只读检查缩小范围。

如果你要把一次失败变成系统评估用例，可以转到安卓手机 Agent 基准测试指南：2026 年怎样评估可靠性、安全和恢复，把当前失败整理成可重复测试。

恢复前置条件并最小重试

Recover 不是马上重跑整个任务，而是恢复失败步骤所需的最小前置条件。权限失败，先重新授予或选择降级路径；应用状态失败，先把目标应用带回正确页面；网络失败，先恢复连接；联系人或时间参数错，先改参数；确认取消，先让用户重新审查目标和后果。

Rerun 要选择最小安全后缀。只读查询可以重新执行；可逆设置可以先读当前状态再修改；会产生外部效果的动作要先确认是否已经完成。短信、邮件、付款、删除、拨号、发帖、创建日程和修改共享文件，都不适合盲目全量重跑。

1. 确认已经完成的外部效果。
2. 修复最早因果步骤的前置条件。
3. 只重跑失败工具或后续最小步骤。
4. 检查下游状态是否符合预期。
5. 在结果确认后停止任务，记录恢复方式。

Android 权限还可能被长期拒绝或自动重置，应用需要优雅降级。Android 权限最佳实践建议测试已授予和已撤销权限组合。对手机智能体来说，这意味着任务设计要能处理“权限暂时没有”“用户拒绝”“需要打开设置页”这三种状态。

多会话任务还要防止互相影响。若你同时运行多个手机任务，可阅读多会话 AI 智能体任务队列：Android 手机上如何隔离运行、等待和恢复，再决定是否暂停其他任务。

用 FoneClaw 当前控制完成排障和恢复

我们在 FoneClaw 里把手机智能体失败调试与恢复做成可观察流程。任务状态、工具结果、操作确认、停止、重试和权限恢复都服务于一个目标：让用户知道失败发生在哪一步，哪些效果已经完成，下一次应该重试哪里。

当前屏幕上下文是用户主动触发的。用户选择附加当前屏幕后，FoneClaw 可以把界面状态纳入判断，例如按钮是否出现、目标应用是否在前台、弹窗是否阻挡、表单是否已经填写。需要详细了解悬浮入口和当前屏幕机制，可以读Android 悬浮 AI 助手与当前屏幕：从提问到可控操作的完整指南。

FoneClaw 的 100+ 个内置工具覆盖了读状态、可逆设置、通信、日历、位置、网页、工作流和扩展等能力族。不同工具的诊断价值不同：读状态工具适合验证前置条件，设置工具适合恢复设备状态，通信和外部服务工具需要更多确认。我们把工具结果、权限要求和确认规则作为排障证据，让用户能区分“模型计划问题”“权限问题”“工具前置条件问题”和“外部应用状态问题”。

恢复时，先回到同一任务上下文，听取或查看最后结果；再按需要附加当前屏幕；然后修复权限、网络、应用前台或目标参数；最后只重试失败步骤。完成后读取最终状态。当前能力族和安装信息以FoneClaw 功能页面为准，我们在产品里持续把恢复控制做得更清楚。

整理有用的支持或问题报告

当同一个最小步骤多次失败、权限恢复后仍失败、结果已经影响外部对象，或你无法判断是否重复执行时，就该升级为支持或问题报告。报告不需要交出全部私人内容，重点是可复现、可定位、可保护隐私。

• 任务目标：用一句话描述，不写完整隐私内容。
• 失败位置：第几步、哪个应用、哪个工具或哪个确认点。
• 设备状态：Android 版本、设备型号、网络、锁屏、前台应用。
• 权限状态：相关权限已允许、被拒绝、长期拒绝或刚被撤销。
• 外部效果：是否已发送、创建、删除、拨号或修改。
• 证据：打码截图、时间点、错误文案、重试次数。

提交前删除密码、令牌、验证码、完整联系人、消息正文、精确地址、支付信息和医疗细节。除非支持人员明确说明且你同意，私密内容不应进入报告正文。

用验收测试防止复发

一次失败处理完后，把它转成小型验收测试。测试不需要复杂：同一个任务，在权限已授予、权限被撤销、网络断开、目标应用不在前台、弹窗出现、用户取消确认等状态下各跑一次。每次记录任务是否能停止、是否能解释失败、是否能只重试最小后缀。

验收标准要具体：读状态工具应返回当前状态；需要权限时应解释缺什么；高影响动作应显示目标和后果；失败后应保留恢复入口；已完成外部效果应被检查后再继续。Android 官方建议测试不同权限组合，这对手机智能体同样适用。

团队使用时，可以把常见失败做成回归清单：联系人重名、通知权限撤销、日历重复、网络断开、位置关闭、短信草稿未发送、插件不可用、当前屏幕不匹配。想把这类测试纳入更长期的智能体治理，可以读自改进手机智能体测试框架：从失败样本到可治理的 Android Agent。