Cách sử dụng mũi tên lớn để hướng dẫn con người qua quy trình Mac do AI điều khiển

big-arrow-on-the-screen thực hiện việc gì

big-arrow-on-the-screen, còn được gọi là bigarrow, là một công cụ dòng lệnh macOS vẽ một mũi tên và bảng chỉ dẫn rất dễ nhìn phía trên mọi cửa sổ. Công cụ này được thiết kế cho các tác nhân AI có thể thực hiện hầu hết tác vụ trên máy tính nhưng cần chuyển một số quyết định nhất định lại cho con người.

Ví dụ, tác nhân có thể chỉ vào nút Allow trong System Settings, xác định đúng cửa sổ trình duyệt hoặc hướng dẫn ai đó qua một quy trình gồm nhiều bước. Người dùng vẫn hoàn toàn kiểm soát: bigarrow không bao giờ nhấp, nhập liệu hay chụp màn hình.

Lớp phủ được hiển thị phía trên các cửa sổ thông thường, hộp thoại, ứng dụng toàn màn hình và Spaces, đồng thời giữ tiêu điểm bàn phím trong ứng dụng vốn đang có tiêu điểm. Các cú nhấp vào mục tiêu sẽ truyền xuống ứng dụng bên dưới. Mũi tên cũng tự động biến mất khi hết thời lượng hoặc khi tiến trình sở hữu thoát.

Tác nhân của bạn có thể giải thích cần làm gì, sau đó đặt một ngón tay trực quan lên chính xác nút điều khiển mà con người cần sử dụng.

Khi nào nên sử dụng

bigarrow hữu ích bất cứ khi nào tác nhân AI cần con người đưa ra quyết định hoặc hoàn thành một hành động. Các ví dụ điển hình gồm lời nhắc cấp quyền, màn hình đồng ý OAuth, xác thực hai yếu tố, CAPTCHA, passkey, thanh toán, chữ ký và xác nhận pháp lý.

Công cụ cũng giúp hướng dẫn rõ ràng hơn khi có nhiều cửa sổ hoặc nút điều khiển tương tự cùng hiển thị. Tác nhân có thể chọn một ứng dụng, cửa sổ hoặc tab trình duyệt cụ thể thay vì yêu cầu người dùng tìm kiếm giữa nhiều cửa sổ đang mở.

Các cách sử dụng khác gồm hướng dẫn ai đó cách dùng ứng dụng, hỗ trợ từ xa, làm nổi bật các nút điều khiển trong video quay màn hình và kiểm tra xem tọa độ do một công cụ tự động hóa khác trả về có chính xác hay không.

Cài đặt trên macOS

Dự án hỗ trợ macOS 14 trở lên. Cách cài đặt đơn giản nhất là dùng Homebrew:

brew install franzenzenhofer/tap/bigarrow

Nếu muốn Claude Code và Codex biết khi nào và cách sử dụng công cụ này, hãy cài đặt thêm skill cho tác nhân:

bigarrow install-skill

Lệnh này cài đặt skill cho Claude Code tại ~/.claude/skills và cho Codex tại ~/.agents/skills. Bạn cũng có thể gọi trực tiếp bigarrow từ shell mà không cần cài đặt skill.

Biên dịch từ mã nguồn

Để tự biên dịch dự án, hãy dùng Xcode 16 trở lên:

swift build -c release

Tệp nhị phân tạo ra nằm tại .build/release/bigarrow. Bản thân ứng dụng được viết bằng Swift. Các tệp shell và Python trong scripts/ được dùng cho ảnh chụp màn hình và kiểm thử.

Các lệnh chỉ dẫn đầu tiên

Ba mẫu cơ bản là chỉ vào một phần tử trợ năng, chỉ vào tọa độ và giữ mũi tên hiển thị cho đến khi bạn dừng nó.

Chỉ vào một nút điều khiển có nhãn

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

--element tìm một nút điều khiển theo nhãn, còn --app xác định ứng dụng chứa nút đó. Bảng chỉ dẫn giải thích hành động người dùng được yêu cầu thực hiện.

Chỉ vào tọa độ

bigarrow point --at 760,500 --text "Franz, click HERE"

Tọa độ sử dụng điểm logic toàn cục với gốc ở góc trên bên trái, cùng hệ tọa độ được macOS Accessibility, CGWindowList và Peekaboo báo cáo. Bạn cũng có thể chỉ vào một hình chữ nhật:

bigarrow point --rect 600,400,240,80 --text "This is the area to review"

Giữ mũi tên hiển thị cho đến bước tiếp theo

bigarrow start --window "Safari:Inbox" --text "This window"
bigarrow stop

start trả về ngay lập tức và giữ mũi tên hiển thị. Dùng stop để xóa mũi tên hiện tại hoặc stop --all để xóa tất cả mũi tên.

Lệnh point chạy một lần có thời lượng mặc định là tám giây. Thay đổi thời lượng bằng --duration; start có mặc định là 300 giây. Dùng --duration 0 để không giới hạn thời gian.

Chọn đúng mục tiêu

bigarrow hỗ trợ nhiều nguồn mục tiêu:

• --at X,Y chỉ vào một tọa độ.
• --rect X,Y,W,H làm nổi bật một vùng hình chữ nhật.
• --mouse chỉ vào vị trí chuột hiện tại.
• --window App[:title] chỉ vào một cửa sổ.
• --element Label --app App tìm một phần tử trợ năng.
• --peekaboo ID --snapshot see.json sử dụng ID phần tử từ kết quả see --json của Peekaboo.

Để kiểm tra các nút điều khiển mà một ứng dụng cung cấp, hãy chạy:

bigarrow elements --app "System Settings"

Với nhiều màn hình, --display N khiến các giá trị tọa độ và hình chữ nhật được tính tương đối theo một màn hình. Hỗ trợ tọa độ toàn cục âm đối với các màn hình được đặt bên trái hoặc phía trên màn hình chính.

Nhắm đúng cửa sổ hoặc tab trình duyệt

Khi cung cấp --app App[:window or tab title] hoặc --window, bigarrow có thể đưa ứng dụng, cửa sổ hoặc tab Chrome/Safari liên quan lên trước khi vẽ. Điều này ngăn mũi tên vốn chính xác xuất hiện trên sai cửa sổ đang hiển thị.

bigarrow point --app "Google Chrome:Pull request" --text "Review this pull request"

Sử dụng --no-raise khi bạn muốn giữ nguyên vị trí các cửa sổ của người dùng. Nếu một ứng dụng khác che mục tiêu sau đó, mũi tên sẽ ẩn đi cho đến khi mục tiêu hiển thị trở lại.

Làm cho mũi tên rõ ràng và hữu ích

Bạn có thể tùy chỉnh hình dạng, kiểu, kích thước, góc, màu sắc và hành vi của mũi tên:

• --shape bend|straight|zigzag|spiral chọn đường đi của mũi tên.
• --style arrow|ring|box chọn mũi tên thông thường, vòng chỉ có viền hoặc hộp chỉ có viền.
• --size S|M|L thay đổi kích thước.
• --corners round|sharp điều khiển góc của biển báo.
• --color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBB đặt màu chính.
• --border shadow|white-black|black thay đổi kiểu viền.
• --border-color, --text-color và --edge-color tùy chỉnh từng màu riêng.
• --close-button thêm nút X có thể nhấp vào biển báo.

Ví dụ, lệnh này vẽ một hộp màu xanh lá nổi bật quanh mục tiêu:

bigarrow point --at 760,500 --style box --color green --text "Review this control"

Nút đóng được bật tùy chọn và cho phép người dùng trực tiếp loại bỏ lớp phủ:

bigarrow start --element "Save" --app "TextEdit" --close-button --text "Click Save when ready"

Các tùy chọn tương tác hữu ích

Một số tùy chọn giúp kết nối lớp phủ với quy trình được hướng dẫn:

• --follow di chuyển mũi tên theo cửa sổ hoặc phần tử.
• --until-click kết thúc mũi tên sau khi nhấp vào mục tiêu.
• --say đọc to nội dung biển báo, hữu ích khi người dùng có thể không nhìn vào màn hình.
• --json cung cấp đầu ra có thể đọc bằng máy cho tác nhân và tập lệnh.

Vì vậy, một chuỗi hướng dẫn có thể chỉ đến một điều khiển, chờ người dùng thao tác, dừng mũi tên rồi chỉ đến điều khiển tiếp theo. Công cụ không tự thực hiện thao tác nhấp.

Hiểu về quyền

Việc vẽ lớp phủ không yêu cầu quyền Ghi màn hình hoặc Trợ năng trên macOS. Tuy nhiên, một số cách tìm hoặc kích hoạt mục tiêu có yêu cầu quyền.

• --at, --rect, --mouse, --window App, --peekaboo và --app App không yêu cầu quyền.
• --element, elements, --until-click và --app App:title yêu cầu quyền Trợ năng.
• --window App:title yêu cầu quyền Ghi màn hình để đọc tiêu đề cửa sổ và quyền Trợ năng để đưa cửa sổ lên trước, trừ khi bạn sử dụng --no-raise.

macOS cấp các quyền này cho ứng dụng đã khởi chạy bigarrow, chẳng hạn như Terminal, iTerm2, Ghostty, VS Code hoặc Claude, thay vì cấp cho chính tệp nhị phân bigarrow.

Chạy lệnh chẩn đoán để xem các quyền liên quan, ứng dụng sở hữu chúng và các màn hình được kết nối:

bigarrow doctor

Khi thiếu quyền bắt buộc, lệnh sẽ thoát với mã trạng thái 4 và xác định ứng dụng cùng khung cài đặt liên quan.

Sử dụng tính năng tự động dọn dẹp an toàn

Mũi tên được thiết kế để không tồn tại sau khi tác nhân hoàn tất. Lệnh point có hẹn giờ sẽ tự động xóa chính nó. Mũi tên cũng kết thúc khi tiến trình tác nhân đã tạo ra nó thoát, sử dụng CLAUDE_PID hoặc BIGARROW_OWNER_PID khi có.

Đối với quy trình Claude Code, có thể dùng bigarrow stop --hook làm hook UserPromptSubmit để xóa các mũi tên của phiên đó khi người dùng phản hồi. Các lệnh dọn dẹp rõ ràng là:

bigarrow stop
bigarrow stop --all

Các biện pháp bảo vệ này hữu ích với những tác nhân có thể bị gián đoạn hoặc thay thế trước khi đến bước dọn dẹp thông thường.

Sử dụng JSON và mã thoát trong quy trình tác nhân

Mọi lệnh đều chấp nhận --json, giúp kiểm tra kết quả bằng chương trình dễ dàng hơn. Các mã thoát được ghi nhận là:

• 0: lệnh hoàn tất thành công.
• 2: dữ liệu đầu vào không hợp lệ.
• 3: không tìm thấy mục tiêu.
• 4: thiếu quyền bắt buộc.

Tác nhân có thể sử dụng các kết quả này để quyết định thử lại bằng phương thức mục tiêu khác, yêu cầu người dùng cấp quyền hoặc giải thích rằng không thể tìm thấy điều khiển được yêu cầu.

Gỡ lỗi mục tiêu nâng cao

Nếu bạn không chắc tọa độ từ Trợ năng, Peekaboo hoặc công cụ khác có chính xác hay không, hãy sử dụng chế độ chạy thử:

bigarrow point --at 760,500 --dry-run --json

Lệnh này báo vị trí mà công cụ sẽ chỉ đến mà không vẽ lớp phủ. Tính năng này hữu ích để xác thực việc chuyển đổi tọa độ, lựa chọn màn hình và kết quả tự động hóa trước khi hiển thị bất kỳ thứ gì cho người dùng.

Peekaboo có thể cung cấp một nguồn mục tiêu khác. Chụp ảnh nhanh JSON bằng Peekaboo, sau đó truyền ID của phần tử phù hợp:

bigarrow point --peekaboo ELEMENT_ID --snapshot see.json --text "Review this element"

Trong Chrome, các phần tử trên trang có thể yêu cầu cờ --force-renderer-accessibility của Chrome hoặc VoiceOver. Thanh công cụ riêng của Chrome vẫn khả dụng thông qua tuyến trợ năng thông thường. Khi nội dung trang không được hiển thị, hãy sử dụng tọa độ thay thế.

Cách các tác nhân nên sử dụng kỹ năng

Kỹ năng đi kèm hỗ trợ cả Claude Code và Codex thông qua một SKILL.md tương thích với Agent Skills, cùng siêu dữ liệu Codex trong agents/openai.yaml. Kỹ năng này hướng dẫn tác nhân khi nào cần chỉ dẫn, cách chọn mục tiêu, cách viết một câu hoàn chỉnh trên biển báo, khi nào sử dụng --say và khi nào dừng sau khi người dùng đã thực hiện thao tác.

Một quy trình thực tế của tác nhân có thể như sau:

1. Xác định thao tác cần con người xác nhận hoặc hỗ trợ.
2. Chọn nhãn, cửa sổ, tab, tọa độ, hình chữ nhật hoặc mục tiêu Peekaboo.
3. Viết biển báo nêu chính xác việc người dùng cần làm và lý do.
4. Đưa ứng dụng mục tiêu lên trước, trừ khi việc giữ nguyên bố cục hiện tại là quan trọng.
5. Chờ con người thực hiện thao tác hoặc phản hồi.
6. Dừng mũi tên trước khi tiếp tục bước tiếp theo.

Công cụ không làm gì

bigarrow được giới hạn có chủ đích. Đây không phải là công cụ chú thích màn hình dành cho con người, bot nhấp chuột hay công cụ chụp ảnh màn hình. Công cụ không bao giờ nhấp chuột, nhập liệu hoặc chụp màn hình. Mục đích của nó là hiển thị hướng dẫn của chương trình, đồng thời để con người tự quyết định và thực hiện thao tác.

Các kiểu vòng tròn và khung sử dụng đường viền để mục tiêu vẫn hiển thị. Biển báo được đặt cách xa mục tiêu khi có đủ không gian, còn nút đóng, nếu được bật, cho phép con người loại bỏ mũi tên. Những lựa chọn thiết kế này giúp công cụ phù hợp với các thao tác nhạy cảm như cấp quyền, xác thực, thanh toán và triển khai.

Kết luận

bigarrow cung cấp cho các tác nhân AI chạy trên macOS một cách đơn giản để trao lại quyền kiểm soát cho con người mà không phải dùng đến các thông báo terminal mơ hồ. Hãy cài đặt công cụ bằng Homebrew, thêm kỹ năng Claude Code hoặc Codex nếu cần, sau đó sử dụng point cho các lời nhắc ngắn hoặc start và stop cho quy trình được hướng dẫn.

Với các mục tiêu nhãn, cửa sổ, tọa độ, hình chữ nhật, chuột và Peekaboo, cùng các kiểu tùy chỉnh, tính năng đọc bằng giọng nói, đầu ra JSON, tự động dọn dẹp và hỗ trợ nhiều màn hình, công cụ biến câu “vui lòng nhấp vào đây” thành hướng dẫn chính xác trên màn hình, đồng thời vẫn đảm bảo thao tác cuối cùng do con người kiểm soát.