快照回来是一棵空树
九成是权限或总线，不是命令写错了。按顺序确认：
agent-desktop status
agent-desktop permissions
agent-desktop list-apps- macOS：辅助功能权限要授予运行 agent-desktop 的那个应用。截图还需要「屏幕录制」，
打开通知中心还需要 System Events 的自动化权限。权限缺失时命令可能返回
PERM_DENIED， 也可能表现为读不到元素，见 macOS。 - Windows：和终端同级完整性的应用无需授权；以管理员身份运行的应用可以读， 但只有同样提权的智能体才能向它发送输入，见 Windows。
- Linux：需要用户自己的图形会话和一条工作中的 AT-SPI 总线，
at-spi2-core要装上， 见 Linux。
剩下的那一成是这个应用确实没有发布可访问性树。它读声明，不猜像素， 所以不暴露树的界面它就看不见。
INVALID_ARGS
你写的 ref 缺了快照 id。完整形式是 @<snapshot_id>:<序号>，例如 @s8f3k2p9:e8。
只写 @e8 会被拒绝，规则见快照与 ref。
PowerShell 用户还会碰到另一种 INVALID_ARGS：不加引号的 @token 被当成散裂运算符，
命令在到达 agent-desktop 之前就被改形了。写成 '@s8f3k2p9:e8'。
STALE_REF
界面已经变了。正确处置是重新快照并使用新快照里的 ref，而不是重试同一个动作。
AMBIGUOUS_TARGET
先读 error.details.kind，它区分两种完全不同的情况。
ref 身份不唯一：saved_ref_ambiguous 表示捕获之后出现了完全相同的元素；
identity_not_unique 表示捕获时就没有证明 ref 唯一，或者窗口没能在快照超时内读完。
重新快照不会解决双胞胎，换一个在窗口内唯一的控件；只是超时的话，用更大的
--timeout-ms 重拍。确实需要点其中一个双胞胎时，只能用
agent-desktop --headed mouse-click --xy X,Y，Linux Wayland 会话不支持。
多窗口目标歧义：用 --app 选目标时应用开了多个窗口，error.details 会列出候选窗口 id，
用 --window-id 指定其中一个：
agent-desktop snapshot --app Finder --window-id w-204749 -i规则和 details.kind 的完整列表见快照与 ref。
什么时候可以重试
只看一个字段：error.disposition.retry。
快照太大，把上下文挤爆了
先用 --skeleton -i --compact 读整体结构，再用 --root <ref> -i --compact 深入其中一块。
见骨架与下钻。
界面上那个按钮明明存在，却读不到
可能的原因：
- 那个元素不是可交互的，被
-i过滤掉了。去掉-i再读一次。 - 树还没读完：
complete为false。先wait，再重新快照。 - 它属于另一个窗口。用
list-windows找到正确的--window-id。 - 它由外壳绘制而不是应用。用
open-system-surface和list-surfaces， 见界面。
我想确认某个动作真的生效了
不要依赖返回值。用一次读取收尾：
agent-desktop wait --element @s8f3k2p9:e6 --predicate value --value 7
agent-desktop get @s8f3k2p9:e6 # 只读一个属性
agent-desktop is @s8f3k2p9:e6 # 只判断一个状态key-down 之类的命令拒绝运行
这是设计如此。key-down、key-up、mouse-down、mouse-up 在有守护进程能够可靠释放
被按住的按键或鼠标键之前一律拒绝运行，因为一个卡住的按键会污染之后所有操作。
按住再拖动用 drag，组合键用 press。见键盘、鼠标与物理输入。
从源码构建失败
先确认工具链：Rust 1.89 或更高；macOS 需要 Xcode 命令行工具，Windows 需要 MSVC 构建工具， Linux 需要一个 C 链接器。每个平台的适配器只能在它自己的操作系统上构建：
cargo build --release -p agent-desktop在 Linux 上还要构建平台辅助程序，并把 agent-desktop-linux-clipboard-owner 放在 CLI 旁边：
cargo build --release -p agent-desktop-linux --bins所有关卡列在仓库的 CONTRIBUTING.md。跨平台调用见构建与链接。
还有别的问题
仓库里的 docs/faq.md 收录了更多问答，docs/solutions/ 记录了过去遇到的缺陷和经验。
报告安全漏洞请走 SECURITY.md，不要开公开 issue。