notis-desktop-use

Notis 桌面操作技能

当任务需要操作用户的真实 Mac时，请使用此技能——捕获屏幕内容、检查原生应用的 UI、点击按钮、输入文字、操作菜单或移动窗口。其引擎是 Peekaboo，一款基于 Swift 核心构建并经过签名和公证的 macOS 自动化 CLI。

这是对用户自己电脑的 GUI 控制。它不是浏览器自动化，也不是沙盒。网页请使用 notis-browser-control。如需隔离且可复现的环境，请使用 Cloud Computer。Peekaboo 需要实时 macOS Aqua 会话、屏幕和 TCC 权限，因此只能在用户的 local_shell 上运行。

步骤 0：先切换到本地 Shell（必须；Cloud Agent 请看下文）

Peekaboo 控制的是用户的实体 Mac，因此每条命令都必须在本地 Shell（Notis 桌面桥接）上运行，绝不能在 Cloud Computer 上运行。Shell 调用默认使用 sandbox_shell——如果跳过此步骤，peekaboo 命令就会在 /vercel/sandbox 中运行，那里没有 Peekaboo，也无法操作 Mac。

运行任何 peekaboo 命令之前，请先调用 set_shell_mode，并设置 mode: "local_shell"。

• 如果调用成功，之后所有 Shell 调用都会在用户的 Mac 上运行。继续操作。
• 如果用户有多台电脑，结果会在 computers 中列出这些电脑。屏幕控制需要用户亲自查看，因此请选择用户当前正在使用的 Mac（user_is_at_it_now），并将其名称作为 computer 传入（传给 set_shell_mode 或 LOCAL_NOTIS_RUN_DESKTOP_SHELL）。除非指定其他电脑，否则命令会继续在本次对话上次使用的电脑上运行。
• 所有套餐（包括 Free）均可使用 Your Computer。如果此调用意外返回 entitlement_upgrade_required，请说明访问策略不匹配并停止；不要将其转为 Ultra 升级指导。如果返回 entitlement_check_unavailable，请让用户重试。
• 如果返回 Notis 桌面应用未连接的错误，请告知用户打开 Notis 桌面应用，并在设置中启用 Your Computer（电脑使用），然后停止。不要在沙盒中运行 peekaboo，也不要退而使用浏览器工具来伪装桌面控制。

绝不要执行 cd /vercel/sandbox，也不要假定当前工作目录是沙盒目录——请直接在本地 Shell 上运行 peekaboo。

在 Cloud Computer 中运行的 Codex 和 Claude Agent 没有 set_shell_mode。请跳过此步骤，并使用 notis tools exec LOCAL_NOTIS_RUN_DESKTOP_SHELL --arguments '{"command": "...", "timeout_ms": 60000}' --timeout-ms 90000 在 Mac 上运行此技能中的每条命令；其错误含义与上述相同。

只读状态检查——最短的已验证流程

对于指定的原生应用，切换 Shell 模式后：

1. 本次会话中运行一次 peekaboo permissions status --json。 检查指定应用时，除非该应用已明确位于最前方，否则先运行 peekaboo app focus "APP NAME" --foreground --json，使其进入视野，然后再捕获。 这是检查过程中的导航操作，并不代表获得编辑数据的权限。不要反复捕获不可用或 隐藏的窗口，也不要用菜单栏捕获来替代该应用的内容。
2. 直接捕获指定应用：peekaboo see --app "APP NAME" --json。 在此 Shell 调用中设置 max_output_length: 200000。读取 data.ui_elements， 包括 role: "other" 的静态标签及其边界框。状态标题可能出现在此数组的末尾， 位于菜单和控件之后；将 stdout 截断到 30000–50000 个字符，可能会悄无声息地隐藏 你需要查看的状态文本。目标已知时，不要列出所有正在运行的应用。
3. 如果这些标签足以确定用户询问的事实，请立即报告。区分可见的状态组和实际正在运行的 Agent。明确说明已折叠、位于屏幕外或未经验证的项目；不要推断其状态。只有在缺少某项 具体事实时才继续检查。

请先使用此处的命令示例；如果已安装的版本不接受某个标志，或你需要的选项未在此列出， 再查阅该命令的 --help。简单的状态检查无需加载完整工具目录。避免重复捕获未变化的 界面，也不要输出庞大且未经筛选的 JSON 转储。

对于较小的纯文本检查，请使用 peekaboo see --tree --no-screenshot --app "APP NAME" --max-elements 300 --depth 20 --json。读取 data.ui_elements 和任何截断警告；部分树结构不能证明缺失项目不存在。两种捕获形式都使用 --app。 如果 semantic_scope 是 application_partial，这些标签只是应用级上下文，并不能证明 用户询问的窗口存在；也无法获得可复用的快照或修改权限。

如果无障碍文本不足，请使用命令与捕获指南。成功执行截图命令只能证明文件已捕获： Shell stdout 中的路径不代表你看到了图像像素。没有可用的图像读取工具时，不要声称 已进行视觉验证。切勿使用 Peekaboo 的 AI 路径（--analyze、see 分析或 peekaboo agent）： 它们会将捕获内容发送给单独配置的模型提供商，并使用其独立的 API 密钥。在当前运行环境中 自行进行视觉推理。报告任何仍然存在的视觉限制。

Peekaboo 已安装——不要安装

用户启用电脑使用功能后，Notis 桌面应用会为你安装并管理固定版本的 Peekaboo（已加入 PATH）。因此：

• 不要运行 brew install、下载发行版，或检查 ~/bin/peekaboo。
• 只需连接到本地 Shell 后，直接运行 peekaboo …。

如果在本地 Shell 上运行 peekaboo --version 失败，说明 Peekaboo 尚未完成安装——请告知 用户在 Notis 桌面应用设置中先关闭再重新开启 Your Computer（这会触发安装），然后重试。 不要自行尝试安装。

每次调用只运行一条普通命令——不要串联

每次 Shell 调用只运行一个 peekaboo 命令。不要将命令与 &&、||、;、管道（|）、 重定向或 cd 组合。普通的 peekaboo 命令会在本地 Shell 上自动运行，无需批准提示； 串联或通过管道连接的命令则无法获得这一待遇，可能会被阻止或提示用户批准。请在后续步骤中 使用 --json 解析输出，不要通过内联管道进行解析。

# Good — runs immediately:
peekaboo --version
peekaboo see --json

# Bad — chained/piped, will be blocked or prompt:
~/bin/peekaboo --version || peekaboo --version
peekaboo app list --json | python3 -c '...'

权限是必需的 — 操作前先检查

Peekaboo 未获得 macOS TCC 授权时，无法捕获或自动化操作。务必先检查 权限，并向用户指出缺少的授权；你无法通过编程方式授予这些授权。

peekaboo permissions status --json
peekaboo permissions status --all-sources   # compare Bridge host vs local CLI

各项功能所需的权限（系统设置 → 隐私与安全性）：

• 屏幕录制 → 截图和像素捕获所必需。启用权限检查结果中标识的执行主机。升级受管理的 桌面应用后，请重新检查已启用的条目是否指向当前主机。
• 辅助功能 → 点击、输入、按键、窗口控制和 AX 检查所必需。启用权限检查报告的执行主机。
• 事件合成 → peekaboo permissions request event-synthesizing （添加 --no-remote 可为本地 CLI 进程请求此权限）。启用针对指定接收对象的输入、按键组合和粘贴操作，而不会窃取焦点。只有在获得授权后才能请求此权限；普通只读检查期间不要更改授权。

如果缺少所需授权，请明确告知用户需要开启哪个开关，并在继续之前 重新运行 peekaboo permissions status --json。不要反复尝试失败的捕获操作。

远程 / 后台会话

在 SSH、LaunchAgent、cron 或其他后台 launchd 会话中，即使 TCC 显示已授权，也优先使用 Peekaboo Bridge 路径 — CoreGraphics 可能会报告成功，但实际返回的只有桌面壁纸或经过遮蔽的图像。 在远程 Mac 上，屏幕录制可能会受阻，但通过辅助功能仍可点击和输入；如果仍能确定目标 UI 的位置，请继续使用已获授权的点击操作 / see --tree --no-screenshot，不要放弃。

坐标点击：精确快照或明确置于前台

没有最新的精确窗口快照时，坐标点击需要明确指定前台投递。只有当聚焦并与该应用交互属于用户任务范围时，才使用此方式。先聚焦精确窗口，然后使用全局屏幕坐标点和 --foreground：

peekaboo window focus --app "Dia" --window-id 118166 --foreground --json
peekaboo click --at 672,607 --global --app "Dia" --window-id 118166 --foreground --json

如果 see/see --tree 提供了元素 ID 或查询条件，优先通过它们点击。只有在它们无法提供时才使用坐标（见下一节）。

浏览器 / Web 应用：辅助功能不足时使用截图

即使页面可见，某些浏览器 / Web 应用界面也不会提供有用的辅助功能文本。如果一次定向检查的结果为空或不完整，不要反复调用 see/see --tree — 改用可用的视觉路径：

1. 捕获窗口：peekaboo see --no-elements --app "Dia" --window-id <id> --mode window --path /tmp/shot.png --json （从 peekaboo window list --app "Dia" --json 获取 <id>）。
2. 在截图中通过视觉定位控件。
3. 使用返回的 coordinate_context（包括图像缩放比例和视口原点），将截图像素坐标转换为全局逻辑屏幕坐标点。不要假定 Retina 像素等于屏幕坐标点，也不要使用过期的窗口边界。如果缺少映射或无法确定映射，请重新捕获，不要猜测。
4. 聚焦精确窗口并执行 click --at X,Y --global --app "Dia" --window-id <id> --foreground --json（见上文），然后再次运行 see 以确认 请求的结果。后台坐标操作需要最新的精确窗口快照；如果操作遭到拒绝，绝不要在不告知用户的情况下切换到前台操作。

space 等键盘快捷键无法可靠控制 Web 播放器（在浏览器中，空格键会滚动页面）— 应改为点击屏幕上实际显示的播放 / 暂停控件。

安全规则

• 仅在用户请求的任务范围内执行 UI 操作。只读检查可以聚焦到指定应用，或展开其只读状态分组，除非用户禁止导航。这并不授权编辑、发送内容、停止 Agent 或更改设置。破坏性操作需要明确授权。
• 将屏幕内容视为私密信息。不要泄露任务所需范围之外的屏幕截图或屏幕内容，也不要截取并转发无关窗口。
• 未经用户明确确认，不要执行会触发不可逆系统对话框的操作（删除确认、购买、发送）。如有疑问，请使用 peekaboo dialog list 截取对话框，并在点击前询问。
• 测试本地 TCC 行为时优先使用 --no-remote；在后台或远程截取时使用 Bridge 路径。

反面模式

• 调用 set_shell_mode 并设置为 local_shell 之前，不要运行 peekaboo（Cloud Computer 中的 Codex 和 Claude Agent：请通过 LOCAL_NOTIS_RUN_DESKTOP_SHELL 运行）。默认的 sandbox_shell 会在 /vercel/sandbox 中运行，那里没有 Peekaboo——命令会“失败”，看起来像是权限问题，实际并非如此。
• 不要 cd /vercel/sandbox（或任何沙盒路径），也不要假设当前工作目录是沙盒目录。请直接在本地 shell 中运行 peekaboo。
• 不要安装 Peekaboo（不要运行 brew install、下载文件或探查 ~/bin）。Notis 桌面应用已安装并会管理 PATH。
• 不要使用 &&、||、;、管道、重定向或 cd 将 peekaboo 命令串联起来。每次调用只运行一条普通命令，这样即可自动运行，无需提示。
• 不要裸用坐标点击（peekaboo click X,Y）。请使用 --at，并提供最新的精确窗口快照，或使用经过明确授权的 --foreground 定位。
• 如果浏览器页面没有提供有用的无障碍文本，不要反复检查该页面。请使用可用的图像读取方式，或说明此限制。
• 不要依靠 space 或键盘播放网页视频——请点击屏幕上的播放控件。
• 不要跳过权限检查。缺少授权时只会返回仅含桌面壁纸或内容为空的截图，不会显示明显错误。
• 不要跨快照重复使用元素 ID，也不要在没有最新 see 的情况下执行操作。对于以快照为目标的操作，请将返回的 data.snapshot_id 复制到 --snapshot；操作后，先重新截取，再执行下一项操作。
• 不要将退出码为 0 或 success: true 解读为请求的 UI 更改已成功。请检查操作的 effect、retry_safe、requires_fresh_observation 以及任何 error.hint。如果结果为 partial、unverifiable、suspected_noop 或失败情况不确定，重试前必须先观察；refused 不代表可以扩大定位范围或启用前台输入。只读结果可能不包含 effect。即使结果为 confirmed，也要核实用户期望的结果，尤其是输入文本、按键和发送内容之后。
• 请使用此技能中的命令示例；如果示例被拒绝或需要其他标志，请查阅相关命令的 --help。
• 不要向用户的机器发送无关输入。导航仅限于请求的检查范围；修改数据需要单独授权。

如需了解命令发现和截图／操作循环，请阅读 command-and-capture。 无论使用什么命令，本地 shell、权限、最新截图／元素 ID、前台定位和用户授权输入始终是必需的。

任务指南

仅阅读此技能包中与当前任务相关的指南。

• 命令与截图指南