diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 2243483b1..aa64371bf 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -1,186 +1,183 @@ --- read_when: - - Створення або налагодження нативних plugin OpenClaw - - Розуміння моделі можливостей plugin або меж власності - - Робота над конвеєром завантаження plugin або реєстром - - Реалізація runtime-хуків provider або channel plugin + - Створення або налагодження нативних плагінів OpenClaw + - Розуміння моделі можливостей плагінів або меж володіння + - Робота над конвеєром завантаження плагінів або реєстром + - Реалізація хуків часу виконання провайдера або плагінів каналів sidebarTitle: Internals -summary: 'Внутрішня будова plugin: модель можливостей, межі власності, контракти, конвеєр завантаження та допоміжні засоби runtime' -title: Внутрішня будова plugin +summary: 'Внутрішні механізми плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' +title: Внутрішні механізми плагінів x-i18n: - generated_at: "2026-04-07T18:46:39Z" + generated_at: "2026-04-07T20:12:37Z" model: gpt-5.4 provider: openai - source_hash: fc5a62710390dc6ad064b818222c1bb7609b3d076741f80bb5bbd9edb90342f1 + source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішня будова plugin +# Внутрішні механізми плагінів - Це **довідник із глибокої архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання plugin](/uk/tools/plugin) — посібник користувача - - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення plugin - - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей + Це **детальний довідник з архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна + - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями + - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації -Ця сторінка описує внутрішню архітектуру системи plugin в OpenClaw. +На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних plugin** всередині OpenClaw. Кожен -нативний plugin OpenClaw реєструється для одного або кількох типів можливостей: +Можливості — це публічна модель **нативних плагінів** в OpenClaw. Кожен +нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади plugin | -| ---------------------- | ---------------------------------------------- | ----------------------------------- | -| Текстова інференція | `api.registerProvider(...)` | `openai`, `anthropic` | -| Бекенд CLI для інференції | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Можливість | Метод реєстрації | Приклади плагінів | +| ---------------------- | ---------------------------------------------- | ------------------------------------ | +| Текстове виведення | `api.registerProvider(...)` | `openai`, `anthropic` | +| Бекенд виведення CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | | Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веботримання | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin, який не реєструє жодної можливості, але надає hooks, tools або -services, є **застарілим plugin лише з hooks**. Такий шаблон досі повністю підтримується. +Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або +сервіси, є **застарілим плагіном лише з хуками**. Цей шаблон досі повністю підтримується. ### Позиція щодо зовнішньої сумісності -Модель можливостей уже впроваджена в core і сьогодні використовується -вбудованими/нативними plugin, але сумісність із зовнішніми plugin усе ще -потребує вищої планки, ніж "це експортується, отже, це заморожено." +Модель можливостей уже інтегрована в ядро та використовується в комплектних/нативних плагінах +сьогодні, але сумісність із зовнішніми плагінами все ще потребує вищої планки, ніж «це +експортовано, отже це незмінно». Поточні рекомендації: -- **наявні зовнішні plugin:** зберігайте працездатність інтеграцій на основі hook; - вважайте це базовим рівнем сумісності -- **нові вбудовані/нативні plugin:** віддавайте перевагу явній реєстрації можливостей, - а не vendor-специфічним зверненням углиб або новим дизайнам лише з hooks -- **зовнішні plugin, що переходять на реєстрацію можливостей:** це дозволено, але - вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, - якщо документація явно не позначає контракт як стабільний +- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте + це базовим рівнем сумісності +- **нові комплектні/нативні плагіни:** надавайте перевагу явній реєстрації можливостей замість + вендор-специфічних звернень усередину або нових рішень лише з хуками +- **зовнішні плагіни, які переходять на реєстрацію можливостей:** це дозволено, але + вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, доки в документації явно не вказано, що контракт стабільний Практичне правило: -- API реєстрації можливостей — це бажаний напрям -- застарілі hooks залишаються найбезпечнішим шляхом без порушення сумісності - для зовнішніх plugin під час переходу -- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому - задокументованому контракту, а не випадковим експортам допоміжних засобів +- API реєстрації можливостей — це бажаний напрямок +- застарілі хуки залишаються найбезпечнішим шляхом без порушень сумісності для зовнішніх плагінів під час переходу +- не всі експортовані допоміжні підшляхи рівнозначні; надавайте перевагу вузькому документованому + контракту, а не випадковим експортам допоміжних засобів -### Форми plugin +### Форми плагінів -OpenClaw класифікує кожен завантажений plugin за формою на основі його -фактичної поведінки під час реєстрації, а не лише статичних метаданих: +OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної +поведінки реєстрації (а не лише статичних метаданих): - **plain-capability** -- реєструє рівно один тип можливості (наприклад, - plugin лише для provider, як-от `mistral`) + плагін лише провайдера, як-от `mistral`) - **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовою інференцією, мовленням, розумінням медіа та генерацією зображень) -- **hook-only** -- реєструє лише hooks (типізовані або кастомні), без можливостей, - tools, commands або services -- **non-capability** -- реєструє tools, commands, services або routes, але без - можливостей + `openai` володіє текстовим виведенням, мовленням, розумінням медіа та генерацією + зображень) +- **hook-only** -- реєструє лише хуки (типізовані або користувацькі), без можливостей, + інструментів, команд або сервісів +- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості -Використайте `openclaw plugins inspect `, щоб побачити форму plugin та -розподіл можливостей. Докладніше див. у [довідці CLI](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та розподіл +можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). -### Застарілі hooks +### Застарілі хуки -Hook `before_agent_start` залишається підтримуваним як шлях сумісності для -plugin лише з hooks. Наявні реальні застарілі plugin досі від нього залежать. +Хук `before_agent_start` залишається підтримуваним як шлях сумісності для +плагінів лише з хуками. Застарілі реальні плагіни все ще залежать від нього. -Напрям: +Напрямок: -- зберігати його працездатним +- зберігати його працездатність - документувати його як застарілий -- для перевизначення моделі/provider віддавати перевагу `before_model_resolve` -- для мутації prompt віддавати перевагу `before_prompt_build` -- видаляти лише після зниження реального використання і після того, як покриття - фікстурами доведе безпечність міграції +- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve` +- для мутації промпта надавати перевагу `before_prompt_build` +- видаляти лише після того, як реальне використання зменшиться, а покриття фікстурами доведе безпечність міграції ### Сигнали сумісності -Під час виконання `openclaw doctor` або `openclaw plugins inspect ` ви можете побачити -одну з таких міток: +Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити +одну з таких позначок: | Сигнал | Значення | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація успішно парситься, і plugin успішно розв'язуються | -| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація невалідна або plugin не вдалося завантажити | +| **config valid** | Конфігурація коректно розбирається, а плагіни успішно визначаються | +| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | +| **legacy warning** | Плагін використовує `before_agent_start`, який вважається застарілим | +| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | -Ні `hook-only`, ні `before_agent_start` не зламають ваш plugin сьогодні -- -`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці -сигнали також з'являються в `openclaw status --all` і `openclaw plugins doctor`. +Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш плагін -- +`hook-only` є рекомендаційним попередженням, а `before_agent_start` лише викликає попередження. Ці +сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури -Система plugin в OpenClaw має чотири шари: +Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить потенційні plugin у налаштованих шляхах, коренях workspace, - глобальних коренях extension і серед вбудованих extension. Під час виявлення спочатку - читаються нативні маніфести `openclaw.plugin.json` і підтримувані bundle-маніфести. + OpenClaw знаходить потенційні плагіни з налаштованих шляхів, коренів workspace, + глобальних коренів розширень і комплектних розширень. Виявлення спочатку читає нативні + маніфести `openclaw.plugin.json` та підтримувані маніфести пакетів. 2. **Увімкнення + валідація** - Core вирішує, чи виявлений plugin увімкнений, вимкнений, заблокований або - вибраний для ексклюзивного слота, такого як memory. -3. **Завантаження runtime** - Нативні plugin OpenClaw завантажуються в процес через jiti і реєструють - можливості в центральному реєстрі. Сумісні bundles нормалізуються у записи - реєстру без імпорту коду runtime. -4. **Використання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати tools, channels, налаштування provider, - hooks, HTTP routes, CLI commands і services. + Ядро вирішує, чи виявлений плагін увімкнено, вимкнено, заблоковано або + вибрано для ексклюзивного слота, такого як пам’ять. +3. **Завантаження часу виконання** + Нативні плагіни OpenClaw завантажуються в тому самому процесі через jiti та реєструють + можливості в центральному реєстрі. Сумісні пакети нормалізуються в + записи реєстру без імпорту коду часу виконання. +4. **Споживання поверхонь** + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування + провайдерів, хуки, HTTP-маршрути, команди CLI та сервіси. -Зокрема для CLI plugin виявлення кореневих команд розділене на дві фази: +Спеціально для CLI плагінів виявлення кореневих команд поділено на дві фази: -- метадані часу парсингу надходять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI plugin може залишатися лінивим і реєструватися під час першого виклику +- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })` +- справжній модуль CLI плагіна може залишатися лінивим і реєструватися при першому виклику -Це дає змогу тримати код CLI, який належить plugin, всередині plugin і водночас дозволяє OpenClaw -резервувати імена кореневих команд до початку парсингу. +Це дозволяє тримати CLI-код, що належить плагіну, всередині плагіна, і при цьому дає OpenClaw +можливість резервувати імена кореневих команд до розбору. -Важлива межа проєктування: +Важлива межа дизайну: -- виявлення + валідація config мають працювати на основі **метаданих manifest/schema** - без виконання коду plugin -- нативна поведінка runtime надходить із шляху `register(api)` модуля plugin +- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** + без виконання коду плагіна +- нативна поведінка часу виконання надходить із шляху `register(api)` модуля плагіна -Такий поділ дозволяє OpenClaw валідовувати config, пояснювати відсутні/вимкнені plugin і -будувати підказки для UI/schema ще до повної активації runtime. +Цей поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки UI/схеми до того, як повне середовище часу виконання стане активним. -### Channel plugin і спільний tool повідомлень +### Плагіни каналів і спільний інструмент message -Channel plugin не потрібно реєструвати окремий tool для надсилання/редагування/реакцій -для звичайних дій у чаті. OpenClaw підтримує один спільний tool `message` у core, а -channel plugin відповідають за специфічне для каналу виявлення та виконання за ним. +Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для +звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у ядрі, а +плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. Поточна межа така: -- core відповідає за спільний host tool `message`, підключення до prompt, - облік сесій/потоків і диспетчеризацію виконання -- channel plugin відповідають за виявлення дій у межах області, виявлення - можливостей і будь-які фрагменти schema, специфічні для каналу -- channel plugin відповідають за граматику розмови сесії, специфічну для provider, - зокрема за те, як conversation id кодують thread id або успадковуються від батьківських conversations -- channel plugin виконують фінальну дію через свій action adapter +- ядро володіє спільним хостом інструмента `message`, прив’язкою промптів, обліком + сесій/гілок і диспетчеризацією виконання +- плагіни каналів володіють виявленням дій у межах області, виявленням можливостей + і будь-якими фрагментами схеми, специфічними для каналу +- плагіни каналів володіють граматикою розмови сесії, специфічною для провайдера, наприклад + тим, як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов +- плагіни каналів виконують фінальну дію через свій адаптер дій -Для channel plugin поверхнею SDK є -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик -виявлення дозволяє plugin повертати видимі дії, можливості та внески в schema -разом, щоб ці частини не розходилися. +Для плагінів каналів поверхнею SDK є +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення +дозволяє плагіну разом повертати свої видимі дії, можливості та +внески до схеми, щоб ці частини не розходилися. -Core передає до цього кроку виявлення runtime-область. Важливі поля: +Ядро передає область часу виконання в цей крок виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -191,124 +188,123 @@ Core передає до цього кроку виявлення runtime-обл - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для context-sensitive plugin. Канал може приховувати або показувати -дії повідомлень залежно від активного облікового запису, поточної кімнати/потоку/повідомлення або -довіреної ідентичності запитувача без жорстко закодованих розгалужень, специфічних для каналу, -у core tool `message`. +Це важливо для контекстно-залежних плагінів. Канал може приховувати або показувати +дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або +довіреної особи відправника-запитувача без жорстко закодованих гілок у +інструменті ядра `message`. -Саме тому зміни маршрутизації embedded-runner усе ще є роботою plugin: runner -відповідає за передавання поточної ідентичності чату/сесії в межу виявлення plugin, щоб -спільний tool `message` показував правильну поверхню, що належить каналу, -для поточного ходу. +Ось чому зміни маршрутизації embedded-runner усе ще є роботою плагіна: runner +відповідає за пересилання поточної ідентичності чату/сесії в межу виявлення плагіна, +щоб спільний інструмент `message` показував правильну поверхню каналу, що належить +поточному ходу. -Для допоміжних засобів виконання, що належать каналу, вбудовані plugin мають тримати runtime -виконання всередині власних модулів extension. Core більше не володіє runtime -message-action для Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. -Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані -plugin мають імпортувати свій локальний код runtime безпосередньо зі своїх -модулів extension. +Для допоміжних засобів виконання, що належать каналу, комплектні плагіни повинні тримати +середовище виконання всередині власних модулів розширення. Ядро більше не володіє +середовищами виконання дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і комплектні +плагіни повинні імпортувати свій локальний код часу виконання безпосередньо зі своїх +модулів розширення. -Та сама межа застосовується і до SDK seam, названих на честь provider, загалом: -core не повинен імпортувати channel-специфічні convenience barrel для Slack, Discord, Signal, -WhatsApp або подібних extension. Якщо core потрібна певна поведінка, або -використовуйте власний barrel `api.ts` / `runtime-api.ts` відповідного вбудованого plugin, -або підніміть потребу в вузьку узагальнену можливість у спільному SDK. +Та сама межа застосовується до загалом вендор-іменованих швів SDK: ядро не повинно +імпортувати зручні барабани, специфічні для каналів Slack, Discord, Signal, +WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, воно має або +використовувати власний барабан `api.ts` / `runtime-api.ts` комплектного плагіна, або підняти цю потребу +до вузької загальної можливості в спільному SDK. -Зокрема для polls існують два шляхи виконання: +Для опитувань зокрема є два шляхи виконання: -- `outbound.sendPoll` — спільний базовий варіант для каналів, які відповідають загальній - моделі опитувань -- `actions.handleAction("poll")` — бажаний шлях для channel-специфічної - семантики опитувань або додаткових параметрів опитування +- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну + модель опитувань +- `actions.handleAction("poll")` — бажаний шлях для семантики опитувань, специфічної для каналу, або додаткових параметрів опитування -Тепер core відкладає спільний парсинг опитувань до моменту, коли dispatch опитування plugin -відхилить дію, щоб обробники опитувань, що належать plugin, могли приймати -channel-специфічні поля опитувань без блокування спочатку загальним парсером poll. +Тепер ядро відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна +відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати поля опитування, +специфічні для каналу, не блокуючись спочатку загальним парсером опитувань. Повну послідовність запуску див. у [Конвеєр завантаження](#load-pipeline). -## Модель власності можливостей +## Модель володіння можливостями -OpenClaw розглядає нативний plugin як межу власності для **компанії** або -**функції**, а не як набір не пов'язаних між собою інтеграцій. +OpenClaw розглядає нативний плагін як межу володіння для **компанії** або +**функції**, а не як набір не пов’язаних інтеграцій. Це означає: -- plugin компанії зазвичай має володіти всіма OpenClaw-поверхнями цієї компанії -- plugin функції зазвичай має володіти повною поверхнею функції, яку він вводить -- channels мають споживати спільні можливості core замість того, щоб - ситуативно перевпроваджувати поведінку provider +- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії +- плагін функції зазвичай має володіти повною поверхнею функції, яку він вводить +- канали мають споживати спільні можливості ядра замість того, щоб повторно реалізовувати + поведінку провайдера ad hoc Приклади: -- вбудований plugin `openai` володіє поведінкою provider моделей OpenAI і поведінкою OpenAI для +- комплектний плагін `openai` володіє поведінкою провайдера моделей OpenAI і поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень -- вбудований plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs -- вбудований plugin `microsoft` володіє поведінкою мовлення Microsoft -- вбудований plugin `google` володіє поведінкою provider моделей Google, а також поведінкою Google для - розуміння медіа + генерації зображень + вебпошуку -- вбудований plugin `firecrawl` володіє поведінкою веботримання Firecrawl -- вбудовані plugin `minimax`, `mistral`, `moonshot` і `zai` володіють своїми +- комплектний плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs +- комплектний плагін `microsoft` володіє поведінкою мовлення Microsoft +- комплектний плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google для + розуміння медіа + генерації зображень + веб-пошуку +- комплектний плагін `firecrawl` володіє поведінкою веб-отримання Firecrawl +- комплектні плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми бекендами розуміння медіа -- вбудований plugin `qwen` володіє текстовою поведінкою provider Qwen, а також - поведінкою розуміння медіа і генерації відео -- plugin `voice-call` — це plugin функції: він володіє транспортом дзвінків, tools, - CLI, routes і мостом медіапотоків Twilio, але споживає спільні можливості мовлення, - а також транскрипції і голосу в реальному часі замість прямого імпорту vendor plugin +- комплектний плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також + поведінкою розуміння медіа та генерації відео +- плагін `voice-call` — це плагін функції: він володіє транспортом дзвінків, інструментами, + CLI, маршрутами та мостом медіапотоків Twilio, але споживає спільні можливості мовлення, + а також транскрипції та голосу в реальному часі замість прямого імпорту вендорних плагінів Бажаний кінцевий стан: -- OpenAI живе в одному plugin, навіть якщо він охоплює текстові моделі, мовлення, зображення і +- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший vendor може зробити те саме для власної області -- channels не турбує, який vendor plugin володіє provider; вони споживають - спільний контракт можливості, який надає core +- інший вендор може робити так само для власної поверхні +- каналам не важливо, який плагін вендора володіє провайдером; вони споживають + спільний контракт можливості, який надає ядро Ось ключова відмінність: -- **plugin** = межа власності -- **можливість** = контракт core, який можуть реалізовувати або споживати кілька plugin +- **plugin** = межа володіння +- **capability** = контракт ядра, який кілька плагінів можуть реалізовувати або споживати -Тому, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не -"який provider має жорстко закодувати обробку відео?" Перше запитання — "яким є -контракт core для можливості відео?" Щойно такий контракт існує, vendor plugin -можуть реєструватися для нього, а channel/feature plugin можуть його споживати. +Тож якщо OpenClaw додає нову доменну область, таку як відео, перше запитання не +«який провайдер має жорстко закодувати обробку відео?» Перше запитання — +«який контракт можливості відео в ядрі?» Щойно цей контракт з’явиться, вендорні плагіни +зможуть реєструватися для нього, а плагіни каналів/функцій — споживати його. -Якщо можливість ще не існує, зазвичай правильний крок такий: +Якщо можливості ще не існує, зазвичай правильний крок такий: -1. визначити відсутню можливість у core -2. відкрити її через API/runtime plugin у типізований спосіб -3. під'єднати channels/features до цієї можливості -4. дозволити vendor plugin реєструвати реалізації +1. визначити відсутню можливість у ядрі +2. відкрити її через API/середовище часу виконання плагіна у типізований спосіб +3. підключити канали/функції до цієї можливості +4. дозволити вендорним плагінам реєструвати реалізації -Це зберігає явну власність і водночас уникає поведінки core, що залежить від -одного vendor або одноразового plugin-специфічного шляху коду. +Це зберігає явне володіння, водночас уникаючи поведінки ядра, яка залежить від +одного вендора або одноразового коду шляху, специфічного для плагіна. ### Шарування можливостей -Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: +Використовуйте цю ментальну модель, коли вирішуєте, де має належати код: -- **шар можливостей core**: спільна оркестрація, політика, fallback, правила - злиття config, семантика доставки та типізовані контракти -- **шар vendor plugin**: vendor-специфічні API, auth, каталоги моделей, синтез мовлення, - генерація зображень, майбутні відеобекенди, endpoint використання -- **шар channel/feature plugin**: інтеграції Slack/Discord/voice-call/etc., - які споживають можливості core і представляють їх на певній поверхні +- **шар можливостей ядра**: спільна оркестрація, політика, резервний шлях, правила + злиття конфігурації, семантика доставки та типізовані контракти +- **шар вендорного плагіна**: вендор-специфічні API, автентифікація, каталоги моделей, синтез + мовлення, генерація зображень, майбутні бекенди відео, кінцеві точки використання +- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, + яка споживає можливості ядра та представляє їх на поверхні Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канал +- ядро володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями та доставкою в канал - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний runtime TTS для телефонії +- `voice-call` споживає допоміжний засіб часу виконання TTS для телефонії -Той самий шаблон слід віддавати перевагу і для майбутніх можливостей. +Той самий шаблон слід віддавати перевагу для майбутніх можливостей. -### Приклад plugin компанії з кількома можливостями +### Приклад плагіна компанії з кількома можливостями -Plugin компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні +Плагін компанії має виглядати цілісно ззовні. Якщо в OpenClaw є спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веботримання та вебпошуку, -vendor може володіти всіма своїми поверхнями в одному місці: +генерації зображень, генерації відео, веб-отримання та веб-пошуку, +вендор може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -362,222 +358,223 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви helper. Важлива форма: +Важливі не точні назви допоміжних засобів. Важлива форма: -- один plugin володіє поверхнею vendor -- core все одно володіє контрактами можливостей -- channels і feature plugin споживають helper `api.runtime.*`, а не код vendor -- контрактні тести можуть перевіряти, що plugin зареєстрував можливості, якими +- один плагін володіє поверхнею вендора +- ядро все одно володіє контрактами можливостей +- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора +- тести контрактів можуть перевіряти, що плагін зареєстрував можливості, якими він заявляє, що володіє ### Приклад можливості: розуміння відео OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. Та сама модель власності застосовується і тут: +можливість. До неї застосовується та сама модель володіння: -1. core визначає контракт media-understanding -2. vendor plugin реєструють `describeImage`, `transcribeAudio` і - `describeVideo`, де це застосовно -3. channels і feature plugin споживають спільну поведінку core, а не - напряму під'єднуються до коду vendor +1. ядро визначає контракт розуміння медіа +2. вендорні плагіни реєструють `describeImage`, `transcribeAudio` і + `describeVideo` за потреби +3. канали та плагіни функцій споживають спільну поведінку ядра, а не + підключаються безпосередньо до коду вендора -Це дозволяє не вбудовувати припущення одного provider щодо відео в core. Plugin володіє -поверхнею vendor; core володіє контрактом можливості та поведінкою fallback. +Це дозволяє не вбудовувати припущення одного провайдера щодо відео в ядро. Плагін володіє +поверхнею вендора; ядро володіє контрактом можливості та резервною поведінкою. -Генерація відео вже використовує ту саму послідовність: core володіє типізованим -контрактом можливості та helper runtime, а vendor plugin реєструють -реалізації `api.registerVideoGenerationProvider(...)` для неї. +Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим +контрактом можливості та допоміжним засобом часу виконання, а вендорні плагіни реєструють +реалізації `api.registerVideoGenerationProvider(...)` для нього. -Потрібен конкретний контрольний список впровадження? Див. -[Capability Cookbook](/uk/plugins/architecture). +Потрібен конкретний контрольний список розгортання? Див. +[Cookbook можливостей](/uk/plugins/architecture). -## Контракти та контроль +## Контракти та примусове забезпечення -Поверхня API plugin навмисно типізована і централізована в +Поверхня API плагінів навмисно типізована та централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -helper runtime, на які plugin може покладатися. +допоміжні засоби часу виконання, на які може покладатися плагін. Чому це важливо: -- автори plugin отримують один стабільний внутрішній стандарт -- core може відхиляти дубльовану власність, наприклад коли два plugin реєструють один і той самий provider id -- під час запуску можна показувати діагностику з конкретними діями для - некоректної реєстрації -- контрактні тести можуть контролювати власність вбудованих plugin і запобігати тихому дрейфу +- автори плагінів отримують один стабільний внутрішній стандарт +- ядро може відхиляти дубльоване володіння, наприклад, коли два плагіни реєструють той самий + id провайдера +- під час запуску можна показувати зрозумілу діагностику для некоректної реєстрації +- тести контрактів можуть забезпечувати володіння комплектних плагінів і запобігати тихому дрейфу -Є два шари контролю: +Є два шари забезпечення: -1. **контроль реєстрації під час runtime** - Реєстр plugin валідовує реєстрації під час завантаження plugin. Приклади: - дубльовані id provider, дубльовані id provider мовлення та некоректні - реєстрації породжують діагностику plugin замість невизначеної поведінки. -2. **контрактні тести** - Вбудовані plugin захоплюються в контрактні реєстри під час тестових запусків, щоб - OpenClaw міг явно перевіряти власність. Сьогодні це використовується для model - providers, speech providers, web-search providers і власності вбудованих реєстрацій. +1. **забезпечення реєстрації часу виконання** + Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: + дубльовані id провайдерів, дубльовані id провайдерів мовлення та некоректні + реєстрації призводять до діагностики плагіна, а не до невизначеної поведінки. +2. **тести контрактів** + Комплектні плагіни фіксуються в реєстрах контрактів під час запуску тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для моделей + провайдерів, провайдерів мовлення, провайдерів веб-пошуку та володіння комплектною реєстрацією. -Практичний ефект у тому, що OpenClaw наперед знає, який plugin якою -поверхнею володіє. Це дозволяє core і channels безшовно поєднуватися, оскільки -власність оголошена, типізована і піддається тестуванню, а не є неявною. +Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою +поверхнею володіє. Це дозволяє ядру та каналам безшовно поєднуватися, оскільки володіння +оголошене, типізоване та перевірюване, а не неявне. -### Що має входити до контракту +### Що має належати контракту -Хороші контракти plugin: +Хороші контракти плагінів: - типізовані -- малі +- невеликі - специфічні для можливості -- належать core -- повторно використовуються кількома plugin -- можуть споживатися channels/features без знання про vendor +- належать ядру +- придатні до повторного використання кількома плагінами +- споживані каналами/функціями без знання про вендора -Погані контракти plugin: +Погані контракти плагінів: -- vendor-специфічна політика, прихована в core -- одноразові лазівки для plugin, які обходять реєстр -- код каналу, який напряму лізе у vendor-реалізацію -- спеціальні runtime-об'єкти, що не входять до `OpenClawPluginApi` або +- вендор-специфічна політика, прихована в ядрі +- одноразові обхідні шляхи для плагіна, які оминають реєстр +- код каналу, що звертається прямо до реалізації вендора +- ad hoc об’єкти часу виконання, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, піднімайте рівень абстракції: спочатку визначте можливість, а -потім дозволяйте plugin підключатися до неї. +Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім +дозвольте плагінам підключатися до неї. ## Модель виконання -Нативні plugin OpenClaw працюють **у межах процесу** разом із Gateway. Вони не -ізольовані. Завантажений нативний plugin має ту саму межу довіри на рівні процесу, -що й код core. +Нативні плагіни OpenClaw працюють **в тому самому процесі**, що й Gateway. Вони не +ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й +код ядра. Наслідки: -- нативний plugin може реєструвати tools, network handlers, hooks і services -- помилка нативного plugin може призвести до аварії gateway або його дестабілізації -- зловмисний нативний plugin еквівалентний довільному виконанню коду всередині +- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси +- помилка нативного плагіна може призвести до аварійного завершення або дестабілізації gateway +- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні bundles безпечніші за замовчуванням, тому що зараз OpenClaw розглядає їх -як набори метаданих/контенту. У поточних релізах це переважно означає -вбудовані Skills. +Сумісні пакети безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх +як пакети метаданих/вмісту. У поточних випусках це переважно означає комплектні +Skills. -Використовуйте allowlist і явні шляхи встановлення/завантаження для невбудованих plugin. Розглядайте -workspace plugin як код для часу розробки, а не як бойові типові значення. +Використовуйте allowlist і явні шляхи встановлення/завантаження для некомплектних плагінів. Розглядайте +workspace-плагіни як код для етапу розробки, а не як типові значення для production. -Для назв пакетів у workspace-вбудованих plugin зберігайте прив'язку id plugin у npm-імені: -`@openclaw/` за замовчуванням або затверджений типізований суфікс, наприклад +Для назв пакетів комплектних workspace тримайте id плагіна прив’язаним до npm-імені: +`@openclaw/` за замовчуванням або зі схваленим типізованим суфіксом, таким як `-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли -пакет навмисно відкриває вужчу роль plugin. +пакет навмисно надає вужчу роль плагіна. Важлива примітка щодо довіри: -- `plugins.allow` довіряє **id plugin**, а не походженню джерела. -- workspace plugin з тим самим id, що й вбудований plugin, навмисно затіняє - вбудовану копію, коли цей workspace plugin увімкнено/додано до allowlist. +- `plugins.allow` довіряє **id плагінів**, а не походженню джерела. +- Workspace-плагін з тим самим id, що й комплектний плагін, навмисно затіняє + комплектну копію, коли цей workspace-плагін увімкнено/внесено до allowlist. - Це нормально й корисно для локальної розробки, тестування патчів і hotfix. ## Межа експорту -OpenClaw експортує можливості, а не зручні реалізаційні helper. +OpenClaw експортує можливості, а не зручні допоміжні реалізації. -Залишайте реєстрацію можливостей публічною. Скорочуйте експорти helper, які не є контрактом: +Зберігайте публічність реєстрації можливостей. Прибирайте непублічні допоміжні експорти: -- допоміжні підшляхи, специфічні для вбудованих plugin -- підшляхи plumbing runtime, не призначені як публічний API -- vendor-специфічні convenience helper -- helper налаштування/onboarding, які є деталями реалізації +- підшляхи допоміжних засобів, специфічні для комплектного плагіна +- підшляхи інфраструктури часу виконання, які не призначені як публічний API +- вендор-специфічні зручні допоміжні засоби +- допоміжні засоби налаштування/онбордингу, які є деталями реалізації -Деякі підшляхи helper вбудованих plugin усе ще залишаються в згенерованій карті -експортів SDK для сумісності та підтримки вбудованих plugin. Поточні приклади: +Деякі підшляхи допоміжних засобів комплектних плагінів усе ще залишаються в згенерованій карті експорту SDK +заради сумісності та підтримки комплектних плагінів. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і кілька seam `plugin-sdk/matrix*`. Розглядайте їх як +`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для -нових сторонніх plugin. +нових сторонніх плагінів. ## Конвеєр завантаження Під час запуску OpenClaw приблизно робить таке: -1. знаходить корені потенційних plugin -2. читає нативні або сумісні bundle-маніфести та метадані package -3. відхиляє небезпечні кандидати -4. нормалізує config plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +1. виявляє корені потенційних плагінів +2. читає нативні або сумісні маніфести пакетів і метадані пакетів +3. відхиляє небезпечних кандидатів +4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає стан увімкнення для кожного кандидата +5. вирішує, чи вмикати кожного кандидата 6. завантажує увімкнені нативні модулі через jiti -7. викликає hooks нативного `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру plugin -8. відкриває реєстр для команд/поверхонь runtime +7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів +8. відкриває реєстр для команд/поверхонь часу виконання -`activate` — це застарілий псевдонім для `register` — loader знаходить будь-який із них (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі комплектні плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. -Запобіжні перевірки відбуваються **до** виконання runtime. Кандидати блокуються, -якщо entry виходить за межі кореня plugin, шлях доступний на запис для всіх або -власність шляху виглядає підозріло для невбудованих plugin. +Перевірки безпеки відбуваються **до** виконання під час часу виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня плагіна, шлях доступний для запису всім, або +власність шляху виглядає підозріло для некомплектних плагінів. ### Поведінка manifest-first Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: -- ідентифікувати plugin -- знаходити оголошені channels/skills/schema config або можливості bundle -- валідовувати `plugins.entries..config` -- доповнювати labels/placeholders у Control UI +- ідентифікувати плагін +- виявити оголошені канали/Skills/схему конфігурації або можливості пакета +- перевірити `plugins.entries..config` +- доповнити мітки/плейсхолдери Control UI - показувати метадані встановлення/каталогу -Для нативних plugin модуль runtime є частиною data plane. Він реєструє -фактичну поведінку, таку як hooks, tools, commands або потоки provider. +Для нативних плагінів модуль часу виконання є частиною data plane. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -### Що кешує loader +### Що кешує завантажувач -OpenClaw підтримує короткоживучі кеші в межах процесу для: +OpenClaw тримає короткі внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів plugin +- реєстрів завантажених плагінів -Ці кеші зменшують ривкове навантаження під час запуску та повторних команд. Їх -доречно розглядати як короткоживучі кеші продуктивності, а не як сховище. +Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як постійне зберігання. Примітка щодо продуктивності: -- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. - Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugin не змінюють випадкові глобальні об'єкти core напряму. Вони -реєструються в центральному реєстрі plugin. +Завантажені плагіни не змінюють напряму випадкові глобальні змінні ядра. Вони реєструються +в центральному реєстрі плагінів. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, статус, діагностика) -- tools -- застарілі hooks і типізовані hooks -- channels -- providers -- handlers Gateway RPC -- HTTP routes +- записи плагінів (ідентичність, джерело, походження, стан, діагностика) +- інструменти +- застарілі хуки та типізовані хуки +- канали +- провайдери +- обробники Gateway RPC +- HTTP-маршрути - реєстратори CLI -- фонові services -- commands, що належать plugin +- фонові сервіси +- команди, що належать плагіну -Після цього можливості core читають із цього реєстру замість прямої взаємодії -з модулями plugin. Це зберігає односторонність завантаження: +Потім функції ядра читають із цього реєстру замість прямої взаємодії з модулями плагінів. +Це зберігає односторонність завантаження: -- модуль plugin -> реєстрація в реєстрі -- runtime core -> споживання реєстру +- модуль плагіна -> реєстрація в реєстрі +- середовище часу виконання ядра -> споживання реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: "читати реєстр", а не "створювати окремі special-case для кожного модуля plugin". +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна +лише одна точка інтеграції: «читати реєстр», а не «обробляти особливі випадки кожного +модуля плагіна». -## Callback-и прив'язки conversation +## Колбеки прив’язки розмов -Plugin, які прив'язують conversation, можуть реагувати, коли схвалення вирішено. +Плагіни, які прив’язують розмову, можуть реагувати, коли погодження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після -схвалення або відхилення запиту на прив'язку: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як +запит на прив’язку буде схвалено або відхилено: ```ts export default { @@ -597,27 +594,27 @@ export default { }; ``` -Поля callback payload: +Поля корисного навантаження колбека: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: розв'язана прив'язка для схвалених запитів -- `request`: підсумок оригінального запиту, підказка від'єднання, id відправника та - метадані conversation +- `binding`: визначена прив’язка для схвалених запитів +- `request`: початкове зведення запиту, підказка від’єднання, id відправника та + метадані розмови -Цей callback має лише повідомний характер. Він не змінює, кому дозволено -прив'язувати conversation, і виконується після завершення обробки схвалення в core. +Цей колбек призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати +розмову, і запускається після завершення обробки погодження ядром. -## Runtime-hooks provider +## Хуки часу виконання провайдера -Тепер plugin provider мають два шари: +Тепер плагіни провайдерів мають два шари: -- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth provider - до завантаження runtime, `channelEnvVars` для дешевого пошуку env/setup каналу - до завантаження runtime, а також `providerAuthChoices` для дешевих - labels onboarding/auth-choice і метаданих прапорців CLI до завантаження runtime -- hooks часу config: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- hooks runtime: `normalizeModelId`, `normalizeTransport`, +- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера + до завантаження часу виконання, `channelEnvVars` для дешевого пошуку env/setup каналу + до завантаження часу виконання, а також `providerAuthChoices` для дешевого онбордингу/вибору автентифікації, + міток і метаданих прапорців CLI до завантаження часу виконання +- хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- хуки часу виконання: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -637,88 +634,88 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw як і раніше володіє загальним циклом агента, failover, обробкою transcript і -політикою tools. Ці hooks є поверхнею розширення для поведінки provider без -потреби в повністю кастомному транспорті інференції. +OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки — поверхня розширення для специфічної поведінки провайдера без +потреби в повністю кастомному транспорті виведення. -Використовуйте manifest `providerAuthEnvVars`, коли provider має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime plugin. -Використовуйте manifest `providerAuthChoices`, коли поверхні onboarding/auth-choice CLI -мають знати id варіанта provider, labels груп і просте підключення auth одним прапорцем -без завантаження runtime provider. Зберігайте `envVars` runtime provider для -підказок для операторів, таких як labels onboarding або змінні налаштування OAuth -client-id/client-secret. +Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові дані на основі env, +які загальні шляхи auth/status/model-picker повинні бачити без завантаження середовища +часу виконання плагіна. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI онбордингу/вибору auth +мають знати про id вибору провайдера, мітки груп і просте +підключення auth одним прапорцем без завантаження середовища часу виконання провайдера. Зберігайте `envVars` у середовищі +часу виконання провайдера для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування +OAuth client-id/client-secret. -Використовуйте manifest `channelEnvVars`, коли канал має auth або setup на основі env, -які загальні шляхи shell-env fallback, перевірок config/status або prompts setup -мають бачити без завантаження runtime каналу. +Використовуйте `channelEnvVars` у маніфесті, коли канал має auth або setup, що керуються env, +які загальний shell-env fallback, перевірки config/status або підказки setup +повинні бачити без завантаження середовища часу виконання каналу. -### Порядок hook і спосіб використання +### Порядок і використання хуків -Для plugin моделей/provider OpenClaw викликає hooks приблизно в такому порядку. -Стовпчик "Коли використовувати" — це швидкий орієнтир для вибору. +Для плагінів моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий посібник для вибору рішення. -| # | Hook | Що він робить | Коли використовувати | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує config provider у `models.providers` під час генерації `models.json` | Provider володіє каталогом або типовими значеннями base URL | -| 2 | `applyConfigDefaults` | Застосовує типові значення config, що належать provider, під час матеріалізації config | Типові значення залежать від режиму auth, env або семантики сімейства моделей provider | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не hook plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Provider володіє очищенням псевдонімів до канонічного розв'язання моделі | -| 4 | `normalizeTransport` | Нормалізує provider-family `api` / `baseUrl` перед загальним складанням моделі | Provider володіє очищенням транспорту для кастомних id provider у тій самій transport family | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв'язанням runtime/provider | Provider потребує очищення config, яке має жити разом із plugin; вбудовані helper для сімейства Google також підстраховують підтримувані записи config Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи native streaming-usage до config providers | Provider потребує виправлень метаданих native streaming usage, що залежать від endpoint | -| 7 | `resolveConfigApiKey` | Розв'язує env-marker auth для config providers до завантаження runtime auth | Provider має власне розв'язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований resolver env-marker AWS | -| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або auth на основі config без збереження plaintext | Provider може працювати із synthetic/local marker credential | -| 9 | `resolveExternalAuthProfiles` | Накладає профілі зовнішньої auth, що належать provider; типове `persistence` — `runtime-only` для creds CLI/app | Provider повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic placeholder profile порівняно з auth на основі env/config | Provider зберігає synthetic placeholder profiles, які не мають переважати | -| 11 | `resolveDynamicModel` | Синхронний fallback для model id provider, яких ще немає в локальному реєстрі | Provider приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Provider потребує мережевих метаданих перед розв'язанням невідомих id | -| 13 | `normalizeResolvedModel` | Фінальний rewrite перед тим, як embedded runner використає розв'язану модель | Provider потребує rewrite транспорту, але все ще використовує core transport | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для vendor-моделей за іншим сумісним transport | Provider розпізнає власні моделі на proxy transport без перехоплення ролі provider | -| 15 | `capabilities` | Метадані transcript/tooling, що належать provider і використовуються спільною логікою core | Provider потрібні особливості transcript/provider-family | -| 16 | `normalizeToolSchemas` | Нормалізує schema tools до того, як їх побачить embedded runner | Provider потребує очищення schema для transport-family | -| 17 | `inspectToolSchemas` | Показує diagnostics schema, що належать provider, після нормалізації | Provider хоче попередження щодо keyword без навчання core правилам, специфічним для provider | -| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Provider потребує tagged reasoning/final output замість native fields | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних обгорток опцій stream | Provider потребує типових параметрів запиту або очищення параметрів для конкретного provider | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream кастомним transport | Provider потребує кастомного wire protocol, а не лише wrapper | -| 21 | `wrapStreamFn` | Обгортка stream після застосування загальних wrapper | Provider потребує wrapper для headers/body/model compat без кастомного transport | -| 22 | `resolveTransportTurnState` | Додає native headers або metadata на один хід transport | Provider хоче, щоб загальні transport надсилали native turn identity provider | -| 23 | `resolveWebSocketSessionPolicy` | Додає native headers WebSocket або політику cool-down сесії | Provider хоче, щоб загальні transport WS налаштовували headers сесії або політику fallback | -| 24 | `formatApiKey` | Форматер auth-profile: збережений profile стає runtime-рядком `apiKey` | Provider зберігає додаткові метадані auth і потребує кастомної форми runtime token | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для кастомних endpoint refresh або політики помилок refresh | Provider не вписується у спільні refreshers `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли не вдається OAuth refresh | Provider потребує власних рекомендацій з ремонту auth після помилки refresh | -| 27 | `matchesContextOverflowError` | Matcher переповнення контекстного вікна, що належить provider | Provider має сирі помилки переповнення, які пропустять загальні heuristics | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить provider | Provider може зіставляти сирі API/transport помилки з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul provider | Provider потребує gating TTL кешу, специфічного для proxy | -| 30 | `buildMissingAuthMessage` | Замінює загальне повідомлення відновлення для відсутньої auth | Provider потребує provider-специфічної підказки для відновлення після відсутності auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей з необов'язковою користувацькою підказкою про помилку | Provider потребує приховати застарілі upstream-рядки або замінити їх підказкою vendor | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після discovery | Provider потребує синтетичних рядків прямої сумісності в `models list` і picker-ах | -| 33 | `isBinaryThinking` | Перемикач reasoning on/off для provider з binary-thinking | Provider підтримує лише бінарне thinking on/off | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Provider хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Provider володіє типовою політикою `/think` для сімейства моделей | -| 36 | `isModernModelRef` | Matcher сучасних моделей для фільтрів live profile і вибору smoke | Provider володіє зіставленням бажаних моделей для live/smoke | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key безпосередньо перед інференцією | Provider потребує обміну token або короткоживучих облікових даних запиту | -| 38 | `resolveUsageAuth` | Розв'язує credentials використання/білінгу для `/usage` і пов'язаних поверхонь status | Provider потребує кастомного парсингу token використання/квот або інших credentials використання | -| 39 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квот, специфічні для provider, після розв'язання auth | Provider потребує власний endpoint використання або parser payload | -| 40 | `createEmbeddingProvider` | Створює adapter embeddings, що належить provider, для memory/search | Поведінка embeddings для memory має належати plugin provider | -| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою transcript для provider | Provider потребує кастомну політику transcript (наприклад, видалення блоків thinking) | -| 42 | `sanitizeReplayHistory` | Перезаписує історію replay після загального очищення transcript | Provider потребує provider-специфічні rewrite replay понад спільні helper compaction | -| 43 | `validateReplayTurns` | Фінальна валідація або зміна форми turn replay перед embedded runner | Transport provider потребує суворішої валідації ходів після загальної санітизації | -| 44 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать provider | Provider потребує телеметрію або власний стан, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | +| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не є хуком плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id до пошуку | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення середовища часу виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; комплектні допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігураційних провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевими точками | +| 7 | `resolveConfigApiKey` | Визначає env-marker auth для конфігураційних провайдерів до завантаження auth часу виконання | Провайдер має власне визначення API-key через env-marker; `amazon-bedrock` також має вбудований AWS env-marker resolver тут | +| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або заснований на config auth без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове `persistence` — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних placeholder-профілів порівняно з auth на основі env/config | Провайдер зберігає синтетичні placeholder-профілі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний fallback для model id, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний warm-up, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для вендорних моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспорті, не перебираючи на себе провайдера | +| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості сімейства транскриптів/провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт виходу reasoning | Провайдеру потрібен tagged reasoning/final output замість native полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані для окремого ходу транспорту | Провайдер хоче, щоб загальні транспорти надсилали власну для провайдера ідентичність ходу | +| 23 | `resolveWebSocketSessionPolicy` | Додає native WebSocket-заголовки або політику cool-down сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику fallback | +| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` під час виконання | Провайдер зберігає додаткові auth-метадані та потребує користувацької форми токена часу виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилок оновлення | Провайдер не підходить під спільні оновлювачі `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка відновлення, що додається, коли оновлення OAuth не вдається | Провайдеру потрібні власні поради щодо відновлення auth після помилки оновлення | +| 27 | `matchesContextOverflowError` | Матчер переповнення context window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі API/транспортні помилки з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутності auth | Провайдеру потрібна власна підказка відновлення при відсутності auth | +| 31 | `suppressBuiltInModel` | Приглушення застарілої upstream-моделі плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і селекторах | +| 33 | `isBinaryThinking` | Перемикач on/off reasoning для провайдерів із binary thinking | Провайдер надає лише двійкове thinking on/off | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | +| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 36 | `isModernModelRef` | Матчер modern-model для live-фільтрів профілів і вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ часу виконання безпосередньо перед виведенням | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 38 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібний користувацький розбір токена usage/quota або інші облікові дані usage | +| 39 | `fetchUsageSnapshot` | Отримує і нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна власна кінцева точка usage або парсер корисного навантаження | +| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті повинна жити разом із плагіном провайдера | +| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, вилучення thinking-блоків) | +| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні власні переписування replay понад спільні допоміжні засоби компактизації | +| 43 | `validateReplayTurns` | Фінальна валідація або переформування ходів replay перед embedded runner | Транспорт провайдера потребує суворішої валідації ходів після загальної санітаризації | +| 44 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin provider, а потім переходять до інших plugin provider, здатних до hooks, -доки хтось справді не змінить model id або transport/config. Це дозволяє -shim-и псевдонімів/compat provider працювати без потреби, щоб викликаючий код знав, -який саме вбудований plugin володіє rewrite. Якщо жоден hook provider не перепише -підтримуваний запис config сімейства Google, вбудований нормалізатор config Google -усе одно виконає це очищення для сумісності. +відповідний плагін провайдера, а потім переходять до інших плагінів провайдерів із підтримкою хуків, +доки один із них фактично не змінить id моделі або transport/config. Це зберігає +працездатність shim-провайдерів alias/compat без необхідності для викликача знати, якому +комплектному плагіну належить переписування. Якщо жоден хук провайдера не перепише +підтримуваний запис конфігурації сімейства Google, комплектний нормалізатор конфігурації Google +все одно застосує це очищення сумісності. -Якщо provider потребує повністю кастомного wire protocol або кастомного виконавця запитів, -це інший клас extension. Ці hooks призначені для поведінки provider, -яка все ще працює на звичайному циклі інференції OpenClaw. +Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запиту, +це інший клас розширення. Ці хуки призначені для поведінки провайдера, +яка все ще працює на звичайному циклі виведення OpenClaw. -### Приклад provider +### Приклад провайдера ```ts api.registerProvider({ @@ -776,117 +773,116 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - і `wrapStreamFn`, тому що володіє прямою сумісністю вперед для Claude 4.6, - підказками щодо сімейства provider, вказівками з ремонту auth, інтеграцією з endpoint використання, - придатністю prompt-cache, типовими значеннями config з урахуванням auth, - типовою/адаптивною політикою thinking Claude та формуванням stream, - специфічним для Anthropic, для beta headers, `/fast` / `serviceTier` і `context1m`. -- Допоміжні засоби stream, специфічні для Claude в Anthropic, поки що залишаються у - власному публічному seam plugin `api.ts` / `contract-api.ts`. Ця поверхня пакета + `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, + і `wrapStreamFn`, оскільки володіє forward-compat Claude 4.6, + підказками сімейства провайдера, рекомендаціями щодо відновлення auth, інтеграцією + кінцевої точки usage, придатністю prompt-cache, типовими значеннями конфігурації з урахуванням auth, + типовою/адаптивною політикою thinking Claude та специфічним для Anthropic формуванням потоку для + beta headers, `/fast` / `serviceTier` і `context1m`. +- Допоміжні засоби потоку, специфічні для Claude в Anthropic, поки що залишаються у власному + публічному шві `api.ts` / `contract-api.ts` комплектного плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі - builder-и wrapper Anthropic замість того, щоб розширювати загальний SDK навколо правил - beta headers одного provider. + побудовники обгорток Anthropic замість розширення загального SDK навколо правил + beta-header одного провайдера. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - тому що володіє прямою сумісністю вперед для GPT-5.4, нормалізацією - прямого OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - придушенням Spark, синтетичними рядками списку OpenAI і політикою thinking / - live-model для GPT-5; сімейство stream `openai-responses-defaults` володіє - спільними native wrappers OpenAI Responses для headers атрибуції, - `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex, - формування payload reasoning-compat і керування контекстом Responses. + оскільки володіє forward-compat GPT-5.4, прямою нормалізацією OpenAI + `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, + приглушенням Spark, синтетичними рядками списку OpenAI та політикою GPT-5 щодо thinking / + live-model; сімейство потоків `openai-responses-defaults` володіє + спільними native-обгортками OpenAI Responses для attribution headers, + `/fast`/`serviceTier`, verbosity тексту, native Codex web search, + формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses. - OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, тому що provider є наскрізним і може відкривати нові + `prepareDynamicModel`, оскільки провайдер є pass-through і може показувати нові model id до оновлення статичного каталогу OpenClaw; він також використовує - `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати - provider-специфічні headers запитів, metadata маршрутизації, патчі reasoning і - політику prompt-cache поза core. Його replay policy надходить від сімейства - `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` - володіє ін'єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. + `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб + специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і + політика prompt-cache не потрапляли в ядро. Його політика replay походить із + сімейства `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` + володіє ін’єкцією proxy reasoning та пропусками unsupported-model / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, - тому що йому потрібні login пристрою, що належать provider, поведінка fallback моделей, - особливості transcript Claude, обмін GitHub token -> Copilot token і - endpoint використання, що належить provider. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому + потрібні власний device login провайдера, поведінка fallback моделі, особливості + транскриптів Claude, обмін GitHub token -> Copilot token і власна + кінцева точка usage провайдера. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, - тому що він усе ще працює на core transport OpenAI, але володіє своєю - нормалізацією transport/base URL, політикою fallback для OAuth refresh, - типовим вибором transport, синтетичними рядками каталогу Codex і інтеграцією з - endpoint використання ChatGPT; він використовує те саме сімейство stream - `openai-responses-defaults`, що й прямий OpenAI. -- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він + все ще працює на транспорті ядра OpenAI, але володіє нормалізацією свого + transport/base URL, політикою fallback оновлення OAuth, типовим вибором транспорту, + синтетичними рядками каталогу Codex та інтеграцією кінцевої точки usage ChatGPT; він + спільно використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI. +- Google AI Studio та Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що - сімейство replay `google-gemini` володіє fallback прямої сумісності вперед для Gemini 3.1, - native валідацією replay Gemini, санітизацією bootstrap replay, режимом - tagged reasoning-output і зіставленням сучасних моделей, тоді як - сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки + сімейство replay `google-gemini` володіє fallback forward-compat Gemini 3.1, + native валідацією replay Gemini, санітаризацією bootstrap replay, режимом tagged + reasoning-output і зіставленням modern-model, тоді як сімейство потоків + `google-thinking` володіє нормалізацією корисного навантаження thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування token, парсингу token і підключення - endpoint квот. + `fetchUsageSnapshot` для форматування токенів, розбору токенів і + підключення кінцевої точки quota. - Anthropic Vertex використовує `buildReplayPolicy` через - сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, - залишалося обмеженим ідентифікаторами Claude, а не всіма transport `anthropic-messages`. + сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося + обмеженим id Claude, а не кожним транспортом `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє - Bedrock-специфічною класифікацією помилок throttle/not-ready/context-overflow - для трафіку Anthropic-on-Bedrock; його replay policy при цьому все ще використовує той самий - guard `anthropic-by-model`, обмежений Claude. + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє + класифікацією помилок Bedrock для throttle/not-ready/context-overflow + у трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий + захист лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini - через transport, сумісні з OpenAI, і потребують санітизації - thought-signature Gemini без native валідації replay Gemini або rewrite bootstrap. + через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini + через транспорти, сумісні з OpenAI, і потребують санітаризації + thought-signature Gemini без native валідації replay Gemini або + переписувань bootstrap. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, тому що один provider володіє і - семантикою повідомлень Anthropic, і OpenAI-compatible; він зберігає видалення - блоків thinking лише для Claude з боку Anthropic, одночасно перевизначаючи режим - reasoning output назад на native, а сімейство stream `minimax-fast-mode` володіє - rewrite моделей fast-mode на спільному шляху stream. -- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він усе ще - використовує спільний transport OpenAI, але потребує нормалізації payload thinking, - що належить provider; сімейство stream `moonshot-thinking` зіставляє config і стан `/think` - на його native binary payload thinking. + сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє як семантикою + Anthropic-message, так і OpenAI-compatible; він зберігає скидання thinking-блоків + лише для Claude на стороні Anthropic, одночасно перевизначаючи режим reasoning + назад на native, а сімейство потоків `minimax-fast-mode` володіє переписуванням моделей + fast-mode на спільному шляху потоку. +- Moonshot використовує `catalog` плюс `wrapStreamFn`, оскільки все ще використовує спільний + транспорт OpenAI, але потребує нормалізації корисного навантаження thinking, що належить провайдеру; сімейство потоків + `moonshot-thinking` зіставляє config плюс стан `/think` з його + native двійковим корисним навантаженням thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, тому що йому потрібні headers запитів, що належать provider, - нормалізація payload reasoning, підказки transcript Gemini та gating - Anthropic cache-TTL; сімейство stream `kilocode-thinking` зберігає ін'єкцію - thinking Kilo на спільному шляху proxy stream, пропускаючи `kilo/auto` та - інші id proxy-моделей, які не підтримують явний payload reasoning. + `isCacheTtlEligible`, оскільки йому потрібні заголовки запиту, що належать провайдеру, + нормалізація корисного навантаження reasoning, підказки транскриптів Gemini та + керування TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає + ін’єкцію Kilo thinking на спільному шляху proxy stream, пропускаючи `kilo/auto` і + інші proxy model id, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback для GLM-5, - типовими значеннями `tool_stream`, UX binary thinking, зіставленням сучасних моделей - і як auth використання, так і отриманням квот; сімейство stream `tool-stream-default-on` - не дає wrapper за замовчуванням увімкненого `tool_stream` перетворитися на - рукописний клей для кожного provider. + `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє fallback GLM-5, + типовими значеннями `tool_stream`, UX двійкового thinking, зіставленням modern-model і обома + — auth usage та отриманням quota; сімейство потоків `tool-stream-default-on` зберігає + обгортку `tool_stream` із увімкненням за замовчуванням поза межами рукописного коду для кожного провайдера. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - тому що володіє нормалізацією native transport xAI Responses, rewrite псевдонімів - fast-mode для Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, - повторним використанням fallback auth для tools, що належать plugin, прямим розв'язанням - моделей Grok для сумісності вперед і compat-патчами, що належать provider, такими як профіль - schema tools xAI, непідтримувані keywords schema, native `web_search` і декодування - аргументів tool-call із HTML-сутностями. + оскільки володіє нормалізацією native xAI Responses transport, переписуванням псевдонімів + Grok fast-mode, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для інструментів, що належать плагіну, визначенням моделі Grok + з forward-compat і compat-патчами, що належать провайдеру, такими як профіль + схеми інструментів xAI, непідтримувані ключові слова схеми, native `web_search` і + декодування аргументів виклику інструментів із HTML-entity. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - тримати особливості transcript/tooling поза core. -- Провайдери, вбудовані лише з catalog, такі як `byteplus`, `cloudflare-ai-gateway`, + особливості транскриптів/інструментів не потрапляли в ядро. +- Комплектні провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового provider, а також спільні - реєстрації media-understanding і video-generation для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс hooks використання, тому що їхня поведінка `/usage` - належить plugin, навіть якщо інференція все ще виконується через спільні transport. +- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації + розуміння медіа та генерації відео для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, оскільки їхня поведінка `/usage` + належить плагіну, навіть хоча виведення все ще працює через спільні транспорти. -## Допоміжні засоби runtime +## Допоміжні засоби часу виконання -Plugin можуть отримувати доступ до вибраних helper core через `api.runtime`. Для TTS: +Плагіни можуть отримати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -907,14 +903,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload TTS core для поверхонь файлів/голосових повідомлень. -- Використовує config core `messages.tts` і вибір provider. -- Повертає PCM audio buffer + sample rate. Plugin мають виконувати ресемплінг/кодування для providers. -- `listVoices` є необов'язковим для кожного provider. Використовуйте його для picker-ів голосів або потоків setup, що належать vendor. -- Списки голосів можуть містити багатші metadata, такі як locale, gender і теги personality для picker-ів, що враховують provider. +- `textToSpeech` повертає звичайне корисне навантаження TTS ядра для поверхонь файлів/голосових повідомлень. +- Використовує конфігурацію ядра `messages.tts` та вибір провайдера. +- Повертає PCM audio buffer + sample rate. Плагіни повинні виконувати resample/encode для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для селекторів голосів або потоків налаштування, що належать вендору. +- Списки голосів можуть містити розширеніші метадані, такі як locale, gender і теги personality для селекторів з урахуванням провайдера. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Plugin також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -934,15 +930,15 @@ api.registerSpeechProvider({ Примітки: -- Тримайте політику TTS, fallback і доставку відповідей у core. -- Використовуйте speech providers для поведінки синтезу, що належить vendor. -- Застарілий вхід Microsoft `edge` нормалізується до id provider `microsoft`. -- Бажана модель власності — орієнтована на компанію: один vendor plugin може володіти - text, speech, image і майбутніми media providers у міру того, як OpenClaw додає ці +- Тримайте політику TTS, fallback і доставку відповіді в ядрі. +- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. +- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один вендорний плагін може + володіти текстом, мовленням, зображенням і майбутніми медіапровайдерами, коли OpenClaw додає ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugin реєструють один типізований -provider media-understanding замість узагальненого key/value bag: +Для розуміння зображень/аудіо/відео плагіни реєструють один типізований +провайдер media-understanding замість загального key/value набору: ```ts api.registerMediaUnderstandingProvider({ @@ -956,16 +952,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Оркестрацію, fallback, config і підключення каналів тримайте в core. -- Поведінку vendor тримайте в plugin provider. -- Розширення мають залишатися адитивно типізованими: нові необов'язкові методи, - нові необов'язкові поля результату, нові необов'язкові можливості. +- Тримайте оркестрацію, fallback, конфігурацію та підключення каналів у ядрі. +- Тримайте поведінку вендора в плагіні провайдера. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові + поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та helper runtime - - vendor plugin реєструють `api.registerVideoGenerationProvider(...)` - - feature/channel plugin споживають `api.runtime.videoGeneration.*` + - ядро володіє контрактом можливості та допоміжним засобом часу виконання + - вендорні плагіни реєструють `api.registerVideoGenerationProvider(...)` + - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` -Для helper runtime media-understanding plugin можуть викликати: +Для допоміжних засобів часу виконання media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -980,8 +976,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо plugin можуть використовувати або runtime media-understanding, -або старіший псевдонім STT: +Для транскрипції аудіо плагіни можуть використовувати або середовище часу виконання +media-understanding, або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -996,11 +992,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує config аудіо media-understanding у core (`tools.media.audio`) і порядок fallback provider. -- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. +- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли результат транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу). +- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. -Plugin також можуть запускати фонові запуски subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1014,14 +1010,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов'язкові перевизначення на один запуск, а не постійні зміни сесії. -- OpenClaw враховує ці поля перевизначення лише для довірених викликаючих. -- Для запусків fallback, що належать plugin, оператори мають явним чином дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски subagent із недовірених plugin усе ще працюють, але запити на перевизначення відхиляються, а не безшумно повертаються до fallback. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. +- OpenClaw враховує ці поля перевизначення лише для довірених викликаючих сторін. +- Для резервних запусків, що належать плагіну, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. +- Запуски subagent із недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять на fallback. -Для вебпошуку plugin можуть споживати спільний helper runtime замість -звернення до підключення agent tool: +Для веб-пошуку плагіни можуть споживати спільний допоміжний засіб часу виконання замість +звернення до підключення інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1037,14 +1033,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugin також можуть реєструвати web-search providers через +Плагіни також можуть реєструвати провайдерів веб-пошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Тримайте вибір provider, розв'язання credentials і спільну семантику запитів у core. -- Використовуйте web-search providers для transport пошуку, специфічних для vendor. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для feature/channel plugin, яким потрібна поведінка пошуку без залежності від wrapper agent tool. +- Тримайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдерів веб-пошуку для вендор-специфічних транспортів пошуку. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1059,12 +1055,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка provider генерації зображень. -- `listProviders(...)`: показує доступні providers генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. +- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. -## HTTP routes Gateway +## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP-ендпоінти через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1079,36 +1075,36 @@ api.registerHttpRoute({ }); ``` -Поля route: +Поля маршруту: -- `path`: шлях route під HTTP server gateway. -- `auth`: обов'язково. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, якими керує plugin. -- `match`: необов'язково. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов'язково. Дозволяє тому самому plugin замінити власну наявну реєстрацію route. -- `handler`: повертайте `true`, коли route обробив запит. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, керованих плагіном. +- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і він спричинить помилку завантаження plugin. Використовуйте натомість `api.registerHttpRoute(...)`. -- Plugin routes мають явно оголошувати `auth`. -- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінювати route іншого plugin. -- Перекривні routes з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` мають залишатися лише в межах одного рівня auth. -- Routes `auth: "plugin"` **не** отримують автоматично operator runtime scope. Вони призначені для webhook/signature verification, якими керує plugin, а не для привілейованих helper-викликів Gateway. -- Routes `auth: "gateway"` працюють усередині runtime scope запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) тримає runtime scope route plugin на рівні `operator.write`, навіть якщо викликаючий надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей header явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах plugin-route з ідентичністю, runtime scope повертається до `operator.write` -- Практичне правило: не припускайте, що route plugin з auth gateway автоматично є поверхнею адміністратора. Якщо вашому route потрібна лише admin-поведінка, вимагайте auth-режим з ідентичністю і документуйте явний контракт header `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` видалено і воно викличе помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. +- Маршрути плагінів повинні явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` тримайте лише на тому самому рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області часу виконання оператора. Вони призначені для webhook/signature verification, керованих плагіном, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` виконуються в межах області часу виконання запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) зберігає області часу виконання маршрутів плагіна прив’язаними до `operator.write`, навіть якщо викликаюча сторона надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з ідентичністю, область часу виконання повертається до `operator.write` +- Практичне правило: не вважайте маршрут плагіна з gateway-auth неявною admin-поверхнею. Якщо вашому маршруту потрібна поведінка лише для admin, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення plugin використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час створення плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: -- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації plugin. -- `openclaw/plugin-sdk/core` для узагальненого спільного контракту для plugin. -- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod schema - `openclaw.json` (`OpenClawSchema`). -- Стабільні channel-примітиви, такі як `openclaw/plugin-sdk/channel-setup`, +- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. +- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. +- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` + (`OpenClawSchema`). +- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1120,15 +1116,15 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і - `openclaw/plugin-sdk/webhook-ingress` для спільного підключення - setup/auth/reply/webhook. `channel-inbound` є спільним місцем для debounce, - зіставлення mention, helper-ів вхідної політики mention, форматування envelope та - helper-ів контексту вхідних envelope. - `channel-setup` — це вузький seam setup для необов'язкового встановлення. - `setup-runtime` — це безпечна для runtime поверхня setup, яку використовують `setupEntry` / - відкладений запуск, включно з adapter-ами патчів setup, безпечними для імпорту. - `setup-adapter-runtime` — це seam adapter налаштування облікових записів із урахуванням env. - `setup-tools` — це малий seam helper для CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` для спільного підключення setup/auth/reply/webhook. + `channel-inbound` — це спільний дім для debounce, зіставлення згадок, + допоміжних засобів inbound mention-policy, форматування envelope і + допоміжних засобів контексту inbound envelope. + `channel-setup` — це вузький шов setup для необов’язкового встановлення. + `setup-runtime` — це безпечна для часу виконання поверхня setup, яку використовують `setupEntry` / + відкладений запуск, включно з безпечними для імпорту адаптерами патчів setup. + `setup-adapter-runtime` — це env-aware шов адаптера налаштування облікового запису. + `setup-tools` — це невеликий шов допоміжних засобів CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, @@ -1136,6 +1132,8 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, `openclaw/plugin-sdk/channel-policy`, + `openclaw/plugin-sdk/approval-gateway-runtime`, + `openclaw/plugin-sdk/approval-handler-adapter-runtime`, `openclaw/plugin-sdk/approval-handler-runtime`, `openclaw/plugin-sdk/approval-runtime`, `openclaw/plugin-sdk/config-runtime`, @@ -1147,198 +1145,194 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних helper runtime/config. - `telegram-command-config` — це вузький публічний seam для нормалізації/валідації кастомних - команд Telegram і він залишається доступним, навіть якщо поверхня контракту - вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний seam text/markdown/logging, включно з - видаленням assistant-visible-text, helper-ами рендерингу/розбиття markdown, helper-ами - редагування, helper-ами directive-tag і утилітами safe-text. -- Approval-специфічні channel seam мають віддавати перевагу одному контракту - `approvalCapability` на plugin. Тоді core читає auth, delivery, render, - native-routing і ліниву поведінку native-handler для approval через цю одну можливість, - а не змішує поведінку approval з не пов'язаними полями plugin. -- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як shim - сумісності для старіших plugin. Новий код має імпортувати вузькіші загальні примітиви, а - код репозиторію не повинен додавати нові імпорти цього shim. -- Внутрішні частини вбудованих extension залишаються приватними. Зовнішні plugin мають - використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може - використовувати публічні entry point репозиторію під коренем пакета plugin, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` і вузько спрямовані файли, наприклад - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета plugin із core або з - іншого extension. -- Розділення entry point у репозиторії: - `/api.js` — це barrel helper/types, - `/runtime-api.js` — це barrel лише для runtime, - `/index.js` — це entry вбудованого plugin, - а `/setup-entry.js` — це entry plugin setup. -- Поточні приклади вбудованих provider: - - Anthropic використовує `api.js` / `contract-api.js` для helper stream Claude, таких - як `wrapAnthropicProviderStream`, helper-и beta-header і парсинг `service_tier`. - - OpenAI використовує `api.js` для builder-ів provider, helper-ів типових моделей і builder-ів provider realtime. - - OpenRouter використовує `api.js` для свого builder-а provider, а також helper-ів onboarding/config, - тоді як `register.runtime.js` і далі може повторно експортувати загальні - helper `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні entry point, завантажені через facade, віддають перевагу активному snapshot config runtime, - якщо він існує, а потім переходять до розв'язаного config-файлу на диску, коли - OpenClaw ще не надає snapshot runtime. -- Загальні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір сумісності з helper seam вбудованих каналів, названих на їхню честь, усе ще існує. - Розглядайте їх як seam підтримки вбудованих/сумісності, а не нові цілі імпорту - для сторонніх рішень; нові міжканальні контракти, як і раніше, мають - потрапляти у загальні підшляхи `plugin-sdk/*` або локальні barrel-и plugin `api.js` / - `runtime-api.js`. + `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів часу виконання/конфігурації. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації + користувацьких команд Telegram і залишається доступним, навіть якщо поверхня контракту комплектного + Telegram тимчасово недоступна. + `text-runtime` — це спільний шов text/markdown/logging, включно з + вилученням assistant-visible-text, допоміжними засобами рендерингу/розбиття markdown, допоміжними засобами редагування, + допоміжними засобами directive-tag і утилітами safe-text. +- Канальні шви, специфічні для погодження, повинні надавати перевагу одному контракту + `approvalCapability` у плагіні. Тоді ядро читає auth погодження, доставку, рендеринг, + native-routing і поведінку lazy native-handler через цю єдину можливість + замість змішування поведінки погодження з не пов’язаними полями плагіна. +- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як + shim сумісності для старіших плагінів. Новий код повинен імпортувати вужчі + загальні примітиви, а код репозиторію не повинен додавати нові імпорти shim. +- Внутрішні механізми комплектних розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише + підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати + публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js`, а також вузько спрямовані файли, такі як + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з + іншого розширення. +- Поділ точок входу репозиторію: + `/api.js` — це барабан helper/types, + `/runtime-api.js` — це барабан лише для часу виконання, + `/index.js` — це точка входу комплектного плагіна, + а `/setup-entry.js` — це точка входу setup-плагіна. +- Поточні приклади комплектних провайдерів: + - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких + як `wrapAnthropicProviderStream`, допоміжні засоби beta-header і парсинг `service_tier`. + - OpenAI використовує `api.js` для побудовників провайдерів, допоміжних засобів типових моделей і побудовників realtime-провайдерів. + - OpenRouter використовує `api.js` для свого побудовника провайдера, а також допоміжних засобів онбордингу/конфігурації, + тоді як `register.runtime.js` усе ще може повторно експортувати загальні + допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні точки входу, завантажені через facade, надають перевагу активному знімку конфігурації часу виконання, + якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли + OpenClaw ще не обслуговує знімок часу виконання. +- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір швів сумісності з брендуванням комплектних каналів усе ще існує. Розглядайте їх як + шви для підтримки комплектних плагінів/сумісності, а не як нові цілі імпорту для сторонніх рішень; + нові міжканальні контракти мають і далі потрапляти на загальні підшляхи `plugin-sdk/*` або в локальні барабани `api.js` / + `runtime-api.js` плагіна. Примітка щодо сумісності: -- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. -- Насамперед віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи +- Для нового коду уникайте кореневого барабана `openclaw/plugin-sdk`. +- Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це бажаний контракт для нової роботи з - вбудованими та зовнішніми plugin. - Парсинг/зіставлення цілей має бути в `openclaw/plugin-sdk/channel-targets`. - Гейти message action і helper-и message-id для реакцій мають бути в + allowlist/status/message-tool — це бажаний контракт для нової + роботи з комплектними та зовнішніми плагінами. + Розбір/зіставлення цілей належить до `openclaw/plugin-sdk/channel-targets`. + Гейти дій повідомлень і допоміжні засоби message-id реакцій належать до `openclaw/plugin-sdk/channel-actions`. -- Допоміжні barrel-и, специфічні для вбудованих extension, за замовчуванням нестабільні. Якщо - helper потрібен лише вбудованому extension, тримайте його за локальним seam - `api.js` або `runtime-api.js` цього extension, а не просувайте в +- Допоміжні барабани, специфічні для комплектних розширень, не є стабільними за замовчуванням. Якщо + допоміжний засіб потрібен лише комплектному розширенню, тримайте його за локальним швом + `api.js` або `runtime-api.js` цього розширення замість того, щоб просувати його до `openclaw/plugin-sdk/`. -- Нові спільні helper seam мають бути загальними, а не названими на честь каналу. Спільний парсинг цілей - має бути в `openclaw/plugin-sdk/channel-targets`; channel-специфічні - внутрішні частини мають залишатися за локальним seam `api.js` або `runtime-api.js` - відповідного plugin. +- Нові спільні шви допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір цілей + належить до `openclaw/plugin-sdk/channel-targets`; внутрішні механізми, специфічні для каналу, + залишаються за локальним швом `api.js` або `runtime-api.js` плагіна-власника. - Підшляхи, специфічні для можливостей, такі як `image-generation`, - `media-understanding` і `speech`, існують тому, що вбудовані/нативні plugin використовують - їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є - довгостроковим замороженим зовнішнім контрактом. + `media-understanding` і `speech`, існують, тому що комплектні/нативні плагіни використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є + довгостроковим незмінним зовнішнім контрактом. -## Schema tool повідомлень +## Схеми інструмента message -Plugin мають володіти channel-специфічними внесками schema в `describeMessageTool(...)`. -Тримайте provider-специфічні поля в plugin, а не в спільному core. +Плагіни повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. +Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному ядрі. -Для спільних портативних фрагментів schema повторно використовуйте загальні helper, експортовані через +Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованих payload карток +- `createMessageToolButtonsSchema()` для корисного навантаження у стилі сітки кнопок +- `createMessageToolCardSchema()` для структурованого payload картки -Якщо форма schema має сенс лише для одного provider, визначайте її у -власному коді цього plugin замість того, щоб просувати у спільний SDK. +Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному +коді цього плагіна замість просування до спільного SDK. -## Розв'язання цілей каналу +## Визначення цілей каналу -Channel plugin мають володіти channel-специфічною семантикою цілей. Зберігайте -спільний outbound host загальним і використовуйте поверхню messaging adapter для правил provider: +Плагіни каналів повинні володіти семантикою цілей, специфічною для каналу. Тримайте спільний +outbound host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: -- `messaging.inferTargetChatType({ to })` вирішує, чи слід трактувати нормалізовану ціль - як `direct`, `group` або `channel` до пошуку в directory. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи слід - одразу перейти до розв'язання у стилі id замість пошуку в directory. -- `messaging.targetResolver.resolveTarget(...)` є fallback plugin, коли - core потребує фінального розв'язання, що належить provider, після нормалізації або - після пропуску в directory. -- `messaging.resolveOutboundSessionRoute(...)` володіє channel-специфічним побудуванням - route сесії після того, як ціль розв'язано. +- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль + слід розглядати як `direct`, `group` або `channel` до пошуку в директорії. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи + ввід слід одразу спрямувати до визначення за схожим на id значенням замість пошуку в директорії. +- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли + ядру потрібне фінальне визначення, що належить провайдеру, після нормалізації або + після промаху по директорії. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, + специфічною для провайдера, коли ціль уже визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають - прийматися до пошуку peers/groups. -- Використовуйте `looksLikeId` для перевірок "вважати це явним/native id цілі". -- Використовуйте `resolveTarget` для provider-специфічного fallback нормалізації, а не для - широкого пошуку в directory. -- Тримайте native id provider, такі як id чатів, id потоків, JID, handles і id кімнат, - всередині значень `target` або provider-специфічних параметрів, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають прийматися до + пошуку серед peer/group. +- Використовуйте `looksLikeId` для перевірок на кшталт «розглядати це як явний/native target id». +- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для провайдера, а не для + широкого пошуку в директорії. +- Тримайте native id провайдера, такі як chat id, thread id, JID, handle і room id, + у значеннях `target` або параметрах, специфічних для провайдера, а не в загальних полях SDK. -## Directory на основі config +## Директорії на основі конфігурації -Plugin, які виводять записи directory із config, мають тримати цю логіку в -plugin і повторно використовувати спільні helper з +Плагіни, які виводять записи директорії з конфігурації, повинні тримати цю логіку в +плагіні та повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі config, такі як: +Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: -- peers DM на основі allowlist -- налаштовані maps каналів/груп -- статичні fallback directory в межах облікового запису +- DM peer, керовані allowlist +- налаштовані карти каналів/груп +- статичні fallback директорії в межах облікового запису -Спільні helper у `directory-runtime` виконують лише загальні операції: +Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрацію запитів -- застосування обмежень +- фільтрацію запиту +- застосування ліміту - дедуплікацію/нормалізацію - побудову `ChannelDirectoryEntry[]` -Channel-специфічну перевірку облікових записів і нормалізацію id слід залишати в -реалізації plugin. +Інспекція облікового запису, специфічна для каналу, і нормалізація id мають залишатися в +реалізації плагіна. -## Каталоги provider +## Каталоги провайдерів -Plugin provider можуть визначати каталоги моделей для інференції через +Плагіни провайдерів можуть визначати каталоги моделей для виведення за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує у +`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: -- `{ provider }` для одного запису provider -- `{ providers }` для кількох записів provider +- `{ provider }` для одного запису провайдера +- `{ providers }` для кількох записів провайдерів -Використовуйте `catalog`, коли plugin володіє model id, типовими base URL -або metadata моделей із прив'язкою до auth, специфічними для provider. +Використовуйте `catalog`, коли плагін володіє model id провайдера, типовими +значеннями base URL або метаданими моделей, що залежать від auth. -`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих -неявних providers OpenClaw: +`catalog.order` визначає, коли каталог плагіна зливається відносно вбудованих +неявних провайдерів OpenClaw: -- `simple`: providers зі звичайним API-key або env -- `profile`: providers, які з'являються, коли існують auth profiles -- `paired`: providers, що синтезують кілька пов'язаних записів provider -- `late`: останній прохід, після інших неявних providers +- `simple`: прості провайдери на основі API-key або env +- `profile`: провайдери, які з’являються, коли існують auth-профілі +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів +- `late`: останній прохід, після інших неявних провайдерів -Пізніші providers перемагають у разі колізії ключів, тож plugin можуть -навмисно перевизначати вбудований запис provider з тим самим id provider. +Пізніші провайдери перемагають у разі колізії ключів, тож плагіни можуть навмисно +перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` усе ще працює як застарілий псевдонім +- `discovery` все ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Read-only інспекція каналів +## Лише читання для перевірки каналу -Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. +Якщо ваш плагін реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може виходити з припущення, що credentials - повністю матеріалізовані, і швидко завершуватися з помилкою, коли потрібних secret бракує. +- `resolveAccount(...)` — це шлях часу виконання. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` і потоки - doctor/config repair, не повинні потребувати матеріалізації runtime credentials лише для + `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config + repair, не повинні потребувати матеріалізації облікових даних часу виконання лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/статусу credentials, якщо це доречно, наприклад: +- Включає поля джерела/стану облікових даних, якщо це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення token лише для повідомлення про read-only - доступність. Для команд у стилі status достатньо повернути `tokenStatus: "available"` - (і відповідне поле source). -- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але - він недоступний у поточному шляху команди. +- Вам не потрібно повертати сирі значення токенів лише для того, щоб повідомити про доступність + лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але + недоступні в поточному шляху команди. -Це дозволяє командам лише для читання повідомляти "налаштовано, але недоступно в -цьому шляху команди" замість аварійного завершення або хибного повідомлення, що -обліковий запис не налаштований. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» +замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. ## Package packs -Каталог plugin може містити `package.json` з `openclaw.extensions`: +Каталог плагіна може містити `package.json` з `openclaw.extensions`: ```json { @@ -1350,64 +1344,66 @@ Plugin provider можуть визначати каталоги моделей } ``` -Кожен entry стає plugin. Якщо pack перелічує кілька extension, id plugin +Кожен запис стає плагіном. Якщо pack перелічує кілька розширень, id плагіна стає `name/`. -Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб -був доступний `node_modules` (`npm install` / `pnpm install`). +Якщо ваш плагін імпортує npm-залежності, встановлюйте їх у цьому каталозі, щоб +`node_modules` був доступний (`npm install` / `pnpm install`). -Запобіжна перевірка безпеки: кожен entry `openclaw.extensions` має залишатися всередині каталогу plugin -після розв'язання symlink. Entries, які виходять за межі каталогу package, +Захисне правило безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна +після визначення symlink. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies під час runtime). Тримайте дерева залежностей plugin "чистими JS/TS" і уникайте пакетів, яким потрібні збірки через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies у середовищі виконання). Тримайте дерева залежностей плагіна як +«чисті JS/TS» і уникайте пакетів, що потребують збірки через `postinstall`. -Необов'язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого channel plugin або -коли channel plugin увімкнено, але ще не налаштовано, він завантажує `setupEntry` -замість повного entry plugin. Це робить запуск і setup легшими, -коли ваш основний entry plugin також підключає tools, hooks або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. +Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або +коли плагін каналу ввімкнено, але він ще не налаштований, він завантажує `setupEntry` +замість повної точки входу плагіна. Це робить запуск і налаштування легшими, +коли основна точка входу плагіна також підключає інструменти, хуки або інший код, +потрібний лише під час виконання. -Необов'язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -дозволяє channel plugin підключитися до того самого шляху `setupEntry` під час -передслухової фази запуску gateway, навіть якщо канал уже налаштовано. +Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +може перевести плагін каналу на той самий шлях `setupEntry` під час +фази запуску gateway до початку прослуховування, навіть якщо канал уже налаштований. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, -яка має існувати до того, як gateway почне слухати. На практиці це означає, що -entry setup має реєструвати всі можливості каналу, від яких залежить запуск, наприклад: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати +до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup +має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: -- реєстрацію самого каналу -- будь-які HTTP routes, які мають бути доступні до початку прослуховування gateway -- будь-які methods, tools або services gateway, які мають існувати в тому самому вікні часу +- саму реєстрацію каналу +- будь-які HTTP-маршрути, які повинні бути доступні до того, як gateway почне прослуховування +- будь-які gateway methods, інструменти або сервіси, які мають існувати в тому самому вікні -Якщо ваш повний entry усе ще володіє будь-якою необхідною для запуску можливістю, не вмикайте -цей прапорець. Залиште plugin зі стандартною поведінкою і дозвольте OpenClaw завантажити -повний entry під час запуску. +Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте +цей прапорець. Залиште плагін із типовою поведінкою й дозвольте OpenClaw завантажувати +повну точку входу під час запуску. -Вбудовані channels також можуть публікувати helper-и поверхні контракту лише для setup, до яких core -може звертатися до завантаження повного runtime каналу. Поточна поверхня -просування setup така: +Комплектні канали також можуть публікувати допоміжні засоби лише для setup на поверхні контракту, які ядро +може використовувати до завантаження повного середовища часу виконання каналу. Поточна +поверхня просування setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли йому потрібно просунути застарілий config каналу з -одним обліковим записом у `channels..accounts.*` без завантаження повного entry plugin. -Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap у -іменований promoted account, коли іменовані accounts уже існують, і може зберігати -налаштований неканонічний ключ default-account замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію +однокористувацького каналу до `channels..accounts.*` без завантаження повної точки входу плагіна. +Поточний комплектний приклад — Matrix: він переносить лише ключі auth/bootstrap у +іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці patch adapter-и setup зберігають ліниве виявлення поверхні контракту вбудованих plugin. -Час імпорту залишається малим; поверхня promotion завантажується лише під час першого використання, -а не повторно входить у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів setup зберігають ледаче виявлення поверхні контракту комплектного плагіна. Час +імпорту залишається легким; поверхня просування завантажується лише при першому використанні +замість повторного входу в запуск комплектного каналу під час імпорту модуля. -Коли ці поверхні запуску містять methods Gateway RPC, тримайте їх на -plugin-специфічному префіксі. Простори імен admin core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди розв'язуються -до `operator.admin`, навіть якщо plugin запитує вужчу область. +Коли ці поверхні запуску включають gateway RPC methods, тримайте їх на +префіксі, специфічному для плагіна. Простори імен admin ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються +до `operator.admin`, навіть якщо плагін запитує вужчу область. Приклад: @@ -1426,8 +1422,8 @@ plugin-специфічному префіксі. Простори імен admi ### Метадані каталогу каналів -Channel plugin можуть рекламувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє core не містити дані каталогу. +Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. Приклад: @@ -1455,23 +1451,23 @@ Channel plugin можуть рекламувати метадані setup/discov } ``` -Корисні поля `openclaw.channel`, окрім мінімального прикладу: +Корисні поля `openclaw.channel`, крім мінімального прикладу: -- `detailLabel`: вторинний label для багатших поверхонь catalog/status -- `docsLabel`: перевизначає текст посилання на документацію -- `preferOver`: id plugin/channel з нижчим пріоритетом, які цей запис каталогу має перевершувати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копірайтом для поверхні вибору -- `markdownCapable`: позначає канал як markdown-capable для рішень щодо outbound-форматування -- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо встановлено `false` +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `docsLabel`: перевизначення тексту посилання для посилання на документацію +- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має перевершувати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору +- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень форматування вихідних повідомлень +- `exposure.configured`: приховує канал із поверхонь списків налаштованих каналів, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних селекторів setup/configure, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` -- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив'язки облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку за сесією під час розв'язання цілей announce +- `showConfigured` / `showInSetup`: застарілі псевдоніми все ще приймаються для сумісності; надавайте перевагу `exposure` +- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Додайте JSON-файл в одне з таких місць: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). +Помістіть JSON-файл в одне з таких місць: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` @@ -1481,15 +1477,15 @@ OpenClaw також може зливати **зовнішні каталоги один або кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Plugin context engine +## Плагіни контекстного рушія -Plugin context engine володіють оркестрацією контексту сесії для ingest, assembly -і compaction. Реєструйте їх зі свого plugin через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний engine через +Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly +і compaction. Реєструйте їх зі свого плагіна через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий конвеєр context, -а не просто додати memory search або hooks. +Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий +конвеєр контексту, а не просто додати пошук у пам’яті або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1517,7 +1513,7 @@ export default function (api) { } ``` -Якщо ваш engine **не** володіє алгоритмом compaction, залишайте `compact()` +Якщо ваш рушій **не** володіє алгоритмом compaction, залиште `compact()` реалізованим і явно делегуйте його: ```ts @@ -1555,46 +1551,45 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin приватним зверненням углиб. Додайте відсутню можливість. +Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте +систему плагінів через приватний внутрішній доступ. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політикою, fallback, злиттям config, - життєвим циклом, channel-facing семантикою і формою helper runtime. -2. додайте типізовані поверхні реєстрації/runtime plugin - Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною +1. визначте контракт ядра + Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, злиття конфігурації, + життєвий цикл, семантика для каналів і форма допоміжного засобу часу виконання. +2. додайте типізовані поверхні реєстрації/часу виконання плагіна + Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. під'єднайте споживачів core + channel/feature - Channels і feature plugin мають споживати нову можливість через core, - а не імпортувати vendor-реалізацію напряму. -4. зареєструйте vendor-реалізації - Потім vendor plugin реєструють свої бекенди для цієї можливості. -5. додайте контрактне покриття - Додайте тести, щоб форма власності та реєстрації залишалася явною з часом. +3. підключіть споживачів ядра + каналів/функцій + Канали та плагіни функцій мають споживати нову можливість через ядро, + а не імпортувати реалізацію вендора напряму. +4. зареєструйте реалізації вендорів + Потім вендорні плагіни реєструють свої бекенди для цієї можливості. +5. додайте покриття контрактів + Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається opinionated, не стаючи жорстко прив'язаним до -світогляду одного provider. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного контрольного списку файлів і робочого прикладу. +Так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до світогляду +одного провайдера. Конкретний перелік файлів і готовий приклад див. у [Cookbook можливостей](/uk/plugins/architecture). ### Контрольний список можливості Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих поверхонь разом: -- типи контракту core у `src//types.ts` -- runner/helper runtime core у `src//runtime.ts` -- поверхня реєстрації API plugin у `src/plugins/types.ts` -- підключення реєстру plugin у `src/plugins/registry.ts` -- відкриття runtime plugin у `src/plugins/runtime/*`, коли feature/channel - plugin мають її споживати -- helper-и capture/test у `src/test-utils/plugin-registration.ts` -- перевірки власності/контракту в `src/plugins/contracts/registry.ts` -- документація для операторів/plugin у `docs/` +- типи контрактів ядра в `src//types.ts` +- runner/допоміжний засіб часу виконання ядра в `src//runtime.ts` +- поверхня реєстрації API плагіна в `src/plugins/types.ts` +- підключення реєстру плагінів у `src/plugins/registry.ts` +- відкриття середовища часу виконання плагіна в `src/plugins/runtime/*`, коли плагіни функцій/каналів + повинні його споживати +- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` +- документація для операторів/плагінів у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще -не повністю інтегрована. +Якщо якоїсь із цих поверхонь бракує, це зазвичай ознака того, що можливість +ще не повністю інтегрована. ### Шаблон можливості @@ -1624,7 +1619,7 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Шаблон контрактного тесту: +Шаблон тесту контракту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1632,7 +1627,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- core володіє контрактом можливості + оркестрацією -- vendor plugin володіють vendor-реалізаціями -- feature/channel plugin споживають helper runtime -- контрактні тести зберігають явну власність +- ядро володіє контрактом можливості + оркестрацією +- вендорні плагіни володіють реалізаціями вендора +- плагіни функцій/каналів споживають допоміжні засоби часу виконання +- тести контрактів зберігають явність володіння diff --git a/docs/uk/plugins/sdk-channel-plugins.md b/docs/uk/plugins/sdk-channel-plugins.md index 7bfe21719..1bba9615e 100644 --- a/docs/uk/plugins/sdk-channel-plugins.md +++ b/docs/uk/plugins/sdk-channel-plugins.md @@ -7,200 +7,210 @@ sidebarTitle: Channel Plugins summary: Покроковий посібник зі створення плагіна каналу повідомлень для OpenClaw title: Створення плагінів каналів x-i18n: - generated_at: "2026-04-07T18:43:35Z" + generated_at: "2026-04-07T20:09:23Z" model: gpt-5.4 provider: openai - source_hash: b709fda7527fcf437b119c4668172804f2f9c9a46f5e39a2161467a4f5f1e42f + source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Створення плагінів каналів -Цей посібник покроково пояснює створення плагіна каналу, який підключає OpenClaw до -платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із безпекою DM, -паруванням, гілкуванням відповідей і надсиланням вихідних повідомлень. +Цей посібник допоможе вам створити плагін каналу, який підключає OpenClaw до +платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із +безпекою DM, сполученням, потоками відповідей і вихідними повідомленнями. - Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте + Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте [Початок роботи](/uk/plugins/building-plugins) про базову структуру пакета та налаштування маніфесту. ## Як працюють плагіни каналів -Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw зберігає один -спільний інструмент `message` у ядрі. Ваш плагін відповідає за: +Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw +зберігає один спільний інструмент `message` у ядрі. Вашому плагіну належать: -- **Config** — визначення облікового запису та майстер налаштування -- **Security** — політика DM і списки дозволених -- **Pairing** — процес підтвердження DM -- **Session grammar** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами гілок і запасними батьківськими варіантами -- **Outbound** — надсилання тексту, медіа й опитувань на платформу -- **Threading** — як організовуються відповіді в гілки +- **Конфігурація** — визначення облікового запису та майстер налаштування +- **Безпека** — політика DM і списки дозволених +- **Сполучення** — потік підтвердження DM +- **Граматика сесії** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами потоків і резервними батьківськими елементами +- **Вихідні повідомлення** — надсилання тексту, медіа й опитувань на платформу +- **Потоки** — як групуються відповіді -Ядро відповідає за спільний інструмент message, зв’язування промптів, зовнішню форму -ключа сесії, загальний облік `:thread:` і диспетчеризацію. +Ядру належать спільний інструмент message, зв’язування промптів, зовнішня форма +ключа сесії, загальний облік `:thread:` і диспетчеризація. -Якщо ваша платформа зберігає додатковий контекст в ідентифікаторах розмов, залишайте цей -розбір у плагіні через `messaging.resolveSessionConversation(...)`. Це -канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим -ідентифікатором гілки, явним `baseConversationId` і будь-якими +Якщо ваша платформа зберігає додаткову область дії в ідентифікаторах розмов, +залишайте цей розбір у плагіні за допомогою +`messaging.resolveSessionConversation(...)`. Це канонічний хук для +зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим +ідентифікатором потоку, явним `baseConversationId` і будь-якими `parentConversationCandidates`. -Коли ви повертаєте `parentConversationCandidates`, зберігайте їх впорядкованими від +Коли ви повертаєте `parentConversationCandidates`, зберігайте їхній порядок від найвужчого батьківського елемента до найширшої/базової розмови. Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів, -також можуть надавати файл верхнього рівня `session-key-api.ts` із відповідним -експортом `resolveSessionConversation(...)`. Ядро використовує цю безпечну для -завантаження поверхню лише тоді, коли реєстр плагінів під час виконання ще недоступний. +також можуть експортувати файл верхнього рівня `session-key-api.ts` із +відповідним експортом `resolveSessionConversation(...)`. Ядро використовує цю +безпечну для завантаження поверхню лише тоді, коли реєстр плагінів під час +виконання ще недоступний. `messaging.resolveParentConversationCandidates(...)` залишається доступним як -застарілий запасний варіант для сумісності, коли плагіну потрібні лише -резервні батьківські варіанти поверх загального/raw id. Якщо існують обидва хуки, ядро спочатку -використовує `resolveSessionConversation(...).parentConversationCandidates` і лише потім -переходить до `resolveParentConversationCandidates(...)`, якщо канонічний хук -їх не повертає. +застарілий резервний варіант сумісності, коли плагіну потрібні лише резервні +батьківські елементи поверх загального/raw id. Якщо наявні обидва хуки, ядро +спочатку використовує +`resolveSessionConversation(...).parentConversationCandidates` і лише потім +повертається до `resolveParentConversationCandidates(...)`, якщо канонічний хук +їх не містить. -## Підтвердження та можливості каналу +## Підтвердження та можливості каналів Більшості плагінів каналів не потрібен код, специфічний для підтверджень. -- Ядро відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну запасну доставку. -- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для підтверджень. -- `ChannelPlugin.approvals` видалено. Виносьте факти про доставку/нативний режим/рендеринг/автентифікацію підтверджень у `approvalCapability`. -- `plugin.auth` призначений лише для login/logout; ядро більше не читає хуки автентифікації підтверджень із цього об’єкта. -- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов автентифікації підтверджень. +- Ядру належать `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальна резервна доставка. +- Надавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, коли каналу потрібна поведінка, специфічна для підтверджень. +- `ChannelPlugin.approvals` видалено. Розміщуйте факти доставки/нативного відтворення/автентифікації підтверджень у `approvalCapability`. +- `plugin.auth` — лише login/logout; ядро більше не читає з цього об’єкта хуки автентифікації підтверджень. +- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — канонічний шов автентифікації підтверджень. - Використовуйте `approvalCapability.getActionAvailabilityState` для доступності автентифікації підтверджень у тому самому чаті. -- Якщо ваш канал надає нативні підтвердження exec, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану ініціювальної поверхні/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей специфічний для exec хук, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціювальний канал нативні підтвердження exec, і включати канал у рекомендації щодо запасного сценарію для нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. -- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дубльованих локальних запитів підтвердження або надсилання індикаторів набору перед доставкою. -- Використовуйте `approvalCapability.delivery` лише для маршрутизації нативних підтверджень або придушення запасної доставки. -- Використовуйте `approvalCapability.nativeRuntime` для фактів нативного підтвердження, що належать каналу. Зберігайте його ледачим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень. -- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтвердження замість спільного рендера. -- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри config, потрібні для ввімкнення нативних підтверджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю облікового запису, як-от `channels..accounts..execApprovals.*`, замість верхньорівневих типових значень. -- Якщо канал може вивести стабільні схожі на власника DM-ідентичності з наявної config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки підтверджень у ядро. -- Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі плюс фактах транспорту/представлення. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте факти, специфічні для каналу, за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб ядро могло зібрати обробник і взяти на себе фільтрацію запитів, маршрутизацію, усунення дублікатів, завершення строку дії, підписку шлюзу та сповіщення про перенаправлення. `nativeRuntime` поділено на кілька менших швів: -- `availability` — чи налаштовано обліковий запис і чи слід обробляти запит -- `presentation` — перетворення спільної view model підтверджень у нативні payload очікування/вирішення/прострочення або фінальні дії -- `transport` — підготовка цілей плюс надсилання/оновлення/видалення нативних повідомлень підтвердження +- Якщо ваш канал надає нативні підтвердження exec, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану поверхні ініціювання/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей хук, специфічний для exec, щоб розрізняти `enabled` і `disabled`, вирішувати, чи підтримує канал ініціювання нативні підтвердження exec, і включати канал до підказок щодо резервного варіанту для нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. +- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для специфічної для каналу поведінки життєвого циклу payload, наприклад приховування дубльованих локальних підказок підтвердження або надсилання індикаторів набору перед доставкою. +- Використовуйте `approvalCapability.delivery` лише для маршрутизації нативних підтверджень або придушення резервної доставки. +- Використовуйте `approvalCapability.nativeRuntime` для фактів нативних підтверджень, що належать каналу. Зберігайте його лінивим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень. +- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтверджень замість спільного рендерера. +- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь для вимкненого шляху пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних підтверджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами повинні відтворювати шляхи з областю облікового запису, як-от `channels..accounts..execApprovals.*`, а не значення верхнього рівня за замовчуванням. +- Якщо канал може виводити стабільні DM-ідентичності, схожі на власника, з наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання специфічної для підтверджень логіки ядра. +- Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі та фактах транспорту/подання. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте специфічні для каналу факти за `approvalCapability.nativeRuntime`, ідеально через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб ядро могло збирати обробник і володіти фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії, підпискою gateway і сповіщеннями про маршрутизацію в інше місце. `nativeRuntime` поділено на кілька менших швів: +- `availability` — чи налаштований обліковий запис і чи слід обробляти запит +- `presentation` — зіставлення спільної view model підтвердження з нативними payload у станах pending/resolved/expired або фінальними діями +- `transport` — підготовка цілей і надсилання/оновлення/видалення нативних повідомлень підтвердження - `interactions` — необов’язкові хуки bind/unbind/clear-action для нативних кнопок або реакцій - `observe` — необов’язкові хуки діагностики доставки -- Якщо каналу потрібні об’єкти, що належать runtime, як-от client, token, додаток Bolt або приймач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-context дозволяє ядру ініціалізувати обробники на основі можливостей зі стану запуску каналу без додавання обгорток, специфічних для підтверджень. -- Звертайтеся до нижчорівневого `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов на основі можливостей ще недостатньо виразний. -- Канали з нативними підтвердженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці помічники. `accountId` зберігає область політики підтверджень для багатьох облікових записів прив’язаною до правильного бот-акаунта, а `approvalKind` зберігає для каналу доступною поведінку підтверджень exec чи plugin без жорстко закодованих розгалужень у ядрі. -- Ядро тепер також відповідає за сповіщення про перенаправлення підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт «підтвердження надійшло в DM / інший канал» із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні помічники можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в ініціювальний чат. -- Зберігайте тип delivered approval id наскрізно. Нативні клієнти не повинні - вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу. +- Якщо каналу потрібні об’єкти, що належать runtime, наприклад клієнт, токен, застосунок Bolt або отримувач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-контексту дозволяє ядру завантажувати обробники, керовані можливостями, зі стану запуску каналу без додавання обгорткового glue-коду, специфічного для підтверджень. +- Звертайтеся до нижчорівневих `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов, керований можливостями, ще недостатньо виразний. +- Канали з нативними підтвердженнями повинні маршрутизувати через ці helper-и і `accountId`, і `approvalKind`. `accountId` зберігає політику підтверджень для кількох облікових записів у правильній області бот-облікового запису, а `approvalKind` зберігає для каналу доступну поведінку підтверджень exec або плагіна без жорстко закодованих гілок у ядрі. +- Тепер ядру також належать сповіщення про перемаршрутизацію підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт "підтвердження перейшло в DM / інший канал" із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні helper-и можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад у чат ініціювання. +- Зберігайте наскрізно тип delivered approval id. Нативні клієнти не повинні вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу. - Різні типи підтверджень можуть навмисно відкривати різні нативні поверхні. - Поточні приклади вбудованих плагінів: + Поточні вбудовані приклади: - Slack зберігає доступною нативну маршрутизацію підтверджень як для exec, так і для plugin id. - - Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec - і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження. -- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка для сумісності, але новий код має надавати перевагу будівнику можливостей і експонувати `approvalCapability` у плагіні. + - Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження. +- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має надавати перевагу побудовнику можливостей і експортувати `approvalCapability` у плагіні. -Для гарячих точок входу каналу віддавайте перевагу вужчим runtime-підшляхам, коли вам потрібна лише -одна частина цієї сім’ї: +Для гарячих точок входу каналу надавайте перевагу вужчим runtime-підшляхам, +коли вам потрібна лише одна частина цієї родини: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` - `openclaw/plugin-sdk/approval-delivery-runtime` +- `openclaw/plugin-sdk/approval-gateway-runtime` +- `openclaw/plugin-sdk/approval-handler-adapter-runtime` - `openclaw/plugin-sdk/approval-handler-runtime` - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`, +Так само надавайте перевагу `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` і -`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша зонтична -поверхня. +`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша +узагальнена поверхня. -Зокрема для налаштування: +Окремо для setup: -- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime помічники налаштування: - безпечні для імпорту адаптери патчів налаштування (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper-и setup: + безпечні для імпорту адаптери patch setup (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), виведення lookup-note, + `createSetupInputPresenceValidator`), вивід нотаток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані - будівники setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шов адаптера - для `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` охоплює будівники налаштування з необов’язковим встановленням - плюс кілька безпечних для налаштування примітивів: + побудовники setup-proxy +- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шов + адаптера для `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` охоплює побудовники setup + з необов’язковим встановленням, а також кілька примітивів, безпечних для setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Якщо ваш канал підтримує налаштування або auth на основі env, і загальні процеси запуску/config -мають знати ці назви env до завантаження runtime, оголошуйте їх у -маніфесті плагіна через `channelEnvVars`. Зберігайте runtime `envVars` каналу або локальні -константи лише для копірайту, орієнтованого на операторів. +Якщо ваш канал підтримує setup або auth на основі env і загальні потоки +startup/config повинні знати ці назви env ще до завантаження runtime, +оголошуйте їх у маніфесті плагіна через `channelEnvVars`. Зберігайте runtime +`envVars` каналу або локальні константи лише для текстів, орієнтованих на операторів. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і `splitSetupEntries` -- використовуйте ширший шов `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні - важчі спільні помічники налаштування/config, такі як +- використовуйте ширший шов `openclaw/plugin-sdk/setup` лише тоді, коли вам + також потрібні важчі спільні helper-и setup/config, наприклад `moveSingleAccountChannelSectionToDefaultAccount(...)` -Якщо ваш канал лише хоче повідомляти «спочатку встановіть цей плагін» на -поверхнях налаштування, віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані -adapter/wizard працюють за принципом fail closed для записів config і фіналізації, а також -повторно використовують те саме повідомлення про обов’язкове встановлення для валідації, фіналізації та тексту -з посиланням на документацію. +Якщо ваш канал хоче лише оголошувати "спочатку встановіть цей плагін" на +поверхнях setup, надавайте перевагу `createOptionalChannelSetupSurface(...)`. +Згенеровані adapter/wizard працюють у безпечному зачиненому режимі щодо +записів конфігурації та фіналізації, а також повторно використовують те саме +повідомлення про необхідність встановлення у валідації, finalize і текстах +посилань на документацію. -Для інших гарячих шляхів каналу віддавайте перевагу вузьким помічникам над ширшими застарілими -поверхнями: +Для інших гарячих шляхів каналів надавайте перевагу вузьким helper-ам замість +ширших застарілих поверхонь: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` і - `openclaw/plugin-sdk/account-helpers` для config багатьох облікових записів і - запасного сценарію облікового запису за замовчуванням + `openclaw/plugin-sdk/account-helpers` для конфігурації кількох + облікових записів і резервного варіанта з обліковим записом за + замовчуванням - `openclaw/plugin-sdk/inbound-envelope` і - `openclaw/plugin-sdk/inbound-reply-dispatch` для вхідного маршруту/конверта та - зв’язування record-and-dispatch + `openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта + вхідних повідомлень і зв’язування record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей - `openclaw/plugin-sdk/outbound-media` і - `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс делегатів - ідентичності/надсилання вихідних повідомлень -- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок гілок - і реєстрації адаптерів -- `openclaw/plugin-sdk/agent-media-payload` лише коли все ще потрібна застаріла - схема полів payload агента/медіа -- `openclaw/plugin-sdk/telegram-command-config` для нормалізації спеціальних команд Telegram, - валідації дублікатів/конфліктів і стабільного при запасному сценарії контракту config команд + `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа та + делегатів identity/send для вихідних повідомлень +- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу + прив’язок потоків і реєстрації адаптерів +- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще + потрібне застаріле компонування полів payload агента/медіа +- `openclaw/plugin-sdk/telegram-command-config` для нормалізації + користувацьких команд Telegram, валідації дублікатів/конфліктів і стабільного + для fallback контракту конфігурації команд -Канали лише з auth зазвичай можуть зупинитися на типовому шляху: ядро обробляє підтвердження, а плагін лише надає можливості outbound/auth. Канали з нативними підтвердженнями, як-от Matrix, Slack, Telegram і спеціальні транспортні канали чату, повинні використовувати спільні нативні помічники замість реалізації власного життєвого циклу підтверджень. +Канали лише з auth зазвичай можуть зупинитися на шляху за замовчуванням: ядро +обробляє підтвердження, а плагін просто надає можливості outbound/auth. Канали +з нативними підтвердженнями, як-от Matrix, Slack, Telegram і користувацькі +chat-транспорти, мають використовувати спільні нативні helper-и замість +створення власного життєвого циклу підтверджень. ## Політика вхідних згадок -Розділяйте обробку вхідних згадок на два рівні: +Розділяйте обробку вхідних згадок на два шари: - збирання доказів, що належить плагіну -- оцінювання спільної політики +- спільна оцінка політики -Для спільного рівня використовуйте `openclaw/plugin-sdk/channel-inbound`. +Для спільного шару використовуйте `openclaw/plugin-sdk/channel-inbound`. -Підходить для логіки, локальної для плагіна: +Добре підходить для локальної логіки плагіна: - виявлення відповіді боту -- виявлення цитування бота -- перевірки участі в гілці -- виключення сервісних/системних повідомлень -- платформонативні кеші, потрібні для доведення участі бота +- виявлення цитати бота +- перевірки участі в потоці +- виключення службових/системних повідомлень +- специфічні для платформи нативні кеші, потрібні для підтвердження участі бота -Підходить для спільного помічника: +Добре підходить для спільного helper-а: - `requireMention` - явний результат згадки - список дозволених неявних згадок - обхід для команд -- остаточне рішення про пропуск +- фінальне рішення про пропуск -Рекомендований процес: +Рекомендований потік: -1. Обчисліть локальні факти згадки. +1. Обчисліть локальні факти згадок. 2. Передайте ці факти в `resolveInboundMentionDecision({ facts, policy })`. 3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у своїй вхідній перевірці. @@ -241,8 +251,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` надає ті самі спільні помічники згадок для -вбудованих плагінів каналів, які вже залежать від інʼєкції runtime: +`api.runtime.channel.mentions` надає ті самі спільні helper-и згадок для +вбудованих плагінів каналів, які вже залежать від runtime injection: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -250,9 +260,9 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Старіші помічники `resolveMentionGating*` залишаються в -`openclaw/plugin-sdk/channel-inbound` лише як експорти для сумісності. Новий код -має використовувати `resolveInboundMentionDecision({ facts, policy })`. +Старіші helper-и `resolveMentionGating*` залишаються в +`openclaw/plugin-sdk/channel-inbound` лише як експорти сумісності. Новий код +повинен використовувати `resolveInboundMentionDecision({ facts, policy })`. ## Покроковий розбір @@ -260,8 +270,8 @@ if (decision.shouldSkip) return; Створіть стандартні файли плагіна. Поле `channel` у `package.json` - робить це плагіном каналу. Повну поверхню метаданих пакета - дивіться в [Налаштування плагіна і Config](/uk/plugins/sdk-setup#openclawchannel): + робить цей пакет плагіном каналу. Повну поверхню метаданих пакета див. у + [Налаштування плагіна та конфігурація](/uk/plugins/sdk-setup#openclawchannel): ```json package.json @@ -311,8 +321,8 @@ if (decision.shouldSkip) return; - Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть із - мінімуму — `id` і `setup` — і додавайте адаптери за потреби. + Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. + Почніть із мінімуму — `id` і `setup` — і додавайте адаптери за потреби. Створіть `src/channel.ts`: @@ -408,18 +418,18 @@ if (decision.shouldSkip) return; ``` - Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви передаєте - декларативні параметри, а будівник поєднує їх: + Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви + передаєте декларативні параметри, а побудовник їх компонуватиме: | Параметр | Що він підключає | | --- | --- | - | `security.dm` | Визначення DM-безпеки з областю дії з полів config | - | `pairing.text` | Текстовий процес парування DM з обміном кодами | - | `threading` | Визначення режиму reply-to (фіксований, з областю облікового запису або власний) | - | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ID повідомлень) | + | `security.dm` | Визначення політики DM з областю дії за полями конфігурації | + | `pairing.text` | Потік текстового сполучення DM з обміном коду | + | `threading` | Визначення режиму reply-to (фіксований, з областю облікового запису або користувацький) | + | `outbound.attachedResults` | Функції надсилання, що повертають метадані результату (ідентифікатори повідомлень) | - Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів, - якщо вам потрібен повний контроль. + Ви також можете передавати сирі об’єкти адаптерів замість декларативних + параметрів, якщо вам потрібен повний контроль. @@ -460,21 +470,23 @@ if (decision.shouldSkip) return; }); ``` - Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw - міг показувати їх у кореневій довідці без активації повного runtime каналу, - тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації - реальних команд. Залишайте `registerFull(...)` для роботи лише під час runtime. + Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, + щоб OpenClaw міг показувати їх у кореневій довідці без активації повного + runtime каналу, тоді як звичайні повні завантаження все одно підхоплюють + ті самі дескриптори для реєстрації реальних команд. Зберігайте + `registerFull(...)` для роботи лише під час runtime. Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте - префікс, специфічний для плагіна. Простори імен адміністратора ядра (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди - визначаються як `operator.admin`. - `defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Усі - параметри дивіться в [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry). + префікс, специфічний для плагіна. Простори імен адміністратора ядра + (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються + зарезервованими й завжди зіставляються з `operator.admin`. + `defineChannelPluginEntry` автоматично обробляє поділ за режимами реєстрації. Див. + [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry), щоб + переглянути всі параметри. - - Створіть `setup-entry.ts` для легкого завантаження під час онбордингу: + + Створіть `setup-entry.ts` для полегшеного завантаження під час onboarding: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -483,16 +495,17 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw завантажує це замість повної точки входу, коли канал вимкнено - або не налаштовано. Це дає змогу не підтягувати важкий runtime-код під час процесів налаштування. - Докладніше дивіться в [Налаштування і Config](/uk/plugins/sdk-setup#setup-entry). + OpenClaw завантажує це замість повної точки входу, коли канал вимкнений + або не налаштований. Це дозволяє не підтягувати важкий runtime-код під час + потоків setup. + Докладніше див. у [Setup і конфігурація](/uk/plugins/sdk-setup#setup-entry). - Ваш плагін має отримувати повідомлення з платформи й переспрямовувати їх до + Ваш плагін має отримувати повідомлення з платформи та пересилати їх у OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і - диспетчеризує його через вхідний обробник вашого каналу: + диспетчеризує його через обробник вхідних повідомлень вашого каналу: ```typescript registerFull(api) { @@ -516,9 +529,9 @@ if (decision.shouldSkip) return; ``` - Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу відповідає - за власний вхідний конвеєр. Подивіться на вбудовані плагіни каналів - (наприклад, пакет плагінів Microsoft Teams або Google Chat), щоб побачити реальні шаблони. + Обробка вхідних повідомлень є специфічною для каналу. Кожен плагін каналу + володіє власним вхідним конвеєром. Дивіться на вбудовані плагіни каналів + (наприклад, пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони. @@ -563,7 +576,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - Спільні помічники тестування дивіться в [Тестування](/uk/plugins/sdk-testing). + Спільні helper-и для тестування див. у [Тестування](/uk/plugins/sdk-testing). @@ -572,46 +585,47 @@ if (decision.shouldSkip) return; ``` /acme-chat/ -├── package.json # metadata openclaw.channel -├── openclaw.plugin.json # Маніфест зі схемою config +├── package.json # метадані openclaw.channel +├── openclaw.plugin.json # маніфест зі схемою конфігурації ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Публічні експорти (необов’язково) -├── runtime-api.ts # Внутрішні runtime-експорти (необов’язково) +├── api.ts # публічні експорти (необов’язково) +├── runtime-api.ts # внутрішні runtime-експорти (необов’язково) └── src/ ├── channel.ts # ChannelPlugin через createChatChannelPlugin - ├── channel.test.ts # Тести - ├── client.ts # API-клієнт платформи - └── runtime.ts # Сховище runtime (за потреби) + ├── channel.test.ts # тести + ├── client.ts # клієнт API платформи + └── runtime.ts # сховище runtime (за потреби) ``` ## Розширені теми - - Фіксовані режими відповіді, режими з областю облікового запису або власні + + Фіксовані режими відповідей, режими з областю облікового запису або користувацькі - + describeMessageTool і виявлення дій inferTargetChatType, looksLikeId, resolveTarget - + TTS, STT, медіа, subagent через api.runtime -Деякі вбудовані допоміжні шви все ще існують для підтримки вбудованих плагінів і -сумісності. Це не рекомендований шаблон для нових плагінів каналів; -віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної -поверхні SDK, якщо тільки ви не підтримуєте безпосередньо це сімейство вбудованих плагінів. +Деякі вбудовані helper seams усе ще існують для підтримки вбудованих плагінів і +сумісності. Вони не є рекомендованим шаблоном для нових плагінів каналів; +надавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної +поверхні SDK, якщо тільки ви безпосередньо не підтримуєте цю родину +вбудованих плагінів. ## Наступні кроки - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів -- [Тестування SDK](/uk/plugins/sdk-testing) — тестові утиліти та контрактні тести +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з імпортів за підшляхами +- [Тестування SDK](/uk/plugins/sdk-testing) — утиліти тестування та контрактні тести - [Маніфест плагіна](/uk/plugins/manifest) — повна схема маніфесту diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 474dbcd7c..9546d2435 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -2,139 +2,143 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви оновлюєте plugin до сучасної архітектури plugin - - Ви підтримуєте зовнішній plugin OpenClaw + - Ви оновлюєте плагін до сучасної архітектури плагінів + - Ви підтримуєте зовнішній плагін OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний plugin SDK -title: Міграція Plugin SDK +summary: Перехід із застарілого шару зворотної сумісності до сучасного SDK плагінів +title: Міграція SDK плагінів x-i18n: - generated_at: "2026-04-07T18:43:55Z" + generated_at: "2026-04-07T20:09:40Z" model: gpt-5.4 provider: openai - source_hash: 509699c3432191a1b2e4214c66d6d620e8d13a064cb2e7b9b38460c7ea45a20d + source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad source_path: plugins/sdk-migration.md workflow: 15 --- -# Міграція Plugin SDK +# Міграція SDK плагінів OpenClaw перейшов від широкого шару зворотної сумісності до сучасної -архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш plugin -було створено до появи нової архітектури, цей посібник допоможе вам -перейти на неї. +архітектури плагінів зі сфокусованими, задокументованими імпортами. Якщо ваш +плагін був створений до появи нової архітектури, цей посібник допоможе вам +виконати міграцію. ## Що змінюється -Стара система plugin надавала дві відкриті поверхні, які дозволяли plugin -імпортувати все необхідне з єдиної точки входу: +Стара система плагінів надавала дві широко відкриті поверхні, які дозволяли +плагінам імпортувати все, що їм потрібно, з єдиної точки входу: - **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував - десятки допоміжних функцій. Його було запроваджено, щоб зберегти роботу - старіших plugin на основі hook, поки створювалася нова архітектура plugin. -- **`openclaw/extension-api`** — міст, що надавав plugin прямий доступ до - допоміжних функцій на боці хоста, як-от вбудований засіб запуску agent. + десятки допоміжних функцій. Його було введено, щоб старіші плагіни на базі + хуків продовжували працювати, поки створювалася нова архітектура плагінів. +- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до + допоміжних функцій на боці хоста, таких як вбудований запускник агента. Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, -але нові plugin не повинні їх використовувати, а наявним plugin слід -перейти до того, як наступний мажорний випуск їх прибере. +але нові плагіни не повинні їх використовувати, а наявні плагіни мають +мігрувати до того, як наступний мажорний реліз їх видалить. Шар зворотної сумісності буде видалено в одному з майбутніх мажорних - випусків. Plugins, які все ще імпортують із цих поверхонь, перестануть + релізів. Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. ## Чому це змінилося -Старий підхід спричиняв проблеми: +Старий підхід створював проблеми: - **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних між собою модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення +- **Циклічні залежності** — широкі повторні експорти полегшували створення циклів імпорту -- **Нечітка поверхня API** — не було способу визначити, які експорти є +- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми -Сучасний plugin SDK вирішує це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим, самодостатнім модулем із чітким призначенням і задокументованим -контрактом. +Сучасний SDK плагінів це виправляє: кожен шлях імпорту +(`openclaw/plugin-sdk/\`) — це невеликий, самодостатній модуль із +чітким призначенням і задокументованим контрактом. -Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти -на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -брендовані допоміжні шви каналів і -`openclaw/plugin-sdk/telegram-core` були приватними скороченнями -моно-репозиторію, а не стабільними контрактами plugin. Натомість -використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору -вбудованих plugin зберігайте допоміжні функції, що належать provider, у -власному `api.ts` або `runtime-api.ts` цього plugin. +Застарілі зручні шви провайдерів для вбудованих каналів також прибрано. +Імпорти на кшталт `openclaw/plugin-sdk/slack`, +`openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, +`openclaw/plugin-sdk/whatsapp`, брендовані для каналів допоміжні шви та +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями для +монорепозиторію, а не стабільними контрактами плагінів. Натомість +використовуйте вузькі узагальнені підшляхи SDK. Усередині робочого простору +вбудованих плагінів зберігайте допоміжні функції, що належать провайдеру, у +власному `api.ts` або `runtime-api.ts` цього плагіна. -Поточні приклади вбудованих provider: +Поточні приклади вбудованих провайдерів: -- Anthropic зберігає допоміжні функції потоку, специфічні для Claude, у +- Anthropic зберігає специфічні для Claude допоміжні функції потоків у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає builder-и provider, допоміжні функції моделей за - замовчуванням і builder-и realtime provider у власному `api.ts` -- OpenRouter зберігає builder provider та допоміжні функції онбордингу/конфігурації - у власному `api.ts` +- OpenAI зберігає конструктори провайдерів, допоміжні функції моделей за + замовчуванням і конструктори realtime-провайдерів у власному `api.ts` +- OpenRouter зберігає конструктор провайдера та допоміжні функції + онбордингу/конфігурації у власному `api.ts` -## Як перейти +## Як виконати міграцію - - Plugins каналів із підтримкою approval тепер розкривають нативну поведінку - approval через `approvalCapability.nativeRuntime` разом зі спільним - реєстром runtime-context. + + Плагіни каналів із підтримкою погодження тепер надають нативну поведінку + погодження через `approvalCapability.nativeRuntime` разом зі спільним + реєстром runtime-контексту. - Ключові зміни: + Основні зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть автентифікацію/доставку, специфічні для approval, зі - застарілого зв’язування `plugin.auth` / `plugin.approvals` - на `approvalCapability` - - `ChannelPlugin.approvals` видалено з публічного контракту + - Перенесіть автентифікацію/доставку, специфічну для погоджень, зі + застарілої зв’язки `plugin.auth` / `plugin.approvals` на + `approvalCapability` + - `ChannelPlugin.approvals` було видалено з публічного контракту channel-plugin; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу з channel; hook - автентифікації approval там більше не читаються ядром - - Реєструйте runtime-об’єкти, що належать каналу, як-от clients, tokens або Bolt - apps, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте повідомлення про перенаправлення, що належать plugin, з native approval handlers; - тепер ядро відповідає за повідомлення routed-elsewhere на основі фактичних результатів доставки - - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте - справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. + - `plugin.auth` залишається лише для потоків входу/виходу каналів; хуки + автентифікації погоджень там більше не читаються ядром + - Реєструйте об’єкти runtime, що належать каналу, як-от клієнти, токени + або застосунки Bolt, через + `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте повідомлення reroute, що належать плагіну, з native + approval-обробників; тепер ядро саме відповідає за повідомлення + routed-elsewhere на основі фактичних результатів доставки + - Під час передавання `channelRuntime` у `createChannelManager(...)` + надавайте реальну поверхню `createPluginRuntime().channel`. Часткові + заглушки відхиляються. - Поточне компонування можливостей approval дивіться в + Актуальну структуру approval capability див. у `/plugins/sdk-channel-plugins`. - Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені Windows - wrappers `.cmd`/`.bat` тепер завершуються з закритою відмовою, якщо ви явно не передасте - `allowShellFallback: true`. + Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані + Windows-обгортки `.cmd`/`.bat` тепер завершуються в закритому режимі, якщо + ви явно не передасте `allowShellFallback: true`. ```typescript - // До + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // Після + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Установлюйте це лише для довірених викликів сумісності, які свідомо - // допускають резервний перехід через shell. + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Якщо ваш виклик не покладається навмисно на резервний перехід через shell, - не встановлюйте `allowShellFallback` і натомість обробляйте згенеровану помилку. + Якщо ваш код навмисно не покладається на резервний варіант через оболонку, + не встановлюйте `allowShellFallback` і натомість обробляйте згенеровану + помилку. - Знайдіть у своєму plugin імпорти з будь-якої із застарілих поверхонь: + Знайдіть у своєму плагіні імпорти з будь-якої застарілої поверхні: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -143,36 +147,38 @@ OpenClaw перейшов від широкого шару зворотної с - - Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні відповідає певному сучасному шляху + імпорту: ```typescript - // До (застарілий шар зворотної сумісності) + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Після (сучасні цільові імпорти) + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних функцій на боці хоста використовуйте впроваджений runtime plugin - замість прямого імпорту: + Для допоміжних функцій на боці хоста використовуйте інжектований runtime + плагіна замість прямого імпорту: ```typescript - // До (застарілий міст extension-api) + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Після (впроваджений runtime) + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується й до інших застарілих допоміжних функцій моста: + Той самий шаблон застосовується і до інших застарілих допоміжних функцій + bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -182,7 +188,7 @@ OpenClaw перейшов від широкого шару зворотної с | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні функції сховища session | `api.runtime.agent.session.*` | + | допоміжні функції сховища сесій | `api.runtime.agent.session.*` | @@ -197,144 +203,146 @@ OpenClaw перейшов від широкого шару зворотної с ## Довідник шляхів імпорту - | Шлях імпорту | Призначення | Ключові експорти | + | Шлях імпорту | Призначення | Основні експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/builders входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу плагіна | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий зонтичний повторний експорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного provider | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цільові визначення та builders входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, builders стану налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні функції runtime на етапі налаштування | Безпечні для імпорту patch-adapters налаштування, допоміжні функції нотаток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/provider-entry` | Допоміжна функція точки входу одного провайдера | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Сфокусовані визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, конструктори статусу налаштування | + | `plugin-sdk/setup-runtime` | Допоміжні функції runtime для етапу налаштування | Безпечні для імпорту адаптери patch для налаштування, допоміжні функції note для lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | | `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Допоміжні функції інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/setup-tools` | Допоміжні функції інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | | `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку облікових записів/конфігурації/action-gate | | `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервного значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції облікових записів | Допоміжні функції списку облікових записів/дій облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервний вибір за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції для облікових записів | Допоміжні функції списку облікових записів/account-action | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | Примітиви DM pairing | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + wiring індикатора набору | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + зв’язування typing | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builders схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики group/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Допоміжні функції вхідних envelope | Спільні допоміжні функції маршрутизації + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції запису та dispatch | - | `plugin-sdk/messaging-targets` | Розбір messaging targets | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні функції вихідного runtime | Допоміжні функції outbound identity/send delegate | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу thread-binding та адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder agent media payload для застарілих layout полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | + | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублювання/конфліктів | + | `plugin-sdk/channel-policy` | Визначення політики для груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Відстеження статусу облікового запису | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Допоміжні функції inbound envelope | Спільні допоміжні функції route + конструкторів envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції inbound reply | Спільні допоміжні функції record-and-dispatch | + | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Допоміжні функції outbound media | Спільне завантаження outbound media | + | `plugin-sdk/outbound-runtime` | Допоміжні функції outbound runtime | Допоміжні функції outbound identity/send delegate | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Життєвий цикл thread-binding і допоміжні функції адаптера | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Конструктор agent media payload для застарілих макетів полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/встановлення plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Logger/runtime env, timeout, retry та backoff helpers | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime plugin | Допоміжні функції команд/hooks/http/interactive plugin | + | `plugin-sdk/runtime-store` | Постійне сховище плагіна | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/plugin-install | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Logger/runtime env, допоміжні функції timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime плагіна | Допоміжні функції commands/hooks/http/interactive для плагіна | | `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра hook | Спільні допоміжні функції конвеєра webhook/internal hook | | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec | - | `plugin-sdk/cli-runtime` | Допоміжні функції runtime CLI | Форматування команд, очікування, допоміжні функції версій | - | `plugin-sdk/gateway-runtime` | Допоміжні функції gateway | Client gateway та допоміжні функції patch статусу каналу | + | `plugin-sdk/cli-runtime` | Допоміжні функції CLI runtime | Форматування команд, очікування, допоміжні функції версій | + | `plugin-sdk/gateway-runtime` | Допоміжні функції gateway | Допоміжні функції клієнта gateway і patch статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції валідації команд Telegram зі стабільним резервним режимом, коли surface контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні функції prompt approval | Payload approval exec/plugin, допоміжні функції capability/profile approval, native approval routing/runtime helpers | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції автентифікації approval | Визначення approver, автентифікація дій у тому ж чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції client approval | Допоміжні функції native exec approval profile/filter | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки approval | Адаптери native approval capability/delivery | - | `plugin-sdk/approval-handler-runtime` | Допоміжні функції handler approval | Спільні допоміжні функції runtime handler approval, включно із завантаженням native approval на основі capability | - | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей approval | Допоміжні функції binding native approval target/account | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply approval | Допоміжні функції payload reply approval exec/plugin | - | `plugin-sdk/channel-runtime-context` | Допоміжні функції runtime-context каналу | Загальні допоміжні функції register/get/watch для channel runtime-context | - | `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції trust, DM gating, external-content і збирання secret | + | `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні функції prompt для погоджень | Payload погодження exec/plugin, допоміжні функції approval capability/profile, допоміжні функції маршрутизації/runtime native approval | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції auth для погоджень | Визначення approver, auth для дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції клієнта погоджень | Допоміжні функції profile/filter для native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки погоджень | Адаптери native approval capability/delivery | + | `plugin-sdk/approval-gateway-runtime` | Допоміжні функції gateway для погоджень | Спільна допоміжна функція gateway-resolution для погоджень | + | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні функції адаптера погоджень | Полегшені допоміжні функції завантаження native approval adapter для гарячих точок входу каналу | + | `plugin-sdk/approval-handler-runtime` | Допоміжні функції approval handler | Ширші допоміжні функції runtime для approval handler; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції target для погоджень | Допоміжні функції зв’язування native approval target/account | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply для погоджень | Допоміжні функції payload відповіді для exec/plugin approval | + | `plugin-sdk/channel-runtime-context` | Допоміжні функції runtime-context каналу | Узагальнені допоміжні функції register/get/watch для channel runtime-context | + | `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції довіри, DM gating, external-content і збирання секретів | | `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції runtime SSRF | Допоміжні функції pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції SSRF runtime | Pinned-dispatcher, guarded fetch, допоміжні функції політики SSRF | | `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні функції керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичного gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок | | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch/proxy | `resolveFetch`, допоміжні функції proxy | | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, виконавці політик | + | `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, runners політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Керування командами та допоміжні функції surface команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд | - | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні функції запитів webhook | Утиліти цілей webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції guard тіла webhook | Допоміжні функції читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Inbound dispatch, heartbeat, planner відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповідей | Допоміжні функції finalize + dispatch provider | + | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Gating команд і допоміжні функції поверхні команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд | + | `plugin-sdk/secret-input` | Розбір секретних входів | Допоміжні функції secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запитів webhook | Утиліти target для webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції guard для тіла webhook | Допоміжні функції читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Inbound dispatch, heartbeat, planner відповіді, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповіді | Допоміжні функції finalize + dispatch до провайдера | | `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування reply reference | `createReplyReferencePlanner` | + | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Допоміжні функції chunk відповіді | Допоміжні функції chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні функції сховища session | Шлях до сховища та допоміжні функції updated-at | - | `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції директорій стану та OAuth | - | `plugin-sdk/routing` | Допоміжні функції маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні функції статусу каналу | Builders зведення стану каналу/облікового запису, типові значення runtime-state, допоміжні функції метаданих проблем | + | `plugin-sdk/session-store-runtime` | Допоміжні функції сховища сесій | Шлях сховища + допоміжні функції updated-at | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції каталогів state та OAuth | + | `plugin-sdk/routing` | Допоміжні функції routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації session-key | + | `plugin-sdk/status-helpers` | Допоміжні функції статусу каналу | Конструктори зведень статусу каналу/облікового запису, значення runtime-state за замовчуванням, допоміжні функції метаданих issue | | `plugin-sdk/target-resolver-runtime` | Допоміжні функції target resolver | Спільні допоміжні функції target resolver | | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації рядків | Допоміжні функції нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні функції URL запиту | Витягування рядкових URL з request-подібних вхідних даних | - | `plugin-sdk/run-command` | Допоміжні функції команд із тайм-аутом | Запускач команд із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витягування tool send | Витягування канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні функції logging | Logger підсистеми та допоміжні функції редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції таблиць Markdown | Допоміжні функції режиму таблиць Markdown | - | `plugin-sdk/reply-payload` | Типи відповідей на повідомлення | Типи payload відповіді | - | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted provider | Допоміжні функції виявлення/конфігурації self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted provider, сумісних з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted provider | - | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime-автентифікації provider | Допоміжні функції визначення ключа API під час runtime | - | `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування ключа API provider | Допоміжні функції онбордингу/запису профілю для ключів API | - | `plugin-sdk/provider-auth-result` | Допоміжні функції результату автентифікації provider | Стандартний builder результату автентифікації OAuth | - | `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу provider | Спільні допоміжні функції інтерактивного входу | - | `plugin-sdk/provider-env-vars` | Допоміжні функції env vars provider | Допоміжні функції пошуку env var для автентифікації provider | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builders політик replay, допоміжні функції endpoint provider та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Patches онбордингу provider | Допоміжні функції конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні функції HTTP provider | Загальні допоміжні функції HTTP/можливостей endpoint provider | - | `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch provider | Допоміжні функції реєстрації/кешу web-fetch provider | - | `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search provider | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter для scoped credentials | - | `plugin-sdk/provider-web-search` | Допоміжні функції web-search provider | Допоміжні функції реєстрації/кешу/runtime web-search provider | - | `plugin-sdk/provider-tools` | Допоміжні функції сумісності tool/schema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні функції використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції використання provider | - | `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper та спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Упорядкована async-черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції fetch/transform/store медіа, а також builders media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору candidate та повідомлень про відсутність моделі для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні функції media-understanding | Типи provider media understanding, а також exports допоміжних функцій зображення/аудіо для provider | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Видалення тексту, видимого assistant, допоміжні функції render/chunking/table для markdown, допоміжні функції редагування, directive-tag, safe-text utilities та пов’язані допоміжні функції text/logging | + | `plugin-sdk/request-url` | Допоміжні функції URL запиту | Витягування рядкових URL із request-подібних вхідних даних | + | `plugin-sdk/run-command` | Допоміжні функції команд із таймером | Runner команд із таймером і нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Читачі параметрів | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витягування надсилання tool | Витягування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції шляхів для тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні функції логування | Допоміжні функції логера підсистеми та редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції Markdown-таблиць | Допоміжні функції режимів Markdown-таблиць | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload відповіді | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted провайдерів | Допоміжні функції виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted провайдерів | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime auth провайдера | Допоміжні функції визначення API-ключа в runtime | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування API-ключа провайдера | Допоміжні функції онбордингу/profile-write для API-ключів | + | `plugin-sdk/provider-auth-result` | Допоміжні функції auth-result провайдера | Стандартний конструктор OAuth auth-result | + | `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу провайдера | Спільні допоміжні функції інтерактивного входу | + | `plugin-sdk/provider-env-vars` | Допоміжні функції env vars провайдера | Допоміжні функції пошуку auth env-var провайдера | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні функції endpoint провайдера та нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Patches онбордингу провайдера | Допоміжні функції конфігурації онбордингу | + | `plugin-sdk/provider-http` | Допоміжні функції HTTP провайдера | Узагальнені допоміжні функції HTTP/можливостей endpoint для провайдера | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch провайдера | Допоміжні функції реєстрації/кешу web-fetch провайдера | + | `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search провайдера | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped credential setters/getters | + | `plugin-sdk/provider-web-search` | Допоміжні функції web-search провайдера | Допоміжні функції реєстрації/кешу/runtime для web-search провайдера | + | `plugin-sdk/provider-tools` | Допоміжні функції сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні функції сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні функції використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції використання провайдерів | + | `plugin-sdk/provider-stream` | Допоміжні функції обгортки потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Впорядкована асинхронна черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції media | Допоміжні функції fetch/transform/store для media, а також конструктори media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції media-generation | Спільні допоміжні функції failover, вибір кандидатів і повідомлення про відсутні моделі для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні функції media-understanding | Типи провайдерів media-understanding, а також орієнтовані на провайдера допоміжні функції для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Видалення видимого для асистента тексту, render/chunking/table для markdown, допоміжні функції редагування чутливих даних, directive-tag, безпечний текст та пов’язані допоміжні функції тексту/логування | | `plugin-sdk/text-chunking` | Допоміжні функції chunking тексту | Допоміжна функція chunking вихідного тексту | - | `plugin-sdk/speech` | Допоміжні функції speech | Типи provider speech, а також exports допоміжних функцій directive, registry і validation для provider | - | `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider speech, registry, directives, normalization | - | `plugin-sdk/realtime-transcription` | Допоміжні функції realtime transcription | Типи provider та допоміжні функції registry | - | `plugin-sdk/realtime-voice` | Допоміжні функції realtime voice | Типи provider та допоміжні функції registry | - | `plugin-sdk/image-generation-core` | Спільне ядро image-generation | Типи image-generation, failover, auth та допоміжні функції registry | - | `plugin-sdk/music-generation` | Допоміжні функції music-generation | Типи provider/request/result для генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро music-generation | Типи music-generation, допоміжні функції failover, пошуку provider та розбору model-ref | - | `plugin-sdk/video-generation` | Допоміжні функції video-generation | Типи provider/request/result для генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро video-generation | Типи video-generation, допоміжні функції failover, пошуку provider та розбору model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей | + | `plugin-sdk/speech` | Допоміжні функції speech | Типи провайдерів speech, а також орієнтовані на провайдера допоміжні функції directive, registry і validation | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдерів speech, registry, directives, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні функції realtime transcription | Типи провайдерів і допоміжні функції registry | + | `plugin-sdk/realtime-voice` | Допоміжні функції realtime voice | Типи провайдерів і допоміжні функції registry | + | `plugin-sdk/image-generation-core` | Спільне ядро image-generation | Типи image-generation, failover, auth і допоміжні функції registry | + | `plugin-sdk/music-generation` | Допоміжні функції music-generation | Типи провайдера/запиту/результату для генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро music-generation | Типи music-generation, допоміжні функції failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/video-generation` | Допоміжні функції video-generation | Типи провайдера/запиту/результату для генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро video-generation | Типи video-generation, допоміжні функції failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивної відповіді | Нормалізація/скорочення payload інтерактивної відповіді | | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | | `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Exports спільного prelude channel plugin | + | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули channel plugin | | `plugin-sdk/channel-status` | Допоміжні функції статусу каналу | Спільні допоміжні функції snapshot/summary статусу каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні функції доступу до group | Спільні допоміжні функції прийняття рішень щодо доступу до group | - | `plugin-sdk/direct-dm` | Допоміжні функції direct-DM | Спільні допоміжні функції автентифікації/guard для direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви passive-channel/status та ambient proxy helper | - | `plugin-sdk/webhook-targets` | Допоміжні функції цілей webhook | Реєстр цілей webhook і допоміжні функції встановлення маршрутів | + | `plugin-sdk/group-access` | Допоміжні функції доступу до груп | Спільні допоміжні функції ухвалення рішень group-access | + | `plugin-sdk/direct-dm` | Допоміжні функції direct-DM | Спільні допоміжні функції auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви пасивного каналу/статусу та ambient proxy helper | + | `plugin-sdk/webhook-targets` | Допоміжні функції target для webhook | Допоміжні функції реєстру webhook target і встановлення route | | `plugin-sdk/webhook-path` | Допоміжні функції шляхів webhook | Допоміжні функції нормалізації шляхів webhook | - | `plugin-sdk/web-media` | Спільні допоміжні функції web media | Допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів plugin SDK | - | `plugin-sdk/memory-core` | Допоміжні функції вбудованого memory-core | Surface допоміжних функцій memory manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Exports рушія foundation хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings хоста пам’яті | Exports рушія embeddings хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Exports рушія QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Exports рушія сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | Допоміжні функції multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | Допоміжні функції запитів хоста пам’яті | + | `plugin-sdk/web-media` | Спільні допоміжні функції web media | Допоміжні функції завантаження віддалених/локальних media | + | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів SDK плагінів | + | `plugin-sdk/memory-core` | Допоміжні функції вбудованого memory-core | Поверхня допоміжних функцій memory manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад memory engine | Runtime-фасад індексації/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Експорти embedding engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні функції хоста пам’яті | Мультимодальні допоміжні функції хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції query хоста пам’яті | Допоміжні функції query хоста пам’яті | | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста пам’яті | Допоміжні функції secret хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | Допоміжні функції журналу подій хоста пам’яті | | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті | Допоміжні функції статусу хоста пам’яті | @@ -344,31 +352,32 @@ OpenClaw перейшов від широкого шару зворотної с | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій core runtime хоста пам’яті | | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій журналу подій хоста пам’яті | | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для plugin, суміжних із memory | - | `plugin-sdk/memory-host-search` | Фасад пошуку active memory | Лінивий фасад runtime search-manager active memory | + | `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для суміжних із пам’яттю плагінів | + | `plugin-sdk/memory-host-search` | Фасад пошуку активної пам’яті | Лінивий runtime-фасад search-manager активної пам’яті | | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Допоміжні функції вбудованого memory-lancedb | Surface допоміжних функцій memory-lancedb | - | `plugin-sdk/testing` | Тестові утиліти | Допоміжні функції та mocks для тестування | + | `plugin-sdk/memory-lancedb` | Допоміжні функції вбудованого memory-lancedb | Поверхня допоміжних функцій memory-lancedb | + | `plugin-sdk/testing` | Утиліти тестування | Допоміжні функції та mock-об’єкти для тестування | -Ця таблиця навмисно охоплює поширену підмножину для міграції, а не всю -поверхню SDK. Повний список із понад 200 точок входу наведено в +Ця таблиця навмисно охоплює лише поширену підмножину для міграції, а не +повну поверхню SDK. Повний список із понад 200 точок входу знаходиться в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі шви допоміжних функцій вбудованих plugin, як-от -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +Цей список усе ще містить деякі шви допоміжних функцій вбудованих плагінів, +такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для -підтримки та сумісності вбудованих plugin, але навмисно -не включені до таблиці поширеної міграції й не є рекомендованою ціллю для -нового коду plugin. +підтримки та сумісності вбудованих плагінів, але навмисно не включені до +таблиці поширеної міграції й не є рекомендованою ціллю для нового коду +плагінів. -Те саме правило застосовується до інших сімейств вбудованих допоміжних функцій, таких як: +Те саме правило застосовується до інших сімейств допоміжних функцій для +вбудованих компонентів, таких як: -- допоміжні функції підтримки browser: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- допоміжні функції підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- surfaces вбудованих helper/plugin, як-от `plugin-sdk/googlechat`, +- поверхні вбудованих helper/plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -377,23 +386,23 @@ OpenClaw перейшов від широкого шару зворотної с `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі розкриває вузьку surface допоміжних функцій токенів: -`DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних +функцій токенів `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете -знайти потрібний експорт, перевірте вихідний код у `src/plugin-sdk/` -або запитайте в Discord. +знайти потрібний експорт, перевірте вихідний код у `src/plugin-sdk/` або +запитайте в Discord. -## Часова шкала видалення +## Графік видалення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні видають попередження під час runtime | -| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні виводять попередження під час виконання | +| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; плагіни, які все ще їх використовують, перестануть працювати | -Усі core plugins уже перенесено. Зовнішнім plugin слід перейти -до наступного мажорного випуску. +Усі core-плагіни вже мігровано. Зовнішнім плагінам слід виконати міграцію +до наступного мажорного релізу. ## Тимчасове приглушення попереджень @@ -408,9 +417,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення plugin каналів -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення plugin provider -- [Внутрішня будова plugin](/uk/plugins/architecture) — глибокий розбір архітектури -- [Маніфест plugin](/uk/plugins/manifest) — довідник зі схеми маніфесту +- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший плагін +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів за subpath +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів +- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів +- [Внутрішня будова плагінів](/uk/plugins/architecture) — глибоке занурення в архітектуру +- [Маніфест плагіна](/uk/plugins/manifest) — довідник зі схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index ad7d7c43c..be27d64d8 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - Вам потрібно знати, з якого підшляху SDK імпортувати - - Вам потрібен довідник щодо всіх методів реєстрації в OpenClawPluginApi + - Потрібно знати, з якого підшляху SDK імпортувати + - Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-07T18:43:53Z" + generated_at: "2026-04-07T20:09:50Z" model: gpt-5.4 provider: openai - source_hash: 68d9b78dab757747cfa0e315376af72040ef79453129c0fa051c4c9dd948060f + source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є +Plugin SDK — це типізований контракт між plugins і core. Ця сторінка є довідником щодо **що імпортувати** і **що можна реєструвати**. **Шукаєте практичний посібник?** - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Channel plugin? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Provider plugin? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) -## Угода про імпорт +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -36,25 +36,25 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий, самодостатній модуль. Це пришвидшує запуск і -запобігає проблемам із циклічними залежностями. Для специфічних для каналу -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для -ширшої парасолькової поверхні та спільних допоміжних засобів, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +запобігає проблемам із циклічними залежностями. Для специфічних для channel +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` +залишайте для ширшої узагальненої поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. -Не додавайте й не використовуйте зручні шари з назвами провайдерів, як-от +Не додавайте і не використовуйте зручні шви з назвами provider, такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шари з брендуванням каналів. Вбудовані plugins мають компонувати загальні -підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці локальні для plugin barrel-файли, або додати вузький загальний SDK -контракт, коли потреба справді є міжканальною. +допоміжні шви з брендингом channel. Bundled plugins мають компонувати загальні +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core +має або використовувати ці локальні barrel-файли plugin, або додавати вузький загальний SDK +контракт, коли потреба справді є міжchannel-ною. Згенерована карта експортів усе ще містить невеликий набір допоміжних -шарів для вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +швів bundled-plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для підтримки вбудованих plugins і сумісності; вони -навмисно не включені до загальної таблиці нижче й не є рекомендованим +підшляхи існують лише для підтримки та сумісності bundled-plugin; вони +навмисно не включені до загальної таблиці нижче і не є рекомендованим шляхом імпорту для нових сторонніх plugins. ## Довідник підшляхів @@ -62,11 +62,11 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому згенерованому списку. -Ставтеся до них як до деталей реалізації/поверхонь сумісності, якщо якась сторінка документації -явно не позначає один із них як публічний. +Зарезервовані допоміжні підшляхи bundled-plugin усе ще з’являються в цьому +згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності, якщо лише сторінка документації +явно не просуває одну з них як публічну. -### Вхід plugin +### Plugin entry | Subpath | Ключові експорти | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | @@ -76,230 +76,232 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку дозволених, конструктори статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, побудовники стану налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для мультиакаунтної конфігурації/гейтінгу дій, допоміжні засоби резервного переходу до акаунта за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора акаунта | - | `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні засоби резервного переходу до значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку акаунтів/дій з акаунтами | + | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації/гейтів дій з кількома акаунтами та резервного використання акаунта за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | + | `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні засоби резервного використання акаунта за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків акаунтів/дій з акаунтами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю для вбудованого контракту | + | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації channel | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram з резервною bundled-contract підтримкою | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідного маршруту та envelope | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень + побудови envelope | | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень | - | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення target | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби для вихідної ідентичності/делегатів надсилання | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор медіа-пейлоаду агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмови/потоку, pairing і налаштованих прив’язок | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення політик груп у runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімків/зведень статусу каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби читання/редагування конфігурації списку дозволених | - | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/зведення пейлоадів інтерактивних відповідей | - | `plugin-sdk/channel-inbound` | Вхідний debounce, зіставлення згадок, допоміжні засоби політики згадок і допоміжні засоби envelope | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності/делегування надсилання | + | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл thread-binding і допоміжні засоби adapter | + | `plugin-sdk/agent-media-payload` | Legacy побудовник agent media payload | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби binding розмов/thread, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації runtime | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy під час runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary статусу channel | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації channel | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації channel | + | `plugin-sdk/channel-plugin-common` | Спільні експорти prelude plugin channel | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення payload інтерактивних відповідей | + | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce вхідних повідомлень, зіставлення mention, політики mention і envelope | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контракту каналу | - | `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, а також типи цілей секретів | + | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення target | + | `plugin-sdk/channel-contract` | Типи контракту channel | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | - + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Значення за замовчуванням бекенда CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для plugins провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю для API-ключів, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugins провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдера | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | + | `plugin-sdk/cli-backend` | Стандарти конфігурації backend CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API key під час runtime для provider plugins | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API key, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth auth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider plugins | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для auth provider | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники replay-policy, допоміжні засоби endpoint provider і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime web-search провайдерів | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/endpoint capability для provider | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби contract для конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch provider | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби contract для конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime web-search provider | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика і допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper-ів і спільні допоміжні wrapper-и для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Допоміжні засоби patch конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Визначення approver-а та допоміжні засоби action-auth у тому самому чаті | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і auth дій у тому самому chat | | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери доставлення/можливостей native approval | - | `plugin-sdk/approval-handler-runtime` | Спільні допоміжні засоби runtime обробника approval, зокрема capability-driven завантаження native approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей native approval + прив’язки акаунтів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби пейлоаду відповіді для exec/plugin approval | - | `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target | + | `plugin-sdk/approval-delivery-runtime` | Adapter-и можливостей/доставки native approval | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Легкі допоміжні засоби завантаження adapter native approval для гарячих entrypoint-ів channel | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для handler approval; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + account-binding | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповідей для exec/plugin approval | + | `plugin-sdk/command-auth-native` | Native auth команд + допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команд і командної поверхні | + | `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні засоби поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналів/plugins | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь secret channel/plugin | | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього контенту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби host allowlist і політики SSRF для приватних мереж | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, SSRF-захищеного fetch і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілей webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру тіла запиту/таймаутів | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього контенту та збирання secret | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і SSRF policy приватних мереж | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із SSRF-захистом і SSRF policy | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби webhook request/target | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body request/timeout | | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервних копій/встановлення plugins | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення plugin | | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context channel | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для plugins | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби пайплайна webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби для команд/hook/http/interactive plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy імпорту/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналів | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби client gateway і patch статусу channel | | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублювання/конфліктів, навіть якщо поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, конструктори approval-capability, допоміжні засоби auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби вхідного/reply runtime, chunking, dispatch, heartbeat, planner відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповідей | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Нормалізація name/description команд Telegram і перевірки дублікатів/конфліктів, навіть коли bundled Telegram contract surface недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники approval-capability, допоміжні засоби auth/profile, native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, heartbeat, планувальник reply | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для reply | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до session store + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби прив’язки route/session-key/account, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу каналів/акаунтів, значення runtime-state за замовчуванням і допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби target resolver | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів | - | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені читачі параметрів tools/CLI | - | `plugin-sdk/tool-send` | Витяг канонічних полів цілей надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування конфіденційних даних | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби path сховища сесій + updated-at | + | `plugin-sdk/state-paths` | Допоміжні засоби path для state/OAuth директорій | + | `plugin-sdk/routing` | Допоміжні засоби для route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби summary статусу channel/account, стандарти runtime-state і допоміжні засоби метаданих issues | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби resolver target | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/string | + | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних вхідних даних | + | `plugin-sdk/run-command` | Запуск команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Загальні рідери параметрів tool/CLI | + | `plugin-sdk/tool-send` | Витягування канонічних полів target надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби path тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування чутливих даних | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму markdown-таблиць | | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | - | `plugin-sdk/file-lock` | Реентрантні допоміжні засоби file-lock | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідних file-lock | | `plugin-sdk/persistent-dedupe` | Допоміжні засоби disk-backed dedupe cache | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session ACP і reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Гнучкий читач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу, статусу й ambient proxy helper | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби команд `/models` і відповідей провайдерів | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | + | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime agent | + | `plugin-sdk/boolean-param` | Рідер вільних boolean-параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення відповідності небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та pairing token | + | `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel, status і ambient proxy helper | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби для переліку Skills command | | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native команд | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби bounded cache | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | + | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і допоміжні засоби pinned lookup | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента | - | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів на основі конфігурації | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконання retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/workspace agent | + | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів директорій на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа плюс конструктори медіа-пейлоадів | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники media payload | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів Media understanding плюс орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/markdown/логування, такі як видалення видимого асистенту тексту, допоміжні засоби render/chunking/table для markdown, редагування конфіденційних даних, допоміжні засоби тегів директив і безпечного тексту | + | `plugin-sdk/media-understanding` | Типи provider для розуміння медіа, а також provider-oriented експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/markdown/logging, такі як видалення тексту, видимого помічнику, допоміжні засоби render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і утиліти safe-text | | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech-провайдерів плюс орієнтовані на провайдерів допоміжні засоби директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільні типи speech-провайдерів, реєстру, директив і допоміжні засоби нормалізації | - | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і розбір model-ref | - | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдерів і розбір model-ref | - | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів webhook | + | `plugin-sdk/speech` | Типи speech provider, а також provider-oriented допоміжні засоби для директив, реєстру й валідації | + | `plugin-sdk/speech-core` | Спільні типи speech provider, а також допоміжні засоби реєстру, директив і нормалізації | + | `plugin-sdk/realtime-transcription` | Типи provider для realtime transcription і допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Типи provider для realtime voice і допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Типи provider для генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи image-generation, а також допоміжні засоби failover, auth і реєстру | + | `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи music-generation, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи video-generation, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/webhook-targets` | Реєстр webhook target і допоміжні засоби встановлення route | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації webhook path | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Реекспортований `zod` для користувачів Plugin SDK | + | `plugin-sdk/zod` | Повторний експорт `zod` для споживачів plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - + | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI helper-ів | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для plugins, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад runtime активної пам’яті для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helper-ів | + | `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексації/пошуку memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine для host memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine для host memory | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine для host memory | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine для host memory | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби для host memory | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів для host memory | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret для host memory | + | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій для host memory | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу для host memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI для host memory | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime для host memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби file/runtime для host memory | + | `plugin-sdk/memory-host-core` | Vendor-neutral псевдонім для допоміжних засобів core runtime host memory | + | `plugin-sdk/memory-host-events` | Vendor-neutral псевдонім для допоміжних засобів журналу подій host memory | + | `plugin-sdk/memory-host-files` | Vendor-neutral псевдонім для допоміжних засобів file/runtime host memory | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для plugins, суміжних із memory | + | `plugin-sdk/memory-host-search` | Active memory runtime facade для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Vendor-neutral псевдонім для допоміжних засобів статусу host memory | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - - | Family | Поточні підшляхи | Призначення | + + | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` лишається barrel-ом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper-ів/runtime вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper-ів/runtime вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper-ів вбудованого IRC | - | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари helper-ів/сумісності для вбудованих каналів | - | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шари helper-ів для вбудованих функцій/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin (`browser-support` залишається barrel-файлом сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | + | Допоміжні засоби, специфічні для channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні засоби bundled channel | + | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` із такими методами: ### Реєстрація можливостей @@ -307,53 +309,53 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | Method | Що реєструє | | ------------------------------------------------ | ------------------------------- | | `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний inference-бекенд CLI | +| `api.registerCliBackend(...)` | Локальний CLI backend inference | | `api.registerChannel(...)` | Канал обміну повідомленнями | | `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription | -| `api.registerRealtimeVoiceProvider(...)` | Двосторонні сесії realtime voice | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова transcription realtime | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні сеанси voice realtime | | `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | | `api.registerImageGenerationProvider(...)` | Генерація зображень | | `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Web search | -### Tools і команди +### Інструменти та команди | Method | Що реєструє | | ------------------------------- | -------------------------------------------- | -| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | +| `api.registerTool(tool, opts?)` | Інструмент agent (обов’язковий або `{ optional: true }`) | | `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура -| Method | Що реєструє | -| ---------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук подій | -| `api.registerHttpRoute(params)` | HTTP endpoint gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фоновий сервіс | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| Method | Що реєструє | +| ---------------------------------------------- | ------------------------------------ | +| `api.registerHook(events, handler, opts?)` | Event hook | +| `api.registerHttpRoute(params)` | Gateway HTTP endpoint | +| `api.registerGatewayMethod(name, handler)` | Gateway RPC method | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фонова служба | +| `api.registerInteractiveHandler(registration)` | Інтерактивний handler | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання memory | -Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, +Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити -вужчу область методу gateway. Для методів, що належать plugin, віддавайте перевагу префіксам, -специфічним для plugin. +вужчу область gateway method. Для методів, що належать plugin, +віддавайте перевагу префіксам, специфічним для plugin. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, що належать registrar -- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої довідки CLI, - маршрутизації та lazy-реєстрації plugin CLI +- `commands`: явні корені команд, якими володіє registrar +- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, + маршрутизації та лінивої реєстрації CLI plugin -Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному шляху кореневого CLI, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим +Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною у звичайному кореневому шляху CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, який відкриває цей registrar. ```typescript @@ -366,7 +368,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю", + description: "Керуйте акаунтами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -374,127 +376,127 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, якщо вам не потрібна lazy-реєстрація кореневого CLI. -Цей сумісний eager-шлях і далі підтримується, але він не встановлює -placeholder-и на основі descriptor для lazy loading на етапі розбору. +Використовуйте лише `commands`, коли вам не потрібна лінива реєстрація кореневого CLI. +Цей eager шлях сумісності залишається підтримуваним, але він не встановлює +placeholder-и на основі descriptors для лінивого завантаження під час парсингу. -### Реєстрація CLI backend +### Реєстрація backend CLI -`api.registerCliBackend(...)` дозволяє plugin керувати конфігурацією за замовчуванням для локального -CLI backend AI, такого як `codex-cli`. +`api.registerCliBackend(...)` дає plugin змогу володіти стандартною конфігурацією для локального +backend AI CLI, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`. +- `id` backend стає префіксом provider у model ref, наприклад `codex-cli/gpt-5`. - `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - значення за замовчуванням plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписування сумісності після злиття +- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + стандартів plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти | Method | Що реєструє | | ------------------------------------------ | ------------------------------------ | -| `api.registerContextEngine(id, factory)` | Context engine (лише один активний одночасно) | -| `api.registerMemoryCapability(capability)` | Єдину можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) | +| `api.registerMemoryCapability(capability)` | Єдину можливість memory | +| `api.registerMemoryPromptSection(builder)` | Побудовник розділу prompt memory | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush memory | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | -### Адаптери embedding для пам’яті +### Адаптери embedding для memory -| Method | Що реєструє | -| ---------------------------------------------- | --------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin | +| Method | Що реєструє | +| ---------------------------------------------- | ----------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding для memory активного plugin | -- `registerMemoryCapability` — рекомендований API ексклюзивного plugin пам’яті. +- `registerMemoryCapability` — це рекомендований API ексклюзивного memory-plugin. - `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб супровідні plugins могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної - структури конкретного plugin пам’яті. + щоб companion plugins могли споживати експортовані memory artifacts через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного + layout конкретного memory plugin. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивного plugin пам’яті. -- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті зареєструвати один - або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або власний - id, визначений plugin). -- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих - id адаптерів. + `registerMemoryRuntime` — це legacy-сумісні API ексклюзивного memory-plugin. +- `registerMemoryEmbeddingProvider` дає активному memory plugin змогу зареєструвати один + або більше id adapter embedding (наприклад, `openai`, `gemini` або власний id, + визначений plugin). +- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, визначається відносно зареєстрованих id + цих adapter. ### Події та життєвий цикл | Method | Що робить | | -------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Колбек binding розмови | ### Семантика рішень hook -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник візьме dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. +- `before_tool_call`: повернення `{ block: true }` є фінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. +- `before_install`: повернення `{ block: true }` є фінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. +- `reply_dispatch`: повернення `{ handled: true, ... }` є фінальним. Щойно будь-який handler заявляє про диспетчеризацію, handler-и з нижчим пріоритетом і стандартний шлях диспетчеризації моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є фінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. ### Поля об’єкта API -| Field | Type | Опис | -| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія plugin (необов’язково) | -| `api.description` | `string?` | Опис plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела plugin | -| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Конфігурація plugin з `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` | Визначення шляху відносно кореня plugin | +| Field | Type | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | +| `api.id` | `string` | ID plugin | +| `api.name` | `string` | Назва для відображення | +| `api.version` | `string?` | Версія plugin (необов’язково) | +| `api.description` | `string?` | Опис plugin (необов’язково) | +| `api.source` | `string` | Шлях до джерела plugin | +| `api.rootDir` | `string?` | Коренева директорія plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime в пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація plugin із `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` | Визначення path відносно кореня plugin | -## Угода про внутрішні модулі +## Угода щодо внутрішніх модулів -У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Внутрішні runtime-експорти - index.ts # Точка входу plugin - setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) + runtime-api.ts # Внутрішні експорти лише для runtime + index.ts # Entry point plugin + setup-entry.ts # Легковаговий entry лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - у production-коді. Для внутрішніх імпортів використовуйте `./api.ts` або + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Facade-loaded публічні поверхні вбудованих plugins (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` і подібні публічні entry-файли) тепер віддають перевагу -активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімка runtime +Facade-loaded публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу +активному snapshot конфігурації runtime, якщо OpenClaw уже запущено. Якщо snapshot runtime ще не існує, вони повертаються до визначеного файлу конфігурації на диску. -Plugins провайдерів також можуть надавати вузький локальний barrel контракту plugin, якщо -helper навмисно є специфічним для провайдера й поки що не належить до загального -підшляху SDK. Поточний приклад серед вбудованих: провайдер Anthropic зберігає свої helper-и -Claude stream у власному публічному шарі `api.ts` / `contract-api.ts` замість +Provider plugins також можуть надавати вузький barrel локального контракту plugin, коли допоміжний засіб +навмисно є специфічним для provider і ще не належить до загального +підшляху SDK. Поточний bundled приклад: provider Anthropic зберігає свої +допоміжні засоби Claude stream у власному публічному шві `api.ts` / `contract-api.ts` замість просування логіки Anthropic beta-header і `service_tier` до загального контракту `plugin-sdk/*`. -Інші поточні приклади серед вбудованих: +Інші поточні bundled приклади: -- `@openclaw/openai-provider`: `api.ts` експортує конструктори провайдерів, - helper-и моделей за замовчуванням і конструктори realtime-провайдерів -- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор провайдера та - helper-и онбордингу/конфігурації +- `@openclaw/openai-provider`: `api.ts` експортує побудовники provider, + допоміжні засоби стандартних моделей і побудовники realtime provider +- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник provider, а також + допоміжні засоби онбордингу/конфігурації Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо helper справді є спільним, перенесіть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або до іншої + Якщо допоміжний засіб справді є спільним, перемістіть його до нейтрального підшляху SDK, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins. @@ -505,4 +507,4 @@ Claude stream у власному публічному шарі `api.ts` / `cont - [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації - [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint - [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей +- [Plugin Internals](/uk/plugins/architecture) — детальна архітектура та модель можливостей