Trợ lý AI

Dùng AI CLI có sẵn trên máy Mac để viết, giải thích và sửa flow ngay trong Astra Scout.

Trợ lý AI là khung chat trong Astra Scout. Tester mô tả điều cần test, AI viết flow dạng YAML. AI cũng giải thích và sửa flow có sẵn, nên tester không phải tự viết YAML.

Astra Scout không kèm sẵn AI. Astra Scout dùng một AI CLI: chương trình dòng lệnh của hãng AI (Claude Code, OpenAI Codex hoặc Gemini CLI) đã cài và đăng nhập trên máy Mac. AI chỉ đọc, không tự sửa file. Astra Scout chèn flow vào file và chạy flow.

Đây là một trong nhiều cách tạo flow. Xem Tạo flow.

Thiết lập AI CLI

Cài một trong các CLI này:

CLI	Cài đặt	Đăng nhập
Claude Code	Làm theo tài liệu Claude Code, ví dụ npm i -g @anthropic-ai/claude-code	Chạy claude, gõ /login
OpenAI Codex	npm i -g @openai/codex hoặc Homebrew	codex login
Gemini CLI	npm i -g @google/gemini-cli hoặc brew install gemini-cli	Chạy gemini và đăng nhập

1. Cài một CLI trong bảng và đăng nhập, theo cột cuối.
2. Trong Astra Scout, mở Cài đặt > AI (Cmd+, mở cửa sổ Cài đặt, rồi bấm AI ở thanh bên).
3. Xem mục Agent. Mỗi CLI có một hàng kèm trạng thái: Sẵn sàng, Chưa đăng nhập hoặc Chưa cài. CLI chưa cài hiện gợi ý cách cài ngay dưới tên.
4. Bấm Quét lại dưới danh sách. App tìm lại các chương trình đã cài trên máy (PATH của shell), nên không cần mở lại app. CLI giờ hiện Sẵn sàng.

Để đổi giá trị mặc định:

1. Ở Mặc định, Nhà cung cấp mặc định chọn CLI mà chat dùng khi chưa chọn CLI nào. Tự động là CLI đầu tiên đã đăng nhập.
2. Lệnh AI trong flow và Model đặt provider và model cho các lệnh AI trong flow (xem Lệnh AI trong flow). Mặc định ở đó là nhà cung cấp mặc định ở trên.
3. Để đổi một CLI, bấm hàng của nó trong Agent. Trang của CLI có Model, Tham số thêm (ví dụ --effort low cho Claude Code) và Đường dẫn CLI (để trống là tự dò). Thay đổi có hiệu lực ngay.

Cài plugin Astra Scout vào CLI

Plugin điều khiển Astra Scout từ terminal bằng AI CLI (xem AI trong terminal). Plugin cấu hình MCP, kênh để AI CLI gọi các chức năng của Astra Scout. Chat trong app không cần plugin.

1. Trong Cài đặt > AI, bấm hàng của CLI.
2. Ở mục Plugin, hàng Plugin Astra Scout hiện Đã cài, Chưa cài, Cần cập nhật, CLI chưa đăng nhập hoặc Chưa có CLI.
3. Bấm Cài đặt (hoặc Cập nhật). Một câu lệnh hiện ra. Không có gì chạy cho đến khi đọc câu lệnh và bấm Chạy.
4. Khi xong, bấm Kiểm tra lại. Hàng đó phải hiện Đã cài. Dòng dưới danh sách Agent cho biết có bao nhiêu CLI đã có plugin.

Mục Astra Scout cho CLI trên cùng pane còn hai trang nữa: Kết nối MCP (công tắc bật hoặc tắt kênh MCP, cùng URL và token mà các CLI dùng để kết nối; token là mật khẩu cục bộ) và Môi trường shell (ghi SCOUT_MCP_TOKEN và SCOUT_MCP_URL vào profile shell để CLI tự tìm thấy kênh này, cũng chỉ sau khi bấm Chạy). Chi tiết ở Plugin scout.

Khung chat

Mở chat và gửi tin nhắn

1. Ở đầu thanh bên trái, bấm biểu tượng lấp lánh (sparkles) trong công tắc (tooltip: "Hiện navigator hoặc trợ lý AI"). Thanh bên giờ liệt kê các cuộc trò chuyện, và cuộc trò chuyện đang mở thay chỗ của editor.
2. Bấm Cuộc trò chuyện mới ở đầu danh sách. Menu này cũng liệt kê từng CLI đã cài; chọn một CLI để bắt đầu cuộc trò chuyện với nó.
3. Dưới ô nhập tin, bấm nút kẹp giấy (nhãn của nó là Ngữ cảnh (N), N là số mục đang bật) để chọn AI nhìn thấy gì. Xem Chọn ngữ cảnh.
4. Bấm tên model bên cạnh để chọn AI và Model cho cuộc trò chuyện này. Mặc định dùng cài đặt trong Cài đặt > AI.
5. Gõ yêu cầu. Bấm Return để gửi, Shift+Return để xuống dòng, hoặc bấm nút gửi tròn (Cmd+Return cũng gửi). Khi AI đang trả lời, nút này thành Dừng.

Cuộc trò chuyện trống gợi ý sẵn vài câu mẫu phía trên ô nhập; bấm một câu để điền vào ô. Thêm vài ví dụ:

• "Viết flow mở app, đăng nhập bằng email test@example.com và kiểm tra thấy màn hình chính"
• "Giải thích flow đang mở làm gì"
• "Thêm step chụp màn hình sau mỗi lần bấm nút"

Để xoá một cuộc trò chuyện, bấm chuột phải vào nó trong danh sách và chọn Xoá cuộc trò chuyện, hoặc dùng menu ... ở đầu cuộc trò chuyện.

Nếu không có CLI nào dùng được, cuộc trò chuyện hiện "Chưa có CLI AI nào dùng được…" kèm nút Quét lại. Thiết lập một CLI trước (xem phía trên).

Chọn ngữ cảnh

AI chỉ biết những gì được gửi kèm tin nhắn. Menu Ngữ cảnh (nút kẹp giấy) có năm công tắc để chọn những gì được gửi:

Mục	AI nhận được gì
File: … (hoặc File hiện tại)	File flow đang mở. Tắt khi không có file nào mở.
Vùng chọn	Các dòng được chọn trong editor
Màn hình device	Danh sách phần tử (element: nút, ô nhập, text) trên màn hình device đang kết nối. Tắt khi chưa kết nối device.
Run cuối: … (hoặc Run mới nhất)	Kết quả và error của run mới nhất. Tắt khi chưa có run.
Flow trong workspace	Vài flow trong workspace để làm mẫu phong cách

Các mục được gửi cùng tin nhắn được liệt kê dưới tin nhắn trong cuộc trò chuyện.

Dùng YAML mà AI viết

Khi câu trả lời có YAML, một hàng nút biểu tượng nhỏ nằm dưới khối code. Rê chuột vào nút để xem tên. Một dòng phía trên ghi Flow hợp lệ, Các lệnh hợp lệ hoặc "YAML chưa hợp lệ: …". Astra Scout kiểm tra YAML và từ chối các command mà nền tảng đang kết nối không chạy được.

Nút	Làm gì
Chèn vào file	Thêm YAML vào flow đang mở. Bị tắt cho đến khi có file flow đang mở.
Tạo file mới	Lưu YAML thành file mới trong workspace. Chỉ với flow đầy đủ (có appId).
Áp dụng vào file	So sánh với file đang mở và áp dụng các thay đổi được chấp nhận. Chỉ với flow đầy đủ.
Chạy thử	Chạy trên device mà không lưu file. Bị tắt cho đến khi kết nối device.
Sao chép	Sao chép YAML

AI tự tra cứu được gì

Khi provider là Claude Code, AI tự xem dữ liệu trong Astra Scout trong lúc trả lời, nên không cần dán vào. Nó xem được: các device và màn hình của chúng, các run cũ và report, crash report của iOS device, các lần khám phá, tracking catalog và coverage, environment (giá trị biến vẫn bị ẩn), tag, ngữ cảnh app, sandbox tester và chính bộ docs này. Mỗi lần tra cứu hiện thành một dòng phía trên câu trả lời; bấm dòng đó để xem kết quả.

AI chỉ được đọc. AI không bao giờ chạy flow, kết nối device, lưu file hay gửi gì lên Jira hoặc Apple: mọi thay đổi được đề xuất bằng YAML, và người dùng áp dụng bằng các nút ở trên.

Việc này cần công tắc Cài đặt > AI > Kết nối MCP > Bật kết nối từ CLI (MCP) đang bật. Khi tắt, chat ghi chú điều đó dưới câu trả lời. OpenAI Codex và Gemini CLI chỉ trả lời dựa trên ngữ cảnh được đính kèm.

Tự sửa đến khi chạy qua

Dùng tự sửa khi một flow vừa fail. Tự sửa chạy flow, nhờ AI đề xuất bản sửa, áp dụng vào một bản nháp và chạy lại. Mỗi lần như vậy là một vòng, và số vòng có giới hạn.

Trước khi bắt đầu: đã mở một workspace, đã kết nối device và không có gì đang chạy. Nếu không, Tự sửa… bị tắt.

1. Chạy flow cho đến khi nó fail. Xem Chạy flow.
2. Trong runner, bấm hàng của flow bị fail để mở chi tiết.
3. Bấm Tự sửa…. (Sửa bằng AI ngay cạnh thì mở một cuộc trò chuyện về fail đó và điền sẵn yêu cầu.)

4. Thanh bên chuyển sang trợ lý AI và thẻ Tự sửa đến khi chạy qua hiện trong cuộc trò chuyện. Nó dùng AI và model đã chọn trong chat, và môi trường chọn trên thanh công cụ. Thẻ có một mục Vòng N/3 cho mỗi vòng, và Dừng để kết thúc.
5. Bật Áp dụng vào file khi chạy qua để ghi bản sửa vào file ngay khi flow pass. Tắt nếu muốn xem lại kết quả trước.
6. Khi xong, bấm Xem và áp dụng… để xem diff trước khi ghi file, Tạo file mới để giữ bản sửa thành file mới, hoặc Xem video vòng cuối để xem vòng cuối. Rê chuột vào biểu tượng để xem tên.

Mỗi vòng ghi lại: step fail và error, lý do của AI, diff YAML và ảnh chụp màn hình trước và sau.

App chạy tối đa 3 vòng.

Tự sửa dừng mà chưa pass trong các trường hợp sau:

• Dừng sớm (Chưa xong) khi cùng một step fail theo cùng cách hai vòng liên tiếp, khi AI đề xuất một phiên bản đã chạy rồi, hoặc khi AI không đề xuất thay đổi nào.
• Dừng với kết luận Fail khi app crash trong hai run liên tiếp.
• Dừng ngay (Bị chặn) khi device hoặc driver fail.

Các step trông giống mua hàng chạy như mọi step khác, nên chỉ dùng device test. Xem Test mua hàng.

Lệnh AI trong flow

Ba lệnh này cho AI nhìn màn hình để kiểm tra hoặc đọc text, dùng khi selector thông thường (như assertVisible) không kiểm được. Chúng là lệnh AI của Maestro, công cụ mà flow dựa trên. Astra Scout chạy chúng bằng AI đã cấu hình, không cần Maestro Cloud.

Lệnh	Cú pháp	Kết quả
assertWithAI	- assertWithAI: "The screen has a Sign in button"	Đúng hoặc sai kèm lý do
assertNoDefectsWithAI	- assertNoDefectsWithAI	Sai khi thấy chữ bị cắt hoặc chồng lên nhau, màn hình trống hoặc layout hỏng
extractTextWithAI	- extractTextWithAI: "CAPTCHA code"	Lưu text đọc được vào ${aiOutput} (hoặc biến đặt trong lệnh)

Để chọn AI nào chạy chúng, mở Cài đặt > AI, và ở Mặc định đặt Lệnh AI trong flow (provider) và Model.

Cần biết:

• Mỗi step chụp màn hình và danh sách phần tử rồi gửi một yêu cầu AI. Việc này tốn một lần gọi model, và AI có thể trả lời khác nhau giữa các run.
• Giống Maestro, chúng mặc định optional: true: step fail hiện màu đỏ nhưng flow vẫn tiếp tục. Thêm optional: false để dừng flow. Mỗi step chờ tối đa 60 giây (đổi bằng timeout: tính bằng mili giây).
• Bảng kết quả của step ghi lại kết luận, câu hỏi, câu trả lời gốc, model và đường dẫn ảnh chụp màn hình.
• Với assertWithAI và assertNoDefectsWithAI có optional: false, nếu confidence của AI dưới 0.6, kết luận của run là Chưa chắc chắn, không phải Pass. Với mặc định optional: true, run vẫn pass và hiện warning. assertNoDefectsWithAI không có ảnh chụp màn hình cũng là Chưa chắc chắn, vì Astra Scout không bao giờ kết luận là không có bug giao diện chỉ từ cây phần tử.

Không chụp màn hình sau khi gõ bí mật

Để bảo vệ mật khẩu, khi một step gõ giá trị lấy từ biến môi trường (như inputText: ${PASSWORD}) hoặc màn hình có ô mật khẩu đã điền, các step AI sau đó trong cùng session device không gửi ảnh chụp màn hình. Chỉ cây phần tử được gửi, với mật khẩu và giá trị đã gõ được thay bằng ***. Điều này kéo dài cho đến khi app được mở lại (launchApp, stopApp, killApp hoặc clearState) hoặc device kết nối lại. Đặt assertNoDefectsWithAI trước step gõ mật khẩu.

Ngữ cảnh app

Ngữ cảnh app là ghi chú ngắn cho AI biết về app: tên màn hình, gói trả phí, thuật ngữ. Giới hạn 16 KiB. Mọi lần gọi AI đều đọc ghi chú này: chat, viết và sửa flow, tự sửa, lệnh AI và khám phá. Ghi chú được lưu theo workspace.

1. Mở một workspace, rồi chọn File > Cài đặt dự án… (Option+Cmd+,).
2. Cuộn tới mục Ngữ cảnh app và gõ vào ô. Khi ô trống, nó hiện một ví dụ.
3. Xem dòng kích thước dưới ô ("N KB trên 16 KB"). Quá giới hạn thì dòng này đỏ và Lưu bị tắt.
4. Bấm Lưu. Ghi chú "Đã lưu ngữ cảnh app" hiện ra. Lưu một ô trống sẽ xoá file.

Ví dụ:

# App context (vocabulary for the AI)
Screens: Home, Practice Test, DMV Handbook, Settings
Paid plans: DMV Pass (weekly / monthly / lifetime)
Terms: "permit test" = the exam for a learner's permit

AI trong terminal

Claude Code, Codex và Gemini CLI cũng điều khiển được Astra Scout. Xem Plugin scout.

Chi tiết kỹ thuật

• Thay cho AI CLI, có thể khởi động server với biến môi trường ANTHROPIC_API_KEY; khi đó Anthropic API xuất hiện như một provider.
• Tự sửa: app chạy tối đa 3 vòng. AI CLI gọi tool autofix_flow có thể yêu cầu tối đa 5.
• Lệnh AI: AI phán xét tách biệt với AI thực hiện thao tác và chỉ nhận assertion hoặc câu hỏi, màn hình và ngữ cảnh app. Text trên màn hình được gửi như dữ liệu không đáng tin, và prompt yêu cầu AI bỏ qua mọi chỉ dẫn hiển thị trên màn hình. Ảnh chụp màn hình được giữ 24 giờ trong một thư mục riêng dưới thư mục temp.
• Ngữ cảnh app lưu ở .scout/context.md trong workspace. Chỉ file của workspace đang chạy được đọc. Nếu .scout hoặc context.md là symlink, device hay FIFO, nó bị từ chối.