agent-desktop

Agent Desktop - Printing Press CLI

agent-desktop 是面向 AI Agent 的原生桌面自动化 CLI。它不是 Agent，也不会调用大模型。它会将操作系统的辅助功能树公开为结构化 JSON，为快照分配作用域限定的引用（例如 @e1），并允许调用方 Agent 对这些引用执行语义化操作。

此 Printing Press 软件包会安装 agent-desktop-pp-cli，这是一个目录桥接工具。该桥接工具不会重新实现自动化功能，而是安装或委托给真正的远程 agent-desktop 软件包（地址为 https://github.com/lahfir/agent-desktop）和 npm 软件包 agent-desktop。

前置条件：安装 CLI

此技能通过 agent-desktop-pp-cli 二进制文件执行操作。**调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install agent-desktop --cli-only
   

2. 验证：agent-desktop-pp-cli --version
3. 确保报告的安装目录已添加到将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用 Go 直接安装（要求 Go 1.26.6 或更高版本）。此方法会将程序安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录添加到 $PATH 中：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-desktop/cmd/agent-desktop-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。在验证成功之前，请勿运行此技能中的命令。

安装真正的 agent-desktop CLI

安装桥接工具后，安装并验证真正的远程桌面自动化 CLI：

agent-desktop-pp-cli install --version latest
agent-desktop-pp-cli doctor

桥接工具默认使用 agent-desktop@latest，因此后续上游版本会从远程软件包渠道获取，而不是复制到 Printing Press 中。如果任务需要固定版本，请使用 agent-desktop-pp-cli install --version <version>。如果只需检查安装命令、无需修改主机，请先使用 agent-desktop-pp-cli install --dry-run。

加载与版本匹配的文档

真正的二进制文件会在可执行文件中附带自身的 Agent 技能。进行较复杂的桌面操作之前，请优先查看这些文档，因为它们与已安装的 agent-desktop 版本完全匹配：

agent-desktop skills
agent-desktop skills get desktop --full
agent-desktop skills get desktop workflows
agent-desktop skills get desktop commands-observation
agent-desktop skills get desktop commands-interaction
agent-desktop skills get desktop commands-system
agent-desktop skills get desktop macos
agent-desktop skills get ffi --full

doctor 确认真正的二进制文件已安装后，对于需要使用自身标志的命令，请直接调用 agent-desktop。

核心循环

所有有效的自动化操作都遵循相同的循环：

agent-desktop permissions
agent-desktop snapshot --app "App Name" -i
agent-desktop click @e5 --snapshot <snapshot_id>
agent-desktop wait --text "Done" --app "App Name" --timeout 5000
agent-desktop snapshot --app "App Name" -i

Agent 使用规则：

• 操作前先创建快照。不要猜测 UI 状态。
• 保留返回的 snapshot_id，并在每个使用引用的命令中传入它。
• 将引用视为临时对象。UI 状态发生变化后，请重新创建快照。
• 优先使用引用而非坐标。请先使用 click @e5、type @e2、check @e4 或 scroll @e1，再考虑使用 mouse-click --xy。
• 使用 wait --predicate actionable、wait --text、wait --window 或 wait --notification，不要盲目休眠。
• 遇到 STALE_REF 或 AMBIGUOUS_TARGET 时，创建新快照并选择新的引用。不要重试同一个过时引用。
• 如果并发 Agent 可能共享最新快照状态，请使用 --session <id>。
• 排查过时引用、歧义、策略拒绝或可操作性故障时，请使用 --trace /tmp/agent-desktop.jsonl。
• 只有在明确需要物理输入时才使用 --headed。默认情况下，基于引用的操作采用无头模式，并优先使用辅助功能。

JSON 契约

所有真正的 agent-desktop 命令都会在 stdout 上输出 JSON 封装。

成功：

{
  "version": "2.0",
  "ok": true,
  "command": "snapshot",
  "data": {
    "snapshot_id": "s8f3k2p9",
    "ref_count": 14
  }
}

错误：

{
  "version": "2.0",
  "ok": false,
  "command": "click",
  "error": {
    "code": "STALE_REF",
    "message": "Element could not be resolved from the requested snapshot",
    "suggestion": "Run snapshot to refresh, then retry with an updated ref"
  }
}

退出代码分别为：成功时 0，结构化运行时错误时 1，参数或解析错误时 2。桥接工具的 run 命令会保留真正二进制文件的退出代码。

命令界面

实际 CLI 暴露了 54 个命令：

类别	命令
观察	snapshot、screenshot、find、get、is、list-surfaces
交互	click、double-click、triple-click、right-click、type、set-value、clear、focus、select、toggle、check、uncheck、expand、collapse
滚动	scroll、scroll-to
键盘	press、key-down、key-up
鼠标	hover、drag、mouse-move、mouse-click、mouse-down、mouse-up
应用/窗口	launch、close-app、list-windows、list-apps、focus-window、resize-window、move-window、minimize、maximize、restore
通知	list-notifications、dismiss-notification、dismiss-all-notifications、notification-action
剪贴板	clipboard-get、clipboard-set、clipboard-clear
等待	wait
系统	status、permissions、version、skills
批处理	batch

常见示例：

agent-desktop snapshot --app Finder -i --compact
agent-desktop snapshot --skeleton --app Slack -i --compact
agent-desktop snapshot --root @e3 --snapshot <snapshot_id> -i --compact
agent-desktop find --app TextEdit --role button --name Save
agent-desktop get @e3 --snapshot <snapshot_id> --property value
agent-desktop is @e7 --snapshot <snapshot_id> --property checked
agent-desktop click @e5 --snapshot <snapshot_id>
agent-desktop type @e2 --snapshot <snapshot_id> "[email protected]"
agent-desktop check @e6 --snapshot <snapshot_id>
agent-desktop scroll @e1 --snapshot <snapshot_id> --direction down --amount 3
agent-desktop press cmd+s --app TextEdit
agent-desktop list-windows --app Finder
agent-desktop focus-window --app Finder
agent-desktop clipboard-get
agent-desktop wait --element @e5 --snapshot <snapshot_id> --predicate actionable --timeout 5000
agent-desktop batch '[{"command":"status","args":{}}]' --stop-on-error

Printing Press 桥接命令

仅将这些命令用于目录查询、安装、诊断和委派：

agent-desktop-pp-cli info
agent-desktop-pp-cli install --version latest
agent-desktop-pp-cli install --version latest --dry-run
agent-desktop-pp-cli install --manager bun
agent-desktop-pp-cli doctor
agent-desktop-pp-cli doctor --json
agent-desktop-pp-cli run version
agent-desktop-pp-cli run status

在 doctor 确认实际二进制文件位于 PATH 后，Agent 可以直接调用 agent-desktop。如果调用方需要稳定的 Printing Press 入口点，请继续使用 agent-desktop-pp-cli run。

平台说明

macOS 是第一阶段已完整实现的适配器。用于启动的应用（例如 Terminal、iTerm、Codex 或其他 Agent 运行时）需要具备 UI 自动化的辅助功能权限。 截屏需要屏幕录制权限。某些自动化界面可能还需要自动化权限。

使用以下命令检查并申请权限：

agent-desktop permissions
agent-desktop permissions --request

如果权限被拒绝，请停止操作并显示返回的 error.suggestion。 不要通过坐标点击绕过 TCC 故障。