diff --git a/docs/uk/concepts/mantis.md b/docs/uk/concepts/mantis.md index bdd0568d6..63f92afe2 100644 --- a/docs/uk/concepts/mantis.md +++ b/docs/uk/concepts/mantis.md @@ -1,85 +1,85 @@ --- read_when: - - Створення або запуск візуальної QA-перевірки наживо для помилок OpenClaw - - Додавання перевірки до та після для запиту на злиття - - Додавання сценаріїв Discord, Slack, WhatsApp або інших реальних транспортів + - Створення або запуск живого візуального QA для помилок OpenClaw + - Додавання перевірки до й після для запиту на злиття + - Додавання сценаріїв для Discord, Slack, WhatsApp або інших транспортних механізмів реального часу - Налагодження QA-запусків, які потребують знімків екрана, автоматизації браузера або доступу через VNC -summary: Mantis — це візуальна система наскрізної перевірки для відтворення помилок OpenClaw на живих транспортах, збирання доказів до та після та прикріплення артефактів до PR. +summary: Mantis — це візуальна система наскрізної перевірки для відтворення помилок OpenClaw у live transports, захоплення доказів до й після та прикріплення артефактів до PR. title: Богомол x-i18n: - generated_at: "2026-05-04T01:25:50Z" + generated_at: "2026-05-04T02:51:58Z" model: gpt-5.5 provider: openai - source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d + source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164 source_path: concepts/mantis.md workflow: 16 --- -Mantis — це система наскрізної перевірки OpenClaw для помилок, яким потрібні реальне -середовище виконання, реальний транспорт і видимий доказ. Вона запускає сценарій на відомому -поганому ref, збирає докази, запускає той самий сценарій на кандидатному ref і +Mantis — це система наскрізної перевірки OpenClaw для помилок, яким потрібні реальне середовище виконання, +реальний транспорт і видимий доказ. Вона запускає сценарій на відомому +поганому посиланні, збирає докази, запускає той самий сценарій на кандидатному посиланні й публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або з локальної команди. -Mantis починає з Discord, бо Discord дає нам цінну першу лінію: -реальну автентифікацію бота, реальні канали guild, реакції, threads, нативні команди та -браузерний інтерфейс, у якому люди можуть візуально підтвердити, що показав транспорт. +Mantis починає з Discord, тому що Discord дає нам першу лінію з високою цінністю: +реальна автентифікація бота, реальні канали гільдії, реакції, треди, нативні команди й +браузерний інтерфейс, де люди можуть візуально підтвердити, що показав транспорт. ## Цілі -- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку бачать - користувачі. -- Зібрати артефакт **before** на базовому ref перед застосуванням виправлення. -- Зібрати артефакт **after** на кандидатному ref після застосування виправлення. -- Використовувати детермінований оракул, коли це можливо, наприклад читання реакції через Discord REST - або перевірку transcript каналу. -- Збирати скриншоти, коли помилка має видиму поверхню UI. -- Запускати локально з CLI, керованого агентом, і віддалено з GitHub. -- Зберігати достатньо стану машини для VNC-рятування, коли вхід, браузерна автоматизація або - автентифікація провайдера зависає. -- Публікувати стислий статус в операторський канал Discord, коли запуск заблоковано, +- Відтворити помилку з issue або PR на GitHub з тією самою формою транспорту, яку + бачать користувачі. +- Зібрати артефакт **до** на базовому посиланні перед застосуванням виправлення. +- Зібрати артефакт **після** на кандидатному посиланні після застосування виправлення. +- Використовувати детермінований оракул, коли це можливо, наприклад читання реакцій + через Discord REST або перевірку транскрипту каналу. +- Збирати скриншоти, коли помилка має видиму поверхню інтерфейсу. +- Запускатися локально з CLI, керованого агентом, і віддалено з GitHub. +- Зберігати достатньо стану машини для відновлення через VNC, коли вхід, автоматизація браузера або + автентифікація провайдера застрягає. +- Публікувати стислий статус в операторський канал Discord, коли запуск заблокований, потребує ручної допомоги через VNC або завершується. ## Нецілі -- Mantis не замінює модульні тести. Запуск Mantis зазвичай має перетворитися на - менший регресійний тест після того, як виправлення стане зрозумілим. -- Mantis не є звичайним швидким CI-гейтом. Він повільніший, використовує живі облікові дані та - призначений для помилок, де живе середовище має значення. -- Mantis не повинен вимагати людини для нормальної роботи. Ручний VNC — це шлях +- Mantis не є заміною модульних тестів. Запуск Mantis зазвичай має перетворитися + на менший регресійний тест після того, як виправлення зрозуміле. +- Mantis не є звичайним швидким CI-гейтом. Він повільніший, використовує живі облікові дані й + призначений для помилок, де важливе живе середовище. +- Mantis не має вимагати участі людини для нормальної роботи. Ручний VNC — це шлях відновлення, а не основний сценарій. -- Mantis не зберігає сирі секрети в артефактах, логах, скриншотах, Markdown +- Mantis не зберігає необроблені секрети в артефактах, журналах, скриншотах, Markdown- звітах або коментарях PR. -## Відповідальність +## Власність -Mantis живе у QA-стеку OpenClaw. +Mantis живе в стеку QA OpenClaw. -- OpenClaw відповідає за середовище виконання сценаріїв, транспортні адаптери, схему доказів і - локальний CLI у `pnpm openclaw qa mantis`. -- QA Lab відповідає за компоненти live transport harness, помічники браузерного захоплення та - записувачі артефактів. -- Crabbox відповідає за прогріті Linux-машини, коли потрібна віддалена VM. -- GitHub Actions відповідає за віддалену точку входу workflow і збереження артефактів. -- ClawSweeper відповідає за маршрутизацію коментарів GitHub: розбір команд мейнтейнерів, - запуск workflow і публікацію фінального коментаря PR. -- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування, - налагодження або повідомлення про застряглий стан. +- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і + локальним CLI під `pnpm openclaw qa mantis`. +- QA Lab володіє частинами живого транспортного стенда, допоміжними засобами захоплення браузера й + записувачами артефактів. +- Crabbox володіє прогрітими Linux-машинами, коли потрібна віддалена VM. +- GitHub Actions володіє віддаленою точкою входу робочого процесу й зберіганням артефактів. +- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів, + запуском робочого процесу й публікацією фінального коментаря PR. +- Агенти OpenClaw керують Mantis через Codex, коли сценарій потребує агентного налаштування, + налагодження або звітування про застряглий стан. -Ця межа тримає знання про транспорт в OpenClaw, планування машин у -Crabbox, а клей мейнтейнерського workflow у ClawSweeper. +Ця межа утримує знання про транспорт в OpenClaw, планування машин у +Crabbox, а зв’язувальний шар робочого процесу мейнтейнерів у ClawSweeper. -## Форма команд +## Форма команди -Перша локальна команда перевіряє Discord-бота, guild, канал, надсилання повідомлення, -надсилання реакції та шлях артефактів: +Перша локальна команда перевіряє бота Discord, гільдію, канал, надсилання повідомлення, +надсилання реакції й шлях артефактів: ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Локальний runner для before і after приймає таку форму: +Локальний runner для до й після приймає таку форму: ```bash pnpm openclaw qa mantis run \ @@ -90,61 +90,106 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Runner створює від’єднані worktree для baseline і candidate у каталозі output, -встановлює залежності, збирає кожен ref, запускає сценарій з +Runner створює відокремлені базове й кандидатне робочі дерева в каталозі виводу, +встановлює залежності, збирає кожне посилання, запускає сценарій з `--allow-failures`, а потім записує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md`. Для першого сценарію Discord успішна перевірка -означає, що статус baseline — `fail`, а статус candidate — `pass`. +означає, що базовий статус — `fail`, а кандидатний статус — `pass`. -Перша VM/браузерна примітива — desktop smoke: +Перший примітив VM/браузера — це димова перевірка робочого столу: ```bash pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -Вона орендує або повторно використовує desktop-машину Crabbox, запускає видимий браузер усередині -VNC-сесії, захоплює desktop, забирає артефакти назад у локальний output -каталог і записує команду перепідключення у звіт. Команда за замовчуванням -використовує провайдера Hetzner, бо це перший провайдер із робочим desktop/VNC -покриттям у лінії Mantis. Перевизначте це через `--provider`, `--crabbox-bin` або -`OPENCLAW_MANTIS_CRABBOX_PROVIDER`, коли запускаєте проти іншого fleet Crabbox. +Він орендує або повторно використовує настільну машину Crabbox, запускає видимий браузер усередині +VNC-сесії, захоплює робочий стіл, стягує артефакти назад у локальний каталог +виводу й записує команду повторного підключення у звіт. За замовчуванням команда +використовує провайдера Hetzner, тому що це перший провайдер з робочим покриттям desktop/VNC +у лінії Mantis. Перевизначайте це за допомогою `--provider`, `--crabbox-bin` або +`OPENCLAW_MANTIS_CRABBOX_PROVIDER` під час запуску проти іншого парку Crabbox. -Корисні прапорці desktop smoke: +Корисні прапорці димової перевірки робочого столу: -- `--lease-id ` або `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` повторно використовує прогрітий desktop. -- `--browser-url ` змінює сторінку, що відкривається у видимому браузері. -- `--html-file ` рендерить repo-local HTML-артефакт у видимому браузері. Mantis використовує це, щоб захопити згенерований timeline status-reaction Discord через реальний Crabbox desktop. -- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` залишає новостворений успішний lease відкритим для VNC-інспекції. Невдалі запуски за замовчуванням залишають lease, коли він був створений, щоб оператор міг перепідключитися. -- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини та час життя lease. +- `--lease-id ` або `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` повторно використовує прогрітий робочий стіл. +- `--browser-url ` змінює сторінку, відкриту у видимому браузері. +- `--html-file ` відображає локальний HTML-артефакт репозиторію у видимому браузері. Mantis використовує це для захоплення згенерованої часової шкали статусних реакцій Discord через реальний робочий стіл Crabbox. +- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` залишає новостворену успішну оренду відкритою для перевірки через VNC. Невдалі запуски за замовчуванням зберігають оренду, якщо її було створено, щоб оператор міг повторно підключитися. +- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини й час життя оренди. -GitHub smoke workflow — `Mantis Discord Smoke`. GitHub workflow before і after -для першого реального сценарію — `Mantis Discord Status Reactions`. Він +Перший повний примітив настільного транспорту — це димова перевірка Slack на робочому столі: + +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --output-dir .artifacts/qa-e2e/mantis/slack-desktop \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` + +Він орендує або повторно використовує настільну машину Crabbox, синхронізує поточний checkout у +VM, запускає `pnpm openclaw qa slack` усередині цієї VM, відкриває Slack Web у VNC- +браузері, захоплює видимий робочий стіл і копіює як артефакти Slack QA, так і +VNC-скриншот назад у локальний каталог виводу. Це перша форма Mantis, +де SUT Gateway OpenClaw і браузер обидва живуть усередині однієї +настільної Linux VM. + +З `--gateway-setup` команда готує постійний одноразовий дім OpenClaw +у `$HOME/.openclaw-mantis/slack-openclaw`, патчить конфігурацію Slack Socket Mode +для вибраного каналу, запускає `openclaw gateway run` на порту +`38973` і тримає Chrome запущеним у VNC-сесії. Це режим "залиш мені +Linux-робочий стіл зі Slack і запущеним claw"; лінія Slack QA бот-до-бота +залишається типовою, коли `--gateway-setup` опущено. + +Обов’язкові вхідні дані для `--credential-source env`: + +- `OPENCLAW_QA_SLACK_CHANNEL_ID` +- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` +- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` +- `OPENCLAW_LIVE_OPENAI_KEY` для віддаленої модельної лінії. Якщо локально задано лише + `OPENAI_API_KEY`, Mantis зіставляє його з `OPENCLAW_LIVE_OPENAI_KEY` + перед викликом Crabbox, щоб пересилання env `OPENCLAW_*` у Crabbox могло передати його + у VM. + +Корисні прапорці Slack для робочого столу: + +- `--lease-id ` повторно запускає на машині, де оператор уже увійшов у Slack Web через VNC. +- `--gateway-setup` запускає постійний OpenClaw Slack Gateway у VM замість того, щоб лише запускати лінію QA бот-до-бота. +- `--slack-url ` відкриває конкретну URL-адресу Slack Web. Без нього Mantis виводить `https://app.slack.com/client//` зі Slack `auth.test`, коли доступний токен SUT-бота. +- `--slack-channel-id ` керує allowlist каналу Slack, який використовується налаштуванням Gateway. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` керує постійним профілем Chrome усередині VM. Типове значення — `$HOME/.config/openclaw-mantis/slack-chrome-profile`, тож ручний вхід у Slack Web переживає повторні запуски на тій самій оренді. +- `--credential-source convex --credential-role ci` використовує спільний пул облікових даних замість прямих env-токенів Slack. +- `--provider-mode`, `--model`, `--alt-model` і `--fast` передаються до живої лінії Slack. + +Димовий робочий процес GitHub — `Mantis Discord Smoke`. Робочий процес GitHub +до й після для першого реального сценарію — `Mantis Discord Status Reactions`. Він приймає: -- `baseline_ref`: ref, який має відтворювати поведінку queued-only. -- `candidate_ref`: ref, який має показувати `queued -> thinking -> done`. +- `baseline_ref`: посилання, яке має відтворити поведінку лише queued. +- `candidate_ref`: посилання, яке має показати `queued -> thinking -> done`. -Він checkout-ить ref workflow harness, збирає окремі worktree baseline і candidate, -запускає `discord-status-reactions-tool-only` для кожного worktree і +Він checkout-ить посилання стенда робочого процесу, збирає окремі базове й кандидатне +робочі дерева, запускає `discord-status-reactions-tool-only` проти кожного робочого дерева та завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як -артефакти Actions. Він також рендерить HTML timeline кожної лінії у Crabbox -desktop browser і публікує ці VNC-скриншоти поруч із детермінованими -timeline PNG у коментарі PR. Workflow збирає Crabbox CLI з -`openclaw/crabbox` main, щоб він міг використовувати поточні прапорці desktop/browser lease -до наступного випуску бінарника Crabbox. +артефакти Actions. Він також рендерить HTML часової шкали кожної лінії у браузері +робочого столу Crabbox і публікує ці VNC-скриншоти поруч із детермінованими +PNG часової шкали в коментарі PR. Робочий процес збирає Crabbox CLI з +`openclaw/crabbox` main, щоб він міг використовувати поточні прапорці оренди desktop/browser +до того, як буде випущено наступний бінарний реліз Crabbox. -Ви також можете запустити status-reactions run напряму з коментаря PR: +Ви також можете запустити запуск статусних реакцій напряму з коментаря PR: ```text @Mantis discord status reactions ``` -Тригер коментаря навмисно вузький. Він запускається лише для коментарів pull request +Тригер коментаря навмисно вузький. Він запускається лише на коментарях pull request від користувачів із доступом write, maintain або admin, і розпізнає лише -запити status-reaction Discord. За замовчуванням він використовує відомий поганий baseline ref -і поточний SHA head PR як candidate. Мейнтейнери можуть перевизначити будь-який -ref: +запити статусних реакцій Discord. За замовчуванням він використовує відоме погане базове посилання +і поточний SHA голови PR як кандидата. Мейнтейнери можуть перевизначити будь-яке +посилання: ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -157,49 +202,49 @@ ref: @clawsweeper verify e2e discord ``` -Перша команда явна й сфокусована на сценарії. Друга згодом може зіставляти PR -або issue з рекомендованими сценаріями Mantis на основі labels, змінених файлів і -результатів review ClawSweeper. +Перша команда явна й сфокусована на сценарії. Друга пізніше може зіставляти PR +або issue з рекомендованими сценаріями Mantis на основі міток, змінених файлів і +висновків рев’ю ClawSweeper. ## Життєвий цикл запуску 1. Отримати облікові дані. 2. Виділити або повторно використати VM. -3. Підготувати профіль desktop/browser, коли сценарію потрібні UI-докази. -4. Підготувати чистий checkout для baseline ref. -5. Встановити залежності та зібрати лише те, що потрібно сценарію. +3. Підготувати профіль робочого столу/браузера, коли сценарію потрібні докази інтерфейсу. +4. Підготувати чистий checkout для базового посилання. +5. Встановити залежності й зібрати лише те, що потрібно сценарію. 6. Запустити дочірній OpenClaw Gateway з ізольованим каталогом стану. -7. Налаштувати live transport, провайдера, модель і профіль браузера. -8. Запустити сценарій і зібрати baseline-докази. -9. Зупинити gateway і зберегти логи. -10. Підготувати candidate ref у тій самій VM. -11. Запустити той самий сценарій і зібрати candidate-докази. -12. Порівняти результати оракула та візуальні докази. -13. Записати Markdown, JSON, логи, скриншоти та необов’язкові trace-артефакти. +7. Налаштувати живий транспорт, провайдера, модель і профіль браузера. +8. Запустити сценарій і зібрати базові докази. +9. Зупинити Gateway і зберегти журнали. +10. Підготувати кандидатне посилання в тій самій VM. +11. Запустити той самий сценарій і зібрати кандидатні докази. +12. Порівняти результати оракула й візуальні докази. +13. Записати Markdown, JSON, журнали, скриншоти й опціональні артефакти трасування. 14. Завантажити артефакти GitHub Actions. -15. Опублікувати стислий статус у PR або Discord. +15. Опублікувати стислий статусний коментар PR або повідомлення Discord. -Сценарій має вміти падати двома різними способами: +Сценарій має вміти зазнавати невдачі двома різними способами: -- **Помилку відтворено**: baseline впав очікуваним способом. -- **Помилка harness**: налаштування середовища, облікові дані, Discord API, браузер або - провайдер впали до того, як оракул помилки став значущим. +- **Помилку відтворено**: базова версія зазнала невдачі очікуваним способом. +- **Збій стенда**: налаштування середовища, облікові дані, Discord API, браузер або + провайдер зазнали невдачі до того, як оракул помилки став змістовним. Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне середовище з поведінкою продукту. ## MVP Discord -Перший сценарій має націлюватися на status reactions Discord у guild channels, де -режим доставки source reply — `message_tool_only`. +Перший сценарій має бути націлений на статусні реакції Discord у каналах гільдій, де +режим доставки вихідної відповіді — `message_tool_only`. -Чому це добрий початковий сценарій для Mantis: +Чому це добрий початковий сценарій Mantis: -- Це видно в Discord як реакції на повідомленні, яке запустило дію. +- Він видимий у Discord як реакції на тригерне повідомлення. - Він має сильний REST-оракул через стан реакцій повідомлення Discord. -- Він перевіряє реальний OpenClaw Gateway, автентифікацію Discord-бота, dispatch повідомлень, - режим доставки source reply, стан status reaction і життєвий цикл model turn. -- Він достатньо вузький, щоб перша реалізація залишалася чесною. +- Він перевіряє реальний OpenClaw Gateway, автентифікацію бота Discord, відправлення повідомлень, + режим доставки вихідної відповіді, стан статусних реакцій і життєвий цикл модельного ходу. +- Він достатньо вузький, щоб перша реалізація була чесною. Очікувана форма сценарію: @@ -232,12 +277,12 @@ evidence: screenshotMessageRow: true ``` -Baseline-докази мають показувати queued acknowledgement reaction, але без -lifecycle transition у режимі tool-only. Candidate-докази мають показувати, що lifecycle -status reactions працюють, коли `messages.statusReactions.enabled` явно -дорівнює true. +Базові докази мають показувати реакцію підтвердження queued, але без +переходу життєвого циклу в режимі лише інструмента. Кандидатні докази мають показувати, що +статусні реакції життєвого циклу працюють, коли `messages.statusReactions.enabled` явно +встановлено в true. -Виконуваний перший зріз — opt-in live QA сценарій Discord: +Перший виконуваний зріз — це opt-in живий сценарій Discord QA: ```bash pnpm openclaw qa discord \ @@ -249,30 +294,30 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Він налаштовує SUT з always-on guild handling, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` і явними status reactions. Оракул -опитує реальне Discord-повідомлення, що запустило дію, і очікує спостережену послідовність +Він налаштовує SUT із постійно ввімкненою обробкою гільдій, `visibleReplies: +"message_tool"`, `ackReaction: "👀"` та явними статусними реакціями. Оракул +опитує реальне тригерне повідомлення Discord і очікує спостережувану послідовність `👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` і `discord-status-reactions-tool-only-timeline.png`. ## Наявні компоненти QA -Mantis має будуватися на наявному приватному QA-стеку, а не починати з +Mantis має будуватися на наявному приватному стеку QA, а не починати з нуля: -- `pnpm openclaw qa discord` уже запускає live Discord line з driver і - SUT bots. -- Live transport runner уже записує звіти та observed-message - артефакти в `.artifacts/qa-e2e/`. -- Credential leases Convex уже надають ексклюзивний доступ до спільних live - transport credentials. -- Browser control service уже підтримує скриншоти, snapshots, - headless managed profiles і remote CDP profiles. -- QA Lab уже має debugger UI і bus для transport-shaped testing. +- `pnpm openclaw qa discord` вже запускає живу лінію Discord із ботами-драйвером і + SUT. +- Живий транспортний runner уже записує звіти та артефакти спостережуваних повідомлень + у `.artifacts/qa-e2e/`. +- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих + транспортних облікових даних. +- Сервіс керування браузером уже підтримує знімки екрана, snapshots, + керовані headless-профілі та віддалені CDP-профілі. +- QA Lab уже має UI налагоджувача та шину для тестування у формі транспортів. -Перша реалізація Mantis може бути тонким before/after runner поверх цих -компонентів плюс один шар візуальних доказів. +Перша реалізація Mantis може бути тонким runner до/після над цими +компонентами плюс один шар візуальних доказів. ## Модель доказів @@ -296,78 +341,77 @@ Mantis має будуватися на наявному приватному QA run.log ``` -`mantis-summary.json` має бути машинозчитуваним джерелом істини. Markdown -звіт призначений для коментарів PR і людського review. +`mantis-summary.json` має бути машинно-читабельним джерелом істини. Markdown-звіт +призначений для коментарів до PR та людського перегляду. -Summary має включати: +Підсумок має включати: -- перевірені refs і SHAs -- transport і scenario id -- machine provider і machine id або lease id -- credential source без secret values -- baseline result -- candidate result -- чи помилка відтворилася на baseline -- чи candidate виправив її -- artifact paths -- санітизовані setup або cleanup issues +- refs і SHAs, які тестувалися +- транспорт і id сценарію +- провайдера машини та id машини або id оренди +- джерело облікових даних без секретних значень +- результат baseline +- результат candidate +- чи відтворилася помилка на baseline +- чи виправив її candidate +- шляхи артефактів +- очищені проблеми налаштування або очищення -Скриншоти — це докази, а не секрети. Однак вони все одно потребують дисципліни редагування: +Знімки екрана є доказами, а не секретами. Вони все одно потребують дисципліни редагування: можуть з’являтися приватні назви каналів, імена користувачів або вміст повідомлень. Для публічних PR -віддавайте перевагу посиланням на артефакти GitHub Actions замість inline images, доки історія редагування -не стане сильнішою. +надавайте перевагу посиланням на артефакти GitHub Actions замість вбудованих зображень, доки історія редагування +не стане надійнішою. ## Браузер і VNC -Browser lane має два режими: +Браузерна лінія має два режими: -- **Headless automation**: стандартний для CI. Chrome запускається з увімкненим CDP, а - Playwright або browser control OpenClaw збирає скриншоти. -- **VNC rescue**: вмикається на тій самій VM, коли вхід, MFA, Discord anti-automation - або візуальне налагодження потребує людини. +- **Headless-автоматизація**: стандартно для CI. Chrome запускається з увімкненим CDP, а + Playwright або керування браузером OpenClaw захоплює знімки екрана. +- **VNC-рятування**: вмикається на тій самій VM, коли вхід, MFA, антиавтоматизація Discord + або візуальне налагодження потребують людини. -Профіль браузера спостерігача Discord має бути достатньо сталим, щоб не -входити в систему під час кожного запуску, але ізольованим від особистого стану -браузера. Профіль належить пулу машин Mantis, а не ноутбуку розробника. +Браузерний профіль спостерігача Discord має бути достатньо постійним, щоб уникати +входу під час кожного запуску, але ізольованим від особистого стану браузера. Профіль +належить пулу машин Mantis, а не ноутбуку розробника. Коли Mantis застрягає, він публікує статусне повідомлення Discord із: - id запуску - id сценарію -- постачальником машин +- провайдером машини - каталогом артефактів -- інструкціями підключення через VNC або noVNC, якщо доступно +- інструкціями підключення VNC або noVNC, якщо доступні - коротким текстом блокера -Перше приватне розгортання може публікувати ці повідомлення в наявний канал -операторів, а пізніше перейти до окремого каналу Mantis. +Перше приватне розгортання може публікувати ці повідомлення в наявний операторський +канал і пізніше перейти до окремого каналу Mantis. ## Машини Mantis має надавати перевагу AWS через Crabbox для першої віддаленої реалізації. -Crabbox надає нам прогріті машини, відстеження оренди, гідратацію, логи, -результати та очищення. Якщо потужності AWS надто повільні або недоступні, -додайте постачальника Hetzner за тим самим інтерфейсом машин. +Crabbox дає нам прогріті машини, відстеження оренд, hydration, журнали, результати та +очищення. Якщо місткість AWS надто повільна або недоступна, додайте провайдера Hetzner +за тим самим інтерфейсом машини. Мінімальні вимоги до VM: -- Linux з інсталяцією Chrome або Chromium, придатною для робочого столу -- доступ CDP для автоматизації браузера -- VNC або noVNC для відновлення +- Linux зі встановленим Chrome або Chromium, придатним для робочого столу +- CDP-доступ для автоматизації браузера +- VNC або noVNC для рятування - Node 22 і pnpm - checkout OpenClaw і кеш залежностей - кеш браузера Playwright Chromium, коли використовується Playwright - достатньо CPU та пам’яті для одного OpenClaw Gateway, одного браузера й одного модельного запуску -- вихідний доступ до Discord, GitHub, постачальників моделей і брокера облікових даних +- вихідний доступ до Discord, GitHub, модельних провайдерів і брокера облікових даних -VM не має зберігати довготривалі необроблені секрети поза очікуваними сховищами -облікових даних або профілю браузера. +VM не повинна зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або +браузерних профілів. ## Секрети -Секрети зберігаються в секретах організації або репозиторію GitHub для -віддалених запусків, а для локальних запусків — у локальному файлі секретів під -контролем оператора. +Секрети зберігаються в секретах організації або репозиторію GitHub для віддалених запусків і в +локальному файлі секретів під контролем оператора для локальних запусків. Рекомендовані назви секретів: @@ -383,47 +427,44 @@ VM не має зберігати довготривалі необроблен - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -У довгостроковій перспективі пул облікових даних Convex має залишатися -звичайним джерелом для живих транспортних облікових даних. Секрети GitHub -початково завантажують брокер і резервні лінії. Workflow статусних реакцій -Discord зіставляє секрети Mantis Crabbox назад зі змінними середовища -`CRABBOX_COORDINATOR` і `CRABBOX_COORDINATOR_TOKEN`, яких очікує Crabbox CLI. -Прості назви секретів GitHub `CRABBOX_*` залишаються прийнятими як резервна -сумісність. +У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом живих +транспортних облікових даних. Секрети GitHub bootstrap брокер і резервні лінії. +Workflow статусних реакцій Discord зіставляє секрети Mantis Crabbox назад із +змінними середовища `CRABBOX_COORDINATOR` і `CRABBOX_COORDINATOR_TOKEN`, +які очікує Crabbox CLI. Прості назви секретів GitHub `CRABBOX_*` залишаються +прийнятими як резервна сумісність. Runner Mantis ніколи не повинен друкувати: - токени ботів Discord -- API-ключі постачальників -- cookie браузера +- API-ключі провайдерів +- cookies браузера - вміст профілів автентифікації - паролі VNC -- необроблені payload облікових даних +- сирі payload облікових даних -Публічні завантаження артефактів також мають редагувати цільові метадані -Discord, як-от id бота, guild, каналу та повідомлення. Workflow GitHub smoke -увімкнув `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини. +Публічні завантаження артефактів також мають редагувати цільові метадані Discord, такі як id ботів, +гільдій, каналів і повідомлень. Smoke workflow GitHub вмикає +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини. -Якщо токен випадково вставили в issue, PR, чат або лог, поверніть його після -збереження нового секрету. +Якщо токен випадково вставлено в issue, PR, чат або журнал, поверніть його +після збереження нового секрету. ## Артефакти GitHub і коментарі PR -Workflow Mantis мають завантажувати повний пакет доказів як короткоживучий -артефакт Actions. Коли workflow запускається для звіту про баг або PR із -виправленням, він також має публікувати відредаговані PNG-скріншоти в гілку -`qa-artifacts` і оновлювати або створювати коментар до цього бага чи PR із -виправленням із вбудованими скріншотами до/після. Не публікуйте основний доказ -лише в загальному PR автоматизації QA. Необроблені логи, спостережені -повідомлення та інші об’ємні докази залишаються в артефакті Actions. +Workflow Mantis мають завантажувати повний пакет доказів як короткоживучий артефакт Actions. +Коли workflow запускається для звіту про помилку або PR із виправленням, він також має +публікувати відредаговані PNG-знімки екрана до гілки `qa-artifacts` і upsert +коментар до цієї помилки або PR із виправленням із вбудованими знімками екрана до/після. Не публікуйте +основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережувані +повідомлення та інші великі докази залишаються в артефакті Actions. -Виробничі workflow мають публікувати ці коментарі через GitHub App Mantis, а не -через `github-actions[bot]`. Зберігайте id застосунку та приватний ключ як -секрети GitHub Actions `MANTIS_GITHUB_APP_ID` і -`MANTIS_GITHUB_APP_PRIVATE_KEY`. Workflow використовує прихований маркер як ключ -upsert, оновлює цей коментар, коли токен може його редагувати, і створює новий -коментар, що належить Mantis, коли старіший маркер, який належить боту, не можна -редагувати. +Production workflow мають публікувати ці коментарі через GitHub App Mantis, а не +через `github-actions[bot]`. Збережіть app id і приватний ключ як секрети GitHub Actions +`MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. +Workflow використовує прихований маркер як ключ upsert, оновлює цей +коментар, коли токен може його редагувати, і створює новий коментар, власником якого є Mantis, коли +старіший маркер, власником якого є бот, неможливо редагувати. Коментар PR має бути коротким і візуальним: @@ -445,21 +486,21 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Коли запуск завершується невдало через збій harness, коментар має повідомляти -саме це, а не натякати, що кандидат не пройшов. +Коли запуск не вдається через збій harness, коментар має сказати саме це, +а не натякати, що candidate не пройшов. ## Нотатки щодо приватного розгортання -Приватне розгортання вже може мати застосунок Discord для Mantis. Повторно -використовуйте цей застосунок замість створення іншого, якщо він має потрібні -дозволи бота й може бути безпечно ротований. +Приватне розгортання може вже мати застосунок Mantis Discord. Повторно використовуйте цей +застосунок замість створення іншого, коли він має потрібні дозволи бота +і його можна безпечно ротувати. -Налаштуйте початковий канал сповіщень оператора через секрети або конфігурацію -розгортання. Спочатку він може вказувати на наявний канал мейнтейнерів або -операцій, а потім перейти до окремого каналу Mantis, щойно він з’явиться. +Налаштуйте початковий канал операторських сповіщень через секрети або конфігурацію +розгортання. Спочатку він може вказувати на наявний канал maintainers або operations, +а потім перейти до окремого каналу Mantis, щойно він з’явиться. -Не вносьте guild ids, channel ids, токени ботів, cookie браузера або паролі VNC -у цей документ. Зберігайте їх у секретах GitHub, брокері облікових даних або +Не розміщуйте guild ids, channel ids, токени ботів, cookies браузера або паролі VNC +у цьому документі. Зберігайте їх у секретах GitHub, брокері облікових даних або локальному сховищі секретів оператора. ## Додавання сценарію @@ -471,44 +512,46 @@ candidate showed the expected queued -> thinking -> done sequence. - потрібні облікові дані - політику baseline ref - політику candidate ref -- патч конфігурації OpenClaw +- config patch OpenClaw - кроки налаштування -- стимул -- очікуваний baseline oracle -- очікуваний candidate oracle +- stimulus +- очікуваний оракул baseline +- очікуваний оракул candidate - цілі візуального захоплення - бюджет timeout - кроки очищення -Сценарії мають надавати перевагу малим типізованим oracle: +Сценарії мають надавати перевагу малим типізованим оракулам: -- стан реакцій Discord для багів реакцій -- посилання на повідомлення Discord для багів тредингу -- thread ts Slack і стан API реакцій для багів Slack -- id повідомлень email і заголовки для багів email -- скріншоти браузера, коли UI є єдиним надійним спостережуваним сигналом +- стан реакцій Discord для помилок реакцій +- посилання на повідомлення Discord для помилок threading +- Slack thread ts і стан reaction API для помилок Slack +- id повідомлень email і headers для помилок email +- знімки екрана браузера, коли UI є єдиним надійним спостережуваним сигналом -Vision-перевірки мають бути додатковими. Якщо API платформи може довести баг, -використовуйте API як oracle pass/fail, а скріншоти залишайте для впевненості -людей. +Vision-перевірки мають бути додатковими. Якщо API платформи може довести помилку, використовуйте +API як оракул pass/fail і залишайте знімки екрана для людської впевненості. -## Розширення постачальників +## Розширення провайдерів Після Discord той самий runner може додати: -- Slack: реакції, треди, згадки застосунку, модальні вікна, завантаження файлів. -- Email: автентифікацію Gmail і трединг повідомлень за допомогою `gog`, коли конекторів недостатньо. -- WhatsApp: вхід через QR, повторну ідентифікацію, доставку повідомлень, медіа, реакції. -- Telegram: gating згадок у групі, команди, реакції там, де доступно. -- Matrix: зашифровані кімнати, зв’язки тредів або відповідей, відновлення після перезапуску. +- Slack: reactions, threads, app mentions, modals, file uploads. +- Email: автентифікація Gmail і threading повідомлень за допомогою `gog`, де connectors недостатньо. +- WhatsApp: QR-вхід, повторна ідентифікація, доставка повідомлень, media, reactions. +- Telegram: gating згадок у групах, commands, reactions, де доступно. +- Matrix: зашифровані rooms, thread або reply relations, restart resume. -Кожен транспорт має мати один дешевий smoke-сценарій і один або більше сценаріїв -класу багів. Дорогі візуальні сценарії мають залишатися opt-in. +Кожен транспорт має мати один дешевий smoke-сценарій і один або більше сценаріїв класу помилок. +Дорогі візуальні сценарії мають залишатися opt-in. ## Відкриті питання -- Який бот Discord має бути driver, а який SUT, коли наявний бот Mantis використовується повторно? -- Чи має вхід браузера спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис або лише REST-докази, доступні для читання ботом, на першій фазі? +- Який бот Discord має бути driver, а який SUT, коли наявний + бот Mantis використовується повторно? +- Чи має вхід браузера спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис + або лише REST-докази, доступні для читання ботом, для першої фази? - Як довго GitHub має зберігати артефакти Mantis для PR? -- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування команди мейнтейнера? -- Чи мають скріншоти редагуватися або обрізатися перед завантаженням для публічних PR? +- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування + команди maintainer? +- Чи потрібно редагувати або обрізати знімки екрана перед завантаженням для публічних PR? diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index 915a4ce54..1ba041f79 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,66 +1,67 @@ --- read_when: - - Розуміння того, як стек QA працює як єдине ціле + - Розуміння того, як компоненти стеку забезпечення якості поєднуються між собою - Розширення qa-lab, qa-channel або транспортного адаптера - Додавання QA-сценаріїв на основі репозиторію - - Побудова автоматизації QA з підвищеною реалістичністю навколо панелі керування Gateway -summary: 'Огляд стеку QA: qa-lab, qa-channel, сценарії на основі репозиторію, лінії реального транспорту, транспортні адаптери та звітування.' + - Створення реалістичнішої QA-автоматизації навколо панелі керування Gateway +summary: 'Огляд стеку QA: qa-lab, qa-channel, сценарії на основі репозиторію, лінії живого транспорту, транспортні адаптери та звітність.' title: Огляд забезпечення якості x-i18n: - generated_at: "2026-05-04T00:35:17Z" + generated_at: "2026-05-04T02:51:53Z" model: gpt-5.5 provider: openai - source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba + source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -Приватний QA-стек призначений для перевірки OpenClaw реалістичнішим, -схожим на канали способом, ніж це може зробити один модульний тест. +Приватний QA-стек призначений для перевірки OpenClaw у реалістичнішому, +канально-орієнтованому режимі, ніж це може зробити один модульний тест. -Поточні складники: +Поточні складові: - `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, - реакції, редагування та видалення. -- `extensions/qa-lab`: UI налагоджувача й QA-шина для спостереження за транскриптом, - ін’єкції вхідних повідомлень і експорту Markdown-звіту. -- `extensions/qa-matrix`, майбутні плагіни запуску: адаптери live-транспорту, які - керують реальним каналом усередині дочірнього QA gateway. -- `qa/`: seed-ресурси з репозиторію для початкового завдання та базових QA-сценаріїв. -- [Mantis](/uk/concepts/mantis): перевірка до й після наживо для помилок, яким - потрібні реальні транспорти, знімки екрана браузера, стан VM і докази PR. + реакції, редагування й видалення. +- `extensions/qa-lab`: інтерфейс налагоджувача й QA-шина для спостереження за транскриптом, + ін’єкції вхідних повідомлень та експорту Markdown-звіту. +- `extensions/qa-matrix`, майбутні runner plugins: адаптери живого транспорту, які + керують реальним каналом усередині дочірнього QA Gateway. +- `qa/`: seed-ресурси з репозиторію для стартового завдання та базових QA + сценаріїв. +- [Mantis](/uk/concepts/mantis): перевірка до й після live-валідації для багів, яким + потрібні реальні транспорти, знімки екрана браузера, стан VM і докази для PR. ## Поверхня команд -Кожен QA-потік виконується через `pnpm openclaw qa `. Багато з них мають -аліаси скриптів `pnpm qa:*`; підтримуються обидві форми. +Кожен QA-потік запускається через `pnpm openclaw qa `. Багато з них мають +псевдоніми скриптів `pnpm qa:*`; підтримуються обидві форми. -| Команда | Призначення | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | Вбудована самоперевірка QA; записує Markdown-звіт. | -| `qa suite` | Запустити сценарії з репозиторію проти QA gateway lane. Аліаси: `pnpm openclaw qa suite --runner multipass` для одноразової Linux VM. | -| `qa coverage` | Вивести markdown-інвентар покриття сценаріїв (`--json` для машинного виводу). | -| `qa parity-report` | Порівняти два файли `qa-suite-summary.json` і записати agentic parity-звіт. | -| `qa character-eval` | Запустити character QA-сценарій на кількох live-моделях зі звітом, оціненим суддею. Див. [Звітування](#reporting). | -| `qa manual` | Запустити одноразовий prompt проти вибраної provider/model lane. | -| `qa ui` | Запустити UI налагоджувача QA та локальну QA-шину (аліас: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Зібрати попередньо підготовлений QA Docker-образ. | -| `qa docker-scaffold` | Записати docker-compose scaffold для QA-дашборда + gateway lane. | -| `qa up` | Зібрати QA-сайт, запустити стек на Docker, вивести URL (аліас: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | -| `qa aimock` | Запустити лише сервер AIMock provider. | -| `qa mock-openai` | Запустити лише scenario-aware сервер provider `mock-openai`. | -| `qa credentials doctor` / `add` / `list` / `remove` | Керувати спільним пулом облікових даних Convex. | -| `qa matrix` | Live transport lane проти одноразового Tuwunel homeserver. Див. [Matrix QA](/uk/concepts/qa-matrix). | -| `qa telegram` | Live transport lane проти реальної приватної групи Telegram. | -| `qa discord` | Live transport lane проти реального приватного каналу Discord guild. | -| `qa slack` | Live transport lane проти реального приватного каналу Slack. | -| `qa mantis` | Runner перевірки до й після для помилок live transport, з доказами status-reactions у Discord і desktop/browser smoke у Crabbox. Див. [Mantis](/uk/concepts/mantis). | +| Команда | Призначення | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | Вбудована самоперевірка QA; записує Markdown-звіт. | +| `qa suite` | Запускає сценарії з репозиторію проти lane QA Gateway. Псевдоніми: `pnpm openclaw qa suite --runner multipass` для одноразової Linux VM. | +| `qa coverage` | Друкує Markdown-інвентар покриття сценаріїв (`--json` для машинного виводу). | +| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує агентний звіт про паритет. | +| `qa character-eval` | Запускає QA-сценарій персонажа на кількох live-моделях із оціненим звітом. Див. [Звітування](#reporting). | +| `qa manual` | Запускає одноразовий prompt проти вибраного lane провайдера/моделі. | +| `qa ui` | Запускає інтерфейс QA-нóлагоджувача та локальну QA-шину (псевдонім: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Збирає попередньо підготовлений QA Docker-образ. | +| `qa docker-scaffold` | Записує docker-compose scaffold для QA-панелі + lane Gateway. | +| `qa up` | Збирає QA-сайт, запускає стек на Docker, друкує URL (псевдонім: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Запускає лише сервер провайдера AIMock. | +| `qa mock-openai` | Запускає лише scenario-aware сервер провайдера `mock-openai`. | +| `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. | +| `qa matrix` | Lane живого транспорту проти одноразового homeserver Tuwunel. Див. [Matrix QA](/uk/concepts/qa-matrix). | +| `qa telegram` | Lane живого транспорту проти реальної приватної групи Telegram. | +| `qa discord` | Lane живого транспорту проти реального приватного каналу guild Discord. | +| `qa slack` | Lane живого транспорту проти реального приватного каналу Slack. | +| `qa mantis` | Runner перевірки до й після для багів живого транспорту, з доказами Discord status-reactions, desktop/browser smoke у Crabbox і Slack-in-VNC smoke. Див. [Mantis](/uk/concepts/mantis). | -## Потік оператора +## Операторський потік -Поточний потік QA-оператора — це двопанельний QA-сайт: +Поточний операторський QA-потік — це двопанельний QA-сайт: -- Ліворуч: Gateway-дашборд (Control UI) з агентом. +- Ліворуч: панель Gateway (Control UI) з агентом. - Праворуч: QA Lab, що показує Slack-подібний транскрипт і план сценарію. Запустіть його так: @@ -69,13 +70,13 @@ x-i18n: pnpm qa:lab:up ``` -Це збирає QA-сайт, запускає gateway lane на Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, -спостерігати реальну поведінку каналу й записати, що спрацювало, не спрацювало або -залишилося заблокованим. +Це збирає QA-сайт, запускає lane Gateway на Docker і відкриває сторінку +QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, +спостерігати реальну поведінку каналу та записувати, що спрацювало, що не вдалося +або що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без перебудови Docker-образу щоразу -запустіть стек із bind-mounted бандлом QA Lab: +Для швидшої ітерації QA Lab UI без перезбирання Docker-образу щоразу +запустіть стек із bind-mounted QA Lab bundle: ```bash pnpm openclaw qa docker-build-image @@ -84,38 +85,38 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` тримає Docker-сервіси на попередньо зібраному образі та bind-mount-ить +`qa:lab:up:fast` тримає Docker-сервіси на попередньо зібраному образі та bind-mount `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перезбирає цей бандл при зміні, а браузер автоматично перезавантажується, коли змінюється -хеш ресурсу QA Lab. +перезбирає цей bundle під час змін, а браузер автоматично перезавантажується, коли змінюється hash +asset-ів QA Lab. -Для локального OpenTelemetry trace smoke виконайте: +Для локального OpenTelemetry trace smoke запустіть: ```bash pnpm qa:otel:smoke ``` -Цей скрипт запускає локальний приймач трас OTLP/HTTP, виконує -QA-сценарій `otel-trace-smoke` з увімкненим плагіном `diagnostics-otel`, потім +Цей скрипт запускає локальний OTLP/HTTP trace receiver, запускає +QA-сценарій `otel-trace-smoke` з увімкненим plugin `diagnostics-otel`, потім декодує експортовані protobuf spans і перевіряє критичну для релізу форму: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` і `openclaw.message.delivery` мають бути присутні; -model calls не мають експортувати `StreamAbandoned` на успішних turns; сирі diagnostic IDs і -атрибути `openclaw.content.*` мають не потрапляти в trace. Він записує -`otel-smoke-summary.json` поруч із артефактами QA suite. +виклики моделі не повинні експортувати `StreamAbandoned` на успішних turns; сирі діагностичні ID та +атрибути `openclaw.content.*` мають залишатися поза trace. Він записує +`otel-smoke-summary.json` поруч з артефактами QA suite. -Observability QA залишається лише для source-checkout. npm tarball навмисно не містить -QA Lab, тому package Docker release lanes не виконують команди `qa`. Використовуйте -`pnpm qa:otel:smoke` із зібраного source checkout, коли змінюєте diagnostics -instrumentation. +Observability QA лишається тільки для source-checkout. npm tarball навмисно не містить +QA Lab, тому package Docker release lanes не запускають команди `qa`. Використовуйте +`pnpm qa:otel:smoke` зі зібраного source checkout під час зміни instrumentation +діагностики. -Для transport-real Matrix smoke lane виконайте: +Для transport-real Matrix smoke lane запустіть: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -Повний довідник CLI, каталог профілів/сценаріїв, env vars і структура артефактів для цієї lane містяться в [Matrix QA](/uk/concepts/qa-matrix). Коротко: він provision-ить одноразовий Tuwunel homeserver у Docker, реєструє тимчасових driver/SUT/observer users, запускає реальний Matrix-плагін усередині дочірнього QA gateway, обмеженого цим транспортом (без `qa-channel`), а потім записує Markdown-звіт, JSON summary, артефакт observed-events і об’єднаний output log у `.artifacts/qa-e2e/matrix-/`. +Повний CLI-довідник, каталог профілів/сценаріїв, env vars і структура артефактів для цього lane описані в [Matrix QA](/uk/concepts/qa-matrix). Коротко: він створює одноразовий homeserver Tuwunel у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний Matrix plugin усередині дочірнього QA Gateway, обмеженого цим транспортом (без `qa-channel`), а потім записує Markdown-звіт, JSON-підсумок, артефакт observed-events і комбінований output log у `.artifacts/qa-e2e/matrix-/`. Для transport-real Telegram, Discord і Slack smoke lanes: @@ -125,19 +126,36 @@ pnpm openclaw qa discord pnpm openclaw qa slack ``` -Вони націлені на попередньо наявний реальний канал із двома ботами (driver + SUT). Обов’язкові env vars, списки сценаріїв, output artifacts і пул облікових даних Convex задокументовані в [довіднику QA для Telegram, Discord і Slack](#telegram-discord-and-slack-qa-reference) нижче. +Вони націлені на вже наявний реальний канал із двома ботами (driver + SUT). Обов’язкові env vars, списки сценаріїв, вихідні артефакти та пул облікових даних Convex задокументовані в [довіднику QA для Telegram, Discord і Slack](#telegram-discord-and-slack-qa-reference) нижче. -Перед використанням pooled live credentials виконайте: +Для повного Slack desktop VM запуску з VNC rescue запустіть: + +```bash +pnpm openclaw qa mantis slack-desktop-smoke \ + --gateway-setup \ + --scenario slack-canary \ + --keep-lease +``` + +Ця команда орендує desktop/browser машину Crabbox, запускає Slack live lane +усередині VM, відкриває Slack Web у VNC-браузері, захоплює desktop і +копіює `slack-qa/` плюс `slack-desktop-smoke.png` назад у директорію артефактів +Mantis. Повторно використовуйте `--lease-id ` після ручного входу в Slack Web +через VNC. З `--gateway-setup` Mantis залишає постійний OpenClaw Slack +Gateway запущеним усередині VM на порту `38973`; без нього команда запускає +звичайний bot-to-bot Slack QA lane і завершується після захоплення артефактів. + +Перед використанням pooled live credentials запустіть: ```bash pnpm openclaw qa credentials doctor ``` -Doctor перевіряє env Convex broker, валідує налаштування endpoint і перевіряє доступність admin/list, коли присутній maintainer secret. Для секретів він повідомляє лише статус set/missing. +Doctor перевіряє env брокера Convex, валідує налаштування endpoint і перевіряє досяжність admin/list, коли присутній секрет maintainer. Він повідомляє лише статус set/missing для секретів. -## Покриття live transport +## Покриття live-транспортів -Live transport lanes мають один спільний контракт замість того, щоб кожна з них вигадувала власну форму списку сценаріїв. `qa-channel` — це широка синтетична suite поведінки продукту, і вона не є частиною матриці покриття live transport. +Live transport lanes спільно використовують один контракт, а не кожен винаходить власну форму списку сценаріїв. `qa-channel` — це широкий синтетичний suite поведінки продукту, і він не є частиною матриці покриття live-транспортів. | Lane | Canary | Mention gating | Bot-to-bot | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration | | -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | @@ -146,52 +164,52 @@ Live transport lanes мають один спільний контракт за | Discord | x | x | x | | | | | | | | x | | Slack | x | x | x | | | | | | | | | -Це зберігає `qa-channel` як широку suite поведінки продукту, тоді як Matrix, -Telegram і майбутні live transports мають спільний явний checklist -transport-contract. +Це залишає `qa-channel` широким suite поведінки продукту, тоді як Matrix, +Telegram і майбутні live-транспорти спільно використовують один явний checklist +контракту транспорту. -Для одноразової Linux VM lane без залучення Docker у QA path виконайте: +Для одноразового Linux VM lane без залучення Docker до QA-шляху запустіть: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує свіжий Multipass guest, встановлює залежності, збирає OpenClaw -усередині guest, запускає `qa suite`, а потім копіює звичайний QA-звіт і -summary назад у `.artifacts/qa-e2e/...` на host. -Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на host. -Host і Multipass suite runs за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими gateway workers. `qa-channel` за замовчуванням має concurrency +Це завантажує свіжий гостьовий екземпляр Multipass, встановлює залежності, збирає OpenClaw +усередині гостьового середовища, запускає `qa suite`, а потім копіює звичайний звіт QA та +зведення назад у `.artifacts/qa-e2e/...` на хості. +Використовується така сама поведінка вибору сценаріїв, як і для `qa suite` на хості. +Запуски набору на хості та в Multipass типово виконують кілька вибраних сценаріїв паралельно +з ізольованими працівниками Gateway. `qa-channel` типово має паралельність 4, обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість workers, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, коли будь-який сценарій падає. Використовуйте `--allow-failures`, коли -потрібні артефакти без failing exit code. -Live runs передають підтримувані QA auth inputs, практичні для -guest: provider keys на основі env, шлях QA live provider config і -`CODEX_HOME`, коли він присутній. Тримайте `--output-dir` під коренем репозиторію, щоб guest -міг записувати назад через змонтований workspace. +кількість працівників, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдало. Використовуйте `--allow-failures`, коли +потрібні артефакти без коду завершення помилки. +Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для +гостьового середовища: ключі провайдерів на основі env, шлях до конфігурації QA live provider і +`CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у корені репозиторію, щоб гостьове середовище +могло записувати назад через змонтований робочий простір. ## Довідник QA для Telegram, Discord і Slack -Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і Docker-backed homeserver provisioning. Telegram, Discord і Slack менші — по кілька сценаріїв, без системи профілів, проти попередньо наявних реальних каналів — тому їхній довідник міститься тут. +Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і підготовку Docker-backed homeserver. Telegram, Discord і Slack менші — по кілька сценаріїв кожен, без системи профілів, проти вже наявних реальних каналів — тому їхній довідник розміщено тут. -### Спільні CLI flags +### Спільні прапорці CLI -Ці lanes реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають ті самі flags: +Ці напрямки реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають однакові прапорці: -| Прапорець | Типове значення | Опис | -| ------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Запустити лише цей сценарій. Можна повторювати. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Куди записуються звіти/підсумок/спостережені повідомлення та вихідний журнал. Відносні шляхи обчислюються відносно `--repo-root`. | -| `--repo-root ` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. | -| `--sut-account ` | `sut` | Тимчасовий ідентифікатор облікового запису в конфігурації QA gateway. | -| `--provider-mode ` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` також працює). | -| `--model ` / `--alt-model ` | типове значення постачальника | Посилання на основну/альтернативну модель. | -| `--fast` | вимкнено | Швидкий режим постачальника, де підтримується. | -| `--credential-source ` | `env` | Див. [Пул облікових даних Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` у CI, інакше `maintainer` | Роль, що використовується, коли `--credential-source convex`. | +| Прапорець | Типово | Опис | +| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Запустити лише цей сценарій. Можна повторювати. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Куди записуються звіти/зведення/спостережені повідомлення та журнал виводу. Відносні шляхи розв’язуються відносно `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. | +| `--sut-account ` | `sut` | Тимчасовий id облікового запису в конфігурації QA Gateway. | +| `--provider-mode ` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` все ще працює). | +| `--model ` / `--alt-model ` | provider default | Основні/альтернативні refs моделей. | +| `--fast` | вимкнено | Швидкий режим провайдера там, де підтримується. | +| `--credential-source ` | `env` | Див. [пул облікових даних Convex](#convex-credential-pool). | +| `--credential-role ` | `ci` у CI, інакше `maintainer` | Роль, яку використовують, коли `--credential-source convex`. | -Кожна смуга завершується з ненульовим кодом у разі будь-якого невдалого сценарію. `--allow-failures` записує артефакти без встановлення коду виходу з помилкою. +Кожен напрямок завершується з ненульовим кодом за будь-якого невдалого сценарію. `--allow-failures` записує артефакти без встановлення коду завершення помилки. ### QA Telegram @@ -199,17 +217,17 @@ Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через pnpm openclaw qa telegram ``` -Націлюється на одну справжню приватну групу Telegram із двома окремими ботами (драйвер + SUT). Бот SUT повинен мати ім’я користувача Telegram; спостереження бот-до-бота працює найкраще, коли в обох ботів увімкнено **Bot-to-Bot Communication Mode** у `@BotFather`. +Націлено на одну реальну приватну групу Telegram із двома окремими ботами (driver + SUT). SUT-бот повинен мати ім’я користувача Telegram; спостереження бот-до-бота працює найкраще, коли обидва боти мають увімкнений **Bot-to-Bot Communication Mode** у `@BotFather`. -Обов’язкові змінні середовища, коли `--credential-source env`: +Обов’язкові env, коли `--credential-source env`: -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий ідентифікатор чату (рядок). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий id чату (рядок). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` Необов’язково: -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах спостережених повідомлень (за замовчуванням редагуються). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах спостережених повідомлень (типово редагує). Сценарії (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): @@ -225,8 +243,8 @@ pnpm openclaw qa telegram Вихідні артефакти: - `telegram-qa-report.md` -- `telegram-qa-summary.json` — включає RTT для кожної відповіді (надсилання драйвером → спостережена відповідь SUT), починаючи з canary. -- `telegram-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. +- `telegram-qa-summary.json` — містить RTT для кожної відповіді (надсилання driver → спостережена відповідь SUT), починаючи з canary. +- `telegram-qa-observed-messages.json` — тіла відредаговано, якщо не задано `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. ### QA Discord @@ -234,15 +252,15 @@ pnpm openclaw qa telegram pnpm openclaw qa discord ``` -Націлюється на один справжній приватний канал гільдії Discord із двома ботами: драйверним ботом, керованим тестовим стендом, і ботом SUT, запущеним дочірнім Gateway OpenClaw через вбудований Discord plugin. Перевіряє обробку згадок каналу, те, що бот SUT зареєстрував нативну команду `/help` у Discord, а також opt-in сценарії доказів Mantis. +Націлено на один реальний приватний канал guild у Discord із двома ботами: driver-бот, керований harness, і SUT-бот, запущений дочірнім OpenClaw Gateway через вбудований Discord Plugin. Перевіряє обробку згадок каналу, те, що SUT-бот зареєстрував нативну команду `/help` у Discord, а також opt-in сценарії доказів Mantis. -Обов’язкові змінні середовища, коли `--credential-source env`: +Обов’язкові env, коли `--credential-source env`: - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — має збігатися з ідентифікатором користувача бота SUT, поверненим Discord (інакше смуга швидко завершується з помилкою). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — має збігатися з id користувача SUT-бота, який повертає Discord (інакше напрямок швидко завершується помилкою). Необов’язково: @@ -253,9 +271,9 @@ pnpm openclaw qa discord - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — opt-in сценарій Mantis. Запускається окремо, оскільки перемикає SUT на постійно ввімкнені відповіді гільдії лише інструментами з `messages.statusReactions.enabled=true`, а потім захоплює часову шкалу REST-реакцій плюс візуальний артефакт HTML/PNG. +- `discord-status-reactions-tool-only` — opt-in сценарій Mantis. Запускається окремо, бо перемикає SUT на always-on, tool-only відповіді guild з `messages.statusReactions.enabled=true`, а потім захоплює REST-хронологію реакцій і візуальний артефакт HTML/PNG. -Запустіть сценарій статусних реакцій Mantis явно: +Запустіть сценарій Mantis для status-reaction явно: ```bash pnpm openclaw qa discord \ @@ -270,8 +288,8 @@ pnpm openclaw qa discord \ - `discord-qa-report.md` - `discord-qa-summary.json` -- `discord-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. -- `discord-qa-reaction-timelines.json` і `discord-status-reactions-tool-only-timeline.png`, коли запускається сценарій статусних реакцій. +- `discord-qa-observed-messages.json` — тіла відредаговано, якщо не задано `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. +- `discord-qa-reaction-timelines.json` і `discord-status-reactions-tool-only-timeline.png`, коли запускається сценарій status-reaction. ### QA Slack @@ -279,9 +297,9 @@ pnpm openclaw qa discord \ pnpm openclaw qa slack ``` -Націлюється на один справжній приватний канал Slack із двома окремими ботами: драйверним ботом, керованим тестовим стендом, і ботом SUT, запущеним дочірнім Gateway OpenClaw через вбудований Slack plugin. +Націлено на один реальний приватний канал Slack із двома окремими ботами: driver-бот, керований harness, і SUT-бот, запущений дочірнім OpenClaw Gateway через вбудований Slack Plugin. -Обов’язкові змінні середовища, коли `--credential-source env`: +Обов’язкові env, коли `--credential-source env`: - `OPENCLAW_QA_SLACK_CHANNEL_ID` - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` @@ -301,22 +319,22 @@ pnpm openclaw qa slack - `slack-qa-report.md` - `slack-qa-summary.json` -- `slack-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. +- `slack-qa-observed-messages.json` — тіла відредаговано, якщо не задано `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. ### Пул облікових даних Convex -Смуги Telegram, Discord і Slack можуть орендувати облікові дані зі спільного пулу Convex замість читання змінних середовища вище. Передайте `--credential-source convex` (або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, надсилає для неї Heartbeat протягом виконання та звільняє її під час завершення роботи. Типи пулу: `"telegram"`, `"discord"` і `"slack"`. +Напрямки Telegram, Discord і Slack можуть орендувати облікові дані зі спільного пулу Convex замість читання env vars вище. Передайте `--credential-source convex` (або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, підтримує її Heartbeat протягом запуску та звільняє під час завершення. Типи пулу: `"telegram"`, `"discord"` і `"slack"`. -Форми payload, які broker перевіряє на `admin/add`: +Форми payload, які broker перевіряє в `admin/add`: -- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` має бути рядком числового chat-id. +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` має бути числовим рядком chat-id. - Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -Операційні змінні середовища та контракт endpoint broker Convex описані в [Testing → Shared Telegram credentials via Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу передує підтримці Discord; семантика broker однакова для обох типів). +Операційні env vars і контракт endpoint broker Convex наведено в [Тестування → Спільні облікові дані Telegram через Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу передує підтримці Discord; семантика broker однакова для обох типів). -## Seeds із репозиторію +## Seeds на основі репозиторію -Seed-ресурси розташовані в `qa/`: +Seed-ресурси розміщені в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` @@ -325,108 +343,108 @@ Seed-ресурси розташовані в `qa/`: агенту. `qa-lab` має залишатися generic markdown runner. Кожен markdown-файл сценарію є -джерелом істини для одного тестового запуску та має визначати: +джерелом істини для одного тестового запуску й має визначати: - метадані сценарію -- необов’язкові метадані категорії, capability, смуги та ризику -- посилання на документацію та код -- необов’язкові вимоги до plugin +- необов’язкові метадані категорії, capability, lane і risk +- docs і code refs +- необов’язкові вимоги до Plugin - необов’язковий patch конфігурації Gateway - виконуваний `qa-flow` Багаторазова runtime-поверхня, що підтримує `qa-flow`, може залишатися generic -і наскрізною. Наприклад, markdown-сценарії можуть поєднувати помічники на боці -транспорту з помічниками на боці браузера, які керують вбудованим Control UI через -шов Gateway `browser.request`, без додавання спеціалізованого runner. +і cross-cutting. Наприклад, markdown-сценарії можуть поєднувати transport-side +helpers із browser-side helpers, які керують вбудованим Control UI через +Gateway `browser.request` seam без додавання runner для спеціального випадку. -Файли сценаріїв слід групувати за продуктовою capability, а не за папкою дерева -джерел. Зберігайте ідентифікатори сценаріїв стабільними під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` -для простежуваності реалізації. +Файли сценаріїв слід групувати за product capability, а не за папкою дерева +джерел. Зберігайте стабільні ID сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` +для трасування реалізації. -Базовий список має залишатися достатньо широким, щоб покривати: +Базовий список має залишатися достатньо широким, щоб охоплювати: -- DM і чат каналу +- DM і channel chat - поведінку thread -- життєвий цикл дій із повідомленнями -- Cron callbacks -- пригадування пам’яті +- життєвий цикл message action +- callbacks Cron +- memory recall - перемикання моделей -- передавання subagent -- читання репозиторію та читання документації -- одне невелике завдання збірки, як-от Lobster Invaders +- handoff subagent +- читання репозиторію та документації +- одне невелике завдання збірки, наприклад Lobster Invaders -## Смуги mock-постачальника +## Mock-напрямки провайдерів -`qa suite` має дві локальні смуги mock-постачальника: +`qa suite` має два локальні mock-напрямки провайдерів: -- `mock-openai` — scenario-aware mock OpenClaw. Він залишається типовою - детермінованою mock-смугою для QA з репозиторію та parity gates. -- `aimock` запускає сервер постачальника на базі AIMock для експериментального protocol, - fixture, record/replay і chaos-покриття. Він є додатковим і не +- `mock-openai` — це scenario-aware mock OpenClaw. Він залишається типовим + детермінованим mock-напрямком для repo-backed QA і parity gates. +- `aimock` запускає AIMock-backed provider server для експериментального protocol, + fixture, record/replay і chaos coverage. Він є додатковим і не замінює scenario dispatcher `mock-openai`. -Реалізація смуг постачальників розташована в `extensions/qa-lab/src/providers/`. -Кожен постачальник володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделі Gateway, +Реалізація provider-lane розміщена в `extensions/qa-lab/src/providers/`. +Кожен provider володіє своїми defaults, запуском локального сервера, конфігурацією моделей Gateway, потребами staging auth-profile і прапорцями live/mock capability. Спільний код suite і -Gateway має маршрутизувати через реєстр постачальників замість розгалуження за -іменами постачальників. +Gateway має маршрутизувати через provider registry замість branching on +provider names. -## Транспортні адаптери +## Transport adapters -`qa-lab` володіє generic транспортним швом для markdown QA-сценаріїв. `qa-channel` є першим адаптером на цьому шві, але ціль дизайну ширша: майбутні справжні або синтетичні канали мають підключатися до того самого suite runner замість додавання транспортно-специфічного QA runner. +`qa-lab` володіє generic transport seam для markdown-сценаріїв QA. `qa-channel` — перший adapter на цьому seam, але ціль дизайну ширша: майбутні реальні або synthetic channels мають підключатися до того самого suite runner замість додавання transport-specific QA runner. -На рівні архітектури поділ такий: +На архітектурному рівні поділ такий: -- `qa-lab` володіє generic виконанням сценаріїв, конкурентністю worker, записом артефактів і звітуванням. -- Транспортний адаптер володіє конфігурацією Gateway, готовністю, спостереженням inbound і outbound, транспортними діями та нормалізованим транспортним станом. +- `qa-lab` володіє generic виконанням сценаріїв, паралельністю працівників, записом артефактів і звітністю. +- Transport adapter володіє конфігурацією Gateway, readiness, inbound and outbound observation, transport actions і normalized transport state. - Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову runtime-поверхню, яка їх виконує. ### Додавання каналу -Додавання каналу до markdown QA-системи потребує рівно двох речей: +Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Транспортного адаптера для каналу. -2. Пакета сценаріїв, що перевіряє контракт каналу. +1. Transport adapter для каналу. +2. Scenario pack, який перевіряє contract каналу. -Не додавайте новий верхньорівневий корінь команди QA, коли спільний host `qa-lab` може володіти flow. +Не додавайте новий top-level root команди QA, коли спільний хост `qa-lab` може володіти flow. -`qa-lab` володіє спільною механікою host: +`qa-lab` володіє спільними механіками хоста: - корінь команди `openclaw qa` -- запуск і teardown suite +- запуск і завершення suite - конкурентність worker - запис артефактів -- генерація звіту +- генерація звітів - виконання сценаріїв -- compatibility aliases для старіших сценаріїв `qa-channel` +- сумісні псевдоніми для старіших сценаріїв `qa-channel` Runner plugins володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway конфігурується для цього транспорту +- як gateway налаштовується для цього транспорту - як перевіряється готовність -- як впроваджуються inbound events -- як спостерігаються outbound messages -- як надаються transcripts і нормалізований транспортний стан -- як виконуються transport-backed actions +- як впроваджуються вхідні події +- як спостерігаються вихідні повідомлення +- як надаються транскрипти й нормалізований стан транспорту +- як виконуються дії, підтримані транспортом - як обробляється транспортно-специфічне скидання або очищення -Мінімальний поріг прийняття для нового каналу: +Мінімальна планка впровадження для нового каналу: 1. Залиште `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте runner транспорту на спільному host seam `qa-lab`. -3. Тримайте специфічну для транспорту механіку всередині runner plugin або harness каналу. -4. Змонтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. Runner plugins мають оголошувати `qaRunners` в `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; ліниві CLI та виконання runner мають залишатися за окремими точками входу. +2. Реалізуйте transport runner на спільному host seam `qa-lab`. +3. Тримайте транспортно-специфічні механіки всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. Runner plugins мають оголошувати `qaRunners` в `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; відкладені CLI та виконання runner мають залишатися за окремими entrypoints. 5. Створіть або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. 6. Використовуйте загальні допоміжні функції сценаріїв для нових сценаріїв. -7. Залишайте наявні псевдоніми сумісності робочими, якщо repo не виконує навмисну міграцію. +7. Зберігайте роботу наявних псевдонімів сумісності, якщо репозиторій не виконує навмисну міграцію. Правило ухвалення рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, помістіть її в `qa-lab`. +- Якщо поведінку можна один раз виразити в `qa-lab`, помістіть її в `qa-lab`. - Якщо поведінка залежить від одного транспорту каналу, тримайте її в цьому runner plugin або plugin harness. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальну допоміжну функцію замість специфічної для каналу гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залиште сценарій специфічним для транспорту й явно зазначте це в контракті сценарію. +- Якщо сценарію потрібна нова можливість, яку може використати більше ніж один канал, додайте загальну допоміжну функцію замість гілки, специфічної для каналу, у `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залиште сценарій транспортно-специфічним і явно зазначте це в контракті сценарію. ### Назви допоміжних функцій сценаріїв @@ -445,21 +463,21 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Псевдоніми сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але під час створення нових сценаріїв слід використовувати загальні назви. Псевдоніми існують, щоб уникнути одночасної примусової міграції, а не як модель на майбутнє. +Псевдоніми сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але під час створення нових сценаріїв слід використовувати загальні назви. Псевдоніми існують, щоб уникнути одночасної міграції всього коду, а не як модель на майбутнє. ## Звітування -`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової лінії bus. +`qa-lab` експортує Markdown-звіт протоколу зі спостереженої часової шкали bus. Звіт має відповідати на такі питання: - Що спрацювало -- Що не вдалося +- Що не спрацювало - Що залишилося заблокованим - Які подальші сценарії варто додати -Для інвентаризації доступних сценаріїв — корисної під час оцінювання обсягу подальшої роботи або підключення нового транспорту — запустіть `pnpm openclaw qa coverage` (додайте `--json` для машинозчитуваного виводу). +Для інвентаризації доступних сценаріїв — корисної під час оцінювання обсягу подальшої роботи або підключення нового транспорту — запустіть `pnpm openclaw qa coverage` (додайте `--json` для машиночитного виводу). -Для перевірок характеру й стилю запустіть той самий сценарій на кількох живих model +Для перевірок характеру й стилю запустіть той самий сценарій на кількох live model refs і запишіть оцінений Markdown-звіт: ```bash @@ -479,36 +497,36 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси QA Gateway, а не Docker. Сценарії оцінювання характеру -мають задавати persona через `SOUL.md`, а потім виконувати звичайні звернення користувача, -як-от чат, допомога з workspace і невеликі файлові завдання. Моделі-кандидату -не слід повідомляти, що її оцінюють. Команда зберігає кожен повний +Команда запускає дочірні процеси локального QA gateway, а не Docker. Сценарії character eval +мають задавати persona через `SOUL.md`, а потім виконувати звичайні user turns, +такі як чат, допомога з робочим простором і невеликі файлові завдання. Candidate model не слід +повідомляти, що її оцінюють. Команда зберігає кожен повний транскрипт, записує базову статистику запуску, а потім просить judge models у fast mode з -міркуванням `xhigh`, де воно підтримується, ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` під час порівняння провайдерів: judge prompt усе ще отримує -кожен транскрипт і статус запуску, але refs кандидатів замінюються нейтральними -мітками, як-от `candidate-01`; звіт зіставляє рейтинги назад із реальними refs після -розбору. -Запуски кандидатів за замовчуванням використовують мислення `high`, з `medium` для GPT-5.5 і `xhigh` -для старіших OpenAI eval refs, які це підтримують. Перевизначте окремого кандидата inline за допомогою +міркуванням `xhigh`, де воно підтримується, ранжувати запуски за природністю, vibe і гумором. +Використовуйте `--blind-judge-models` під час порівняння providers: judge prompt усе одно отримує +кожен транскрипт і статус запуску, але candidate refs замінюються нейтральними +мітками, як-от `candidate-01`; звіт зіставляє рейтинги з реальними refs після +парсингу. +Candidate runs за замовчуванням використовують thinking `high`, з `medium` для GPT-5.5 і `xhigh` +для старіших OpenAI eval refs, які це підтримують. Перевизначте конкретного candidate inline за допомогою `--model provider/model,thinking=`. `--thinking ` усе ще задає -глобальний fallback, а старіша форма `--model-thinking ` зберігається +глобальний fallback, а старіша форма `--model-thinking ` збережена для сумісності. -OpenAI refs кандидатів за замовчуванням використовують fast mode, щоб priority processing застосовувалася там, де -провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли -окремому кандидату чи судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалості кандидатів і суддів -записуються у звіт для аналізу benchmark, але judge prompts явно вказують +OpenAI candidate refs за замовчуванням використовують fast mode, щоб priority processing застосовувався там, +де provider це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли +окремому candidate або judge потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете +примусово ввімкнути fast mode для кожної candidate model. Тривалості candidate і judge +записуються у звіті для benchmark analysis, але judge prompts явно вказують не ранжувати за швидкістю. -Запуски моделей-кандидатів і суддів за замовчуванням мають concurrency 16. Зменште -`--concurrency` або `--judge-concurrency`, коли ліміти провайдера чи навантаження на локальний Gateway +Запуски candidate і judge model за замовчуванням мають concurrency 16. Зменште +`--concurrency` або `--judge-concurrency`, коли ліміти provider або навантаження локального gateway роблять запуск надто шумним. -Коли не передано candidate `--model`, character eval за замовчуванням використовує +Коли candidate `--model` не передано, character eval за замовчуванням використовує `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і -`google/gemini-3.1-pro-preview`, коли не передано `--model`. -Коли не передано `--judge-model`, судді за замовчуванням: +`google/gemini-3.1-pro-preview`, коли `--model` не передано. +Коли `--judge-model` не передано, judges за замовчуванням: `openai/gpt-5.5,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. @@ -517,4 +535,4 @@ OpenAI refs кандидатів за замовчуванням викорис - [Matrix QA](/uk/concepts/qa-matrix) - [QA Channel](/uk/channels/qa-channel) - [Тестування](/uk/help/testing) -- [Dashboard](/uk/web/dashboard) +- [Панель керування](/uk/web/dashboard)