Show HN: Let your AI agents paint big arrows, boxes and text on your screen

Hacker News Best

Hacker News Best2026年10月9日

Show HN: Let your AI agents paint big arrows, boxes and text on your screen

6.9内容质量

TL;DR · AI 摘要

GitHub - franzenzenhofer/big-arrow-on-the-screen: Let your AI agents paint big arrows, boxes and text on your Mac screen...

核心要点

主题聚焦：Show HN: Let your AI agents paint big arrows, bo
来源：Hacker News Best，建议结合原文判断细节。
AI 分析暂不可用，本条为保底评分与摘要。

#AI#编程#后端#安全#产品

打开原文

GitHub - franzenzenhofer/big-arrow-on-the-screen: 让你的AI代理在Mac屏幕上绘制大箭头、方框和文本。一个CLI工具，点击穿透，自动消失。适用于Claude Code和Codex。MIT许可证 · GitHub

让你的AI代理在屏幕上绘制大箭头、方框和文本

big-arrow-on-the-screen（bigarrow）是一个macOS命令行工具，也是Claude Code和Codex的技能插件，它能在每个窗口上方绘制箭头和提示信息。点击操作会穿透到下方的应用程序，键盘焦点保持不变，箭头会自动消失。采用MIT许可证。

你的AI代理可以重构单体仓库、编写迁移脚本并解释单子，但当它需要你点击一个按钮时，它会在你未关注的终端中打印"请在对话框中点击允许"。bigarrow为它提供了"手指"。

code

bigarrow point --element
"
Allow
"
--app
"
System Settings
"
--text
"
Franz, click Allow: Ghostty may control your Mac
"

箭头存在于所有其他窗口之上的透明窗口中，覆盖所有显示器和所有Space空间。对目标的点击操作会传递到下方的应用程序，绘制过程完全不需要macOS权限。它只是一个Swift二进制文件：没有守护进程、没有菜单栏图标、不需要账户、不收集任何数据，我们确认过两次，内部也没有AI。它只是一个箭头。

这到底有什么实际用途？

合理的问题。箭头自旧石器时代就已存在。变化在于：如今软件代理可以在你的Mac上执行真实任务，最终总会遇到必须由人类完成的步骤，或者人类希望学习完成的步骤。

"点击允许。" macOS权限提示、OAuth授权界面、"使用...?"对话框。代理可以找到按钮但不能/不应该为你点击。现在它可以指向这个按钮。

"轮到你了。" 二次验证码、验证码、通行密钥、支付确认、签名、法律复选框。这些是代理绝不能自行点击的项目。它指向目标，由你决定，然后继续执行。

"是这个窗口，不是那个。" 你有14个Chrome窗口。代理知道具体是哪一个：--window "Google Chrome:Pull request"。它甚至能选择正确的标签页：--app "Google Chrome:Pull request"。

"我需要你，而你正在煮咖啡。" --say会朗读提示信息。你的Mac会真的打电话叫你回办公桌。

"展示给我看。" 向代理询问如何在Keynote、Blender或系统设置中执行某个操作，它会依次指向每个控件而不是进行描述：开始，等待你操作，停止，下一步。就像产品导览，但没有产品本身。完整示例：如何在Mac上允许屏幕录制，每张截图都是代理绘制的箭头。

协助他人。安装到父母的Mac上，那里的代理可以指导他们如何将文档另存为PDF。指向比"顶部的按钮，不对，另一个顶部"更有效。

远程协助。"不是那个网格图标。" 直接指向它而不是描述。

演示、屏幕录像、文档。在录制时突出重点，或通过--png参数直接将箭头渲染到PNG中用于文档。

调试坐标。不确定你的辅助功能、截图或Peekaboo坐标是否正确？指向它们并查看。--dry-run --json会告诉你它将指向的位置而无需实际绘制。

它不是：人类用的屏幕标注工具、自动点击机器人或截图工具。它从不点击、输入或捕获任何内容。它只指向。这是刻意为之的设计。

这次没有虚假的对话框。测试用的 Mac（macOS 27）上运行的是真实的应用程序，使用中立的演示内容，全新的浏览器配置文件，以及由脚本 scripts/real-scenes.sh 演示的真正的 bigarrow。以下每条命令都完全按照实际运行的命令执行；脚本仅添加了 --no-animation --json 用于截图。

code

open
"
x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility
"
bigarrow start --element Terminal_Toggle --app
"
System Settings
"
\
  --text
"
Franz, switch this on: Terminal may control your Mac
"
--from right

引导用户完成权限设置：深度链接直接打开精确的面板，箭头定位到唯一的开关，提示文字说明其作用。（在 macOS 27 上，该面板称为“设备控制与数据访问”。没有人会通过旧名称找到它。）

code

bigarrow start --element Animate --app Keynote --role radiobutton --text
"
1. Click Animate
"
--from right
bigarrow start --element
"
Add an Effect
"
--app Keynote --text
"
2. Add an Effect
"
--from right

指导应用程序使用：“在哪里添加转场？”两个编号步骤，同时显示在屏幕上的工具栏中，该工具栏已放弃使用文字。

code

bigarrow start --element PDF --role button --app TextEdit \
  --text
"
Mom, click PDF, then Save as PDF
"
--from bottom

通过屏幕共享帮助家长，无需花费二十分钟解释“那个小按钮，在左下角，不，左边”。

code

bigarrow start --app
"
Google Chrome:Sourdough
"
--element
"
Sourdough - Wikipedia
"
--role radiobutton \
  --text
"
It's this tab, not the other 13
"
--from top

--app "App:tab title" 会将正确的窗口置于前台并选择标签页，然后再指向它。代理知道它指的是哪个标签页，现在你也可以。

code

bigarrow start --element Group --role menubutton --app Finder \
  --text
"
No, the other grid icon. This one.
"
--from top

远程协助，更新至 macOS 27：齿轮图标已消失，但现在有两个网格图标，且总是另一个图标。

这不是一个玩笑应用：《如何在 Mac 上允许屏幕录制》，一份真实且逐步指导的教程，其中每张截图都是代理使用 bigarrow 绘制的箭头。

安装

code

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。该二进制文件仅适用于 Swift；scripts/ 中的 shell 和 Python 文件用于记录截图和运行测试。

代理需要的三个命令

code

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

每个箭头都会自行结束。不需要清理代理忘记的箭头：

时间限制

code

bigarrow point ... --duration 10

（默认 8 秒；

code

start

300 秒；

code

--duration 0

= 无限制）

启动和停止

code

bigarrow start ...

立即返回；

code

bigarrow stop

（或

code

stop --all

）会移除它

代理离开时

箭头会在绘制它的代理进程退出时结束（

code

CLAUDE_PID

，或

code

BIGARROW_OWNER_PID

）

用户回答时

code

bigarrow stop --hook

作为 Claude Code

code

UserPromptSubmit

钩子会清除该会话的箭头

用户关闭时

code

--close-button

会在提示信息上添加一个可点击的 X（需用户同意）

Targets: --at X,Y , --rect X,Y,W,H , --mouse , --window App[:title] , --element Label --app App , --peekaboo ID --snapshot see.json (from Peekaboo's see --json ). Coordinates are global top-left logical points, the space Accessibility, CGWindowList and Peekaboo report. --display N makes --at and --rect relative to one display.

箭头会绑定到它指向的应用程序。使用 --app App[:window or tab title]（或 --window ）时，bigarrow 会首先将该应用程序、窗口或 Chrome/Safari 标签页带到前台，因为指向终端后方隐藏的窗口是一种特殊类型的无用操作。如果后续有其他应用程序覆盖了目标，箭头会隐藏，直到目标再次可见。--no-raise 会保持窗口原位不动。bigarrow 元素 --app X 列出 --element 可以匹配的内容。bigarrow doctor 显示权限、权限所有者以及你的显示器信息。

每个命令都支持 --json 参数。退出代码：0 表示成功，2 表示输入错误，3 表示目标未找到，4 表示权限缺失。代理程序喜爱退出代码。人类则能容忍它们。

外观

它是一支箭头，因此我们在它的外观上投入了不合理多的时间。

在干净的测试机器上拍摄的真实截图，六种外观分别显示在白色、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，以及针对 X 的 --close-color 和 --close-x-color。未指定时，系统会自动选择可读的颜色

--close-button 在标志右侧末端添加一个 X（白色圆圈，X 为箭头颜色），且永远不会覆盖文本或超出屏幕范围

--follow 随窗口或元素移动，--until-click 在目标上点击后结束，--say 会朗读标志内容

多个箭头同时显示时，它们的标志会相互避让

箭杆通过一个扩张的关节从标志延伸出来，这个关节永远不会碰到圆角。scripts/gallery.py 会将所有组合在屏幕外渲染，并放大显示每个关节（连接点），因为关节处的缝隙显然不可接受。

创意箭头

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

--color green

--shape zigzag --color orange：zigzag，用于真正紧急的情况

--shape spiral：绕标志一圈后指向按钮

--color purple

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

三个启动项，一个按钮，零歧义

--style box --corners sharp，加上关于 macOS 权限的教训

常见问题

是否需要屏幕录制或辅助功能？绘图不需要任何权限。但某些定位目标的方式需要：

你使用

权限

code

--at

,

code

--rect

code

--mouse

code

--window App

code

--peekaboo

code

--app App

无权限需求

code

--element

code

elements

code

--until-click

code

--app App:title

（提升窗口或选择标签页）

辅助功能

code

--window App:title

(macOS 26 隐藏窗口标题)

屏幕录制功能，加上辅助功能权限以提升窗口（不使用

code

--no-raise

macOS 将这些权限授予启动 bigarrow 的应用程序（即你的终端或 IDE，如 Terminal、iTerm2、Ghostty、VS Code、Claude），而非 bigarrow 本身。因此你需要在系统设置中启用对应的应用程序。bigarrow doctor 会告诉你具体是哪个应用程序，并在缺少权限时以代码 4 退出，同时指出应用程序名称和设置面板。

它从不会夺取焦点。为何能显示在最前？在 macOS 中，位于顶层和拥有键盘焦点是两回事。箭头窗口处于屏幕保护程序窗口层级，位于普通窗口、对话框和全屏应用之上，但永远不会成为活动窗口，因此你输入的内容会继续保留在原处。使用 --app 参数时，目标应用程序会先被置于前台。

在输入时会夺取我的焦点吗？不会。这是项目中最难修复的 bug：NSApplication.run() 会静默激活一个没有终端的进程，导致分离的箭头夺取焦点。bigarrow 会自行处理事件，测试也验证了前台应用程序永远不会改变。

能点击穿透吗？可以，除了箭头标志和箭身部分：点击这些区域会移除箭头（箭头会在指针下略微变暗以示提示）。点击目标或箭头头部附近区域会直接穿透到应用程序。点击箭头本身永远不会夺取焦点。

多显示器？全屏应用？舞台管理器？空间？都可以。主显示器左侧或上方的显示器（负坐标）也支持。当箭头显示在某个显示器上时拔掉该显示器，箭头会礼貌地离开。详见验证矩阵。

脉动箭头会消耗多少 CPU？在 CI 运行器上实测为 1.4%。Core Animation 在渲染服务器中完成相关工作。

--element 参数能在网页内部使用吗？在 Electron 应用中可以。在 Chrome 中，仅当 Chrome 使用 --force-renderer-accessibility 参数运行（或启用了 VoiceOver）时有效；Chrome 会忽略常规的页面内容暴露请求（2026 年 10 月测试确认）。Chrome 自带的工具栏始终有效。否则请指向页面坐标，相关技巧已说明。

代理能否利用此功能欺骗用户，例如覆盖“拒绝”按钮？理论上可以覆盖按钮，但能运行 shell 命令的代理已经可以读取你的文件并运行任意程序，因此 bigarrow 并未提供新功能。bigarrow 本身保证的特性（每项均通过测试验证）：框线和环线均为轮廓，确保目标始终可见；标志始终与目标保持清晰距离，若空间不足（目标占据大部分屏幕时），则尽可能少地覆盖目标；点击标志或箭身会移除箭头；所有箭头最终都会自行消失。它从不会点击、输入或捕获任何内容。当代理要求你批准操作时，技能会提示标志上显示点击操作的具体内容，让你在掌握事实的情况下做出决定。

为何使用技能？这会消耗很多 token 吗？代理始终只能看到技能描述（约 190 个 token）。完整的指令（约 2,200 个 token，使用 Anthropic 的 token-count API 对 Claude Opus 5.5 计数）仅在代理决定指向时加载。这些指令教授代理何时指向、如何定位目标以及在标志上写什么内容。你也可以跳过技能，直接调用 bigarrow。

code


为什么不用一些屏幕标注应用？那些是给人用来在屏幕上绘制的。这个是给程序用来从shell中指向事物并使用退出码的。在写第一行代码前检查了26个工具（研究）。没有一个能做到这一点。

这是AI吗？不是。它是你AI堆栈中最不智能的部分，而且为此感到自豪。

## 我们知道它有效的原因

- 91个自动化测试：几何形状、位置、连接平滑度、黄金图像、录制的窗口服务器、Accessibility和Peekaboo 4.9.0测试用例，以及对真实窗口服务器的测试（窗口层级1000、点击穿透、焦点永不移动、分离和停止计时）。CI在macOS 15上运行这些测试；它们也在macOS 26和macOS 27上通过。

- 在干净的运行器（visual.yml）上进行了17项行为检查：在X上真实点击、--until-click、--follow、提升（和--no-raise）、覆盖时隐藏、选择Chrome标签页、以所有者进程结束、停止--hook、--say、全屏应用、Stage Manager、空间切换、第二个显示器、2x显示器、箭头过程中拔掉显示器、CPU。上方的演示GIF由同一工作流程录制，运行环境是没有任何个人内容的桌面。

- 仅给一个新代理提供技能和"告诉Franz在Chrome中找到重新加载按钮的位置"指令时，它通过标签找到了目标并构建了正确的命令（转录文本）。它还发现了一个漏洞，现在这个漏洞已成为一个测试。

## 对于代理（以及配置它们的人类）

skill/big-arrow/中的技能同时适用于Claude Code和Codex（一个SKILL.md，代理技能格式，以及agents/openai.yaml用于Codex）。它告诉代理何时指向、如何选择目标、在提示牌上写完整句子、在你可能没看的时候添加--say，并在执行完毕后停止。

## 计划、决策、研究

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。负责任地使用指针。