big-arrow(命令名 bigarrow)是一个 macOS 屏幕指引工具:在人类用户的屏幕上绘制带标牌的大箭头,指向需要点击或操作的界面元素,并可通过浮动卡片交接待粘贴的值、密钥与问题。它面向“程序负责定位、人类负责决定”的协作场景,例如在设置页面指向唯一需要打开的开关,或在终端外展示需要人工粘贴的命令与验证码。
主要能力
- 箭头指引:用大箭头和一句话标牌指向目标控件,标牌需写明具体动作(如“点击保存”),涉及支付、授权、签署、发送、删除时应在标牌上写明后果。
- 目标定位:支持按原生/Electron 应用中的标签(--element --app)、应用或窗口(--window)、Chrome 标签页内矩形区域(--rect)、截图坐标(--at)定位;指向应用内目标时应同时传 --app 或 --window,应用被其他窗口遮挡时箭头会隐藏。
- 提醒与时效:--say 用于用户可能未看屏幕时;时间紧迫场景配合 --color red 并在标牌上写明截止时间。
- 值交接:单个待粘贴值以 {{value}} 形式出现在标牌上,附带复制按钮;两个及以上值、密钥或问题时使用浮动卡片,卡片不抢焦点,含复制按钮。
- 密钥处理:--secret 接受来源而非明文(pass:、keychain:<service>/<account>、op:、env:、file:),也可通过 stdin 传入 JSON 卡片;密钥显示为圆点,复制为隐藏内容,30 秒后从剪贴板移除。
- 问题与回答:--ask 支持输入回答,--choice 提供 2 至 6 个选项,--button 提供按钮;bigarrow wait 阻塞直到获得回答,并以 JSON 输出结果、已复制字段等;用户关闭卡片未回答时退出码为 1。
- 生命周期:每步一个箭头,完成后执行 bigarrow stop;箭头也会在 300 秒后、会话退出或用户回答时自动结束;点击标牌或箭杆(复制按钮除外)会移除箭头,此时应检查结果而非重绘。
使用方式 先确认 bigarrow 版本不低于 0.5.1,旧版本需先升级。典型流程是:自行打开目标设置面板或 URL,用 bigarrow start 指向剩余的那一个控件,等待结果(页面变化、任务继续、文件出现),再执行 bigarrow stop。卡片示例使用 card 子命令指定标题、应用、字段、密钥、链接与按钮,随后用 wait 获取回答。需要粘贴但不应由程序执行的命令或 URL 可放在标牌上作为 {{value}}。
权限与错误 辅助功能(--element、App:title、--until-click)与屏幕录制(--window App:title)权限属于运行 shell 的应用(Terminal、Ghostty、VS Code),而非 bigarrow;权限缺失时退出码为 4,可运行 bigarrow doctor 诊断,并按错误信息打开对应设置面板。退出码 2 表示输入有误,3 表示目标未找到(错误信息会列出存在的目标)。在 Chrome 页面内使用 --element 需要 Chrome 以 --force-renderer-accessibility 启动,否则需将 getBoundingClientRect() 转换为 --rect。
适用场景与限制 适合 macOS 上需要人类确认、授权、输入验证码或粘贴命令的交互环节,以及把多值/密钥/问题集中到不抢焦点的浮动卡片中交接。限制包括:仅面向 macOS;依赖系统辅助功能与屏幕录制权限;需 bigarrow 0.5.1 及以上;密钥不应出现在命令行参数中;卡片在仅有值时会持续显示,需要自行关闭。更多面板 ID、外观与时序参数见项目 reference.md。