diff --git a/docs/uk/cli/skills.md b/docs/uk/cli/skills.md index eee53606b..f29e3c603 100644 --- a/docs/uk/cli/skills.md +++ b/docs/uk/cli/skills.md @@ -1,27 +1,27 @@ --- read_when: - - Ви хочете побачити, які Skills доступні й готові до запуску - - Ви хочете шукати, встановлювати або оновлювати Skills із ClawHub - - Ви хочете налагодити відсутні бінарні файли, змінні середовища або конфігурацію для Skills -summary: Довідник CLI для `openclaw skills` (пошук/встановлення/оновлення/список/відомості/перевірка) + - Ви хочете побачити, які Skills доступні та готові до запуску + - Ви хочете знайти, встановити або оновити Skills з ClawHub + - Ви хочете налагодити відсутні бінарні файли/env/конфігурацію для Skills +summary: Довідка CLI для `openclaw skills` (search/install/update/list/info/check) title: Skills x-i18n: - generated_at: "2026-04-24T03:16:07Z" + generated_at: "2026-04-28T00:10:36Z" model: gpt-5.4 provider: openai - source_hash: 31cd7647a15cd5df6cf5a2311e63bb11cc3aabfe8beefda7be57dc76adc509ea + source_hash: 5059bf04c68dabe289d2c376407a52989c970e3d16e7637a2c83f4e24ad6564c source_path: cli/skills.md workflow: 15 --- # `openclaw skills` -Переглядайте локальні Skills і встановлюйте/оновлюйте Skills із ClawHub. +Переглядайте локальні Skills та встановлюйте/оновлюйте Skills з ClawHub. -Пов’язано: +Пов’язане: - Система Skills: [Skills](/uk/tools/skills) -- Конфігурація Skills: [Конфігурація Skills](/uk/tools/skills-config) +- Конфігурація Skills: [Skills config](/uk/tools/skills-config) - Встановлення з ClawHub: [ClawHub](/uk/tools/clawhub) ## Команди @@ -32,32 +32,50 @@ openclaw skills search --limit 20 --json openclaw skills install openclaw skills install --version openclaw skills install --force +openclaw skills install --agent openclaw skills update openclaw skills update --all +openclaw skills update --all --agent openclaw skills list openclaw skills list --eligible openclaw skills list --json openclaw skills list --verbose +openclaw skills list --agent openclaw skills info openclaw skills info --json +openclaw skills info --agent openclaw skills check openclaw skills check --json +openclaw skills check --agent ``` -`search`/`install`/`update` безпосередньо використовують ClawHub і встановлюють у каталог `skills/` активного робочого простору. `list`/`info`/`check` як і раніше переглядають локальні Skills, видимі для поточного робочого простору та конфігурації. +`search`/`install`/`update` напряму використовують ClawHub і встановлюють у активний +каталог робочого простору `skills/`. `list`/`info`/`check` як і раніше перевіряють локальні +Skills, видимі для поточного робочого простору та конфігурації. Команди, що +працюють з робочим простором, визначають цільовий робочий простір через `--agent `, +потім через поточний робочий каталог, якщо він знаходиться всередині налаштованого +робочого простору агента, а потім через агента за замовчуванням. -Ця команда CLI `install` завантажує теки Skills із ClawHub. Встановлення залежностей Skills через Gateway, запущене з онбордингу або налаштувань Skills, натомість використовує окремий шлях запиту `skills.install`. +Ця команда CLI `install` завантажує теки Skills з ClawHub. Встановлення залежностей +Skills через Gateway, які запускаються під час онбордингу або з налаштувань Skills, +замість цього використовують окремий шлях запиту `skills.install`. Примітки: -- `search [query...]` приймає необов’язковий запит; пропустіть його, щоб переглянути типовий пошуковий канал ClawHub. +- `search [query...]` приймає необов’язковий запит; не вказуйте його, щоб переглянути стандартну + стрічку пошуку ClawHub. - `search --limit ` обмежує кількість повернених результатів. -- `install --force` перезаписує наявну теку Skill у робочому просторі для того самого slug. -- `update --all` оновлює лише відстежувані встановлення ClawHub в активному робочому просторі. -- `list` є типовою дією, якщо не вказано підкоманду. -- `list`, `info` і `check` записують свій сформований вивід у stdout. Із `--json` це означає, що машиночитний вміст залишається в stdout для конвеєрів і скриптів. +- `install --force` перезаписує наявну теку Skills робочого простору для того самого + slug. +- `--agent ` націлюється на один налаштований робочий простір агента та перевизначає + визначення за поточним робочим каталогом. +- `update --all` оновлює лише відстежувані встановлення з ClawHub в активному робочому просторі. +- `list` є дією за замовчуванням, якщо не вказано підкоманду. +- `list`, `info` і `check` записують свій відформатований вивід у stdout. З + `--json` це означає, що машинозчитувані дані залишаються у stdout для каналів + і скриптів. -## Пов’язано +## Пов’язане -- [Довідник CLI](/uk/cli) +- [Довідка CLI](/uk/cli) - [Skills](/uk/tools/skills) diff --git a/docs/uk/plugins/hooks.md b/docs/uk/plugins/hooks.md index c616162ee..993b2af2a 100644 --- a/docs/uk/plugins/hooks.md +++ b/docs/uk/plugins/hooks.md @@ -2,21 +2,21 @@ read_when: - Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу - Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin - - Ви обираєте між внутрішніми хуками та хуками plugin + - 'Ви вирішуєте, що вибрати: внутрішні хуки чи хуки Plugin' summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway' -title: Хуки Plugin +title: хуки Plugin x-i18n: - generated_at: "2026-04-27T22:37:53Z" + generated_at: "2026-04-28T00:10:39Z" model: gpt-5.4 provider: openai - source_hash: 0aae1c2321491ed0eb82b6306be61cd7e4bffccf8e22d1455267110fdf4fc62b + source_hash: 2bdc52ada8f8949f24b7930ee1daac254477ef678396ea61102775173f68e0d5 source_path: plugins/hooks.md workflow: 15 --- -Хуки Plugin — це внутрішньопроцесні точки розширення для plugin OpenClaw. Використовуйте їх, +Хуки Plugin — це точки розширення в процесі виконання для plugin OpenClaw. Використовуйте їх, коли plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень, -життєвий цикл сесії, маршрутизацію сабагентів, встановлення або запуск Gateway. +життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway. Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий скрипт `HOOK.md`, встановлений оператором, для подій команд і Gateway, таких як @@ -56,65 +56,67 @@ export default definePluginEntry({ }); ``` -Обробники хуків виконуються послідовно у порядку спадання `priority`. Хуки з однаковим пріоритетом -зберігають порядок реєстрації. +Обробники хуків виконуються послідовно в порядку спадання `priority`. Хуки з +однаковим пріоритетом зберігають порядок реєстрації. -Кожен хук отримує `event.context.pluginConfig` — розв’язану конфігурацію для -plugin, який зареєстрував цей обробник. Використовуйте її для рішень у хуках, яким -потрібні поточні параметри plugin; OpenClaw інжектує її для кожного обробника, не змінюючи -спільний об’єкт події, який бачать інші plugins. +Кожен хук отримує `event.context.pluginConfig` — обчислену конфігурацію для +plugin, який зареєстрував цей обробник. Використовуйте її для рішень у хуках, +яким потрібні поточні параметри plugin; OpenClaw додає її для кожного +обробника без змінювання спільного об’єкта події, який бачать інші plugins. ## Каталог хуків -Хуки згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають -результат рішення (block, cancel, override або require approval); усі інші призначені -лише для спостереження. +Хуки згруповані за поверхнею, яку вони розширюють. Назви **жирним** приймають +результат рішення (блокування, скасування, перевизначення або вимога схвалення); +усі інші призначені лише для спостереження. **Хід агента** - `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії -- `before_prompt_build` — додати динамічний контекст або текст системного промпту перед викликом моделі -- `before_agent_start` — сумісна комбінована фаза; натомість віддавайте перевагу двом хукам вище -- **`before_agent_reply`** — завершити хід моделі достроково синтетичною відповіддю або тишею +- `agent_turn_prepare` — спожити поставлені в чергу ін’єкції ходу plugin і додати контекст того самого ходу до хуків промпта +- `before_prompt_build` — додати динамічний контекст або текст системного промпта до виклику моделі +- `before_agent_start` — комбінована фаза лише для сумісності; натомість віддавайте перевагу двом хукам вище +- **`before_agent_reply`** — перервати хід моделі синтетичною відповіддю або безшумно - **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі -- `agent_end` — спостерігати за фінальними повідомленнями, станом успіху та тривалістю запуску +- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску +- `heartbeat_prompt_contribution` — додати контекст лише для Heartbeat для фонових моніторів і plugin життєвого циклу **Спостереження за розмовою** -- `model_call_started` / `model_call_ended` — спостерігати за очищеними метаданими виклику провайдера/моделі, часом, результатом і обмеженими хешами request id без вмісту промпту або відповіді -- `llm_input` — спостерігати за входом провайдера (системний промпт, промпт, історія) -- `llm_output` — спостерігати за виходом провайдера +- `model_call_started` / `model_call_ended` — спостерігати очищені метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту промпта або відповіді +- `llm_input` — спостерігати вхід провайдера (системний промпт, промпт, історія) +- `llm_output` — спостерігати вихід провайдера **Інструменти** - **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення -- `after_tool_call` — спостерігати за результатами інструментів, помилками та тривалістю -- **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента +- `after_tool_call` — спостерігати результати інструмента, помилки та тривалість +- **`tool_result_persist`** — переписати повідомлення помічника, створене з результату інструмента - **`before_message_write`** — перевірити або заблокувати запис повідомлення в процесі (рідко) **Повідомлення та доставка** - **`inbound_claim`** — перехопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді) -- `message_received` — спостерігати за вхідним вмістом, відправником, потоком і метаданими +- `message_received` — спостерігати вхідний вміст, відправника, гілку та метадані - **`message_sending`** — переписати вихідний вміст або скасувати доставку -- `message_sent` — спостерігати за успіхом або невдачею вихідної доставки -- **`before_dispatch`** — перевірити або переписати вихідний dispatch перед передачею каналу +- `message_sent` — спостерігати успіх або збій вихідної доставки +- **`before_dispatch`** — перевірити або переписати вихідне dispatch до передавання каналу - **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді **Сесії та Compaction** - `session_start` / `session_end` — відстежувати межі життєвого циклу сесії -- `before_compaction` / `after_compaction` — спостерігати за циклами Compaction або анотувати їх -- `before_reset` — спостерігати за подіями скидання сесії (`/reset`, програмні скидання) +- `before_compaction` / `after_compaction` — спостерігати або анотувати цикли Compaction +- `before_reset` — спостерігати події скидання сесії (`/reset`, програмні скидання) -**Сабагенти** +**Субагенти** -- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію сабагентів і доставку завершення +- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію субагентів і доставку після завершення **Життєвий цикл** -- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси, якими володіє plugin, разом із Gateway -- **`before_install`** — перевіряти сканування встановлення skill або plugin та за потреби блокувати +- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси plugin разом із Gateway +- **`before_install`** — перевіряти сканування встановлення skill або plugin і за потреби блокувати ## Політика викликів інструментів @@ -125,7 +127,7 @@ plugin, який зареєстрував цей обробник. Викори - необов’язковий `event.runId` - необов’язковий `event.toolCallId` - поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, - `ctx.runId`, `ctx.jobId` (встановлюється для запусків, ініційованих Cron), і діагностичний `ctx.trace` + `ctx.runId`, `ctx.jobId` (встановлюється для запусків, керованих cron), і діагностичний `ctx.trace` Він може повертати: @@ -151,64 +153,58 @@ type BeforeToolCallResult = { Правила: - `block: true` є термінальним і пропускає обробники з нижчим пріоритетом. -- `block: false` вважається відсутністю рішення. +- `block: false` розглядається як відсутність рішення. - `params` переписує параметри інструмента для виконання. -- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin. - Команда `/approve` може схвалювати як exec, так і схвалення plugin. -- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом - запросив схвалення. +- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin. Команда `/approve` може схвалювати як exec, так і схвалення plugin. +- `block: true` із нижчим пріоритетом усе одно може заблокувати після того, як хук із вищим пріоритетом запросив схвалення. - `onResolution` отримує підсумкове рішення щодо схвалення — `allow-once`, `allow-always`, `deny`, `timeout` або `cancelled`. -### Збереження результатів інструментів +Вбудовані plugins, яким потрібна політика рівня хоста, можуть реєструвати довірені політики інструментів через `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних хуків `before_tool_call` і до рішень зовнішніх plugin. Використовуйте їх лише для довірених хостом бар’єрів, таких як політика робочого простору, контроль бюджету або безпека зарезервованих робочих процесів. Зовнішні plugins мають використовувати звичайні хуки `before_tool_call`. -Результати інструментів можуть містити структуровані `details` для рендерингу в UI, діагностики, -маршрутизації медіа або метаданих, якими володіє plugin. Сприймайте `details` як метадані -середовища виконання, а не як вміст промпту: +### Збереження результатів інструмента -- OpenClaw видаляє `toolResult.details` перед повторним відтворенням у провайдері та входом Compaction, - щоб метадані не ставали контекстом моделі. -- Збережені записи сесії зберігають лише обмежені `details`. Надто великі details - замінюються компактним підсумком і `persistedDetailsTruncated: true`. -- `tool_result_persist` і `before_message_write` виконуються перед фінальним - обмеженням збереження. Хуки все одно мають зберігати повернуті `details` невеликими й уникати - розміщення важливого для промпту тексту лише в `details`; видимий для моделі вихід інструмента - слід поміщати в `content`. +Результати інструмента можуть містити структуровані `details` для рендерингу в UI, діагностики, +маршрутизації медіа або метаданих, що належать plugin. Розглядайте `details` як +метадані часу виконання, а не як вміст промпта: -## Хуки промпту та моделі +- OpenClaw видаляє `toolResult.details` перед повторним відтворенням провайдером і входом Compaction, щоб метадані не ставали контекстом моделі. +- Постійно збережені записи сесії містять лише обмежені `details`. Завеликі details замінюються компактним підсумком і `persistedDetailsTruncated: true`. +- `tool_result_persist` і `before_message_write` виконуються до фінального обмеження на постійне збереження. Хуки все одно мають тримати повернуті `details` малими й уникати розміщення тексту, релевантного для промпта, лише в `details`; видимий для моделі вихід інструмента слід поміщати в `content`. + +## Хуки промпта та моделі Для нових plugins використовуйте хуки, специфічні для фази: - `before_model_resolve`: отримує лише поточний промпт і метадані вкладень. Поверніть `providerOverride` або `modelOverride`. -- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. - Поверніть `prependContext`, `systemPrompt`, `prependSystemContext` або - `appendSystemContext`. +- `agent_turn_prepare`: отримує поточний промпт, підготовлені повідомлення сесії та будь-які ін’єкції рівно-один-раз, зняті з черги для цієї сесії. Поверніть `prependContext` або `appendContext`. +- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. Поверніть `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`. +- `heartbeat_prompt_contribution`: виконується лише для ходів Heartbeat і повертає `prependContext` або `appendContext`. Призначений для фонових моніторів, яким потрібно підсумовувати поточний стан без зміни ходів, ініційованих користувачем. -`before_agent_start` залишається для сумісності. Надавайте перевагу явним хукам вище, +`before_agent_start` зберігається для сумісності. Віддавайте перевагу явним хукам вище, щоб ваш plugin не залежав від застарілої комбінованої фази. -`before_agent_start` і `agent_end` включають `event.runId`, коли OpenClaw може -ідентифікувати активний запуск. Це саме значення також доступне в `ctx.runId`. -Запуски, ініційовані Cron, також мають `ctx.jobId` (ідентифікатор вихідного завдання cron), щоб -хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретного запланованого -завдання. +`before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може +визначити активний запуск. Те саме значення також доступне в `ctx.runId`. +Запуски, керовані Cron, також надають `ctx.jobId` (ідентифікатор вихідної Cron-задачі), щоб +хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретної +запланованої задачі. -Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера, -яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів -або request id провайдера. Ці хуки містять стабільні метадані, такі як +Використовуйте `model_call_started` і `model_call_ended` для телеметрії +викликів провайдера, яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів або request ID провайдера. Ці хуки містять стабільні метадані, такі як `runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, фінальні -`durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може вивести -обмежений хеш request id провайдера. +`durationMs`/`outcome` та `upstreamRequestIdHash`, коли OpenClaw може вивести +обмежений хеш request-id провайдера. `before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну -фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не +фінальну відповідь помічника. Це не шлях скасування `/stop`, і він не виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб -попросити harness зробити ще один прохід моделі перед фіналізацією, `{ action: -"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, -щоб продовжити. Нативні хуки Codex `Stop` ретранслюються в цей хук як рішення OpenClaw +попросити harness виконати ще один прохід моделі до фіналізації, `{ action: +"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, щоб продовжити. +Власні хуки `Stop` у Codex передаються в цей хук як рішення OpenClaw `before_agent_finalize`. -Зовнішні plugins, не включені до складу, яким потрібні `llm_input`, `llm_output`, +Невбудовані plugins, яким потрібні `llm_input`, `llm_output`, `before_agent_finalize` або `agent_end`, мають встановити: ```json @@ -225,66 +221,90 @@ type BeforeToolCallResult = { } ``` -Хуки, що змінюють промпт, можна вимкнути для кожного plugin через -`plugins.entries..hooks.allowPromptInjection=false`. +Хуки, що змінюють промпт, і стійкі ін’єкції наступного ходу можна вимкнути для кожного plugin +через `plugins.entries..hooks.allowPromptInjection=false`. + +### Розширення сесії та ін’єкції наступного ходу + +Workflow plugins можуть зберігати невеликий JSON-сумісний стан сесії за допомогою +`api.registerSessionExtension(...)` і оновлювати його через метод Gateway +`sessions.pluginPatch`. Рядки сесії проєктують зареєстрований стан розширення через +`pluginExtensions`, що дозволяє Control UI та іншим клієнтам відображати +стан, який належить plugin, без вивчення внутрішньої реалізації plugin. + +Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin потрібен стійкий контекст, який +має потрапити до наступного ходу моделі рівно один раз. OpenClaw знімає поставлені в чергу ін’єкції до +хуків промпта, відкидає прострочені ін’єкції та усуває дублікати за `idempotencyKey` +для кожного plugin. Це правильна точка інтеграції для відновлення після схвалення, +підсумків політик, змін від фонового монітора та продовжень команд, які +мають бути видимі моделі на наступному ході, але не повинні ставати постійним +текстом системного промпта. + +Семантика очищення є частиною контракту. Зворотні виклики очищення розширень сесії та +очищення життєвого циклу часу виконання отримують `reset`, `delete`, `disable` або +`restart`. Хост видаляє постійний стан розширення сесії плагіна-власника та +очікувані ін’єкції наступного ходу для `reset`/`delete`/`disable`; `restart` зберігає +стійкий стан сесії, а зворотні виклики очищення дають plugins змогу звільняти +задачі планувальника, контекст виконання та інші позасмугові ресурси для старого +покоління часу виконання. ## Хуки повідомлень Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки: -- `message_received`: спостерігати за вхідним вмістом, відправником, `threadId`, `messageId`, - `senderId`, необов’язковою кореляцією запуску/сесії та метаданими. +- `message_received`: спостерігати вхідний вміст, відправника, `threadId`, `messageId`, + `senderId`, необов’язкову кореляцію запуску/сесії та метадані. - `message_sending`: переписати `content` або повернути `{ cancel: true }`. -- `message_sent`: спостерігати за остаточним успіхом або невдачею. +- `message_sent`: спостерігати фінальний успіх або збій. -Для аудіо-відповідей TTS без тексту `content` може містити приховану озвучену транскрипцію, -навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього -`content` оновлює лише транскрипцію, видиму для хука; воно не рендериться як -підпис до медіа. +Для відповідей TTS лише з аудіо `content` може містити приховану транскрипцію +озвученого тексту, навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього +`content` оновлює лише видиму для хука транскрипцію; воно не відображається як +підпис медіа. Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, -`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Надавайте перевагу -цим полям першого класу, а не читанню застарілих метаданих. +`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу +цим полям першого класу, перш ніж звертатися до застарілих метаданих. -Надавайте перевагу типізованим полям `threadId` і `replyToId`, а не використанню -метаданих, специфічних для каналу. +Віддавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати +метадані, специфічні для каналу. Правила рішень: - `message_sending` з `cancel: true` є термінальним. -- `message_sending` з `cancel: false` вважається відсутністю рішення. +- `message_sending` з `cancel: false` розглядається як відсутність рішення. - Переписаний `content` передається далі хукам із нижчим пріоритетом, якщо пізніший хук не скасує доставку. ## Хуки встановлення `before_install` виконується після вбудованого сканування для встановлень skill і plugin. -Поверніть додаткові findings або `{ block: true, blockReason }`, щоб зупинити +Поверніть додаткові результати або `{ block: true, blockReason }`, щоб зупинити встановлення. -`block: true` є термінальним. `block: false` вважається відсутністю рішення. +`block: true` є термінальним. `block: false` розглядається як відсутність рішення. ## Життєвий цикл Gateway -Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. -Контекст надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для -перевірки та оновлення Cron. Використовуйте `gateway_stop`, щоб очищати довготривалі +Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст +надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для +перевірки та оновлення cron. Використовуйте `gateway_stop`, щоб очищати довготривалі ресурси. -Не покладайтеся на внутрішній хук `gateway:startup` для сервісів середовища виконання, -якими володіє plugin. +Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання, +що належать plugin. ## Майбутні застарівання -Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Виконайте +Кілька поверхонь, суміжних із хуками, застаріли, але все ще підтримуються. Виконайте міграцію до наступного мажорного релізу: -- **Текстові plaintext-конверти каналів** в обробниках `inbound_claim` і `message_received`. +- **Незашифровані конверти каналу** в обробниках `inbound_claim` і `message_received`. Читайте `BodyForAgent` і структуровані блоки контексту користувача - замість розбору плаского тексту конверта. Див. - [Plaintext channel envelopes → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). -- **`before_agent_start`** залишається для сумісності. Нові plugins мають використовувати + замість парсингу плоского тексту конверта. Див. + [Незашифровані конверти каналу → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). +- **`before_agent_start`** зберігається для сумісності. Нові plugins мають використовувати `before_model_resolve` і `before_prompt_build` замість комбінованої фази. - **`onResolution` у `before_tool_call`** тепер використовує типізоване @@ -292,15 +312,15 @@ type BeforeToolCallResult = { `timeout` / `cancelled`) замість довільного `string`. Повний список — реєстрація можливостей пам’яті, профіль thinking провайдера, -зовнішні провайдери auth, типи виявлення провайдерів, аксесори TaskFlow середовища виконання -та перейменування `command-auth` → `command-status` — див. у -[Plugin SDK migration → Active deprecations](/uk/plugins/sdk-migration#active-deprecations). +зовнішні провайдери автентифікації, типи виявлення провайдерів, аксесори часу виконання задач +і перейменування `command-auth` → `command-status` — див. у +[Міграція Plugin SDK → Активні застарівання](/uk/plugins/sdk-migration#active-deprecations). -## Пов’язані матеріали +## Пов’язане -- [Plugin SDK migration](/uk/plugins/sdk-migration) — активні застарівання та графік видалення -- [Building plugins](/uk/plugins/building-plugins) -- [Plugin SDK overview](/uk/plugins/sdk-overview) -- [Plugin entry points](/uk/plugins/sdk-entrypoints) -- [Internal hooks](/uk/automation/hooks) -- [Plugin architecture internals](/uk/plugins/architecture-internals) +- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та графік видалення +- [Створення plugins](/uk/plugins/building-plugins) +- [Огляд Plugin SDK](/uk/plugins/sdk-overview) +- [Точки входу Plugin](/uk/plugins/sdk-entrypoints) +- [Внутрішні хуки](/uk/automation/hooks) +- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals) diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 4d9fbf89d..efe89bbfe 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,21 +1,21 @@ --- read_when: - - Вам потрібно знати, з якого підшляху SDK імпортувати + - Потрібно знати, з якого підшляху SDK імпортувати - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Import map, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник з API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-27T11:01:36Z" + generated_at: "2026-04-28T00:10:37Z" model: gpt-5.4 provider: openai - source_hash: 205c57492fd2c90c01a87bae34716d6abcf420c7bdc2f51bd3042e52a3872ec6 + source_hash: f9b00b189c2a5e632a1c7e614a3e9371dcc3114d3582d795e3c88fb5d5a0f13a source_path: plugins/sdk-overview.md workflow: 15 --- -Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка — +Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — довідник про **що імпортувати** і **що можна реєструвати**. @@ -27,7 +27,7 @@ Plugin SDK — це типізований контракт між плагін - Плагін інструмента або хука життєвого циклу? Див. [Хуки плагінів](/uk/plugins/hooks). -## Угода щодо імпорту +## Правило імпорту Завжди імпортуйте з конкретного підшляху: @@ -38,37 +38,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу -хелперів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; -`openclaw/plugin-sdk/core` залишайте для ширшої парасолькової поверхні та -спільних хелперів, таких як +допоміжних засобів entry/build віддавайте перевагу +`openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої узагальненої поверхні та спільних допоміжних функцій, таких як `buildChannelConfigSchema`. -Для конфігурації каналу публікуйте JSON Schema, якою володіє канал, через +Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через `openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema` -призначений для спільних примітивів схем і узагальненого builder. Застарілі -експорти схем вбудованих каналів знаходяться в `plugin-sdk/channel-config-schema-legacy` -лише для сумісності зі вбудованими компонентами; це не шаблон для нових плагінів. +призначений для спільних примітивів схем і універсального збирача. Застарілі +експорти схем вбудованих каналів розміщено в +`plugin-sdk/channel-config-schema-legacy` лише для сумісності з вбудованими +рішеннями; це не шаблон для нових плагінів. - Не імпортуйте branded convenience seams для провайдерів або каналів (наприклад + Не імпортуйте зручні seam-інтерфейси, позначені як provider або channel (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни композують узагальнені підшляхи SDK усередині власних barrel-файлів - `api.ts` / `runtime-api.ts`; споживачі core мають або використовувати ці локальні - barrel-файли плагіна, або додавати вузький узагальнений контракт SDK, коли потреба + Вбудовані плагіни поєднують універсальні підшляхи SDK усередині власних barrel-файлів + `api.ts` / `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні + barrel-файли плагіна, або додати вузький універсальний контракт SDK, якщо потреба справді є міжканальною. -Невеликий набір helper seams вбудованих плагінів (`plugin-sdk/feishu`, -`plugin-sdk/zalo`, `plugin-sdk/matrix*` тощо) усе ще присутній у -згенерованій мапі експортів. Вони існують лише для підтримки вбудованих плагінів і +Невеликий набір допоміжних seam-інтерфейсів для вбудованих плагінів (`plugin-sdk/feishu`, +`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще присутній у +згенерованій карті експортів. Вони існують лише для супроводу вбудованих плагінів і не рекомендуються як шляхи імпорту для нових сторонніх плагінів. ## Довідник підшляхів -Plugin SDK доступний як набір вузьких підшляхів, згрупованих за областями (entry -плагіна, канал, провайдер, auth, runtime, capability, memory і зарезервовані -хелпери вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див. у -[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). +Plugin SDK надається як набір вузьких підшляхів, згрупованих за напрямами (entry +плагіна, channel, provider, auth, runtime, capability, memory і зарезервовані +допоміжні засоби для вбудованих плагінів). Повний каталог — згрупований і з +посиланнями — див. у [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. @@ -79,75 +80,119 @@ Plugin SDK доступний як набір вузьких підшляхів, ### Реєстрація можливостей -| Метод | Що реєструє | -| ----------------------------------------------- | ------------------------------------ | -| `api.registerProvider(...)` | Текстове inferencing (LLM) | -| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend inferencing CLI | -| `api.registerChannel(...)` | Канал повідомлень | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)`| Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| Метод | Що він реєструє | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | Текстову інференцію (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | +| `api.registerCliBackend(...)` | Локальний backend інференції CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокову транскрипцію в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерацію зображень | +| `api.registerMusicGenerationProvider(...)` | Генерацію музики | +| `api.registerVideoGenerationProvider(...)` | Генерацію відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що реєструє | -| ------------------------------ | -------------------------------------------- | -| `api.registerTool(tool, opts?)`| Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Власна команда (обходить LLM) | +| Метод | Що він реєструє | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | +| `api.registerCommand(def)` | Користувацьку команду (обходить LLM) | -Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка -підказка маршрутизації, якою володіє команда. Тримайте цей текст про саму команду; -не додавайте специфічну для провайдера або плагіна політику до builder-ів промптів core. +Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна +коротка підказка маршрутизації, що належить команді. Робіть цей текст саме про +команду; не додавайте специфічну для провайдера чи плагіна політику до +збирачів prompt у ядрі. ### Інфраструктура -| Метод | Що реєструє | -| --------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerGatewayDiscoveryService(service)`| Локальний advertiser виявлення Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)`| Інтерактивний handler | -| `api.registerAgentToolResultMiddleware(...)` | Middleware результату інструмента під час виконання | -| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція промпту поруч із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| Метод | Що він реєструє | +| ---------------------------------------------- | -------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук події | +| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerGatewayDiscoveryService(service)` | Сервіс оголошення локального виявлення Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманду CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerAgentToolResultMiddleware(...)` | Проміжний обробник результатів інструментів runtime | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус для пошуку/читання memory | + +### Хуки хоста для workflow-плагінів + +Хуки хоста — це seam-інтерфейси SDK для плагінів, яким потрібно брати участь у +життєвому циклі хоста, а не лише додавати provider, channel або tool. Це +універсальні контракти; їх може використовувати Plan Mode, але так само ними +можуть користуватися workflow затвердження, шлюзи політик робочого простору, +фонові монітори, майстри налаштування та UI-плагіни-компаньйони. + +| Метод | Контракт, яким він володіє | +| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | Стан сесії, що належить плагіну, сумісний із JSON і проєктується через сесії Gateway | +| `api.enqueueNextTurnInjection(...)` | Надійний контекст рівно-один-раз, що вбудовується в наступний хід агента для однієї сесії | +| `api.registerTrustedToolPolicy(...)` | Політика інструментів trusted/bundled до плагіна, яка може блокувати або переписувати параметри інструментів | +| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | +| `api.registerCommand(...)` | Обмежені команди плагіна; результати команд можуть встановлювати `continueAgent: true` | +| `api.registerControlUiDescriptor(...)` | Дескриптори внеску в Control UI для поверхонь сесій, інструментів, запусків або налаштувань | +| `api.registerRuntimeLifecycle(...)` | Колбеки очищення для ресурсів runtime, що належать плагіну, на шляхах reset/delete/reload | +| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна на рівні запуску, що очищується на завершальному етапі життєвого циклу запуску | +| `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сесій, що належать плагіну, з детермінованим очищенням | + +Ці контракти навмисно розділяють повноваження: + +- Зовнішні плагіни можуть володіти розширеннями сесій, дескрипторами UI, командами, + метаданими інструментів, ін’єкціями в наступний хід і звичайними хуками. +- Політики trusted інструментів виконуються до звичайних хуків `before_tool_call` і + доступні лише для bundled, оскільки вони беруть участь у політиці безпеки хоста. +- Володіння зарезервованими командами доступне лише для bundled. Зовнішнім плагінам + слід використовувати власні назви команд або псевдоніми. +- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з + `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, + полями prompt із застарілого `before_agent_start` і + `enqueueNextTurnInjection`. + +Приклади споживачів, не пов’язаних із Plan: + +| Архетип плагіна | Використовувані хуки | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Workflow затвердження | Розширення сесії, продовження команди, ін’єкція в наступний хід, дескриптор UI | +| Шлюз політик бюджету/робочого простору | Trusted tool policy, metadata інструментів, проєкція сесії | +| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок у Heartbeat prompt, дескриптор UI | +| Майстер налаштування або онбордингу | Розширення сесії, обмежені команди, дескриптор Control UI | - Зарезервовані адміністраторські простори імен core (`config.*`, `exec.approvals.*`, `wizard.*`, + Зарезервовані простори назв адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити - вужчий scope методу Gateway. Для методів, якими володіє плагін, віддавайте перевагу - префіксам, специфічним для плагіна. + вужчу область видимості методу gateway. Для методів, що належать плагіну, + віддавайте перевагу префіксам, специфічним для плагіна. - + Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм потрібно переписати результат інструмента після виконання і до того, як runtime - поверне цей результат назад у модель. Це надійний runtime-neutral seam для - асинхронних reducer-ів виходу, таких як tokenjuice. + поверне цей результат назад у модель. Це trusted і runtime-нейтральний + seam-інтерфейс для асинхронних редукторів виводу, таких як tokenjuice. -Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного -цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни -не можуть реєструвати це middleware; для роботи, якій не потрібен таймінг -результату інструмента до моделі, використовуйте звичайні хуки плагінів OpenClaw. Старий -шлях реєстрації factory вбудованих extension лише для Pi було видалено. +Вбудовані плагіни повинні оголошувати `contracts.agentToolResultMiddleware` для +кожного цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни +не можуть реєструвати цей middleware; для роботи, якій не потрібен таймінг +результатів інструментів до моделі, використовуйте звичайні хуки плагінів OpenClaw. Старий +шлях реєстрації фабрики вбудованих розширень лише для Pi було вилучено. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає змогу плагіну рекламувати активний -Gateway через локальний транспорт виявлення, такий як mDNS/Bonjour. OpenClaw викликає службу -під час запуску Gateway, коли локальне виявлення ввімкнене, передає поточні -порти Gateway і не секретні TXT-підказки, а також викликає повернений -handler `stop` під час вимкнення Gateway. +`api.registerGatewayDiscoveryService(...)` дозволяє плагіну оголошувати активний +Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає +сервіс під час запуску Gateway, коли ввімкнено локальне виявлення, передає +поточні порти Gateway і не секретні підказки даних TXT, а також викликає +повернений обробник `stop` під час зупинки Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -163,20 +208,21 @@ api.registerGatewayDiscoveryService({ }); ``` -Плагіни виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або -автентифікацію. Виявлення — це підказка маршрутизації; довірою й далі керують auth Gateway і pinning TLS. +Плагіни виявлення Gateway не повинні трактувати оголошені значення TXT як +секрети або автентифікацію. Виявлення — це підказка маршрутизації; довірою, як і +раніше, керують автентифікація Gateway та TLS pinning. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для довідки кореневого CLI, +- `commands`: явні корені команд, якими володіє реєстратор +- `descriptors`: дескриптори команд на етапі парсингу, які використовуються для довідки кореневого CLI, маршрутизації та лінивої реєстрації CLI плагіна -Якщо ви хочете, щоб команда плагіна лишалася ліниво завантажуваною в нормальному шляху кореневого CLI, -надайте `descriptors`, що покривають кожен корінь команди верхнього рівня, який відкриває цей -registrar. +Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною в +звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен +корінь команди верхнього рівня, що експонується цим реєстратором. ```typescript api.registerCli( @@ -188,7 +234,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -196,93 +242,94 @@ api.registerCli( ); ``` -Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI. -Цей eager-сумісний шлях усе ще підтримується, але він не встановлює -плейсхолдери на основі дескрипторів для лінивого завантаження на етапі парсингу. +Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація +кореневого CLI. Цей сумісний eager-шлях усе ще підтримується, але він не +встановлює заповнювачі на основі descriptors для лінивого завантаження на етапі +парсингу. ### Реєстрація backend CLI -`api.registerCliBackend(...)` дає змогу плагіну володіти конфігурацією за замовчуванням для локального -AI backend CLI, такого як `codex-cli`. +`api.registerCliBackend(...)` дозволяє плагіну володіти конфігурацією за +замовчуванням для локального backend CLI ШІ, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в посиланнях на моделі, наприклад `codex-cli/gpt-5`. -- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - значень плагіна за замовчуванням перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття - (наприклад нормалізації старих форм прапорців). +- `id` backend стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`. +- `config` backend використовує ту саму структуру, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + значення за замовчуванням плагіна перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття + (наприклад, для нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що реєструє | -| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати адитивні промпти. | -| `api.registerMemoryCapability(capability)`| Єдину можливість пам’яті | -| `api.registerMemoryPromptSection(builder)`| Builder секції промпту пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| Метод | Що він реєструє | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Context engine (одночасно активним може бути лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення prompt. | +| `api.registerMemoryCapability(capability)` | Уніфіковану можливість memory | +| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt для memory | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory | -### Адаптери embedding пам’яті +### Адаптери embedding для memory -| Метод | Що реєструє | -| ---------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | +| Метод | Що він реєструє | +| ---------------------------------------------- | ----------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного плагіна | -- `registerMemoryCapability` — рекомендований API ексклюзивного плагіна пам’яті. -- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, - щоб супровідні плагіни могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість проникнення в приватну розкладку - конкретного плагіна пам’яті. +- `registerMemoryCapability` — бажаний API ексклюзивного memory-плагіна. +- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`, + щоб плагіни-компаньйони могли споживати експортовані артефакти memory через + `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури + конкретного memory-плагіна. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — застаріло-сумісні API ексклюзивного плагіна пам’яті. -- `registerMemoryEmbeddingProvider` дає змогу активному плагіну пам’яті зареєструвати один - або кілька ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або - власний ідентифікатор, визначений плагіном). + `registerMemoryRuntime` — це сумісні з legacy API ексклюзивного memory-плагіна. +- `registerMemoryEmbeddingProvider` дозволяє активному memory-плагіну реєструвати один + або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або + власний id, визначений плагіном). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих - ідентифікаторів адаптерів. + `agents.defaults.memorySearch.fallback`, резолвиться відносно цих зареєстрованих + id адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| ------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)`| Колбек прив’язки розмови | +| Метод | Що він робить | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | -Див. [Хуки плагінів](/uk/plugins/hooks), щоб переглянути приклади, поширені назви хуків і -семантику guard. +Приклади, поширені назви хуків і семантику guard див. у +[Хуки плагінів](/uk/plugins/hooks). -### Семантика рішень у хуках +### Семантика рішень хуків -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються. - `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються. - `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере dispatch на себе, handler-и нижчого пріоритету та стандартний шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перебирає на себе dispatch, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник установлює це значення, обробники з нижчим пріоритетом пропускаються. - `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. `metadata` залишайте для специфічних для каналу доповнень. +- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для специфічних для каналу додаткових даних. - `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для каналу `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість опори на внутрішні хуки `gateway:startup`. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор плагіна | -| `api.name` | `string` | Назва для відображення | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Специфічна для плагіна конфігурація з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Хелпери runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | ID плагіна | +| `api.name` | `string` | Назва для відображення | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime в пам’яті, якщо доступний) | +| `api.pluginConfig` | `Record` | Специфічна для плагіна конфігурація з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю дії (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | +| `api.resolvePath(input)` | `(string) => string` | Резолвить шлях відносно кореня плагіна | -## Угода щодо внутрішніх модулів +## Внутрішня угода щодо модулів Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: @@ -296,41 +343,41 @@ my-plugin/ Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - з production-коду. Для внутрішніх імпортів використовуйте `./api.ts` або - `./runtime-api.ts`. Шлях SDK — лише зовнішній контракт. + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих плагінів, завантажені через facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), надають перевагу -активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime -ще не існує, вони переходять у резервний режим до визначеного файла конфігурації на диску. +Публічні поверхні вбудованих плагінів, завантажувані через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу +активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до резолвленого файлу конфігурації на диску. -Плагіни провайдерів можуть відкривати вузький локальний контрактний barrel плагіна, коли -helper навмисно є специфічним для провайдера і ще не належить до узагальненого підшляху SDK. -Приклади вбудованих плагінів: +Плагіни провайдерів можуть експонувати вузький локальний barrel-контракт плагіна, коли +певний helper навмисно є специфічним для провайдера і поки що не належить до +універсального підшляху SDK. Приклади вбудованих рішень: -- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для helper-ів - beta-header Claude і `service_tier` stream. -- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдера, - helper-и моделей за замовчуванням і builder-и провайдерів realtime. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера - разом із helper-ами онбордингу/конфігурації. +- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для helper-функцій + beta-header Claude і потоку `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдерів, + helper-и моделей за замовчуванням і builder-и realtime-провайдерів. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера, + а також helper-и онбордингу/конфігурації. - Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо helper справді є спільним, підвищте його до нейтрального підшляху SDK, + Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. + Якщо helper справді є спільним, перенесіть його до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливість, замість жорсткого зв’язування двох плагінів. + поверхні, орієнтованої на capability, замість зв’язування двох плагінів між собою. -## Пов’язане +## Пов’язані матеріали - Параметри `definePluginEntry` і `defineChannelPluginEntry`. + Опції `definePluginEntry` і `defineChannelPluginEntry`. - - Повний довідник простору імен `api.runtime`. + + Повний довідник простору назв `api.runtime`. Пакування, маніфести та схеми конфігурації. @@ -341,7 +388,7 @@ helper навмисно є специфічним для провайдера і Міграція із застарілих поверхонь. - - Поглиблена архітектура та модель можливостей. + + Поглиблена архітектура та модель capability.