big-arrow

big-arrow

bigarrow 会绘制一支带有标牌、可点击穿透的箭头，无需权限，也不会抢占焦点。直接指向目标本身；终端里的一行文字很容易被忽略。

需要 bigarrow 0.5.1 或更高版本。如果 bigarrow --version 显示的是较旧版本，请先运行 brew upgrade franzenzenhofer/tap/bigarrow：旧版二进制没有 card，并且会将 {{value}} 当作纯文本显示。

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
bigarrow start --element "Ghostty" --app "System Settings" --text "Franz, switch this on: Ghostty may record your screen" --say
# watch for the result (page changed, job continued, file appeared), then:
bigarrow stop

规则

• 自己打开确切的窗格或 URL，然后指向留给用户操作的那个控件。不要引导用户逐层打开菜单。由用户点击；你负责指引。
• 标牌上要用一个完整句子说明操作（“Franz，请点击 Save”，绝不要只说“这里”）。如果点击会批准、授权、付款、签名、发送或删除内容，还要说明后果：“Franz，请点击 Pay：支付 49 EUR 给 Hetzner”。由用户做决定；相关事实要写在标牌上，不能只显示在终端里。
• 用户可能没在看时，使用 --say。有时限的操作（代码即将过期、页面即将超时、任务正在等待）：使用 --color red --say，并说明截止时间：“Franz，请立即输入 2FA 代码，该代码将在 60 秒后过期”。
• 需要粘贴的内容（你不能代为运行的命令、URL、代码）：将其作为 {{value}} 放在标牌上。用户会看到值旁边的复制按钮（不带花括号）；点击一次即可复制全部内容，箭头会继续显示。指明粘贴位置：“Franz，请复制 {{sudo xcodebuild -license accept}} 并粘贴到这里”，然后确认内容已粘贴。
• 每个步骤只显示一支箭头；步骤完成后立即运行 bigarrow stop。箭头也会自动消失：300 秒后、会话退出时，或用户作答时（见下方的钩子）。
• 点击标牌或箭杆（复制按钮除外）会移除箭头（点击目标会穿透）。箭头被移除，表示用户已看到它：检查结果，不要重新绘制。除非用户要求，否则不要使用 --close-button。

卡片：值、机密信息、回答

只需粘贴一个值：在标牌上使用 {{value}} 标签。需要粘贴两个或更多值、包含机密信息，或提出问题时：使用提示卡，这是一种带有复制按钮且不会抢占焦点的浮动窗口。

bigarrow card --title "Franz, log in to Hetzner" --app "Google Chrome" --field "[email protected]" \
  --secret "Password=keychain:hetzner/franz" --link https://console.hetzner.cloud --button "done=I'm in"
bigarrow wait          # blocks until an answer: {"result":"button","value":"done","copied":["User","Password"],...}

• 绝不要在命令行中放置机密信息（ps 会将其显示给所有人）：--secret 接受以下来源：pass:、keychain:<service>/<account>、op:、env:、file:，也可以通过标准输入传入 JSON 卡片中的值。机密信息会显示为圆点，复制时会隐藏，并在 30 秒后从剪贴板中清除。
• --ask "Question?"（键入回答）、--choice id=Label（2 到 6 个选项）、--button id=Label。wait 在用户作答时以 0 退出；用户未作答就关闭卡片时以 1 退出：此时请在终端中询问。
• 含问题的卡片会在所有问题都得到回答后自动关闭（--keep 会让卡片保持显示，直到用户点击 X）；回答中的 answers 包含所有问题的答案。只有值的卡片会一直显示，直到用户点击 X。卡片会在你的会话和提示词钩子结束后继续显示；不再需要时，请自行关闭：运行 bigarrow stop --pid <pid> 或 bigarrow stop --cards。
• 卡片中的行可以用于指引：在 JSON 卡片中，"point": {"element": "Password"} 会将箭头指向该值的输入位置；用户复制下一个值时，箭头会随之移动。start ... --card card.json 会同时显示箭头和卡片。行类型和 JSON 格式见：reference.md。

目标

已知信息	使用方式
原生应用或 Electron 应用中的标签	--element "Allow" --app "System Settings"
应用或其某个窗口	--window "Safari" / --window "Safari:Inbox"
Chrome 标签页中的某个位置	--rect x,y,w,h --app "Google Chrome:<tab title>"
截图中的某个位置	--at X,Y --app "<App>"

在应用内指定目标时，始终传入 --app（或 --window）：它会先被置于前台，其他应用覆盖它时箭头会隐藏。App:title 会匹配窗口标题；如果没有匹配项，则匹配标签页。坐标是相对于屏幕左上角的全局坐标。在 Chrome 页面中使用 --element，需要以 --force-renderer-accessibility 参数启动 Chrome；否则，请将 getBoundingClientRect() 的结果转换为 --rect（见 reference.md）。不确定时？运行 bigarrow elements --app X --match "allow" 或 --dry-run。

错误

输入错误时退出码为 2，未找到目标时退出码为 3（消息会列出已存在的目标），缺少权限时退出码为 4：运行 bigarrow doctor。辅助功能（--element、App:title、--until-click）和屏幕录制（--window App:title）权限属于运行你的 shell 的应用（Terminal、Ghostty、VS Code），而不是 bigarrow。打开错误消息中指出的面板（macOS 27 中，辅助功能位于“设备控制和数据访问”），并切换该应用的开关。

更多内容（面板 ID、外观和计时标志）：reference.md。

设置一次

~/.claude/settings.json："hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "bigarrow stop --hook"}]}]}