Плагины

VibeOS имеет систему плагинов для добавления пользовательских инструментов, хуков и интеграций без изменения основного кода.

Если вы хотите создать собственный инструмент для себя, своей команды или одного проекта, это обычно правильный путь. Страница руководства разработчика Добавление инструментов предназначена для встроенных инструментов ядра VibeOS, которые находятся в tools/ и toolsets.py.

→ Создайте плагин VibeOS — пошаговое руководство с полным рабочим примером.

Краткий обзор

Поместите каталог в ~/.vibeos/plugins/ с файлом plugin.yaml и кодом Python:

~/.vibeos/plugins/my-plugin/
├── plugin.yaml      # манифест
├── __init__.py      # register() — связывает схемы с обработчиками
├── schemas.py       # схемы инструментов (что видит LLM)
└── tools.py         # обработчики инструментов (что выполняется при вызове)

Запустите VibeOS — ваши инструменты появятся рядом со встроенными. Модель может вызывать их немедленно.

Минимальный рабочий пример

Вот полный плагин, который добавляет инструмент hello_world и регистрирует каждый вызов инструмента через хук.

~/.vibeos/plugins/hello-world/plugin.yaml

name: hello-world
version: "1.0"
description: Пример минимального плагина

~/.vibeos/plugins/hello-world/__init__.py

"""Минимальный плагин VibeOS — регистрирует инструмент и хук."""

import json


def register(ctx):
    # --- Инструмент: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Возвращает дружеское приветствие для указанного имени.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Имя для приветствия",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Возвращает дружеское приветствие для указанного имени.",
    )

    # --- Хук: регистрировать каждый вызов инструмента ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] вызван инструмент: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

Поместите оба файла в ~/.vibeos/plugins/hello-world/, перезапустите VibeOS, и модель сможет немедленно вызывать hello_world. Хук выводит строку лога после каждого вызова инструмента.

Локальные плагины проекта в ./.vibeos/plugins/ по умолчанию отключены. Включайте их только для доверенных репозиториев, установив VIBEOS_ENABLE_PROJECT_PLUGINS=true перед запуском VibeOS.

Что могут делать плагины

Каждый API ctx.* ниже доступен внутри функции register(ctx) плагина.

Возможность	Как
Добавлять инструменты	`ctx.register_tool(name=..., toolset=..., schema=..., handler=...)`
Добавлять хуки	`ctx.register_hook("post_tool_call", callback)`
Добавлять слеш-команды	`ctx.register_command(name, handler, description)` — добавляет `/name` в CLI и шлюзовых сессиях
Отправлять инструменты из команд	`ctx.dispatch_tool(name, args)` — вызывает зарегистрированный инструмент с автоматической привязкой контекста родительского агента
Добавлять CLI-команды	`ctx.register_cli_command(name, help, setup_fn, handler_fn)` — добавляет `vibeos <plugin>` <subcommand>`
Внедрять сообщения	`ctx.inject_message(content, role="user")` — см. Внедрение сообщений
Поставлять файлы данных	`Path(__file__).parent / "data" / "file.yaml"`
Включать навыки	`ctx.register_skill(name, path)` — пространство имён `plugin:skill`, загружается через `skill_view("plugin:skill")`
Ограничивать переменными окружения	`requires_env: [API_KEY]` в plugin.yaml — запрашивается во время `vibeos plugins install`
Распространять через pip	`[project.entry-points."vibeos_agent.plugins"]`
Регистрировать платформу шлюза (Discord, Telegram, IRC, …)	`ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — см. Добавление адаптеров платформ
Регистрировать бэкенд генерации изображений	`ctx.register_image_gen_provider(provider)` — см. Плагины провайдеров генерации изображений
Регистрировать бэкенд генерации видео	`ctx.register_video_gen_provider(provider)` — см. Плагины провайдеров генерации видео
Регистрировать движок сжатия контекста	`ctx.register_context_engine(engine)` — см. Плагины движков контекста
Регистрировать бэкенд памяти	Создайте подкласс `MemoryProvider` в `plugins/memory/<name>/__init__.py` — см. Плагины провайдеров памяти (использует отдельную систему обнаружения)
Выполнять LLM-вызов от хоста	`ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — использует активную модель пользователя + аутентификацию для одноразового завершения с опциональной валидацией JSON-схемы. См. Доступ плагинов к LLM
Регистрировать бэкенд вывода (LLM-провайдер)	`register_provider(ProviderProfile(...))` в `plugins/model-providers/<name>/__init__.py` — см. Плагины провайдеров моделей (использует отдельную систему обнаружения)

Обнаружение плагинов

Источник	Путь	Сценарий использования
Встроенные	`<repo>/plugins/`	Поставляются с VibeOS — см. Встроенные плагины
Пользовательские	`~/.vibeos/plugins/`	Личные плагины
Проектные	`.vibeos/plugins/`	Плагины для конкретного проекта (требуется `VIBEOS_ENABLE_PROJECT_PLUGINS=true`)
pip	`vibeos_agent.plugins` entry_points	Распространяемые пакеты
Nix	`services.vibeos-agent.extraPlugins` / `extraPythonPackages`	Декларативные установки NixOS — см. Установка через Nix

Более поздние источники переопределяют более ранние при совпадении имён, поэтому пользовательский плагин с тем же именем, что и встроенный, заменяет его.

Подкатегории плагинов

Внутри каждого источника VibeOS также распознаёт каталоги подкатегорий, которые направляют плагины в специализированные системы обнаружения:

Подкаталог	Что содержит	Система обнаружения
`plugins/` (корень)	Общие плагины — инструменты, хуки, слеш-команды, CLI-команды, встроенные навыки	`PluginManager` (kind: `standalone` или `backend`)
`plugins/platforms/<name>/`	Адаптеры каналов шлюза (`ctx.register_platform()`)	`PluginManager` (kind: `platform`, на один уровень глубже)
`plugins/image_gen/<name>/`	Бэкенды генерации изображений (`ctx.register_image_gen_provider()`)	`PluginManager` (kind: `backend`, на один уровень глубже)
`plugins/memory/<name>/`	Провайдеры памяти (подкласс `MemoryProvider`)	Собственный загрузчик в `plugins/memory/__init__.py` (kind: `exclusive` — один активен за раз)
`plugins/context_engine/<name>/`	Движки сжатия контекста (`ctx.register_context_engine()`)	Собственный загрузчик в `plugins/context_engine/__init__.py` (один активен за раз)
`plugins/model-providers/<name>/`	Профили LLM-провайдеров (`register_provider(ProviderProfile(...))`)	Собственный загрузчик в `providers/__init__.py` (лениво сканируется при первом вызове `get_provider_profile()`)

Пользовательские плагины в ~/.vibeos/plugins/model-providers/<name>/ и ~/.vibeos/plugins/memory/<name>/ переопределяют встроенные плагины с тем же именем — последний записавший побеждает в register_provider() / register_memory_provider(). Поместите каталог, и он заменит встроенный без каких-либо изменений в репозитории.

Плагины — это opt-in (с несколькими исключениями)

Общие плагины и установленные пользователем бэкенды по умолчанию отключены — обнаружение находит их (поэтому они отображаются в vibeos plugins и /plugins), но ничего с хуками или инструментами не загружается, пока вы не добавите имя плагина в plugins.enabled в ~/.vibeos/config.yaml. Это предотвращает выполнение стороннего кода без вашего явного согласия.

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # опциональный список запрета — всегда побеждает, если имя есть в обоих
    - noisy-plugin

Три способа изменить состояние:

vibeos plugins                    # интерактивное переключение (пробел для отметки/снятия)
vibeos plugins enable <name>      # добавить в белый список
vibeos plugins disable <name>     # удалить из белого списка + добавить в запрещённые

После vibeos plugins install owner/repo появляется запрос Включить 'name' сейчас? [y/N] — по умолчанию нет. Пропустите запрос для скриптовых установок с помощью --enable или --no-enable.

Что белый список НЕ блокирует

Несколько категорий плагинов обходят plugins.enabled — они являются частью встроенной поверхности VibeOS и нарушили бы базовую функциональность, если бы были заблокированы по умолчанию:

Тип плагина	Как активируется вместо этого
Встроенные плагины платформ (IRC, Teams и т.д. в `plugins/platforms/`)	Автоматически загружаются, чтобы каждый поставляемый канал шлюза был доступен. Фактический канал включается через `gateway.platforms.<name>.enabled` в `config.yaml`.
Встроенные бэкенды (провайдеры генерации изображений в `plugins/image_gen/` и т.д.)	Автоматически загружаются, чтобы бэкенд по умолчанию «просто работал». Выбор происходит через `<category>.provider` в `config.yaml` (например, `image_gen.provider: openai`).
Провайдеры памяти (`plugins/memory/`)	Все обнаруженные; ровно один активен, выбирается через `memory.provider` в `config.yaml`.
Движки контекста (`plugins/context_engine/`)	Все обнаруженные; один активен, выбирается через `context.engine` в `config.yaml`.
Провайдеры моделей (`plugins/model-providers/`)	Все встроенные провайдеры в `plugins/model-providers/` обнаруживаются и регистрируются при первом вызове `get_provider_profile()`. Пользователь выбирает один за раз через `--provider` или `config.yaml`.
Плагины бэкендов, установленные через pip	Opt-in через `plugins.enabled` (как и общие плагины).
Установленные пользователем платформы (в `~/.vibeos/plugins/platforms/`)	Opt-in через `plugins.enabled` — сторонние адаптеры шлюзов требуют явного согласия.

Коротко: встроенная инфраструктура «всегда работает» загружается автоматически; сторонние общие плагины — opt-in. Белый список plugins.enabled — это шлюз специально для произвольного кода, который пользователь помещает в ~/.vibeos/plugins/.

Миграция для существующих пользователей

При обновлении до версии VibeOS с opt-in плагинами (схема конфига v21+) любые пользовательские плагины, уже установленные в ~/.vibeos/plugins/, которые не были в plugins.disabled, автоматически переносятся в plugins.enabled. Ваша существующая настройка продолжает работать. Встроенные автономные плагины НЕ переносятся — даже существующие пользователи должны явно включить их. (Встроенные плагины платформ/бэкендов никогда не нуждались в переносе, потому что они никогда не были заблокированы.)

Доступные хуки

Плагины могут регистрировать обратные вызовы для этих событий жизненного цикла. Полные сведения, сигнатуры обратных вызовов и примеры см. на странице Хуки событий.

Хук	Срабатывает когда
`pre_tool_call`	Перед выполнением любого инструмента
`post_tool_call`	После возврата любого инструмента
`pre_llm_call`	Один раз за ход, перед циклом LLM — может вернуть `{"context": "..."}` для внедрения контекста в сообщение пользователя
`post_llm_call`	Один раз за ход, после цикла LLM (только успешные ходы)
`on_session_start`	Создана новая сессия (только первый ход)
`on_session_end`	Конец каждого вызова `run_conversation` + обработчик выхода из CLI
`on_session_finalize`	CLI/шлюз завершает активную сессию (`/new`, GC, выход из CLI)
`on_session_reset`	Шлюз заменяет ключ сессии (`/new`, `/reset`, `/clear`, ротация бездействия)
`subagent_stop`	Один раз для каждого дочернего агента после завершения `delegate_task`
`pre_gateway_dispatch`	Шлюз получил сообщение пользователя, до аутентификации и отправки. Верните `{"action": "skip" \| "rewrite" \| "allow", ...}` для управления потоком.

Типы плагинов

VibeOS имеет четыре вида плагинов:

Тип	Что делает	Выбор	Расположение
Общие плагины	Добавляют инструменты, хуки, слеш-команды, CLI-команды	Множественный выбор (включить/отключить)	`~/.vibeos/plugins/`
Провайдеры памяти	Заменяют или дополняют встроенную память	Одиночный выбор (один активен)	`plugins/memory/`
Движки контекста	Заменяют встроенный компрессор контекста	Одиночный выбор (один активен)	`plugins/context_engine/`
Провайдеры моделей	Объявляют бэкенд вывода (OpenRouter, Anthropic, …)	Множественная регистрация, выбирается через `--provider` / `config.yaml`	`plugins/model-providers/`

Провайдеры памяти и движки контекста являются провайдерскими плагинами — только один каждого типа может быть активен одновременно. Провайдеры моделей также являются плагинами, но многие загружаются одновременно; пользователь выбирает один за раз через --provider или config.yaml. Общие плагины могут быть включены в любой комбинации.

Подключаемые интерфейсы — куда обратиться для каждого

Таблица выше показывает четыре категории плагинов, но внутри «Общих плагинов» PluginContext предоставляет несколько различных точек расширения — и VibeOS также принимает расширения вне системы Python-плагинов (бэкенды на основе конфигурации, команды с привязкой к оболочке, внешние серверы и т.д.). Используйте эту таблицу, чтобы найти правильную документацию для того, что вы хотите создать:

Хотите добавить…	Как	Руководство по созданию
Инструмент, который может вызывать LLM	Python-плагин — `ctx.register_tool()`	Создайте плагин VibeOS · Добавление инструментов
Хук жизненного цикла (до/после LLM, начало/конец сессии, фильтр инструментов)	Python-плагин — `ctx.register_hook()`	Справочник по хукам · Создайте плагин VibeOS
Слеш-команду для CLI / шлюза	Python-плагин — `ctx.register_command()`	Создайте плагин VibeOS · Расширение CLI
Подкоманду для `vibeos <thing>	Python-плагин — `ctx.register_cli_command()`	Расширение CLI
Встроенный навык, который поставляет ваш плагин	Python-плагин — `ctx.register_skill()`	Создание навыков
Бэкенд вывода (LLM-провайдер: OpenAI-совместимый, Codex, Anthropic-Messages, Bedrock)	Плагин провайдера — `register_provider(ProviderProfile(...))` в `plugins/model-providers/<name>/`	Плагины провайдеров моделей · Добавление провайдеров
Канал шлюза (Discord / Telegram / IRC / Teams / и т.д.)	Плагин платформы — `ctx.register_platform()` в `plugins/platforms/<name>/`	Добавление адаптеров платформ
Бэкенд памяти (Honcho, Mem0, Supermemory, …)	Плагин памяти — подкласс `MemoryProvider` в `plugins/memory/<name>/`	Плагины провайдеров памяти
Стратегию сжатия контекста	Плагин движка контекста — `ctx.register_context_engine()`	Плагины движков контекста
Бэкенд генерации изображений (DALL·E, SDXL, …)	Плагин бэкенда — `ctx.register_image_gen_provider()`	Плагины провайдеров генерации изображений
Бэкенд генерации видео (Veo, Kling, Pixverse, Grok-Imagine, Runway, …)	Плагин бэкенда — `ctx.register_video_gen_provider()`	Плагины провайдеров генерации видео
Бэкенд TTS (любой CLI — Piper, VoxCPM, Kokoro, xtts, скрипты клонирования голоса, …)	На основе конфигурации (рекомендуется) — объявите в `tts.providers.<name> с` type: command`в`config.yaml`. ИЛИ Python-плагин бэкенда —` ctx.register_tts_provider()` для движков с Python-SDK / потоковой передачей, которым нужно больше, чем шаблон оболочки.	Настройка TTS · Руководство по Python-плагину
Бэкенд STT (любой CLI — whisper.cpp, пользовательский бинарник whisper, локальный ASR CLI)	На основе конфигурации (рекомендуется) — объявите в `stt.providers.<name> с` type: command`в`config.yaml`, или установите` VIBEOS_LOCAL_STT_COMMAND`для устаревшего запасного варианта с одной командой. ИЛИ Python-плагин бэкенда —`ctx.register_transcription_provider()` для движков с Python-SDK (OpenRouter, SenseAudio, Gemini-STT и т.д.).	Настройка STT · Руководство по Python-плагину
Внешние инструменты через MCP (файловая система, GitHub, Linear, Notion, любой MCP-сервер)	На основе конфигурации — объявите `mcp_servers.<name> с` command:`/`url:`в`config.yaml`. VibeOS автоматически обнаруживает инструменты сервера и регистрирует их вместе со встроенными.	MCP
Дополнительные источники навыков (пользовательские репозитории GitHub, частные индексы навыков)	CLI — `vibeos skills tap add` <repo>`	Хаб навыков · Публикация пользовательского tap
Хуки событий шлюза (срабатывают на `gateway:startup`, `session:start`, `agent:end`, `command:*`)	Поместите `HOOK.yaml` + `handler.py` в `~/.vibeos/hooks/<name>/`	Хуки событий
Хуки оболочки (выполняют команду оболочки при событиях — уведомления, журналы аудита, оповещения на рабочем столе)	На основе конфигурации — объявите в `hooks:` в `config.yaml`	Хуки оболочки

примечание

Не всё является Python-плагином. Некоторые поверхности расширения намеренно используют команды оболочки на основе конфигурации (TTS, STT, хуки оболочки), чтобы любой существующий CLI стал плагином без написания Python. Другие — это внешние серверы (MCP), к которым агент подключается и автоматически регистрирует инструменты. А некоторые — это каталоги для размещения (хуки шлюза) со своим собственным форматом манифеста. Выберите правильную поверхность для стиля интеграции, который подходит вашему случаю использования; руководства по созданию в таблице выше охватывают заполнители, обнаружение и примеры.

Декларативные плагины NixOS

На NixOS плагины могут быть установлены декларативно через опции модуля — без необходимости vibeos plugins install. Полные сведения см. в руководстве по установке Nix.

services.vibeos-agent = {
  # Плагин из каталога (дерево исходников с plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # Плагин через entry-point (pip-пакет)
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
  # Включить в конфиге
  settings.plugins.enabled = [ "my-plugin" ];
};

Декларативные плагины связываются символическими ссылками с префиксом nix-managed- — они сосуществуют с плагинами, установленными вручную, и автоматически удаляются при удалении из конфигурации Nix.

Управление плагинами

vibeos plugins                               # единый интерактивный интерфейс
vibeos plugins list                          # таблица: включено / отключено / не включено
vibeos plugins install user/repo             # установить из Git, затем запрос Включить? [y/N]
vibeos plugins install user/repo --enable    # установить И включить (без запроса)
vibeos plugins install user/repo --no-enable # установить, но оставить отключённым (без запроса)
vibeos plugins update my-plugin              # получить последнюю версию
vibeos plugins remove my-plugin              # удалить
vibeos plugins enable my-plugin              # добавить в белый список
vibeos plugins disable my-plugin             # удалить из белого списка + добавить в запрещённые

Интерактивный интерфейс

Запуск vibeos plugins без аргументов открывает составной интерактивный экран:

Плагины
  ↑↓ навигация  ПРОБЕЛ переключить  ВВОД настроить/подтвердить  ESC готово

  Общие плагины
 → [✓] my-tool-plugin — Пользовательский инструмент поиска
   [ ] webhook-notifier — Хуки событий
   [ ] disk-cleanup — Автоматическая очистка временных файлов [встроенный]

  Провайдерские плагины
     Провайдер памяти          ▸ honcho
     Движок контекста           ▸ compressor

Раздел «Общие плагины» — флажки, переключение ПРОБЕЛОМ. Отмечено = в plugins.enabled, не отмечено = в plugins.disabled (явное выключение).
Раздел «Провайдерские плагины» — показывает текущий выбор. Нажмите ВВОД, чтобы войти в переключатель радио-кнопок, где вы выбираете одного активного провайдера.
Встроенные плагины отображаются в том же списке с тегом [встроенный].

Выбор провайдерских плагинов сохраняется в config.yaml:

memory:
  provider: "honcho"      # пустая строка = только встроенный

context:
  engine: "compressor"    # встроенный компрессор по умолчанию

Включено, отключено или ни то, ни другое

Плагины находятся в одном из трёх состояний:

Состояние	Значение	В `plugins.enabled`?	В `plugins.disabled`?
`enabled`	Загружен при следующей сессии	Да	Нет
`disabled`	Явно выключен — не загрузится, даже если также в `enabled`	(неважно)	Да
`not enabled`	Обнаружен, но никогда не включён	Нет	Нет

По умолчанию для нового установленного или встроенного плагина — not enabled. vibeos plugins list показывает все три различных состояния, чтобы вы могли видеть, что было явно выключено, а что просто ожидает включения.

В работающей сессии /plugins показывает, какие плагины загружены в данный момент.

Внедрение сообщений

Плагины могут внедрять сообщения в активный разговор с помощью ctx.inject_message():

ctx.inject_message("Новые данные получены от вебхука", role="user")

Сигнатура: ctx.inject_message(content: str, role: str = "user") -> bool

Как это работает:

Если агент бездействует (ожидает ввода пользователя), сообщение помещается в очередь как следующий ввод и начинает новый ход.
Если агент в середине хода (активно работает), сообщение прерывает текущую операцию — так же, как если бы пользователь ввёл новое сообщение и нажал Enter.
Для ролей, отличных от "user", содержимое предваряется префиксом [role] (например, [system] ...).
Возвращает True, если сообщение было успешно поставлено в очередь, False, если нет ссылки на CLI (например, в режиме шлюза).

Это позволяет таким плагинам, как пульты удалённого управления, мосты обмена сообщениями или приёмники вебхуков, передавать сообщения в разговор из внешних источников.

примечание

inject_message доступен только в режиме CLI. В режиме шлюза нет ссылки на CLI, и метод возвращает False.

Полные сведения о контрактах обработчиков, формате схем, поведении хуков, обработке ошибок и распространённых ошибках см. в полном руководстве.

Краткий обзор​

Минимальный рабочий пример​

Что могут делать плагины​

Обнаружение плагинов​

Подкатегории плагинов​

Плагины — это opt-in (с несколькими исключениями)​

Что белый список НЕ блокирует​

Миграция для существующих пользователей​

Доступные хуки​

Типы плагинов​

Подключаемые интерфейсы — куда обратиться для каждого​

Декларативные плагины NixOS​

Управление плагинами​

Интерактивный интерфейс​

Включено, отключено или ни то, ни другое​

Внедрение сообщений​