From 6ccb1a628c11b4d4b0c5fde6fe796e49f36e2d05 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 20 Apr 2026 18:54:07 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/automation/hooks.md | 164 ++++++++++++------------ docs/uk/pi.md | 246 ++++++++++++++++++------------------ 2 files changed, 206 insertions(+), 204 deletions(-) diff --git a/docs/uk/automation/hooks.md b/docs/uk/automation/hooks.md index 5baaab272..88a636864 100644 --- a/docs/uk/automation/hooks.md +++ b/docs/uk/automation/hooks.md @@ -1,33 +1,33 @@ --- read_when: - - Вам потрібна автоматизація на основі подій для /new, /reset, /stop і подій життєвого циклу агента - - Вам потрібно створити, встановити або налагодити хуки + - Вам потрібна автоматизація на основі подій для `/new`, `/reset`, `/stop` і подій життєвого циклу агента + - Ви хочете створити, встановити або налагодити хуки summary: 'Хуки: автоматизація на основі подій для команд і подій життєвого циклу' title: Хуки x-i18n: - generated_at: "2026-04-10T20:41:23Z" + generated_at: "2026-04-20T18:52:42Z" model: gpt-5.4 provider: openai - source_hash: 14296398e4042d442ebdf071a07c6be99d4afda7cbf3c2b934e76dc5539742c7 + source_hash: 16ce72899cc0eb4366c3a1d0a18da51aa8ce26d16ccc98efb975f2ad7269efd1 source_path: automation/hooks.md workflow: 15 --- # Хуки -Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Вони автоматично виявляються в каталогах, і їх можна переглядати за допомогою `openclaw hooks`. +Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з директорій та переглядати через `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакунок хуків, застарілий обробник чи додаткову директорію хуків. В OpenClaw є два типи хуків: -- **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. -- **Вебхуки**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Вебхуки](/uk/automation/cron-jobs#webhooks). +- **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, наприклад `/new`, `/reset`, `/stop` або події життєвого циклу. +- **Webhooks**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Webhooks](/uk/automation/cron-jobs#webhooks). -Хуки також можуть бути вбудовані в плагіни. `openclaw hooks list` показує як окремі хуки, так і хуки, якими керують плагіни. +Хуки також можуть постачатися в складі plugin. `openclaw hooks list` показує як окремі хуки, так і хуки, якими керують plugin. ## Швидкий старт ```bash -# Список доступних хуків +# Перелічити доступні хуки openclaw hooks list # Увімкнути хук @@ -42,27 +42,27 @@ openclaw hooks info session-memory ## Типи подій -| Подія | Коли спрацьовує | -| ------------------------ | ---------------------------------------------- | -| `command:new` | Видано команду `/new` | -| `command:reset` | Видано команду `/reset` | -| `command:stop` | Видано команду `/stop` | -| `command` | Будь-яка подія команди (загальний слухач) | -| `session:compact:before` | Перед тим, як ущільнення підсумовує історію | -| `session:compact:after` | Після завершення ущільнення | -| `session:patch` | Коли властивості сесії змінюються | -| `agent:bootstrap` | Перед вставленням bootstrap-файлів workspace | -| `gateway:startup` | Після запуску каналів і завантаження хуків | -| `message:received` | Вхідне повідомлення з будь-якого каналу | -| `message:transcribed` | Після завершення транскрибування аудіо | -| `message:preprocessed` | Після завершення обробки медіа та посилань | -| `message:sent` | Вихідне повідомлення доставлено | +| Подія | Коли спрацьовує | +| ------------------------ | ----------------------------------------------- | +| `command:new` | Видано команду `/new` | +| `command:reset` | Видано команду `/reset` | +| `command:stop` | Видано команду `/stop` | +| `command` | Будь-яка подія команди (загальний слухач) | +| `session:compact:before` | Перед тим, як Compaction підсумує історію | +| `session:compact:after` | Після завершення Compaction | +| `session:patch` | Коли змінюються властивості сесії | +| `agent:bootstrap` | Перед впровадженням bootstrap-файлів workspace | +| `gateway:startup` | Після запуску каналів і завантаження хуків | +| `message:received` | Вхідне повідомлення з будь-якого каналу | +| `message:transcribed` | Після завершення транскрибування аудіо | +| `message:preprocessed` | Після завершення обробки всіх медіа та посилань | +| `message:sent` | Вихідне повідомлення доставлено | ## Написання хуків ### Структура хука -Кожен хук — це каталог, що містить два файли: +Кожен хук — це директорія з двома файлами: ``` my-hook/ @@ -75,27 +75,27 @@ my-hook/ ```markdown --- name: my-hook -description: "Короткий опис того, що робить цей хук" +description: "Short description of what this hook does" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- # My Hook -Тут розміщується докладна документація. +Detailed documentation goes here. ``` **Поля метаданих** (`metadata.openclaw`): -| Поле | Опис | -| ---------- | ------------------------------------------------------------ | -| `emoji` | Emoji для відображення в CLI | -| `events` | Масив подій для прослуховування | -| `export` | Іменований експорт для використання (типово `"default"`) | -| `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) | -| `requires` | Потрібні `bins`, `anyBins`, `env` або шляхи `config` | -| `always` | Обійти перевірки відповідності (boolean) | -| `install` | Методи встановлення | +| Поле | Опис | +| ---------- | ---------------------------------------------------- | +| `emoji` | Emoji для відображення в CLI | +| `events` | Масив подій, які потрібно прослуховувати | +| `export` | Іменований експорт для використання (типово `"default"`) | +| `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) | +| `requires` | Обов’язкові `bins`, `anyBins`, `env` або шляхи `config` | +| `always` | Обійти перевірки придатності (boolean) | +| `install` | Методи встановлення | ### Реалізація обробника @@ -117,55 +117,57 @@ export default handler; Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте через push, щоб надіслати користувачу), і `context` (дані, специфічні для події). -### Основні елементи контексту подій +### Основні дані context подій **Події команд** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. -**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (дані, специфічні для провайдера, включно з `senderId`, `senderName`, `guildId`). +**Події повідомлень** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (дані, специфічні для провайдера, зокрема `senderId`, `senderName`, `guildId`). **Події повідомлень** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`. **Події повідомлень** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. -**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточний збагачений вміст), `context.from`, `context.channelId`. +**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (кінцеве збагачене тіло), `context.from`, `context.channelId`. **Події bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`. -**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати події patch. +**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть ініціювати події patch. -**Події ущільнення**: `session:compact:before` включає `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. +**Події Compaction**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додатково містить `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. ## Виявлення хуків -Хуки виявляються з таких каталогів у порядку зростання пріоритету перевизначення: +Хуки виявляються з таких директорій у порядку зростання пріоритету перевизначення: 1. **Вбудовані хуки**: постачаються разом з OpenClaw -2. **Хуки плагінів**: хуки, вбудовані у встановлені плагіни -3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх workspace). Додаткові каталоги з `hooks.internal.load.extraDirs` мають той самий пріоритет. -4. **Хуки workspace**: `/hooks/` (для окремого агента, типово вимкнені, доки їх явно не увімкнути) +2. **Хуки plugin**: хуки, вбудовані у встановлені plugin +3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлюються користувачем, спільні для всіх workspace). Додаткові директорії з `hooks.internal.load.extraDirs` мають той самий пріоритет. +4. **Хуки workspace**: `/hooks/` (для окремого агента, типово вимкнені, доки їх явно не ввімкнуть) -Хуки workspace можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією ж назвою. +Хуки workspace можуть додавати нові імена хуків, але не можуть перевизначати вбудовані, керовані або надані plugin хуки з тією самою назвою. -### Набори хуків +Gateway пропускає виявлення внутрішніх хуків під час запуску, доки внутрішні хуки не буде налаштовано. Увімкніть вбудований або керований хук через `openclaw hooks enable `, встановіть пакунок хуків або задайте `hooks.internal.enabled=true`, щоб увімкнути цю можливість. -Набори хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: +### Пакунки хуків + +Пакунки хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: ```bash openclaw plugins install ``` -Npm-специфікації підтримують лише реєстр (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. +Npm-специфікації підтримуються лише для реєстру (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file та діапазони semver відхиляються. ## Вбудовані хуки -| Хук | Події | Що він робить | -| --------------------- | ------------------------------ | ----------------------------------------------------- | -| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | Вставляє додаткові bootstrap-файли з glob-шаблонів | -| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли запускається gateway | +| Хук | Події | Що робить | +| -------------------- | ----------------------------- | ------------------------------------------------------ | +| session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | Впроваджує додаткові bootstrap-файли за glob-шаблонами | +| command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` | +| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли стартує gateway | -Увімкнути будь-який вбудований хук: +Увімкнення будь-якого вбудованого хука: ```bash openclaw hooks enable @@ -173,9 +175,9 @@ openclaw hooks enable -### Докладніше про session-memory +### Подробиці session-memory -Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файлу через LLM і зберігає його в `/memory/YYYY-MM-DD-slug.md`. Потрібно, щоб було налаштовано `workspace.dir`. +Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug назви файлу через LLM і зберігає в `/memory/YYYY-MM-DD-slug.md`. Потребує налаштованого `workspace.dir`. @@ -196,25 +198,25 @@ openclaw hooks enable } ``` -Шляхи обчислюються відносно workspace. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). +Шляхи обчислюються відносно workspace. Завантажуються лише розпізнавані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). -### Докладніше про command-logger +### Подробиці command-logger Логує кожну slash-команду в `~/.openclaw/logs/commands.log`. -### Докладніше про boot-md +### Подробиці boot-md -Запускає `BOOT.md` з активного workspace під час запуску gateway. +Запускає `BOOT.md` з активного workspace під час старту gateway. -## Хуки плагінів +## Хуки plugin -Плагіни можуть реєструвати хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, зміни промптів, керування потоком повідомлень тощо. Plugin SDK надає 28 хуків, що охоплюють визначення моделі, життєвий цикл агента, потік повідомлень, виконання інструментів, координацію субагентів і життєвий цикл gateway. +Plugin можуть реєструвати хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, зміни prompt, керування потоком повідомлень тощо. Plugin SDK надає 28 хуків, що охоплюють визначення моделі, життєвий цикл агента, потік повідомлень, виконання інструментів, координацію субагентів і життєвий цикл gateway. -Повний довідник із хуків плагінів, включно з `before_tool_call`, `before_agent_reply`, `before_install` та всіма іншими хуками плагінів, див. у [Архітектура плагінів](/uk/plugins/architecture#provider-runtime-hooks). +Повний довідник по хуках plugin, зокрема `before_tool_call`, `before_agent_reply`, `before_install` та всі інші хуки plugin, див. у [Архітектура plugin](/uk/plugins/architecture#provider-runtime-hooks). ## Конфігурація @@ -249,7 +251,7 @@ openclaw hooks enable } ``` -Додаткові каталоги хуків: +Додаткові директорії хуків: ```json { @@ -267,16 +269,16 @@ openclaw hooks enable Застарілий формат конфігурації масиву `hooks.internal.handlers` усе ще підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення. -## Довідка CLI +## Довідник CLI ```bash -# Список усіх хуків (додайте --eligible, --verbose або --json) +# Перелічити всі хуки (додайте --eligible, --verbose або --json) openclaw hooks list # Показати докладну інформацію про хук openclaw hooks info -# Показати зведення про відповідність +# Показати зведення про придатність openclaw hooks check # Увімкнути/вимкнути @@ -286,31 +288,31 @@ openclaw hooks disable ## Рекомендовані практики -- **Робіть обробники швидкими.** Хуки запускаються під час обробки команд. Для важких задач використовуйте fire-and-forget через `void processInBackground(event)`. -- **Коректно обробляйте помилки.** Обгортайте ризиковані операції в try/catch; не викидайте винятки, щоб інші обробники могли виконатися. -- **Рано фільтруйте події.** Одразу повертайтеся, якщо тип/дія події не є релевантними. +- **Підтримуйте швидкість обробників.** Хуки виконуються під час обробки команд. Запускайте важкі завдання у фоновому режимі без очікування через `void processInBackground(event)`. +- **Коректно обробляйте помилки.** Обгорніть ризиковані операції в try/catch; не кидайте винятки, щоб інші обробники могли виконатися. +- **Рано фільтруйте події.** Відразу повертайтеся, якщо тип/дія події не є релевантними. - **Використовуйте конкретні ключі подій.** Надавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. -## Усунення неполадок +## Усунення проблем -### Хук не виявлено +### Хук не виявляється ```bash -# Перевірте структуру каталогу +# Перевірити структуру директорії ls -la ~/.openclaw/hooks/my-hook/ # Має показати: HOOK.md, handler.ts -# Список усіх виявлених хуків +# Перелічити всі виявлені хуки openclaw hooks list ``` -### Хук не відповідає умовам +### Хук непридатний ```bash openclaw hooks info my-hook ``` -Перевірте відсутні бінарні файли (PATH), змінні середовища, значення конфігурації або сумісність з ОС. +Перевірте, чи не бракує бінарних файлів (PATH), змінних середовища, значень конфігурації або сумісності з ОС. ### Хук не виконується @@ -320,7 +322,7 @@ openclaw hooks info my-hook ## Пов’язане -- [Довідка CLI: hooks](/cli/hooks) -- [Вебхуки](/uk/automation/cron-jobs#webhooks) -- [Архітектура плагінів](/uk/plugins/architecture#provider-runtime-hooks) — повний довідник із хуків плагінів +- [Довідник CLI: hooks](/cli/hooks) +- [Webhooks](/uk/automation/cron-jobs#webhooks) +- [Архітектура plugin](/uk/plugins/architecture#provider-runtime-hooks) — повний довідник по хуках plugin - [Конфігурація](/uk/gateway/configuration-reference#hooks) diff --git a/docs/uk/pi.md b/docs/uk/pi.md index cb1c3b23e..62a48a166 100644 --- a/docs/uk/pi.md +++ b/docs/uk/pi.md @@ -1,32 +1,32 @@ --- read_when: - Розуміння дизайну інтеграції Pi SDK в OpenClaw - - Зміна життєвого циклу сесій агента, інструментів або підключення провайдерів для Pi -summary: Архітектура вбудованої інтеграції Pi-агента та життєвого циклу сесій в OpenClaw + - Зміна життєвого циклу сесії агента, інструментів або підключення провайдера для Pi +summary: Архітектура інтеграції вбудованого агента Pi в OpenClaw та життєвий цикл сесії title: Архітектура інтеграції Pi x-i18n: - generated_at: "2026-04-05T19:39:41Z" + generated_at: "2026-04-20T18:52:55Z" model: gpt-5.4 provider: openai - source_hash: 28594290b018b7cc2963d33dbb7cec6a0bd817ac486dafad59dd2ccabd482582 + source_hash: ece62eb1459e8a861610c8502f2b3bf5172500207df5e78f4abe7a2a416a47fc source_path: pi.md workflow: 15 --- # Архітектура інтеграції Pi -Цей документ описує, як OpenClaw інтегрується з [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) та пов’язаними з ним пакетами (`pi-ai`, `pi-agent-core`, `pi-tui`) для реалізації можливостей свого AI-агента. +Цей документ описує, як OpenClaw інтегрується з [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) та його спорідненими пакетами (`pi-ai`, `pi-agent-core`, `pi-tui`) для забезпечення можливостей свого AI-агента. ## Огляд -OpenClaw використовує SDK pi, щоб вбудувати AI-агента для програмування у свою архітектуру шлюзу повідомлень. Замість запуску pi як підпроцесу або використання режиму RPC, OpenClaw безпосередньо імпортує та створює `AgentSession` через `createAgentSession()`. Цей вбудований підхід надає: +OpenClaw використовує Pi SDK, щоб вбудувати AI-агента для програмування у свою архітектуру шлюзу повідомлень. Замість запуску pi як підпроцесу або використання режиму RPC, OpenClaw напряму імпортує та створює `AgentSession` через `createAgentSession()`. Такий вбудований підхід забезпечує: - Повний контроль над життєвим циклом сесії та обробкою подій -- Впровадження власних інструментів (повідомлення, sandbox, дії для конкретних каналів) -- Налаштування системного промпту для кожного каналу/контексту -- Збереження сесій із підтримкою розгалуження/ущільнення -- Ротацію профілів автентифікації для кількох облікових записів із резервним перемиканням -- Перемикання моделей незалежно від провайдера +- Ін'єкцію власних інструментів (повідомлення, sandbox, дії, специфічні для каналу) +- Налаштування системного prompt для кожного каналу/контексту +- Збереження сесій із підтримкою розгалуження/Compaction +- Ротацію кількох auth-профілів облікових записів із failover +- Незалежне від провайдера перемикання моделей ## Залежності пакетів @@ -39,50 +39,50 @@ OpenClaw використовує SDK pi, щоб вбудувати AI-аген } ``` -| Пакет | Призначення | -| ---------------- | ------------------------------------------------------------------------------------------------------- | -| `pi-ai` | Базові абстракції LLM: `Model`, `streamSimple`, типи повідомлень, API провайдерів | -| `pi-agent-core` | Цикл агента, виконання інструментів, типи `AgentMessage` | +| Package | Призначення | +| ----------------- | ----------------------------------------------------------------------------------------------------- | +| `pi-ai` | Базові абстракції LLM: `Model`, `streamSimple`, типи повідомлень, API провайдерів | +| `pi-agent-core` | Цикл агента, виконання інструментів, типи `AgentMessage` | | `pi-coding-agent` | Високорівневий SDK: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, вбудовані інструменти | -| `pi-tui` | Компоненти термінального UI (використовуються в локальному режимі TUI OpenClaw) | +| `pi-tui` | Компоненти термінального UI (використовуються в локальному режимі TUI OpenClaw) | ## Структура файлів ``` src/agents/ -├── pi-embedded-runner.ts # Повторний експорт із pi-embedded-runner/ +├── pi-embedded-runner.ts # Реекспорти з pi-embedded-runner/ ├── pi-embedded-runner/ -│ ├── run.ts # Основна точка входу: runEmbeddedPiAgent() +│ ├── run.ts # Головна точка входу: runEmbeddedPiAgent() │ ├── run/ │ │ ├── attempt.ts # Логіка однієї спроби з налаштуванням сесії │ │ ├── params.ts # Тип RunEmbeddedPiAgentParams -│ │ ├── payloads.ts # Побудова payload-відповідей із результатів запуску -│ │ ├── images.ts # Впровадження зображень для vision-моделі +│ │ ├── payloads.ts # Побудова payload відповіді з результатів запуску +│ │ ├── images.ts # Ін'єкція зображень для vision-моделі │ │ └── types.ts # EmbeddedRunAttemptResult -│ ├── abort.ts # Виявлення помилок переривання +│ ├── abort.ts # Визначення помилки скасування │ ├── cache-ttl.ts # Відстеження TTL кешу для обрізання контексту -│ ├── compact.ts # Логіка ручного/автоматичного ущільнення +│ ├── compact.ts # Логіка ручного/автоматичного Compaction │ ├── extensions.ts # Завантаження розширень pi для вбудованих запусків │ ├── extra-params.ts # Додаткові параметри потоку для конкретних провайдерів -│ ├── google.ts # Виправлення порядку ходів для Google/Gemini +│ ├── google.ts # Виправлення порядку ходів Google/Gemini │ ├── history.ts # Обмеження історії (DM проти групи) -│ ├── lanes.ts # Командні доріжки сесії/глобальні +│ ├── lanes.ts # Доріжки команд сесії/глобальних команд │ ├── logger.ts # Логер підсистеми │ ├── model.ts # Визначення моделі через ModelRegistry -│ ├── runs.ts # Відстеження активних запусків, переривання, черга -│ ├── sandbox-info.ts # Інформація про sandbox для системного промпту +│ ├── runs.ts # Відстеження активних запусків, скасування, черга +│ ├── sandbox-info.ts # Інформація про sandbox для системного prompt │ ├── session-manager-cache.ts # Кешування екземплярів SessionManager │ ├── session-manager-init.ts # Ініціалізація файлу сесії -│ ├── system-prompt.ts # Побудова системного промпту -│ ├── tool-split.ts # Поділ інструментів на builtIn та custom +│ ├── system-prompt.ts # Побудова системного prompt +│ ├── tool-split.ts # Розділення інструментів на builtIn і custom │ ├── types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult │ └── utils.ts # Відображення ThinkLevel, опис помилок -├── pi-embedded-subscribe.ts # Підписка/диспетчеризація подій сесії +├── pi-embedded-subscribe.ts # Підписка на події сесії та диспетчеризація ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams ├── pi-embedded-subscribe.handlers.ts # Фабрика обробників подій ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts -├── pi-embedded-block-chunker.ts # Поділ потокових відповідей на блоки +├── pi-embedded-block-chunker.ts # Розбиття потокових блочних відповідей ├── pi-embedded-messaging.ts # Відстеження надісланих інструментом повідомлень ├── pi-embedded-helpers.ts # Класифікація помилок, валідація ходів ├── pi-embedded-helpers/ # Допоміжні модулі @@ -90,17 +90,17 @@ src/agents/ ├── pi-tools.ts # createOpenClawCodingTools() ├── pi-tools.abort.ts # Обгортання AbortSignal для інструментів ├── pi-tools.policy.ts # Політика allowlist/denylist для інструментів -├── pi-tools.read.ts # Кастомізації інструмента read +├── pi-tools.read.ts # Налаштування інструмента читання ├── pi-tools.schema.ts # Нормалізація схем інструментів ├── pi-tools.types.ts # Псевдонім типу AnyAgentTool ├── pi-tool-definition-adapter.ts # Адаптер AgentTool -> ToolDefinition ├── pi-settings.ts # Перевизначення налаштувань -├── pi-hooks/ # Власні hooks для pi -│ ├── compaction-safeguard.ts # Захисне розширення +├── pi-hooks/ # Власні хуки pi +│ ├── compaction-safeguard.ts # Розширення-запобіжник │ ├── compaction-safeguard-runtime.ts -│ ├── context-pruning.ts # Розширення обрізання контексту на основі TTL кешу +│ ├── context-pruning.ts # Розширення обрізання контексту за Cache-TTL │ └── context-pruning/ -├── model-auth.ts # Визначення профілю автентифікації +├── model-auth.ts # Визначення auth-профілю ├── auth-profiles.ts # Сховище профілів, cooldown, failover ├── model-selection.ts # Визначення моделі за замовчуванням ├── models-config.ts # Генерація models.json @@ -109,20 +109,20 @@ src/agents/ ├── failover-error.ts # Клас FailoverError ├── defaults.ts # DEFAULT_PROVIDER, DEFAULT_MODEL ├── system-prompt.ts # buildAgentSystemPrompt() -├── system-prompt-params.ts # Визначення параметрів системного промпту +├── system-prompt-params.ts # Визначення параметрів системного prompt ├── system-prompt-report.ts # Генерація звіту для налагодження ├── tool-summaries.ts # Підсумки описів інструментів ├── tool-policy.ts # Визначення політики інструментів ├── transcript-policy.ts # Політика валідації транскрипту -├── skills.ts # Побудова знімків/промптів Skills +├── skills.ts # Знімок Skills / побудова prompt ├── skills/ # Підсистема Skills ├── sandbox.ts # Визначення контексту sandbox ├── sandbox/ # Підсистема sandbox -├── channel-tools.ts # Впровадження інструментів для конкретних каналів +├── channel-tools.ts # Ін'єкція інструментів, специфічних для каналу ├── openclaw-tools.ts # Інструменти, специфічні для OpenClaw ├── bash-tools.ts # Інструменти exec/process ├── apply-patch.ts # Інструмент apply_patch (OpenAI) -├── tools/ # Реалізації окремих інструментів +├── tools/ # Окремі реалізації інструментів │ ├── browser-tool.ts │ ├── canvas-tool.ts │ ├── cron-tool.ts @@ -136,12 +136,12 @@ src/agents/ └── ... ``` -Середовища виконання дій із повідомленнями для конкретних каналів тепер розміщені в каталогах розширень, якими володіють plugins, а не в `src/agents/tools`, наприклад: +Середовища виконання дій повідомлень, специфічних для каналу, тепер знаходяться у директоріях розширень, що належать Plugin, а не в `src/agents/tools`, наприклад: -- файли середовища виконання дій plugin Discord -- файл середовища виконання дій plugin Slack -- файл середовища виконання дій plugin Telegram -- файл середовища виконання дій plugin WhatsApp +- файли середовища виконання дій Plugin Discord +- файл середовища виконання дій Plugin Slack +- файл середовища виконання дій Plugin Telegram +- файл середовища виконання дій Plugin WhatsApp ## Основний потік інтеграції @@ -171,7 +171,7 @@ const result = await runEmbeddedPiAgent({ ### 2. Створення сесії -Усередині `runEmbeddedAttempt()` (яка викликається з `runEmbeddedPiAgent()`) використовується SDK pi: +Усередині `runEmbeddedAttempt()` (який викликається з `runEmbeddedPiAgent()`) використовується Pi SDK: ```typescript import { @@ -225,41 +225,41 @@ const subscription = subscribeEmbeddedPiSession({ }); ``` -Серед оброблюваних подій: +Обробляються такі події: - `message_start` / `message_end` / `message_update` (потоковий текст/мислення) - `tool_execution_start` / `tool_execution_update` / `tool_execution_end` - `turn_start` / `turn_end` - `agent_start` / `agent_end` -- `auto_compaction_start` / `auto_compaction_end` +- `compaction_start` / `compaction_end` -### 4. Надсилання промпту +### 4. Prompting -Після налаштування сесії надсилається промпт: +Після налаштування сесія отримує prompt: ```typescript await session.prompt(effectivePrompt, { images: imageResult.images }); ``` -SDK обробляє весь цикл роботи агента: надсилання до LLM, виконання викликів інструментів, потокове передавання відповідей. +SDK обробляє повний цикл агента: надсилання до LLM, виконання викликів інструментів, потокову передачу відповідей. -Впровадження зображень є локальним для промпту: OpenClaw завантажує посилання на зображення з поточного промпту та передає їх через `images` лише для цього ходу. Він не сканує повторно попередні ходи історії, щоб повторно впроваджувати payload-и зображень. +Ін'єкція зображень є локальною для prompt: OpenClaw завантажує посилання на зображення з поточного prompt і передає їх через `images` лише для цього ходу. Він не сканує повторно старі ходи історії, щоб повторно ін'єктувати payload зображень. ## Архітектура інструментів ### Конвеєр інструментів -1. **Базові інструменти**: `codingTools` із pi (`read`, `bash`, `edit`, `write`) +1. **Базові інструменти**: `codingTools` у pi (`read`, `bash`, `edit`, `write`) 2. **Власні заміни**: OpenClaw замінює bash на `exec`/`process`, налаштовує `read`/`edit`/`write` для sandbox -3. **Інструменти OpenClaw**: повідомлення, browser, canvas, sessions, cron, gateway тощо -4. **Інструменти каналів**: інструменти дій для Discord/Telegram/Slack/WhatsApp -5. **Фільтрація політиками**: інструменти фільтруються за профілем, провайдером, агентом, групою, політиками sandbox +3. **Інструменти OpenClaw**: повідомлення, браузер, canvas, сесії, Cron, Gateway тощо +4. **Інструменти каналу**: інструменти дій, специфічні для Discord/Telegram/Slack/WhatsApp +5. **Фільтрація за політиками**: інструменти фільтруються за профілем, провайдером, агентом, групою, політиками sandbox 6. **Нормалізація схем**: схеми очищуються з урахуванням особливостей Gemini/OpenAI -7. **Обгортання AbortSignal**: інструменти обгортаються для підтримки сигналів переривання +7. **Обгортання AbortSignal**: інструменти обгортаються для підтримки сигналів скасування -### Адаптер визначень інструментів +### Адаптер визначення інструментів -`AgentTool` із pi-agent-core має іншу сигнатуру `execute`, ніж `ToolDefinition` у pi-coding-agent. Адаптер у `pi-tool-definition-adapter.ts` з’єднує їх: +`AgentTool` у pi-agent-core має іншу сигнатуру `execute`, ніж `ToolDefinition` у pi-coding-agent. Адаптер у `pi-tool-definition-adapter.ts` з'єднує їх: ```typescript export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { @@ -269,33 +269,33 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { description: tool.description ?? "", parameters: tool.parameters, execute: async (toolCallId, params, onUpdate, _ctx, signal) => { - // pi-coding-agent signature differs from pi-agent-core + // сигнатура pi-coding-agent відрізняється від pi-agent-core return await tool.execute(toolCallId, params, signal, onUpdate); }, })); } ``` -### Стратегія поділу інструментів +### Стратегія розділення інструментів `splitSdkTools()` передає всі інструменти через `customTools`: ```typescript export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { - builtInTools: [], // Empty. We override everything + builtInTools: [], // Порожньо. Ми все перевизначаємо customTools: toToolDefinitions(options.tools), }; } ``` -Це забезпечує узгодженість фільтрації політиками, інтеграції sandbox і розширеного набору інструментів OpenClaw для всіх провайдерів. +Це гарантує, що фільтрація за політиками, інтеграція sandbox і розширений набір інструментів в OpenClaw залишаються узгодженими для всіх провайдерів. -## Побудова системного промпту +## Побудова системного prompt -Системний промпт будується в `buildAgentSystemPrompt()` (`system-prompt.ts`). Він формує повний промпт із розділами, зокрема Tooling, Tool Call Style, Safety guardrails, довідка CLI OpenClaw, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, Runtime metadata, а також Memory і Reactions, якщо вони ввімкнені, плюс необов’язкові файли контексту й додатковий вміст системного промпту. Для мінімального режиму промпту, який використовується субагентами, розділи обрізаються. +Системний prompt будується в `buildAgentSystemPrompt()` (`system-prompt.ts`). Він збирає повний prompt із секціями, зокрема Tooling, Tool Call Style, захисні обмеження безпеки, довідка CLI OpenClaw, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, метадані середовища виконання, а також Memory і Reactions, коли вони ввімкнені, і додатково — необов’язкові файли контексту та додатковий вміст системного prompt. Секції обрізаються для мінімального режиму prompt, який використовується підлеглими агентами. -Промпт застосовується після створення сесії через `applySystemPromptOverrideToSession()`: +Prompt застосовується після створення сесії через `applySystemPromptOverrideToSession()`: ```typescript const systemPromptOverride = createSystemPromptOverride(appendPrompt); @@ -306,17 +306,17 @@ applySystemPromptOverrideToSession(session, systemPromptOverride); ### Файли сесій -Сесії — це JSONL-файли з деревоподібною структурою (зв’язки id/parentId). За збереження відповідає `SessionManager` із Pi: +Сесії — це JSONL-файли з деревоподібною структурою (зв’язування через id/parentId). `SessionManager` у Pi відповідає за збереження стану: ```typescript const sessionManager = SessionManager.open(params.sessionFile); ``` -OpenClaw обгортає його за допомогою `guardSessionManager()` для безпечної обробки результатів інструментів. +OpenClaw обгортає це через `guardSessionManager()` для безпечної обробки результатів інструментів. ### Кешування сесій -`session-manager-cache.ts` кешує екземпляри SessionManager, щоб уникнути повторного розбору файлу: +`session-manager-cache.ts` кешує екземпляри SessionManager, щоб уникнути повторного парсингу файлів: ```typescript await prewarmSessionFile(params.sessionFile); @@ -328,14 +328,14 @@ trackSessionManagerAccess(params.sessionFile); `limitHistoryTurns()` обрізає історію розмови залежно від типу каналу (DM чи група). -### Ущільнення +### Compaction -Автоматичне ущільнення запускається при переповненні контексту. Типові сигнатури переповнення включають +Автоматичний Compaction запускається при переповненні контексту. Типові ознаки такого переповнення включають `request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` і `ollama error: context -length exceeded`. `compactEmbeddedPiSessionDirect()` обробляє ручне -ущільнення: +length exceeded`. `compactEmbeddedPiSessionDirect()` обробляє ручний +Compaction: ```typescript const compactResult = await compactEmbeddedPiSessionDirect({ @@ -345,16 +345,16 @@ const compactResult = await compactEmbeddedPiSessionDirect({ ## Автентифікація та визначення моделі -### Профілі автентифікації +### Auth-профілі -OpenClaw підтримує сховище профілів автентифікації з кількома API-ключами на провайдера: +OpenClaw підтримує сховище auth-профілів із кількома API-ключами для кожного провайдера: ```typescript const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile }); ``` -Профілі обертаються при збоях із відстеженням cooldown: +Профілі ротуються після збоїв із відстеженням cooldown: ```typescript await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); @@ -373,13 +373,13 @@ const { model, error, authStorage, modelRegistry } = resolveModel( config, ); -// Uses pi's ModelRegistry and AuthStorage +// Використовує ModelRegistry і AuthStorage з Pi authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); ``` ### Failover -`FailoverError` запускає резервне перемикання моделі, якщо це налаштовано: +`FailoverError` запускає fallback моделі, якщо це налаштовано: ```typescript if (fallbackConfigured && isFailoverErrorMessage(errorText)) { @@ -395,11 +395,11 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) { ## Розширення Pi -OpenClaw завантажує власні розширення pi для спеціалізованої поведінки: +OpenClaw завантажує власні розширення Pi для спеціалізованої поведінки: -### Захист ущільнення +### Запобіжник Compaction -`src/agents/pi-hooks/compaction-safeguard.ts` додає захисні механізми для ущільнення, зокрема адаптивне бюджетування токенів, а також зведення про збої інструментів і файлові операції: +`src/agents/pi-hooks/compaction-safeguard.ts` додає захисні обмеження до Compaction, зокрема адаптивне бюджетування токенів, а також підсумки збоїв інструментів і файлових операцій: ```typescript if (resolveCompactionMode(params.cfg) === "safeguard") { @@ -410,7 +410,7 @@ if (resolveCompactionMode(params.cfg) === "safeguard") { ### Обрізання контексту -`src/agents/pi-hooks/context-pruning.ts` реалізує обрізання контексту на основі TTL кешу: +`src/agents/pi-hooks/context-pruning.ts` реалізує обрізання контексту на основі Cache-TTL: ```typescript if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { @@ -424,11 +424,11 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { } ``` -## Потокова передача та блокові відповіді +## Потокова передача та блочні відповіді -### Поділ на блоки +### Розбиття на блоки -`EmbeddedBlockChunker` керує потоковим перетворенням тексту на окремі блоки відповіді: +`EmbeddedBlockChunker` керує потоковим текстом, перетворюючи його на окремі блоки відповіді: ```typescript const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null; @@ -436,18 +436,18 @@ const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : n ### Видалення тегів thinking/final -Потоковий вивід обробляється для видалення блоків ``/`` і виділення вмісту ``: +Потоковий вивід обробляється так, щоб видаляти блоки ``/`` і витягати вміст ``: ```typescript const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { - // Strip ... content - // If enforceFinalTag, only return ... content + // Видалити вміст ... + // Якщо enforceFinalTag увімкнено, повертати лише вміст ... }; ``` ### Директиви відповіді -Директиви відповіді, такі як `[[media:url]]`, `[[voice]]`, `[[reply:id]]`, аналізуються та виділяються: +Директиви відповіді, такі як `[[media:url]]`, `[[voice]]`, `[[reply:id]]`, розбираються та витягуються: ```typescript const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk); @@ -457,20 +457,20 @@ const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDi ### Класифікація помилок -`pi-embedded-helpers.ts` класифікує помилки для відповідної обробки: +`pi-embedded-helpers.ts` класифікує помилки для належної обробки: ```typescript -isContextOverflowError(errorText) // Context too large -isCompactionFailureError(errorText) // Compaction failed -isAuthAssistantError(lastAssistant) // Auth failure -isRateLimitAssistantError(...) // Rate limited -isFailoverAssistantError(...) // Should failover +isContextOverflowError(errorText) // Контекст завеликий +isCompactionFailureError(errorText) // Compaction не вдався +isAuthAssistantError(lastAssistant) // Помилка автентифікації +isRateLimitAssistantError(...) // Спрацювало обмеження частоти +isFailoverAssistantError(...) // Потрібен failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` -### Резервний рівень thinking +### Fallback для рівня thinking -Якщо рівень thinking не підтримується, використовується резервний варіант: +Якщо рівень thinking не підтримується, використовується fallback: ```typescript const fallbackThinking = pickFallbackThinkingLevel({ @@ -495,61 +495,61 @@ const sandbox = await resolveSandboxContext({ }); if (sandboxRoot) { - // Use sandboxed read/edit/write tools - // Exec runs in container - // Browser uses bridge URL + // Використовувати ізольовані інструменти read/edit/write + // Exec виконується в контейнері + // Browser використовує bridge URL } ``` -## Обробка для конкретних провайдерів +## Обробка, специфічна для провайдера ### Anthropic -- Очищення магічного рядка відмови +- Очищення magic string для відмов - Валідація ходів для послідовних ролей -- Сувора валідація параметрів інструментів Pi на upstream-рівні +- Строга валідація параметрів інструментів Pi на upstream-рівні ### Google/Gemini -- Санітизація схем інструментів, якою володіє plugin +- Санітизація схем інструментів, що належать Plugin ### OpenAI - Інструмент `apply_patch` для моделей Codex -- Обробка зниження рівня thinking +- Обробка пониження рівня thinking ## Інтеграція TUI -OpenClaw також має локальний режим TUI, який безпосередньо використовує компоненти pi-tui: +OpenClaw також має локальний режим TUI, який напряму використовує компоненти pi-tui: ```typescript // src/tui/tui.ts import { ... } from "@mariozechner/pi-tui"; ``` -Це забезпечує інтерактивний досвід роботи в терміналі, подібний до нативного режиму pi. +Це забезпечує інтерактивний досвід у терміналі, подібний до нативного режиму pi. -## Ключові відмінності від Pi CLI +## Основні відмінності від Pi CLI -| Аспект | Pi CLI | Вбудований OpenClaw | -| --------------- | ----------------------- | --------------------------------------------------------------------------------------------------- | -| Виклик | Команда `pi` / RPC | SDK через `createAgentSession()` | -| Інструменти | Стандартні інструменти для програмування | Власний набір інструментів OpenClaw | -| Системний промпт | AGENTS.md + промпти | Динамічний для кожного каналу/контексту | -| Зберігання сесій | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (або `$OPENCLAW_STATE_DIR/agents//sessions/`) | -| Auth | Окремі облікові дані | Кілька профілів із ротацією | -| Розширення | Завантажуються з диска | Програмно + шляхи на диску | -| Обробка подій | Рендеринг TUI | На основі callback-ів (`onBlockReply` тощо) | +| Aspect | Pi CLI | Вбудований OpenClaw | +| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | +| Invocation | Команда `pi` / RPC | SDK через `createAgentSession()` | +| Tools | Стандартні інструменти для кодування | Власний набір інструментів OpenClaw | +| System prompt | AGENTS.md + prompts | Динамічний, для кожного каналу/контексту | +| Session storage | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (або `$OPENCLAW_STATE_DIR/agents//sessions/`) | +| Auth | Один обліковий запис | Кілька профілів із ротацією | +| Extensions | Завантажуються з диска | Програмно + шляхи з диска | +| Event handling | Рендеринг TUI | На основі callback-функцій (`onBlockReply` тощо) | ## Майбутні міркування -Напрями для потенційного доопрацювання: +Сфери для потенційного перегляду: -1. **Узгодження сигнатур інструментів**: наразі виконується адаптація між сигнатурами pi-agent-core і pi-coding-agent +1. **Вирівнювання сигнатур інструментів**: наразі є адаптація між сигнатурами pi-agent-core і pi-coding-agent 2. **Обгортання менеджера сесій**: `guardSessionManager` додає безпеку, але підвищує складність -3. **Завантаження розширень**: можна безпосередніше використовувати `ResourceLoader` із pi -4. **Складність обробника потоків**: `subscribeEmbeddedPiSession` значно розрісся -5. **Особливості провайдерів**: багато кодових шляхів для конкретних провайдерів, які pi потенційно міг би обробляти сам +3. **Завантаження розширень**: можна було б безпосередніше використовувати `ResourceLoader` із Pi +4. **Складність обробника потоків**: `subscribeEmbeddedPiSession` став занадто великим +5. **Особливості провайдерів**: багато гілок коду, специфічних для провайдерів, які Pi потенційно міг би обробляти сам ## Тести @@ -567,8 +567,8 @@ import { ... } from "@mariozechner/pi-tui"; - `src/agents/pi-settings.test.ts` - `src/agents/pi-hooks/**/*.test.ts` -Живі/опціональні: +Live/opt-in: - `src/agents/pi-embedded-runner-extraparams.live.test.ts` (увімкніть `OPENCLAW_LIVE_TEST=1`) -Актуальні команди запуску див. у [Pi Development Workflow](/uk/pi-dev). +Актуальні команди запуску дивіться в [Робочий процес розробки Pi](/uk/pi-dev).