bigarrow CLI：macOS AI 代理的视觉引导工具

TL;DR – bigarrow 的功能及其重要性

bigarrow 是一个单二进制文件的 macOS 命令行工具，它可以在任何窗口或屏幕坐标上方绘制可穿透点击的箭头、方框以及可选的文本，并能自动消失。它在绘制时不需要屏幕录制或辅助功能权限，支持多显示器、多桌面（Spaces）和全屏应用，并能返回精确的退出代码，以便 AI 代理可靠地发出成功或失败的信号。通过让代理能够“指向”而非“点击”，bigarrow 弥补了许多自动化工作流中仅靠人类操作的最后一步。

核心功能 – 代理所需的三个命令

结论： 代理只需三个简单的命令即可实现指向、追踪和清除箭头。

命令	用途	示例
`bigarrow point`	绘制一个指向 UI 元素（通过标签）或屏幕坐标的箭头，可选择添加标题。	`bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"`
`bigarrow start` / `bigarrow stop`	保持箭头可见，直到代理明确停止或超时。	`bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop`
`bigarrow point --at X,Y`	当无法进行基于标签的定位时（例如非辅助功能支持的网页），指定原始坐标。	`bigarrow point --at 760,500 --text "Franz, click HERE"`

所有命令都接受 --duration、--json 输出以及全套样式标志（形状、颜色、大小等）。退出代码是确定性的：0 表示成功，2 表示输入错误，3 表示未找到目标，4 表示缺少权限。

为什么要“指向”而不是“点击”？

结论： 指向操作尊重用户的主体性，避免了安全隐患，同时又能引导人类操作。

权限对话框 – macOS 提示（如“允许”）可以在不让代理执行点击的情况下被高亮显示。
敏感操作 – 双重验证（2FA）、验证码、支付确认、法律复选框等仍由人类控制。
窗口消歧 – 当打开多个 Chrome 窗口时，--window "Google Chrome:Pull request" 会选择正确的标签页，然后进行指向。
音频提示 – --say 会大声朗读标题，将用户的注意力拉回桌面。
远程协助 – 代理可以直接指向目标，而不是描述“那个齿轮图标”。
文档记录 – --png 将箭头渲染为 PNG 图片，用于静态文档或截屏录制。
调试 – --dry-run --json 会报告计算出的目标而不进行绘制，这对于坐标验证非常有用。

该工具刻意不进行点击、输入或截屏；它纯粹是一个视觉提示工具。

安装与集成

结论： bigarrow 可以通过 Homebrew 安装或从源码构建，并包含现成的 Claude Code / Codex 技能。

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。

样式选项 – 让箭头更醒目

结论： 丰富的视觉参数设置确保箭头在任何背景下都清晰可见。

形状： bend（弯曲）、straight（直线）、zigzag（紧急）、spiral（循环一次）。
样式： arrow（默认）、ring（环形）、box（仅边框）。
大小： S、M、L。
边角： round（圆角）或 sharp（直角）。
颜色： 命名调色板（red、orange 等）或自定义 #RRGGBB。
边框： shadow（默认）、white-black、black。
关闭按钮： --close-button 添加一个 X，点击即可移除箭头。
动态行为： --follow 追踪移动窗口，--until-click 在点击后结束，--say 触发语音合成。

该项目包含一个画廊脚本，可以在屏幕外渲染每种组合，并放大箭头杆与标志连接的接合处，确保视觉外观的无缝衔接。

权限模型 – 为什么不需要屏幕录制？

结论： 绘制过程使用了一个透明的覆盖窗口，macOS 允许这样做而无需额外授权；只有目标发现功能才需要辅助功能权限。

绘制 – 不需要屏幕录制或辅助功能权限。
目标查找 – --element、elements、--until-click 和 --window 依赖于辅助功能，macOS 将此权限授予 shell 进程（Terminal、iTerm、VS Code、Claude）而不是 bigarrow 本身。
bigarrow doctor – 报告哪个应用拥有必要的权限，如果缺少权限则以代码 4 退出。

这种设计防止了工具在后台静默捕获屏幕内容，同时仍能实现精确的 UI 元素识别。

macOS 环境下的稳健性

结论： 该箭头适用于多显示器、全屏应用、台前调度（Stage Manager）和多桌面，并能优雅地处理显示器断开连接的情况。

支持主屏幕左侧/上方的负坐标显示器。
在箭头存在时拔掉显示器，箭头会自动消失。
已通过 CI 在 macOS 15、26 和 27 上验证。
CPU 占用极低 – 在 CI 运行器上约为 1.4%，由 Core Animation 处理渲染。

作者强调的实际应用场景

结论： bigarrow 解决了 AI 增强工作流中的具体痛点。

权限提示 – 代理无法点击的“允许”对话框。
2FA / 验证码 – 代理指向，人类确认。
窗口选择 – 在数十个 Chrome 窗口中消除歧义。
引导式入门 – 带有开始/停止语义的分步导览。
远程帮助 – 为同事指向正确的 UI 元素。
文档记录 – 自动生成带注释的截图。
坐标调试 – 对辅助功能或 Peekaboo 坐标进行视觉确认。

社区反馈 – 热门评论总结

结论： 用户认可该概念，但对安全性、可用性和更广泛的适用性提出了担忧。

“我试着读了‘它需要屏幕录制或辅助功能吗？’那部分，但写得有点草率……有什么能阻止它画一个方框来遮挡‘拒绝’按钮吗？” – @hn8726（澄清：绘制永远不会遮挡 UI 元素；只有标志本身是可点击的。）

“箭头解决了‘我该点哪里’的问题，但没解决‘我该不该点’的问题。它可能会削弱人类的决策作用。” – @tilemarch（强调了伦理界限；该工具刻意在自动化点击之前停下。）

“这对于通过电话帮助我妈妈下载和打印文档非常有用。” – @arshxyz（提出了一个非代理的远程协助用例。）

“如果有一个 iPad 版本能启动正确的应用并引导用户完成银行转账，我愿意花钱购买。” – @lbreakjai（表明了对跨平台 UI 助手工具的需求。）

“README 是面向技术人员的；更简单的 UI 可以扩大采用范围。” – @usrbinbash（指出了文档的可访问性问题。）

总的来说，社区看到了视觉引导的价值，但强调需要明确界限以维护用户同意。

测试覆盖率与可靠性

结论： 广泛的自动化测试验证了几何结构、渲染和交互行为。

87 个单元测试，涵盖几何结构、接合平滑度、黄金图像对比以及与辅助功能和 Peekaboo 固定装置的集成。
17 个视觉行为检查，在真实的 macOS 窗口服务器上进行 CI 测试：可穿透点击、焦点保持、多显示器处理、CPU 使用率等。
代理技能测试 – 一个全新的 Claude Code 代理仅使用该技能成功定位了 Chrome 的“重新加载”按钮，并暴露了一个被添加为回归测试的错误。

局限性与待解决问题

结论： bigarrow 不是通用的屏幕标注工具，也不能替代 UI 自动化。

它不能点击、输入或截屏。
网页元素定位仅在以 --force-renderer-accessibility 启动或启用 VoiceOver 的 Electron 应用和 Chrome 中有效。
该工具依赖辅助功能进行基于标签的定位；如果没有辅助功能，必须手动提供坐标。
暂不支持 iOS/iPadOS – 评论显示社区对此有兴趣。

仓库暗示的未来方向

结论： 作者计划扩展文档、完善技能格式并探索额外的视觉提示。

详细的 PLAN.md、DECISIONS/ 和 RESEARCH/ 目录概述了架构和风险评估。
先前的工作包括 Peekaboo 可视化工具和 Nameplate；bigarrow 填补了“箭头+标签”覆盖层的空白。
潜在的扩展包括更丰富的动画、多代理协调或跨平台移植。

总结

bigarrow 为 AI 代理提供了一种轻量级、无需权限的方式，在 macOS 上向用户“指向” UI 元素，将模糊的“点击此按钮”提示转化为清晰的视觉线索，同时保留了用户的主体性和系统安全性。其极小的占用空间、稳健的测试和灵活的样式使其成为任何代理驱动工作流的实用补充。