chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8f908d91e0
commit
a2a09580ba
@ -2,40 +2,36 @@
|
||||
read_when:
|
||||
- Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
|
||||
- Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED
|
||||
- Ви оновлюєте Plugin до сучасної архітектури plugin-ів
|
||||
- Ви підтримуєте зовнішній Plugin OpenClaw
|
||||
- Ви оновлюєте plugin до сучасної архітектури plugin-ів
|
||||
- Ви підтримуєте зовнішній plugin OpenClaw
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK
|
||||
title: Міграція Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T02:58:47Z"
|
||||
generated_at: "2026-04-23T03:31:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0abdf5135b0e0a029348b77447ca713e43762a65934310088a098fee93cf9981
|
||||
source_hash: 8f21fc911a961bf88f6487dae0c1c2f54c0759911b2a992ae6285aa2f8704006
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Міграція Plugin SDK
|
||||
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin-ів зі сфокусованими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію.
|
||||
OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin-ів із цільовими, задокументованими імпортами. Якщо ваш plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію.
|
||||
|
||||
## Що змінюється
|
||||
|
||||
Стара система plugin-ів надавала дві широкі поверхні, які дозволяли plugin-ам імпортувати
|
||||
все, що їм потрібно, з єдиної точки входу:
|
||||
Стара система plugin-ів надавала дві широко відкриті поверхні, які дозволяли plugin-ам імпортувати будь-що потрібне з єдиної точки входу:
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував десятки
|
||||
допоміжних засобів. Його було запроваджено, щоб зберегти працездатність старіших plugin-ів на основі хуків, поки будувалася нова архітектура plugin-ів.
|
||||
- **`openclaw/extension-api`** — міст, який надавав plugin-ам прямий доступ до
|
||||
допоміжних засобів на боці хоста, таких як вбудований виконавець агентів.
|
||||
- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші plugin-и на основі хуків продовжували працювати, поки створювалася нова архітектура plugin-ів.
|
||||
- **`openclaw/extension-api`** — міст, який надавав plugin-ам прямий доступ до допоміжних засобів на стороні хоста, таких як вбудований засіб запуску агентів.
|
||||
|
||||
Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові
|
||||
plugin-и не повинні їх використовувати, а наявні plugin-и мають виконати міграцію до того, як у наступному мажорному релізі їх буде вилучено.
|
||||
Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові plugin-и не повинні їх використовувати, а наявні plugin-и мають виконати міграцію до того, як у наступному великому випуску їх буде видалено.
|
||||
|
||||
<Warning>
|
||||
Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних релізів.
|
||||
Plugin-и, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться.
|
||||
Шар зворотної сумісності буде видалено в майбутньому великому випуску.
|
||||
Plugin-и, які досі імпортують із цих поверхонь, перестануть працювати, коли це станеться.
|
||||
</Warning>
|
||||
|
||||
## Чому це змінилося
|
||||
@ -44,60 +40,50 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
|
||||
- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних модулів
|
||||
- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту
|
||||
- **Нечітка поверхня API** — не було способу визначити, які експорти є стабільними, а які внутрішніми
|
||||
- **Неочевидна поверхня API** — не було способу зрозуміти, які експорти були стабільними, а які — внутрішніми
|
||||
|
||||
Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом.
|
||||
Сучасний Plugin SDK виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\<subpath\>`) є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом.
|
||||
|
||||
Успадковані зручні поверхні provider-ів для вбудованих channel-ів також більше не існують. Імпорти
|
||||
на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
|
||||
допоміжні поверхні з брендуванням channel-ів і
|
||||
`openclaw/plugin-sdk/telegram-core` були приватними скороченнями монорепозиторію, а не
|
||||
стабільними контрактами plugin-ів. Натомість використовуйте вузькі узагальнені підшляхи SDK. Усередині
|
||||
робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать provider-у, у власному
|
||||
`api.ts` або `runtime-api.ts` цього plugin-а.
|
||||
Застарілі зручні seams провайдерів для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, branded helper seams каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями mono-repo, а не стабільними контрактами plugin-ів. Натомість використовуйте вузькі узагальнені підшляхи SDK. Усередині робочого простору вбудованого plugin-а зберігайте допоміжні засоби, що належать провайдеру, у власному `api.ts` або `runtime-api.ts` цього plugin-а.
|
||||
|
||||
Поточні приклади вбудованих provider-ів:
|
||||
Поточні приклади вбудованих провайдерів:
|
||||
|
||||
- Anthropic зберігає специфічні для Claude допоміжні засоби потоків у власній поверхні `api.ts` /
|
||||
`contract-api.ts`
|
||||
- OpenAI зберігає білдери provider-ів, допоміжні засоби моделей за замовчуванням і білдери
|
||||
provider-ів realtime у власному `api.ts`
|
||||
- OpenRouter зберігає білдер provider-а та допоміжні засоби онбордингу/конфігурації у власному
|
||||
`api.ts`
|
||||
- Anthropic зберігає допоміжні засоби потокової обробки, специфічні для Claude, у власному seam `api.ts` / `contract-api.ts`
|
||||
- OpenAI зберігає конструктори провайдерів, допоміжні засоби для моделей за замовчуванням і конструктори realtime-провайдерів у власному `api.ts`
|
||||
- OpenRouter зберігає конструктор провайдера та допоміжні засоби onboarding/config у власному `api.ts`
|
||||
|
||||
## Як виконати міграцію
|
||||
|
||||
<Steps>
|
||||
<Step title="Перенесіть approval-native обробники на факти можливостей">
|
||||
Channel plugin-и з підтримкою approval тепер розкривають нативну поведінку approval через
|
||||
`approvalCapability.nativeRuntime` разом зі спільним реєстром runtime-контексту.
|
||||
<Step title="Перенесіть approval-native обробники на факти capability">
|
||||
Channel plugin-и з підтримкою approval тепер надають нативну поведінку approval через
|
||||
`approvalCapability.nativeRuntime` разом зі спільним реєстром runtime-context.
|
||||
|
||||
Ключові зміни:
|
||||
|
||||
- Замініть `approvalCapability.handler.loadRuntime(...)` на
|
||||
`approvalCapability.nativeRuntime`
|
||||
- Перенесіть auth/доставку, специфічні для approval, із застарілої прив’язки `plugin.auth` /
|
||||
`plugin.approvals` на `approvalCapability`
|
||||
- `ChannelPlugin.approvals` було вилучено з публічного контракту channel-plugin-а;
|
||||
- Перенесіть auth/delivery, специфічні для approval, зі застарілої прив’язки `plugin.auth` /
|
||||
`plugin.approvals` до `approvalCapability`
|
||||
- `ChannelPlugin.approvals` було видалено з публічного контракту channel-plugin-а;
|
||||
перенесіть поля delivery/native/render до `approvalCapability`
|
||||
- `plugin.auth` залишається лише для потоків login/logout channel-ів; auth-хуки
|
||||
approval там більше не зчитуються core
|
||||
- Реєструйте об’єкти runtime, що належать channel-у, як-от клієнти, токени або Bolt
|
||||
- `plugin.auth` лишається лише для потоків login/logout каналу; auth-хуки approval
|
||||
там більше не зчитуються ядром
|
||||
- Реєструйте runtime-об’єкти, що належать каналу, такі як clients, tokens або Bolt
|
||||
apps, через `openclaw/plugin-sdk/channel-runtime-context`
|
||||
- Не надсилайте сповіщення reroute, що належать plugin-у, з нативних обробників approval;
|
||||
сповіщення «маршрутизовано в інше місце» тепер належать core і базуються на фактичних результатах доставки
|
||||
- Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте
|
||||
реальну поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються.
|
||||
- Не надсилайте повідомлення reroute, що належать plugin-у, з native approval-обробників;
|
||||
тепер ядро відповідає за повідомлення routed-elsewhere на основі фактичних результатів delivery
|
||||
- Передаючи `channelRuntime` у `createChannelManager(...)`, надавайте
|
||||
справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються.
|
||||
|
||||
Поточну структуру можливостей approval див. у `/plugins/sdk-channel-plugins`.
|
||||
Актуальну структуру approval capability див. у `/plugins/sdk-channel-plugins`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте резервну поведінку Windows wrapper">
|
||||
Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows
|
||||
wrapper-и `.cmd`/`.bat` тепер аварійно завершуються за принципом fail closed, якщо ви явно не передасте `allowShellFallback: true`.
|
||||
<Step title="Перевірте fallback-поведінку Windows wrapper">
|
||||
Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows
|
||||
wrappers `.cmd`/`.bat` тепер завершуються з помилкою за замовчуванням, якщо ви явно не передасте
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -112,13 +98,13 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
});
|
||||
```
|
||||
|
||||
Якщо ваш виклик навмисно не покладається на shell fallback, не задавайте
|
||||
`allowShellFallback`, а натомість обробляйте згенеровану помилку.
|
||||
Якщо ваш код свідомо не покладається на shell fallback, не встановлюйте
|
||||
`allowShellFallback` і натомість обробляйте викинуту помилку.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Знайдіть застарілі імпорти">
|
||||
Пошукайте у своєму Plugin імпорти з будь-якої із застарілих поверхонь:
|
||||
Знайдіть у вашому plugin-і імпорти з будь-якої із застарілих поверхонь:
|
||||
|
||||
```bash
|
||||
grep -r "plugin-sdk/compat" my-plugin/
|
||||
@ -127,7 +113,7 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Замініть на сфокусовані імпорти">
|
||||
<Step title="Замініть їх на цільові імпорти">
|
||||
Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту:
|
||||
|
||||
```typescript
|
||||
@ -144,7 +130,7 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
|
||||
```
|
||||
|
||||
Для допоміжних засобів на боці хоста використовуйте впроваджений runtime Plugin замість прямого імпорту:
|
||||
Для допоміжних засобів на стороні хоста використовуйте injected runtime plugin-а замість прямого імпорту:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated extension-api bridge)
|
||||
@ -155,7 +141,7 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
|
||||
```
|
||||
|
||||
Такий самий шаблон застосовується й до інших допоміжних засобів застарілого моста:
|
||||
Такий самий шаблон застосовується й до інших допоміжних засобів застарілого bridge:
|
||||
|
||||
| Старий імпорт | Сучасний еквівалент |
|
||||
| --- | --- |
|
||||
@ -165,7 +151,7 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
|
||||
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
|
||||
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
|
||||
| session store helpers | `api.runtime.agent.session.*` |
|
||||
| допоміжні засоби session store | `api.runtime.agent.session.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
@ -180,175 +166,175 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
## Довідник шляхів імпорту
|
||||
|
||||
<Accordion title="Таблиця поширених шляхів імпорту">
|
||||
| Import path | Призначення | Ключові експорти |
|
||||
| Шлях імпорту | Призначення | Ключові експорти |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу Plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Успадкований узагальнений повторний експорт для визначень/білдерів точок входу channel-ів | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider-а | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Сфокусовані визначення та білдери точок входу channel-ів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, білдери статусу налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні засоби runtime під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування |
|
||||
| `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin-а | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої схеми config | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Цільові визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Підказки allowlist, конструктори статусу налаштування |
|
||||
| `plugin-sdk/setup-runtime` | Допоміжні засоби runtime під час налаштування | Безпечні для імпорту адаптери setup patch, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, проксі делегованого налаштування |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/шлюзу дій облікового запису |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/config/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` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback до типового значення |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби списку облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Примітиви сполучення DM | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + зв’язування typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Білдери схем конфігурації | Типи схем конфігурації channel-ів |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів |
|
||||
| `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Допоміжні засоби життєвого циклу статусу облікового запису та потоку чернеток | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки |
|
||||
| `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних відповідей | Спільні допоміжні засоби запису та диспетчеризації |
|
||||
| `plugin-sdk/messaging-targets` | Аналіз цілей повідомлень | Допоміжні засоби аналізу/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегата надсилання та планування payload |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок thread | Допоміжні засоби життєвого циклу прив’язок thread і адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Успадковані допоміжні засоби media payload | Білдер media payload агента для успадкованих макетів полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише успадковані утиліти runtime channel-ів |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді |
|
||||
| `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення plugin-ів |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, допоміжні засоби timeout, retry і backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime Plugin | Допоміжні засоби команд/хуків/http/інтерактивності Plugin |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра hook | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook |
|
||||
| `plugin-sdk/channel-pairing` | Примітиви DM pairing | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Прив’язка префікса відповіді та typing | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Фабрики адаптерів config | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Конструктори схем config | Типи схем config каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби config команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів |
|
||||
| `plugin-sdk/channel-policy` | Визначення політики group/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Допоміжні засоби статусу облікового запису та життєвого циклу draft stream | `createAccountStatusSink`, допоміжні засоби фіналізації draft preview |
|
||||
| `plugin-sdk/inbound-envelope` | Допоміжні засоби inbound envelope | Спільні допоміжні засоби маршрутизації + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби inbound reply | Спільні допоміжні засоби запису та dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Аналіз messaging targets | Допоміжні засоби аналізу/зіставлення targets |
|
||||
| `plugin-sdk/outbound-media` | Допоміжні засоби outbound media | Спільне завантаження outbound media |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound runtime | Допоміжні засоби outbound identity/send delegate і планування payload |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби thread-binding | Допоміжні засоби життєвого циклу thread-binding та адаптерів |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор agent media payload для застарілих макетів полів |
|
||||
| `plugin-sdk/channel-runtime` | Застарілий compatibility shim | Лише застарілі утиліти channel runtime |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів reply |
|
||||
| `plugin-sdk/runtime-store` | Постійне сховище plugin-а | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/встановлення plugin-ів |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, timeout, retry і backoff helpers |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби plugin runtime | Допоміжні засоби команд/хуків/http/interactive plugin-а |
|
||||
| `plugin-sdk/hook-runtime` | Допоміжні засоби hook pipeline | Спільні допоміжні засоби pipeline webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби process | Спільні допоміжні засоби exec |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Клієнт Gateway і допоміжні засоби patch статусу channel-ів |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби запитів approval | Payload approval exec/plugin, допоміжні засоби можливостей/профілю approval, нативні допоміжні засоби маршрутизації/runtime approval |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth approval | Визначення approver, auth дій у тому самому chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілю/фільтра нативного exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Нативні адаптери можливостей/доставки approval |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway approval | Спільний допоміжний засіб визначення Gateway approval |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження адаптера нативного approval для гарячих точок входу channel-ів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби runtime обробника approval; віддавайте перевагу вужчим поверхням adapter/gateway, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілі approval | Допоміжні засоби нативної цілі approval/прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді exec/plugin approval |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні засоби runtime-context channel-ів | Узагальнені допоміжні засоби register/get/watch для runtime-context channel-ів |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, шлюзу DM, зовнішнього вмісту та збирання секретів |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway і channel-status patch |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби config | Допоміжні засоби завантаження/запису config |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram, стабільні у fallback, коли surface контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби approval prompt | Exec/plugin approval payload, approval capability/profile helpers, native approval routing/runtime helpers |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби approval auth | Визначення approver, auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби approval client | Допоміжні засоби profile/filter для native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби approval delivery | Адаптери native approval capability/delivery |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби approval gateway | Спільний допоміжний засіб визначення approval gateway |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби approval adapter | Полегшені допоміжні засоби завантаження native approval adapter для гарячих channel entrypoints |
|
||||
| `plugin-sdk/approval-handler-runtime` | Допоміжні засоби approval handler | Ширші допоміжні засоби approval handler runtime; надавайте перевагу вужчим adapter/gateway seams, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби approval target | Допоміжні засоби прив’язки native approval target/account |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби approval reply | Допоміжні засоби payload відповіді exec/plugin approval |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні засоби channel runtime-context | Узагальнені допоміжні засоби register/get/watch для channel runtime-context |
|
||||
| `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, DM gating, external-content і collection secret-ів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби шлюзу діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого cache | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби diagnostic gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби error graph |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch/proxy | `resolveFetch`, допоміжні засоби proxy |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці policy |
|
||||
| `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Шлюз команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд |
|
||||
| `plugin-sdk/command-auth` | Допоміжні засоби gating команд і command-surface | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд |
|
||||
| `plugin-sdk/command-status` | Рендерери статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
|
||||
| `plugin-sdk/secret-input` | Аналіз секретного введення | Допоміжні засоби секретного введення |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілі Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідна диспетчеризація, Heartbeat, планувальник відповіді, чанкування |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Допоміжні засоби finalize + диспетчеризації provider-а |
|
||||
| `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні засоби чанків відповіді | Допоміжні засоби чанкування тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні засоби статусу channel-ів | Білдери підсумків статусу channel-ів/облікових записів, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби визначення цілей |
|
||||
| `plugin-sdk/secret-input` | Аналіз secret input | Допоміжні засоби secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти target Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла Webhook-запиту | Допоміжні засоби читання/обмеження тіла запиту |
|
||||
| `plugin-sdk/reply-runtime` | Спільний reply runtime | Inbound dispatch, Heartbeat, планувальник reply, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби reply dispatch | Допоміжні засоби finalize + provider dispatch |
|
||||
| `plugin-sdk/reply-history` | Допоміжні засоби reply-history | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Планування reply reference | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Допоміжні засоби reply chunk | Допоміжні засоби text/markdown chunking |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби session store | Допоміжні засоби шляху store + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби state path | Допоміжні засоби каталогів state і OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key |
|
||||
| `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори зведення статусу каналу/облікового запису, типові значення runtime-state, допоміжні засоби metadata проблем |
|
||||
| `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-payload` | Витягування payload tool | Витягування нормалізованих payload з об’єктів результатів tool |
|
||||
| `plugin-sdk/tool-send` | Витягування send tool | Витягування канонічних полів цілі send з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистеми та редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-table | Допоміжні засоби режиму markdown-table |
|
||||
| `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи 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 auth provider-а | Допоміжні засоби визначення API-ключа runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа provider-а | Допоміжні засоби онбордингу/запису профілю API-ключа |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні засоби auth-result provider-а | Стандартний білдер OAuth auth-result |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного login provider-а | Спільні допоміжні засоби інтерактивного login |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби env-var provider-а | Допоміжні засоби пошуку env-var auth provider-а |
|
||||
| `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay provider-а | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні білдери політики replay, допоміжні засоби endpoint provider-а та нормалізації model-id |
|
||||
| `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider-ів | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Патчі онбордингу provider-а | Допоміжні засоби конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider-а | Узагальнені допоміжні засоби HTTP/можливостей endpoint provider-а |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider-а | Допоміжні засоби реєстрації/кешу provider-а web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search provider-а | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider-ів, яким не потрібна прив’язка ввімкнення Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search provider-а | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped сетери/гетери облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби web-search provider-а | Допоміжні засоби реєстрації/кешу/runtime provider-а web-search |
|
||||
| `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`, типи обгорток потоку та спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту provider-а | Нативні допоміжні засоби транспорту provider-а, як-от guarded fetch, перетворення транспортних повідомлень і потоки записуваних транспортних подій |
|
||||
| `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягування рядкових URL із request-подібних вхідних даних |
|
||||
| `plugin-sdk/run-command` | Допоміжні засоби timed command | Виконавець timed command із нормалізованими stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягування tool payload | Витягування нормалізованих payload із об’єктів результатів tool |
|
||||
| `plugin-sdk/tool-send` | Витягування tool send | Витягування канонічних полів target надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Допоміжні засоби temp path | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logging | Допоміжні засоби subsystem logger і редагування чутливих даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-table | Допоміжні засоби режимів markdown table |
|
||||
| `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи reply payload |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted провайдера | Допоміжні засоби виявлення/config self-hosted провайдера |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/config self-hosted провайдера |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime провайдера | Допоміжні засоби визначення API-ключа runtime |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби onboarding/profile-write API-ключа |
|
||||
| `plugin-sdk/provider-auth-result` | Допоміжні засоби auth-result провайдера | Стандартний конструктор OAuth auth-result |
|
||||
| `plugin-sdk/provider-auth-login` | Допоміжні засоби interactive login провайдера | Спільні допоміжні засоби interactive login |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби env-var провайдера | Допоміжні засоби пошуку env-var auth провайдера |
|
||||
| `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` | Патчі onboarding провайдера | Допоміжні засоби config для onboarding |
|
||||
| `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера, зокрема допоміжні засоби multipart form для транскрипції аудіо |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/cache провайдера web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби config web-search провайдера | Вузькі допоміжні засоби config/облікових даних web-search для провайдерів, яким не потрібна прив’язка вмикання plugin-а |
|
||||
| `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту config/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/cache/runtime провайдера web-search |
|
||||
| `plugin-sdk/provider-tools` | Допоміжні засоби compat для tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + diagnostics, а також допоміжні засоби compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | Допоміжні засоби usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби usage провайдера |
|
||||
| `plugin-sdk/provider-stream` | Допоміжні засоби wrapper для stream провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи wrapper-ів stream, а також спільні допоміжні засоби wrapper-ів для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Допоміжні засоби нативного транспорту провайдера, такі як guarded fetch, перетворення transport message і writable transport event streams |
|
||||
| `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби media | Допоміжні засоби fetch/transform/store media, а також білдери media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації media | Спільні допоміжні засоби failover, вибір кандидатів і повідомлення про відсутні моделі для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи provider-ів media understanding, а також експорти допоміжних засобів зображень/аудіо для provider-ів |
|
||||
| `plugin-sdk/text-runtime` | Спільні текстові допоміжні засоби | Видалення тексту, видимого помічнику, допоміжні засоби рендерингу/чанкування/таблиць markdown, редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні засоби чанкування тексту | Допоміжний засіб чанкування вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні засоби speech | Типи provider-ів speech, а також допоміжні засоби директив, реєстру та валідації для provider-ів |
|
||||
| `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider-ів speech, реєстр, директиви, нормалізація |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи provider-ів, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи provider-ів і допоміжні засоби реєстру |
|
||||
| `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, auth і допоміжні засоби реєстру |
|
||||
| `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи provider-ів/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук provider-а та аналіз model-ref |
|
||||
| `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи provider-ів/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук provider-а та аналіз model-ref |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивної відповіді | Нормалізація/зведення payload інтерактивної відповіді |
|
||||
| `plugin-sdk/channel-config-primitives` | Примітиви конфігурації channel-ів | Вузькі примітиви config-schema channel-ів |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації channel-ів | Допоміжні засоби авторизації запису конфігурації channel-ів |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільна преамбула channel-ів | Експорти спільної преамбули channel plugin-ів |
|
||||
| `plugin-sdk/channel-status` | Допоміжні засоби статусу channel-ів | Спільні допоміжні засоби snapshot/summary статусу channel-ів |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби ухвалення рішень щодо доступу до груп |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard direct-DM |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби media | Допоміжні засоби fetch/transform/store для media, а також конструктори media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації media | Спільні допоміжні засоби failover, вибору candidate і повідомлень про відсутню model для генерації зображень/відео/музики |
|
||||
| `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдерів media understanding, а також provider-facing експорти допоміжних засобів для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення тексту, видимого для асистента, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування чутливих даних, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби text/logging |
|
||||
| `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Допоміжні засоби speech | Типи провайдерів speech, а також provider-facing допоміжні засоби директив, реєстру й валідації |
|
||||
| `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдерів speech, реєстр, директиви, нормалізація |
|
||||
| `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в реальному часі | Типи провайдерів, допоміжні засоби реєстру та спільний допоміжний засіб WebSocket session |
|
||||
| `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи провайдерів і допоміжні засоби реєстру |
|
||||
| `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/interactive-runtime` | Допоміжні засоби interactive reply | Нормалізація/редукція payload interactive reply |
|
||||
| `plugin-sdk/channel-config-primitives` | Примітиви config каналу | Вузькі примітиви channel config-schema |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби запису config каналу | Допоміжні засоби авторизації запису config каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude channel plugin |
|
||||
| `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби config allowlist | Допоміжні засоби редагування/читання config allowlist |
|
||||
| `plugin-sdk/group-access` | Допоміжні засоби доступу до group | Спільні допоміжні засоби рішень щодо доступу до group |
|
||||
| `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard для direct-DM |
|
||||
| `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status і ambient proxy |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддаленого/локального media |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби target Webhook | Допоміжні засоби реєстру target Webhook і встановлення route |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби шляху Webhook | Допоміжні засоби нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних media |
|
||||
| `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів менеджера пам’яті/конфігурації/файлів/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексу/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста пам’яті | Експорти базового рушія хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і узагальнені допоміжні засоби batch/remote; конкретні віддалені provider-и розміщуються у plugin-ах, яким вони належать |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Експорти рушія сховища хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | Мультимодальні допоміжні засоби хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Базовий runtime хоста пам’яті | Допоміжні засоби базового runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім базового runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів базового runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `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` | Базовий engine memory host | Експорти базового engine memory host |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Engine embedding-ів memory host | Контракти embedding-ів пам’яті, доступ до реєстру, локальний провайдер і узагальнені допоміжні засоби batch/remote; конкретні віддалені провайдери розміщуються у plugin-ах, яким вони належать |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | QMD engine memory host | Експорти QMD engine memory host |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Engine сховища memory host | Експорти engine сховища memory host |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal memory host | Допоміжні засоби multimodal memory host |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів memory host | Допоміжні засоби запитів memory host |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret memory host | Допоміжні засоби secret memory host |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій memory host | Допоміжні засоби журналу подій memory host |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу memory host | Допоміжні засоби статусу memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime memory host | Допоміжні засоби CLI runtime memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime memory host | Допоміжні засоби core runtime memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби file/runtime memory host | Допоміжні засоби file/runtime memory host |
|
||||
| `plugin-sdk/memory-host-core` | Псевдонім core runtime memory host | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime memory host |
|
||||
| `plugin-sdk/memory-host-events` | Псевдонім журналу подій memory host | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій memory host |
|
||||
| `plugin-sdk/memory-host-files` | Псевдонім file/runtime memory host | Нейтральний до постачальника псевдонім для допоміжних засобів file/runtime memory host |
|
||||
| `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugin-ів, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active memory |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory |
|
||||
| `plugin-sdk/memory-host-status` | Псевдонім статусу memory host | Нейтральний до постачальника псевдонім для допоміжних засобів статусу memory host |
|
||||
| `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb |
|
||||
| `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mock-и |
|
||||
| `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks |
|
||||
</Accordion>
|
||||
|
||||
Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною
|
||||
поверхнею SDK. Повний список із понад 200 точок входу міститься в
|
||||
Ця таблиця навмисно містить поширену підмножину для міграції, а не всю
|
||||
поверхню SDK. Повний список із понад 200 точок входу міститься у
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Цей список усе ще включає деякі допоміжні поверхні вбудованих plugin-ів, як-от
|
||||
Цей список усе ще містить деякі seams допоміжних засобів вбудованих plugin-ів, такі як
|
||||
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
|
||||
`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для
|
||||
підтримки та сумісності вбудованих plugin-ів, але навмисно
|
||||
не включені до поширеної таблиці міграції та не є рекомендованою ціллю для
|
||||
не включені до таблиці поширеної міграції та не є рекомендованою ціллю для
|
||||
нового коду plugin-ів.
|
||||
|
||||
Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як:
|
||||
@ -357,7 +343,7 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
- Matrix: `plugin-sdk/matrix*`
|
||||
- LINE: `plugin-sdk/line*`
|
||||
- IRC: `plugin-sdk/irc*`
|
||||
- поверхні вбудованих допоміжних засобів/plugin-ів, як-от `plugin-sdk/googlechat`,
|
||||
- поверхні вбудованих допоміжних засобів/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`,
|
||||
@ -366,26 +352,26 @@ plugin-и не повинні їх використовувати, а наявн
|
||||
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
|
||||
`plugin-sdk/thread-ownership` і `plugin-sdk/voice-call`
|
||||
|
||||
`plugin-sdk/github-copilot-token` наразі надає вузьку
|
||||
поверхню допоміжних засобів токенів `DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`plugin-sdk/github-copilot-token` зараз надає вузьку поверхню допоміжних засобів токена:
|
||||
`DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`.
|
||||
|
||||
Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти експорт,
|
||||
Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти експорт,
|
||||
перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord.
|
||||
|
||||
## Хронологія вилучення
|
||||
## Часова шкала видалення
|
||||
|
||||
| Коли | Що відбувається |
|
||||
| Коли | Що відбувається |
|
||||
| ---------------------- | ----------------------------------------------------------------------- |
|
||||
| **Зараз** | Застарілі поверхні виводять попередження під час виконання |
|
||||
| **Наступний мажорний реліз** | Застарілі поверхні буде вилучено; plugin-и, які все ще їх використовують, не працюватимуть |
|
||||
| **Зараз** | Застарілі поверхні виводять попередження під час виконання |
|
||||
| **Наступний великий випуск** | Застарілі поверхні буде видалено; plugin-и, які досі їх використовують, перестануть працювати |
|
||||
|
||||
Усі core plugin-и вже мігровано. Зовнішнім plugin-ам слід виконати
|
||||
міграцію до наступного мажорного релізу.
|
||||
Усі core plugin-и вже мігровано. Зовнішні plugin-и мають виконати
|
||||
міграцію до наступного великого випуску.
|
||||
|
||||
## Тимчасове приглушення попереджень
|
||||
|
||||
Установіть ці змінні середовища, поки працюєте над міграцією:
|
||||
Встановіть ці змінні середовища, поки працюєте над міграцією:
|
||||
|
||||
```bash
|
||||
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
|
||||
@ -396,9 +382,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів
|
||||
- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів за підшляхами
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugin-ів
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugin-ів
|
||||
- [Внутрішня будова plugin-ів](/uk/plugins/architecture) — детальний розбір архітектури
|
||||
- [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту
|
||||
- [Внутрішня будова plugin-ів](/uk/plugins/architecture) — глибший огляд архітектури
|
||||
- [Маніфест plugin-а](/uk/plugins/manifest) — довідник зі схеми маніфесту
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібно знати, з якого підшляху SDK імпортувати
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
- Вам потрібно знати, з якого підшляху SDK імпортувати.
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi.
|
||||
- Ви шукаєте конкретний експорт SDK.
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T02:58:55Z"
|
||||
generated_at: "2026-04-23T03:31:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 947f309c36e0a4d9c20639f5e18bc1b9d9e07af333414741ad36f24017716ae1
|
||||
source_hash: 5f9608fa3194b1b1609d16d7e2077ea58de097e9e8d4cedef4cb975adfb92938
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Огляд Plugin SDK
|
||||
|
||||
Plugin SDK — це типізований контракт між plugins і core. Ця сторінка є
|
||||
довідником щодо **що імпортувати** і **що можна реєструвати**.
|
||||
Plugin SDK — це типізований контракт між plugin-ами та core. Ця сторінка є
|
||||
довідником про **що імпортувати** і **що можна зареєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте практичний посібник?**
|
||||
**Шукаєте покроковий посібник?**
|
||||
- Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins)
|
||||
- Channel plugin? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Provider 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)
|
||||
</Tip>
|
||||
|
||||
## Угода щодо імпорту
|
||||
@ -36,39 +36,39 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий
|
||||
запуск і запобігає проблемам із циклічними залежностями. Для специфічних для channel
|
||||
допоміжних засобів входу/збирання надавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
|
||||
ширшої узагальнювальної поверхні та спільних допоміжних засобів, таких як
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і
|
||||
запобігає проблемам із циклічними залежностями. Для специфічних для каналу
|
||||
хелперів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core`
|
||||
залишайте для ширшої umbrella-поверхні та спільних хелперів, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Не додавайте і не використовуйте зручні seams з назвами providers, такі як
|
||||
Не додавайте й не використовуйте seam-и з provider-орієнтованими назвами для зручності, такі як
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або
|
||||
допоміжні seams із брендуванням channel. Вбудовані plugins мають компонувати узагальнені
|
||||
брендовані для каналу seam-и хелперів. Вбудовані plugin-и мають компонувати загальні
|
||||
підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core
|
||||
має або використовувати ці локальні для plugin barrel-файли, або додавати вузький узагальнений SDK
|
||||
контракт, коли потреба справді є міжканальною.
|
||||
має або використовувати ці локальні для plugin-а barrel-файли, або додавати вузький загальний SDK
|
||||
контракт, коли потреба справді охоплює кілька каналів.
|
||||
|
||||
Згенерована карта експорту все ще містить невеликий набір допоміжних
|
||||
seams для вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
Згенерована карта експортів усе ще містить невеликий набір seam-ів хелперів для вбудованих plugin-ів,
|
||||
таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці
|
||||
підшляхи існують лише для супроводу вбудованих plugins і сумісності; їх
|
||||
навмисно пропущено в поширеній таблиці нижче, і вони не є рекомендованим
|
||||
шляхом імпорту для нових сторонніх plugins.
|
||||
підшляхи існують лише для підтримки та сумісності вбудованих plugin-ів; їх
|
||||
навмисно не включено до поширеної таблиці нижче, і вони не є рекомендованими
|
||||
шляхами імпорту для нових сторонніх plugin-ів.
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із
|
||||
понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому
|
||||
згенерованому списку. Розглядайте їх як деталі реалізації/поверхні сумісності, якщо лише сторінка документації
|
||||
явно не просуває один із них як публічний.
|
||||
Зарезервовані підшляхи хелперів для вбудованих plugin-ів усе ще з’являються в цьому згенерованому списку.
|
||||
Вважайте їх деталями реалізації/поверхнями сумісності, якщо лише сторінка документації
|
||||
явно не позначає один із них як публічний.
|
||||
|
||||
### Вхід plugin
|
||||
### Точка входу plugin-а
|
||||
|
||||
| Subpath | Ключові експорти |
|
||||
| Subpath | Key exports |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
@ -76,245 +76,245 @@ seams для вбудованих plugins, таких як `plugin-sdk/feishu`,
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи channel">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/config-schema` | Кореневий експорт Zod-схеми `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, побудовники статусу налаштування |
|
||||
| `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` | Допоміжні засоби multi-account config/action-gate, допоміжні засоби резервного варіанта облікового запису за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id |
|
||||
| `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного варіанта за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби account-list/account-action |
|
||||
| `plugin-sdk/account-core` | Хелпери для конфігурації та action-gate з кількома обліковими записами, хелпери fallback для облікового запису за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, хелпери нормалізації ідентифікатора облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Пошук облікового запису + хелпери fallback до облікового запису за замовчуванням |
|
||||
| `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` | Типи схеми конфігурації channel |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним варіантом контракту вбудованого plugin |
|
||||
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд |
|
||||
| `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Хелпери нормалізації/валідації користувацьких команд Telegram із fallback на контракт вбудованого plugin-а |
|
||||
| `plugin-sdk/command-gating` | Вузькі хелпери gate авторизації команд |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернетки |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних даних і побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й диспетчеризації вхідних відповідей |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності, делегата надсилання та планування payload |
|
||||
| `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок thread і адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа-payload агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки conversation/thread, pairing і налаштованих прив’язок |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy у runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/зведення статусу channel |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації channel |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації channel |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні експортовані елементи prelude для channel plugin |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо group-access |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямого DM |
|
||||
| `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Message Presentation](/uk/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | Барель сумісності для debounce вхідних даних, зіставлення mention, допоміжних засобів mention-policy та допоміжних засобів envelope |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy без ширшої поверхні runtime вхідних даних |
|
||||
| `plugin-sdk/channel-location` | Допоміжні засоби контексту та форматування розташування channel |
|
||||
| `plugin-sdk/channel-logging` | Допоміжні засоби журналювання channel для відкидання вхідних даних і збоїв typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів відповіді |
|
||||
| `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями channel, а також застарілі допоміжні засоби native schema, збережені для сумісності plugin |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контрактів channel |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, хелпери життєвого циклу/фіналізації чернеткового потоку |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні хелпери побудови вхідного маршруту та envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні хелпери запису та диспетчеризації вхідних відповідей |
|
||||
| `plugin-sdk/messaging-targets` | Хелпери парсингу/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні хелпери завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Хелпери вихідної ідентичності, send delegate і планування payload |
|
||||
| `plugin-sdk/poll-runtime` | Вузькі хелпери нормалізації опитувань |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Хелпери життєвого циклу прив’язок потоку та адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий конструктор media payload агента |
|
||||
| `plugin-sdk/conversation-runtime` | Хелпери прив’язки conversation/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 статусу каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Хелпери авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin-а |
|
||||
| `plugin-sdk/allowlist-config-edit` | Хелпери редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні хелпери рішень щодо group-access |
|
||||
| `plugin-sdk/direct-dm` | Спільні хелпери auth/guard для прямого DM |
|
||||
| `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі хелпери інтерактивних відповідей. Див. [Message Presentation](/uk/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, хелперів mention-policy та хелперів envelope |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі хелпери mention-policy без ширшої поверхні inbound runtime |
|
||||
| `plugin-sdk/channel-location` | Хелпери контексту та форматування розташування каналу |
|
||||
| `plugin-sdk/channel-logging` | Хелпери логування каналу для пропусків inbound і збоїв typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | Типи результату відповіді |
|
||||
| `plugin-sdk/channel-actions` | Хелпери message-action каналу, а також застарілі хелпери нативної schema, збережені для сумісності plugin-ів |
|
||||
| `plugin-sdk/channel-targets` | Хелпери парсингу/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контракту каналу |
|
||||
| `plugin-sdk/channel-feedback` | Підключення feedback/reaction |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі хелпери secret-контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи provider">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи provider-ів">
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `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` | Стандартний побудовник результату auth OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider plugins |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env-var для auth provider |
|
||||
| `plugin-sdk/provider-setup` | Кураторські хелпери налаштування локальних/self-hosted provider-ів |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані хелпери налаштування self-hosted provider-ів, сумісних з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Значення за замовчуванням CLI backend + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Хелпери визначення API key у runtime для provider plugin-ів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Хелпери онбордингу/запису профілю API key, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth auth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні хелпери інтерактивного входу для provider plugin-ів |
|
||||
| `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 provider і допоміжні засоби нормалізації 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 provider |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби contract config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування provider для web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для providers, яким не потрібне підключення enable plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби contract config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і засоби встановлення/отримання credential з областю дії |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime provider для web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | Загальні хелпери HTTP/endpoint capability provider-а, зокрема хелпери multipart form для транскрипції аудіо |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі хелпери контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Хелпери реєстрації/кешу provider-а web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі хелпери config/credential для web-search для provider-ів, яким не потрібне підключення enable plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі хелпери контракту config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для credentials |
|
||||
| `plugin-sdk/provider-web-search` | Хелпери реєстрації/кешу/runtime provider-а web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення schema Gemini + діагностика, а також хелпери сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби нативного транспорту provider, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту з можливістю запису |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні хелпери обгорток для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Нативні хелпери транспорту provider-а, такі як guarded fetch, перетворення transport message і потоки подій writable transport |
|
||||
| `plugin-sdk/provider-onboard` | Хелпери patch конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Хелпери process-local singleton/map/cache |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи auth і безпеки">
|
||||
| Subpath | Ключові експорти |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника |
|
||||
| `plugin-sdk/command-status` | Побудовники повідомлень command/help, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
|
||||
| `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-gateway-runtime` | Спільний допоміжний засіб визначення Gateway approval |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні засоби завантаження адаптера native approval для гарячих entrypoint channel |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника approval; надавайте перевагу вужчим adapter/gateway seams, коли їх достатньо |
|
||||
| `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 command auth + native session-target |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
|
||||
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації command-body і command-surface |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, хелпери реєстру команд, хелпери авторизації відправника |
|
||||
| `plugin-sdk/command-status` | Конструктори команд/довідкових повідомлень, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Хелпери визначення approver-а та auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Хелпери профілю/фільтра native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Native адаптери capability/delivery для approval |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Спільний хелпер визначення approval Gateway |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Легковагові хелпери завантаження native адаптера approval для hot entrypoint-ів каналу |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші хелпери runtime обробника approval; віддавайте перевагу вужчим seam-ам adapter/gateway, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Native хелпери target + account-binding для approval |
|
||||
| `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` | Хелпери нормалізації command-body і command-surface |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `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, external-content і збирання secret |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватної мережі |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні засоби розбору введення secret |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout запиту |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі хелпери збирання secret-контрактів для secret-поверхонь channel/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі хелпери `coerceSecretRef` і типізації SecretRef для парсингу secret-контрактів/конфігурації |
|
||||
| `plugin-sdk/security-runtime` | Спільні хелпери довіри, DM gating, зовнішнього вмісту та збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Хелпери політики SSRF для host allowlist і приватних мереж |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі хелпери pinned-dispatcher без широкої infra runtime-поверхні |
|
||||
| `plugin-sdk/ssrf-runtime` | Хелпери pinned-dispatcher, fetch із захистом SSRF та політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Хелпери парсингу secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Хелпери запитів/цілей Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Хелпери розміру body/тайм-ауту запиту |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Subpath | Ключові експорти |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Узагальнені допоміжні засоби реєстрації та пошуку runtime-context channel |
|
||||
| `plugin-sdk/runtime` | Широкі хелпери runtime/logging/backup/встановлення plugin-ів |
|
||||
| `plugin-sdk/runtime-env` | Вузькі хелпери runtime env, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Загальні хелпери реєстрації та пошуку channel runtime-context |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і виправлення статусу channel |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису config і пошуку config plugin |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назви/опису команди Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники можливостей approval, допоміжні засоби auth/profile, допоміжні засоби native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, Heartbeat, планувальник відповіді |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби reply-history для короткого вікна, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні хелпери команд/хуків/http/interactive для plugin-ів |
|
||||
| `plugin-sdk/hook-runtime` | Спільні хелпери pipeline для Webhook/внутрішніх hook-ів |
|
||||
| `plugin-sdk/lazy-runtime` | Хелпери lazy імпорту/прив’язування runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Хелпери exec процесів |
|
||||
| `plugin-sdk/cli-runtime` | Хелпери форматування CLI, очікування та версій |
|
||||
| `plugin-sdk/gateway-runtime` | Хелпери Gateway client і patch статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Хелпери завантаження/запису конфігурації та пошуку конфігурації plugin-а |
|
||||
| `plugin-sdk/telegram-command-config` | Хелпери нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel `text-runtime` |
|
||||
| `plugin-sdk/approval-runtime` | Хелпери exec/plugin approval, конструктори capability approval, хелпери auth/profile, native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні хелпери inbound/reply runtime, chunking, dispatch, Heartbeat, planner відповіді |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі хелпери dispatch/finalize відповіді |
|
||||
| `plugin-sdk/reply-history` | Спільні хелпери reply-history для короткого вікна, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби прив’язки route/session-key/account, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу channel/account, значення runtime-state за замовчуванням і допоміжні засоби метаданих issue |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/string |
|
||||
| `plugin-sdk/request-url` | Витягування рядкових URL із вхідних даних типу fetch/request |
|
||||
| `plugin-sdk/run-command` | Timed runner команд із нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Поширені засоби читання параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool |
|
||||
| `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe зберігання на диску |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язки ACP лише для читання без імпортів запуску життєвого циклу |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Гнучкий засіб читання boolean param |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів dangerous-name |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токена pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді provider для команди `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби виведення списку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих agent harnesses: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби мосту інструментів OpenClaw і утиліти результатів attempt |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби прапорців і подій діагностики |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі хелпери chunking для text/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Хелпери шляху session store + updated-at |
|
||||
| `plugin-sdk/state-paths` | Хелпери шляхів до каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Хелпери route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні хелпери summary статусу каналу/облікового запису, значення runtime-state за замовчуванням і хелпери metadata проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні хелпери визначення цілей |
|
||||
| `plugin-sdk/string-normalization-runtime` | Хелпери нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Витягання URL-рядків із вхідних даних типу fetch/request |
|
||||
| `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягання нормалізованих payload із об’єктів результатів tool |
|
||||
| `plugin-sdk/tool-send` | Витягання канонічних полів цілі надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-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/persistent-dedupe` | Хелпери dedupe cache з дисковим зберіганням |
|
||||
| `plugin-sdk/acp-runtime` | Хелпери ACP runtime/session і reply-dispatch |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Визначення ACP binding лише для читання без імпортів запуску життєвого циклу |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Гнучкий читач boolean-параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Хелпери визначення збігів небезпечних назв |
|
||||
| `plugin-sdk/device-bootstrap` | Хелпери bootstrap пристрою та токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви хелперів passive-channel, status і ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Хелпери відповіді для команди `/models` / provider-а |
|
||||
| `plugin-sdk/skill-commands-runtime` | Хелпери списку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Хелпери реєстру/build/serialize для native команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness-ів агента: типи harness, хелпери steer/abort для active-run, хелпери моста tool OpenClaw і утиліти результатів attempt |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Хелпери виявлення endpoint Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | Хелпери системних подій/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі хелпери обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Хелпери діагностичних прапорців і подій |
|
||||
| `plugin-sdk/error-runtime` | Хелпери графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Хелпери обгорнутого fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch |
|
||||
| `plugin-sdk/response-limit-runtime` | Засіб читання обмеженого body відповіді без широкої поверхні media runtime |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації налаштованих binding або сховищ pairing |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби читання session-store без широких імпортів запису/обслуговування config |
|
||||
| `plugin-sdk/response-limit-runtime` | Читач обмеженого body відповіді без широкої media runtime-поверхні |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан binding conversation без configured binding routing або pairing store |
|
||||
| `plugin-sdk/session-store-runtime` | Хелпери читання session-store без широких імпортів запису/обслуговування конфігурації |
|
||||
| `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
|
||||
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і хоста SCP |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби config retry і runner retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогу на основі config |
|
||||
| `plugin-sdk/string-coerce-runtime` | Вузькі хелпери приведення й нормалізації primitive record/string без імпортів markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Хелпери нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Хелпери конфігурації retry і виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Хелпери каталогу/ідентичності/workspace агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/dedup каталогу на основі конфігурації |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи capability і тестування">
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover генерації медіа, вибір candidate і повідомлення про відсутню model |
|
||||
| `plugin-sdk/media-understanding` | Типи provider для розуміння медіа, а також експорти допоміжних засобів image/audio для provider |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення assistant-visible-text, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби directive-tag і утиліти safe-text |
|
||||
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи provider для speech, а також допоміжні засоби directive, registry і validation для provider |
|
||||
| `plugin-sdk/speech-core` | Спільні типи provider для speech, допоміжні засоби registry, directive і normalizaton |
|
||||
| `plugin-sdk/realtime-transcription` | Типи provider для realtime transcription, допоміжні засоби registry і спільний допоміжний засіб сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Типи provider для realtime voice і допоміжні засоби registry |
|
||||
| `plugin-sdk/image-generation` | Типи provider для генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і registry |
|
||||
| `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення route |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK |
|
||||
| `plugin-sdk/media-runtime` | Спільні хелпери fetch/transform/store для медіа, а також конструктори media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні хелпери failover для media generation, вибір кандидатів і повідомлення про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи provider-а media understanding, а також provider-facing експорти хелперів для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні хелпери text/markdown/logging, такі як видалення видимого для асистента тексту, хелпери render/chunking/table для Markdown, хелпери редагування чутливих даних, хелпери тегів директив і утиліти безпечного тексту |
|
||||
| `plugin-sdk/text-chunking` | Хелпер chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи speech provider-а, а також provider-facing хелпери директив, реєстру та валідації |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech provider-а, хелпери реєстру, директив і нормалізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи provider-а realtime transcription, хелпери реєстру та спільний хелпер WebSocket session |
|
||||
| `plugin-sdk/realtime-voice` | Типи provider-а realtime voice і хелпери реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи provider-а image generation |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи image generation, хелпери failover, auth і реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи provider-а/request/result для генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, хелпери failover, пошук provider-а та парсинг model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи provider-а/request/result для генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, хелпери failover, пошук provider-а та парсинг model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Хелпери реєстру цілей Webhook і встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Хелпери нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні хелпери завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи Memory">
|
||||
| Subpath | Ключові експорти |
|
||||
| Subpath | Key exports |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку Memory |
|
||||
| `plugin-sdk/memory-core` | Поверхня хелперів bundled memory-core для хелперів manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексу/пошуку Memory |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до registry, локальний provider і узагальнені пакетні/віддалені допоміжні засоби |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний provider і загальні хелпери batch/remote |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних засобів core runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних засобів журналу подій хоста Memory |
|
||||
| `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних засобів файлів/runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugins, суміжних із memory |
|
||||
| `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до manager пошуку |
|
||||
| `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста Memory |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні хелпери хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-query` | Хелпери запитів хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-secret` | Secret-хелпери хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-events` | Хелпери журналу подій хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-status` | Хелпери статусу хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Хелпери CLI runtime хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Хелпери core runtime хоста Memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Хелпери file/runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-core` | Vendor-neutral псевдонім для хелперів core runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-events` | Vendor-neutral псевдонім для хелперів журналу подій хоста Memory |
|
||||
| `plugin-sdk/memory-host-files` | Vendor-neutral псевдонім для хелперів file/runtime хоста Memory |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні хелпери managed-markdown для plugin-ів, суміжних із memory |
|
||||
| `plugin-sdk/memory-host-search` | Active Memory runtime facade для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Vendor-neutral псевдонім для хелперів статусу хоста Memory |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня хелперів bundled memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи допоміжних засобів для вбудованих plugins">
|
||||
| Family | Поточні підшляхи | Призначене використання |
|
||||
<Accordion title="Зарезервовані підшляхи bundled-helper">
|
||||
| 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` | Поверхня допоміжних засобів/runtime вбудованого Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime вбудованого LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого 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` | Поверхні сумісності/допоміжних засобів вбудованих 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` | Поверхні допоміжних засобів вбудованих функцій/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-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` | Seam-и сумісності/хелперів bundled channel |
|
||||
| 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` | Seam-и хелперів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -323,69 +323,69 @@ seams для вбудованих plugins, таких як `plugin-sdk/feishu`,
|
||||
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
### Реєстрація capability
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------------ | ------------------------------------ |
|
||||
| `api.registerProvider(...)` | Виведення тексту (LLM) |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
|
||||
| `api.registerCliBackend(...)` | Локальний backend виведення CLI |
|
||||
| `api.registerChannel(...)` | Канал повідомлень |
|
||||
| `api.registerSpeechProvider(...)` | Text-to-speech / синтез STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в realtime |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні сеанси голосу в realtime |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
| `api.registerCliBackend(...)` | Локальний CLI backend inference |
|
||||
| `api.registerChannel(...)` | Канал повідомлень |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Provider веб-отримання / скрапінгу |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
|
||||
### Інструменти та команди
|
||||
### Tools і команди
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------- | ------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
| Method | What it registers |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Tool агента (обов’язковий або `{ 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.registerEmbeddedExtensionFactory(factory)` | Фабрика extension вбудованого runner для Pi |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція prompt, суміжна з memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний corpus пошуку/читання memory |
|
||||
| Method | What it registers |
|
||||
| ----------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook подій |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фонова служба |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| `api.registerEmbeddedExtensionFactory(factory)` | Фабрика розширень вбудованого runner-а Pi |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt-а, суміжний із memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус для пошуку/читання memory |
|
||||
|
||||
Зарезервовані простори назв admin у core (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
Зарезервовані core admin-простори імен (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
|
||||
вужчу область методу Gateway. Для методів, що належать plugin,
|
||||
надавайте перевагу префіксам, специфічним для plugin.
|
||||
вужчу область gateway method. Для методів,
|
||||
що належать plugin-у, віддавайте перевагу префіксам, специфічним для plugin-а.
|
||||
|
||||
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin потребує нативного для Pi
|
||||
таймінгу подій під час вбудованих запусків OpenClaw, наприклад для асинхронних переписувань `tool_result`,
|
||||
які мають відбутися до того, як буде надіслано фінальне повідомлення з результатом інструмента.
|
||||
Сьогодні це surface для вбудованих plugins: лише вбудовані plugins можуть реєструвати її, і
|
||||
вони мають оголошувати `contracts.embeddedExtensionFactories: ["pi"]` у
|
||||
`openclaw.plugin.json`. Залишайте звичайні хук-и OpenClaw plugin для всього,
|
||||
що не потребує цього низькорівневого seam.
|
||||
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin-у потрібен
|
||||
власний для Pi таймінг подій під час вбудованих запусків OpenClaw, наприклад асинхронні перезаписи
|
||||
`tool_result`, які мають відбутися до того, як буде надіслано фінальне повідомлення про результат tool.
|
||||
Сьогодні це seam для bundled plugin-ів: лише bundled plugin-и можуть реєструвати такий seam, і
|
||||
вони мають оголосити `contracts.embeddedExtensionFactories: ["pi"]` у
|
||||
`openclaw.plugin.json`. Залишайте звичайні hook-и plugin-ів OpenClaw для всього,
|
||||
що не потребує цього seam нижчого рівня.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, якими володіє registrar
|
||||
- `descriptors`: дескриптори команд на етапі розбору, що використовуються для кореневої довідки CLI,
|
||||
маршрутизації та відкладеної реєстрації CLI plugin
|
||||
- `commands`: явні корені команд, що належать реєстратору
|
||||
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI,
|
||||
маршрутизації та lazy-реєстрації CLI plugin-а
|
||||
|
||||
Якщо ви хочете, щоб команда plugin залишалася відкладено завантажуваною у звичайному кореневому шляху CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що його відкриває
|
||||
цей registrar.
|
||||
Якщо ви хочете, щоб команда plugin-а залишалася lazy-loaded у звичайному шляху кореневого CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команд верхнього рівня, що їх відкриває
|
||||
цей реєстратор.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -405,138 +405,138 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands`, коли вам не потрібна відкладена реєстрація кореневого CLI.
|
||||
Використовуйте лише `commands`, якщо вам не потрібна lazy-реєстрація кореневого CLI.
|
||||
Цей eager-шлях сумісності залишається підтримуваним, але він не встановлює
|
||||
placeholder-и на основі descriptor для відкладеного завантаження на етапі розбору.
|
||||
placeholder-и на основі descriptor для lazy loading на етапі парсингу.
|
||||
|
||||
### Реєстрація backend CLI
|
||||
### Реєстрація CLI backend
|
||||
|
||||
`api.registerCliBackend(...)` дає змогу plugin володіти конфігурацією за замовчуванням для локального
|
||||
backend AI CLI, такого як `codex-cli`.
|
||||
`api.registerCliBackend(...)` дає plugin-у змогу володіти конфігурацією за замовчуванням для локального
|
||||
AI CLI backend, такого як `codex-cli`.
|
||||
|
||||
- `id` backend стає префіксом provider у посиланнях на model, як-от `codex-cli/gpt-5`.
|
||||
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- `id` backend-а стає префіксом provider-а в посиланнях на моделі, наприклад `codex-cli/gpt-5`.
|
||||
- `config` backend-а використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
|
||||
значення plugin за замовчуванням перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття
|
||||
значення за замовчуванням plugin-а перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує перезаписів сумісності після злиття
|
||||
(наприклад, нормалізації старих форм прапорців).
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфіковану можливість memory |
|
||||
| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt для memory |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для memory |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory |
|
||||
| Method | What it registers |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до prompt-а. |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфікована capability memory |
|
||||
| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt-а для memory |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory |
|
||||
|
||||
### Адаптери embedding для memory
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ---------------------------------------------- | ------------------------------------------ |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin |
|
||||
| Method | What it registers |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin-а |
|
||||
|
||||
- `registerMemoryCapability` — це пріоритетний API ексклюзивного memory-plugin.
|
||||
- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб companion plugins могли споживати експортовані артефакти memory через
|
||||
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватного
|
||||
layout конкретного memory plugin.
|
||||
- `registerMemoryCapability` — це рекомендований API ексклюзивного memory-plugin-а.
|
||||
- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб companion plugin-и могли використовувати експортовані артефакти memory через
|
||||
`openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватного
|
||||
компонування конкретного memory plugin-а.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` — це сумісні зі спадщиною API ексклюзивного memory-plugin.
|
||||
- `registerMemoryEmbeddingProvider` дає змогу активному memory plugin реєструвати один
|
||||
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький id,
|
||||
визначений plugin).
|
||||
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих
|
||||
id адаптерів.
|
||||
`registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивного memory-plugin-а.
|
||||
- `registerMemoryEmbeddingProvider` дає активному memory plugin-у змогу реєструвати один
|
||||
або кілька ідентифікаторів адаптерів embedding (наприклад, `openai`, `gemini` або користувацький
|
||||
ідентифікатор, визначений plugin-ом).
|
||||
- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, визначається відносно зареєстрованих
|
||||
ідентифікаторів адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Method | Що робить |
|
||||
| -------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| Method | What it does |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки conversation |
|
||||
|
||||
### Семантика рішень hook
|
||||
### Семантика рішень hook-ів
|
||||
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як і пропуск `cancel`), а не перевизначенням.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідних thread/topic. Залишайте `metadata` для специфічних для channel додаткових даних.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для channel `metadata`.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. `metadata` залишайте для додаткових даних, специфічних для каналу.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для каналу `metadata`.
|
||||
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні hook-и `gateway:startup`.
|
||||
|
||||
### Поля об’єкта API
|
||||
|
||||
| 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` | Поточний знімок config (активний знімок runtime у пам’яті, якщо доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Специфічна для plugin config з `plugins.entries.<id>.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 | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `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` | Поточний snapshot конфігурації (активний snapshot runtime у пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для plugin-а, з `plugins.entries.<id>.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-а |
|
||||
|
||||
## Угода щодо внутрішніх модулів
|
||||
|
||||
Усередині вашого 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 # Точка входу plugin-а
|
||||
setup-entry.ts # Легковагова точка входу лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production code. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
із production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Публічні поверхні вбудованих plugins, завантажувані через facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер надають перевагу
|
||||
активному знімку config runtime, якщо OpenClaw уже запущено. Якщо знімок runtime
|
||||
ще не існує, вони повертаються до визначеного config-файлу на диску.
|
||||
Публічні поверхні bundled plugin-ів, завантажені через facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають перевагу
|
||||
активному snapshot конфігурації runtime, коли OpenClaw уже запущено. Якщо snapshot runtime
|
||||
ще не існує, вони повертаються до визначеного файла конфігурації на диску.
|
||||
|
||||
Plugins provider також можуть відкривати вузький локальний barrel контракту plugin, коли
|
||||
допоміжний засіб навмисно є специфічним для provider і ще не належить до узагальненого підшляху SDK.
|
||||
Поточний вбудований приклад: provider Anthropic зберігає свої допоміжні засоби потоку Claude
|
||||
у власному публічному seam `api.ts` / `contract-api.ts` замість
|
||||
просування логіки бета-заголовка Anthropic і `service_tier` в узагальнений
|
||||
контракт `plugin-sdk/*`.
|
||||
Provider plugin-и також можуть надавати вузький локальний barrel контракту plugin-а, коли
|
||||
хелпер навмисно є специфічним для provider-а і ще не належить до загального
|
||||
підшляху SDK. Поточний bundled-приклад: provider Anthropic зберігає свої
|
||||
хелпери потоку Claude у власному публічному seam `api.ts` / `contract-api.ts` замість
|
||||
того, щоб просувати логіку бета-заголовків Anthropic і `service_tier` до загального
|
||||
контракту `plugin-sdk/*`.
|
||||
|
||||
Інші поточні вбудовані приклади:
|
||||
Інші поточні bundled-приклади:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує побудовники provider,
|
||||
допоміжні засоби моделей за замовчуванням і побудовники realtime provider
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник provider, а також
|
||||
допоміжні засоби онбордингу/config
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує конструктори provider-ів,
|
||||
хелпери моделей за замовчуванням і конструктори realtime provider-ів
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор provider-а, а також
|
||||
хелпери onboarding/config
|
||||
|
||||
<Warning>
|
||||
Production code extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжний засіб справді є спільним, перенесіть його в нейтральний підшлях SDK,
|
||||
такий як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншу
|
||||
surface, орієнтовану на можливості, замість зв’язування двох plugins між собою.
|
||||
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо хелпер справді є спільним, перемістіть його до нейтрального підшляху SDK,
|
||||
наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
capability-орієнтованої поверхні, замість того щоб жорстко зв’язувати два plugin-и між собою.
|
||||
</Warning>
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry`
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору назв `api.runtime`
|
||||
- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми config
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime`
|
||||
- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації
|
||||
- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint
|
||||
- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих surfaces
|
||||
- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей
|
||||
- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь
|
||||
- [Plugin Internals](/uk/plugins/architecture) — детальна архітектура й модель capability
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте новий Plugin постачальника моделей
|
||||
- Ви хочете додати до OpenClaw OpenAI-сумісний проксі або власну LLM
|
||||
- Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime-хуки
|
||||
- Ви створюєте новий plugin постачальника моделей
|
||||
- Ви хочете додати до OpenClaw сумісний з OpenAI проксі або користувацьку LLM
|
||||
- Вам потрібно зрозуміти автентифікацію постачальника, каталоги та рантайм-хуки
|
||||
sidebarTitle: Provider Plugins
|
||||
summary: Покроковий посібник зі створення Plugin постачальника моделей для OpenClaw
|
||||
title: Створення Plugin постачальників моделей
|
||||
summary: Покроковий посібник зі створення plugin постачальника моделей для OpenClaw
|
||||
title: Створення plugin постачальників моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T02:58:43Z"
|
||||
generated_at: "2026-04-23T03:31:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b46f72d7f636caf4b072ce84db2af5b6e6f4c8d4b75f6ea102c948c3865353c7
|
||||
source_hash: ba14ad9c9ac35c6209b6533e50ab3a6da0ef0de2ea6a6a4e7bf69bc65d39c484
|
||||
source_path: plugins/sdk-provider-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Створення Plugin постачальників моделей
|
||||
# Створення plugin постачальників моделей
|
||||
|
||||
Цей посібник покроково пояснює створення Plugin постачальника, який додає постачальника моделей
|
||||
Цей посібник пояснює, як створити plugin постачальника, який додає постачальника моделей
|
||||
(LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей,
|
||||
автентифікацією через API-ключ і динамічним визначенням моделей.
|
||||
|
||||
<Info>
|
||||
Якщо ви раніше не створювали жодного Plugin для OpenClaw, спочатку прочитайте
|
||||
[Початок роботи](/uk/plugins/building-plugins) про базову структуру пакета
|
||||
та налаштування маніфесту.
|
||||
Якщо ви раніше не створювали plugin для OpenClaw, спочатку прочитайте
|
||||
[Початок роботи](/uk/plugins/building-plugins) для ознайомлення з базовою
|
||||
структурою пакета та налаштуванням маніфесту.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Plugin постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель
|
||||
має працювати через нативний агент-демон, який керує потоками, Compaction або подіями
|
||||
має працювати через нативний демон агента, який керує потоками, Compaction або подіями
|
||||
інструментів, поєднайте постачальника з [agent harness](/uk/plugins/sdk-agent-harness),
|
||||
а не виносьте деталі протоколу демона в core.
|
||||
а не виносьте деталі протоколу демона в ядро.
|
||||
</Tip>
|
||||
|
||||
## Покроковий розбір
|
||||
@ -97,17 +97,17 @@ x-i18n:
|
||||
</CodeGroup>
|
||||
|
||||
Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти
|
||||
облікові дані без завантаження runtime вашого Plugin. Додавайте `providerAuthAliases`,
|
||||
коли варіант постачальника має повторно використовувати автентифікацію іншого ідентифікатора постачальника. `modelSupport`
|
||||
є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш Plugin постачальника зі скорочених
|
||||
ідентифікаторів моделей, як-от `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте
|
||||
облікові дані без завантаження рантайму вашого plugin. Додавайте `providerAuthAliases`,
|
||||
коли варіант постачальника має повторно використовувати auth іншого id постачальника. `modelSupport`
|
||||
є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш plugin постачальника за скороченими
|
||||
id моделей, як-от `acme-large`, ще до появи рантайм-хуків. Якщо ви публікуєте
|
||||
постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build`
|
||||
є обов’язковими в `package.json`.
|
||||
у `package.json` є обов’язковими.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Зареєструйте постачальника">
|
||||
Мінімальному постачальнику потрібні `id`, `label`, `auth` і `catalog`:
|
||||
Мінімальний постачальник потребує `id`, `label`, `auth` і `catalog`:
|
||||
|
||||
```typescript index.ts
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -182,8 +182,8 @@ x-i18n:
|
||||
`openclaw onboard --acme-ai-api-key <key>` і вибрати
|
||||
`acme-ai/acme-large` як свою модель.
|
||||
|
||||
Якщо апстрім-постачальник використовує інші керівні токени, ніж OpenClaw, додайте
|
||||
невелике двонапрямне текстове перетворення замість заміни шляху стримінгу:
|
||||
Якщо постачальник вище за потоком використовує інші керівні токени, ніж OpenClaw, додайте
|
||||
невелике двоспрямоване текстове перетворення замість заміни шляху потокової передачі:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -200,13 +200,13 @@ x-i18n:
|
||||
});
|
||||
```
|
||||
|
||||
`input` переписує фінальний системний промпт і текстовий вміст повідомлення перед
|
||||
передаванням. `output` переписує текстові дельти відповіді асистента та фінальний текст до того,
|
||||
як OpenClaw розбере власні керівні маркери або доставку через канал.
|
||||
`input` переписує фінальний системний prompt і вміст текстових повідомлень перед
|
||||
передаванням. `output` переписує текстові дельти асистента й фінальний текст до того, як
|
||||
OpenClaw розбере власні керівні маркери або доставку каналом.
|
||||
|
||||
Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією
|
||||
через API-ключ і одним runtime на основі каталогу, надавайте перевагу вужчому
|
||||
допоміжному методу `defineSingleProviderPluginEntry(...)`:
|
||||
Для вбудованих постачальників, які реєструють лише одного текстового постачальника з auth через API-ключ
|
||||
плюс один рантайм, що підтримується каталогом, віддавайте перевагу вужчому
|
||||
хелперу `defineSingleProviderPluginEntry(...)`:
|
||||
|
||||
```typescript
|
||||
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
|
||||
@ -246,33 +246,33 @@ x-i18n:
|
||||
});
|
||||
```
|
||||
|
||||
`buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити реальну
|
||||
автентифікацію постачальника. Він може виконувати специфічне для постачальника виявлення.
|
||||
Використовуйте `buildStaticProvider` лише для офлайнових рядків, які безпечно показувати до налаштування
|
||||
автентифікації; він не повинен вимагати облікові дані або виконувати мережеві запити.
|
||||
Відображення `models list --all` в OpenClaw наразі виконує статичні каталоги
|
||||
лише для вбудованих Plugin постачальників, із порожньою конфігурацією, порожнім env та без
|
||||
шляхів агента/робочого простору.
|
||||
`buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити реальний
|
||||
auth постачальника. Він може виконувати специфічне для постачальника виявлення. Використовуйте
|
||||
`buildStaticProvider` лише для офлайн-рядків, які безпечно показувати до налаштування auth;
|
||||
він не повинен вимагати облікових даних або виконувати мережеві запити.
|
||||
Показ `models list --all` в OpenClaw наразі виконує статичні каталоги
|
||||
лише для вбудованих plugin постачальників, із порожньою конфігурацією, порожнім env і без
|
||||
шляхів agent/workspace.
|
||||
|
||||
Якщо вашому процесу автентифікації також потрібно змінювати `models.providers.*`, псевдоніми
|
||||
та модель агента за замовчуванням під час onboard, використовуйте допоміжні пресети з
|
||||
`openclaw/plugin-sdk/provider-onboard`. Найвужчі допоміжні методи:
|
||||
Якщо ваш потік auth також має оновлювати `models.providers.*`, аліаси та
|
||||
модель агента за замовчуванням під час onboarding, використовуйте preset-хелпери з
|
||||
`openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери:
|
||||
`createDefaultModelPresetAppliers(...)`,
|
||||
`createDefaultModelsPresetAppliers(...)` і
|
||||
`createModelCatalogPresetAppliers(...)`.
|
||||
|
||||
Коли нативна кінцева точка постачальника підтримує потокові блоки використання в
|
||||
звичайному транспорті `openai-completions`, надавайте перевагу спільним допоміжним методам каталогу з
|
||||
`openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок ідентифікатора постачальника.
|
||||
Коли нативна кінцева точка постачальника підтримує блоки використання в потоці на
|
||||
звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з
|
||||
`openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок provider-id.
|
||||
`supportsNativeStreamingUsageCompat(...)` і
|
||||
`applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за картою можливостей кінцевої точки,
|
||||
тож нативні кінцеві точки в стилі Moonshot/DashScope також можуть підключатися, навіть якщо Plugin
|
||||
використовує власний ідентифікатор постачальника.
|
||||
`applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за картою можливостей кінцевої точки,
|
||||
тож нативні кінцеві точки в стилі Moonshot/DashScope також підключаються, навіть коли plugin використовує
|
||||
користувацький provider id.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте динамічне визначення моделі">
|
||||
Якщо ваш постачальник приймає довільні ідентифікатори моделей (наприклад, проксі або маршрутизатор),
|
||||
<Step title="Додайте динамічне визначення моделей">
|
||||
Якщо ваш постачальник приймає довільні id моделей, (наприклад, проксі або маршрутизатор),
|
||||
додайте `resolveDynamicModel`:
|
||||
|
||||
```typescript
|
||||
@ -299,12 +299,12 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте runtime-хуки (за потреби)">
|
||||
<Step title="Додайте рантайм-хуки (за потреби)">
|
||||
Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки
|
||||
поступово, у міру того як вони потрібні вашому постачальнику.
|
||||
поступово, у міру потреб вашого постачальника.
|
||||
|
||||
Спільні конструктори допоміжних методів тепер покривають найпоширеніші сімейства replay/tool-compat,
|
||||
тому Plugin зазвичай не потрібно вручну підключати кожен хук окремо:
|
||||
Спільні builder-хелпери тепер покривають найпоширеніші сімейства replay/tool-compat,
|
||||
тому plugin зазвичай не потрібно вручну підключати кожен хук окремо:
|
||||
|
||||
```typescript
|
||||
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
|
||||
@ -328,13 +328,13 @@ x-i18n:
|
||||
|
||||
| Сімейство | Що воно підключає |
|
||||
| --- | --- |
|
||||
| `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з санітизацією ідентифікаторів викликів інструментів, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту |
|
||||
| `anthropic-by-model` | Claude-орієнтована політика replay, що вибирається за `modelId`, тож транспорти повідомлень Anthropic отримують специфічне очищення thinking-block Claude лише тоді, коли визначена модель справді є ідентифікатором Claude |
|
||||
| `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим тегованого виводу reasoning |
|
||||
| `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або переписування bootstrap |
|
||||
| `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message та OpenAI-compatible в одному Plugin; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic |
|
||||
| `openai-compatible` | Спільна політика replay у стилі OpenAI для транспортів, сумісних з OpenAI, включно з санітарною обробкою tool-call-id, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту |
|
||||
| `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді має id Claude |
|
||||
| `google-gemini` | Нативна політика replay для Gemini плюс санітарна обробка bootstrap replay і режим тегованого reasoning-output |
|
||||
| `passthrough-gemini` | Санітарна обробка Gemini thought-signature для моделей Gemini, що працюють через проксі-транспорти, сумісні з OpenAI; не вмикає нативну валідацію replay Gemini або переписування bootstrap |
|
||||
| `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному plugin; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic |
|
||||
|
||||
Реальні приклади з вбудованих Plugin:
|
||||
Реальні приклади вбудованих постачальників:
|
||||
|
||||
- `google` і `google-gemini-cli`: `google-gemini`
|
||||
- `openrouter`, `kilocode`, `opencode` і `opencode-go`: `passthrough-gemini`
|
||||
@ -346,15 +346,15 @@ x-i18n:
|
||||
|
||||
| Сімейство | Що воно підключає |
|
||||
| --- | --- |
|
||||
| `google-thinking` | Нормалізація thinking payload Gemini на спільному шляху stream |
|
||||
| `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху proxy stream, де `kilo/auto` та непідтримувані ідентифікатори reasoning proxy пропускають ін’єкцію thinking |
|
||||
| `moonshot-thinking` | Відображення двійкового payload native-thinking Moonshot із config + рівня `/think` |
|
||||
| `minimax-fast-mode` | Переписування моделі fast-mode MiniMax на спільному шляху stream |
|
||||
| `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, деталізація text, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses |
|
||||
| `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів proxy з централізованою обробкою пропусків для непідтримуваних моделей/`auto` |
|
||||
| `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, яким потрібен stream інструментів, якщо його явно не вимкнено |
|
||||
| `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху stream |
|
||||
| `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху proxy stream, де `kilo/auto` і непідтримувані proxy reasoning id пропускають ін’єктований thinking |
|
||||
| `moonshot-thinking` | Відображення payload native-thinking Moonshot у двійковому форматі з config + рівня `/think` |
|
||||
| `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху stream |
|
||||
| `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution headers, `/fast`/`serviceTier`, text verbosity, нативний web search Codex, формування payload reasoning-compat і керування контекстом Responses |
|
||||
| `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, із централізованою обробкою пропусків unsupported-model/`auto` |
|
||||
| `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнено явно |
|
||||
|
||||
Реальні приклади з вбудованих Plugin:
|
||||
Реальні приклади вбудованих постачальників:
|
||||
|
||||
- `google` і `google-gemini-cli`: `google-thinking`
|
||||
- `kilocode`: `kilocode-thinking`
|
||||
@ -364,77 +364,76 @@ x-i18n:
|
||||
- `openrouter`: `openrouter-thinking`
|
||||
- `zai`: `tool-stream-default-on`
|
||||
|
||||
`openclaw/plugin-sdk/provider-model-shared` також експортує enum
|
||||
сімейств replay, а також спільні допоміжні методи, з яких ці сімейства побудовані. До поширених публічних
|
||||
експортів належать:
|
||||
`openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств
|
||||
replay, а також спільні хелпери, з яких ці сімейства побудовані. Поширені публічні
|
||||
експорти включають:
|
||||
|
||||
- `ProviderReplayFamily`
|
||||
- `buildProviderReplayFamilyHooks(...)`
|
||||
- спільні конструктори replay, як-от `buildOpenAICompatibleReplayPolicy(...)`,
|
||||
- спільні builder-и replay, такі як `buildOpenAICompatibleReplayPolicy(...)`,
|
||||
`buildAnthropicReplayPolicyForModel(...)`,
|
||||
`buildGoogleGeminiReplayPolicy(...)` і
|
||||
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
|
||||
- допоміжні методи replay Gemini, як-от `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
- хелпери replay для Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
і `resolveTaggedReasoningOutputMode()`
|
||||
- допоміжні методи endpoint/model, як-от `resolveProviderEndpoint(...)`,
|
||||
- хелпери endpoint/model, такі як `resolveProviderEndpoint(...)`,
|
||||
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і
|
||||
`normalizeNativeXaiModelId(...)`
|
||||
|
||||
`openclaw/plugin-sdk/provider-stream` надає як конструктор сімейств, так і
|
||||
публічні допоміжні методи обгорток, які ці сімейства повторно використовують. До поширених публічних експортів
|
||||
належать:
|
||||
`openclaw/plugin-sdk/provider-stream` надає як builder сімейств,
|
||||
так і публічні хелпери-обгортки, які ці сімейства використовують повторно. Поширені публічні експорти
|
||||
включають:
|
||||
|
||||
- `ProviderStreamFamily`
|
||||
- `buildProviderStreamFamilyHooks(...)`
|
||||
- `composeProviderStreamWrappers(...)`
|
||||
- спільні обгортки OpenAI/Codex, як-от
|
||||
- спільні обгортки OpenAI/Codex, такі як
|
||||
`createOpenAIAttributionHeadersWrapper(...)`,
|
||||
`createOpenAIFastModeWrapper(...)`,
|
||||
`createOpenAIServiceTierWrapper(...)`,
|
||||
`createOpenAIResponsesContextManagementWrapper(...)` і
|
||||
`createCodexNativeWebSearchWrapper(...)`
|
||||
- спільні обгортки proxy/provider, як-от `createOpenRouterWrapper(...)`,
|
||||
- спільні обгортки proxy/provider, такі як `createOpenRouterWrapper(...)`,
|
||||
`createToolStreamWrapper(...)` і `createMinimaxFastModeWrapper(...)`
|
||||
|
||||
Деякі допоміжні методи stream навмисно залишаються локальними для постачальника. Поточний вбудований
|
||||
Деякі stream-хелпери навмисно залишаються локальними для постачальника. Поточний вбудований
|
||||
приклад: `@openclaw/anthropic-provider` експортує
|
||||
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
|
||||
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і
|
||||
низькорівневі конструктори обгорток Anthropic через свій публічний seam `api.ts` /
|
||||
`contract-api.ts`. Ці допоміжні методи залишаються специфічними для Anthropic, оскільки
|
||||
builder-и нижчого рівня для обгорток Anthropic зі свого публічного шва `api.ts` /
|
||||
`contract-api.ts`. Ці хелпери залишаються специфічними для Anthropic, оскільки
|
||||
вони також кодують обробку Claude OAuth beta і gating `context1m`.
|
||||
|
||||
Інші вбудовані постачальники також тримають локальними обгортки, специфічні для транспорту, коли
|
||||
поведінку неможливо чисто поділити між сімействами. Поточний приклад: вбудований Plugin xAI
|
||||
цю поведінку не можна чисто поділити між сімействами. Поточний приклад: вбудований plugin xAI
|
||||
зберігає нативне формування xAI Responses у власному
|
||||
`wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, типовим `tool_stream`,
|
||||
очищенням непідтримуваних strict-tool і
|
||||
видаленням payload reasoning, специфічного для xAI.
|
||||
`wrapStreamFn`, включно з переписуванням аліасів `/fast`, `tool_stream` за замовчуванням,
|
||||
очищенням unsupported strict-tool і видаленням payload reasoning, специфічним для xAI.
|
||||
|
||||
`openclaw/plugin-sdk/provider-tools` наразі надає одне спільне
|
||||
сімейство схеми інструментів плюс спільні допоміжні методи schema/compat:
|
||||
`openclaw/plugin-sdk/provider-tools` наразі надає одне спільне сімейство
|
||||
схем інструментів плюс спільні хелпери schema/compat:
|
||||
|
||||
- `ProviderToolCompatFamily` документує поточний перелік спільних сімейств.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схеми Gemini
|
||||
- `ProviderToolCompatFamily` документує поточний спільний інвентар сімейств.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini
|
||||
+ діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів.
|
||||
- `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)`
|
||||
— це базові публічні допоміжні методи схем Gemini.
|
||||
- `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI:
|
||||
`toolSchemaProfile: "xai"`, непідтримувані ключові слова схеми, нативна
|
||||
підтримка `web_search` і декодування аргументів виклику інструментів із HTML-entity.
|
||||
- `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до
|
||||
визначеної моделі до того, як вона потрапить до runner.
|
||||
— це базові публічні хелпери схем Gemini.
|
||||
- `resolveXaiModelCompatPatch()` повертає вбудований compat-патч xAI:
|
||||
`toolSchemaProfile: "xai"`, непідтримувані ключові слова схем, нативну
|
||||
підтримку `web_search` і декодування аргументів виклику інструментів з HTML-сутностей.
|
||||
- `applyXaiModelCompat(model)` застосовує той самий compat-патч xAI до
|
||||
визначеної моделі до того, як вона дійде до runner.
|
||||
|
||||
Реальний приклад із вбудованих Plugin: Plugin xAI використовує `normalizeResolvedModel` плюс
|
||||
`contributeResolvedModelCompat`, щоб ці метадані compat належали
|
||||
постачальнику, а не були жорстко закодовані в core.
|
||||
Реальний вбудований приклад: plugin xAI використовує `normalizeResolvedModel` плюс
|
||||
`contributeResolvedModelCompat`, щоб зберігати ці compat-метадані у власності
|
||||
постачальника, а не жорстко кодувати правила xAI в ядрі.
|
||||
|
||||
Той самий шаблон package-root також лежить в основі інших вбудованих постачальників:
|
||||
Той самий шаблон кореня пакета також лежить в основі інших вбудованих постачальників:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує конструктори постачальників,
|
||||
допоміжні методи моделі за замовчуванням і конструктори realtime постачальників
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор постачальника
|
||||
плюс допоміжні методи onboard/config
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує builder-и постачальників,
|
||||
хелпери моделей за замовчуванням і builder-и realtime-постачальників
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує builder постачальника
|
||||
плюс хелпери onboarding/config
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Обмін токенів">
|
||||
@ -451,8 +450,8 @@ x-i18n:
|
||||
},
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Власні заголовки">
|
||||
Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту:
|
||||
<Tab title="Користувацькі заголовки">
|
||||
Для постачальників, яким потрібні користувацькі заголовки запитів або модифікації тіла:
|
||||
|
||||
```typescript
|
||||
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
|
||||
@ -470,7 +469,7 @@ x-i18n:
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Ідентичність нативного транспорту">
|
||||
Для постачальників, яким потрібні нативні заголовки запиту/сесії або метадані на
|
||||
Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії на
|
||||
узагальнених транспортних рівнях HTTP або WebSocket:
|
||||
|
||||
```typescript
|
||||
@ -511,80 +510,80 @@ x-i18n:
|
||||
|
||||
| # | Хук | Коли використовувати |
|
||||
| --- | --- | --- |
|
||||
| 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням |
|
||||
| 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час матеріалізації config |
|
||||
| 3 | `normalizeModelId` | Очищення псевдонімів `model-id` для legacy/preview перед пошуком |
|
||||
| 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним збиранням моделі |
|
||||
| 1 | `catalog` | Каталог моделей або значення `base URL` за замовчуванням |
|
||||
| 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, якими володіє постачальник, під час materialization конфігурації |
|
||||
| 3 | `normalizeModelId` | Очищення застарілих/preview аліасів model-id перед пошуком |
|
||||
| 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед збиранням узагальненої моделі |
|
||||
| 5 | `normalizeConfig` | Нормалізація config `models.providers.<id>` |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для постачальників config |
|
||||
| 7 | `resolveConfigApiKey` | Визначення автентифікації через env-marker, що належить постачальнику |
|
||||
| 8 | `resolveSyntheticAuth` | Синтетична автентифікація для local/self-hosted або на основі config |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Опускає синтетичні заповнювачі збереженого профілю нижче за автентифікацію env/config |
|
||||
| 10 | `resolveDynamicModel` | Приймати довільні ідентифікатори апстрім-моделей |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Переписування compat для нативного streaming-usage для config-постачальників |
|
||||
| 7 | `resolveConfigApiKey` | Визначення auth за env-marker, яким володіє постачальник |
|
||||
| 8 | `resolveSyntheticAuth` | Синтетичний auth для local/self-hosted або на основі config |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Опускання синтетичних заповнювачів stored-profile нижче auth env/config |
|
||||
| 10 | `resolveDynamicModel` | Приймати довільні upstream model id |
|
||||
| 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням |
|
||||
| 12 | `normalizeResolvedModel` | Переписування транспорту перед runner |
|
||||
|
||||
Нотатки щодо runtime fallback:
|
||||
Нотатки щодо рантайм-fallback:
|
||||
|
||||
- `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші
|
||||
Plugin постачальників, що підтримують хуки, доки один із них справді не змінить config.
|
||||
- `normalizeConfig` спочатку перевіряє зіставленого постачальника, а потім інші
|
||||
plugin постачальників, що підтримують хуки, доки один із них справді не змінить config.
|
||||
Якщо жоден хук постачальника не перепише підтримуваний запис config сімейства Google,
|
||||
усе одно буде застосовано вбудований нормалізатор config Google.
|
||||
- `resolveConfigApiKey` використовує хук постачальника, якщо він доступний. Вбудований
|
||||
шлях `amazon-bedrock` також має вбудований resolver AWS env-marker саме тут,
|
||||
хоча автентифікація runtime Bedrock і далі використовує стандартний
|
||||
усе одно застосовується вбудований нормалізатор config Google.
|
||||
- `resolveConfigApiKey` використовує хук постачальника, якщо його надано. Вбудований
|
||||
шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker,
|
||||
хоча сам рантайм-auth Bedrock все ще використовує стандартний
|
||||
ланцюжок AWS SDK.
|
||||
| 13 | `contributeResolvedModelCompat` | Прапорці compat для моделей вендора за іншим сумісним транспортом |
|
||||
| 14 | `capabilities` | Статичний набір можливостей для legacy; лише сумісність |
|
||||
| 15 | `normalizeToolSchemas` | Очищення схеми інструментів, що належить постачальнику, перед реєстрацією |
|
||||
| 16 | `inspectToolSchemas` | Діагностика схеми інструментів, що належить постачальнику |
|
||||
| 17 | `resolveReasoningOutputMode` | Контракт тегованого чи нативного виводу reasoning |
|
||||
| 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності |
|
||||
| 15 | `normalizeToolSchemas` | Очищення схем інструментів, яким володіє постачальник, перед реєстрацією |
|
||||
| 16 | `inspectToolSchemas` | Діагностика схем інструментів, якою володіє постачальник |
|
||||
| 17 | `resolveReasoningOutputMode` | Контракт reasoning-output: tagged чи native |
|
||||
| 18 | `prepareExtraParams` | Параметри запиту за замовчуванням |
|
||||
| 19 | `createStreamFn` | Повністю власний транспорт StreamFn |
|
||||
| 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла на звичайному шляху stream |
|
||||
| 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn |
|
||||
| 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cool-down |
|
||||
| 23 | `formatApiKey` | Власна форма токена runtime |
|
||||
| 24 | `refreshOAuth` | Власне оновлення OAuth |
|
||||
| 25 | `buildAuthDoctorHint` | Підказка для відновлення автентифікації |
|
||||
| 26 | `matchesContextOverflowError` | Виявлення переповнення контексту, що належить постачальнику |
|
||||
| 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику |
|
||||
| 28 | `isCacheTtlEligible` | Керування TTL кешу промптів |
|
||||
| 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію |
|
||||
| 30 | `suppressBuiltInModel` | Приховати застарілі апстрім-рядки |
|
||||
| 31 | `augmentModelCatalog` | Синтетичні рядки для прямої сумісності вперед |
|
||||
| 19 | `createStreamFn` | Повністю користувацький транспорт `StreamFn` |
|
||||
| 20 | `wrapStreamFn` | Користувацькі обгортки headers/body на звичайному шляху stream |
|
||||
| 21 | `resolveTransportTurnState` | Нативні headers/metadata для кожного turn |
|
||||
| 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cooldown |
|
||||
| 23 | `formatApiKey` | Користувацька форма рантайм-токена |
|
||||
| 24 | `refreshOAuth` | Користувацьке оновлення OAuth |
|
||||
| 25 | `buildAuthDoctorHint` | Підказка щодо виправлення auth |
|
||||
| 26 | `matchesContextOverflowError` | Визначення переповнення, яким володіє постачальник |
|
||||
| 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, якою володіє постачальник |
|
||||
| 28 | `isCacheTtlEligible` | Gating TTL для кешу prompt |
|
||||
| 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутній auth |
|
||||
| 30 | `suppressBuiltInModel` | Приховати застарілі upstream-рядки |
|
||||
| 31 | `augmentModelCatalog` | Синтетичні рядки для forward-compat |
|
||||
| 32 | `resolveThinkingProfile` | Набір опцій `/think`, специфічний для моделі |
|
||||
| 33 | `isBinaryThinking` | Сумісність із двійковим вмиканням/вимиканням thinking |
|
||||
| 34 | `supportsXHighThinking` | Сумісність із підтримкою reasoning `xhigh` |
|
||||
| 35 | `resolveDefaultThinkingLevel` | Сумісність із політикою `/think` за замовчуванням |
|
||||
| 36 | `isModernModelRef` | Відповідність live/smoke моделей |
|
||||
| 33 | `isBinaryThinking` | Сумісність двійкового thinking увімк./вимк. |
|
||||
| 34 | `supportsXHighThinking` | Сумісність підтримки reasoning `xhigh` |
|
||||
| 35 | `resolveDefaultThinkingLevel` | Сумісність політики `/think` за замовчуванням |
|
||||
| 36 | `isModernModelRef` | Зіставлення live/smoke моделей |
|
||||
| 37 | `prepareRuntimeAuth` | Обмін токенів перед інференсом |
|
||||
| 38 | `resolveUsageAuth` | Власний розбір облікових даних використання |
|
||||
| 39 | `fetchUsageSnapshot` | Власна кінцева точка використання |
|
||||
| 40 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку |
|
||||
| 41 | `buildReplayPolicy` | Власна політика replay/Compaction транскрипту |
|
||||
| 42 | `sanitizeReplayHistory` | Переписування replay, специфічне для постачальника, після загального очищення |
|
||||
| 43 | `validateReplayTurns` | Сувора валідація turn replay перед вбудованим runner |
|
||||
| 44 | `onModelSelected` | Callback після вибору моделі (наприклад, телеметрія) |
|
||||
| 38 | `resolveUsageAuth` | Користувацький розбір облікових даних використання |
|
||||
| 39 | `fetchUsageSnapshot` | Користувацька кінцева точка використання |
|
||||
| 40 | `createEmbeddingProvider` | Адаптер embedding, яким володіє постачальник, для пам’яті/пошуку |
|
||||
| 41 | `buildReplayPolicy` | Користувацька політика replay/Compaction транскрипту |
|
||||
| 42 | `sanitizeReplayHistory` | Переписування replay, специфічні для постачальника, після загального очищення |
|
||||
| 43 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner |
|
||||
| 44 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) |
|
||||
|
||||
Примітка щодо налаштування промптів:
|
||||
Примітка щодо налаштування prompt:
|
||||
|
||||
- `resolveSystemPromptContribution` дозволяє постачальнику додавати до
|
||||
системного промпту підказки для сімейства моделей з урахуванням кешу. Надавайте йому перевагу над
|
||||
`before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі
|
||||
- `resolveSystemPromptContribution` дозволяє постачальнику ін’єктувати cache-aware
|
||||
вказівки для system prompt для сімейства моделей. Віддавайте йому перевагу над
|
||||
`before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделей
|
||||
і має зберігати стабільний/динамічний поділ кешу.
|
||||
|
||||
Докладні описи та реальні приклади див. у
|
||||
[Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
[Внутрішня архітектура: рантайм-хуки постачальника](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте додаткові можливості (необов’язково)">
|
||||
<a id="step-5-add-extra-capabilities"></a>
|
||||
Plugin постачальника може реєструвати speech, транскрипцію в realtime, голос у realtime,
|
||||
розуміння медіа, генерацію зображень, генерацію відео, web fetch
|
||||
і web search разом із текстовим інференсом:
|
||||
Plugin постачальника може реєструвати синтез мовлення, транскрибування в реальному часі, голос у реальному
|
||||
часі, розуміння медіа, генерацію зображень, генерацію відео, web fetch
|
||||
і web search поряд із текстовим інференсом:
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -689,7 +688,7 @@ x-i18n:
|
||||
api.registerWebFetchProvider({
|
||||
id: "acme-ai-fetch",
|
||||
label: "Acme Fetch",
|
||||
hint: "Отримуйте сторінки через backend рендерингу Acme.",
|
||||
hint: "Fetch pages through Acme's rendering backend.",
|
||||
envVars: ["ACME_FETCH_API_KEY"],
|
||||
placeholder: "acme-...",
|
||||
signupUrl: "https://acme.example.com/fetch",
|
||||
@ -700,7 +699,7 @@ x-i18n:
|
||||
acme.apiKey = value;
|
||||
},
|
||||
createTool: () => ({
|
||||
description: "Отримати сторінку через Acme Fetch.",
|
||||
description: "Fetch a page through Acme Fetch.",
|
||||
parameters: {},
|
||||
execute: async (args) => ({ content: [] }),
|
||||
}),
|
||||
@ -714,20 +713,31 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw класифікує це як plugin **hybrid-capability**. Це
|
||||
рекомендований шаблон для корпоративних Plugin (один Plugin на вендора). Див.
|
||||
[Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model).
|
||||
OpenClaw класифікує це як plugin **гібридних можливостей**. Це
|
||||
рекомендований шаблон для корпоративних plugin (один plugin на вендора). Див.
|
||||
[Внутрішня архітектура: володіння можливостями](/uk/plugins/architecture#capability-ownership-model).
|
||||
|
||||
Для генерації відео надавайте перевагу наведеній вище структурі можливостей із урахуванням режиму:
|
||||
`generate`, `imageToVideo` і `videoToVideo`. Плоскі агреговані поля, як-от
|
||||
`maxInputImages`, `maxInputVideos` і `maxDurationSeconds`,
|
||||
недостатні, щоб коректно оголосити підтримку режимів перетворення або вимкнених режимів.
|
||||
Для генерації відео віддавайте перевагу показаній вище структурі можливостей, що враховує режим:
|
||||
`generate`, `imageToVideo` і `videoToVideo`. Плоскі агреговані поля на кшталт
|
||||
`maxInputImages`, `maxInputVideos` і `maxDurationSeconds` недостатні,
|
||||
щоб коректно оголошувати підтримку режимів трансформації або вимкнених режимів.
|
||||
|
||||
Постачальники генерації музики мають дотримуватися того самого шаблону:
|
||||
`generate` для генерації лише за промптом і `edit` для генерації
|
||||
на основі еталонного зображення. Плоскі агреговані поля, як-от `maxInputImages`,
|
||||
`supportsLyrics` і `supportsFormat`, недостатні для оголошення підтримки редагування;
|
||||
очікуваним контрактом є явні блоки `generate` / `edit`.
|
||||
Для потокових STT-постачальників віддавайте перевагу спільному хелперу WebSocket. Він забезпечує
|
||||
узгодженість proxy capture, backoff при повторному підключенні, flush під час закриття, ready-handshake,
|
||||
постановки аудіо в чергу та діагностики подій закриття між постачальниками, водночас
|
||||
залишаючи коду постачальника відповідальність лише за відображення upstream-подій.
|
||||
|
||||
Пакетні STT-постачальники, які надсилають multipart audio через POST, повинні використовувати
|
||||
`buildAudioTranscriptionFormData(...)` з
|
||||
`openclaw/plugin-sdk/provider-http` разом із хелперами HTTP-запитів постачальника.
|
||||
Хелпер форми нормалізує імена файлів завантаження, включно з AAC-завантаженнями,
|
||||
яким потрібне ім’я файлу у стилі M4A для сумісних API транскрибування.
|
||||
|
||||
Постачальники генерації музики повинні дотримуватися того самого шаблону:
|
||||
`generate` для генерації лише за prompt і `edit` для генерації
|
||||
на основі референсного зображення. Плоскі агреговані поля на кшталт `maxInputImages`,
|
||||
`supportsLyrics` і `supportsFormat` недостатні, щоб оголошувати підтримку
|
||||
редагування; очікуваним контрактом є явні блоки `generate` / `edit`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -768,43 +778,43 @@ x-i18n:
|
||||
|
||||
## Публікація в ClawHub
|
||||
|
||||
Plugin постачальників публікуються так само, як і будь-який інший зовнішній code Plugin:
|
||||
Plugin постачальників публікуються так само, як і будь-який інший зовнішній code plugin:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети Plugin мають використовувати
|
||||
Не використовуйте тут застарілий аліас публікації лише для Skills; пакети plugin слід публікувати через
|
||||
`clawhub package publish`.
|
||||
|
||||
## Структура файлів
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-ai/
|
||||
├── package.json # Метадані openclaw.providers
|
||||
├── openclaw.plugin.json # Маніфест із метаданими автентифікації постачальника
|
||||
├── package.json # openclaw.providers metadata
|
||||
├── openclaw.plugin.json # Manifest with provider auth metadata
|
||||
├── index.ts # definePluginEntry + registerProvider
|
||||
└── src/
|
||||
├── provider.test.ts # Тести
|
||||
└── usage.ts # Кінцева точка використання (необов’язково)
|
||||
├── provider.test.ts # Tests
|
||||
└── usage.ts # Usage endpoint (optional)
|
||||
```
|
||||
|
||||
## Довідка щодо порядку каталогу
|
||||
## Довідник порядку каталогу
|
||||
|
||||
`catalog.order` визначає, коли ваш каталог об’єднується відносно вбудованих
|
||||
`catalog.order` керує тим, коли ваш каталог зливається відносно вбудованих
|
||||
постачальників:
|
||||
|
||||
| Порядок | Коли | Випадок використання |
|
||||
| --------- | ------------- | ----------------------------------------------- |
|
||||
| `simple` | Перший прохід | Прості постачальники з API-ключем |
|
||||
| `profile` | Після simple | Постачальники, прив’язані до профілів автентифікації |
|
||||
| `paired` | Після profile | Синтез кількох пов’язаних записів |
|
||||
| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) |
|
||||
| Порядок | Коли | Варіант використання |
|
||||
| --------- | ------------- | ---------------------------------------------- |
|
||||
| `simple` | Перший прохід | Прості постачальники з API-ключем |
|
||||
| `profile` | Після simple | Постачальники, обмежені auth-профілями |
|
||||
| `paired` | Після profile | Синтез кількох пов’язаних записів |
|
||||
| `late` | Останній прохід | Перевизначити наявних постачальників (перемагає при колізії) |
|
||||
|
||||
## Наступні кроки
|
||||
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш Plugin також надає канал
|
||||
- [SDK Runtime](/uk/plugins/sdk-runtime) — допоміжні методи `api.runtime` (TTS, search, subagent)
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник щодо імпортів subpath
|
||||
- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — подробиці про хуки та приклади з вбудованих Plugin
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш plugin також надає канал
|
||||
- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent)
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath
|
||||
- [Внутрішня архітектура plugin](/uk/plugins/architecture#provider-runtime-hooks) — деталі хуків і приклади вбудованих постачальників
|
||||
|
||||
@ -5,18 +5,18 @@ read_when:
|
||||
summary: 'Плагін Voice Call: вихідні + вхідні дзвінки через Twilio/Telnyx/Plivo (встановлення плагіна + конфігурація + CLI)'
|
||||
title: Плагін Voice Call
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T00:39:52Z"
|
||||
generated_at: "2026-04-23T03:31:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4106c156a52e06047d31a149b2944f50b38c41e5db664efa1f2a96b2b20fa88d
|
||||
source_hash: 2fbfe1aba459dd4fbe1b5c100430ff8cbe8987d7d34b875d115afcaee6e56412
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Voice Call (плагін)
|
||||
# Voice Call (Plugin)
|
||||
|
||||
Голосові дзвінки для OpenClaw через плагін. Підтримує вихідні сповіщення та
|
||||
багатокрокові розмови з політиками для вхідних викликів.
|
||||
Голосові дзвінки для OpenClaw через Plugin. Підтримує вихідні сповіщення та
|
||||
багатоходові розмови із вхідними політиками.
|
||||
|
||||
Поточні провайдери:
|
||||
|
||||
@ -25,18 +25,18 @@ x-i18n:
|
||||
- `plivo` (Voice API + XML transfer + GetInput speech)
|
||||
- `mock` (розробка/без мережі)
|
||||
|
||||
Швидка ментальна модель:
|
||||
Коротка ментальна модель:
|
||||
|
||||
- Встановіть плагін
|
||||
- Встановіть Plugin
|
||||
- Перезапустіть Gateway
|
||||
- Налаштуйте в `plugins.entries.voice-call.config`
|
||||
- Використовуйте `openclaw voicecall ...` або інструмент `voice_call`
|
||||
|
||||
## Де це працює (локально чи віддалено)
|
||||
|
||||
Плагін Voice Call працює **всередині процесу Gateway**.
|
||||
Plugin Voice Call працює **всередині процесу Gateway**.
|
||||
|
||||
Якщо ви використовуєте віддалений Gateway, встановіть/налаштуйте плагін на **машині, де працює Gateway**, а потім перезапустіть Gateway, щоб він завантажив плагін.
|
||||
Якщо ви використовуєте віддалений Gateway, встановіть/налаштуйте Plugin на **машині, де працює Gateway**, а потім перезапустіть Gateway, щоб він його завантажив.
|
||||
|
||||
## Встановлення
|
||||
|
||||
@ -69,7 +69,7 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
"voice-call": {
|
||||
enabled: true,
|
||||
config: {
|
||||
provider: "twilio", // або "telnyx" | "plivo" | "mock"
|
||||
provider: "twilio", // or "telnyx" | "plivo" | "mock"
|
||||
fromNumber: "+15550001234",
|
||||
toNumber: "+15550005678",
|
||||
|
||||
@ -81,8 +81,8 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
telnyx: {
|
||||
apiKey: "...",
|
||||
connectionId: "...",
|
||||
// Публічний ключ webhook Telnyx з Telnyx Mission Control Portal
|
||||
// (рядок Base64; також можна задати через TELNYX_PUBLIC_KEY).
|
||||
// Telnyx webhook public key from the Telnyx Mission Control Portal
|
||||
// (Base64 string; can also be set via TELNYX_PUBLIC_KEY).
|
||||
publicKey: "...",
|
||||
},
|
||||
|
||||
@ -91,19 +91,19 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
authToken: "...",
|
||||
},
|
||||
|
||||
// Сервер webhook
|
||||
// Webhook server
|
||||
serve: {
|
||||
port: 3334,
|
||||
path: "/voice/webhook",
|
||||
},
|
||||
|
||||
// Безпека webhook (рекомендовано для тунелів/проксі)
|
||||
// Webhook security (recommended for tunnels/proxies)
|
||||
webhookSecurity: {
|
||||
allowedHosts: ["voice.example.com"],
|
||||
trustedProxyIPs: ["100.64.0.1"],
|
||||
},
|
||||
|
||||
// Публічний доступ (виберіть один варіант)
|
||||
// Public exposure (pick one)
|
||||
// publicUrl: "https://example.ngrok.app/voice/webhook",
|
||||
// tunnel: { provider: "ngrok" },
|
||||
// tailscale: { mode: "funnel", path: "/voice/webhook" }
|
||||
@ -114,11 +114,11 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
|
||||
streaming: {
|
||||
enabled: true,
|
||||
provider: "openai", // необов’язково; якщо не задано, використовується перший зареєстрований провайдер транскрипції в реальному часі
|
||||
provider: "openai", // optional; first registered realtime transcription provider when unset
|
||||
streamPath: "/voice/stream",
|
||||
providers: {
|
||||
openai: {
|
||||
apiKey: "sk-...", // необов’язково, якщо задано OPENAI_API_KEY
|
||||
apiKey: "sk-...", // optional if OPENAI_API_KEY is set
|
||||
model: "gpt-4o-transcribe",
|
||||
silenceDurationMs: 800,
|
||||
vadThreshold: 0.5,
|
||||
@ -138,45 +138,41 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для Twilio/Telnyx потрібен **публічно доступний** URL webhook.
|
||||
- Для Plivo потрібен **публічно доступний** URL webhook.
|
||||
- Twilio/Telnyx потребують **публічно доступної** URL-адреси Webhook.
|
||||
- Plivo потребує **публічно доступної** URL-адреси Webhook.
|
||||
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
|
||||
- Якщо у старіших конфігураціях досі використовуються `provider: "log"`, `twilio.from` або застарілі ключі OpenAI в `streaming.*`, запустіть `openclaw doctor --fix`, щоб переписати їх.
|
||||
- Для Telnyx потрібен `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо тільки `skipSignatureVerification` не має значення true.
|
||||
- Якщо старіші конфігурації досі використовують `provider: "log"`, `twilio.from` або застарілі ключі OpenAI в `streaming.*`, виконайте `openclaw doctor --fix`, щоб переписати їх.
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо тільки `skipSignatureVerification` не має значення true.
|
||||
- `skipSignatureVerification` призначений лише для локального тестування.
|
||||
- Якщо ви використовуєте безкоштовний тариф ngrok, задайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусово увімкнена.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Використовуйте тільки для локальної розробки.
|
||||
- URL безкоштовного тарифу ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio не проходитимуть перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel.
|
||||
- Типові параметри безпеки для streaming:
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для однієї вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікування + активні).
|
||||
- Під час виконання fallback поки що все ще приймає ці старі ключі voice-call, але шлях переписування — це `openclaw doctor --fix`, а шар сумісності є тимчасовим.
|
||||
- Якщо ви використовуєте безкоштовний тариф ngrok, задайте `publicUrl` точною URL-адресою ngrok; перевірка підпису завжди примусово виконується.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook-и Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є local loopback (локальний агент ngrok). Використовуйте лише для локальної розробки.
|
||||
- URL-адреси ngrok на безкоштовному тарифі можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio не пройдуть перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel.
|
||||
- Значення безпеки streaming за замовчуванням:
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають коректний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих pre-start сокетів на одну вихідну IP-адресу.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувальні + активні).
|
||||
- Runtime fallback поки що все ще приймає ці старі ключі voice-call, але шлях переписування — це `openclaw doctor --fix`, а shim сумісності є тимчасовим.
|
||||
|
||||
## Транскрипція streaming
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо дзвінка.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо дзвінків.
|
||||
|
||||
Поточна поведінка під час виконання:
|
||||
Поточна поведінка в runtime:
|
||||
|
||||
- `streaming.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого
|
||||
зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі включають OpenAI (`openai`) і xAI
|
||||
(`xai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Сирий конфіг провайдера зберігається в `streaming.providers.<providerId>`.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера, або якщо жодного провайдера
|
||||
транскрипції в реальному часі взагалі не зареєстровано, Voice Call записує попередження в лог і
|
||||
пропускає медіа streaming замість того, щоб завершити роботу всього плагіна з помилкою.
|
||||
- `streaming.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі включають Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), які реєструються їхніми провайдерськими Plugins.
|
||||
- Необроблена конфігурація, що належить провайдеру, розташована в `streaming.providers.<providerId>`.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного провайдера транскрипції в реальному часі, Voice Call записує попередження в журнал і пропускає потокову передачу медіа замість того, щоб зупиняти весь Plugin.
|
||||
|
||||
Типові параметри транскрипції OpenAI для streaming:
|
||||
Значення OpenAI для потокової транскрипції за замовчуванням:
|
||||
|
||||
- API-ключ: `streaming.providers.openai.apiKey` або `OPENAI_API_KEY`
|
||||
- model: `gpt-4o-transcribe`
|
||||
- модель: `gpt-4o-transcribe`
|
||||
- `silenceDurationMs`: `800`
|
||||
- `vadThreshold`: `0.5`
|
||||
|
||||
Типові параметри транскрипції xAI для streaming:
|
||||
Значення xAI для потокової транскрипції за замовчуванням:
|
||||
|
||||
- API-ключ: `streaming.providers.xai.apiKey` або `XAI_API_KEY`
|
||||
- endpoint: `wss://api.x.ai/v1/stt`
|
||||
@ -199,7 +195,7 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
streamPath: "/voice/stream",
|
||||
providers: {
|
||||
openai: {
|
||||
apiKey: "sk-...", // необов’язково, якщо задано OPENAI_API_KEY
|
||||
apiKey: "sk-...", // optional if OPENAI_API_KEY is set
|
||||
model: "gpt-4o-transcribe",
|
||||
silenceDurationMs: 800,
|
||||
vadThreshold: 0.5,
|
||||
@ -213,7 +209,7 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
}
|
||||
```
|
||||
|
||||
Використання xAI замість цього:
|
||||
Використовуйте xAI натомість:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -227,7 +223,7 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
streamPath: "/voice/stream",
|
||||
providers: {
|
||||
xai: {
|
||||
apiKey: "${XAI_API_KEY}", // необов’язково, якщо задано XAI_API_KEY
|
||||
apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
|
||||
endpointingMs: 800,
|
||||
language: "en",
|
||||
},
|
||||
@ -248,17 +244,17 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
- `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs`
|
||||
- `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold`
|
||||
|
||||
## Очищувач застарілих викликів
|
||||
## Очищення застарілих дзвінків
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний webhook
|
||||
(наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення — `0`
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати дзвінки, які ніколи не отримують фінальний Webhook
|
||||
(наприклад, дзвінки в режимі notify, які ніколи не завершуються). Значення за замовчуванням — `0`
|
||||
(вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Продакшн:** `120`–`300` секунд для потоків у стилі notify.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли
|
||||
завершитися. Хороша відправна точка — `maxDurationSeconds + 30–60` секунд.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні дзвінки могли
|
||||
завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -277,30 +273,30 @@ cd "$PLUGIN_SRC" && pnpm install
|
||||
}
|
||||
```
|
||||
|
||||
## Безпека webhook
|
||||
## Безпека Webhook
|
||||
|
||||
Коли перед Gateway стоїть проксі або тунель, плагін відновлює
|
||||
публічний URL для перевірки підпису. Ці параметри керують тим,
|
||||
яким переспрямованим заголовкам довіряти.
|
||||
Коли перед Gateway стоїть проксі або тунель, Plugin відновлює
|
||||
публічну URL-адресу для перевірки підпису. Ці параметри керують тим,
|
||||
яким переспрямованим заголовкам можна довіряти.
|
||||
|
||||
`webhookSecurity.allowedHosts` визначає дозволений список хостів із заголовків переспрямування.
|
||||
`webhookSecurity.allowedHosts` задає список дозволених хостів із переспрямованих заголовків.
|
||||
|
||||
`webhookSecurity.trustForwardingHeaders` дозволяє довіряти переспрямованим заголовкам без списку дозволених хостів.
|
||||
`webhookSecurity.trustForwardingHeaders` дозволяє довіряти переспрямованим заголовкам без списку дозволених.
|
||||
|
||||
`webhookSecurity.trustedProxyIPs` дозволяє довіряти переспрямованим заголовкам, лише якщо
|
||||
`webhookSecurity.trustedProxyIPs` дозволяє довіряти переспрямованим заголовкам лише тоді, коли
|
||||
віддалена IP-адреса запиту збігається зі списком.
|
||||
|
||||
Захист від повторного відтворення webhook увімкнено для Twilio і Plivo. Повторно відтворені коректні webhook-
|
||||
запити підтверджуються, але пропускаються без побічних ефектів.
|
||||
Захист від повторного відтворення Webhook увімкнено для Twilio і Plivo. Повторно відтворені коректні запити Webhook
|
||||
підтверджуються, але пропускаються без побічних ефектів.
|
||||
|
||||
Кроки розмови Twilio включають токен для кожного кроку в callback `\<Gather>`, тому
|
||||
застарілі/повторно відтворені callback мовлення не можуть задовольнити новіший очікуваний крок транскрипції.
|
||||
Ходи розмови Twilio включають токен на кожен хід у callback-ах `<Gather>`, тому
|
||||
застарілі/повторно відтворені callback-и мовлення не можуть задовольнити новіший очікуваний хід транскрипції.
|
||||
|
||||
Неавтентифіковані webhook-запити відхиляються до читання тіла запиту, якщо відсутні
|
||||
обов’язкові заголовки підпису провайдера.
|
||||
Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні
|
||||
обов’язкові заголовки підпису від провайдера.
|
||||
|
||||
Webhook voice-call використовує спільний профіль тіла до автентифікації (64 KB / 5 секунд)
|
||||
разом з обмеженням кількості одночасних запитів на IP до перевірки підпису.
|
||||
Webhook voice-call використовує спільний профіль pre-auth для тіла (64 KB / 5 секунд),
|
||||
а також обмеження на кількість одночасних запитів з однієї IP-адреси до перевірки підпису.
|
||||
|
||||
Приклад зі стабільним публічним хостом:
|
||||
|
||||
@ -323,9 +319,9 @@ Webhook voice-call використовує спільний профіль ті
|
||||
|
||||
## TTS для дзвінків
|
||||
|
||||
Voice Call використовує базову конфігурацію `messages.tts` для
|
||||
streaming мовлення в дзвінках. Ви можете перевизначити її в конфігурації плагіна з
|
||||
**тією самою структурою** — вона глибоко зливається з `messages.tts`.
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для
|
||||
потокового мовлення в дзвінках. Ви можете перевизначити її в конфігурації Plugin з
|
||||
**тією самою структурою** — вона глибоко об’єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -343,15 +339,15 @@ streaming мовлення в дзвінках. Ви можете перевиз
|
||||
|
||||
Примітки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації плагіна (`openai`, `elevenlabs`, `microsoft`, `edge`) автоматично мігруються до `tts.providers.<provider>` під час завантаження. У збереженій конфігурації надавайте перевагу структурі `providers`.
|
||||
- **Microsoft speech ігнорується для голосових дзвінків** (для телеком-аудіо потрібен PCM; поточний транспорт Microsoft не надає вихід PCM для телефонії).
|
||||
- Базовий TTS використовується, коли увімкнено медіа streaming Twilio; інакше дзвінки повертаються до рідних голосів провайдера.
|
||||
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо TTS для телефонії в цьому стані недоступний, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли TTS для телефонії повертається до вторинного провайдера, Voice Call записує попередження в лог із ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) автоматично мігруються до `tts.providers.<provider>` під час завантаження. У збереженій конфігурації надавайте перевагу структурі `providers`.
|
||||
- **Microsoft speech ігнорується для голосових дзвінків** (телефонному аудіо потрібен PCM; поточний транспорт Microsoft не надає PCM-вивід для телефонії).
|
||||
- Основний TTS використовується, коли увімкнено потокову передачу медіа Twilio; в іншому разі дзвінки переходять на вбудовані голоси провайдера.
|
||||
- Якщо медіапотік Twilio вже активний, Voice Call не переходить на TwiML `<Say>`. Якщо TTS для телефонії недоступний у цьому стані, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли TTS для телефонії переходить на резервного провайдера, Voice Call записує попередження в журнал із ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
|
||||
|
||||
### Більше прикладів
|
||||
|
||||
Використовувати лише базовий TTS (без перевизначення):
|
||||
Використовувати лише основний TTS (без перевизначення):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -366,7 +362,7 @@ streaming мовлення в дзвінках. Ви можете перевиз
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначити на ElevenLabs лише для дзвінків (залишити базове значення в інших місцях):
|
||||
Перевизначити на ElevenLabs лише для дзвінків (зберегти основне значення за замовчуванням в інших місцях):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -391,7 +387,7 @@ streaming мовлення в дзвінках. Ви можете перевиз
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначити лише модель OpenAI для дзвінків (приклад глибокого злиття):
|
||||
Перевизначити лише модель OpenAI для дзвінків (приклад глибокого об’єднання):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -414,25 +410,25 @@ streaming мовлення в дзвінках. Ви можете перевиз
|
||||
}
|
||||
```
|
||||
|
||||
## Вхідні виклики
|
||||
## Вхідні дзвінки
|
||||
|
||||
Типове значення політики вхідних викликів — `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
Політика вхідних дзвінків за замовчуванням має значення `disabled`. Щоб увімкнути вхідні дзвінки, задайте:
|
||||
|
||||
```json5
|
||||
{
|
||||
inboundPolicy: "allowlist",
|
||||
allowFrom: ["+15550001234"],
|
||||
inboundGreeting: "Вітаю! Чим я можу допомогти?",
|
||||
inboundGreeting: "Hello! How can I help?",
|
||||
}
|
||||
```
|
||||
|
||||
`inboundPolicy: "allowlist"` — це фільтр caller ID з низьким рівнем гарантії. Плагін
|
||||
`inboundPolicy: "allowlist"` — це екранування caller ID з низьким рівнем гарантій. Plugin
|
||||
нормалізує надане провайдером значення `From` і порівнює його з `allowFrom`.
|
||||
Перевірка webhook автентифікує доставку від провайдера та цілісність даних, але
|
||||
вона не доводить право власності на номер викликача в PSTN/VoIP. Сприймайте `allowFrom` як
|
||||
фільтрацію caller ID, а не як сильну ідентифікацію викликача.
|
||||
Перевірка Webhook автентифікує доставку від провайдера та цілісність корисного навантаження, але
|
||||
вона не доводить право власності на номер виклику PSTN/VoIP. Розглядайте `allowFrom` як
|
||||
фільтрацію caller ID, а не як сильну ідентифікацію абонента.
|
||||
|
||||
Автовідповіді використовують систему агента. Налаштовуйте через:
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою:
|
||||
|
||||
- `responseModel`
|
||||
- `responseSystemPrompt`
|
||||
@ -440,51 +436,51 @@ streaming мовлення в дзвінках. Ви можете перевиз
|
||||
|
||||
### Контракт озвученого виводу
|
||||
|
||||
Для автовідповідей Voice Call додає суворий контракт озвученого виводу до системного запиту:
|
||||
Для автовідповідей Voice Call додає суворий контракт озвученого виводу до системного prompt:
|
||||
|
||||
- `{"spoken":"..."}`
|
||||
|
||||
Потім Voice Call обережно витягує текст для озвучення:
|
||||
Потім Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує дані, позначені як reasoning/error content.
|
||||
- Розбирає прямий JSON, JSON в огороджених блоках або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту та прибирає ймовірні вступні абзаци з плануванням/метаінформацією.
|
||||
- Ігнорує payload-и, позначені як reasoning/error content.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоках або вбудовані ключі `"spoken"`.
|
||||
- Використовує простий текст як fallback і видаляє ймовірні вступні абзаци з плануванням/метаінформацією.
|
||||
|
||||
Це дозволяє зосередити озвучення на тексті, призначеному для абонента, і уникнути витоку тексту планування в аудіо.
|
||||
Це дозволяє зосередити озвучене відтворення на тексті для абонента й уникнути витоку тексту планування в аудіо.
|
||||
|
||||
### Поведінка під час запуску розмови
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів у режимі `conversation` обробка першого повідомлення прив’язана до стану живого відтворення:
|
||||
Для вихідних дзвінків `conversation` обробка першого повідомлення прив’язана до стану живого відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише поки початкове привітання активно озвучується.
|
||||
- Якщо початкове відтворення не вдається, виклик повертається до стану `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для Twilio streaming починається після підключення потоку без додаткової затримки.
|
||||
- Очищення черги barge-in та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується.
|
||||
- Якщо початкове відтворення не вдається, дзвінок повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокової передачі Twilio починається при підключенні потоку без додаткової затримки.
|
||||
|
||||
### Пільговий період після відключення потоку Twilio
|
||||
### Пільговий період при відключенні потоку Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call очікує `2000ms` перед автоматичним завершенням виклику:
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає `2000ms`, перш ніж автоматично завершити дзвінок:
|
||||
|
||||
- Якщо потік повторно підключається протягом цього вікна, автозавершення скасовується.
|
||||
- Якщо після завершення пільгового періоду потік не реєструється повторно, виклик завершується, щоб не допустити завислих активних викликів.
|
||||
- Якщо після завершення пільгового періоду жоден потік не реєструється знову, дзвінок завершується, щоб запобігти завислим активним дзвінкам.
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
|
||||
openclaw voicecall start --to "+15555550123" # псевдонім для call
|
||||
openclaw voicecall start --to "+15555550123" # alias for call
|
||||
openclaw voicecall continue --call-id <id> --message "Any questions?"
|
||||
openclaw voicecall speak --call-id <id> --message "One moment"
|
||||
openclaw voicecall end --call-id <id>
|
||||
openclaw voicecall status --call-id <id>
|
||||
openclaw voicecall tail
|
||||
openclaw voicecall latency # звести затримку кроків із логів
|
||||
openclaw voicecall latency # summarize turn latency from logs
|
||||
openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call. Використовуйте
|
||||
`--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити аналіз
|
||||
останніми N записами (типово 200). Вивід включає p50/p90/p99 для затримки кроків
|
||||
і часу очікування в режимі прослуховування.
|
||||
`--file <path>`, щоб вказати інший журнал, і `--last <n>`, щоб обмежити аналіз
|
||||
останніми N записами (типово 200). Вивід включає p50/p90/p99 для затримки
|
||||
ходу та часу очікування прослуховування.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user