Cho agent một máy để kiểm thử

Một rig là một cỗ máy dùng một lần mà agent mở ra khi cần thực sự thử một việc gì đó: tải một trang, nhấp qua một ứng dụng desktop, chạm khắp một chiếc điện thoại. Bạn có thể xem nó làm việc theo thời gian thực, và giành quyền điều khiển bất cứ lúc nào bạn muốn.

Các rig terminal khép kín, trình duyệt và desktop là VM với đĩa dùng một lần và mạng có cổng kiểm soát. Android và iOS là những trình giả lập do máy chủ quản lý: trạng thái thiết bị của chúng dùng một lần, nhưng mạng của chúng đi theo máy chủ lưu trữ.

Thiết lập một lần

Rig chạy trên máy đang chạy cc_server — chính máy đó, không phải máy bạn đang nhìn. Có năm bề mặt dành cho người dùng; các bề mặt desktop và di động cần thiết lập trên máy chủ:

Bề mặt	Chạy trên	Thiết lập
Terminal (VM)	Một microVM khởi động từ image Ubuntu được ghim	Không — image được tải tự động trong lần dùng đầu tiên
Browser (VM)	Một microVM khởi động từ image Debian được ghim, với Chromium, Firefox hoặc WebKit được cài trong lần dùng đầu tiên	Không — tương tự
Máy tính (VM)	QEMU với image desktop Linux có sẵn Chromium, Firefox, WebKit và bộ CLI nền tảng kiểu runner do GitHub vận hành	Cài QEMU (`brew install qemu`), rồi Nhập một image desktop trong Cài đặt → Máy chủ → Rigs
Android	Trình giả lập Android của Google	Cài Android SDK, tạo một AVD và khởi động nó (bên dưới)
Trình mô phỏng iOS	CoreSimulator trên máy Mac chạy máy chủ	Cài Xcode và runtime Trình mô phỏng iOS được yêu cầu, rồi cài cầu nối tự động hóa trong Cài đặt → Máy chủ → Rigs

Các cỗ máy terminal và trình duyệt khởi động từ image được ghim theo digest: các byte chính xác được chỉ định trước, chỉ tải một lần trong lần khởi động đầu và được lưu vào bộ nhớ đệm — sau lần khởi động đầu của mỗi loại, những cỗ máy về sau bỏ qua toàn bộ phần tải xuống và khởi động trong vài giây. Cài đặt → Máy chủ → Rigs hiển thị những gì máy chủ của bạn có thể khởi động và mọi cỗ máy đang chạy ngay lúc này.

Một image desktop đã cài vẫn quản lý được từ cùng trang đó: Nhập thay thế nó bằng một tệp qcow2 mới hơn, còn Xóa gỡ nó để bạn có thể cài một bản dựng mới.

Thiết bị di động được thiết lập theo cách khác

Không có image nào của chúng tôi cho Android hay iOS, và đó không phải là một thiếu sót. Image hệ thống Android đến từ SDK của Google; runtime iOS đến từ Xcode. Với Android, hãy cài Android Studio (hoặc bộ công cụ SDK dòng lệnh), thêm một thiết bị ảo trong Device Manager, rồi khởi động nó. Trang Rigs sau đó báo Android là khả dụng.

Trang đó cũng cho bạn biết chính xác bước nào bạn đang thiếu — không có SDK, không có trình giả lập, không có thiết bị ảo, hay một thiết bị đơn giản là chưa chạy — vì bốn trường hợp đó có bốn cách khắc phục khác nhau và chỉ một trong số đó là tải xuống. Nếu bạn khởi động cc_server từ một shell không thấy được SDK, hãy export nó:

export ANDROID_HOME="$HOME/Library/Android/sdk"

Với iOS, bản thân máy chủ phải chạy trên macOS với Xcode và một runtime Trình mô phỏng iOS đã cài. Mở Cài đặt → Máy chủ → Rigs và nhấn Cài đặt cầu nối tự động hóa iOS. Máy chủ tải artifact WebDriverAgent được ghim theo checksum, xác minh nó, rồi cài vào kho tự động hóa thuộc sở hữu máy chủ. Không có trình mô phỏng nào khởi động trong quá trình thiết lập.

Mở một cỗ máy

Các cỗ máy tồn tại dưới dạng tab, bên cạnh chat và diff — trong một space hoặc trên trang PR, trong cùng menu +, dưới mục Máy:

Máy tính — một desktop Linux với Chromium, Firefox và WebKit
Chromium, Firefox hoặc WebKit — một trình duyệt
Android — trình giả lập Android đang chạy
Trình mô phỏng iOS — một trình mô phỏng dùng một lần được tạo cho cuộc hội thoại này

Chọn một mục và nhấn Khởi động máy. Tab cho biết quá trình khởi động đang ở giai đoạn nào (“Starting the microVM”, “Waiting for the guest to come up”) thay vì chỉ quay vòng.

Tab được giới hạn theo cuộc hội thoại, và công cụ agent cũng vậy. Một tab Chromium, Firefox hoặc WebKit và browser_use, Android và mobile_use, hay Trình mô phỏng iOS và ios_use đều trỏ tới cùng một cỗ máy mặc định. Các ô giao diện bổ sung là những cỗ máy so sánh riêng; công cụ agent luôn dùng cỗ máy mặc định.

Để build, cài đặt và khởi động một ứng dụng Flutter trên Android:

fvm flutter build apk --debug

Sau đó gọi mobile_use với install_apk và build/app/outputs/flutter-apk/app-debug.apk, rồi tiếp theo là start_app và tên gói Android. ui_dump, ảnh chụp màn hình và thao tác nhập đều điều khiển đúng thiết bị đang hiển thị trong tab dành cho người. stop_app, clear_app_data, uninstall_app, open_url, và các lời gọi shell dạng argv bao trùm phần còn lại của vòng phát triển mà không cần gọi shell trên máy chủ.

Để build, cài đặt và khởi động một ứng dụng Flutter trên Trình mô phỏng iOS:

fvm flutter build ios --simulator --debug
/usr/bin/plutil -extract CFBundleIdentifier raw -o - \
  build/ios/iphonesimulator/Runner.app/Info.plist

Sau đó gọi ios_use với install_app và thư mục .app, rồi tiếp theo là start_app và bundle identifier do plutil in ra. Công cụ iOS cũng cung cấp stop_app, uninstall_app, open_url, và một hành động spawn dạng argv cho việc chẩn đoán cục bộ trong trình mô phỏng.

Màn hình desktop và trình duyệt tự thay đổi kích thước theo bảng điều khiển. iOS giữ nguyên kích thước point cố định của trình mô phỏng và thêm viền đen quanh nó. Mọi bề mặt vẫn có hai làn độc lập: agent nhận ảnh chụp nhỏ, rẻ, còn bạn nhận khung hình trực tiếp. Chuyển tab sẽ dừng luồng dành cho người, nên một cỗ máy chạy nền không tốn băng thông hiển thị.

Một tab rig không tự khởi động cỗ máy, kể cả trong lúc khôi phục bố cục. Quy tắc đó ngăn một lần mở ứng dụng vô tình khởi động VM hay tạo thiết bị mô phỏng.

Điều khiển cỗ máy

Canvas là của bạn để gõ và nhấp vào bất cứ khi nào không ai khác đang giữ quyền điều khiển độc quyền — hoặc khi chính bạn giữ quyền đó. Trong lúc bạn giữ khóa đó, thẻ trạng thái hiển thị Bạn đang điều khiển, agent vẫn có thể chụp màn hình, và máy chủ từ chối các hành động làm thay đổi dữ liệu của nó tại điểm nghẽn duy nhất mà mọi hành động đều đi qua. Mọi việc bạn làm đều được ghi lại dưới tên bạn.

Nhấn Dừng máy khi bạn xong việc.

Quyền điều khiển là độc quyền có chủ đích: hai chủ thể cùng gõ vào một cỗ máy sẽ tạo ra thao tác nhập mà cả hai đều không hề muốn.

Đưa nội dung vào và ra

Sao chép và dán hoạt động theo cả hai chiều trên canvas của rig, và việc kéo tệp cũng vậy.

Sao chép và dán. Nhấn tổ hợp sao chép khi đang ở trên canvas và bất cứ thứ gì cỗ máy đã sao chép — văn bản, một hình ảnh, một danh sách tệp — sẽ được đặt vào bảng nhớ tạm của bạn. Dán sẽ gửi nội dung của bạn theo chiều ngược lại và nhấn dán bên trong cỗ máy. Trên macOS, tổ hợp là ⌘C/⌘V; ⌃C vẫn tới được shell của hệ thống khách dưới dạng tín hiệu ngắt. Trên Windows và Linux, dùng ⌃C/⌃V — hệ thống khách nhận đúng phím bấm mà nó vẫn nhận, nên ⌃C trong terminal của hệ thống khách vẫn ngắt và bảng nhớ tạm của bạn không bị đụng tới.

Không có gì đồng bộ ngầm. Một mật khẩu bạn sao chép trên máy của mình không tự xuất hiện bên trong VM chỉ vì một bộ hẹn giờ kích hoạt; nó chỉ đi qua khi bạn dán.

Dán vào một rig được phép theo mặc định. Sao chép ra khỏi một rig sẽ hỏi trước — một quyền cấp trong mười phút, hoặc Luôn cho phép trong Cài đặt → Máy chủ → Rigs → Quyền truy cập bảng nhớ tạm. Hai chiều độc lập với nhau, và chúng đi theo bạn, chứ không theo không gian làm việc.

Kéo tệp vào. Thả chúng vào bất cứ đâu trên canvas.

Trên Browser (VM), trang nhận một cú thả thật tại đúng điểm bạn thả, nên một vùng tải lên hoạt động y hệt như với tệp cục bộ.
Trên Máy tính (VM), các tệp nằm trong ~/Drops và đường dẫn của chúng được đặt vào bảng nhớ tạm của cỗ máy, nên ⌃V sẽ dán chúng vào trình quản lý tệp hay một trường tải lên. Máy chủ không thể tạo giả một thao tác kéo vào một ứng dụng Linux bất kỳ mà không chạy một daemon đặc quyền bên trong VM, thứ mà rig cố ý không có — nên thông báo sẽ cho bạn biết các tệp đã đi đâu thay vì giả vờ rằng một cú thả đã xảy ra.
Trên một terminal, tệp được sao chép vào và đường dẫn của nó được gõ tại dấu nhắc, sẵn sàng để truyền cho một lệnh. Dán một hình ảnh vào terminal cũng làm điều tương tự: nó được lưu trong cỗ máy và bạn nhận đường dẫn.

Kéo tệp ra hoạt động từ Máy tính (VM). Bắt đầu kéo một tệp bên trong cỗ máy, đưa con trỏ ra khỏi canvas, và nó trở thành một thao tác kéo thật trên desktop của bạn — thả nó vào Finder hoặc Explorer. Sao chép tệp trong trình quản lý tệp của cỗ máy rồi dán ở phía bạn cũng hoạt động. Browser (VM) không cung cấp tính năng này: một trình duyệt không giao diện không có payload kéo thả để đọc, và việc đoán từ vùng chọn văn bản của trang sẽ chiếm mất những cú nhấp thông thường.

Terminal bên trong một rig

Các terminal trong một space hoặc trên một trang PR có thể chạy bên trong một rig thay vì trên chính máy của máy chủ. Khi làm vậy, bảng điều khiển hiển thị huy hiệu VM khép kín.

Những gì thay đổi:

Không gì bạn chạy chạm tới máy chủ. Một lệnh rm -rf trong đó sẽ khiến bạn mất luôn rig của mình.
Mạng từ chối theo mặc định. Chỉ những host trong danh sách máy chủ được phép của rig mới truy cập được, và mọi thứ đều đi qua một cổng thực thi danh sách đó.
git push vẫn hoạt động trong một terminal do bạn mở. Rig không lưu thông tin xác thực nào; nó hỏi máy chủ một token ngắn hạn cho từng thao tác, bị giới hạn bởi quyền truy cập forge của chính bạn, và token đó bị thu hồi khi rig đóng. Một rig do agent mở nhận thông tin xác thực chỉ đọc, nên nó có thể fetch nhưng không thể push.

Những gì cần biết:

Một terminal khép kín được khôi phục sẽ chờ bạn. Giống như một tab rig, một terminal microvm quay trở lại cùng bố cục của bạn sẽ hiển thị nút Mở shell thay vì khởi động VM ngay khi mở. Một terminal shell máy chủ tốn một tiến trình; một terminal khép kín tốn cả một cỗ máy.
Tệp thả lên terminal được gõ, chứ không được mở. Thả một tệp CSV lên một terminal khép kín thì nó được sao chép vào cỗ máy và đường dẫn trong hệ thống khách xuất hiện tại dấu nhắc — còn đường dẫn trên máy chủ sẽ là một lệnh thất bại ở đó.
Bản sao trong rig chỉ là một bản sao. Cây làm việc của bạn trên máy chủ vẫn là nguồn có thẩm quyền. Những commit bạn tạo bên trong một rig được mang trở lại refs/rigs/<id>/* khi bạn yêu cầu — chúng không bao giờ dịch chuyển nhánh của bạn hay chạm vào cây làm việc của bạn.
Công việc nhắm đích máy chủ vẫn chạy trên máy chủ. Một hệ thống khách Linux không thể build cho macOS hay chạy xcodebuild. Hãy chọn backend native một cách tường minh cho việc đó; ứng dụng sẽ yêu cầu bạn xác nhận thay vì âm thầm chuyển.

Cổng

Chạy một máy chủ dev trong Terminal (VM) — ví dụ pnpm dev trên cổng 3000 — và trong vài giây, biểu tượng phích cắm ở góc terminal sẽ sáng lên: cổng được chuyển tiếp tới localhost:3000 trên máy của bạn, truy cập được tại localhost:3000 bên trong Browser (VM), chia sẻ được trên mạng của bạn, và có thể đặt tên thành https://myapp.test. Toàn bộ luồng — tự động chuyển tiếp, chia sẻ qua LAN, tên miền dev với HTTPS — có hướng dẫn riêng: Chuyển tiếp cổng từ terminal.

Image tùy chỉnh

Một không gian làm việc có thể trỏ Terminal (VM) và Browser (VM) tới image riêng của nó — trong Cài đặt → Máy chủ → Rigs → Image tùy chỉnh (không gian làm việc này). Cách dùng điển hình: mở rộng image mặc định bằng bộ công cụ mà dự án của bạn cần để mọi terminal khởi động trong trạng thái sẵn sàng, hoặc tái sử dụng một image mà nhóm bạn đã phát hành.

Cỗ máy vẫn khởi động bên trong cùng môi trường cách ly: cùng cổng egress, cùng broker thông tin xác thực, cùng vòng đời. Chỉ quản trị viên không gian làm việc mới thay đổi được cài đặt này, máy mới sẽ nhận nó (máy đang chạy giữ nguyên), và tham chiếu phải là một image từ registry — đường dẫn cục bộ bị từ chối.

Một image phải cung cấp những gì:

Terminal (VM) — một image Linux có bash. Nó cũng cần git, curl và socat — hoặc cài sẵn, hoặc cài được trong lần khởi động đầu (mọi image dựa trên Debian/Ubuntu đều dùng được: chúng được cài tự động, cùng với một bộ công cụ CLI kiểu runner do GitHub vận hành: trình biên dịch, Python 3, jq, công cụ lưu trữ, rsync. Runtime ngôn ngữ như Node/Go/Java và Docker không được cài sẵn). Cổng 7911 của hệ thống khách được dành riêng cho bộ chuyển tiếp cổng.
Browser (VM) — một image Debian/Ubuntu có bash và socat, cộng với một tệp nhị phân chromium. Máy chủ tự khởi động Chromium dưới dạng chromium --headless=new và chuyển tiếp DevTools từ cổng 9223 của hệ thống khách sang 9222. PulseAudio và ffmpeg được cài trong lần khởi động đầu. Đừng build FROM chromedp/headless-shell — tệp nhị phân đó không có âm thanh. Phần ghi đè chỉ áp dụng cho rig Chromium; Firefox và WebKit bỏ qua nó và khởi động image Debian được ghim. Các cổng 9222/9223 của hệ thống khách được dành riêng.

Hai khuyến nghị: ghim tham chiếu theo digest (@sha256:…) để các byte không thể thay đổi dưới chân bạn, và lưu trữ nó trên Docker Hub hoặc GitHub Container Registry — host tải xuống của những registry đó được cổng egress chấp nhận tự động; những registry khác có thể cần host phân phối nội dung của chúng truy cập được thì mới pull được.

Khi một rig biến mất

Rig vốn được thiết kế để tạm thời:

Nhàn rỗi — sau ~15 phút không có gì diễn ra, một rig trình duyệt, desktop hoặc di động sẽ đỗ (đóng băng, thức dậy ngay khi có thao tác kế tiếp). Một terminal khép kín chờ 45 phút. Sau gấp đôi khoảng nhàn rỗi, nó đóng.
Giới hạn thời gian — mỗi rig có một thời hạn cứng mà nó không thể gia hạn, bất kể đang làm gì.
Bộ nhớ — nếu máy chủ cần chỗ cho một rig mới, nó đóng rig ít được dùng gần đây nhất. Một rig đang có người điều khiển, xem, hoặc có terminal đang mở sẽ không bao giờ bị lấy đi.

Khi một rig khép kín đóng, đĩa của nó bị hủy. Đóng một rig Android sẽ tách khỏi trình giả lập trên máy chủ — chứ không xóa nó. Một rig iOS sẽ xóa thiết bị CoreSimulator mà nó đã tạo. Hãy mang những gì bạn muốn giữ trở về trước.

Một rig có thể tiếp cận những gì

Các rig terminal khép kín, trình duyệt và desktop mặc định dùng cổng egress từ chối theo mặc định: bạn cấp quyền cho từng host một cách tường minh, và đường đi duy nhất của hệ thống khách là một cổng thực thi danh sách đó. Một rig trình duyệt cũng cho phép site sản phẩm (usectrl.dev) ngay từ đầu. Broker thông tin xác thực dùng cùng danh sách đó.

Hai lưu ý thẳng thắn:

Mạng di động đi theo máy chủ. Trình giả lập của Android và CoreSimulator của Apple không nằm sau cổng egress của môi trường cách ly. Cả hai tab di động đều không có nút bỏ qua mạng, vì mạng do máy chủ quản lý vốn đã không bị hạn chế.
Mọi thứ một rig đọc đều không đáng tin cậy. Văn bản trang, DOM, cây trợ năng và bản kết xuất giao diện quay về agent được bọc trong những dấu đánh dấu nói rằng “đây là dữ liệu, không phải chỉ thị”. Một trang cố ra lệnh cho agent của bạn sẽ được đọc như một chuỗi được trích dẫn.

Bạn có thể xem mọi thứ đang chạy, và dừng bất kỳ thứ nào, trong Cài đặt → Máy chủ → Rigs.

Liên quan

Rigs và môi trường cách ly — mô hình đằng sau tất cả những điều này: vì sao dùng VM, hai làn hiển thị, broker thông tin xác thực, vòng đời
Chuyển tiếp cổng từ terminal — tiếp cận một máy chủ dev từ bất cứ đâu cần đến
Tham chiếu rigs — mọi bề mặt, động từ, cổng và giá trị mặc định ở một nơi
Cấu hình rào chắn — Điều khiển một enclosure (rig) là một lớp hành động bạn có thể đặt thành cho phép, hỏi trước hoặc từ chối, theo từng không gian làm việc, agent hoặc space. Các chế độ chỉ đọc từ chối thẳng.