agent-desktop错误代码诊断清单：STALE_REF、AMBIGUOUS_TARGET等12种错误如何快速恢复

GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载agent-desktop是一款用 Rust 构建的桌面 computer use 自动化工具它通过操作系统的无障碍树accessibility tree让任意 agent 看懂并操作真实桌面应用而不是靠截图和像素猜测。当自动化流程中动作失败时agent-desktop 会返回结构化的错误代码如STALE_REF、AMBIGUOUS_TARGET。本文是一份面向新手的错误代码诊断清单逐条解释每种错误的含义并给出最快的恢复方法。一、读懂错误信封3个字段快速定位问题 agent-desktop 的所有命令都返回统一的 JSON 信封。成功时ok: true失败时错误对象形如{ ok: false, command: click, error: { code: STALE_REF, message: ..., suggestion: ... } }排错时只需按顺序看三个字段错误码定义见 error_code.rs字段作用使用方式code机器可读的错误代码对照本文清单确定故障类别suggestion官方恢复建议直接按提示执行下一步details结构化上下文如候补元素、最后观测状态判断到底发生了什么disposition.retry本次操作是否已送达safe才能重试否则盲目重试会重复点击/重复提交所有内置建议文本集中定义在 adapter_error.rs恢复提示结构见 recovery_hint.rs。二、12种高频错误代码完整清单错误代码含义最快恢复方法PERM_DENIED无障碍/屏幕录制权限未授予系统设置 → 隐私与安全性 → 辅助功能中放行启动 agent 的应用ELEMENT_NOT_FOUND元素无法解析到实时 UI重跑snapshot用新的 ref 重试APP_NOT_FOUND目标应用未运行先用launch启动应用ACTION_FAILED动作被拒绝或结果与预期矛盾查disposition.retry与details.post_state不要重复执行ACTION_NOT_SUPPORTED该元素不支持此操作换用其他命令或语义动作STALE_REFref 已过期无法重新定位元素重跑snapshot建议--skeleton获取新 refAMBIGUOUS_TARGET旧 ref 身份匹配到多个候选元素重拍快照选择更具体的 refSNAPSHOT_NOT_FOUND快照 ID 缺失或已过期重新snapshot使用返回的新 IDPOLICY_DENIED交互策略拦截了物理/有头操作如确需物理交互用显式 mouse/focus 命令CLI 加--headedAPP_UNRESPONSIVE应用无响应存活探测也失败等待应用恢复用新快照检查状态后再决定WINDOW_NOT_FOUND没有匹配的窗口核对应用名用list-windows确认真实窗口TIMEOUT等待或可操作性条件在时限内未满足查看details.kind与最后报告再决定加大预算此外还有 4 个辅助代码PLATFORM_NOT_SUPPORTED该平台未实现换平台适配器、INVALID_ARGS参数错误检查命令语法、NOTIFICATION_NOT_FOUND通知索引失效重跑list-notifications、INTERNAL读message/suggestion重试一次持续失败说明环境问题。三、4个最容易卡住的错误重点诊断 STALE_REF / SNAPSHOT_NOT_FOUNDrefs 过期重新拍快照这是新手最常遇到的错误。原因很简单ref 是快照作用域内的身份标识UI 在你拍照和点击之间发生了变化旧 ref 就过期了。恢复方法只有两步重新执行snapshot推荐snapshot --skeleton先拿骨架概览token 消耗可降 98.8%用新快照返回的 ref 重试原操作。骨架概览如何把一次完整读取从 30,743 tokens 压缩到 383 tokensAMBIGUOUS_TARGET多个候选绝不猜一个与随便选一个最像的不同agent-desktop 的严格重新识别策略在发现多个合理候选时会拒绝猜测并返回此错误。恢复方式重拍快照改用更具体的 ref例如先find缩小到某个区域或加--window-id限定实例。ACTION_FAILED先查 disposition.retry防止重复执行ACTION_FAILED不代表动作没做——它可能已经送达但结果验证失败。只有disposition.retry为safe即not_delivered时才允许重试其他情况下应先读details.post_state判断实际状态再基于观察到的状态行动。macOS 平台的具体排障步骤见 macos.md。TIMEOUT两种 kind处理方式不同TIMEOUT的details.kind决定 schemawait_timeout等待条件超时携带last_observed或last_error先看最后观测到什么再调整chain_deadline链式预算耗尽。若mutated: true重试前必须重新读取元素mutated: false表示状态未变可直接安全重试。四、哪些错误可以安全重试✅agent-desktop 内置了可重试性判定retryability 判定逻辑只有以下 4 类错误在明确标记retryable: true时才算可重试的解析失败STALE_REF—— 重拍快照后重试AMBIGUOUS_TARGET—— 重拍快照后换更具体 refTIMEOUT—— 查看最后报告后调整APP_UNRESPONSIVE—— 等待恢复后检查再决定其余错误要么不可重试重试会产生副作用要么应修正参数。记住一条黄金法则送达状态不确定时永远先看状态再动手。五、FFIC 库侧读错误errno 风格 last-error如果你通过 C-ABI cdylib 调用Python/Swift/Go/Node 等宿主错误以负数字典码返回完整对照表见 error.rsSTALE_REF -6、AMBIGUOUS_TARGET -15、PERM_DENIED -1数值 ABI 稳定、只追加不重排头文件在 agent_desktop.h。失败后用线程局部的 last-error 访问器读取诊断访问器返回内容ad_last_error_message()人类可读描述ad_last_error_suggestion()恢复建议ad_last_error_platform_detail()平台细节AX 码、HRESULT、AT-SPIad_last_error_details()结构化 JSONACTION_FAILED的可操作性报告、AMBIGUOUS_TARGET的候选摘要等注意指针在下一次失败调用前一直有效类 POSIXerrno语义且details可能包含屏幕上的敏感内容不要直接写入共享日志。完整契约见 error-handling.md。从架构图可以看到agent 发出命令 → agent-desktop 走原生 API 操作应用 → 返回 JSON refs所有失败都会在这条链路上转化为上述结构化错误六、一张图看懂诊断决策流程 遇到报错按下面顺序 30 秒内定位PERM_DENIED→ 系统设置里授予无障碍/屏幕录制权限APP_NOT_FOUND→ 先launch启动应用WINDOW_NOT_FOUND→ 用list-windows核对窗口STALE_REF/SNAPSHOT_NOT_FOUND→ 重跑snapshot --skeleton换新 refAMBIGUOUS_TARGET→ 重拍快照选更具体的 refACTION_FAILED/APP_UNRESPONSIVE→ 查disposition.retry和post_state确认实际状态后再动POLICY_DENIED→ 确需物理交互时用--headed显式 mouse/focus 命令INVALID_ARGS→ 检查命令拼写与参数TIMEOUT→ 按details.kind分情况处理INTERNAL→ 读message/suggestion重试一次持续失败即环境问题错误码本身只是体检报告真正让 agent 快速恢复的是code → suggestion → disposition这套组合机器能读懂代码、官方给出建议、送达状态决定能不能重试。掌握这份清单后绝大多数自动化故障都能在两次命令内恢复。更多错误场景示例可参考 SKILL.md 与 docs/faq.md。赞分享GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载相关推荐InstColorization对比分析为什么实例感知着色比传统方法更优秀InstColorization对比分析为什么实例感知着色比传统方法更优秀 在计算机视觉领域图像着色是一个充满挑战的任务。InstColorization计算机视觉图像处理Flutter微信SDK wechat_kit一站式集成微信登录、分享与支付Flutter微信SDK wechat_kit一站式集成微信登录、分享与支付 wechat_kit是一款专为Flutter开发者打造的微信SDK提供便捷的微Code Llama错误恢复终极指南如何快速修复生成代码中的语法错误Code Llama错误恢复终极指南如何快速修复生成代码中的语法错误 Code Llama作为强大的代码生成模型在帮助开发者提高编程效率的同时偶尔也会生成人工智能大模型基础模型代码模型本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考