ВойтиСкачать
VibeCode SDK · Plugin API 2

Создавайте инструменты для ВайбКода.

Ваш сервис, интерфейс и рабочий процесс — внутри приложения. Публичный SDK, типизированный API и готовые примеры. Исходники приложения не нужны.

Скачать SDK 2.0Первый плагин

ZIPMITNode.js 20+ВайбКод 0.9.18+

my-pluginтерминал
# шаблон из CLI внутри архива SDK
❯ node scripts/extension.mjs create ../my-plugin
❯ cd ../my-plugin && npm install && npm run build
# проверка и сборка пакета
❯ cd ../vibecode-sdk
❯ node scripts/extension.mjs validate ../my-plugin/dist
❯ node scripts/extension.mjs pack ../my-plugin/dist \
    ../my-plugin.vibee-plugin
# дальше: Настройки → Расширения приложения
my-plugin.vibee-pluginустанавливается выключенным
ЛицензияMITSDK и примеры открыты для доработки
Примеры3 примераМинимальный, workspace и HTTP
Plugin APIAPI 1 + 2Совместимость существующих расширений
01

Первый плагин

Используйте Приложение ВайбКод 0.9.18 или новее. Установите Node.js 20 или новее и распакуйте SDK. CLI входит в архив и не требует установки npm-пакета SDK.

Терминалbash · PowerShell
cd vibecode-sdk
node scripts/extension.mjs create ../my-plugin
cd ../my-plugin
npm install
npm run build
cd ../vibecode-sdk
node scripts/extension.mjs validate ../my-plugin/dist
node scripts/extension.mjs pack ../my-plugin/dist ../my-plugin.vibee-plugin

В приложении откройте «Настройки → Расширения приложения → Установить из файла». Пакет устанавливается выключенным. Выберите разрешения, затем включите расширение.

Для новых поверхностей требуется сборка приложения с Plugin API 2. Версия приложения и версия Plugin API — разные значения. Обычные примеры находятся в папке examples; каждый уже готов к validate и pack.

02

Манифест и формат пакета

manifest.jsonкорень пакета
{
  "manifestVersion": 1,
  "id": "publisher.service",
  "name": "Мой сервис",
  "version": "1.0.0",
  "publisher": "Publisher",
  "description": "Инструменты моего сервиса",
  "engines": { "vibee": "^2.0.0" },
  "main": "main.js",
  "pages": [{ "id": "home", "title": "Мой сервис", "entry": "index.html", "surface": "panel" }],
  "permissions": ["storage", "workspace.metadata", "ui.surfaces"],
  "commands": [{ "id": "open", "title": "Открыть панель" }]
}

Нормативная схема — src/shared/extension-manifest.schema.json в SDK. Пакет .vibee-plugin — ZIP с манифестом в корне.

  • 32 МиБраспакованных данных максимум
  • 1000файлов в пакете максимум
  • Без CDNскрипты, шрифты и изображения — внутри пакета

Абсолютные пути, симлинки и выход через .. запрещены.

03

API: runtime и интерфейс

main.js экспортирует activate(sdk). В нём регистрируйте команды и инструменты; активация должна завершиться за 10 секунд. В HTML-странице используйте window.vibeePlugin. TypeScript-контракт полностью включён в src/shared/extensions.ts.

main.jsactivate(sdk)
export async function activate(sdk) {
  sdk.commands.register('open', async () => {
    const workspace = await sdk.workspace.current();
    if (!workspace) throw new Error('Выберите разрешённый проект');
    await sdk.ui.openPanel('home', workspace.root);
  });
}
Справочник10 групп
ГруппаМетоды и назначение
info()ID, версия API, язык и тема приложения.
storageget(key), set(key, value), delete(key): собственное хранилище расширения.
commandsregister(id, handler) внутри activate; execute(id, input) из страницы.
httprequest({url, method, body, credentialId, timeoutMs, streamId}), cancel(id), onChunk(callback). Возвращает status, headers, body.
auth / credentialsauth.connect({id, authorizationUrl, tokenUrl, clientId, scopes}); credentials.list(), remove(id). Секреты не возвращаются странице.
workspaceroots(), list(), current(), read(root, path), write(root, path, text), onChanged(callback).
uinotify(message), openExternal(url), openPage(id), openTab(id, root), openPanel(id, root), closeSurface().
agentToolsregister(id, handler). Инструмент, effect и JSON Schema объявляются в манифесте; доступ агента к папке выдаётся отдельно.
operationslist(), set(operation): журнал внешних операций со статусами pending, running, succeeded, failed, unknown.
aiProviders / networkProvidersregister(provider): подключение сервисов через выданные разрешения. Форма provider описана в типах SDK.

Асинхронные методы возвращают Promise. Ошибки обрабатывайте через try/catch и показывайте пользователю. Не повторяйте неизвестный результат покупки или публикации: сначала сверяйте состояние с сервером сервиса.

04

Вкладки, панели и события

surface: "tab" занимает рабочую область; "panel" открывает боковую панель. Оба варианта используют изолированный WebContentsView. Корень должен быть разрешён расширению и выбран в приложении.

  • Режим Codeповерхности видны только в нём
  • Скрываютсяпри переходе в библиотеку, настройки или диалог
  • Закрываютсяпо Escape и при смене проекта

Отключение расширения освобождает её ресурсы.

index.htmlwindow.vibeePlugin
const sdk = window.vibeePlugin;
const off = sdk.workspace.onChanged(event => {
  // event.type: opened, closed, selected
  // event.workspace: только разрешённые метаданные либо null
  document.querySelector('h1').textContent = event.workspace?.name || 'Нет проекта';
});
window.addEventListener('pagehide', off);
document.querySelector('#close').onclick = () => sdk.ui.closeSurface();

Предусмотрите кнопку закрытия поверхности. Нет доступа к терминальному выводу, произвольным IPC или Electron. Файлы вне выданных корней недоступны.

05

Разрешения

storage
собственные данные
credentials
сохранённые подключения
http
запросы к объявленным origin и методам
background
фоновая активация
workspace.metadata
метаданные разрешённых проектов
workspace.events
события разрешённых проектов
workspace.read · write
файлы
ui.surfaces
панели и вкладки
agentTools · aiProviders · networkProviders
соответствующие интеграции

Запись файла подтверждается пользователем. Сетевые адреса и методы объявляются в network. Для локальных сервисов отдельно указывается local: true. Расширение выполняет клиентскую работу; владение аккаунтом и права на удалённые ресурсы проверяет ваш сервер.

Хеш пакета подтверждает целостность файла, а не личность автора. Удаление плагина не отменяет подписку и не удаляет удалённый сервер.

06

Разработка и диагностика

Подключайте собранную папку dist в режиме разработки. После изменения пересоберите проект, загрузите изменения и выдайте необходимые разрешения новой версии. Приложение работает со снимком пакета. Сообщения sdk.ui.notify и ошибки видны в карточке расширения.

Перед публикацией проверьте
  • отказ HTTP
  • отменённое разрешение
  • недоступный workspace
  • повторное открытие
  • отключение
  • обновление

Не используйте личные ключи в примерах и не включайте .env в пакет.

07

Версии и миграция

API 1 поддерживается наряду с API 2. Для новых методов требуется engines.vibee: "^2.0.0". Новые разрешения и surface объявляйте явно. Существующие плагины API 1 не получают дополнительные права при обновлении приложения.

SDK2.0.0типы, CLI и схема
Plugin API1 + 2новые методы — с ^2.0.0
manifestVersion1остаётся прежним

Версию своего плагина повышайте по semver, описывайте новые разрешения и изменения данных.

08

Попасть в библиотеку

Предоставьте публичный репозиторий или страницу релиза, лицензию, описание, совместимость и список разрешений. Мы проверяем структуру и рассматриваем заявку вручную. Отправка заявки не публикует плагин автоматически.

Предложить плагин, MCP, скилл или промпт