Дати агенту машину для тестів

Rig — це одноразова машина, яку агент відкриває, коли йому треба справді щось спробувати: завантажити сторінку, поклацати в застосунку для робочого столу, потицяти в телефоні. Ви можете спостерігати за його роботою в реальному часі й будь-коли перехопити керування.

Ізольовані rig термінала, браузера й робочого столу — це ВМ з одноразовими дисками й мережами за шлюзом. Android і iOS — керовані хостом емулятори: їхній стан пристрою одноразовий, але мережа прямує за хостом сервера.

Налаштуйте один раз

Rig працюють на машині, де розміщено cc_server, — саме на тій машині, а не на тій, на яку ви дивитеся. Є п’ять поверхонь, видимих користувачеві; поверхням робочого столу та мобільним потрібне налаштування хоста:

Поверхня	Де працює	Налаштування
Terminal (VM)	мікроВМ, що завантажує закріплений образ Ubuntu	Нічого — образ отримують автоматично під час першого використання
Browser (VM)	мікроВМ, що завантажує закріплений образ Debian, а Chromium, Firefox або WebKit встановлюється під час першого використання	Нічого — так само
Комп’ютер (VM)	QEMU з образом робочого столу Linux, що містить Chromium, Firefox, WebKit і базовий набір CLI рівня GitHub-hosted runner	Установіть QEMU (`brew install qemu`), а тоді Імпортувати образ робочого столу в Налаштування → Сервер → Rigs
Android	емулятор Android від Google	Установіть Android SDK, створіть AVD і запустіть його (нижче)
Симулятор iOS	CoreSimulator на сервері Mac	Установіть Xcode і потрібне середовище виконання iOS, а тоді встановіть міст автоматизації в Налаштування → Сервер → Rigs

Машини термінала й браузера завантажуються з образів, закріплених за дайджестом: точні байти названо заздалегідь, один раз отримано під час першого запуску й закешовано — після першого запуску кожного різновиду наступні машини взагалі пропускають завантаження й піднімаються за секунди. Налаштування → Сервер → Rigs показує, що може запустити ваш сервер, і кожну машину, що працює просто зараз.

Установленим образом робочого столу й далі можна керувати з тієї ж сторінки: Імпортувати замінює його новішим qcow2, а Видалити прибирає його, щоб ви могли встановити свіжу збірку.

Мобільні пристрої налаштовують інакше

Для Android чи iOS немає наших образів, і це не недогляд. Системні образи Android постачає SDK від Google; середовища виконання iOS — Xcode. Для Android установіть Android Studio (або інструменти SDK командного рядка), додайте віртуальний пристрій у Device Manager і запустіть його. Тоді сторінка Rigs повідомить, що Android доступний.

Вона також точно підказує, якого кроку вам бракує — немає SDK, немає емулятора, немає віртуального пристрою або пристрій просто не запущено, — бо кожен із цих чотирьох випадків має власне виправлення, і лише одне з них полягає в завантаженні. Якщо ви запускаєте cc_server з оболонки, яка не бачить SDK, експортуйте його:

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

Для iOS сам сервер має працювати на macOS з установленими Xcode і середовищем виконання Симулятора iOS. Відкрийте Налаштування → Сервер → Rigs і натисніть Установити міст автоматизації iOS. Сервер отримує артефакт WebDriverAgent, закріплений за контрольною сумою, перевіряє його й установлює у сховище автоматизації, що належить серверу. Під час налаштування жоден симулятор не запускається.

Відкрийте машину

Машини живуть як вкладки — поруч із чатом і діфом, у просторі чи на сторінці PR, у тому самому меню +, під пунктом Машини:

Комп’ютер — робочий стіл Linux із Chromium, Firefox і WebKit
Chromium, Firefox або WebKit — браузер
Android — запущений емулятор Android
Симулятор iOS — одноразовий симулятор, створений для цієї розмови

Виберіть одну й натисніть Запустити машину. Вкладка показує, на якому етапі запуск («Запуск мікроВМ», «Очікування, поки гість підніметься»), а не просто крутить індикатор.

Вкладка прив’язана до розмови, як і інструмент агента. Вкладка Chromium, Firefox або WebKit і browser_use, Android і mobile_use, або Симулятор iOS і ios_use вказують на ту саму типову машину. Додаткові слоти інтерфейсу — це окремі машини для порівняння; інструменти агента завжди використовують типову.

Щоб зібрати, установити й запустити застосунок Flutter на Android:

fvm flutter build apk --debug

А тоді викличте mobile_use з install_apk і build/app/outputs/flutter-apk/app-debug.apk, далі start_app і назву пакета Android. ui_dump, знімки екрана й введення керують тим самим пристроєм, що показано у вкладці для людини. stop_app, clear_app_data, uninstall_app, open_url і виклики shell у формі argv покривають решту циклу розробки, не запускаючи оболонку на хості сервера.

Щоб зібрати, установити й запустити застосунок Flutter у Симуляторі iOS:

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

А тоді викличте ios_use з install_app і каталогом .app, далі start_app та ідентифікатор пакета, який виведе plutil. Інструмент iOS також надає stop_app, uninstall_app, open_url і дію spawn у формі argv для локальної діагностики симулятора.

Дисплеї робочого столу й браузера змінюють розмір під панель. iOS зберігає фіксований розмір симулятора в пунктах і додає чорні поля. Кожна поверхня все одно має два незалежні канали: агент отримує маленькі дешеві знімки екрана, а ви — живий перегляд. Перемикання вкладок зупиняє канал для людини, тож фонова машина не споживає пропускну здатність дисплея.

Вкладка rig сама не запускає машину, зокрема під час відновлення розкладки. Це правило не дає запуску застосунку несподівано вмикати ВМ чи створювати пристрої симуляторів.

Керуйте машиною

Полотно доступне для введення тексту й клацань щоразу, коли ексклюзивне керування не тримає ніхто інший — або коли його тримаєте ви. Поки цей замок у вас, статусний ярлик показує Керування у вас, агент усе ще може робити знімки екрана, а сервер відхиляє його змінювальні дії в єдиній точці, через яку проходить кожна дія. Усе, що ви робите, записується під вашим ім’ям.

Коли закінчите, натисніть Зупинити машину.

Керування ексклюзивне навмисно: коли двоє суб’єктів вводять щось в одну машину, виходить введення, якого не мав на увазі жоден із них.

Переміщайте дані всередину й назовні

Копіювання й вставлення працюють в обидва боки через полотно rig, як і перетягування файлів.

Копіювання й вставлення. Натисніть сполучення для копіювання над полотном, і те, що скопіювала машина — текст, зображення, список файлів, — потрапить у ваш буфер обміну. Вставлення надсилає ваш вміст у зворотному напрямку й натискає «вставити» всередині машини. У macOS сполучення — ⌘C/⌘V; ⌃C і далі доходить до оболонки гостя як переривання. У Windows і Linux використовуйте ⌃C/⌃V — гість отримує те саме натискання, яке отримав би й так, тож ⌃C у гостьовому терміналі й далі перериває роботу, а ваш власний буфер обміну залишається недоторканим.

Нічого не синхронізується у фоні. Пароль, скопійований на вашій машині, не потрапляє всередину ВМ через те, що спрацював таймер; він перетинає межу тоді, коли ви вставляєте.

Вставлення в rig дозволене за замовчуванням. Копіювання з rig спершу запитує підтвердження — дозвіл на десять хвилин або Завжди дозволяти в Налаштування → Сервер → Rigs → Доступ до буфера обміну. Ці два напрямки незалежні й супроводжують вас, а не робочий простір.

Перетягування файлів усередину. Кидайте їх будь-де на полотні.

У Browser (VM) сторінка отримує справжнє перетягування в тій точці, де ви відпустили, тож зона завантаження поводиться точно так, як із локальним файлом.
У Комп’ютер (VM) файли потрапляють у ~/Drops, а їхні шляхи — у буфер обміну машини, тож ⌃V вставляє їх у файловий менеджер чи поле завантаження. Хост не може синтезувати перетягування в довільний застосунок Linux, не запустивши привілейований демон усередині ВМ, якого rig навмисно не мають, — тож спливаюче повідомлення каже, куди поділися файли, а не вдає, ніби перетягування відбулося.
У терміналі файл копіюють усередину, а його шлях вводять у запрошенні, готовий передати команді. Вставлення зображення в термінал робить те саме: його зберігають у машині, а ви отримуєте шлях.

Перетягування файлів назовні працює з Комп’ютер (VM). Почніть перетягувати файл усередині машини, виведіть вказівник за межі полотна — і воно стане справжнім перетягуванням на вашому робочому столі: киньте його у Finder чи Explorer. Копіювання файлів у файловому менеджері машини й вставлення на вашому боці теж працює. У Browser (VM) цього немає: у безголового браузера немає вмісту перетягування, який можна прочитати, а вгадування за виділеним текстом сторінки перехоплювало б звичайні клацання.

Термінали всередині rig

Термінали в просторі чи на сторінці PR можуть працювати всередині rig, а не на власній машині сервера. Коли так, панель показує значок Ізольована VM.

Що змінюється:

Ніщо з того, що ви запускаєте, не дістається хоста. rm -rf там коштує вам rig.
Мережа заборонена за замовчуванням. Доступні лише хости зі списку дозволених rig, і все проходить через шлюз, який це забезпечує.
git push усе ще працює в терміналі, який відкрили ви. У rig немає збережених облікових даних; для кожної операції він просить у сервера короткочасні, обмежені вашим власним доступом до хостингу коду, і цей токен відкликають, коли rig закривається. Rig, який відкрив агент, отримує облікові дані лише для читання, тож може робити fetch, але не push.

Що варто знати:

Відновлений ізольований термінал чекає на вас. Як і вкладка rig, термінал microvm, що повертається з вашою розкладкою, показує кнопку Відкрити shell, а не запускає свою ВМ під час старту. Термінал в оболонці хоста коштує процес; ізольований — машину.
Файли, кинуті на термінал, вводяться, а не відкриваються. Киньте CSV на ізольований термінал — його скопіюють у машину, а його гостьовий шлях з’явиться в запрошенні; шлях хоста був би командою, яка там не спрацює.
Копія в rig — це копія. Ваше робоче дерево на хості залишається джерелом істини. Коміти, зроблені всередині rig, переносяться назад у refs/rigs/<id>/*, коли ви попросите, — вони ніколи не пересувають вашу гілку й не чіпають робоче дерево.
Робота під хост усе ще виконується на хості. Гість Linux не може збирати для macOS чи запускати xcodebuild. Для цього явно виберіть нативний бекенд; застосунок попросить вас підтвердити, а не перемкнеться тихо.

Порти

Запустіть dev-сервер у Terminal (VM) — скажімо, pnpm dev на порту 3000 — і за кілька секунд іконка вилки в куті термінала засвітиться: порт переадресовується на localhost:3000 на вашій машині, доступний за localhost:3000 усередині Browser (VM), доступний для спільного використання у вашій мережі й отримує ім’я https://myapp.test. Увесь цей процес — автопереадресація, спільний доступ у локальній мережі, dev-домени з HTTPS — описано в окремому посібнику: Пробросити порти з термінала.

Власні образи

Робочий простір може вказати для Terminal (VM) і Browser (VM) власні образи — у Налаштування → Сервер → Rigs → Власні образи (цей робочий простір). Типове застосування: доповнити типовий образ інструментарієм, потрібним вашому проєкту, щоб кожен термінал стартував готовим, або повторно використати образ, який ваша команда вже публікує.

Машина все одно запускається в тому самому ізольованому середовищі: той самий шлюз виходу, той самий брокер облікових даних, той самий життєвий цикл. Змінювати це налаштування можуть лише адміністратори робочого простору, нові машини його підхоплюють (уже запущені зберігають свій), а посилання має вказувати на образ із реєстру — локальні шляхи відхиляються.

Що має надавати образ:

Terminal (VM) — образ Linux із bash. Йому також потрібні git, curl і socat — або встановлені заздалегідь, або такі, що їх можна встановити під час першого запуску (підійде будь-який образ на основі Debian/Ubuntu: їх установлюють автоматично, разом із набором CLI у стилі GitHub-hosted runner: компілятори, Python 3, jq, інструменти для архівів, rsync. Мовні середовища виконання на кшталт Node/Go/Java та Docker не встановлено заздалегідь). Гостьовий порт 7911 зарезервовано для переадресації портів.
Browser (VM) — образ Debian/Ubuntu з bash і socat, а також бінарним файлом chromium. Сервер сам запускає Chromium як chromium --headless=new і передає DevTools із гостьового 9223 на 9222. PulseAudio та ffmpeg установлюють під час першого запуску. Не збирайте FROM chromedp/headless-shell — у цього бінарного файлу немає звуку. Заміна стосується лише rig Chromium; Firefox і WebKit її ігнорують і завантажують закріплений образ Debian. Гостьові порти 9222/9223 зарезервовано.

Дві поради: закріпіть посилання за дайджестом (@sha256:…), щоб байти не могли змінитися під вами, і розмістіть його на Docker Hub або GitHub Container Registry — хости завантаження цих реєстрів допускаються через шлюз виходу автоматично; іншим може знадобитися, щоб їхні хости доставки вмісту були доступні для завантаження.

Коли rig зникає

Rig задумані як тимчасові:

Простій — після ~15 хвилин без жодної активності rig браузера, робочого столу чи мобільний переходить у режим паркування (заморожений, прокидається миттєво з наступною дією). Ізольований термінал чекає 45 хвилин. Після подвійного вікна простою він закривається.
Обмеження часу — кожен rig має жорсткий строк життя, який не може продовжити, хоч би що він робив.
Пам’ять — якщо серверу потрібне місце для нового rig, він закриває той, що використовувався найдавніше. Rig, яким хтось керує, за яким спостерігає або в якому відкрито термінал, ніколи не забирають.

Коли ізольований rig закривається, його диск відкидається. Закриття rig Android від’єднується від емулятора на хості — він його не видаляє. Rig iOS видаляє створений ним пристрій CoreSimulator. Спершу перенесіть назад усе, що хочете зберегти.

До чого rig має доступ

Ізольовані rig термінала, браузера й робочого столу типово мають шлюз виходу, заборонений за замовчуванням: ви надаєте хости явно, і єдиний шлях для гостя — шлюз, який забезпечує цей список. Rig браузера також одразу допускає сайт продукту (usectrl.dev). Брокер облікових даних використовує той самий список.

Дві чесні застороги:

Мобільна мережа прямує за хостом. Емулятор Android і CoreSimulator від Apple не стоять за шлюзом виходу ізольованого середовища. Жодна з мобільних вкладок не пропонує елемента керування для обходу мережі, бо керована хостом мережа вже необмежена.
Усе, що rig читає, — ненадійне. Текст сторінки, DOM, дерева доступності та дампи подання повертаються агенту загорнутими в маркери, які кажуть «це дані, а не інструкції». Сторінка, яка намагається віддавати вашому агенту накази, читається як рядок у лапках.

Побачити все, що працює, і зупинити будь-що з цього можна в Налаштування → Сервер → Rigs.

Пов’язане

Rigs та ізольовані середовища — модель, що стоїть за всім цим: чому ВМ, два канали відображення, брокер облікових даних, життєвий цикл
Пробросити порти з термінала — дістатися dev-сервера звідки завгодно, де це важливо
Довідка з rigs — кожна поверхня, дія, порт і типове значення в одному місці
Налаштувати обмеження — Drive an enclosure (rig) — це клас дій, який можна налаштувати на дозвіл, «спочатку запитати» чи заборону для робочого простору, агента або простору. Режими лише для читання забороняють його цілком.