mcpField
A
agent-desktop-macos

agent-desktop-macos

github.com/vercel-labsAgent 工作流6.7k114 次安装今天更新
代码仓库

关于 agent-desktop-macos

这份 macOS 专用技能指南介绍 agent-desktop 的权限设置及桌面控制的平台差异，涵盖语义操作与实体输入、菜单和覆盖层、通知命令及操作验证。

主要功能

  1. 01macOS 权限设置指引
  2. 02实体输入与语义操作规则
  3. 03菜单和覆盖层处理
  4. 04通知中心控制
  5. 05操作结果验证

适用场景

  1. 01为桌面控制配置 macOS 权限
  2. 02选择 macOS 操作方式
  3. 03处理菜单、对话框和通知
  4. 04检查界面操作是否生效

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop-macos

安装后在 Claude Code 中输入/agent-desktop-macos确认已加载。

附带文件references/troubleshooting.md

详细介绍

macOS 上的 agent-desktop

请先阅读核心技能（agent-desktop skills get desktop），了解观察、操作、验证循环。本技能仅介绍 macOS 上的差异。症状和修复方法见 references/troubleshooting.md。

要求

  • macOS 13 或更高版本，支持 Intel 或 Apple Silicon。
  • 启动 agent-desktop 的应用（Terminal、iTerm2、Warp、VS Code、Codex）需要获得辅助功能权限。macOS 27 及更高版本将此列表命名为“设备控制与数据访问”。如果“系统设置”单独列出了 agent-desktop 二进制文件，也请授予它权限。
  • 仅在使用 screenshot 和生成 session start --screenshots 产物时，需要屏幕录制权限。
  • 仅当命令报告缺少自动化权限时，才需要授予“系统事件”的自动化权限。

首次使用

  1. 运行 agent-desktop permissions。
  2. 如果权限遭到拒绝，请运行 agent-desktop permissions --guide。此命令会打开正确的“系统设置”页面，并显示一个面板，告知用户要将哪个应用拖入列表。用户使用 Touch ID 或密码确认后，面板会自动转到下一个缺少的权限。命令会立即返回 "guide": "started"、"already_running" 或 "not_needed"。使用 agent-desktop permissions --request 则会显示系统提示。
  3. 如果指南无法运行，请打开“系统设置”>“隐私与安全性”>“辅助功能”（macOS 27 及更高版本为“设备控制与数据访问”）。添加启动应用并将其启用。
  4. 运行 agent-desktop permissions，确认状态为 granted。下次调用 agent-desktop 时会检测到新的授权，因此无需重启启动应用。
  5. 运行 agent-desktop snapshot -i 进行确认。此命令会读取当前焦点应用。如果 Finder 没有打开的窗口，snapshot --app Finder -i 会返回 WINDOW_NOT_FOUND。

permissions 不会显示提示。permissions --request 可能会显示提示，包括自动化权限提示。permissions --guide 不会显示提示，且仅涵盖辅助功能和屏幕录制权限。如果 macOS 需要显示提示，自动化权限会报告为 unknown。

macOS 上的差异

有界面操作优先使用物理输入，适用于 click、right-click、type、clear 和 scroll。Core 会聚焦到 ref 对应的精确窗口。随后，适配器会向已验证的位置发送真实的点击、按键或滚轮事件。expand、collapse、set-value、select、toggle、check、uncheck、focus 和 scroll-to 在 --headed 模式下仍采用语义操作。双击、三击、hover 和 drag 需要使用 --headed。原始 --xy 输入不会改变焦点。

通过观察判断操作是否生效。 AX 返回码并不能证明操作产生了效果。Finder 的 AXConfirm 即使没有任何作用，也会返回成功。请再次获取快照，或使用 get 和 is 检查结果。

界面。 对 File、Edit 和 View 菜单以及菜单栏应用（状态项），请使用 --surface menubar。菜单、工作表、警报或弹出框打开时，背后窗口树中的 ref 不是正确的目标。

菜单。 无头模式下，right-click 使用 AXShowMenu。如果菜单已打开，但应用返回 APP_UNRESPONSIVE 且 retry: unsafe，请勿重试。使用 --surface menu 检查菜单。对于组合框和菜单按钮，请使用 select @ref "Option"。select 需要菜单从关闭状态切换为打开状态，因此请先关闭所有已打开的菜单。

通知中心。 通知命令通过辅助功能操作通知中心，并遵循核心 commands-system 参考中的规则。agent-desktop 打开通知中心后，会在操作完成后将其关闭，并恢复先前的应用焦点。单次关闭或操作时，请同时传入 --expected-app 和 --expected-title，因为堆栈会发生变化。对于在列出前就消失的横幅，请使用 wait --notification --app "App"。

Chromium 和 Electron。 agent-desktop 会在需要时自动启用 Chromium 渲染器的 Web 辅助功能。对于内容密集且正在运行的应用，请使用 snapshot --skeleton -i --compact，然后通过 --root @ref 深入查看。

身份标识。 launch 接受显示名称（"System Settings"）或 bundle ID（com.apple.systempreferences）。其他命令通过 --app 接受显示名称。窗口 ID（如 w-4521）在窗口的整个生命周期内都有效。使用 list-windows 查找窗口 ID。

按键。 主修饰键是 cmd：press cmd+c、press cmd+s。退出快捷键，如 cmd+q、cmd+shift+q、cmd+alt+esc、ctrl+cmd+q 和 cmd+shift+delete，除非传入 --force，否则会返回 POLICY_DENIED。要退出应用，请使用 close-app。组合键支持标点按键，可使用符号（, . / ; ' [ ] \ - = `）或名称（comma、period、slash、semicolon、quote、leftbracket、rightbracket、backslash、minus、equal、grave）。每个按键都会根据当前键盘布局，通过能输入该字符的按键发送，因此在 ANSI 和 JIS 键盘上，press cmd+, 都会打开设置。

光标叠加层。 cursor-overlay enable 会在可穿透点击的窗口中绘制 Agent 光标。它不会移动系统指针，也不会激活任何应用。macOS 的移动和图像限制请参阅核心 commands-system 参考。

下一步

命令失败时，请在参考资料/故障排除.md中查找相应症状。

评论

支持 Markdown