【2026 最新】bigarrow 教學：讓 Claude Code 在 Mac 指位置，六步建立可驗證人機交接

你請 Claude Code 幫忙設定工具，終端機跳出一句「請到那個視窗按一下」。桌面上有三個視窗，哪一個才是它說的？這篇 bigarrow 教學，帶你把文字指示變成短暫的螢幕箭頭，同時保留自己核對視窗與操作內容的時間。

本文專為第一次接觸命令列的 Mac 使用者寫：先畫一個不涉及批准的座標標記，再接到 Claude Code 的人工交接流程。你會學會設定目標、原因、期限與清除方式，最後用四個情境驗收；不需要先懂 Agent 架構。

截至 2026 年 10 月 12 日，本文固定採用 bigarrow v0.4.5 穩定版，不混用開發分支新增的操作。這次環境未安裝 bigarrow，也沒有可完成原始視窗核對的人機測試工作階段；以下提供依官方程式與文件整理的上手及驗收方法，不填入本機錯位率或測試成績。

先說結論：bigarrow 教學先記住這個等式

可靠交接＝標記位置＋說明目的＋限時清除＋人在原始介面核對。 箭頭像朋友站在旁邊伸手指路：它能幫你找到方向，批准的依據仍然是你看清楚的原始視窗。

• 第一步只在空白區畫五秒箭頭，先確認自己會清除。
• 找按鈕之前，先用 doctor 確認螢幕與權限對象。
• 標記移動了、文字怪了、目標找不到了，就結束這次交接，重新定位。

一、bigarrow 是什麼？給 Agent 一根指路的手指

big-arrow-on-the-screen 是工具的完整名稱，bigarrow 是你在終端機輸入的指令。它在 macOS 視窗上方畫出箭頭、外框或圈選，把「這裡」變成看得見的位置。命令列就是用一行文字叫軟體做事；Agent 則是能選擇工具、執行步驟的 AI 工作程式。

它適合教別人找功能、指出需要人工確認的欄位，或讓 Agent 在卡住時交回控制權。這裡把它放在 Agent Harness 的工具層：模型提出交接需求，執行層畫標記，人在原始介面決定下一步。

要分清兩件事：畫在最上面，與取得鍵盤焦點，是不同的行為。 另外，使用 --app 或 --window 定位時，工具可能先把目標程式帶到前景；因此「箭頭本身不搶焦點」不等於整條指令完全不改變前景視窗。這個差別由 官方執行流程 與 --no-raise 選項界定。

二、bigarrow 教學起步：三個指令畫出第一個短暫標記

準備一台 macOS 14 或更新版本的 Mac，以及已安裝的 Homebrew（Mac 常用的套件管理工具）。目前作者的 Formula 會從原始碼編譯，還需要 Xcode 16 或更新版本；單有 Homebrew 不保證編譯環境已備妥。還沒有 Homebrew 的人，可先依 Homebrew 官方安裝說明 完成安裝，再回到這一步。打開「終端機」，逐行貼上，不要一次把批准操作也交給 AI。

brew install franzenzenhofer/tap/bigarrow

bigarrow doctor --json

bigarrow point --at 400,300 --text "練習：這裡只是座標標記" --duration 5 --json

安裝入口來自 作者的 Homebrew Formula。先讀 doctor 的版本；本文對照的是 v0.4.5。如果你安裝到其他版本，先用 bigarrow point --help 與對應版本文件核對旗標，再沿用這份流程。

第三行把箭尖放在 400,300，不是找「400 號按鈕」。這是從全域左上角計算的邏輯點，不是 Retina 截圖的實體像素；若該座標不在你的螢幕範圍，請依 doctor 的顯示器範圍選一個內部位置。

這一步只看三件事：你是否看到指向預期位置的標記、標記是否約五秒後消失、終端機是否回傳成功。--json 讓輸出便於保存；成功回傳代表指令完成，不代表你已批准任何操作。要提早清除，另開一個終端機分頁執行下面這行。

bigarrow stop --all --json

point 在前景等到結束；start 讓標記在背景顯示並立即回傳。依 穩定版參數定義，一般 point 預設八秒，start 預設三百秒；帶 --close-button 或 --until-click 時也會採用較長的等待預設。本文每次都明寫 --duration。 --duration 0 表示取消時間上限，練習不用它。

三、定位與權限：先找對象，再決定要不要開門

想像朋友指路的三種說法：「桌面右邊那個位置」、「文字編輯那個視窗」、「標成儲存的按鈕」。越接近真正的控制項，越需要軟體讀取介面資訊。Accessibility（輔助使用權限）是 macOS 允許程式透過輔助介面讀取或控制應用程式的授權，與畫一個箭頭不同。

① 固定座標：拿著一張位置地圖

--at X,Y 與 --rect X,Y,W,H 可直接指定位置或矩形；本文的座標畫圖本身不要求 Accessibility 或螢幕錄製權限。缺點是地圖不會自動理解按鈕：視窗移動之後，同一座標可能指到另一個地方。不要把舊截圖像素直接當新螢幕座標。

② 應用程式視窗：先找那一扇窗

bigarrow start --window TextEdit --style box --text "練習：核對這個文字編輯視窗" --duration 10 --follow --json

先自己打開「文字編輯」並新增一份空白文件。這行用應用程式名稱定位，指向所選視窗的中心；--style box 在這個點附近畫框，不是替整個視窗畫完整邊框。--follow 要求重新解析可移動的視窗目標。若同時開了多份文件，不能光憑程式名稱就斷定它找到了你心中的那一份。

若加上標題，例如 --window "TextEdit:練習交接"，穩定版的視窗標題查找會要求螢幕錄製權限；把指定視窗帶到前景另涉及 Accessibility，--no-raise 則略過帶到前景。先核對 視窗解析規則，不要為了省事一次開滿權限。

③ Accessibility 元素：叫出控制項的名字

bigarrow elements --app TextEdit --json

這行列出可匹配的介面元素，需要 Accessibility。從輸出找出你真的看得到的標籤，再替換下列指令中的 實際標籤；它是待替換文字，不是 macOS 的固定按鈕名稱。

bigarrow point --element "實際標籤" --app TextEdit --text "練習：先核對控制項用途" --duration 10 --dry-run --json

--dry-run 會解析目標並回報預計位置，略過畫圖與帶到前景；解析 Accessibility 元素仍需權限。請先自己把文字編輯視窗顯示出來。確認匹配正確才移除 --dry-run；同名按鈕很多時，要進一步指定 --role 或更精確的視窗範圍。

這三種路線依 穩定版目標定義 分工。本文從原生 Mac 應用程式開始，不把瀏覽器網頁內按鈕的可讀性當作必然；網頁、工具列、Electron 應用程式的輔助介面要各自驗證。

④ doctor 排查：確認誰拿到了權限

bigarrow doctor --require accessibility --json

--require 把權限缺失變成可檢查的錯誤。依 doctor 實作，你要找的是啟動 shell 的負責應用程式，例如 Terminal、iTerm2 或 VS Code，不是看到缺權限就盲找 bigarrow。tmux、SSH 或啟動鏈較複雜時，請連同輸出的父程序資訊核對。

需要授權時，先清除箭頭，自己開啟「系統設定 → 隱私權與安全性 → 輔助使用」，核對應用程式名稱再決定。Apple 的輔助使用說明 將授權視為允許應用程式存取及控制 Mac，並提供開關與加入程式的方法。螢幕相關權限則在 螢幕與系統音訊錄製設定；不要把兩個開关混為一談。

下面是作者在真正 Finder 應用程式中安排的官方示範：黑色圈選指向檢視方式，綠色外框指向群組功能。它示範標記的外觀，不是本文對你電腦的定位結果。

四、接到 Claude Code：建立一筆能核對的交接

先閱讀 這個版本隨附的 big-arrow Skill，再安裝給 Claude Code。Skill 是教 Agent 何時、如何使用工具的一份操作指南；這條路線由 shell 執行 bigarrow。

bigarrow install-skill --claude

Claude Code 的 官方 Skills 文件 說明，個人 Skill 位於 ~/.claude/skills，可跨專案載入。安裝後開始或重開 Claude Code 工作階段，確認它可讀到 big-arrow，並在終端機確認 bigarrow 在 PATH；Skill 檔案與可執行工具要同時存在。

第一次不要用付款、刪檔或權限批准練習。用文字編輯的空白文件，送出這段要求：

請用 big-arrow 做一次非破壞性人機交接。先找文字編輯視窗，回報目標、定位方式、原因與清除指令；解析失敗就停止。標記只顯示十秒，文字寫「請先核對這個空白文件」。等待我在原始視窗核對後明確回覆，不要自行點擊，也不要把標記消失當作完成。

把一次交接當成一張短期工單，至少留下五個欄位：目標身分、定位依據、操作後果、有效期限、清除方式。 例如「文字編輯／目前空白文件；視窗中心；只確認文件而不寫入；十秒；這次回傳的 PID」。需要只清除這一個標記，可用 bigarrow stop --pid 回傳的PID --json，把字樣換成 start 回傳的實際數字。

完整走一次：Agent 解析目標 → 保留命令與輸出 → 顯示十秒標記 → 人確認找到視窗 → 清除標記 → 人閱讀原始視窗 → 人回覆「已核對」或「取消」→ Agent 依回覆結束或重新定位。想了解如何把回覆接回執行層，可接著讀 從零建立 Agent Harness。

箭頭不是權限閘門。 在應用程式批准後續動作前，要另外驗證原始要求、實際範圍與人的明確決定；「收到回覆」「點了目標」「箭頭消失」是三個不同事件。語音 Agent 權限閘門 講的是批准與執行的關係，這篇處理的是批准之前如何找到並核對介面。

也保留 Claude Code 本身的工具批准流程。官方權限文件 區分工具規則與操作系統隔離，指令比對本身不是程式的安全邊界。初次練習逐次核對要執行的 shell 命令，不用「允許所有 Bash」來換取一支箭頭。

五、bigarrow 教學驗收：四個刻意弄壞的情境

以下是供你執行的驗收題。每題記錄「版本、命令、目標、預期、觀察、回傳碼、清除結果」；先在空白文件練習，別把官方測試或自己的猜測填成觀察。

① 移動視窗：座標跟的是地點，還是目標？

痛點：標記出現後把文字編輯視窗拖走。先用固定座標畫五秒標記，記錄箭尖與視窗是否分離；再用前述 --window TextEdit --follow 指令重做。驗收：記錄可移動目標有沒有被重新定位，以及舊位置是否留下標記；若視窗對不上，清除、重新解析，不准沿用舊座標。

② 多螢幕：左邊螢幕也可能有負座標

痛點：把第二台顯示器擺在主螢幕左側後，截圖位置與全域座標不一致。先跑 bigarrow doctor --json，記下顯示器編號與原點；再以 --display N --at X,Y 指定該顯示器內的邏輯點，將 N、X、Y 換成輸出可用的數字。驗收：在每台螢幕重做短期限標記，記錄出現在哪台、是否偏移、清除是否完成；不要拿第二台的一份結果代表所有排列。

③ 目標不存在：有錯誤比亂指更好

bigarrow point --element "ALPHALAB_NONEXISTENT_TARGET_7F31" --app TextEdit --text "這是失敗情境" --duration 5 --dry-run --json

痛點：Agent 猜了一個介面裡沒有的名稱。先確保文字編輯在前景且 Accessibility 已授權，再用一個未出現在元素列表中的測試名稱。驗收：目標解析失敗應回傳 3；缺權限可能先回傳 4，參數錯誤為 2。依 官方錯誤碼 分類問題，不能把所有失敗一律改用任意座標。

④ 誤導文字：看穿漂亮的指示牌

痛點：文字說「已批准」，其實原始視窗還在等待決定。在空白文件畫一個五秒座標標記，文字填「練習：這句話聲稱已批准，但沒有批准紀錄」，不搭配任何真實授權操作。驗收：你是否會先清除標記、看原始介面，再拒絕把這句話當批准？若交接程式光看牌子、標記消失或一次點擊就繼續執行，應修改狀態判斷。

Hacker News 的 原始討論 曾提出覆蓋層可能遮住拒絕按鈕或影響決定的疑問。這些是值得設計驗收的質疑，不是已量化的事故率。文章的作法很具體：敏感操作前，先移除覆蓋，再讀原始要求。

六、常見坑：穿透點擊不等於視覺透明

依 v0.4.5 的 命中區域實作，牌子與箭身有互動區，點它們會關閉標記；目標附近的點擊則可到達底下應用程式。這不能推出「拒絕按鈕永遠不會被視覺遮擋」。牌子的位置與畫面內容仍要一起看；出現重疊就清除，必要時重新選 --from 方向。

--until-click 可把目標點擊當作結束標記的條件，也會涉及 Accessibility。本文的交接採明確期限與人的回覆：批准不能只靠關閉箭頭這個訊號。發生失敗時，分別記錄清除成功與原始操作是否完成。

有多個 Agent 時，stop --all 會清除全部存活標記，適合第一次獨立練習；日常整合改用 --pid 或 --session，避免打斷別人的標記。預設 stop 只移除最新一個，這由 clear／stop 的選擇邏輯 決定。

進階可以把 bigarrow stop --hook 放進 Claude Code 的 UserPromptSubmit command hook，讓收到提示時清理對應工作階段。官方 Hooks 文件 說明該事件在處理提示前執行，也可能由排程或其他工作階段訊息觸發。因此收到這個事件不等於使用者批准；它在這裡只負責清除。

使用 hook 前，依 工作階段歸屬實作 核對標記帶有的 session 與 hook 輸入的 session_id 相同。手動 Terminal 畫出的標記可能沒有相同的 session；先保留 PID 清除路線，不要以為裝了 hook 就包辦所有箭頭。讀懂命令後將 hook 條目合併到既有設定，保留原來的 hooks。

常見問題：八個新手最容易卡住的地方

1. 可以在 Windows 或 Linux 照貼嗎？

不能直接沿用這篇的 macOS 路線。v0.4.5 的 Swift Package 宣告 macOS 14 平台，本文的權限與視窗定位也依 Mac 設計。

2. 第一個座標箭頭就要開輔助使用嗎？

不需要為這個純座標畫圖步驟開啟。改用元素查找或點擊監測時，才依那條命令的需求檢查。

3. dry-run 可以繞過 Accessibility 嗎？

不能把它當權限繞過。它省掉畫圖，元素解析仍會檢查 Accessibility。

4. 箭頭出現就代表找到了正確按鈕嗎？

不一定。指令成功與語意正確是兩關；先核對程式、視窗與控制項，再看操作後果。

5. 它會自己按下批准嗎？

本文的 bigarrow 指令只用於標記；批准由人在原始介面操作。若 Agent 還配置其他點擊工具，要另外管理那些工具的執行權限。

6. 為什麼只關掉一個箭頭？

因為不帶選擇旗標的 stop 選最新標記。獨立練習用 stop –all，正式整合保留自己的 PID 或 session。

7. 為什麼畫框不是整個視窗的邊框？

因為這裡的 –window 預設定位到視窗中心點；box 改變標記外觀，不把點自動擴成整個視窗。需要矩形就明確提供 –rect。

8. 沒看懂權限對象時要怎麼做？

先停止交接。清除標記，讀 doctor 的負責應用程式與錯誤，再到原始系統設定核對；不要照著牌子開不認識的程式權限。

給新手的三個重點

• 先練會消失的箭頭：期限與清除是操作的一部分。
• 先驗定位再接 Agent：固定位置、視窗中心、介面元素回答的是不同問題。
• 把批准留在原始介面：指路文字提供線索，人的決定要有另一份明確紀錄。