屏幕上的大箭头能做什么
big-arrow-on-the-screen，也称为 bigarrow，是一款 macOS 命令行工具，可在每个窗口上方绘制醒目的箭头和提示牌。它专为 AI 智能体设计：智能体可以完成大多数计算机任务，但某些决策必须交还给人类。
例如，智能体可以指向“允许”按钮、识别正确的浏览器窗口，或引导用户完成多步骤工作流。用户始终掌握控制权：bigarrow 不会点击、输入或捕获屏幕内容。
覆盖层会显示在普通窗口、对话框、全屏应用和空间上方，同时保持键盘焦点在当前已获得焦点的应用中。针对目标的点击会穿透覆盖层，传递给下方的应用。箭头也会在持续时间结束或所属进程退出时自动移除。
你的智能体可以说明该做什么，然后在真人需要操作的准确控件上放置一个醒目的指示。
何时使用
当 AI 智能体需要真人做出决定或完成操作时，bigarrow 都很有用。典型场景包括权限提示、OAuth 授权页面、双因素身份验证、CAPTCHA、人 passkey、付款、签名和法律确认。
当屏幕上显示多个相似窗口或控件时，它也能让指引更清晰。智能体可以选择特定的应用、窗口或浏览器标签页，而不是让用户在许多打开的窗口中自行查找。
其他用途包括教学使用应用、提供远程帮助、在屏幕录制中突出显示控件，以及检查其他自动化工具返回的坐标是否正确。
在 macOS 上安装
该项目支持 macOS 14 或更高版本。最简单的安装方式是使用 Homebrew：
brew install franzenzenhofer/tap/bigarrow
如果你希望 Claude Code 和 Codex 知道何时以及如何使用该工具，也请安装它的智能体技能：
bigarrow install-skill该命令会将技能安装到 Claude Code 的 ~/.claude/skills 和 Codex 的 ~/.agents/skills。你也可以不安装技能，直接从 shell 调用 bigarrow。
从源代码构建
要自行编译项目，请使用 Xcode 16 或更高版本：
swift build -c release生成的二进制文件位于 .build/release/bigarrow。应用本身使用 Swift 编写。scripts/ 中的 shell 和 Python 文件用于截图和测试。
第一个指向命令
三种基本用法分别是指向辅助功能元素、指向坐标，以及让箭头保持显示直到你将其停止。
指向带标签的控件
bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow: Ghostty may control your Mac"--element 根据控件标签进行匹配，--app 则标识包含该控件的应用。提示牌会说明用户需要执行的操作。
指向坐标
bigarrow point --at 760,500 --text "Franz, click HERE"坐标使用全局左上角逻辑点，与 macOS Accessibility、CGWindowList 和 Peekaboo 报告的坐标空间相同。你也可以指向一个矩形区域：
bigarrow point --rect 600,400,240,80 --text "This is the area to review"让箭头保持显示直到下一步
bigarrow start --window "Safari:Inbox" --text "This window"
bigarrow stopstart 会立即返回，并让箭头保持显示。使用 stop 移除当前箭头，或使用 stop --all 移除所有箭头。
一次性的 point 命令默认持续八秒。使用 --duration 可更改时长；start 默认持续 300 秒。使用 --duration 0 可不设时间限制。
选择正确的目标
bigarrow 支持多种目标来源：
--at X,Y指向坐标。--rect X,Y,W,H突出显示矩形区域。--mouse指向当前鼠标位置。--window App[:title]指向窗口。--element Label --app App查找辅助功能元素。--peekaboo ID --snapshot see.json使用 Peekaboo 的see --json输出中的元素 ID。
要查看应用公开的控件，请运行：
bigarrow elements --app "System Settings"对于多显示器，--display N 会让坐标和矩形值以其中一个显示器为基准。对于位于主显示器左侧或上方的显示器，也支持负的全局坐标。
定位正确的窗口或浏览器标签页
当你提供 --app App[:window or tab title] 或 --window 时，bigarrow 可以在绘制箭头前将相关应用、窗口或 Chrome/Safari 标签页置于前台。这样可以避免本来准确的箭头显示在错误的可见窗口上方。
bigarrow point --app "Google Chrome:Pull request" --text "Review this pull request"如果希望用户的窗口保持原位，请使用 --no-raise。如果其他应用后来遮挡了目标，箭头会隐藏，直到目标再次可见。
让箭头清晰且实用
你可以自定义箭头的形状、样式、大小、圆角、颜色和行为：
--shape bend|straight|zigzag|spiral选择箭头路径。--style arrow|ring|box选择普通箭头、仅显示边框的圆环或仅显示边框的方框。--size S|M|L更改大小。--corners round|sharp控制标记的边角样式。--color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBB设置主颜色。--border shadow|white-black|black更改边框效果。--border-color、--text-color和--edge-color分别自定义颜色。--close-button在标记上添加可点击的 X。
例如，以下命令会在目标周围绘制醒目的绿色方框：
bigarrow point --at 760,500 --style box --color green --text "Review this control"关闭按钮需要主动启用，可让用户直接关闭叠加层：
bigarrow start --element "Save" --app "TextEdit" --close-button --text "Click Save when ready"
实用的交互选项
多个选项可以帮助将叠加层与引导式工作流连接起来：
--follow让箭头跟随窗口或元素移动。--until-click在用户点击目标后结束箭头。--say朗读标记内容；当用户可能没有注视屏幕时很有用。--json为代理和脚本提供机器可读的输出。
因此，引导式流程可以先指向一个控件，等待用户操作，结束箭头，然后指向下一个控件。该工具不会自行执行点击。
了解权限
绘制叠加层不需要 macOS 的屏幕录制或辅助功能权限。不过，某些查找或激活目标的方式需要相应权限。
--at、--rect、--mouse、--window App、--peekaboo和--app App不需要权限。--element、elements、--until-click和--app App:title需要辅助功能权限。--window App:title需要屏幕录制权限才能读取窗口标题，并需要辅助功能权限才能将窗口置于前台，除非使用--no-raise。
macOS 会将这些权限授予启动 bigarrow 的应用，例如 Terminal、iTerm2、Ghostty、VS Code 或 Claude，而不是授予 bigarrow 二进制文件本身。
运行诊断命令，查看相关权限、其所属应用以及已连接的显示器：
bigarrow doctor缺少所需权限时，命令会以状态码 4 退出，并指出涉及的应用和设置面板。
安全使用自动清理
箭头的设计目标是在代理完成工作后不会一直残留。定时的 point 命令会自动移除自身。创建箭头的代理进程退出时，箭头也会结束；如果可用，工具会使用 CLAUDE_PID 或 BIGARROW_OWNER_PID。
对于 Claude Code 工作流，可以将 bigarrow stop --hook 用作 UserPromptSubmit 钩子，在用户响应时清除该会话的箭头。显式清理命令如下：
bigarrow stop
bigarrow stop --all对于可能在正常清理步骤前被中断或替换的代理，这些保护措施很有用。
在代理工作流中使用 JSON 和退出码
每个命令都接受 --json，从而更容易以编程方式检查结果。文档规定的退出码如下：
0：命令成功完成。2：输入无效。3：未找到目标。4：缺少所需权限。
代理可以根据这些结果决定是否使用其他目标方法重试、请求用户授予权限，或说明无法找到请求的控件。
高级目标调试
如果不确定来自辅助功能、Peekaboo 或其他工具的坐标是否正确，可以使用试运行：
bigarrow point --at 760,500 --dry-run --json
该命令会报告工具将指向的位置，但不会绘制叠加层。这有助于在向用户显示任何内容前，验证坐标转换、显示器选择和自动化结果。
Peekaboo 可以提供另一种目标来源。先捕获 Peekaboo JSON 快照，然后传入匹配的元素 ID：
bigarrow point --peekaboo ELEMENT_ID --snapshot see.json --text "Review this element"在 Chrome 中，页面元素可能需要 Chrome 的 --force-renderer-accessibility 标志或 VoiceOver。Chrome 自带的工具栏仍可通过常规辅助功能路径使用。当页面内容未被暴露时，请改用坐标。
代理应如何使用此技能
随附的技能通过一个兼容 Agent Skills 的 SKILL.md 同时支持 Claude Code 和 Codex，并在 agents/openai.yaml 中包含 Codex 元数据。它会指导代理何时指示、如何选择目标、如何在标牌上写出完整句子、何时使用 --say，以及在用户采取行动后何时停止。
实际的代理流程如下：
- 确定需要人工确认或协助的操作。
- 选择标签、窗口、标签页、坐标、矩形区域或 Peekaboo 目标。
- 编写标牌，明确说明用户应做什么以及原因。
- 将目标应用程序置于前台，除非保持当前布局很重要。
- 等待用户操作或回应。
- 在继续下一步之前停止箭头。
此工具不会做什么
bigarrow 的功能经过有意限制。它不是面向用户的屏幕标注工具、点击机器人或截图工具。它绝不会点击、输入文字或捕获屏幕。它的用途是让程序的指令可见，同时将决定权和操作权留给用户。
环形和方框样式使用轮廓线，以便目标保持可见。如果空间足够，标牌会放置在远离目标的位置；启用关闭按钮后，用户可以关闭箭头。这些设计选择使该工具适用于权限、身份验证、付款和部署等敏感操作。
结论
bigarrow 为基于 macOS 的 AI 代理提供了一种简单方式，让其无需依赖含糊的终端消息即可将控制权交还给用户。使用 Homebrew 安装它，并在需要时添加 Claude Code 或 Codex 技能，然后使用 point 发送简短提示，或使用 start 和 stop 执行引导式流程。
借助标签、窗口、坐标、矩形区域、鼠标和 Peekaboo 目标，以及可自定义的样式、语音、JSON 输出、自动清理和多显示器支持，该工具将“请点击这里”转化为精确的屏幕指引，同时确保最终操作由用户掌控。