Додавання можливостей (посібник для контриб'юторів)

Використовуйте це, коли OpenClaw потрібна нова спільна доменна область, така як генерація зображень, генерація відео або майбутня функціональна область, підтримана постачальником.

Правило:

• Plugin = межа володіння
• можливість = спільний контракт ядра

Не починайте з підключення постачальника безпосередньо до каналу або інструмента. Починайте з визначення можливості.

# Коли створювати можливість

Створюйте нову можливість, коли всі ці умови виконуються:

1. Її правдоподібно могли б реалізувати кілька постачальників.
2. Канали, інструменти або функціональні Plugin мають споживати її, не зважаючи на постачальника.
3. Ядро має володіти fallback, політикою, конфігурацією або поведінкою доставки.

Якщо робота стосується лише постачальника і спільного контракту ще немає, зупиніться й спершу визначте контракт.

# Стандартна послідовність

1. Визначте типізований контракт ядра.
2. Додайте реєстрацію Plugin для цього контракту.
3. Додайте спільний runtime-помічник.
4. Підключіть один реальний Plugin постачальника як доказ.
5. Переведіть споживачів функцій/каналів на runtime-помічник.
6. Додайте тести контракту.
7. Задокументуйте конфігурацію для оператора й модель володіння.

# Що куди належить

Ядро:

• Типи запиту/відповіді.
• Реєстр постачальників + розв’язання.
• Поведінка fallback.
• Схема конфігурації з поширеними метаданими документації title / description на вкладених об’єктах, wildcard, елементах масиву та вузлах композиції.
• Поверхня runtime-помічника.

Plugin постачальника:

• Виклики API постачальника.
• Обробка автентифікації постачальника.
• Нормалізація запитів, специфічна для постачальника.
• Реєстрація реалізації можливості.

Функціональний/канальний Plugin:

• Викликає api.runtime.* або відповідний помічник plugin-sdk/*-runtime.
• Ніколи не викликає реалізацію постачальника напряму.

# Шви постачальника та harness

Використовуйте хуки постачальника, коли поведінка належить контракту постачальника моделі, а не generic agent loop. Приклади включають параметри запиту, специфічні для постачальника, після вибору транспорту, пріоритет auth-profile, накладки prompt і маршрутизацію follow-up fallback після failover моделі/профілю.

Використовуйте хуки agent harness, коли поведінка належить runtime, який виконує turn. Harness можуть класифікувати успішні, але непридатні результати спроб, як-от порожні відповіді, відповіді лише з reasoning або лише з плануванням, щоб зовнішня політика model fallback могла ухвалити рішення про повторну спробу.

Тримайте обидва шви вузькими:

• Ядро володіє політикою повторів/fallback.
• Plugin постачальників володіють підказками для запитів/auth/маршрутизації, специфічними для постачальника.
• Harness Plugin володіють класифікацією спроб, специфічною для runtime.
• Сторонні Plugin повертають підказки, а не прямі мутації стану ядра.

# Контрольний список файлів

Для нової можливості очікуйте змін у таких областях:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• Один або кілька bundled plugin packages.
• Конфігурація, документація, тести.

# Робочий приклад: генерація зображень

Генерація зображень відповідає стандартній формі:

1. Ядро визначає ImageGenerationProvider.
2. Ядро експортує registerImageGenerationProvider(...).
3. Ядро експортує runtime.imageGeneration.generate(...).
4. Plugin openai, google, fal і minimax реєструють реалізації, підтримані постачальниками.
5. Майбутні постачальники реєструють той самий контракт без зміни каналів/інструментів.

Ключ конфігурації навмисно відокремлений від маршрутизації аналізу зору:

• agents.defaults.imageModel аналізує зображення.
• agents.defaults.imageGenerationModel генерує зображення.

Тримайте їх окремо, щоб fallback і політика залишалися явними.

# Контрольний список рев’ю

Перед постачанням нової можливості перевірте:

• Жоден канал/інструмент не імпортує код постачальника напряму.
• Runtime-помічник є спільним шляхом.
• Принаймні один тест контракту перевіряє bundled ownership.
• Документація конфігурації називає новий ключ моделі/конфігурації.
• Документація Plugin пояснює межу володіння.

Якщо PR пропускає шар можливостей і жорстко вбудовує поведінку постачальника в канал/інструмент, поверніть його й спершу визначте контракт.

# Пов’язане

• Внутрішня архітектура Plugin — модель можливостей, володіння, конвеєр завантаження, runtime-помічники.
• Створення Plugin — посібник зі створення першого Plugin.
• Огляд SDK — довідник карти імпортів і API реєстрації.
• Створення Skills — супровідна поверхня для контриб’юторів.