Plugin scout
Điều khiển Astra Scout từ Claude Code, Codex CLI hoặc Gemini CLI qua MCP để chạy, viết và sửa flow.
Plugin scout cho phép một AI CLI (Claude Code, OpenAI Codex CLI hoặc Gemini CLI) điều khiển Astra Scout đang chạy trên máy Mac. Từ terminal, tester và dev chạy flow, viết flow từ mô tả, sửa flow fail, khám phá app như người dùng, kiểm tra tracking và chẩn đoán thiết lập. Với khung chat trong app, xem Trợ lý AI.
Plugin cấu hình MCP (Model Context Protocol) cho CLI. Plugin thêm skill, tức hướng dẫn dựng sẵn cho AI về một việc như chạy flow, cùng vài command như /scout:setup.
Plugin chỉ chứa skill, command và cấu hình MCP. Plugin không có binary, không có hook lúc bắt đầu session và không có script nào chạy trên máy. Astra Scout thực hiện mọi việc với device.
Bắt đầu nhanh
- Cài plugin vào CLI bằng nút trong app: xem Cài bằng nút bấm.
- Đưa token, một mật khẩu cục bộ, cho CLI, cũng bằng nút trong app. Xem MCP token.
- Mở terminal mới, khởi động lại CLI và chạy
/scout:setup. Lệnh này báo thiết lập đã đúng chưa.
Đây là một trong nhiều cách tạo flow. Xem Tạo flow.
Skill
| Skill | Dùng để |
|---|---|
run-flow | Chạy flow từ file hoặc YAML dán vào và xem kết quả từng lệnh, video và crash |
write-flow | Viết flow mới từ mô tả, đọc text và id thật từ màn hình, kiểm tra, lưu (hỏi trước khi ghi đè) và chạy thử |
fix-flow | Chạy vòng tự sửa của Astra Scout cho flow fail, xem diff và chỉ lưu nếu được đồng ý |
explore-app | Khám phá app theo một persona và nhận báo cáo Markdown kèm các flow đề xuất |
check-tracking | Chạy flow, rồi kiểm tra event Amplitude với catalog nêu trong header của flow (tracking-specs/<app>.yaml) và các step assertEvents, rồi giải thích các rule fail hoặc N/A |
device-setup | Dùng Kiểm tra thiết lập để tìm và sửa error Xcode, Team ID, Developer Mode, Android SDK và AI CLI |
edit-tracking-spec | Sửa catalog tracking: gợi ý sửa từ event của run (chạy thử trước), đổi tên event ở mọi nơi, import taxonomy sheet kèm xem trước |
triage-run | Phân loại một run đã xong: đọc báo cáo, xem crash report của device, tìm bug trong tài liệu, rồi gợi ý fix-flow hoặc report-bug |
report-bug | Báo bug của run fail hoặc lần khám phá lên Jira, chỉ gửi những gì tester duyệt trong Astra Scout |
test-purchase | Chuẩn bị test mua trong app: xem sandbox tester, đổi tốc độ gia hạn subscription, xoá lịch sử mua sau khi tester duyệt |
manage-workspace | Quản lý environment và variable, tag của flow, file app context, đổi tên hoặc sao chép file flow |
Command: /scout:setup kiểm tra Astra Scout có đang chạy không, URL MCP đúng chưa, MCP đã bật chưa và token đã đặt chưa, và hiện các step cài cho từng CLI. /scout:doctor chạy kiểm tra thiết lập. Codex không có command /scout:…, nên bảo nó "run scout setup" hoặc gõ $ để chọn skill.
MCP tool
Skill ở trên gọi các tool, nên không cần nhớ chúng. Danh sách này dùng để tra cứu. Astra Scout cung cấp 55 tool qua MCP. Cột "Có thay đổi gì không?" cho biết tool chỉ đọc hay thực hiện một hành động. report_bug và clear_purchase_history luôn chờ tester xác nhận trong Astra Scout. list_environments ẩn giá trị variable (chúng có thể chứa mật khẩu).
Device và app
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
list_devices | Liệt kê các device Astra Scout thấy | Chỉ đọc |
connect_device | Kết nối tới một device (boot simulator hoặc emulator nếu cần) | Hành động |
disconnect_device | Ngắt kết nối device đang dùng | Hành động |
boot_device | Boot simulator hoặc emulator mà không kết nối | Hành động |
shutdown_device | Tắt simulator hoặc emulator đang chạy | Hành động |
get_screen | Đọc màn hình: các element kèm text và id, có thể kèm ảnh chụp | Chỉ đọc |
list_apps | Liệt kê app đã cài trên device | Chỉ đọc |
list_builds | Liệt kê các build của team cho app đang test, kèm build đang dùng | Chỉ đọc |
list_team_runs | Liệt kê các lượt chạy team đã đưa lên cloud, mới nhất trước, kèm kết quả và file | Chỉ đọc |
get_team_run | Đọc một lượt chạy của team: file kèm URL ký và report | Chỉ đọc |
install_app | Chọn và cài một build của team lên device, như Use This Build | Hành động |
uninstall_app | Gỡ app và xoá dữ liệu của nó (chỉ trên device test) | Hành động |
list_device_reports | Liệt kê báo cáo crash và log lưu trên iOS device | Chỉ đọc |
read_device_report | Đọc một báo cáo đó, đã che secret và text đã gõ | Chỉ đọc |
Flow và run
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
run_flow | Chạy flow từ file hoặc YAML ở nền | Hành động |
get_run | Trạng thái của run: từng lệnh, tóm tắt crash và video | Chỉ đọc |
stop_run | Dừng một run hoặc một auto-fix | Hành động |
run_command | Chạy ngay một lệnh Maestro | Hành động |
list_flows | Liệt kê các file flow của workspace | Chỉ đọc |
read_flow | Đọc một file flow | Chỉ đọc |
save_flow | Lưu file flow sau khi kiểm tra (không ghi đè nếu chưa được đồng ý) | Hành động |
validate_flow | Kiểm tra flow mà không chạy | Chỉ đọc |
autofix_flow | Sửa flow fail theo vòng chạy, AI sửa, chạy (không ghi gì) | Hành động |
get_autofix | Trạng thái auto-fix: các vòng, diff và YAML cuối | Chỉ đọc |
list_runs | Liệt kê các run đã xong gần đây | Chỉ đọc |
get_run_report | Báo cáo đầy đủ của một run đã xong | Chỉ đọc |
Workspace
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
list_environments | Liệt kê environment cùng tag và variable (giá trị bị ẩn) | Chỉ đọc |
save_environment | Tạo hoặc cập nhật một environment | Hành động |
list_tags | Liệt kê tag dùng trong flow và flow nào có tag nào | Chỉ đọc |
get_app_context | Đọc file app context mà AI dùng | Chỉ đọc |
set_app_context | Thay file app context | Hành động |
rename_flow | Đổi tên hoặc di chuyển file flow (không bao giờ thay file có sẵn) | Hành động |
duplicate_flow | Sao chép file flow (không bao giờ thay file có sẵn) | Hành động |
get_sync_status | Trạng thái Team Sync của workspace: conflict, file chờ push, file không sync được | Chỉ đọc |
sync_workspace | Sync workspace với team ngay và trả về trạng thái. Tool không giải conflict: người dùng giải trong Astra Scout. Xem Team Sync | Hành động |
Tracking
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
check_tracking | Kiểm tra event mà run đã gửi với catalog: pass, fail, warn hoặc N/A cho từng rule | Chỉ đọc |
compare_tracking_runs | So sánh event của run iOS và run Android cùng một flow | Chỉ đọc |
amplitude_user_lookup | Đọc user property và event mới nhất Amplitude lưu cho user của run | Chỉ đọc |
list_amplitude_projects | Liệt kê project Amplitude đã thiết lập trong Cài đặt (không hiện key) | Chỉ đọc |
list_tracking_specs | Liệt kê các catalog tracking | Chỉ đọc |
read_tracking_spec | Đọc một catalog dạng YAML và dạng event, rule đã parse | Chỉ đọc |
edit_tracking_spec | Sửa catalog và giữ comment (chạy thử trước) | Hành động |
suggest_tracking_spec | Gợi ý sửa catalog từ event các run đã gửi (không ghi gì) | Chỉ đọc |
get_unassigned_events | Event của run mà chưa step assertEvents nào nhận | Chỉ đọc |
get_tracking_coverage | Event trong catalog mà không flow nào kiểm tra, và event đã gửi mà catalog chưa có | Chỉ đọc |
import_taxonomy | Import taxonomy sheet (.xlsx, .csv, .tsv) vào catalog, có xem trước | Hành động |
Explore và bug
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
explore_app | Khám phá app theo một persona ở nền | Hành động |
get_explore | Trạng thái khám phá: step, màn hình và issue | Chỉ đọc |
list_explores | Liệt kê các lần khám phá đã qua và đang chạy | Chỉ đọc |
get_explore_screenshot | Một màn hình của lần khám phá dưới dạng ảnh | Chỉ đọc |
report_bug | Báo bug từ run hoặc lần khám phá lên Jira | Hành động, chờ xác nhận |
App Store sandbox
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
list_sandbox_testers | Liệt kê các sandbox tester của App Store Connect | Chỉ đọc |
set_sandbox_renewal_rate | Đổi tốc độ gia hạn subscription của tester | Hành động |
clear_purchase_history | Xoá lịch sử mua của tester trên server Apple | Hành động, chờ xác nhận |
Setup và tài liệu
| Tool | Làm gì | Có thay đổi gì không? |
|---|---|---|
doctor | Kiểm tra Xcode, simulator, Android SDK, signing và AI CLI | Chỉ đọc |
get_ios_signing | Xem Team ID và trạng thái signing cho iOS device | Chỉ đọc |
search_docs | Tìm trong tài liệu đóng gói sẵn trong app | Chỉ đọc |
Cài bằng nút bấm (khuyến nghị)
Các nút dưới đây cài plugin vào một CLI mà không cần gõ lệnh. Có thể đọc từng lệnh trước khi nó chạy.
App đóng gói sẵn plugin và sao chép nó vào ~/.astra-scout/plugin mỗi lần khởi động. Các nút cài từ bản sao đó.
Chọn Astra Scout > Cài đặt… (
Cmd+,) rồi bấm AI ở thanh bên. Trong Agent, mỗi CLI có một hàng kèm trạng thái. Dưới danh sách có một dòng dạng "N trên M CLI đã có plugin · phiên bản V trong app" (V là phiên bản plugin đóng gói trong app). Nếu một CLI được cài hoặc đăng nhập sau khi app đã khởi động, bấm Quét lại.
Bấm hàng của một CLI, ví dụ Claude Code. Trong mục Plugin, hàng Plugin Astra Scout hiện một trạng thái: Chưa có CLI, CLI chưa đăng nhập, Chưa cài, Cần cập nhật hoặc Đã cài. Dòng gợi ý bên dưới cho biết còn thiếu gì, ví dụ "Hãy cài Claude Code, rồi bấm Kiểm tra lại."
Bấm Cài đặt (hoặc Cập nhật) trên hàng đó. Một mục tên Cài đặt cho Claude Code (hoặc Cập nhật cho Claude Code) hiện ra bên dưới kèm lệnh chính xác. Chưa có gì chạy.
Đọc lệnh, rồi bấm Chạy. Một khung log hiện kết quả, và trạng thái ghi Đang chạy…, sau đó Đã xong hoặc "Mã thoát N". Dừng kết thúc lệnh. Sao chép đưa lệnh vào clipboard để chạy trong terminal khác. Khi lệnh kết thúc, trạng thái plugin được kiểm tra lại.
Bấm Kiểm tra lại trong mục Plugin nếu trạng thái không đổi. Hàng này phải ghi Đã cài.
Quay lại AI và mở Môi trường shell (trong Astra Scout cho CLI). Ở hàng
SCOUT_MCP_TOKEN, bấm Thêm vào profile shell. Nút bị tắt khi MCP không khả dụng.Mục Thêm SCOUT_MCP_TOKEN vào shell hiện lệnh và dòng sẽ được thêm, ví dụ "Thêm dòng này vào ~/.zshrc, thay mọi dòng cũ của cùng biến:". File phụ thuộc vào shell đăng nhập:
~/.zshrcvới zsh,~/.bash_profilevới bash,~/.config/fish/conf.d/astra-scout-token.fishvới fish. Dòng này đọc token từ filemcp-tokencủa Astra Scout, nên bản thân token không được ghi ra, token mới không cần sửa gì, và chạy hai lần không thêm dòng thứ hai. Bấm Chạy.
Nếu Astra Scout không ở cổng 5050, một hàng thứ hai
SCOUT_MCP_URLhiện ra với Đặt trong profile shell. Làm tương tự cho hàng này.Mở terminal mới, khởi động lại CLI và chạy
/scout:setup.
App không nhúng terminal. Mọi lệnh đều có thể sao chép và chạy trong terminal bất kỳ.
Cài thủ công
Chỉ làm cách này khi không dùng được các nút. Marketplace trong các lệnh là một nguồn plugin cục bộ mà CLI đọc. Nếu app đã khởi động ít nhất một lần, plugin nằm ở ~/.astra-scout/plugin. Dùng đường dẫn đó. Nếu không, dùng thư mục plugin/ của repository. Đây là các lệnh mà các nút chạy.
| CLI | Cài đặt | Cập nhật |
|---|---|---|
| Claude Code | claude plugin marketplace add ~/.astra-scout/plugin && claude plugin install scout@astra-scout | claude plugin marketplace add ~/.astra-scout/plugin && claude plugin marketplace update astra-scout && claude plugin update scout@astra-scout |
| Codex | codex plugin marketplace remove astra-scout >/dev/null 2>&1; codex plugin marketplace add ~/.astra-scout/plugin && codex plugin add scout@astra-scout | Giống lệnh cài |
| Gemini CLI | gemini extensions install ~/.astra-scout/plugin | gemini extensions update scout |
Với Codex, phần đầu xoá marketplace astra-scout cũ để Codex chấp nhận nguồn mới. Nó vô hại khi chưa có marketplace nào.
Kiểm tra kết nối: trong Claude Code, /mcp phải hiện plugin:scout:astra-scout đã kết nối. Trong Codex, codex mcp list. Trong Gemini CLI, gemini mcp list.
Chỉ dùng một cách kết nối. Một MCP server astra-scout thêm thủ công phải được xoá để các tool không bị liệt kê hai lần.
MCP token
Token là mật khẩu cục bộ để plugin đăng nhập vào Astra Scout, nhờ đó chỉ chương trình được người dùng cho phép mới điều khiển được app. Cài đặt hiện token đó.
Chọn Astra Scout > Cài đặt…, bấm AI, rồi Kết nối MCP. Hàng của nó ghi "Bật · localhost:5050" (hoặc "Tắt").
Kiểm tra Bật kết nối từ CLI (MCP) đang bật. Công tắc bật sẵn, trừ khi đã bị tắt.
Cạnh URL, bấm Sao chép URL nếu cần. Mặc định là
http://localhost:5050/mcp. Nếu Astra Scout ở cổng khác, một warning "Không dùng cổng mặc định 5050" hiện ra (xem bên dưới).Token được che. Bấm biểu tượng con mắt (Hiện token hoặc Ẩn token) để xem, hoặc bấm Sao chép token. Token được tạo ở run đầu tiên và lưu trong file
mcp-tokenở thư mục dữ liệu (~/Library/Application Support/Astra Scout/data/mcp-tokenvới app native). Trỏ chuột vào token để thấy đường dẫn.Để đưa token cho các CLI, dùng Môi trường shell (xem trên). Hoặc làm thủ công: đặt nó vào một biến môi trường, vì plugin chỉ đọc token từ đó.
bashecho "export SCOUT_MCP_TOKEN='<token>'" >> ~/.zshrc exec zshKhối 1. Đặt token trên cùng trang hiện sẵn dòng
export, kèm nút sao chép.
Để thay token, bấm mũi tên tròn (Tạo token mới). Một hộp thoại hỏi Tạo lại token MCP?. Bấm Tạo token mới. Mọi CLI đang dùng token cũ bị từ chối (401) ngay. Nếu biến được đặt bằng token đã sao chép, đặt lại. Nếu đã dùng Thêm vào profile shell, khởi động lại CLI.
Khối 2. Đăng ký Astra Scout với CLI hiện một lệnh cho Claude Code, Codex hoặc Gemini CLI (chọn trong bộ chọn). Cách này thay thế plugin, không bổ sung. Dùng cái này hoặc cái kia.
Nếu Astra Scout không ở cổng 5050
App chuyển sang cổng khác khi 5050 bận và ghi URL thật vào ~/.astra-scout/mcp.json. Cách đơn giản nhất là giải phóng cổng 5050 và mở lại app. Nếu không, trỏ CLI tới URL mới:
| CLI | Cách làm |
|---|---|
| Claude Code, Gemini CLI | export SCOUT_MCP_URL='http://localhost:<PORT>/mcp', rồi khởi động lại CLI. Hoặc dùng Đặt trong profile shell ở hàng SCOUT_MCP_URL. |
| Codex | codex mcp add astra-scout --url http://localhost:<PORT>/mcp --bearer-token-env-var SCOUT_MCP_TOKEN |
Mọi CLI khác hỗ trợ MCP qua streamable HTTP đều có thể dùng một server tên astra-scout tại URL đó với header Authorization: Bearer ${SCOUT_MCP_TOKEN}.
Có thể nhờ gì
- "Liệt kê các device, rồi chạy
flows/samples/settings_smoke.yamltrên một iOS device simulator" - "Viết một flow: mở Settings, vào General, kiểm tra About hiển thị. Lưu vào samples/"
- "
mydmv/smoke_launch.yamlfail. Tự sửa tối đa 3 vòng và cho tôi xem diff trước khi lưu" - "Khám phá phần onboarding như một người mới, 25 step, và viết báo cáo"
- "Chạy
mydmv/onboarding_paywall_skip.yaml, rồi kiểm tra tracking" (header của flow nêumydmv/tracking-specs/mydmv.yaml) - "iOS device không kết nối được và báo cần một development team. Kiểm tra giúp."
An toàn
run_flow,run_command,autofix_flowvàexplore_appchạy ngay trên device test, không cần xác nhận. Hai tool cần được duyệt làreport_bugvàclear_purchase_history.- Khi một CLI gọi một trong hai tool đó, Astra Scout hiện một hộp thoại native Cho phép yêu cầu từ CLI? và đưa app lên trước. Hộp thoại liệt kê yêu cầu, gồm tool và CLI nào đã gửi. Bấm Cho phép để tiếp tục hoặc Huỷ để từ chối. Esc và Return cũng chọn Huỷ. Nếu không ai trả lời trong 10 phút, yêu cầu được coi là bị từ chối. Các yêu cầu đến từng cái một, cũ nhất trước. Không có tool nào cho CLI tự xác nhận.
- Không có tool để xoá file hay chạy lệnh shell.
save_flowkhông ghi đè nếu chưa được đồng ý, và mọi đường dẫn đều nằm trong workspace. Mỗi device chỉ chạy một lần tại một thời điểm. - Các skill cho phép sẵn các tool chỉ đọc trong Claude Code. Các tool ghi hoặc thao tác trên device (
save_flow,run_flow,run_command,autofix_flow, kết nối device) theo các hộp xin quyền thông thường của CLI. - Mọi lời gọi MCP đều được ghi log. Khi MCP bật, Cài đặt > AI > Kết nối MCP kết thúc bằng Hoạt động từ CLI: 20 lời gọi gần nhất, mỗi dòng có giờ, CLI, tool, tóm tắt ngắn và kết quả: OK, Chờ xác nhận (CLI đang chờ câu trả lời cho hộp thoại trên), Quá nhiều lệnh hoặc Error. Mục này ghi "Chưa có CLI nào gọi Astra Scout." cho tới khi có CLI gọi.
- Token là bí mật cục bộ. Không dán token vào chat và không commit.
- Báo bug lên Jira là gửi ra ngoài, nên
report_bugluôn cần xác nhận trong app. Xem Jira.
Liên quan
- Trợ lý AI cho khung chat trong app
- Cài đặt cho mọi nút của mục AI
- Khám phá app và Tracking