agent desktop 弹出 stale_ref 错误时，重新读取目标窗口，拿新快照里的完整 ref_id 重试就好。要是返回的是 ambiguous_target 错误，先拉取窗口列表，指定 --window-id 参数再操作就行。这两类报错，前者要核对元素引用，后者要核对窗口范围。
如何判断该刷新引用还是重选窗口？
直接看返回JSON里的error.code字段就够了：STALE_REF 代表需要重新定位当前界面的元素，AMBIGUOUS_TARGET 说明目标范围内匹配到了多个候选对象。我们之前测试直接按Finder应用名读快照，就碰到了这类多窗口报错。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
遇到 STALE_REF 时怎样重新定位元素？
切回当前要操作的目标窗口，执行下面的命令重新拉取快照，根据按钮的名称、角色找到新的引用后，再跑之前的操作就行。操作前务必先检查 error.disposition.retry 字段，只有标记为 safe 的时候，才能直接按提示重试。
agent-desktop snapshot --app Finder --window-id "替换为当前窗口ID" -i
如果操作中途页面或者窗口已经切走了，先判断下原来的操作还有没有执行的必要，比如目标视图本来就已经是选中状态，直接读取状态就好，没必要重复操作。
多窗口报错怎么处理？
先运行命令拉取所有窗口列表，核对窗口标题和对应ID，选好你要操作的目标窗口，再用这个ID重新跑快照就行。如果窗口关闭过、或者重新打开过，就得重新拉取一次窗口列表。
agent-desktop list-windows --app Finder
agent-desktop snapshot --app Finder --window-id "替换为当前窗口ID" -i
我们这轮测试完整走通了Finder多窗口报错、指定窗口ID后恢复的全流程，其中STALE_REF的处理逻辑完全遵循官方项目文档。如果重新拉取快照之后还是报错，先留存错误码和不含隐私信息的操作上下文，再排查是权限、窗口还是元素引用的问题。
| 错误码 | 先做什么 | 怎样验证 |
|---|---|---|
STALE_REF |
重新读取目标窗口的快照，按元素名称和角色找新引用。 | 核对新引用对应的是原来要操作的元素。 |
AMBIGUOUS_TARGET |
列出窗口并按标题选当前 ID。 | 加 --window-id 后重跑快照，检查 ok。 |
排查时保留失败命令返回的 JSON。即使命令退出码非零，也可以单独查看保存的文件。下面的第一条用于复现多窗口情形，只读取界面。
agent-desktop snapshot --app Finder -i > finder-error.json
jq '.error | {code, suggestion, retry: .disposition.retry}' finder-error.json如果错误为多窗口歧义，按上文选出窗口后重新读取，再核对顶层 ok。
