用 Vercel agent-desktop 让编码 Agent 直接操作桌面应用（无障碍树，不靠截图）

agent-desktop 是 Rust 写的单二进制，官方推荐用 npm 全局安装（也可等官方 Homebrew / Scoop 包）。装完先验证版本，确认拿到 1.0.x：

# 全局安装
npm install -g agent-desktop

# 验证安装（应显示 1.0.2 或更新）
agent-desktop --version

# 查看帮助，确认命令可用
agent-desktop --help

无障碍能力是系统级权限，必须显式授权，否则快照拿不到元素：

# macOS：系统设置 → 隐私与安全性 → 辅助功能
#   把运行 agent-desktop 的终端 / 你的 IDE 加进允许列表
# Windows：UI Automation 默认开启，无需额外设置
# Linux：需安装并启用 AT-SPI（多数桌面环境默认开）
#   如遇权限问题，可跑权限引导，逐个勾选要授权的应用
agent-desktop

用 snapshot 给某个应用拍快照。-i 让输出更易读，快照里每个可操作元素都带 ref_id（形如 @s8f3k2p9:e8）和 available_actions（这个元素能做什么）：

# 给「访达 / Finder」拍快照（-i 人类可读）
agent-desktop snapshot --app "Finder" -i

# 对复杂应用，先用 --skeleton 看骨架，token 更省
agent-desktop snapshot --app "Slack" --skeleton

# 钻进某个区域再细看（用上一步拿到的 ref）
agent-desktop snapshot --app "Slack" --root @s8f3k2p9:e8

返回的 JSON 里，一个节点大概长这样："role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"]。记下这个 ref_id，下一步就靠它操作。

拿到 ref 后，用 click / type / scroll 等操作它，操作完再拍一张快照验证结果。这就是 agent-desktop 的核心循环：

# 点击某个元素
agent-desktop click @s8f3k2p9:e8

# 在输入框里打字
agent-desktop type @s8f3k2p9:e9 "[email protected]"

# 滚动某个区域
agent-desktop scroll @s8f3k2p9:e10 --amount 200

# 操作完立刻复查，确认变成了预期状态
agent-desktop snapshot --app "Finder" -i

agent-desktop 的命令统一返回 JSON envelope（含 ok / data / error 与重试建议）。常见失败信号：

agent-desktop 是 CLI，最稳的接法是把它包成一个「操作桌面」工具，让编码 Agent 在「观察—操作—再观察」循环里调用。下面是一段最小 Node 封装（调用子进程跑 CLI，把 JSON envelope 原样返回给 Agent）：

// desktop-tool.mjs
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const run = promisify(execFile);

export async function desktop(action, args) {
  // action: snapshot | click | type | scroll
  const { stdout } = await run('agent-desktop', [action, ...args], { maxBuffer: 1e8 });
  return stdout; // JSON envelope: { ok, data, error, retry }
}

// Agent 调用示例（伪代码）：
// 1) desktop('snapshot', ['--app','Finder','-i'])
// 2) desktop('click', ['@s8f3k2p9:e8'])
// 3) desktop('snapshot', ['--app','Finder','-i'])  // 验证结果

把这个工具注册成你 Agent 的 computer-use 能力（Claude Code 的 MCP tool、Codex 的 function、或 Cursor 的 command 都行），Agent 就能自己决定「先看看、再点哪、点完确认」。想让操作真的动鼠标，加 --headed；想压低 token，给稠密应用加 --skeleton 或 --compact。更完整的 60 个命令参考见官方文档站 agent-browser.dev/desktop。