diff --git a/docs/uk/concepts/mantis.md b/docs/uk/concepts/mantis.md index 614a23a8d..90b87ccdd 100644 --- a/docs/uk/concepts/mantis.md +++ b/docs/uk/concepts/mantis.md @@ -1,85 +1,65 @@ --- read_when: - - Створення або запуск живої візуальної перевірки якості для помилок OpenClaw - - Додавання перевірок до й після для запиту на злиття - - Додавання сценаріїв транспорту в реальному часі для Discord, Slack, WhatsApp або інших сервісів - - Налагодження запусків QA, для яких потрібні знімки екрана, автоматизація браузера або доступ через VNC -summary: Mantis — це візуальна система наскрізної верифікації для відтворення помилок OpenClaw на живих транспортах, збирання доказів до й після та прикріплення артефактів до PR. + - Створення або запуск живого візуального контролю якості для помилок OpenClaw + - Додавання перевірки «до» й «після» для запиту на злиття + - Додавання сценаріїв для Discord, Slack, WhatsApp або інших живих транспортів + - Налагодження запусків QA, яким потрібні знімки екрана, автоматизація браузера або доступ VNC +summary: Mantis — це система візуальної наскрізної перевірки для відтворення помилок OpenClaw на діючих транспортах, збору доказів до й після та прикріплення артефактів до запитів на злиття. title: Богомол x-i18n: - generated_at: "2026-05-05T06:58:51Z" + generated_at: "2026-05-05T08:17:39Z" model: gpt-5.5 provider: openai - source_hash: 00f2be92845fb13e410af7188f348010140914514d739b930f97b43abaa66a0c + source_hash: 6b287e2832e3e49de6b3cb65aeb1d381a36fc30ce9c94dc5b6b4d7e928c2706c source_path: concepts/mantis.md workflow: 16 --- -Mantis — це система наскрізної перевірки OpenClaw для помилок, яким потрібні реальне -середовище виконання, реальний транспорт і видимий доказ. Вона запускає сценарій на відомому -поганому ref, збирає докази, запускає той самий сценарій на кандидатному ref і -публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або -з локальної команди. +Mantis — це система наскрізної верифікації OpenClaw для помилок, яким потрібні справжнє середовище виконання, справжній транспорт і видимий доказ. Вона запускає сценарій для відомого поганого ref, збирає докази, запускає той самий сценарій для кандидатного ref і публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або з локальної команди. -Mantis починається з Discord, тому що Discord дає нам цінний перший напрям: -реальну автентифікацію бота, реальні канали гільдії, реакції, треди, нативні команди та -браузерний UI, де люди можуть візуально підтвердити, що показав транспорт. +Mantis починає з Discord, тому що Discord дає нам першу lane з високою цінністю: справжню автентифікацію бота, справжні канали guild, реакції, треди, нативні команди та браузерний UI, де люди можуть візуально підтвердити те, що показав транспорт. ## Цілі -- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку - бачать користувачі. -- Зібрати артефакт **до** на базовому ref перед застосуванням виправлення. -- Зібрати артефакт **після** на кандидатному ref після застосування виправлення. -- Використовувати детермінований оракул, коли це можливо, наприклад читання реакції - через Discord REST або перевірку транскрипту каналу. -- Збирати знімки екрана, коли помилка має видиму UI-поверхню. -- Запускати локально з CLI, керованого агентом, і віддалено з GitHub. -- Зберігати достатньо стану машини для VNC-відновлення, коли вхід, браузерна автоматизація або - автентифікація провайдера застрягає. -- Публікувати стислий статус в операторський канал Discord, коли запуск заблокований, - потребує ручної допомоги через VNC або завершується. +- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку бачать користувачі. +- Захопити артефакт **before** на baseline ref перед застосуванням виправлення. +- Захопити артефакт **after** на candidate ref після застосування виправлення. +- Використовувати детермінований oracle, коли це можливо, наприклад читання реакції через Discord REST або перевірку transcript каналу. +- Захоплювати знімки екрана, коли помилка має видиму UI-поверхню. +- Запускати локально з керованого агентом CLI і віддалено з GitHub. +- Зберігати достатньо стану машини для VNC-рятування, коли вхід, браузерна автоматизація або автентифікація provider застрягає. +- Публікувати стислий статус в операторський канал Discord, коли запуск заблоковано, потрібна ручна VNC-допомога або запуск завершено. -## Поза цілями +## Нецілі -- Mantis не є заміною модульних тестів. Запуск Mantis зазвичай має перетворитися - на менший регресійний тест після того, як виправлення зрозуміле. -- Mantis не є звичайним швидким CI-шлюзом. Він повільніший, використовує live-облікові дані та - призначений для помилок, де live-середовище має значення. -- Mantis не повинен потребувати людини для нормальної роботи. Ручний VNC — це шлях - відновлення, а не штатний шлях. -- Mantis не зберігає необроблені секрети в артефактах, логах, знімках екрана, Markdown - звітах або коментарях PR. +- Mantis не є заміною unit tests. Запуск Mantis зазвичай має перетворитися на менший регресійний тест після того, як виправлення зрозуміле. +- Mantis не є звичайним швидким CI gate. Він повільніший, використовує live credentials і зарезервований для помилок, де живе середовище має значення. +- Mantis не має вимагати участі людини для нормальної роботи. Ручний VNC — це шлях рятування, а не штатний шлях. +- Mantis не зберігає raw secrets в артефактах, логах, знімках екрана, Markdown-звітах або PR-коментарях. -## Зони відповідальності +## Власність -Mantis живе в стеку QA OpenClaw. +Mantis живе в QA-стеку OpenClaw. -- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і - локальним CLI під `pnpm openclaw qa mantis`. -- QA Lab володіє частинами live-транспортного harness, допоміжними засобами браузерного захоплення та - записувачами артефактів. +- OpenClaw володіє runtime сценаріїв, транспортними адаптерами, схемою доказів і локальним CLI у `pnpm openclaw qa mantis`. +- QA Lab володіє частинами live transport harness, помічниками захоплення браузера та записувачами артефактів. - Crabbox володіє прогрітими Linux-машинами, коли потрібна віддалена VM. -- GitHub Actions володіє віддаленою точкою входу workflow та зберіганням артефактів. -- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів, - dispatch workflow і публікацією фінального коментаря PR. -- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування, - налагодження або звітування про застряглий стан. +- GitHub Actions володіє віддаленою точкою входу workflow і збереженням артефактів. +- ClawSweeper володіє маршрутизацією GitHub-коментарів: розбором команд мейнтейнерів, dispatch workflow і публікацією фінального PR-коментаря. +- Агенти OpenClaw керують Mantis через Codex, коли сценарій потребує агентного налаштування, налагодження або звітування про застряглий стан. -Ця межа тримає знання про транспорт в OpenClaw, планування машин у -Crabbox, а клей workflow мейнтейнерів у ClawSweeper. +Ця межа тримає знання про транспорт в OpenClaw, планування машин у Crabbox, а workflow-зв’язку для мейнтейнерів у ClawSweeper. -## Формат команд +## Форма команди -Перша локальна команда перевіряє Discord-бота, гільдію, канал, надсилання повідомлення, -надсилання реакції та шлях артефактів: +Перша локальна команда перевіряє Discord-бота, guild, канал, надсилання повідомлення, надсилання реакції та шлях артефактів: ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Локальний runner до і після приймає таку форму: +Локальний runner before і after приймає таку форму: ```bash pnpm openclaw qa mantis run \ @@ -90,35 +70,26 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Runner створює від'єднані baseline і candidate worktree у вихідному -каталозі, встановлює залежності, збирає кожен ref, запускає сценарій із -`--allow-failures`, потім записує `baseline/`, `candidate/`, `comparison.json`, -і `mantis-report.md`. Для першого сценарію Discord успішна перевірка -означає, що статус baseline — `fail`, а статус candidate — `pass`. +Runner створює від’єднані baseline і candidate worktrees у каталозі виводу, встановлює залежності, збирає кожен ref, запускає сценарій з `--allow-failures`, а потім записує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md`. Для першого Discord-сценарію успішна верифікація означає, що baseline status має `fail`, а candidate status має `pass`. -Перший примітив VM/browser — desktop smoke: +Перша VM/browser primitive — це desktop smoke: ```bash pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -Він орендує або повторно використовує desktop-машину Crabbox, запускає видимий браузер усередині -VNC-сеансу, захоплює робочий стіл, витягує артефакти назад у локальний вихідний -каталог і записує команду повторного підключення у звіт. Команда за замовчуванням -використовує провайдера Hetzner, тому що це перший провайдер із робочим desktop/VNC -покриттям у напрямі Mantis. Перевизначте його через `--provider`, `--crabbox-bin` або -`OPENCLAW_MANTIS_CRABBOX_PROVIDER` під час запуску проти іншого флоту Crabbox. +Вона орендує або повторно використовує desktop-машину Crabbox, запускає видимий браузер у VNC-сесії, захоплює desktop, витягує артефакти назад у локальний каталог виводу і записує команду повторного підключення у звіт. Команда за замовчуванням використовує Hetzner provider, тому що це перший provider з робочим desktop/VNC-покриттям у Mantis lane. Перевизначте його за допомогою `--provider`, `--crabbox-bin` або `OPENCLAW_MANTIS_CRABBOX_PROVIDER` під час запуску проти іншого Crabbox fleet. Корисні прапорці desktop smoke: - `--lease-id ` або `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` повторно використовує прогрітий desktop. - `--browser-url ` змінює сторінку, відкриту у видимому браузері. -- `--html-file ` рендерить repo-local HTML-артефакт у видимому браузері. Mantis використовує це для захоплення згенерованої timeline реакцій статусу Discord через реальний desktop Crabbox. -- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` залишає новостворену успішну оренду відкритою для VNC-перегляду. Невдалі запуски за замовчуванням залишають оренду, якщо її було створено, щоб оператор міг повторно підключитися. -- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини та час життя оренди. +- `--html-file ` рендерить локальний HTML-артефакт repo у видимому браузері. Mantis використовує це, щоб захопити згенеровану часову шкалу Discord status-reaction через справжній Crabbox desktop. +- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` залишає новостворену passing lease відкритою для VNC-інспекції. Failed runs за замовчуванням залишають lease, коли її було створено, щоб оператор міг перепідключитися. +- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини та час життя lease. -Перший повний desktop-транспортний примітив — Slack desktop smoke: +Перша повна desktop transport primitive — це Slack desktop smoke: ```bash pnpm openclaw qa mantis slack-desktop-smoke \ @@ -128,72 +99,88 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Він орендує або повторно використовує desktop-машину Crabbox, синхронізує поточний checkout у -VM, запускає `pnpm openclaw qa slack` всередині цієї VM, відкриває Slack Web у VNC -браузері, захоплює видимий робочий стіл і копіює як артефакти Slack QA, так і -VNC-знімок екрана назад у локальний вихідний каталог. Це перша форма Mantis, -де SUT OpenClaw Gateway і браузер живуть усередині однієї -Linux desktop VM. +Вона орендує або повторно використовує desktop-машину Crabbox, синхронізує поточний checkout у VM, запускає `pnpm openclaw qa slack` усередині цієї VM, відкриває Slack Web у VNC-браузері, захоплює видимий desktop і копіює як артефакти Slack QA, так і VNC-знімок екрана назад у локальний каталог виводу. Це перша форма Mantis, де SUT OpenClaw Gateway і браузер обидва живуть в одній Linux desktop VM. -З `--gateway-setup` команда готує сталий одноразовий дім OpenClaw -у `$HOME/.openclaw-mantis/slack-openclaw`, патчить конфігурацію Slack Socket Mode -для вибраного каналу, запускає `openclaw gateway run` на порту -`38973` і залишає Chrome запущеним у VNC-сеансі. Це режим "залиш мені -Linux desktop зі Slack і запущеним claw"; напрям bot-to-bot Slack QA -залишається типовим, коли `--gateway-setup` пропущено. +З `--gateway-setup` команда готує постійний одноразовий OpenClaw home у `$HOME/.openclaw-mantis/slack-openclaw`, патчить конфігурацію Slack Socket Mode для вибраного каналу, запускає `openclaw gateway run` на порту `38973` і залишає Chrome запущеним у VNC-сесії. Це режим "залиш мені Linux desktop зі Slack і запущеним claw"; bot-to-bot Slack QA lane залишається типовою, коли `--gateway-setup` опущено. -Обов'язкові вхідні дані для `--credential-source env`: +Обов’язкові вхідні дані для `--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. +- `OPENCLAW_LIVE_OPENAI_KEY` для remote model lane. Якщо локально встановлено лише `OPENAI_API_KEY`, Mantis мапить його на `OPENCLAW_LIVE_OPENAI_KEY` перед викликом Crabbox, щоб forwarding env `OPENCLAW_*` у Crabbox міг передати його у VM. Корисні прапорці Slack desktop: -- `--lease-id ` повторно запускає проти машини, де оператор уже увійшов у Slack Web через VNC. -- `--gateway-setup` запускає сталий Slack Gateway OpenClaw у VM замість запуску лише напряму bot-to-bot QA. -- `--slack-url ` відкриває конкретний URL Slack Web. Без нього Mantis виводить `https://app.slack.com/client//` зі Slack `auth.test`, коли доступний token 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` використовує спільний пул облікових даних замість прямих Slack env tokens. -- `--provider-mode`, `--model`, `--alt-model` і `--fast` передаються в live-напрям Slack. +- `--lease-id ` повторно запускає на машині, де оператор уже увійшов у Slack Web через VNC. +- `--gateway-setup` запускає постійний OpenClaw Slack Gateway у VM замість запуску лише bot-to-bot QA lane. +- `--slack-url ` відкриває конкретний Slack Web URL. Без нього Mantis виводить `https://app.slack.com/client//` зі Slack `auth.test`, коли доступний SUT bot token. +- `--slack-channel-id ` керує allowlist Slack-каналів, яку використовує gateway setup. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` керує постійним профілем Chrome усередині VM. Типове значення — `$HOME/.config/openclaw-mantis/slack-chrome-profile`, тому ручний вхід у Slack Web зберігається для повторних запусків на тій самій lease. +- `--credential-source convex --credential-role ci` використовує спільний credential pool замість прямих Slack env tokens. +- `--provider-mode`, `--model`, `--alt-model` і `--fast` передаються у Slack live lane. -GitHub smoke workflow — `Mantis Discord Smoke`. GitHub workflow до і після -для першого реального сценарію — `Mantis Discord Status Reactions`. Він -приймає: +GitHub smoke workflow — це `Mantis Discord Smoke`. Before і after GitHub workflow для першого справжнього сценарію — це `Mantis Discord Status Reactions`. Він приймає: -- `baseline_ref`: ref, який має відтворити поведінку лише queued. +- `baseline_ref`: ref, який має відтворити поведінку queued-only. - `candidate_ref`: ref, який має показати `queued -> thinking -> done`. -Він checkout ref harness workflow, збирає окремі baseline і candidate -worktree, запускає `discord-status-reactions-tool-only` проти кожного worktree і -завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як -артефакти Actions. Він також рендерить HTML timeline кожного напряму в desktop-браузері -Crabbox і публікує ці VNC-знімки екрана поряд із детермінованими -PNG timeline у коментарі PR. Той самий коментар PR вбудовує легкі -GIF-перегляди з обрізанням руху, згенеровані `crabbox media preview`, посилається на -відповідні MP4-кліпи з обрізанням руху та зберігає повні desktop MP4-файли для глибокого -перегляду. Знімки екрана залишаються inline для швидкого перегляду. Workflow збирає -Crabbox CLI з -`openclaw/crabbox` main, щоб він міг використовувати поточні прапорці desktop/browser lease -до виходу наступного бінарного релізу Crabbox. +Він робить checkout workflow harness ref, збирає окремі baseline і candidate worktrees, запускає `discord-status-reactions-tool-only` проти кожного worktree і завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як Actions artifacts. Він також рендерить timeline HTML кожної lane у Crabbox desktop browser і публікує ці VNC-знімки екрана поруч із детермінованими timeline PNG у PR-коментарі. Той самий PR-коментар вбудовує легкі motion-trimmed GIF previews, згенеровані `crabbox media preview`, посилається на відповідні motion-trimmed MP4 clips і зберігає повні desktop MP4 files для глибокої інспекції. Знімки екрана залишаються inline для швидкого review. Workflow збирає Crabbox CLI з main `openclaw/crabbox`, щоб використовувати поточні desktop/browser lease flags до того, як буде зрізано наступний Crabbox binary release. -Ви також можете запустити status-reactions run напряму з коментаря PR: +`Mantis Scenario` — це generic manual entrypoint. Він приймає `scenario_id`, `candidate_ref`, необов’язковий `baseline_ref` і необов’язковий `pr_number`, а потім dispatch scenario-owned workflow. Wrapper навмисно тонкий: scenario workflows усе ще володіють своїм transport setup, credentials, VM class, expected oracle і artifact manifest. + +`Mantis Slack Desktop Smoke` — це перший Slack VM workflow. Він робить checkout trusted candidate ref в окремому worktree, орендує Crabbox Linux desktop, запускає `pnpm openclaw qa mantis slack-desktop-smoke --gateway-setup` проти цього candidate, відкриває Slack Web у VNC-браузері, записує desktop, генерує motion-trimmed preview за допомогою `crabbox media preview`, завантажує повний каталог артефактів і необов’язково публікує inline evidence comment у цільовому PR. Використовуйте цю lane, коли вам потрібен "Linux desktop зі Slack і запущеним claw" замість лише bot-to-bot Slack transcript. + +Кожен PR-publishing scenario записує `mantis-evidence.json` поруч зі своїм звітом. Ця схема є handoff між scenario code і GitHub comments: + +```json +{ + "schemaVersion": 1, + "id": "discord-status-reactions", + "title": "Mantis Discord Status Reactions QA", + "summary": "Human-readable top summary for the PR comment.", + "scenario": "discord-status-reactions-tool-only", + "comparison": { + "baseline": { "sha": "...", "status": "fail", "expected": "queued-only" }, + "candidate": { "sha": "...", "status": "pass", "expected": "queued -> thinking -> done" }, + "pass": true + }, + "artifacts": [ + { + "kind": "timeline", + "lane": "baseline", + "label": "Baseline queued-only", + "path": "baseline/timeline.png", + "targetPath": "baseline.png", + "alt": "Baseline Discord timeline", + "width": 420 + } + ] +} +``` + +Значення artifact `path` є відносними до каталогу manifest. Значення `targetPath` є відносними шляхами під publish directory гілки `qa-artifacts`. Publisher відхиляє path traversal і пропускає entries, позначені `"required": false`, коли optional previews або videos недоступні. + +Підтримувані artifact kinds: + +- `timeline`: детермінований знімок екрана сценарію, зазвичай before/after. +- `desktopScreenshot`: знімок екрана VNC/browser desktop. +- `motionPreview`: inline animated GIF, згенерований із desktop recording. +- `motionClip`: motion-trimmed MP4, який видаляє статичні lead-in і tail. +- `fullVideo`: повний MP4 recording для глибокої інспекції. +- `metadata`: JSON/log sidecar. +- `report`: Markdown-звіт. + +Reusable publisher — це `scripts/mantis/publish-pr-evidence.mjs`. Workflows викликають його з manifest, target PR, `qa-artifacts` target root, comment marker, Actions artifact URL, run URL і request source. Він копіює declared artifacts у гілку `qa-artifacts`, створює summary-first PR comment з inline images/previews і linked videos, а потім оновлює наявний marker comment або створює новий. + +Ви також можете запустити status-reactions run напряму з PR-коментаря: ```text @Mantis discord status reactions ``` -Тригер коментаря навмисно вузький. Він запускається лише на коментарях pull request -від користувачів із доступом write, maintain або admin, і розпізнає лише -запити реакцій статусу Discord. За замовчуванням він використовує відомий поганий baseline ref -і поточний SHA голови PR як candidate. Мейнтейнери можуть перевизначити будь-який -ref: +Comment trigger навмисно вузький. Він запускається лише на pull request comments від користувачів із доступом write, maintain або admin і розпізнає лише Discord status-reaction requests. За замовчуванням він використовує відомий поганий baseline ref і поточний PR head SHA як candidate. Мейнтейнери можуть перевизначити будь-який ref: ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -206,49 +193,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. Підготувати профіль робочого стола/браузера, коли сценарію потрібні UI-докази. +4. Підготувати чистий checkout для базового ref. +5. Встановити залежності й зібрати лише те, що потрібно сценарію. 6. Запустити дочірній OpenClaw Gateway з ізольованим каталогом стану. -7. Налаштувати live-транспорт, провайдера, модель і browser profile. -8. Запустити сценарій і зібрати baseline evidence. -9. Зупинити gateway і зберегти логи. -10. Підготувати candidate ref у тій самій VM. -11. Запустити той самий сценарій і зібрати candidate evidence. -12. Порівняти результати oracle і візуальні докази. -13. Записати Markdown, JSON, логи, знімки екрана та необов'язкові trace artifacts. +7. Налаштувати live-транспорт, провайдер, модель і профіль браузера. +8. Запустити сценарій і зібрати базові докази. +9. Зупинити Gateway і зберегти журнали. +10. Підготувати кандидатний ref у тій самій VM. +11. Запустити той самий сценарій і зібрати докази кандидата. +12. Порівняти результати oracle та візуальні докази. +13. Записати Markdown, JSON, журнали, знімки екрана та необовʼязкові артефакти trace. 14. Завантажити артефакти GitHub Actions. -15. Опублікувати стислий статусний PR або Discord-повідомлення. +15. Опублікувати стислий статус у PR або Discord. -Сценарій повинен мати змогу завершуватися невдачею двома різними способами: +Сценарій має вміти завершуватися з помилкою двома різними способами: -- **Помилку відтворено**: baseline завершився невдачею очікуваним способом. -- **Збій harness**: налаштування середовища, облікові дані, Discord API, браузер або - провайдер завершилися невдачею до того, як bug oracle став змістовним. +- **Баг відтворено**: базовий варіант завершився з очікуваною помилкою. +- **Помилка harness**: налаштування середовища, облікові дані, Discord API, браузер або + провайдер завершилися з помилкою до того, як oracle бага став змістовним. Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне середовище з поведінкою продукту. -## Discord MVP +## MVP для Discord -Перший сценарій має бути спрямований на реакції статусу Discord у каналах гільдії, де -режим доставки відповіді джерела — `message_tool_only`. +Перший сценарій має бути націлений на реакції статусу Discord у каналах guild, де +режим доставки вихідної відповіді — `message_tool_only`. -Чому це хороший початковий сценарій Mantis: +Чому це добре початкове завдання для Mantis: -- Він видимий у Discord як реакції на тригерне повідомлення. -- Він має сильний REST-оракул через стан реакцій повідомлення Discord. -- Він перевіряє реальний OpenClaw Gateway, автентифікацію Discord-бота, dispatch повідомлень, - режим доставки відповіді джерела, стан реакцій статусу та життєвий цикл model turn. -- Він достатньо вузький, щоб перша реалізація залишалася чесною. +- Це видно в Discord як реакції на повідомлення-тригер. +- Є сильний REST oracle через стан реакцій повідомлення Discord. +- Це перевіряє реальний OpenClaw Gateway, автентифікацію бота Discord, диспетчеризацію повідомлень, + режим доставки вихідної відповіді, стан реакцій статусу та життєвий цикл ходу моделі. +- Воно достатньо вузьке, щоб перша реалізація залишалася чесною. Очікувана форма сценарію: @@ -281,12 +268,12 @@ evidence: screenshotMessageRow: true ``` -Baseline evidence має показувати queued acknowledgement reaction, але не -lifecycle transition у tool-only mode. Candidate evidence має показувати, що lifecycle -status reactions запускаються, коли `messages.statusReactions.enabled` явно -дорівнює true. +Базові докази мають показувати поставлену в чергу реакцію підтвердження, але без +переходу життєвого циклу в режимі лише для інструментів. Докази кандидата мають показувати, що реакції +статусу життєвого циклу виконуються, коли `messages.statusReactions.enabled` явно +має значення true. -Перший виконуваний зріз — opt-in Discord live QA scenario: +Перший виконуваний зріз — opt-in live QA-сценарій Discord: ```bash pnpm openclaw qa discord \ @@ -298,30 +285,30 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Це налаштовує SUT із постійно ввімкненою обробкою guild, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` і явними статусними реакціями. Оракул +Він налаштовує SUT із постійно ввімкненою обробкою guild, `visibleReplies: +"message_tool"`, `ackReaction: "👀"` та явними реакціями статусу. Oracle опитує реальне повідомлення-тригер у Discord і очікує спостережувану послідовність `👀 -> 🤔 -> 👍`. Артефакти містять `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` і `discord-status-reactions-tool-only-timeline.png`. -## Наявні складові QA +## Наявні частини QA -Mantis має спиратися на наявний приватний стек QA, а не починати з +Mantis має будуватися на наявному приватному QA-стеку, а не починати з нуля: -- `pnpm openclaw qa discord` вже запускає живу Discord-смугу з driver-ботом і - SUT-ботом. -- Наявний runner живого транспорту вже записує звіти й артефакти спостережених повідомлень +- `pnpm openclaw qa discord` уже запускає live-лінію Discord із driver і + SUT-ботами. +- Live transport runner уже записує звіти й артефакти спостережуваних повідомлень у `.artifacts/qa-e2e/`. -- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих +- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних live облікових даних транспорту. - Сервіс керування браузером уже підтримує знімки екрана, snapshots, - керовані headless-профілі та віддалені CDP-профілі. -- QA Lab уже має UI debugger і bus для тестування у формі транспорту. + headless керовані профілі та віддалені CDP-профілі. +- QA Lab уже має UI налагоджувача та bus для тестування у формі transport. Перша реалізація Mantis може бути тонким runner до/після поверх цих -складових плюс один шар візуальних доказів. +частин, плюс один шар візуальних доказів. ## Модель доказів @@ -345,76 +332,76 @@ Mantis має спиратися на наявний приватний стек run.log ``` -`mantis-summary.json` має бути машиночитним джерелом істини. Звіт -Markdown призначений для коментарів PR і людського перегляду. +`mantis-summary.json` має бути машинозчитуваним джерелом істини. Звіт +Markdown призначений для коментарів у PR і людського ревʼю. -Summary має містити: +Підсумок має містити: -- перевірені refs і SHAs -- transport і scenario id -- постачальника машини та machine id або lease id +- перевірені refs і SHA +- transport і id сценарію +- провайдера машини та id машини або id оренди - джерело облікових даних без секретних значень -- результат baseline -- результат candidate -- чи відтворилася помилка на baseline -- чи candidate її виправив -- шляхи до артефактів -- санітизовані проблеми setup або cleanup +- результат базового варіанта +- результат кандидата +- чи відтворився баг на базовому варіанті +- чи кандидат це виправив +- шляхи артефактів +- санітизовані проблеми налаштування або очищення -Знімки екрана є доказами, а не секретами. Вони все одно потребують дисципліни редагування: -можуть з’являтися назви приватних каналів, імена користувачів або вміст повідомлень. Для публічних PR -надавайте перевагу посиланням на артефакти GitHub Actions замість inline-зображень, доки історія редагування -не стане надійнішою. +Знімки екрана — це докази, а не секрети. Вони все одно потребують дисципліни редагування: +можуть зʼявлятися приватні назви каналів, імена користувачів або вміст повідомлень. Для публічних PR +надавайте перевагу посиланням на артефакти GitHub Actions замість вбудованих зображень, доки історія +редагування не стане сильнішою. ## Браузер і VNC -Браузерна смуга має два режими: +Браузерна лінія має два режими: -- **Headless-автоматизація**: типово для CI. Chrome запускається з увімкненим CDP, а - Playwright або керування браузером OpenClaw захоплює знімки екрана. -- **VNC-порятунок**: увімкнено на тій самій VM, коли login, MFA, антиавтоматизація Discord - або візуальне налагодження потребують участі людини. +- **Headless automation**: типовий для CI. Chrome запускається з увімкненим CDP, а + Playwright або керування браузером OpenClaw збирає знімки екрана. +- **VNC rescue**: увімкнено на тій самій VM, коли вхід, MFA, Discord anti-automation + або візуальне налагодження потребують людини. -Профіль браузера-спостерігача Discord має бути достатньо persistent, щоб уникати -входу в систему для кожного запуску, але ізольованим від особистого стану браузера. Профіль -належить до пулу машин Mantis, а не до ноутбука розробника. +Профіль браузера спостерігача Discord має бути достатньо постійним, щоб уникати +входу для кожного запуску, але ізольованим від особистого стану браузера. Профіль +належить пулу машин Mantis, а не ноутбуку розробника. -Коли Mantis застрягає, він публікує статусне повідомлення в Discord із: +Коли Mantis застрягає, він публікує статус у Discord з: -- run id -- scenario id -- постачальником машини +- id запуску +- id сценарію +- провайдером машини - каталогом артефактів - інструкціями підключення VNC або noVNC, якщо доступні -- коротким текстом blocker +- коротким текстом блокера Перше приватне розгортання може публікувати ці повідомлення в наявний операторський -канал і пізніше перейти до окремого каналу Mantis. +канал, а пізніше перейти до виділеного каналу Mantis. ## Машини -Mantis має віддавати перевагу AWS через Crabbox для першої віддаленої реалізації. +Mantis має надавати перевагу AWS через Crabbox для першої віддаленої реалізації. Crabbox дає нам прогріті машини, відстеження оренд, hydration, журнали, результати та -cleanup. Якщо ємність AWS надто повільна або недоступна, додайте провайдера Hetzner -за тим самим інтерфейсом машини. +очищення. Якщо місткість AWS надто повільна або недоступна, додайте провайдера Hetzner +за тим самим інтерфейсом машин. Мінімальні вимоги до VM: -- Linux зі встановленим Chrome або Chromium, придатним для desktop -- CDP-доступ для браузерної автоматизації -- VNC або noVNC для порятунку +- Linux із встановленим Chrome або Chromium, здатним працювати з робочим столом +- доступ CDP для автоматизації браузера +- VNC або noVNC для rescue - Node 22 і pnpm - checkout OpenClaw і кеш залежностей - кеш браузера Playwright Chromium, коли використовується Playwright -- достатньо CPU і пам’яті для одного OpenClaw Gateway, одного браузера й одного model run -- вихідний доступ до Discord, GitHub, model providers і брокера облікових даних +- достатньо CPU та памʼяті для одного OpenClaw Gateway, одного браузера й одного запуску моделі +- вихідний доступ до Discord, GitHub, провайдерів моделей і брокера облікових даних -VM не має зберігати довгоживучі raw secrets поза очікуваними сховищами облікових даних або -профілів браузера. +VM не має зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або +профілю браузера. ## Секрети -Секрети зберігаються в секретах організації або репозиторію GitHub для віддалених запусків і в +Секрети живуть у секретах організації або репозиторію GitHub для віддалених запусків і в локальному файлі секретів під контролем оператора для локальних запусків. Рекомендовані назви секретів: @@ -425,50 +412,50 @@ VM не має зберігати довгоживучі raw secrets поза о - `OPENCLAW_QA_DISCORD_GUILD_ID` - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID` -- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` для публічних завантажень артефактів GitHub +- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` для завантажень публічних артефактів GitHub - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих -облікових даних транспорту. Секрети GitHub bootstrapping брокера та fallback-смуг. -Workflow статусних реакцій Discord зіставляє секрети Mantis Crabbox назад із +У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для live +облікових даних транспорту. Секрети GitHub початково запускають брокер і fallback-лінії. +Workflow реакцій статусу Discord зіставляє секрети Mantis Crabbox назад зі змінними середовища `CRABBOX_COORDINATOR` і `CRABBOX_COORDINATOR_TOKEN`, -яких очікує Crabbox CLI. Прості назви секретів GitHub `CRABBOX_*` залишаються -прийнятими як fallback для сумісності. +які очікує Crabbox CLI. Прості назви секретів GitHub `CRABBOX_*` залишаються +прийнятими як fallback сумісності. -Runner Mantis ніколи не повинен друкувати: +Runner Mantis ніколи не має друкувати: - токени ботів Discord -- API-ключі provider +- API-ключі провайдерів - cookies браузера -- вміст auth profile +- вміст профілів автентифікації - паролі VNC -- raw payloads облікових даних +- сирі payloads облікових даних -Публічні завантаження артефактів також мають редагувати цільові metadata Discord, як-от bot, -guild, channel і message ids. Workflow GitHub smoke вмикає -`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` з цієї причини. +Завантаження публічних артефактів також мають редагувати цільові метадані Discord, такі як bot, +guild, channel і message ids. GitHub smoke workflow вмикає +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини. -Якщо токен випадково вставлено в issue, PR, chat або log, ротувати його +Якщо token випадково вставлено в issue, PR, чат або журнал, замініть його після збереження нового секрету. ## Артефакти GitHub і коментарі PR -Workflows Mantis мають завантажувати повний пакет доказів як короткоживучий артефакт Actions. -Коли workflow запускається для звіту про помилку або PR із виправленням, він також має -публікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і upsert -коментар до цієї помилки або PR із виправленням з inline-знімками до/після. Не публікуйте -основний доказ лише в generic PR автоматизації QA. Raw logs, спостережені -повідомлення та інші об’ємні докази залишаються в артефакті Actions. +Workflows Mantis мають завантажувати повний bundle доказів як короткоживучий артефакт Actions. +Коли workflow запускається для звіту про баг або PR з виправленням, він також має +публікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і upsert-коментар +до цього бага або PR з виправленням із вбудованими знімками до/після. Не публікуйте +основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережувані +повідомлення та інші обʼємні докази залишаються в артефакті Actions. Production workflows мають публікувати ці коментарі через Mantis GitHub App, а не -через `github-actions[bot]`. Зберігайте app id і private key як секрети GitHub Actions -`MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. -Workflow використовує прихований marker як upsert key, оновлює цей -коментар, коли token може його редагувати, і створює новий коментар від імені Mantis, коли -старіший marker, що належить bot, неможливо редагувати. +через `github-actions[bot]`. Зберігайте app id і приватний ключ як секрети +GitHub Actions `MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. +Workflow використовує прихований marker як ключ upsert, оновлює цей +коментар, коли token може його редагувати, і створює новий коментар від імені Mantis, +коли старіший marker, створений ботом, не можна редагувати. Коментар PR має бути коротким і візуальним: @@ -490,72 +477,68 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Коли запуск не вдається через збій harness, у коментарі має бути сказано саме це, -а не створюватися враження, що candidate failed. +Коли запуск завершується з помилкою через помилку harness, у коментарі має бути сказано саме це +замість натяку, що кандидат завершився з помилкою. -## Нотатки приватного розгортання +## Примітки щодо приватного розгортання -Приватне розгортання вже може мати застосунок Mantis Discord. Повторно використовуйте цей -застосунок замість створення іншого app, якщо він має правильні bot -permissions і його можна безпечно ротувати. +У приватному розгортанні вже може бути застосунок Mantis Discord. Повторно використайте цей +застосунок замість створення іншого, коли він має потрібні дозволи бота +і його можна безпечно ротувати. -Задайте початковий канал операторських сповіщень через секрети або конфігурацію розгортання. -Він може спершу вказувати на наявний канал maintainers або operations, -а потім перейти до окремого каналу Mantis, коли такий існуватиме. +Задайте початковий операторський канал сповіщень через секрети або конфігурацію +розгортання. Спершу він може вказувати на наявний канал мейнтейнерів або операцій, +а потім перейти до виділеного каналу Mantis, коли він зʼявиться. -Не розміщуйте guild ids, channel ids, bot tokens, browser cookies або VNC passwords -у цьому документі. Зберігайте їх у GitHub secrets, брокері облікових даних або +Не додавайте guild ids, channel ids, bot tokens, browser cookies або VNC passwords +до цього документа. Зберігайте їх у секретах GitHub, брокері облікових даних або локальному сховищі секретів оператора. ## Додавання сценарію Сценарій Mantis має оголошувати: -- id і title +- id і заголовок - transport - потрібні облікові дані -- baseline ref policy -- candidate ref policy -- config patch OpenClaw -- кроки setup -- stimulus -- очікуваний baseline oracle -- очікуваний candidate oracle -- visual capture targets -- timeout budget -- кроки cleanup +- політику базового ref +- політику кандидатного ref +- patch конфігурації OpenClaw +- кроки налаштування +- стимул +- очікуваний oracle базового варіанта +- очікуваний oracle кандидата +- цілі візуального захоплення +- бюджет timeout +- кроки очищення -Scenarios мають віддавати перевагу невеликим typed oracles: +Сценарії мають надавати перевагу малим, типізованим oracles: -- стан реакцій Discord для помилок реакцій -- посилання на повідомлення Discord для threading bugs -- thread ts Slack і стан reaction API для помилок Slack -- email message ids і headers для email bugs -- знімки екрана браузера, коли UI є єдиним надійним observable +- стан реакцій Discord для багів реакцій +- посилання на повідомлення Discord для багів threading +- thread ts Slack і стан API реакцій для багів Slack +- ids повідомлень email і headers для багів email +- знімки екрана браузера, коли UI є єдиним надійним спостережуваним сигналом -Vision checks мають бути додатковими. Якщо API платформи може довести помилку, використовуйте -API як pass/fail oracle і залишайте знімки екрана для людської впевненості. +Vision-перевірки мають бути додатковими. Якщо platform API може довести баг, використовуйте +API як oracle pass/fail і зберігайте знімки екрана для людської впевненості. -## Розширення provider +## Розширення провайдера Після Discord той самий runner може додати: -- Slack: reactions, threads, app mentions, modals, file uploads. -- Email: Gmail auth і message threading з використанням `gog`, де connectors недостатньо. -- WhatsApp: QR login, re-identification, message delivery, media, reactions. -- Telegram: group mention gating, commands, reactions where available. -- Matrix: encrypted rooms, thread або reply relations, restart resume. +- Slack: реакції, гілки, згадки застосунку, модальні вікна, завантаження файлів. +- Email: автентифікація Gmail і групування повідомлень у ланцюжки за допомогою `gog`, коли конекторів недостатньо. +- WhatsApp: вхід через QR, повторна ідентифікація, доставлення повідомлень, медіа, реакції. +- Telegram: обмеження згадок у групах, команди, реакції там, де доступно. +- Matrix: зашифровані кімнати, зв’язки гілок або відповідей, відновлення після перезапуску. -Кожен transport має мати один дешевий smoke scenario і один або більше bug-class -scenarios. Дорогі visual scenarios мають залишатися opt-in. +Кожен транспорт повинен мати один дешевий smoke-сценарій і один або кілька сценаріїв класів помилок. Дорогі візуальні сценарії мають залишатися опційними. ## Відкриті питання -- Який Discord bot має бути driver, а який SUT, коли - наявний Mantis bot використовується повторно? -- Чи observer browser login має використовувати людський обліковий запис Discord, test account - або лише bot-readable REST evidence для першої фази? -- Як довго GitHub має зберігати артефакти Mantis для PRs? -- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування - команди maintainer? -- Чи потрібно редагувати або обрізати знімки екрана перед upload для public PRs? +- Який Discord-бот має бути драйвером, а який SUT, коли повторно використовується наявний бот Mantis? +- Чи має вхід браузера-спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис або лише доступні боту REST-докази для першого етапу? +- Як довго GitHub має зберігати артефакти Mantis для PR? +- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування команди від супровідника? +- Чи потрібно редагувати або обрізати знімки екрана перед завантаженням для публічних PR?