diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index df10c807a..c8ccbbc80 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,63 +1,63 @@ --- read_when: - - Розуміння того, як поєднується стек QA + - Розуміння того, як стек QA поєднується в єдину систему - Розширення qa-lab, qa-channel або адаптера транспорту - - Додавання QA-сценаріїв з опорою на репозиторій + - Додавання сценаріїв QA з прив’язкою до репозиторію - Створення більш реалістичної автоматизації QA навколо панелі керування Gateway -summary: 'Огляд стеку QA: qa-lab, qa-channel, сценарії з опорою на репозиторій, live-канали транспорту, адаптери транспорту та звітність.' +summary: 'Огляд стека QA: qa-lab, qa-channel, сценарії з прив’язкою до репозиторію, лінії живого транспорту, адаптери транспорту та звітність.' title: Огляд QA x-i18n: - generated_at: "2026-04-27T17:44:07Z" + generated_at: "2026-04-27T17:51:57Z" model: gpt-5.4 provider: openai - source_hash: 75c47dc9a430d54c2a701a70efbe098a3ddecef74afe91c4e594f5eea9e57bbb + source_hash: 59d5f32e674cd32a08094b475ba72a70233437d2f8be26a53205628d9770fd6d source_path: concepts/qa-e2e-automation.md workflow: 15 --- -Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний, -каналоподібний спосіб, ніж це може зробити окремий модульний тест. +Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, +орієнтований на канали спосіб, ніж це може зробити один модульний тест. Поточні складові: - `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, - реакції, редагування та видалення. -- `extensions/qa-lab`: UI налагоджувача та шина QA для спостереження за транскриптом, - ін’єкції вхідних повідомлень і експорту Markdown-звіту. -- `extensions/qa-matrix`, майбутні плагіни-ранери: адаптери live-транспорту, які - керують реальним каналом усередині дочірнього QA Gateway. -- `qa/`: seed-ресурси з опорою на репозиторій для стартового завдання та базових - QA-сценаріїв. + реакцій, редагування та видалення. +- `extensions/qa-lab`: інтерфейс налагодження та шина QA для спостереження за транскриптом, + інʼєкції вхідних повідомлень і експорту звіту у форматі Markdown. +- `extensions/qa-matrix`, майбутні runner-плагіни: адаптери живого транспорту, які + керують реальним каналом усередині дочірнього шлюзу QA. +- `qa/`: seed-ресурси з прив’язкою до репозиторію для стартового завдання та базових + сценаріїв QA. ## Поверхня команд Усі потоки QA запускаються через `pnpm openclaw qa `. Багато з них мають -псевдоніми скриптів `pnpm qa:*`; підтримуються обидві форми. +аліаси скриптів `pnpm qa:*`; підтримуються обидві форми. -| Команда | Призначення | -| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | Вбудована самоперевірка QA; записує Markdown-звіт. | -| `qa suite` | Запуск сценаріїв з опорою на репозиторій на смузі QA Gateway. Псевдоніми: `pnpm openclaw qa suite --runner multipass` для тимчасової Linux VM. | -| `qa coverage` | Виводить Markdown-інвентар покриття сценаріїв (`--json` для машинного виводу). | -| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує агентний звіт parity-gate. | -| `qa character-eval` | Запускає character QA-сценарій на кількох live-моделях із оціненим звітом. Див. [Звітність](#reporting). | -| `qa manual` | Запускає одноразовий промпт на вибраній смузі провайдера/моделі. | -| `qa ui` | Запускає UI налагоджувача QA та локальну шину QA (псевдонім: `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Збирає попередньо підготовлений Docker-образ QA. | -| `qa docker-scaffold` | Записує шаблон docker-compose для панелі керування QA + смуги 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` | Запускає лише сервер провайдера `mock-openai` з урахуванням сценаріїв. | -| `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. | -| `qa matrix` | Смуга live-транспорту з тимчасовим homeserver Tuwunel. Див. [Matrix QA](/uk/concepts/qa-matrix). | -| `qa telegram` | Смуга live-транспорту проти реальної приватної групи Telegram. | -| `qa discord` | Смуга live-транспорту проти реального приватного каналу Discord guild. | +| Команда | Призначення | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `qa run` | Вбудована самоперевірка QA; записує звіт у форматі Markdown. | +| `qa suite` | Запускає сценарії з прив’язкою до репозиторію проти лінії шлюзу QA. Аліаси: `pnpm openclaw qa suite --runner multipass` для тимчасової Linux VM. | +| `qa coverage` | Виводить інвентар покриття сценаріїв у markdown (`--json` для машинного виводу). | +| `qa parity-report` | Порівнює два файли `qa-suite-summary.json` і записує agentic parity-gate звіт. | +| `qa character-eval` | Запускає сценарій character QA на кількох живих моделях з оціненим звітом. Див. [Звітність](#reporting). | +| `qa manual` | Запускає одноразовий prompt проти вибраної лінії provider/model. | +| `qa ui` | Запускає інтерфейс налагодження QA та локальну шину QA (аліас: `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Збирає попередньо підготовлений Docker-образ QA. | +| `qa docker-scaffold` | Записує scaffold docker-compose для панелі QA + лінії шлюзу. | +| `qa up` | Збирає сайт QA, запускає стек на базі Docker, виводить URL (аліас: `pnpm qa:lab:up`; варіант `:fast` додає `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Запускає лише сервер provider AIMock. | +| `qa mock-openai` | Запускає лише сервер provider `mock-openai`, обізнаний про сценарії. | +| `qa credentials doctor` / `add` / `list` / `remove` | Керує спільним пулом облікових даних Convex. | +| `qa matrix` | Лінія живого транспорту проти тимчасового homeserver Tuwunel. Див. [Matrix QA](/uk/concepts/qa-matrix). | +| `qa telegram` | Лінія живого транспорту проти реальної приватної групи Telegram. | +| `qa discord` | Лінія живого транспорту проти реального каналу Discord guild. | ## Потік роботи оператора Поточний потік роботи оператора QA — це двопанельний сайт QA: -- Ліворуч: панель керування Gateway (Control UI) з агентом. +- Ліворуч: панель Gateway (Control UI) з агентом. - Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. Запустіть його так: @@ -66,12 +66,12 @@ x-i18n: pnpm qa:lab:up ``` -Це збирає сайт QA, запускає смугу Gateway з опорою на Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, -спостерігати за реальною поведінкою каналу та фіксувати, що спрацювало, що -не спрацювало або що залишилося заблокованим. +Це збирає сайт QA, запускає лінію шлюзу на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту +місію QA, спостерігати реальну поведінку каналу та фіксувати, що спрацювало, +що не спрацювало або що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без перебудови Docker-образу щоразу +Для швидшої ітерації інтерфейсу QA Lab без щоразу повторного збирання Docker-образу запустіть стек із bind-mounted збіркою QA Lab: ```bash @@ -81,125 +81,194 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` тримає Docker-сервіси на попередньо зібраному образі та -bind-mount’ить `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перебудовує цю збірку при змінах, а браузер автоматично перезавантажується, -коли змінюється хеш ресурсу QA Lab. +`qa:lab:up:fast` залишає сервіси Docker на попередньо зібраному образі та bind-mount +монтує `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` +перезбирає цю збірку при змінах, а браузер автоматично перезавантажується, коли +змінюється хеш ресурсів QA Lab. -Для локального smoke-тесту трасування OpenTelemetry виконайте: +Для локальної smoke-перевірки трасування OpenTelemetry виконайте: ```bash pnpm qa:otel:smoke ``` Цей скрипт запускає локальний приймач трас OTLP/HTTP, виконує -QA-сценарій `otel-trace-smoke` з увімкненим плагіном `diagnostics-otel`, а потім -декодує експортовані protobuf span-и та перевіряє критичну для релізу форму: +сценарій QA `otel-trace-smoke` з увімкненим плагіном `diagnostics-otel`, а потім +декодує експортовані spans protobuf і перевіряє критично важливу для релізу форму: мають бути присутні `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` і `openclaw.message.delivery`; виклики моделей не повинні експортувати `StreamAbandoned` у разі успішних ходів; сирі діагностичні ID та -атрибути `openclaw.content.*` не повинні потрапляти до трасування. Він записує -`otel-smoke-summary.json` поруч з артефактами QA suite. +атрибути `openclaw.content.*` не повинні потрапляти до траси. Файл +`otel-smoke-summary.json` записується поруч з артефактами набору QA. -Observability QA лишається доступним лише з checkout вихідного коду. npm tarball -навмисно не містить QA Lab, тому смуги релізу пакетів Docker не запускають -команди `qa`. Використовуйте `pnpm qa:otel:smoke` з checkout зібраного вихідного коду -під час змін в інструментуванні діагностики. +Observability QA залишається доступним лише з checkout вихідного коду. У npm tarball навмисно +не включено QA Lab, тому лінії релізу Docker-пакета не запускають команди `qa`. Використовуйте +`pnpm qa:otel:smoke` із checkout зібраного вихідного коду при зміні інструментації +діагностики. -Для transport-real smoke-смуги Matrix виконайте: +Для smoke-лінії Matrix з реальним транспортом виконайте: ```bash pnpm openclaw qa matrix --profile fast --fail-fast ``` -Повний довідник CLI, каталог профілів/сценаріїв, змінні середовища та структура артефактів для цієї смуги наведено в [Matrix QA](/uk/concepts/qa-matrix). Коротко: вона розгортає тимчасовий homeserver Tuwunel у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний плагін Matrix усередині дочірнього QA Gateway, обмеженого цим транспортом (без `qa-channel`), а потім записує Markdown-звіт, JSON-зведення, артефакт observed-events і об’єднаний журнал виводу в `.artifacts/qa-e2e/matrix-/`. +Повний довідник CLI, каталог профілів/сценаріїв, змінні env і структура артефактів для цієї лінії містяться в [Matrix QA](/uk/concepts/qa-matrix). Коротко: вона розгортає тимчасовий homeserver Tuwunel у Docker, реєструє тимчасових користувачів driver/SUT/observer, запускає реальний плагін Matrix усередині дочірнього шлюзу QA, обмеженого цим транспортом (без `qa-channel`), а потім записує звіт Markdown, підсумок JSON, артефакт observed-events і обʼєднаний лог виводу до `.artifacts/qa-e2e/matrix-/`. -Для transport-real smoke-смуги Telegram виконайте: +Для smoke-ліній Telegram і Discord з реальним транспортом: ```bash pnpm openclaw qa telegram +pnpm openclaw qa discord ``` -Ця смуга націлюється на одну реальну приватну групу Telegram замість -розгортання тимчасового сервера. Для неї потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, -`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також два різні боти в одній -приватній групі. Бот SUT повинен мати ім’я користувача Telegram, а спостереження -bot-to-bot працює найкраще, коли в обох ботів увімкнено режим Bot-to-Bot Communication Mode -у `@BotFather`. Установіть `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`, щоб зберігати -тіла повідомлень в артефактах observed-message (типово вони редагуються). -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо -вам потрібні артефакти без коду завершення з помилкою. -Звіт і зведення Telegram включають RTT для кожної відповіді — від запиту на -надсилання повідомлення драйвером до спостережуваної відповіді SUT, починаючи з canary. +Обидві орієнтовані на заздалегідь наявний реальний канал із двома ботами (driver + SUT). Обов’язкові змінні env, списки сценаріїв, вихідні артефакти та спільний пул облікових даних Convex задокументовано нижче в розділі [Довідник QA для Telegram і Discord](#telegram-and-discord-qa-reference). -Перед використанням pooled live-облікових даних виконайте: +Перед використанням спільних живих облікових даних виконайте: ```bash pnpm openclaw qa credentials doctor ``` -Doctor перевіряє env брокера Convex, валідує налаштування endpoint і перевіряє -досяжність admin/list, коли присутній секрет супроводжувача. Він повідомляє лише -статус set/missing для секретів. +Doctor перевіряє env брокера Convex, валідовує налаштування endpoint і перевіряє доступність admin/list, коли присутній секрет супровідника. Для секретів він повідомляє лише про стан set/missing. -Для transport-real smoke-смуги Discord виконайте: +## Покриття живого транспорту -```bash -pnpm openclaw qa discord -``` +Лінії живого транспорту використовують один контракт, замість того щоб кожна вигадувала власну форму списку сценаріїв. `qa-channel` — це широкий синтетичний набір перевірок поведінки продукту, і він не є частиною матриці покриття живого транспорту. -Ця смуга націлюється на один реальний приватний канал Discord guild із двома ботами: ботом -driver, яким керує harness, і ботом SUT, який запускається дочірнім -OpenClaw Gateway через комплектний плагін Discord. Для неї потрібні -`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` у разі використання env-облікових даних. Установіть -`OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`, щоб зберігати тіла повідомлень в -артефактах observed-message (типово вони редагуються). -Смуга перевіряє обробку згадок каналу та перевіряє, що бот SUT -зареєстрував у Discord нативну команду `/help`. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо -вам потрібні артефакти без коду завершення з помилкою. +| Лінія | Канарейка | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція треду | Спостереження за реакціями | Команда help | Нативна реєстрація команд | +| -------- | --------- | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | -------------- | -------------------------- | ------------ | ------------------------- | +| Matrix | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | | | | | | | x | | +| Discord | x | x | | | | | | | | x | -## Покриття live-транспорту +Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix, +Telegram і майбутні живі транспорти мають спільний явний контрольний список +контрактів транспорту. -Live-смуги транспорту використовують спільний контракт замість того, щоб кожна вигадувала власну форму списку сценаріїв. `qa-channel` — це широкий синтетичний набір перевірок поведінки продукту, і він не входить до матриці покриття live-транспорту. - -| Смуга | Canary | Обмеження за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша взаємодія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | Реєстрація нативної команди | -| -------- | ------ | --------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | | | | | | | x | | -| Discord | x | x | | | | | | | | x | - -Це залишає `qa-channel` широким набором перевірок поведінки продукту, тоді як Matrix, -Telegram і майбутні live-транспорти спільно використовують один явний -контрольний список транспортного контракту. - -Для смуги з тимчасовою Linux VM без залучення Docker у шлях QA виконайте: +Для лінії на тимчасовій Linux VM без використання Docker у шляху QA виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує новий гість Multipass, установлює залежності, збирає OpenClaw -усередині гостя, запускає `qa suite`, а потім копіює звичайний QA-звіт і -зведення назад до `.artifacts/qa-e2e/...` на хості. -Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. -Запуски suite на хості й у Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими worker-ами Gateway. `qa-channel` за замовчуванням використовує рівень паралелізму 4, -обмежений кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість worker-ів, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо +Це завантажує нову гостьову систему Multipass, встановлює залежності, збирає OpenClaw +усередині гостя, запускає `qa suite`, а потім копіює звичайний звіт і +підсумок QA назад у `.artifacts/qa-e2e/...` на хості. +Використовується така сама поведінка вибору сценаріїв, як і в `qa suite` на хості. +Запуски наборів на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно +з ізольованими worker-процесами шлюзу. Для `qa-channel` за замовчуванням використовується concurrency +4, обмежене кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати +кількість worker-процесів, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. -Live-запуски передають підтримувані QA-входи автентифікації, які практичні для -гостьової системи: ключі провайдерів на основі env, шлях до конфігурації QA live provider і +Живі запуски передають підтримувані вхідні дані автентифікації QA, які практичні для +гостя: ключі provider на основі env, шлях до конфігурації живого provider QA і `CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість -міг записувати назад через змонтований робочий простір. +міг записувати дані назад через змонтований workspace. -## Seed-ресурси з опорою на репозиторій +## Довідник QA для Telegram і Discord -Seed-ресурси розміщені в `qa/`: +Matrix має [окрему сторінку](/uk/concepts/qa-matrix) через кількість сценаріїв і розгортання homeserver на базі Docker. Telegram і Discord менші — лише кілька сценаріїв у кожному, без системи профілів, проти вже наявних реальних каналів — тому їхній довідник міститься тут. + +### Спільні прапорці CLI + +Обидві лінії реєструються через `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` і приймають однакові прапорці: + +| Прапорець | За замовчуванням | Опис | +| ------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Запустити лише цей сценарій. Можна вказувати повторно. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord}-` | Куди записуються звіти/підсумок/спостережені повідомлення та журнал виводу. Відносні шляхи обчислюються від `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального cwd. | +| `--sut-account ` | `sut` | Ідентифікатор тимчасового облікового запису всередині конфігурації шлюзу QA. | +| `--provider-mode ` | `live-frontier` | `mock-openai` або `live-frontier` (застарілий `live-openai` також працює). | +| `--model ` / `--alt-model ` | provider default | Посилання на основну/альтернативну модель. | +| `--fast` | вимкнено | Швидкий режим provider там, де він підтримується. | +| `--credential-source ` | `env` | Див. [Спільний пул облікових даних Convex](#convex-credential-pool). | +| `--credential-role ` | `ci` у CI, інакше `maintainer` | Роль, що використовується з `--credential-source convex`. | + +Обидві команди завершуються з ненульовим кодом у разі помилки будь-якого сценарію. `--allow-failures` записує артефакти без встановлення коду завершення з помилкою. + +### Telegram QA + +```bash +pnpm openclaw qa telegram +``` + +Націлено на одну реальну приватну групу Telegram із двома різними ботами (driver + SUT). Бот SUT повинен мати ім’я користувача Telegram; спостереження бот-до-бота працює найкраще, коли в обох ботів увімкнено **Bot-to-Bot Communication Mode** у `@BotFather`. + +Обов’язкові змінні env при `--credential-source env`: + +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — числовий ідентифікатор чату (рядок). +- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` +- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` + +Необов’язково: + +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах observed-message (за замовчуванням вони редагуються). + +Сценарії (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`): + +- `telegram-canary` +- `telegram-mention-gating` +- `telegram-mentioned-message-reply` +- `telegram-help-command` +- `telegram-commands-command` +- `telegram-tools-compact-command` +- `telegram-whoami-command` +- `telegram-context-command` + +Вихідні артефакти: + +- `telegram-qa-report.md` +- `telegram-qa-summary.json` — містить RTT для кожної відповіді (надсилання driver → спостережена відповідь SUT), починаючи з canary. +- `telegram-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. + +### Discord QA + +```bash +pnpm openclaw qa discord +``` + +Націлено на один реальний приватний канал Discord guild із двома ботами: ботом driver, яким керує harness, і ботом SUT, що запускається дочірнім шлюзом OpenClaw через вбудований плагін Discord. Перевіряє обробку згадок у каналі та те, що бот SUT зареєстрував нативну команду `/help` у Discord. + +Обов’язкові змінні 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_CAPTURE_CONTENT=1` зберігає тіла повідомлень в артефактах observed-message. + +Сценарії (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`): + +- `discord-canary` +- `discord-mention-gating` +- `discord-native-help-command-registration` + +Вихідні артефакти: + +- `discord-qa-report.md` +- `discord-qa-summary.json` +- `discord-qa-observed-messages.json` — тіла редагуються, якщо не встановлено `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`. + +### Спільний пул облікових даних Convex + +І лінії Telegram, і лінії Discord можуть орендувати облікові дані зі спільного пулу Convex замість читання наведених вище змінних env. Передайте `--credential-source convex` (або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab отримує ексклюзивну оренду, надсилає Heartbeat протягом усього запуску та звільняє її під час завершення роботи. Види пулів — `"telegram"` і `"discord"`. + +Форми payload, які брокер валідовує на `admin/add`: + +- 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 }`. + +Операційні змінні env і контракт endpoint брокера Convex описані в [Testing → Shared Telegram credentials via Convex](/uk/help/testing#shared-telegram-credentials-via-convex-v1) (назва розділу передує підтримці Discord; семантика брокера однакова для обох видів). + +## Seeds із прив’язкою до репозиторію + +Seed-ресурси містяться в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` @@ -207,113 +276,113 @@ Seed-ресурси розміщені в `qa/`: Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. -`qa-lab` має залишатися універсальним markdown-ранером. Кожен markdown-файл сценарію є -джерелом істини для одного тестового запуску і має визначати: +`qa-lab` має залишатися універсальним markdown-runner. Кожен markdown-файл сценарію +є джерелом істини для одного тестового запуску й повинен визначати: - метадані сценарію -- необов’язкові метадані категорії, можливостей, смуги та ризику -- посилання на документацію та код -- необов’язкові вимоги до плагінів -- необов’язковий patch конфігурації Gateway +- необов’язкові метадані category, capability, lane та risk +- посилання на docs і code +- необов’язкові вимоги до Plugin +- необов’язковий патч конфігурації шлюзу - виконуваний `qa-flow` -Універсальна поверхня рантайму, що підтримує `qa-flow`, може залишатися загальною -і наскрізною. Наприклад, markdown-сценарії можуть поєднувати допоміжні засоби з боку -транспорту з допоміжними засобами з боку браузера, які керують вбудованим Control UI через -інтерфейс Gateway `browser.request`, без додавання спеціального раннера. +Багаторазова runtime-поверхня, що підтримує `qa-flow`, може залишатися універсальною +і наскрізною. Наприклад, markdown-сценарії можуть поєднувати допоміжні +засоби на боці транспорту з допоміжними засобами на боці браузера, які керують вбудованим Control UI через +шов Gateway `browser.request`, не додаючи спеціалізований runner. -Файли сценаріїв слід групувати за можливостями продукту, а не за папкою дерева -вихідного коду. Зберігайте стабільність ID сценаріїв під час переміщення файлів; використовуйте -`docsRefs` і `codeRefs` для відстежуваності реалізації. +Файли сценаріїв слід групувати за можливостями продукту, а не за папкою +дерева вихідного коду. Зберігайте стабільність ідентифікаторів сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` +для трасування реалізації. -Базовий список має залишатися достатньо широким, щоб покривати: +Базовий список має залишатися достатньо широким, щоб охоплювати: -- DM і чат у каналі +- чат у DM і каналі - поведінку тредів - життєвий цикл дій із повідомленнями -- Cron callbacks -- виклик пам’яті +- зворотні виклики Cron +- пригадування пам’яті - перемикання моделей -- передавання до subagent +- передачу до субагента - читання репозиторію та документації -- одне невелике завдання зі збірки, наприклад Lobster Invaders +- одне невелике завдання зі збирання, наприклад Lobster Invaders -## Смуги mock-провайдерів +## Mock-лінії provider -`qa suite` має дві локальні смуги mock-провайдерів: +`qa suite` має дві локальні mock-лінії provider: -- `mock-openai` — це mock OpenClaw з урахуванням сценаріїв. Він залишається - типовою детермінованою mock-смугою для QA з опорою на репозиторій і parity gate. -- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколу, - фікстур, запису/відтворення та chaos. Він є додатковим і не - замінює диспетчер сценаріїв `mock-openai`. +- `mock-openai` — це mock OpenClaw, обізнаний про сценарії. Він залишається + типовою детермінованою mock-лінією для QA з прив’язкою до репозиторію та parity gate. +- `aimock` запускає сервер provider на базі AIMock для експериментального + покриття протоколів, фікстур, запису/відтворення та chaos-перевірок. Це доповнення і воно не + замінює dispatcher сценаріїв `mock-openai`. -Реалізація смуг провайдера знаходиться в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделі Gateway, -потребами staging auth-profile та прапорцями можливостей live/mock. Спільний код suite і -Gateway має маршрутизувати через реєстр провайдерів замість розгалуження за -іменами провайдерів. +Реалізація provider-ліній міститься в `extensions/qa-lab/src/providers/`. +Кожен provider володіє своїми значеннями за замовчуванням, запуском локального сервера, конфігурацією моделі шлюзу, +потребами staging auth-profile і прапорцями можливостей live/mock. Спільний код suite і +шлюзу має маршрутизуватися через реєстр provider, а не розгалужуватися за +іменами provider. ## Адаптери транспорту -`qa-lab` володіє універсальним інтерфейсом транспорту для markdown QA-сценаріїв. `qa-channel` — перший адаптер на цьому інтерфейсі, але ціль архітектури ширша: майбутні реальні або синтетичні канали мають підключатися до того самого раннера suite замість додавання transport-specific QA-ранера. +`qa-lab` володіє універсальним швом транспорту для markdown-сценаріїв QA. `qa-channel` — перший адаптер на цьому шві, але ціль дизайну ширша: майбутні реальні або синтетичні канали мають підключатися до того самого runner наборів замість додавання transport-specific runner QA. На рівні архітектури розподіл такий: -- `qa-lab` володіє універсальним виконанням сценаріїв, паралельністю worker-ів, записом артефактів і звітністю. -- Адаптер транспорту володіє конфігурацією Gateway, готовністю, спостереженням за вхідними й вихідними подіями, транспортними діями та нормалізованим станом транспорту. -- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає універсальну поверхню рантайму, яка їх виконує. +- `qa-lab` володіє універсальним виконанням сценаріїв, concurrency worker-процесів, записом артефактів і звітністю. +- Адаптер транспорту володіє конфігурацією шлюзу, готовністю, спостереженням за вхідними й вихідними подіями, діями транспорту та нормалізованим станом транспорту. +- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає багаторазову runtime-поверхню, яка їх виконує. ### Додавання каналу Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Адаптера транспорту для каналу. -2. Пакета сценаріїв, який перевіряє контракт каналу. +1. Адаптер транспорту для каналу. +2. Набір сценаріїв, що перевіряє контракт каналу. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може володіти цим потоком. `qa-lab` володіє спільною механікою хоста: - коренем команди `openclaw qa` -- запуском і зупинкою suite -- паралельністю worker-ів +- запуском і завершенням набору +- concurrency worker-процесів - записом артефактів - генерацією звітів - виконанням сценаріїв -- псевдонімами сумісності для старіших сценаріїв `qa-channel` +- аліасами сумісності для старіших сценаріїв `qa-channel` -Плагіни-ранери володіють транспортним контрактом: +Runner-плагіни володіють транспортним контрактом: -- тим, як `openclaw qa ` монтується під спільним коренем `qa` -- тим, як Gateway конфігурується для цього транспорту -- тим, як перевіряється готовність -- тим, як ін’єктуються вхідні події -- тим, як спостерігаються вихідні повідомлення -- тим, як надаються транскрипти й нормалізований стан транспорту -- тим, як виконуються дії з опорою на транспорт -- тим, як обробляються transport-specific скидання або очищення +- як `openclaw qa ` монтується під спільним коренем `qa` +- як шлюз налаштовується для цього транспорту +- як перевіряється готовність +- як інʼєктуються вхідні події +- як спостерігаються вихідні повідомлення +- як надаються транскрипти та нормалізований стан транспорту +- як виконуються дії на основі транспорту +- як обробляється transport-specific скидання або очищення -Мінімальна планка впровадження для нового каналу: +Мінімальний поріг прийняття для нового каналу: -1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте транспортний раннер на спільному інтерфейсі хоста `qa-lab`. -3. Тримайте transport-specific механіку всередині плагіна-ранера або harness каналу. -4. Монтуйте раннер як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. Плагіни-ранери мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і раннера має залишатися за окремими entrypoint. +1. Залиште `qa-lab` власником спільного кореня `qa`. +2. Реалізуйте transport runner на спільному хостовому шві `qa-lab`. +3. Тримайте transport-specific механіку всередині runner-плагіна або harness каналу. +4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючий кореневий простір команд. Runner-плагіни мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте універсальні helper-и сценаріїв для нових сценаріїв. -7. Зберігайте роботу наявних псевдонімів сумісності, якщо в репозиторії не виконується навмисна міграція. +6. Використовуйте універсальні helper для нових сценаріїв. +7. Зберігайте роботу наявних аліасів сумісності, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішення суворе: +Правило ухвалення рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного канального транспорту, тримайте її в цьому плагіні-ранері або harness плагіна. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додавайте універсальний helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. +- Якщо поведінка залежить від транспорту одного каналу, тримайте її в цьому runner-плагіні або harness плагіна. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте універсальний helper замість branch для конкретного каналу в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію. -### Назви helper-ів сценаріїв +### Назви helper сценаріїв -Бажані універсальні helper-и для нових сценаріїв: +Переважні універсальні helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -328,22 +397,22 @@ Gateway має маршрутизувати через реєстр провай - `formatTransportTranscript` - `resetTransport` -Псевдоніми сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але для створення нових сценаріїв слід використовувати універсальні назви. Ці псевдоніми існують, щоб уникнути міграції в один день, а не як модель на майбутнє. +Аліаси сумісності залишаються доступними для наявних сценаріїв — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — але для створення нових сценаріїв слід використовувати універсальні назви. Аліаси існують, щоб уникнути міграції в один день, а не як модель на майбутнє. ## Звітність -`qa-lab` експортує Markdown-протокольний звіт зі спостережуваної часової шкали шини. -Звіт має відповідати на запитання: +`qa-lab` експортує протокольний звіт Markdown зі спостережуваної часової шкали шини. +Звіт має відповідати на такі запитання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим -- Які подальші сценарії варто додати +- Які follow-up сценарії варто додати -Щоб отримати інвентар доступних сценаріїв — корисний під час оцінки подальшої роботи або підключення нового транспорту — виконайте `pnpm openclaw qa coverage` (додайте `--json` для машинозчитуваного виводу). +Щоб отримати інвентар доступних сценаріїв — корисний під час оцінювання обсягу подальших робіт або підключення нового транспорту — виконайте `pnpm openclaw qa coverage` (додайте `--json` для машинозчитуваного виводу). -Для перевірок характеру та стилю запускайте той самий сценарій на кількох refs live-моделей -і записуйте оцінений Markdown-звіт: +Для перевірок характеру та стилю запустіть той самий сценарій на кількох живих +посиланнях моделей і запишіть оцінений звіт у форматі Markdown: ```bash pnpm openclaw qa character-eval \ @@ -362,41 +431,41 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси QA Gateway, а не Docker. Сценарії character eval -мають задавати persona через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, -такі як чат, допомога з робочим простором і невеликі файлові завдання. Моделі-кандидату +Команда запускає локальні дочірні процеси шлюзу QA, а не Docker. Сценарії character eval +мають задавати persona через `SOUL.md`, а потім виконувати звичайні ходи користувача, +такі як чат, допомога з workspace і невеликі файлові завдання. Кандидатній моделі не слід повідомляти, що її оцінюють. Команда зберігає кожен повний -транскрипт, записує базову статистику запуску, а потім просить моделі-судді в fast mode з -міркуванням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` при порівнянні провайдерів: prompt судді однаково отримує -кожен транскрипт і статус запуску, але refs кандидатів замінюються нейтральними -мітками на кшталт `candidate-01`; після парсингу звіт зіставляє ранги назад із реальними refs. -Для запусків кандидатів за замовчуванням використовується thinking `high`, `medium` для GPT-5.5 і `xhigh` -для старіших eval refs OpenAI, які це підтримують. Замініть значення для конкретного кандидата прямо в рядку через +транскрипт, записує базову статистику запуску, а потім просить моделі-оцінювачі в швидкому режимі з +мисленням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. +Використовуйте `--blind-judge-models` при порівнянні provider: prompt оцінювання все одно отримує +кожен транскрипт і статус запуску, але посилання кандидатів замінюються нейтральними +мітками на кшталт `candidate-01`; після парсингу звіт зіставляє ранжування назад із реальними посиланнями. +Для кандидатних запусків за замовчуванням використовується мислення `high`, з `medium` для GPT-5.5 і `xhigh` +для старіших посилань OpenAI eval, які це підтримують. Перевизначте конкретного кандидата безпосередньо через `--model provider/model,thinking=`. `--thinking ` як і раніше задає -глобальне резервне значення, а старіша форма `--model-thinking ` зберігається +глобальний резервний варіант, а старіша форма `--model-thinking ` зберігається для сумісності. -Refs кандидатів OpenAI за замовчуванням використовують fast mode, щоб застосовувалася пріоритетна обробка там, -де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` прямо в рядку, коли -одному кандидату або судді потрібно перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість роботи кандидатів і суддів -записується у звіті для аналізу бенчмарків, але в prompt-ах для суддів явно сказано +Для посилань кандидатів OpenAI за замовчуванням використовується швидкий режим, щоб застосовувалася +обробка з пріоритетом там, де provider це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` безпосередньо, коли +окремому кандидату або оцінювачу потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете +примусово ввімкнути швидкий режим для кожної кандидатної моделі. Тривалість роботи кандидатів і оцінювачів +записується у звіті для аналізу бенчмарків, але prompts оцінювання явно вказують не ранжувати за швидкістю. -Запуски моделей-кандидатів і моделей-суддів за замовчуванням обидва мають паралельність 16. Зменшуйте -`--concurrency` або `--judge-concurrency`, коли обмеження провайдера або навантаження на локальний Gateway +І для кандидатних, і для суддівських запусків моделей за замовчуванням використовується concurrency 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, коли обмеження provider або навантаження на локальний шлюз роблять запуск надто шумним. -Якщо не передано жодного кандидатського `--model`, для character eval за замовчуванням використовуються +Якщо не передано жодного кандидатного `--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`, суддями за замовчуванням є +Якщо не передано жодного `--judge-model`, за замовчуванням використовуються оцінювачі `openai/gpt-5.5,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. -## Пов’язана документація +## Пов’язані документи - [Matrix QA](/uk/concepts/qa-matrix) -- [QA Channel](/uk/channels/qa-channel) -- [Testing](/uk/help/testing) -- [Dashboard](/uk/web/dashboard) +- [Канал QA](/uk/channels/qa-channel) +- [Тестування](/uk/help/testing) +- [Панель керування](/uk/web/dashboard)