diff --git a/docs/uk/plugins/sdk-runtime.md b/docs/uk/plugins/sdk-runtime.md index 70ce72fdd..fa9479b2d 100644 --- a/docs/uk/plugins/sdk-runtime.md +++ b/docs/uk/plugins/sdk-runtime.md @@ -1,28 +1,28 @@ --- read_when: - - Потрібно викликати допоміжні функції ядра з Plugin (TTS, STT, генерація зображень, вебпошук, субагент, вузли) + - Вам потрібно викликати допоміжні функції ядра з Plugin (TTS, STT, генерація зображень, вебпошук, субагент, вузли) - Ви хочете зрозуміти, що надає api.runtime - - Ви звертаєтеся до допоміжних засобів конфігурації, агента або медіа з коду Plugin + - Ви звертаєтеся до допоміжних функцій конфігурації, агента або медіа з коду Plugin sidebarTitle: Runtime helpers -summary: api.runtime -- впроваджені допоміжні засоби середовища виконання, доступні для плагінів +summary: api.runtime -- інʼєктовані допоміжні засоби runtime, доступні для Plugin title: Допоміжні засоби середовища виконання Plugin x-i18n: - generated_at: "2026-04-28T11:20:50Z" + generated_at: "2026-04-29T13:06:22Z" model: gpt-5.5 provider: openai - source_hash: d332e9ab4a163a55b7edaefc420d845cfda8486646e13a758ec3133097c17be1 + source_hash: 399e2433e272fe30e7451690a64826df8e30a064269b8d9a7aa2dd2b0c5688b8 source_path: plugins/sdk-runtime.md workflow: 16 --- -Довідник для об’єкта `api.runtime`, який вводиться в кожен плагін під час реєстрації. Використовуйте ці допоміжні функції замість прямого імпорту внутрішніх модулів хоста. +Довідник для об’єкта `api.runtime`, який впроваджується в кожен Plugin під час реєстрації. Використовуйте ці допоміжні функції замість прямого імпорту внутрішніх компонентів хоста. - - Покроковий посібник, який використовує ці допоміжні функції в контексті плагінів каналів. + + Покроковий посібник, що показує використання цих допоміжних функцій у контексті Plugin для каналів. - - Покроковий посібник, який використовує ці допоміжні функції в контексті плагінів провайдерів. + + Покроковий посібник, що показує використання цих допоміжних функцій у контексті Plugin для провайдерів. @@ -34,38 +34,38 @@ register(api) { ## Завантаження й запис конфігурації -Надавайте перевагу конфігурації, яку вже передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-ах каналу чи провайдера. Це дає змогу проводити один знімок процесу крізь роботу замість повторного розбору конфігурації на гарячих шляхах. +Надавайте перевагу конфігурації, яку вже передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-функціях каналу/провайдера. Це забезпечує передавання одного знімка процесу через виконання роботи замість повторного розбору конфігурації на гарячих шляхах. -Використовуйте `api.runtime.config.current()` лише тоді, коли довгоживучому обробнику потрібен поточний знімок процесу, а конфігурацію не було передано цій функції. Повернене значення доступне лише для читання; перед редагуванням клонуйте його або використайте допоміжну функцію мутації. +Використовуйте `api.runtime.config.current()` лише тоді, коли довготривалому обробнику потрібен поточний знімок процесу, а конфігурацію не було передано в цю функцію. Повернене значення доступне лише для читання; перед редагуванням створіть копію або використайте допоміжну функцію мутації. -Фабрики інструментів отримують `ctx.runtimeConfig` плюс `ctx.getRuntimeConfig()`. Використовуйте getter у callback-у `execute` довгоживучого інструмента, коли конфігурація може змінитися після створення визначення інструмента. +Фабрики інструментів отримують `ctx.runtimeConfig` разом із `ctx.getRuntimeConfig()`. Використовуйте getter у callback-функції `execute` довготривалого інструмента, коли конфігурація може змінитися після створення визначення інструмента. -Зберігайте зміни за допомогою `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибрати явну політику `afterWrite`: +Зберігайте зміни за допомогою `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибирати явну політику `afterWrite`: -- `afterWrite: { mode: "auto" }` дає планувальнику перезавантаження Gateway змогу вирішити. +- `afterWrite: { mode: "auto" }` дозволяє планувальнику перезавантаження Gateway ухвалити рішення. - `afterWrite: { mode: "restart", reason: "..." }` примусово виконує чистий перезапуск, коли автор запису знає, що гаряче перезавантаження небезпечне. -- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження або перезапуск лише тоді, коли викликач сам відповідає за подальшу дію. +- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження/перезапуск лише тоді, коли викликач відповідає за подальші дії. -Допоміжні функції мутації повертають `afterWrite` плюс типізований підсумок `followUp`, щоб викликачі могли логувати або тестувати, чи вони запросили перезапуск. Gateway усе ще відповідає за те, коли цей перезапуск фактично відбудеться. +Допоміжні функції мутації повертають `afterWrite` разом із типізованим підсумком `followUp`, щоб викликачі могли логувати або тестувати, чи запитали вони перезапуск. Gateway і далі відповідає за те, коли цей перезапуск фактично відбудеться. -`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` є застарілими допоміжними функціями сумісності під `runtime-config-load-write`. Вони попереджають один раз під час виконання й залишаються доступними для старих зовнішніх плагінів протягом міграційного вікна. Вбудовані плагіни не повинні їх використовувати; охоронні перевірки межі конфігурації падають, якщо код плагіна викликає їх або імпортує ці допоміжні функції з підшляхів SDK плагінів. +`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` — застарілі допоміжні функції сумісності під `runtime-config-load-write`. Вони один раз попереджають під час виконання й залишаються доступними для старих зовнішніх Plugin протягом міграційного вікна. Вбудовані Plugin не повинні їх використовувати; захисні перевірки межі конфігурації завершаться помилкою, якщо код Plugin викликає їх або імпортує ці допоміжні функції з підшляхів Plugin SDK. -Для прямих імпортів SDK використовуйте спеціалізовані підшляхи конфігурації замість широкого агрегувального модуля сумісності +Для прямих імпортів SDK використовуйте сфокусовані підшляхи конфігурації замість широкого сумісного barrel `openclaw/plugin-sdk/config-runtime`: `config-types` для типів, `plugin-config-runtime` для перевірок уже завантаженої конфігурації та пошуку -запису плагіна, `runtime-config-snapshot` для поточних знімків процесу та -`config-mutation` для записів. Тести вбудованих плагінів мають напряму мокати ці спеціалізовані -підшляхи замість мокання широкого агрегувального модуля сумісності. +точки входу Plugin, `runtime-config-snapshot` для поточних знімків процесу, а +`config-mutation` для записів. Тести вбудованих Plugin мають напряму mock-ати ці сфокусовані +підшляхи замість mock широкого сумісного barrel. -Внутрішній код середовища виконання OpenClaw має той самий напрям: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні записи мутацій оновлюють знімок середовища виконання процесу й просувають його внутрішню ревізію; довгоживучі кеші мають прив’язуватися до ключа кешу, яким володіє середовище виконання, замість локальної серіалізації конфігурації. Довгоживучі модулі середовища виконання мають сканер із нульовою терпимістю до неявних викликів `loadConfig()`; використовуйте переданий `cfg`, запит `context.getRuntimeConfig()` або `getRuntimeConfig()` на явній межі процесу. +Внутрішній runtime-код OpenClaw дотримується того самого напряму: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні мутаційні записи оновлюють runtime-знімок процесу й збільшують його внутрішню ревізію; довготривалі кеші мають прив’язуватися до ключа кешу, яким володіє runtime, замість локальної серіалізації конфігурації. Довготривалі runtime-модулі мають сканер із нульовою терпимістю до неявних викликів `loadConfig()`; використовуйте переданий `cfg`, запитовий `context.getRuntimeConfig()` або `getRuntimeConfig()` на явній межі процесу. -Шляхи виконання провайдерів і каналів мають використовувати активний знімок конфігурації середовища виконання, а не файловий знімок, повернений для читання чи редагування конфігурації. Файлові знімки зберігають вихідні значення, як-от маркери SecretRef, для UI та записів; callback-и провайдерів потребують вирішеного runtime-представлення. Коли допоміжну функцію можна викликати або з активним вихідним знімком, або з активним runtime-знімком, перед читанням облікових даних пропустіть його через `selectApplicableRuntimeConfig()`. +Шляхи виконання провайдерів і каналів мають використовувати активний знімок runtime-конфігурації, а не файловий знімок, повернений для читання або редагування конфігурації. Файлові знімки зберігають початкові значення, як-от маркери SecretRef, для UI та записів; callback-функціям провайдерів потрібне вирішене runtime-представлення. Коли допоміжну функцію можна викликати або з активним початковим знімком, або з активним runtime-знімком, перед читанням облікових даних пропускайте його через `selectApplicableRuntimeConfig()`. -## Простори імен середовища виконання +## Простори імен runtime - Ідентичність агента, каталоги та керування сесіями. + Ідентичність агента, каталоги та керування сеансами. ```typescript // Resolve the agent's working directory @@ -109,15 +109,15 @@ register(api) { }); ``` - `runEmbeddedAgent(...)` є нейтральною допоміжною функцією для запуску звичайного ходу агента OpenClaw з коду плагіна. Вона використовує те саме вирішення провайдера/моделі та вибір agent-harness, що й відповіді, ініційовані каналом. + `runEmbeddedAgent(...)` — нейтральна допоміжна функція для запуску звичайного ходу агента OpenClaw з коду Plugin. Вона використовує те саме вирішення провайдера/моделі та вибір agent-harness, що й відповіді, ініційовані каналом. - `runEmbeddedPiAgent(...)` залишається псевдонімом сумісності. + `runEmbeddedPiAgent(...)` залишається сумісним псевдонімом. - `resolveThinkingPolicy(...)` повертає підтримувані провайдером/моделлю рівні мислення й необов’язкове значення за замовчуванням. Плагіни провайдерів володіють профілем, специфічним для моделі, через свої thinking-хуки, тому плагіни інструментів мають викликати цю допоміжну функцію середовища виконання замість імпорту або дублювання списків провайдерів. + `resolveThinkingPolicy(...)` повертає підтримувані провайдером/моделлю рівні thinking і необов’язкове значення за замовчуванням. Plugin провайдерів володіють профілем для конкретної моделі через свої thinking hooks, тому Plugin інструментів мають викликати цю runtime-допоміжну функцію замість імпорту або дублювання списків провайдерів. - `normalizeThinkingLevel(...)` перетворює текст користувача, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою його проти вирішеної політики. + `normalizeThinkingLevel(...)` перетворює користувацький текст, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою щодо вирішеної політики. - **Допоміжні функції сховища сесій** містяться в `api.runtime.agent.session`: + **Допоміжні функції сховища сеансів** розташовані в `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -137,7 +137,7 @@ register(api) { - Запускайте та керуйте фоновими запусками субагентів. + Запуск і керування фоновими виконаннями subagent. ```typescript // Start a subagent run @@ -165,14 +165,14 @@ register(api) { ``` - Перевизначення моделі (`provider`/`model`) потребують явного дозволу оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені плагіни все одно можуть запускати субагентів, але запити на перевизначення відхиляються. + Перевизначення моделі (`provider`/`model`) потребують явної згоди оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені Plugin усе ще можуть запускати subagent, але запити на перевизначення відхиляються. - `deleteSession(...)` може видаляти сесії, створені тим самим плагіном через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або операторських сесій усе ще потребує запиту Gateway з адміністративною областю дії. + `deleteSession(...)` може видаляти сеанси, створені тим самим Plugin через `api.runtime.subagent.run(...)`. Видалення довільних сеансів користувача або оператора все ще потребує Gateway-запиту з областю адміністратора. - Виводьте список підключених вузлів і викликайте команду вузла-хоста з коду плагіна, завантаженого Gateway, або з CLI-команд плагіна. Використовуйте це, коли плагін володіє локальною роботою на спареному пристрої, наприклад браузером або аудіомостом на іншому Mac. + Перелічує підключені вузли та викликає команду, розміщену на вузлі, з коду Plugin, завантаженого Gateway, або з CLI-команд Plugin. Використовуйте це, коли Plugin володіє локальною роботою на спареному пристрої, наприклад браузером або аудіомостом на іншому Mac. ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -185,11 +185,11 @@ register(api) { }); ``` - Усередині Gateway це середовище виконання працює в процесі. У CLI-командах плагіна воно викликає налаштований Gateway через RPC, тому команди на кшталт `openclaw googlemeet recover-tab` можуть перевіряти спарені вузли з термінала. Команди Node й далі проходять через звичайне спарювання вузлів Gateway, списки дозволених команд і локальну обробку команд на вузлі. + Усередині Gateway цей runtime працює в межах процесу. У CLI-командах Plugin він викликає налаштований Gateway через RPC, тож команди на кшталт `openclaw googlemeet recover-tab` можуть перевіряти спарені вузли з термінала. Команди вузлів усе ще проходять звичайне спарювання вузлів Gateway, allowlist команд і локальну обробку команд на вузлі. - Прив’яжіть середовище виконання TaskFlow до наявного ключа сесії OpenClaw або довіреного контексту інструмента, а потім створюйте й керуйте TaskFlow без передавання власника в кожному виклику. + Прив’язує runtime TaskFlow до наявного ключа сеансу OpenClaw або довіреного контексту інструмента, а потім створює TaskFlow і керує ними без передавання власника під час кожного виклику. ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -216,7 +216,7 @@ register(api) { }); ``` - Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли у вас уже є довірений ключ сесії OpenClaw з вашого власного шару прив’язки. Не прив’язуйте з необробленого користувацького введення. + Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли вже маєте довірений ключ сеансу OpenClaw із власного шару прив’язки. Не виконуйте прив’язку з необроблених користувацьких даних. @@ -246,7 +246,7 @@ register(api) { - Аналіз зображень, аудіо й відео. + Аналіз зображень, аудіо та відео. ```typescript // Describe an image @@ -276,15 +276,15 @@ register(api) { }); ``` - Повертає `{ text: undefined }`, коли вивід не створено (наприклад, пропущені вхідні дані). + Повертає `{ text: undefined }`, коли вихідні дані не створено (наприклад, вхід пропущено). - `api.runtime.stt.transcribeAudioFile(...)` залишається сумісним псевдонімом для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`. + `api.runtime.stt.transcribeAudioFile(...)` лишається сумісним псевдонімом для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`. - Генерування зображень. + Генерація зображень. ```typescript const result = await api.runtime.imageGeneration.generate({ @@ -310,7 +310,7 @@ register(api) { - Низькорівневі медіаутиліти. + Низькорівневі утиліти для медіа. ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -351,8 +351,8 @@ register(api) { `mutateConfigFile(...)` і `replaceConfigFile(...)` повертають значення `followUp`, наприклад `{ mode: "restart", requiresRestart: true, reason }`, - яке фіксує намір автора запису, не забираючи керування перезапуском у - Gateway. + яке фіксує намір записувача, не забираючи контроль перезапуску в + gateway. @@ -389,7 +389,7 @@ register(api) { - Розв’язання автентифікації моделей і провайдерів. + Розв’язання автентифікації моделі та провайдера. ```typescript const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); @@ -401,12 +401,28 @@ register(api) { - Розв’язання каталогу стану. + Розв’язання каталогу стану та сховище ключів на базі SQLite. ```typescript - const stateDir = api.runtime.state.resolveStateDir(); + const stateDir = api.runtime.state.resolveStateDir(process.env); + const store = api.runtime.state.openKeyedStore({ + namespace: "my-feature", + maxEntries: 200, + defaultTtlMs: 15 * 60_000, + }); + + await store.register("key-1", { value: "hello" }); + const value = await store.lookup("key-1"); + await store.consume("key-1"); + await store.clear(); ``` + Сховища ключів переживають перезапуски та ізольовані ідентифікатором Plugin, прив’язаним до середовища виконання. Обмеження: `maxEntries` на простір імен, 1 000 активних рядків на Plugin, JSON-значення до 64 КБ і необов’язкове завершення строку дії TTL. + + + Лише вбудовані plugins у цьому випуску. + + Фабрики інструментів пам’яті та CLI. @@ -419,9 +435,9 @@ register(api) { - Допоміжні засоби середовища виконання, специфічні для каналу (доступні, коли завантажено plugin каналу). + Допоміжні засоби середовища виконання, специфічні для каналу (доступні, коли завантажено Plugin каналу). - `api.runtime.channel.mentions` — це спільна поверхня політики вхідних згадок для вбудованих plugin каналів, які використовують ін’єкцію середовища виконання: + `api.runtime.channel.mentions` — це спільна поверхня політики вхідних згадок для вбудованих plugins каналів, які використовують ін’єкцію середовища виконання: ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -448,7 +464,7 @@ register(api) { }); ``` - Доступні допоміжні засоби згадок: + Доступні допоміжні засоби для згадок: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -456,14 +472,14 @@ register(api) { - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` навмисно не надає старіші сумісні допоміжні засоби `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. + `api.runtime.channel.mentions` навмисно не відкриває старі допоміжні засоби сумісності `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. ## Зберігання посилань на середовище виконання -Використовуйте `createPluginRuntimeStore`, щоб зберігати посилання на середовище виконання для використання поза зворотним викликом `register`: +Використовуйте `createPluginRuntimeStore`, щоб зберегти посилання на середовище виконання для використання поза зворотним викликом `register`: @@ -504,7 +520,7 @@ register(api) { -Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для рідкісних випадків, коли одному plugin навмисно потрібно більше ніж один слот середовища виконання. +Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для рідкісних випадків, коли одному Plugin навмисно потрібно більше ніж один слот середовища виконання. ## Інші поля верхнього рівня `api` @@ -512,29 +528,29 @@ register(api) { Окрім `api.runtime`, об’єкт API також надає: - Ідентифікатор plugin. + Ідентифікатор Plugin. - Відображувана назва plugin. + Відображувана назва Plugin. Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний). - Конфігурація, специфічна для plugin, з `plugins.entries..config`. + Конфігурація, специфічна для Plugin, з `plugins.entries..config`. - Журналювальник з областю видимості (`debug`, `info`, `warn`, `error`). + Обмежений за областю logger (`debug`, `info`, `warn`, `error`). - Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом. + Поточний режим завантаження; `"setup-runtime"` — це легковагове вікно запуску/налаштування перед повним entry. - Розв’язати шлях відносно кореня plugin. + Розв’язати шлях відносно кореня Plugin. ## Пов’язане -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і реєстр +- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і registry - [Точки входу SDK](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник підшляхів +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник subpath