franzenzenhofer/big-arrow-on-the-screen

Source: https://github.com/franzenzenhofer/big-arrow-on-the-screen

让你的 AI 代理在屏幕上画大箭头、方框和文字

big-arrow-on-the-screen（bigarrow）：一个精巧的 macOS 命令行工具，同时也是一个代理技能（agent skill）。点击穿透，绝不抢焦点，自动消失。MIT 协议。

CI (https://github.com/franzenzenhofer/big-arrow-on-the-screen/actions/workflows/ci.yml) License: MIT

Hacker News 页面配了五个 bigarrow 箭头：真正的文章在这里，终于有一个比这个箭头还大的了，从 2007 年起设计就没变过，今天的讨论帖早在 2014 年就吵过了，不是潜水党？点这里登录

你的 AI 代理能重构 monorepo、写迁移脚本、解释 Monad，但当它需要你点一个按钮时，它只能把 “请在对话框中点击 Allow” 打印在一个你根本没在看的终端里。bigarrow 给了它一根手指。

bigarrow 指向对话框中的 Allow 按钮

bigarrow point --element "Allow" --app "System Settings" --text "Franz，点击 Allow"

一个大方友好、带着标牌的箭头出现在所有窗口之上，指向目标，然后自动消失。它点击穿透，绝不抢走你的焦点，适用于所有显示器和所有桌面空间，而且绘制完全不需要任何权限。它只是一个精巧的 Swift 二进制文件。没有守护进程，没有菜单栏图标，没有账号，没有遥测，而且我们反复确认过——里面没有 AI。它就是一个箭头。

这东西到底是干什么用的？

问得好。箭头从旧石器时代就已经存在了。以下才是变化所在：软件代理如今真正在你的 Mac 上干活了，而它们一直撞上同一堵墙——只有人类才能做的那部分工作。

• “点击 Allow。” macOS 权限提示框、OAuth 授权页面、“用…打开？“对话框。代理能找到按钮，但不该或者不能替你按下去。现在它可以指给你看了。
• “该你了。” 2FA 验证码、CAPTCHA、通行密钥、支付确认、签名、法律条款复选框。这些是代理绝不应该代替你点击的东西。它指出来，你来做决定，然后它继续。
• “是这个窗口，不是那个。” 你开了 14 个 Chrome 窗口。代理知道它说的是哪个：--window "Google Chrome:Pull request"。它甚至能选对标签页：--app "Google Chrome:Pull request"。
• “我需要你，而你正在泡咖啡。” --say 会把标牌上的文字朗读出来。你的 Mac 会直接把你叫回座位。
• 引导式设置和入门教程。 一步步带人走过设置面板：start，等他们操作完，stop，进入下一步。就像产品导览，只是没有产品。
• 远程协助。 “不是那个，是另一个齿轮图标。” 指出来，而不是费劲描述。
• 演示、录屏、文档。 录屏时突出重点，或者用 --png 直接把箭头渲染成 PNG 用于文档。
• 调试坐标。 不确定你的辅助功能（Accessibility）、截图或 Peekaboo 坐标对不对？指出来看看。--dry-run --json 会告诉你它将会指向哪里，但不实际绘制。

我们都经历过的场景

使用中性的演示对话框摆拍，用真实的 bigarrow 在干净的 CI 运行器上录制（BACKDROP_ARGS=--cover scripts/funny-scenes.sh）。对话框是假的。感受是真的。

它不是什么：不是给人用的屏幕标注工具，不是点击机器人，也不是截图工具。它从不点击、输入或截取任何东西。它只负责指。刻意为之。

安装

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill          # 教会 Claude Code (~/.claude/skills) 和 Codex (~/.agents/skills)

从源码构建：swift build -c release（需要 Xcode 16 或更新版本，macOS 14 或更新版本），二进制文件位于 .build/release/bigarrow。

代理需要的三个命令

bigarrow point --element "Allow" --app "System Settings" --text "Franz，点击 Allow"    # 按标签查找
bigarrow point --at 760,500 --text "Franz，点击这里"                                    # 按坐标定位
bigarrow start --window "Safari:Inbox" --text "这个窗口" && bigarrow stop             # 持续显示直到停止

每个箭头都会自己消失。没人需要替一个忘记收拾的代理清理残局：

目标类型：--at X,Y、--rect X,Y,W,H、--mouse、--window App[:标题]、--element 标签 --app 应用、--peekaboo ID --snapshot see.json（来自 Peekaboo 的 see --json）。坐标为全局左上角逻辑点，即辅助功能（Accessibility）、CGWindowList 和 Peekaboo 所报告的坐标空间。--display N 使 --at 和 --rect 相对于某个显示器。

箭头与它指向的应用绑定。--app 应用[:窗口或标签页标题]（或 --window）会先把该应用、窗口或 Chrome/Safari 标签页带到前台，因为指向一个藏在终端后面的窗口是最没用的事；当另一个应用遮挡目标时，箭头会隐藏，目标回到前台时它也随之回来。--no-raise 则不动你的窗口。bigarrow elements --app X 列出 --element 可以匹配的元素。bigarrow doctor 显示权限、权限归属方以及你的显示器信息。

每个命令都支持 --json。退出码：0 成功，2 输入错误，3 目标未找到，4 缺少权限。代理喜欢退出码。人类勉强能忍受。

外观

它是一个箭头，所以我们在外观上花了不成比例的时间。

带标牌的大箭头：点这里、标牌在这里、过来这边、你在这里、输入你的姓名、先读这个、不是那个、点击 Allow

所有边框样式和颜色选项：默认白色边框带阴影、白底黑边、纯黑色、关闭按钮、自定义边框和文字颜色

在干净测试机上的真实截图，六种外观分别叠加在白色、macOS 灰色、深色、黑色、红色和繁忙网页上：

默认、白底黑边、纯黑色、关闭按钮、自定义颜色加黑色箭头，各叠加在六种背景上

所有样式、形状、尺寸和颜色

• --shape bend|straight|zigzag|spiral（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：默认是白色边框（深色背景则用深色边框）加投影；white-black 在白色边框外加一圈细黑边代替阴影；black 只是一圈细黑色轮廓
• 每种颜色都可自定义：--border-color、--text-color、--edge-color，关闭按钮还有 --close-color 和 --close-x-color。不指定时，每项会自动选择可读的颜色
• --close-button 在标牌右端放置一个 X（白色圆圈，X 为箭头颜色），永远不会遮住文字也不会跑到屏幕外
• --follow 跟随窗口或元素移动，--until-click 在点击目标时结束，--say 朗读标牌文字
• 同时显示多个箭头时，标牌会互相避让

箭杆从标牌伸出，通过一个外扩的接头连接，接头永远不会碰到圆角。scripts/gallery.py 离屏渲染所有组合并放大检查每个接头（接头详情），因为接头处出现接缝显然是不可接受的。

常见问题

它需要屏幕录制或辅助功能权限吗？ 绘制不需要任何权限。--element、elements、--until-click 和 front --window 使用辅助功能（Accessibility），macOS 将该权限授予运行你 shell 的应用（Terminal、iTerm2、Ghostty、VS Code、Claude），而不是授予 bigarrow 本身。bigarrow doctor 会显示是哪个应用，退出码 4 会告诉代理应该向你请求什么。--window App:标题 需要读取窗口标题，macOS 26 在没有屏幕录制权限时会隐藏标题；单独使用 --window App 不需要任何权限。

它会在我打字时抢走焦点吗？ 不会。这是项目中最难修复的一个 bug：NSApplication.run() 会悄悄激活一个没有终端的进程，导致后台的箭头抢走焦点。bigarrow 改为自己泵送事件循环，测试会验证最前面的应用始终不变。

我可以点击穿透它吗？ 可以。除了标牌和箭杆之外的任何位置：在标牌或箭杆上点击会移除箭头（在指针下箭头会稍微变暗以示提示）。点击目标本身或箭头尖端附近的任何位置，都会直接穿透到底层应用。点击箭头永远不会获取焦点。

多显示器？全屏应用？台前调度（Stage Manager）？多个桌面空间（Spaces）？ 可以，可以，可以，都可以。包括位于主显示器左侧或上方的显示器（负坐标）。在箭头显示时拔掉该显示器，箭头会礼貌地消失。参见验证矩阵。

一个脉冲动画的箭头消耗多少 CPU？ 在 CI 运行器上实测为 1.4%。实际渲染工作由渲染服务器的 Core Animation 完成。

--element 能在网页中工作吗？ 在 Electron 应用中可以。在 Chrome 中，只有当 Chrome 以 --force-renderer-expose-accessibility（或开启 VoiceOver）启动时才行；Chrome 会忽略通常的内容暴露请求，已在 2026 年 10 月在 Chrome 上验证。Chrome 自身的工具栏始终可用。其他情况下请指向页面坐标，技能文档中有说明。

为什么不直接用[某个屏幕标注应用]呢？ 那些是给人在屏幕上画画用的。这是给程序用的，从 shell 中指向目标，带退出码。在写下第一行代码之前，我们调研了二十六个工具（调研记录）。没有一个能做这件事。

它是 AI 吗？ 不是。它是你 AI 工具链中智能程度最低的部分，并且引以为傲。

我们怎么知道它能用

• 87 个自动化测试：几何计算、定位、接头平滑度、黄金图像、录制的窗口服务器、辅助功能和 Peekaboo 4.9.0 测试数据，以及针对真实窗口服务器的测试（窗口层级 1000、点击穿透、焦点永不移动、分离与停止计时）。CI 在 macOS 15 上运行这些测试；它们也在 macOS 26 和 macOS 27 上通过了。
• 在干净的运行器上进行了 17 项行为检查（visual.yml）：真实点击 X 按钮、--until-click、--follow、置前（以及 --no-raise）、被遮挡时隐藏、选择 Chrome 标签页、随属主进程结束、stop --hook、--say、全屏应用、台前调度、切换桌面空间、第二显示器、2x 缩放显示器、箭头显示中拔掉显示器、CPU 占用。上面的演示 GIF 由同一个工作流录制，在一个没有任何个人信息的桌面上完成。
• 一个全新的代理，只给了它技能文档和 “告诉 Franz Chrome 里的 Reload 按钮在哪里”，就通过标签找到了它并构建了正确的命令（对话记录）。它还发现了一个 bug，现在已经变成了一个测试用例。

面向代理（以及配置代理的人类）

skill/big-arrow/ 中的技能同时适用于 Claude Code 和 Codex（一个 SKILL.md，Agent Skills 格式，外加 agents/openai.yaml 用于 Codex）。它告诉代理何时应该指出来、如何选择目标、在标牌上写一句完整的话、在你可能没在看时加上 --say，并在你操作完毕后 stop。

计划、决策、调研

docs/plan/PLAN.md（目标、架构、风险），docs/plan/TICKETS.md（由 docs/plan/tickets.json 生成），docs/decisions/，docs/research/（已验证的事实及链接），docs/verification/，docs/skill-tests/，CHANGELOG.md。

先例与致谢

Peekaboo 的可视化器 (https://github.com/openclaw/Peekaboo) 和 Peter Steinberger 的 Nameplate (https://github.com/steipete/Nameplate) 展示了覆盖层窗口的实现方案和代理技能的打包方式。两者都没有绘制带标签的指向箭头，这正是本项目填补的空白。bigarrow 支持将 Peekaboo 的 see --json 作为可选的目标来源。

许可证

MIT。请负责任地使用箭头。