企业官网建设流程全解析

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能

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）：

所有内置建议文本集中定义在 adapter_error.rs，恢复提示结构见 recovery_hint.rs。

二、12种高频错误代码完整清单

此外还有 4 个辅助代码：PLATFORM_NOT_SUPPORTED（该平台未实现，换平台适配器）、INVALID_ARGS（参数错误，检查命令语法）、NOTIFICATION_NOT_FOUND（通知索引失效，重跑list-notifications）、INTERNAL（读message/suggestion，重试一次，持续失败说明环境问题）。

三、4个最容易卡住的错误：重点诊断 🎯

STALE_REF / SNAPSHOT_NOT_FOUND：refs 过期，重新拍快照

这是新手最常遇到的错误。原因很简单：ref 是快照作用域内的身份标识，UI 在你拍照和点击之间发生了变化，旧 ref 就"过期"了。

恢复方法只有两步：

1. 重新执行snapshot（推荐snapshot --skeleton，先拿骨架概览，token 消耗可降 98.8%）；
2. 用新快照返回的 ref 重试原操作。

骨架概览如何把一次完整读取从 30,743 tokens 压缩到 383 tokens：

AMBIGUOUS_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决定 schema：

• wait_timeout：等待条件超时，携带last_observed或last_error，先看最后观测到什么再调整；
• chain_deadline：链式预算耗尽。若mutated: true，重试前必须重新读取元素；mutated: false表示状态未变，可直接安全重试。

四、哪些错误可以安全重试？✅

agent-desktop 内置了可重试性判定（retryability 判定逻辑）：只有以下 4 类错误在明确标记retryable: true时才算"可重试的解析失败"：

• STALE_REF—— 重拍快照后重试
• AMBIGUOUS_TARGET—— 重拍快照后换更具体 ref
• TIMEOUT—— 查看最后报告后调整
• APP_UNRESPONSIVE—— 等待恢复后检查再决定

其余错误要么不可重试（重试会产生副作用），要么应修正参数。记住一条黄金法则：送达状态不确定时，永远先看状态再动手。

五、FFI（C 库）侧读错误：errno 风格 last-error

如果你通过 C-ABI cdylib 调用（Python/Swift/Go/Node 等宿主），错误以负数字典码返回，完整对照表见 error.rs（STALE_REF = -6、AMBIGUOUS_TARGET = -15、PERM_DENIED = -1，数值 ABI 稳定、只追加不重排），头文件在 agent_desktop.h。

失败后用线程局部的 last-error 访问器读取诊断：

注意：指针在下一次失败调用前一直有效（类 POSIXerrno语义），且details可能包含屏幕上的敏感内容，不要直接写入共享日志。完整契约见 error-handling.md。

从架构图可以看到：agent 发出命令 → agent-desktop 走原生 API 操作应用 → 返回 JSON + refs，所有失败都会在这条链路上转化为上述结构化错误：

六、一张图看懂诊断决策流程 🧭

遇到报错，按下面顺序 30 秒内定位：

1. PERM_DENIED？→ 系统设置里授予无障碍/屏幕录制权限
2. APP_NOT_FOUND？→ 先launch启动应用
3. WINDOW_NOT_FOUND？→ 用list-windows核对窗口
4. STALE_REF/SNAPSHOT_NOT_FOUND？→ 重跑snapshot --skeleton，换新 ref
5. AMBIGUOUS_TARGET？→ 重拍快照，选更具体的 ref
6. ACTION_FAILED/APP_UNRESPONSIVE？→ 查disposition.retry和post_state，确认实际状态后再动
7. POLICY_DENIED？→ 确需物理交互时用--headed显式 mouse/focus 命令
8. INVALID_ARGS？→ 检查命令拼写与参数
9. TIMEOUT？→ 按details.kind分情况处理
10. INTERNAL？→ 读message/suggestion，重试一次；持续失败即环境问题

错误码本身只是"体检报告"，真正让 agent 快速恢复的是code → suggestion → disposition这套组合：机器能读懂代码、官方给出建议、送达状态决定能不能重试。掌握这份清单后，绝大多数自动化故障都能在两次命令内恢复。更多错误场景示例可参考 SKILL.md 与 docs/faq.md。

• GUI 自动化
• AI 应用
• 桌面应用
• AI 技能