From cdd7d4bda824fd3c44585ee322ecbe29b9b1557a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 7 Apr 2026 22:41:55 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/qa-e2e-automation.md | 71 ++-- docs/uk/refactor/qa.md | 536 ++++++++++++++++++++++++++ 2 files changed, 571 insertions(+), 36 deletions(-) create mode 100644 docs/uk/refactor/qa.md diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index eff5d2788..ffe01b928 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,51 +1,51 @@ --- read_when: - Розширення qa-lab або qa-channel - - Додавання QA-сценаріїв, що підтримуються репозиторієм + - Додавання QA-сценаріїв із підтримкою репозиторію - Побудова реалістичнішої QA-автоматизації навколо панелі Gateway -summary: Форма приватної QA-автоматизації для qa-lab, qa-channel, підготовлених сценаріїв і звітів за протоколом -title: QA E2E Automation +summary: Форма приватної QA-автоматизації для qa-lab, qa-channel, початкових сценаріїв і звітів за протоколом +title: QA E2E-автоматизація x-i18n: - generated_at: "2026-04-07T08:57:00Z" + generated_at: "2026-04-07T22:41:23Z" model: gpt-5.4 provider: openai - source_hash: b68cfcfb50532dbda93ba62e1ed8dc6a7ddd4214cb1db8c9a84a7bc0b32b3060 + source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# QA E2E Automation +# QA E2E-автоматизація -Приватний стек QA призначений для перевірки OpenClaw у реалістичніший, -орієнтований на канали спосіб, ніж це може зробити один unit-тест. +Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний, +орієнтований на канали спосіб, ніж це може зробити один модульний тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, гілки, - реакцій, редагування та видалення. -- `extensions/qa-lab`: UI налагодження та шина QA для спостереження за транскриптом, - інʼєкції вхідних повідомлень і експорту звіту у Markdown. -- `qa/`: ресурси підготовки, що підтримуються репозиторієм, для початкового завдання та базових QA +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, channel, thread, + reaction, edit і delete. +- `extensions/qa-lab`: UI для налагодження та шина QA для спостереження за транскриптом, + введення вхідних повідомлень і експорту Markdown-звіту. +- `qa/`: ресурси початкових даних із підтримкою репозиторію для стартового завдання та базових QA сценаріїв. Поточний робочий процес оператора QA — це двопанельний QA-сайт: - Ліворуч: панель Gateway (Control UI) з агентом. -- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. +- Праворуч: QA Lab, що показує схожий на Slack транскрипт і план сценарію. -Запустіть це так: +Запустіть його так: ```bash pnpm qa:lab:up ``` -Це збирає QA-сайт, запускає lane Gateway на базі Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту -QA-місію, спостерігати реальну поведінку каналу та записувати, що спрацювало, -що не спрацювало або залишилося заблокованим. +Це збирає QA-сайт, запускає доріжку gateway на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA-місію, +спостерігати за реальною поведінкою каналу та фіксувати, що спрацювало, що не +спрацювало або що залишилося заблокованим. -Щоб швидше ітерувати UI QA Lab без повторного збирання Docker-образу щоразу, -запустіть стек із QA Lab bundle, змонтованим через bind mount: +Щоб швидше ітеруватися над UI QA Lab без перебудови Docker-образу щоразу, +запустіть стек із bind-mounted збіркою QA Lab: ```bash pnpm openclaw qa docker-build-image @@ -54,41 +54,40 @@ 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` -перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсів QA Lab. +перебудовує цей bundle при змінах, а браузер автоматично перезавантажується, коли змінюється хеш ресурсу QA Lab. -## Ресурси підготовки, що підтримуються репозиторієм +## Початкові дані з підтримкою репозиторію -Ресурси підготовки розміщені в `qa/`: +Ресурси початкових даних розміщено в `qa/`: -- `qa/QA_KICKOFF_TASK.md` -- `qa/seed-scenarios.json` +- `qa/scenarios.md` Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. Базовий список має залишатися достатньо широким, щоб охоплювати: -- чат у DM і каналах -- поведінку гілок +- чат у DM і каналі +- поведінку потоків - життєвий цикл дій із повідомленнями -- cron callbacks -- відновлення памʼяті +- cron-зворотні виклики +- відновлення пам’яті - перемикання моделей -- передачу підзадач субагенту +- передавання підагенту - читання репозиторію та документації -- одне невелике завдання зі збирання, наприклад Lobster Invaders +- одне невелике завдання зі збірки, таке як Lobster Invaders ## Звітність -`qa-lab` експортує Markdown-звіт за протоколом на основі часової шкали спостережуваної шини. +`qa-lab` експортує Markdown-звіт за протоколом на основі спостережуваної часової шкали шини. Звіт має відповідати на такі запитання: - Що спрацювало - Що не спрацювало - Що залишилося заблокованим -- Які сценарії продовження варто додати +- Які сценарії для подальшої роботи варто додати -## Повʼязані документи +## Пов’язана документація - [Тестування](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) diff --git a/docs/uk/refactor/qa.md b/docs/uk/refactor/qa.md new file mode 100644 index 000000000..238690b71 --- /dev/null +++ b/docs/uk/refactor/qa.md @@ -0,0 +1,536 @@ +--- +x-i18n: + generated_at: "2026-04-07T22:41:54Z" + model: gpt-5.4 + provider: openai + source_hash: 3a13a050574d3fbd7a9a935aa57aa260a92975029b64418633df55159fd7cb29 + source_path: refactor/qa.md + workflow: 15 +--- + +# Рефакторинг QA + +Статус: базову міграцію завершено. + +## Мета + +Перевести QA OpenClaw із моделі з розділеними визначеннями на єдине джерело істини: + +- метадані сценаріїв +- підказки, що надсилаються моделі +- налаштування та очищення +- логіка harness +- перевірки та критерії успіху +- артефакти та підказки для звітів + +Бажаний кінцевий стан — це універсальний QA harness, який завантажує потужні файли визначень сценаріїв замість жорсткого кодування більшості поведінки в TypeScript. + +## Поточний стан + +Основне джерело істини тепер міститься в `qa/scenarios.md`. + +Реалізовано: + +- `qa/scenarios.md` + - канонічний пакет QA + - ідентичність оператора + - стартова місія + - метадані сценаріїв + - прив’язки обробників +- `extensions/qa-lab/src/scenario-catalog.ts` + - парсер markdown-пакета + валідація zod +- `extensions/qa-lab/src/qa-agent-bootstrap.ts` + - рендеринг плану з markdown-пакета +- `extensions/qa-lab/src/qa-agent-workspace.ts` + - заповнює згенеровані файли сумісності плюс `QA_SCENARIOS.md` +- `extensions/qa-lab/src/suite.ts` + - вибирає виконувані сценарії через визначені в markdown прив’язки обробників +- QA bus protocol + UI + - універсальні вбудовані вкладення для рендерингу image/video/audio/file + +Поверхні, що ще залишаються розділеними: + +- `extensions/qa-lab/src/suite.ts` + - усе ще містить більшість виконуваної логіки кастомних обробників +- `extensions/qa-lab/src/report.ts` + - усе ще виводить структуру звіту з результатів виконання + +Отже, розділення джерела істини вже виправлено, але виконання все ще здебільшого спирається на обробники, а не є повністю декларативним. + +## Як виглядає реальна поверхня сценаріїв + +Ознайомлення з поточним suite показує кілька окремих класів сценаріїв. + +### Проста взаємодія + +- базова перевірка каналу +- базова перевірка DM +- продовження в треді +- перемикання моделі +- проходження підтвердження +- реакція/редагування/видалення + +### Зміна конфігурації та runtime + +- вимкнення skill через patch конфігурації +- пробудження після restart через apply конфігурації +- перемикання можливостей після restart конфігурації +- перевірка розходження inventory runtime + +### Перевірки файлової системи та репозиторію + +- звіт про виявлення source/docs +- збірка Lobster Invaders +- пошук артефакта згенерованого image + +### Оркестрація пам’яті + +- відтворення з пам’яті +- інструменти пам’яті в контексті каналу +- резервний сценарій при збої пам’яті +- ранжування пам’яті сесії +- ізоляція пам’яті тредів +- sweep dreaming пам’яті + +### Інтеграція інструментів і plugin + +- виклик MCP plugin-tools +- видимість skill +- гаряче встановлення skill +- нативна генерація image +- круговий цикл image +- розпізнавання image із вкладення + +### Багатоходові та багатосуб’єктні + +- передача підзадачі субагенту +- fanout-синтез субагента +- потоки у стилі відновлення після restart + +Ці категорії важливі, тому що вони визначають вимоги до DSL. Плоского списку prompt + очікуваного тексту недостатньо. + +## Напрям + +### Єдине джерело істини + +Використовувати `qa/scenarios.md` як авторське джерело істини. + +Пакет має залишатися: + +- зручним для читання під час review +- придатним для машинного розбору +- достатньо насиченим, щоб керувати: + - виконанням suite + - bootstrap робочого простору QA + - метаданими UI QA Lab + - підказками для docs/discovery + - генерацією звітів + +### Бажаний формат авторингу + +Використовувати markdown як формат верхнього рівня зі структурованим YAML всередині. + +Рекомендована форма: + +- YAML frontmatter + - id + - title + - surface + - tags + - docs refs + - code refs + - overrides для model/provider + - prerequisites +- прозові секції + - objective + - notes + - debugging hints +- fenced YAML-блоки + - setup + - steps + - assertions + - cleanup + +Це дає: + +- кращу читабельність PR, ніж гігантський JSON +- багатший контекст, ніж чистий YAML +- строгий розбір і валідацію zod + +Чистий JSON прийнятний лише як проміжна згенерована форма. + +## Запропонована форма файлу сценарію + +Приклад: + +````md +--- +id: image-generation-roundtrip +title: Image generation roundtrip +surface: image +tags: [media, image, roundtrip] +models: + primary: openai/gpt-5.4 +requires: + tools: [image_generate] + plugins: [openai, qa-channel] +docsRefs: + - docs/help/testing.md + - docs/concepts/model-providers.md +codeRefs: + - extensions/qa-lab/src/suite.ts + - src/gateway/chat-attachments.ts +--- + +# Objective + +Перевірити, що згенероване медіа повторно прикріплюється на наступному ході. + +# Setup + +```yaml scenario.setup +- action: config.patch + patch: + agents: + defaults: + imageGenerationModel: + primary: openai/gpt-image-1 +- action: session.create + key: agent:qa:image-roundtrip +``` +```` + +# Steps + +```yaml scenario.steps +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Перевірка генерації image: згенеруй QA-зображення маяка та опиши його одним коротким реченням. +- action: artifact.capture + kind: generated-image + promptSnippet: Перевірка генерації image + saveAs: lighthouseImage +- action: agent.send + session: agent:qa:image-roundtrip + message: | + Перевірка roundtrip image: опиши вкладення із зображенням маяка одним коротким реченням. + attachments: + - fromArtifact: lighthouseImage +``` + +# Expect + +```yaml scenario.expect +- assert: outbound.textIncludes + value: lighthouse +- assert: requestLog.matches + where: + promptIncludes: Перевірка roundtrip image + imageInputCountGte: 1 +- assert: artifact.exists + ref: lighthouseImage +``` + +```` + +## Можливості runner, які має покривати DSL + +На основі поточного suite універсальний runner потребує більшого, ніж просто виконання prompt. + +### Дії середовища та налаштування + +- `bus.reset` +- `gateway.waitHealthy` +- `channel.waitReady` +- `session.create` +- `thread.create` +- `workspace.writeSkill` + +### Дії ходу агента + +- `agent.send` +- `agent.wait` +- `bus.injectInbound` +- `bus.injectOutbound` + +### Дії конфігурації та runtime + +- `config.get` +- `config.patch` +- `config.apply` +- `gateway.restart` +- `tools.effective` +- `skills.status` + +### Дії з файлами та артефактами + +- `file.write` +- `file.read` +- `file.delete` +- `file.touchTime` +- `artifact.captureGeneratedImage` +- `artifact.capturePath` + +### Дії з пам’яттю та cron + +- `memory.indexForce` +- `memory.searchCli` +- `doctor.memory.status` +- `cron.list` +- `cron.run` +- `cron.waitCompletion` +- `sessionTranscript.write` + +### Дії MCP + +- `mcp.callTool` + +### Перевірки + +- `outbound.textIncludes` +- `outbound.inThread` +- `outbound.notInRoot` +- `tool.called` +- `tool.notPresent` +- `skill.visible` +- `skill.disabled` +- `file.contains` +- `memory.contains` +- `requestLog.matches` +- `sessionStore.matches` +- `cron.managedPresent` +- `artifact.exists` + +## Змінні та посилання на артефакти + +DSL має підтримувати збережені результати та подальші посилання на них. + +Приклади з поточного suite: + +- створити тред, а потім повторно використати `threadId` +- створити сесію, а потім повторно використати `sessionKey` +- згенерувати image, а потім прикріпити файл на наступному ході +- згенерувати рядок-маркер пробудження, а потім перевірити, що він з’являється пізніше + +Потрібні можливості: + +- `saveAs` +- `${vars.name}` +- `${artifacts.name}` +- типізовані посилання для path, session key, thread id, marker, результатів tool + +Без підтримки змінних harness і далі повертатиме логіку сценаріїв назад у TypeScript. + +## Що має залишитися як escape hatch + +Повністю чистий декларативний runner нереалістичний на фазі 1. + +Деякі сценарії за своєю природою вимагають складної оркестрації: + +- sweep dreaming пам’яті +- пробудження після restart через apply конфігурації +- перемикання можливостей після restart конфігурації +- визначення артефакта згенерованого image за timestamp/path +- оцінювання discovery-report + +Наразі для них слід використовувати явні кастомні обробники. + +Рекомендоване правило: + +- 85-90% декларативно +- явні кроки `customHandler` для складного залишку +- лише іменовані та документовані кастомні обробники +- жодного анонімного вбудованого коду у файлі сценарію + +Це збереже універсальний рушій чистим і водночас дозволить рухатися вперед. + +## Архітектурна зміна + +### Поточний стан + +Markdown сценаріїв уже є джерелом істини для: + +- виконання suite +- bootstrap-файлів робочого простору +- каталогу сценаріїв UI QA Lab +- метаданих звітів +- discovery prompts + +Згенерована сумісність: + +- заповнений робочий простір усе ще містить `QA_KICKOFF_TASK.md` +- заповнений робочий простір усе ще містить `QA_SCENARIO_PLAN.md` +- заповнений робочий простір тепер також містить `QA_SCENARIOS.md` + +## План рефакторингу + +### Фаза 1: loader і schema + +Готово. + +- додано `qa/scenarios.md` +- додано парсер для іменованого вмісту markdown YAML pack +- виконано валідацію через zod +- споживачів переведено на розібраний pack +- видалено `qa/seed-scenarios.json` і `qa/QA_KICKOFF_TASK.md` на рівні репозиторію + +### Фаза 2: універсальний рушій + +- розділити `extensions/qa-lab/src/suite.ts` на: + - loader + - engine + - registry дій + - registry перевірок + - custom handlers +- зберегти наявні helper-функції як операції рушія + +Результат: + +- рушій виконує прості декларативні сценарії + +Почати зі сценаріїв, які здебільшого складаються з prompt + wait + assert: + +- продовження в треді +- розпізнавання image із вкладення +- видимість і виклик skill +- базова перевірка каналу + +Результат: + +- перші справжні сценарії, визначені в markdown, постачаються через універсальний рушій + +### Фаза 4: міграція сценаріїв середньої складності + +- roundtrip генерації image +- інструменти пам’яті в контексті каналу +- ранжування пам’яті сесії +- передача підзадачі субагенту +- fanout-синтез субагента + +Результат: + +- доведено змінні, артефакти, перевірки tool і перевірки request-log + +### Фаза 5: залишити складні сценарії на custom handlers + +- sweep dreaming пам’яті +- пробудження після restart через apply конфігурації +- перемикання можливостей після restart конфігурації +- розходження inventory runtime + +Результат: + +- той самий формат авторингу, але з явними блоками custom-step там, де це потрібно + +### Фаза 6: видалити жорстко закодовану карту сценаріїв + +Коли покриття pack стане достатньо хорошим: + +- видалити більшість TypeScript-розгалужень для конкретних сценаріїв із `extensions/qa-lab/src/suite.ts` + +## Підтримка Fake Slack / Rich Media + +Поточний QA bus орієнтований насамперед на текст. + +Пов’язані файли: + +- `extensions/qa-channel/src/protocol.ts` +- `extensions/qa-lab/src/bus-state.ts` +- `extensions/qa-lab/src/bus-queries.ts` +- `extensions/qa-lab/src/bus-server.ts` +- `extensions/qa-lab/web/src/ui-render.ts` + +Сьогодні QA bus підтримує: + +- текст +- реакції +- треди + +Він ще не моделює вбудовані медіавкладення. + +### Потрібний транспортний контракт + +Додати універсальну модель вкладень QA bus: + +```ts +type QaBusAttachment = { + id: string; + kind: "image" | "video" | "audio" | "file"; + mimeType: string; + fileName?: string; + inline?: boolean; + url?: string; + contentBase64?: string; + width?: number; + height?: number; + durationMs?: number; + altText?: string; + transcript?: string; +}; +```` + +Потім додати `attachments?: QaBusAttachment[]` до: + +- `QaBusMessage` +- `QaBusInboundMessageInput` +- `QaBusOutboundMessageInput` + +### Чому спочатку універсально + +Не створювати модель медіа лише для Slack. + +Натомість: + +- одна універсальна транспортна модель QA +- кілька рендерерів поверх неї + - поточний чат QA Lab + - майбутній fake Slack web + - будь-які інші представлення fake transport + +Це запобігає дублюванню логіки й дозволяє медіасценаріям залишатися незалежними від конкретного транспорту. + +### Потрібна робота в UI + +Оновити UI QA для рендерингу: + +- вбудованого попереднього перегляду image +- вбудованого audio player +- вбудованого video player +- chip вкладеного file + +Поточний UI вже вміє рендерити треди та реакції, тож рендеринг вкладень має нашаровуватися на ту саму модель картки повідомлення. + +### Робота над сценаріями, яку відкриває медіатранспорт + +Щойно вкладення почнуть проходити через QA bus, можна буде додати багатші сценарії fake-chat: + +- вбудована відповідь із image у fake Slack +- розпізнавання audio-вкладення +- розпізнавання video-вкладення +- змішаний порядок вкладень +- відповідь у треді зі збереженням медіа + +## Рекомендація + +Наступний етап реалізації має бути таким: + +1. додати loader сценаріїв markdown + schema zod +2. згенерувати поточний каталог із markdown +3. спочатку мігрувати кілька простих сценаріїв +4. додати універсальну підтримку вкладень QA bus +5. рендерити вбудоване image в UI QA +6. потім розширити на audio і video + +Це найменший шлях, який доводить обидві цілі: + +- універсальний QA, визначений через markdown +- багатші fake messaging surfaces + +## Відкриті питання + +- чи мають файли сценаріїв дозволяти вбудовані markdown-шаблони prompt зі вставкою змінних +- чи мають setup/cleanup бути іменованими секціями, чи просто впорядкованими списками дій +- чи мають посилання на артефакти бути строго типізованими в schema, чи базуватися на рядках +- чи мають custom handlers жити в одному registry або в окремих registry для кожної surface +- чи має згенерований файл сумісності JSON залишатися закоміченим під час міграції