GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载peekaboo menubar是 Peekaboo CLI 中专门用于操作 macOS 状态栏图标status items即 menu bar extras例如 Wi-Fi、蓝牙、电池以及各类第三方托盘图标的轻量级子命令。它通过MenuServiceBridge直接与菜单栏服务通信帮助 AI Agent 以先只读枚举、后显式授权点击的安全方式完成状态栏交互是自动化流程中点击系统托盘图标的标准化入口。读完本文你将掌握menubar list/menubar click的完整参数用法、--foreground强制同意机制、按应用--app/--pid作用域定位 AX 状态项的原理以及--verify多重弹窗验证策略。命令定位状态栏专用与传统应用菜单互补Peekaboo 的菜单类命令有明确分工peekaboo menu处理传统的应用菜单如 File、Edit而peekaboo menubar严格面向菜单栏右侧的状态栏图标。在 MenuBarCommand.swift 的命令描述中可以看到menubar的子命令注册为list与click两个真正的 Commander 子命令且命令名不含连字符不是menu-bar。两者的核心差异体现在交互代价上menubar list是只读操作始终在后台完成不打断用户当前工作menubar click会打开全局状态栏 UI弹出 popover/菜单因此强制要求显式的--foreground同意其语义在源码中定义为 Allow opening global menu bar UI (required for click)见 MenuBarCommand.swift。子命令与关键选项总览menubar包含两个子命令均支持全局的--json结构化输出与--verbose详细模式子命令说明list打印每个可见状态栏图标及其索引--json额外输出 bundle ID 与 AX 标识符click按名称或索引点击状态栏图标结合--app/--pid可点击特定应用拥有的 AX 状态项click子命令的完整选项与 MenuBarCommand.swift 的 Commander 绑定一一对应参数类型说明[itemName]位置参数目标状态栏项目名称传递给click--index n数字按列表索引定位与menubar list展示的排序一致0 起--app name-or-bundle-id字符串仅限带名称的click在指定应用中检查 AX 状态项与--pid、--index互斥--pid pid数字仅限带名称的click在指定正 PID 进程中检查 AX 状态项与--app、--index互斥--foreground标志click必需允许 Peekaboo 打开全局状态栏 UI 并打断当前前台工作流--verify标志点击后确认同一 PID 拥有的 popover 出现或焦点已转移到所属应用/窗口含 OCR 兜底--includeRawDebug仅list标志在 JSON 输出中包含原始调试字段窗口 owner/layer全局标志—--json输出结构化负载--verbose在列出时增加描述信息list只读枚举状态栏清单peekaboo menubar list通过MenuServiceBridge.listMenuBarItems获取清单见 PeekabooBridgeClientMenusDockDialogs.swift底层走 Bridge 通道不触发任何前台交互。人类可读输出默认输出格式由 MenuBarItemListOutput.swift 定义$ peekaboo menubar list Menu Bar Items (5): [0] untitled Frame: 0,0 24×22 [1] Wi-Fi Description: Wi-Fi status Frame: 300,0 20×20 ...每行展示[索引] 名称并在可用时附带 Description 与屏幕坐标 Frame。当列表非空时命令还会打印一行提示引导你使用peekaboo menubar click --index index --foreground或peekaboo menubar click name --foreground此行为同样有测试覆盖见 MenuBarCommandConsentTests.swift。若未检测到任何状态项则输出No menu bar items detected.。JSON 输出字段--json输出包含items与menu_bar_items同一数组的别名兼容不同消费方以及count。每个MenuBarItemInfo条目定义于 MenuServiceProtocol.swift包含字段含义title面向用户展示的名称rawTitle系统报告的原始名称可能形如Item-0index菜单栏中的序号isVisible当前是否可见description可选描述bundleIdentifier所属应用的 bundle ID如com.apple.controlcenterownerName所属应用名或 owner 字符串如Control Centeridentifier/axIdentifierAX 稳定标识符axDescriptionAX 帮助文本frame屏幕坐标包围盒rawWindowID/rawWindowLayer/rawOwnerPID原始窗口 ID、窗口层菜单项常见 24/25、拥有进程 PIDrawSource数据来源如cgs、cgwindow、ax-control-centerselectionEvidence精确的状态项身份与有序清单摘要供后续点击操作校验--verbose模式会追加 owner 名称与隐藏状态等诊断信息--includeRawDebug则会补全rawWindowID/rawWindowLayer等原始调试字段。click名称、索引与应用作用域三种定位方式menubar click的目标解析分为**无作用域全局清单与应用作用域--app/--pid**两条路径两者都要求先满足--foreground。强制的前置同意--foreground在 MenuBarCommand.swift 中clickMenuBarItem的第一道关卡就是检查--foreground缺失时直接抛出MenuBarClickPreflight.foregroundConsentRequired其错误信息为 Menu bar clicks require --foreground because status items open global UI.。这保证在任何状态项查找之前就完成拒绝避免产生无谓的查询与副作用。对应的测试foreground consent precedes explicit named preparation与named click without foreground refuses before lookup or dispatch验证了缺少--foreground时prepareCalls、listCallCount、namedClickCalls、indexClickCalls全部为零即不触发任何查找或分发见 MenuBarCommandConsentTests.swift。无作用域按索引或按名称无--app/--pid时命令先通过listMenuBarItems拿到当前显示的 WindowServer 清单再由MenuBarItemSelector见 DeterministicDesktopLeafSelector.swift完成匹配按索引--index n直接对应list展示的序号。索引越界/过期会以MENU_ITEM_NOT_FOUND拒绝提示重新执行menubar list获取当前索引。按名称大小写不敏感的模糊匹配匹配字段覆盖title、rawTitle、identifier、axDescription、ownerName。关键的设计保证是名称目标在分发阶段始终保持名称绑定即使两次调用之间状态栏发生重排点击也不会被错误重定向到另一个索引——resolveClickTarget中索引选择器只负责定位候选真正下发时仍走 named 请求MenuBarItemActionRequest(named:...)相关测试foreground named click preserves name-based dispatch断言namedClickCalls [Wi-Fi]而indexClickCalls为空见 MenuBarCommandConsentTests.swift。此外无作用域的名称/索引保留显示的 WindowServer 清单 精确窗口路径一个唯一显示的名称不会触发全局 AX 扫描因此无关的图形辅助进程无法阻塞该路径只有含糊匹配或过期的显示证据会在分发前被拒绝。应用作用域--app 与 --pidclick name --app ...或--pid ...走 scoped 准备路径命令先通过MenuBarClickPreflight.prepare调用MenuServiceBridge.prepareMenuBarItem在指定应用代generation内部、带有 deadline 地准备一份AXExtrasMenuBar清单。参数校验规则在 MenuBarCommand.swift 中明确--app与--pid二选一同时给出报VALIDATION_ERROR--index不能与--app/--pid组合PID 必须是正数空字符串、PID:0前缀等非法应用标识会被拒绝名称与索引不能同时给出。准备阶段会记录原始 owner 选择器、进程代与选中项证据分发阶段对证据做复验并在最终读取之间核对原生叶节点身份不借用 Control Center 代理的窗口 ID且准备过程从不聚焦应用。若应用名/bundle ID 指向的应用在当前代中缺失、不可读、已变化或匹配含糊一律在分发前拒绝不确定的 AX 提交绝不通过其他路由重试。作用域内匹配的细节语义在显式 owner 内项目文本只匹配原生叶节点的 title、help、description 或 identifier应用名与 bundle ID 是 owner 选择器不是额外的项目名别名。作用域点击与无作用域点击一样强制--foreground且不能使用--index也绝不回退到其他应用或全局清单。若运行时未协商scopedMenuBarActions较旧的 Bridge host 会直接拒绝而非忽略 owner 作用域见 PeekabooBridgeClientMenusDockDialogs.swift。同时兼容性说明既有的编程式clickMenuExtraAPI 仍保留仅依赖 Accessibility 的系统菜单路径不需要 CG 窗口或 Event Synthesizing 权限原始命名的 SDK 调用保留 AX 优先查找与既有的安全分发前兜底。这两条兼容路由都不会取代CLI 与当前受证明的远程命名调用所使用的证据绑定请求。错误输出契约名称缺失、索引过期、作用域不匹配等失败统一在分发前以MENU_ITEM_NOT_FOUND拒绝JSON 负载包含effect: refused、retry_safe: true、mutation_dispatched: false源码定义于 MenuBarCommand.swift。测试missing named item is one typed pre-dispatch refusal断言了完整的错误消息Menu bar item not found: Missing及上述字段见 MenuBarCommandConsentTests.swift。verify点击后的多重弹窗验证链--verify的核心实现在 MenuBarClickVerifier.swift验证按以下优先级逐步进行任一步成功即返回verified: true及对应methodpopover 解析无 OCR轮询MenuBarPopoverResolver在给定超时默认 1.5s内寻找与点击项同 PID 的弹出窗口。解析依据依次为 owner PID置信度 1.0、owner 名称0.9、排名/首选 X 坐标0.4原因标记如owner_pid、owner_name、preferred_x、window_rank见 MenuBarPopoverResolver.swift。焦点窗口变化确认点击后前台应用是否变为 owner或聚焦窗口的 ID/标题是否发生变化focused_window置信度 0.7。owner 窗口出现检查 layer 0 上是否出现 owner 的可见窗口owner_pid_window置信度 0.6通过ObservationMenuBarWindowCatalog按 PID 或按名称/标题匹配。OCR 兜底默认开启对排名靠前的候选窗口执行 OCR要求 popover 文本包含目标标题/owner 名并将验证锚定到点击项的 X 坐标区域 OCR 兜底ocr_area也在允许时启用。OCR 需要屏幕录制Screen Recording权限。AX 菜单检查默认关闭仅当环境变量PEEKABOO_MENUBAR_AX_VERIFY1时才通过isMenuExtraMenuOpen检查 AX 菜单是否展开ax_menu。两个验证开关的环境变量语义环境变量默认作用PEEKABOO_MENUBAR_OCR_VERIFY0OCR 开启显式关闭 OCR 验证仍要求 popover 文本包含目标标题/ownerPEEKABOO_MENUBAR_AX_VERIFY1AX 关闭显式开启 AX 菜单检查可选依赖 Accessibility验证成功后JSON 输出的verified为trueeffect 升级为confirmed验证失败会抛出operationErrorMenu bar verification failed: popover not detected。此外点击结果会记录屏幕坐标数据若可得便于你关联交互发生的屏幕位置。完整可运行的实战示例# 1. 只读列出所有状态栏图标及其索引后台进行无需 --foreground peekaboo menubar list # 2. 按名称点击 Wi-Fi 图标必须显式 --foreground peekaboo menubar click Wi-Fi --foreground # 3. 点击并验证 popover 已打开OCR 验证默认开启 peekaboo menubar click Wi-Fi --verify --foreground # 4. 直接按索引点击第三个图标并输出结构化 JSON peekaboo menubar click --index 3 --foreground --json # 5. 显式定位第三方应用 AX 拥有的状态项按 bundle ID peekaboo menubar click Status Item --app com.example.StatusApp --foreground --json # 6. 把命名项绑定到从应用列表取得的 PID peekaboo menubar click Status Item --pid 12345 --foreground --json # 7. 带原始调试字段的 JSON 清单list 专属 peekaboo menubar list --json --includeRawDebugclick --foreground --json的成功负载示例ClickJSONOutput见 MenuBarCommand.swift包含success、clicked元素描述、executionTime、verified与selectedLeafEvidence数组非 JSON 模式下验证成功会额外打印✅ Clicked menu bar item: ...与 Verified menu bar click (method)--verbose下还会显示耗时。故障排查先确认权限使用peekaboo permissions status验证 Screen Recording 与 Accessibility 权限均已授予OCR 验证依赖屏幕录制AX 依赖辅助功能。确认进程与当前 UI用peekaboo app list确认目标进程用peekaboo window list确认其精确窗口再用peekaboo see查看当前界面再重试。用结构化输出定位问题重跑时加--json或--verbose可以拿到具体的错误码如MENU_ITEM_NOT_FOUND、VALIDATION_ERROR、hint与retry_safe字段便于判断是名称/索引过期、作用域冲突还是缺少同意。索引过期状态栏重排后索引会失效先peekaboo menubar list刷新再按新索引操作名称目标则不受重排影响。验证失败若--verify报 popover not detected先确认点击确实产生了弹出 UI可临时设PEEKABOO_MENUBAR_OCR_VERIFY0排除 OCR 因素或设PEEKABOO_MENUBAR_AX_VERIFY1尝试 AX 路径。小结peekaboo menubar把 macOS 状态栏交互收敛为只读枚举 显式授权点击两段式流程list始终在后台提供权威清单click以--foreground作为强制门槛再通过名称/索引/应用作用域三种定位与--verify的五级验证链popover、焦点变化、owner 窗口、OCR、AX在可审计的证据绑定机制下完成点击。理解这些选项与拒绝语义你就能在自动化流程中安全、可靠地驱动 Wi-Fi、蓝牙、电池等系统状态项与第三方托盘应用。赞分享GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载相关推荐Peekaboo dialog 命令实战指南用 Accessibility 精确驱动 macOS 对话框、输入与文件面板Peekaboo dialog 命令实战指南用 Accessibility 精确驱动 macOS 对话框、输入与文件面板 peekaboo dialog 是GUI 自动化MCP 服务AI 应用如何快速上手Cosmos3-Nano5分钟从零开始的多模态AI模型部署指南如何快速上手Cosmos3 Nano5分钟从零开始的多模态AI模型部署指南 Cosmos3 Nano 是NVIDIA推出的全能多模态世界模型专为物理AI应用人工智能基础模型大模型多模态媒体生成具身智能命令名称命令名称 简洁的命令描述 可选的第二行描述 更多信息官方文档链接 示例描述 命令 选项 {{参数}} 另一个示例描述 命令 选项1 选项2 {{值1}}文档教程知识库上一篇SMS Backup OAuth2认证机制揭秘如何安全备份短信到Gmail下一篇Amphion Singing Voice ConversionSVC指南基于多语义内容特征与扩散声学模型的歌声转换全流程实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考