agent desktop 是 vercel labs 推出的开源桌面自动化工具，靠系统无障碍树读取应用窗口、按钮等各类元素，返回能直接用来操作的json引用，非常适合给编码助手使用，查看、操控本地电脑上的应用。这个工具本身只提供桌面操作的基础能力，具体的任务判断、操作先后顺序，得由调用它的助手来实现。
Agent Desktop 怎样读取桌面应用？
Agent Desktop 读取的是系统开放给辅助技术的界面结构。拿Finder举例，应用会主动提供按钮的名称、角色、当前状态这类信息，生成快照的时候，所有可操作元素都会被分配专属引用，比如工具栏里的「图标视图」按钮，识别出来的角色就是单选按钮。
调用方可以通过CLI或者C接口访问平台适配层：macOS下实际读取界面的是系统自带的辅助功能接口，Windows和Linux则分别调用对应系统的原生接口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
读快照的时候，可以先填应用名缩小检索范围，如果这个应用开了好几个窗口，再加窗口ID进一步限定范围。权限配置完之后，先在终端里试读Finder的交互元素就行，如果弹出多窗口提示，先把所有窗口列出来，选你刚打开的练习目录对应的窗口就好。
agent-desktop list-windows --app Finder
快照引用和操作结果有什么关系？
引用只在它所属的快照和对应目标上下文里生效。常规操作流程一般是先拉取快照，按元素的名称和角色找到目标按钮，执行操作之后，再拉取一次新快照确认状态。命令返回 ok: true 只能说明这条命令本身跑成功了，最终的实际操作结果，必须从新快照里核对确认。
举个例子，要把当前的列表视图改成图标视图，先找到「图标视图」按钮点击，之后去新快照里检查这个按钮的选中状态，就能把「点击动作本身执行成功」和「窗口成功切换到目标视图」两个环节分开验证，不会混淆。
操作顺序 读取当前窗口 → 找到元素引用 → 执行动作 → 重新读取并验证
想在本地电脑上看一次结构化输出，先在已经完成授权的终端打开Finder，用窗口列表里查到的当前窗口ID替换命令里的占位内容就行。需要用到jq的话，先确认你已经安装了这个工具。
agent-desktop list-windows --app Finder
agent-desktop snapshot --app Finder --window-id "替换为当前窗口ID" -i > finder-snapshot.json
jq '.. | objects | select(.role? == "radiobutton" and .name? == "图标视图") | {name, role, ref_id, value}' finder-snapshot.json
哪些桌面任务适合先尝试？
刚上手的时候，优先选操作有明确名称、结果直观可见的任务练手，比如切换练习目录的视图就非常合适。如果你的任务需要判断颜色、识别图片内容，或者涉及没有暴露语义的自绘控件，要先检查快照里能不能找到对应的目标节点，要是找不到对应节点，先手动打开应用界面核对，别对着无效引用反复操作浪费时间。
