bigarrow 开源：让 AI 智能体在 macOS 屏幕上画大箭头提示用户操作

Hacker News：AI 热帖· franze·2026-10-09 19:03· 1 小时前AI 评分72

让你的 AI 智能体在屏幕上画出大箭头、方框和文字

AI 导读

作者发布开源工具 bigarrow（big-arrow-on-the-screen），一个 macOS CLI 和智能体技能，让 AI 智能体在屏幕上画出带文字的大箭头、方框，指向需要人工点击的按钮或窗口。

正文

big-arrow-on-the-screen (bigarrow)：一个小巧的 macOS CLI 和一个智能体技能。点击穿透，绝不抢焦点，自行消失。MIT 许可。

你的 AI 智能体可以重构 monorepo、编写迁移脚本、解释 monad，但当它需要你点击一个按钮时，它却把 “请在对话框中点击允许” 打印到一个你根本没在看的终端里。bigarrow 给了它一根手指。

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"

一个巨大、友好的箭头带着标牌出现在所有内容之上，指向目标，然后再次消失。它点击穿透，绝不抢你的焦点，在所有显示器和所有 Space 上都有效，而且绘制时完全不需要任何权限。它是一个小巧的 Swift 二进制文件。没有守护进程，没有菜单栏图标，没有账户，没有遥测，而且我们检查了两次，里面没有 AI。它就是一根箭头。

这到底是干什么用的？

问得好。箭头大约自旧石器时代就已存在。变化在于：软件智能体现在会在你的 Mac 上做真正的工作，而它们总是撞上同一堵墙，那部分只有人类才能做的事。

“点击允许。” macOS 权限提示、OAuth 同意屏幕、“打开方式……？”对话框。智能体可以找到按钮，但不应、也不能替你按下。现在它可以指向它。
“轮到你了。” 2FA 验证码、CAPTCHA、通行密钥、支付确认、签名、法律复选框。这些是智能体绝不应代表自己点击的东西。它指向，你决定，它继续。
“是这个窗口，不是那个。” 你开了 14 个 Chrome 窗口。智能体知道它指的是哪一个：--window "Google Chrome:Pull request"。它甚至能选对标签页：--app "Google Chrome:Pull request"。
“我需要你，而你却在煮咖啡。” --say 会朗读标牌。你的 Mac 会真的把你叫回桌前。
引导式设置和入门引导。 一步步带人走过设置面板：start，等待他们操作，stop，下一步。就像产品导览，只是没有产品。
远程协助。 “不，是另一个齿轮图标。”直接指向它，而不是描述它。
演示、录屏、文档。 录制时高亮重点，或者用 --png 把箭头直接渲染成 PNG 用于文档。
调试坐标。 不确定你的辅助功能、截图或 Peekaboo 坐标是否正确？指向它们看看。--dry-run --json 会告诉你它会指向哪里，而不实际绘制。

我们都经历过的场景

用一个中立的演示对话框搭建，并在干净的 CI runner 上用真实的 bigarrow 录制（BACKDROP_ARGS=--cover scripts/funny-scenes.sh）。对话框是假的。感受是真的。



`--color green`	`--shape zigzag --color orange`

`--color purple`	`--close-button`，因为人类拥有最终决定权

三个 `start`，一个按钮，零歧义	`--style box --corners sharp`，外加一堂关于 macOS 权限的课

`--shape spiral`：先绕标牌一圈，然后指向按钮

它不是什么：不是给人用的屏幕标注工具，不是点击机器人，也不是截图工具。它从不点击、输入或捕获任何东西。它只指向。刻意如此。

安装

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill          # teaches Claude Code (~/.claude/skills) and Codex (~/.agents/skills)

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

智能体需要的三条命令

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"   # by label
bigarrow point --at 760,500 --text "Franz, click HERE"                                 # by coordinate
bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop            # until stopped

每根箭头都会自行结束。没人需要为一个忘记清理的智能体善后：


时间限制	`bigarrow point ... --duration 10`（默认 8 秒；`start` 300 秒；`--duration 0` = 无限制）
启动和停止	`bigarrow start ...` 立即返回；`bigarrow stop`（或 `stop --all`）将其移除
代理离开	当绘制箭头的代理进程退出时，箭头结束（`CLAUDE_PID`，或 `BIGARROW_OWNER_PID`）
人类回答	`bigarrow stop --hook` 作为 Claude Code 的 `UserPromptSubmit` 钩子会清除该会话的箭头
人类关闭它	`--close-button` 在标牌上放置一个可点击的 X（可选启用）

目标：--at X,Y、--rect X,Y,W,H、--mouse、--window App[:title]、--element Label --app App、--peekaboo ID --snapshot see.json（来自 Peekaboo 的 see --json）。坐标是全局左上角逻辑点，即 Accessibility、CGWindowList 和 Peekaboo 报告的空间。--display N 使 --at 和 --rect 相对于单个显示器。

箭头与它所指向的应用绑定。--app App[:window or tab title]（或 --window）会先将该应用、窗口或 Chrome/Safari 标签页带到前台，因为指向一个藏在终端后面的窗口是一种特别没用的行为；而当另一个应用覆盖目标时，箭头会隐藏，并随目标一起回来。--no-raise 不会动你的窗口。bigarrow elements --app X 列出 --element 可以匹配的内容。bigarrow doctor 显示权限、权限所有者以及你的显示器。

每条命令都接受 --json。退出码：0 表示正常，2 表示输入错误，3 表示未找到目标，4 表示缺少权限。代理喜欢退出码。人类容忍它们。

外观

它是一支箭头，所以我们在它的外观上花了不合理的大量时间。

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

--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：默认是白色边框（在浅色上为深色）加投影；white-black 在白色边框外加上一条细黑边，而不是投影；black 只是一条细黑轮廓
每种颜色都由你决定：--border-color、--text-color、--edge-color，对于 X 则是 --close-color 和 --close-x-color。省略时，每个都会自行选择一种可读的颜色
--close-button 在标牌右端内部放置一个 X（白色圆圈，X 为箭头颜色），这样它永远不会遮住文字或超出屏幕
--follow 随窗口或元素移动，--until-click 在点击目标时结束，--say 朗读标牌
多个箭头同时出现时，它们的标牌会彼此避开

箭杆通过一个外扩的接头从标牌中长出，这个接头永远不会撞上圆角。scripts/gallery.py 会在屏幕外渲染每一种组合，并放大每个接头（junctions），因为接头处出现接缝，显然是不可接受的。

FAQ

它需要屏幕录制或辅助功能权限吗？ 绘制两者都不需要。--element、elements、--until-click 和 front --window 使用辅助功能权限，macOS 会将其授予运行你 shell 的应用（Terminal、iTerm2、Ghostty、VS Code、Claude），而绝不会授予 bigarrow 本身。bigarrow doctor 会指出那个应用，退出码 4 会准确告诉代理该向你请求什么。--window App:title 会读取窗口标题，而 macOS 26 在没有屏幕录制权限时会隐藏这些标题；只有 --window App 什么都不需要。

它会在我在打字时抢走我的焦点吗？ 不会。那是这个项目中最难的 bug：NSApplication.run() 会悄悄激活一个没有终端的进程，所以分离的箭头会抢走焦点。bigarrow 改为自行泵送事件，测试会检查最前面的应用从未改变。

我能点击穿透它吗？ 可以，除了标牌和箭杆之外的所有地方都可以：点击那里会移除箭头（指针悬停时它会稍微变暗以表示这一点）。点击目标，或箭头头部附近的任何地方，都会直接穿透到应用。点击箭头永远不会夺走焦点。

多显示器？全屏应用？台前调度？空间？ 是，是，是，是。包括位于主显示器左侧或上方（负坐标）的显示器。当箭头位于某个显示器上时拔掉该显示器，箭头会礼貌地离开。参见验证矩阵。

一个脉冲箭头会消耗多少 CPU？ 在 CI 运行器上测得为 1.4%。Core Animation 在渲染服务器中完成这项工作。

--element 能在网页内部工作吗？ 在 Electron 应用中，可以。在 Chrome 中，只有当 Chrome 以 --force-renderer-accessibility 运行时（或 VoiceOver 开启时）才行；Chrome 会忽略通常的暴露页面内容请求，已于 2026 年 10 月在 Chrome 上验证。Chrome 自带的工具栏始终有效。否则就指向页面的坐标，技能中有说明。

为什么不直接用[某个屏幕标注应用]？ 那些是给人在屏幕上画东西用的。这个是给程序从 shell 中指向东西用的，还带退出码。在写一行代码之前检查了二十六个工具（研究）。没有一个能做到这一点。

它是 AI 吗？ 不是。它是你 AI 技术栈中最不智能的部分，并为此感到自豪。

我们如何知道它能工作

87 项自动化测试：几何、放置、关节平滑度、黄金图像、录制的窗口服务器、Accessibility 和 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 中重新加载按钮在哪里”的新智能体通过标签找到了它，并构建了正确的命令（记录）。它还发现了一个 bug，现在已成为一项测试。

面向智能体（以及配置它们的人类）

skill/big-arrow/ 中的技能同时适用于 Claude Code 和 Codex（一个 SKILL.md，Agent Skills 格式，外加用于 Codex 的 agents/openai.yaml）。它告诉智能体何时指向、如何选择目标、在标牌上写一个完整的句子、在你可能没看的时候添加 --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。

先前技术与致谢

Peter Steinberger 的 Peekaboo 可视化器（https://github.com/openclaw/Peekaboo）和 Nameplate（https://github.com/steipete/Nameplate）展示了覆盖窗口配方和智能体技能打包。两者都没有绘制带标签的指向箭头，而这正是本项目填补的空白。bigarrow 将 Peekaboo 的 see --json 读取为可选目标来源。

许可证

MIT。请负责任地指向。

来源：Hacker News：AI 热帖 · github.com