Создание плагина VibeOS

Это руководство проведёт вас через создание полноценного плагина VibeOS с нуля. В результате вы получите работающий плагин с несколькими инструментами, хуками жизненного цикла, поставляемыми файлами данных и встроенным навыком — всё, что поддерживает система плагинов.

Не уверены, какой гайд вам нужен?

VibeOS имеет несколько различных подключаемых интерфейсов — некоторые используют Python register_* API, другие управляются через конфигурацию или каталоги. Сначала воспользуйтесь этой картой:

Если вы хотите добавить…	Читайте
Пользовательские инструменты, хуки, слеш-команды, навыки или CLI-подкоманды	Это руководство (общая поверхность плагинов)
LLM / бэкенд для инференса (новый провайдер)	Плагины провайдеров моделей
Канал шлюза (Discord/Telegram/IRC/Teams и т.д.)	Добавление адаптеров платформ
Бэкенд памяти (Honcho/Mem0/Supermemory и т.д.)	Плагины провайдеров памяти
Движок сжатия контекста	Плагины движков контекста
Бэкенд генерации изображений	Плагины провайдеров генерации изображений
Бэкенд генерации видео	Плагины провайдеров генерации видео
TTS бэкенд (любой CLI — Piper, VoxCPM, Kokoro, клонирование голоса, …)	Провайдеры пользовательских команд TTS — управляется конфигом, Python не нужен
STT бэкенд (пользовательский whisper / ASR CLI)	Транскрипция голосовых сообщений — установите `VIBEOS_LOCAL_STT_COMMAND` в шаблон команды
Внешние инструменты через MCP (файловая система, GitHub, Linear, любой MCP-сервер)	MCP — объявите `mcp_servers.<name>` в `config.yaml`
Хуки событий шлюза (срабатывают при запуске, событиях сессии, командах)	Хуки событий — поместите `HOOK.yaml` + `handler.py` в `~/.vibeos/hooks/<name>/`
Шелл-хуки (выполнить shell-команду по событиям)	Шелл-хуки — объявите в разделе `hooks:` в `config.yaml`
Дополнительные источники навыков (пользовательские репозитории GitHub, частные индексы навыков)	Навыки — `vibeos skills tap add <repo>` · Публикация tap
Первоклассный основной провайдер инференса (не плагин)	Добавление провайдеров

Смотрите полную Таблицу подключаемых интерфейсов для сводного обзора всех точек расширения, включая управляемые конфигом (TTS, STT, MCP, шелл-хуки) и каталоги (хуки шлюза).

Плагины сторонних продуктов поставляются отдельно — не в основное дерево

Плагины, интегрирующие чей-то чужой продукт или проект — бэкенды наблюдаемости/метрик, вендорские SaaS-коннекторы, панели аналитики, интеграции с платными сервисами — создаются и распространяются как отдельные репозитории плагинов, а не сливаются в Linx72/VibeOS. Пользователи устанавливают их в ~/.vibeos/plugins/ или через точку входа pip; всё в этом руководстве работает так же из отдельного репозитория. Это решение о связности и поддержке (ядро быстро развивается, и мы не владеем вашим бэкендом), а не планка качества — плагин может быть отличным и всё равно находиться в своём репозитории. Продвигайте его через GitHub Issues или README вашего репозитория плагина. Смотрите CONTRIBUTING.md для политики.

Что вы создаёте

Плагин калькулятора с двумя инструментами:

calculate — вычисление математических выражений (2**16, sqrt(144), pi * 5**2)
unit_convert — конвертация между единицами измерения (100 F → 37.78 C, 5 km → 3.11 mi)

Плюс хук, который логирует каждый вызов инструмента, и встроенный файл навыка.

Шаг 1: Создайте каталог плагина

mkdir -p ~/.vibeos/plugins/calculator
cd ~/.vibeos/plugins/calculator

Шаг 2: Напишите манифест

Создайте plugin.yaml:

name: calculator
version: 1.0.0
description: Математический калькулятор — вычисление выражений и конвертация единиц
provides_tools:
  - calculate
  - unit_convert
provides_hooks:
  - post_tool_call

Это говорит VibeOS: «Я плагин под названием calculator, я предоставляю инструменты и хуки». Поля provides_tools и provides_hooks — это списки того, что регистрирует плагин.

Необязательные поля, которые можно добавить:

author: Ваше Имя
requires_env:          # блокирует загрузку, если нет env-переменных; запрашивается при установке
  - SOME_API_KEY       # простой формат — плагин отключён, если отсутствует
  - name: OTHER_KEY    # расширенный формат — показывает описание/url при установке
    description: "Ключ для сервиса Other"
    url: "https://other.com/keys"
    secret: true

Шаг 3: Напишите схемы инструментов

Создайте schemas.py — это то, что читает LLM, чтобы решить, когда вызывать ваши инструменты:

"""Схемы инструментов — то, что видит LLM."""

CALCULATE = {
    "name": "calculate",
    "description": (
        "Вычисляет математическое выражение и возвращает результат. "
        "Поддерживает арифметику (+, -, *, /, **), функции (sqrt, sin, cos, "
        "log, abs, round, floor, ceil) и константы (pi, e). "
        "Используйте для любой математики, о которой спрашивает пользователь."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Математическое выражение для вычисления (например, '2**10', 'sqrt(144)')",
            },
        },
        "required": ["expression"],
    },
}

UNIT_CONVERT = {
    "name": "unit_convert",
    "description": (
        "Конвертирует значение между единицами измерения. Поддерживает длину (m, km, mi, ft, in), "
        "вес (kg, lb, oz, g), температуру (C, F, K), данные (B, KB, MB, GB, TB) "
        "и время (s, min, hr, day)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "value": {
                "type": "number",
                "description": "Числовое значение для конвертации",
            },
            "from_unit": {
                "type": "string",
                "description": "Исходная единица (например, 'km', 'lb', 'F', 'GB')",
            },
            "to_unit": {
                "type": "string",
                "description": "Целевая единица (например, 'mi', 'kg', 'C', 'MB')",
            },
        },
        "required": ["value", "from_unit", "to_unit"],
    },
}

Почему схемы важны: Поле description — это то, как LLM решает, когда использовать ваш инструмент. Будьте конкретны в том, что он делает и когда его использовать. Параметры parameters определяют, какие аргументы будет передавать LLM.

Шаг 4: Напишите обработчики инструментов

Создайте tools.py — это код, который фактически выполняется, когда LLM вызывает ваши инструменты:

"""Обработчики инструментов — код, выполняемый при вызове каждого инструмента LLM."""

import json
import math

# Безопасные глобальные переменные для вычисления выражений — без доступа к файлам/сети
_SAFE_MATH = {
    "abs": abs, "round": round, "min": min, "max": max,
    "pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos,
    "tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10,
    "floor": math.floor, "ceil": math.ceil,
    "pi": math.pi, "e": math.e,
    "factorial": math.factorial,
}


def calculate(args: dict, **kwargs) -> str:
    """Безопасно вычисляет математическое выражение.

    Правила для обработчиков:
    1. Получают args (dict) — параметры, переданные LLM
    2. Выполняют работу
    3. Возвращают строку JSON — ВСЕГДА, даже при ошибке
    4. Принимают **kwargs для обратной совместимости
    """
    expression = args.get("expression", "").strip()
    if not expression:
        return json.dumps({"error": "Выражение не предоставлено"})

    try:
        result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
        return json.dumps({"expression": expression, "result": result})
    except ZeroDivisionError:
        return json.dumps({"expression": expression, "error": "Деление на ноль"})
    except Exception as e:
        return json.dumps({"expression": expression, "error": f"Некорректно: {e}"})


# Таблицы конвертации — значения в базовых единицах
_LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01}
_WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495}
_DATA = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
_TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400}


def _convert_temp(value, from_u, to_u):
    # Нормализация к Цельсию
    c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value)
    # Конвертация в целевую
    return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c)


def unit_convert(args: dict, **kwargs) -> str:
    """Конвертирует между единицами измерения."""
    value = args.get("value")
    from_unit = args.get("from_unit", "").strip()
    to_unit = args.get("to_unit", "").strip()

    if value is None or not from_unit or not to_unit:
        return json.dumps({"error": "Необходимы value, from_unit и to_unit"})

    try:
        # Температура
        if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}:
            result = _convert_temp(float(value), from_unit.upper(), to_unit.upper())
            return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4),
                             "output": f"{round(result, 4)} {to_unit}"})

        # Конвертации на основе соотношений
        for table in (_LENGTH, _WEIGHT, _DATA, _TIME):
            lc = {k.lower(): v for k, v in table.items()}
            if from_unit.lower() in lc and to_unit.lower() in lc:
                result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()]
                return json.dumps({"input": f"{value} {from_unit}",
                                 "result": round(result, 6),
                                 "output": f"{round(result, 6)} {to_unit}"})

        return json.dumps({"error": f"Невозможно конвертировать {from_unit} → {to_unit}"})
    except Exception as e:
        return json.dumps({"error": f"Конвертация не удалась: {e}"})

Ключевые правила для обработчиков:

Сигнатура: def my_handler(args: dict, **kwargs) -> str
Возврат: Всегда строка JSON. Как для успеха, так и для ошибок.
Никогда не вызывайте исключения: Ловите все исключения, возвращайте JSON с ошибкой.
Принимайте **kwargs: VibeOS может передавать дополнительный контекст в будущем.

Шаг 5: Напишите регистрацию

Создайте __init__.py — это связывает схемы с обработчиками:

"""Плагин калькулятора — регистрация."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

# Отслеживание использования инструментов через хуки
_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    """Хук: выполняется после каждого вызова инструмента (не только нашего)."""
    _call_log.append({"tool": tool_name, "session": task_id})
    if len(_call_log) > 100:
        _call_log.pop(0)
    logger.debug("Инструмент вызван: %s (сессия %s)", tool_name, task_id)


def register(ctx):
    """Связывает схемы с обработчиками и регистрирует хуки."""
    ctx.register_tool(name="calculate",    toolset="calculator",
                      schema=schemas.CALCULATE,    handler=tools.calculate)
    ctx.register_tool(name="unit_convert", toolset="calculator",
                      schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)

    # Этот хук срабатывает для ВСЕХ вызовов инструментов, не только наших
    ctx.register_hook("post_tool_call", _on_post_tool_call)

Что делает register():

Вызывается ровно один раз при запуске
ctx.register_tool() помещает ваш инструмент в реестр — модель видит его немедленно
ctx.register_hook() подписывается на события жизненного цикла
ctx.register_cli_command() регистрирует подкоманду CLI (например, vibeos my-plugin <subcommand>)
ctx.register_command() регистрирует слеш-команду внутри сессии (например, /myplugin <args> в CLI / чате шлюза) — см. Регистрация слеш-команд ниже
ctx.dispatch_tool(name, arguments) — вызывает любой другой инструмент (встроенный или из другого плагина) с автоматически подключённым контекстом родительского агента (одобрения, учётные данные, task_id). Полезно из обработчиков слеш-команд, которым нужно вызвать terminal, read_file или любой другой инструмент так, как если бы его вызвала модель напрямую.
Если эта функция аварийно завершается, плагин отключается, но VibeOS продолжает работу

Пример dispatch_tool — слеш-команда, запускающая инструмент:

def handle_scan(ctx, raw_args: str):
    """Реализует /scan, вызывая инструмент terminal через реестр."""
    result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{raw_args}'"})
    return result  # возвращается в UI чата вызывающего

def register(ctx):
    # Обработчики получают одну строку raw_args; замыкаем ctx через lambda.
    ctx.register_command(
        "scan",
        lambda raw: handle_scan(ctx, raw),
        description="Найти файлы, соответствующие glob-шаблону",
    )

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

Шаг 6: Протестируйте

Запустите VibeOS:

vibeos

Вы должны увидеть calculator: calculate, unit_convert в списке инструментов баннера.

Попробуйте эти запросы:

Сколько будет 2 в 16-й степени?
Конвертируй 100 фаренгейтов в цельсии
Чему равен квадратный корень из 2, умноженный на пи?
Сколько гигабайт в 1.5 терабайтах?

Проверьте статус плагина:

/plugins

Вывод:

Plugins (1):
  ✓ calculator v1.0.0 (2 tools, 1 hooks)

Отладка обнаружения плагина

Если ваш плагин не отображается — или отображается, но не загружается — установите VIBEOS_PLUGINS_DEBUG=1, чтобы получить подробные логи обнаружения в stderr:

VIBEOS_PLUGINS_DEBUG=1 vibeos plugins list

Вы увидите для каждого источника плагинов (встроенные, пользовательские, проектные, точки входа):

какие каталоги были просканированы и сколько манифестов каждый из них дал
для каждого манифеста: разрешённый ключ, имя, вид, источник, путь на диске
причины пропуска: disabled via config, not enabled in config, exclusive plugin, no plugin.yaml, depth cap reached
при загрузке: импортируемый плагин, плюс однострочное резюме того, что зарегистрировал register(ctx) (инструменты, хуки, слеш-команды, CLI-команды)
при ошибке парсинга: полный traceback для исключения (ошибки сканера YAML и т.д.)
при ошибке register(): полный traceback, указывающий на строку в вашем __init__.py, которая вызвала ошибку

Те же логи всегда записываются в ~/.vibeos/logs/agent.log на уровне WARNING (только ошибки) и DEBUG (всё), когда установлена переменная окружения. Поэтому, если вы не можете запустить с переменной окружения (например, изнутри шлюза), вместо этого просматривайте файл лога:

vibeos logs --level WARNING | grep -i plugin

Распространённые причины, по которым плагин не появляется:

Не включён в конфиге — плагины подключаются по желанию. Выполните vibeos plugins enable <name> (имя берётся из вывода plugins list, который может быть <category>/<plugin> для вложенных структур).
Неправильная структура каталогов — должно быть ~/.vibeos/plugins/<plugin-name>/plugin.yaml (плоская) или ~/.vibeos/plugins/<category>/<plugin-name>/plugin.yaml (один уровень вложенности категории, максимум). Всё, что глубже, игнорируется.
Отсутствует __init__.py — каталогу плагина нужны как plugin.yaml, так и __init__.py с функцией register(ctx).
Неправильный kind — адаптерам шлюза нужен kind: platform в манифесте. Провайдеры памяти автоматически определяются как kind: exclusive и маршрутизируются через конфиг memory.provider вместо plugins.enabled.

Финальная структура вашего плагина

~/.vibeos/plugins/calculator/
├── plugin.yaml      # «Я calculator, я предоставляю инструменты и хуки»
├── __init__.py      # Связка: схемы → обработчики, регистрация хуков
├── schemas.py       # Что читает LLM (описания + спецификации параметров)
└── tools.py         # Что выполняется (функции calculate, unit_convert)

Четыре файла, чёткое разделение:

Манифест объявляет, что такое плагин
Схемы описывают инструменты для LLM
Обработчики реализуют фактическую логику
Регистрация связывает всё вместе

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

Поставлять файлы данных

Поместите любые файлы в каталог вашего плагина и читайте их во время импорта:

# В tools.py или __init__.py
from pathlib import Path

_PLUGIN_DIR = Path(__file__).parent
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"

with open(_DATA_FILE) as f:
    _DATA = yaml.safe_load(f)

Встраивать навыки

Плагины могут поставлять файлы навыков, которые агент загружает через skill_view("plugin:skill"). Зарегистрируйте их в вашем __init__.py:

~/.vibeos/plugins/my-plugin/
├── __init__.py
├── plugin.yaml
└── skills/
    ├── my-workflow/
    │   └── SKILL.md
    └── my-checklist/
        └── SKILL.md

from pathlib import Path

def register(ctx):
    skills_dir = Path(__file__).parent / "skills"
    for child in sorted(skills_dir.iterdir()):
        skill_md = child / "SKILL.md"
        if child.is_dir() and skill_md.exists():
            ctx.register_skill(child.name, skill_md)

Теперь агент может загружать ваши навыки по их именам с пространством имён:

skill_view("my-plugin:my-workflow")   # → версия плагина
skill_view("my-workflow")              # → встроенная версия (без изменений)

Ключевые свойства:

Навыки плагина только для чтения — они не попадают в ~/.vibeos/skills/ и не могут быть отредактированы через skill_manage.
Навыки плагина не перечисляются в индексе <available_skills> системного промпта — они загружаются явно по желанию.
Простые имена навыков не затрагиваются — пространство имён предотвращает коллизии со встроенными навыками.
Когда агент загружает навык плагина, перед ним добавляется баннер контекста пакета, перечисляющий родственные навыки из того же плагина.

Устаревший паттерн

Старый паттерн shutil.copy2 (копирование навыка в ~/.vibeos/skills/) всё ещё работает, но создаёт риск коллизии имён со встроенными навыками. Для новых плагинов предпочитайте ctx.register_skill().

Блокировка по переменным окружения

Если вашему плагину нужен API-ключ:

# plugin.yaml — простой формат (обратно совместимый)
requires_env:
  - WEATHER_API_KEY

Если WEATHER_API_KEY не установлен, плагин отключается с понятным сообщением. Никакого сбоя, никакой ошибки в агенте — просто «Plugin weather disabled (missing: WEATHER_API_KEY)».

Когда пользователи запускают vibeos plugins install, их интерактивно запрашивают для любых отсутствующих переменных requires_env. Значения автоматически сохраняются в .env.

Для лучшего опыта установки используйте расширенный формат с описаниями и URL для регистрации:

# plugin.yaml — расширенный формат
requires_env:
  - name: WEATHER_API_KEY
    description: "API-ключ для OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

Поле	Обязательное	Описание
`name`	Да	Имя переменной окружения
`description`	Нет	Показывается пользователю во время запроса установки
`url`	Нет	Где получить учётные данные
`secret`	Нет	Если `true`, ввод скрывается (как поле пароля)

Оба формата можно смешивать в одном списке. Уже установленные переменные молча пропускаются.

Ленивая установка опциональных Python-зависимостей

Если ваш плагин оборачивает SDK, который может быть не установлен у каждого пользователя (вендорский SDK, тяжёлая ML-библиотека, платформозависимый пакет), не импортируйте его в начале модуля. Используйте хелпер tools.lazy_deps.ensure(...) внутри обработчика инструмента — VibeOS установит пакет при первом использовании, с учётом настройки пользователя security.allow_lazy_installs.

# tools.py
from tools.lazy_deps import ensure, FeatureUnavailable

def my_tool_handler(args, **kwargs):
    try:
        ensure("my-plugin.my-backend")   # ключ должен быть в LAZY_DEPS
    except FeatureUnavailable as exc:
        return {"error": str(exc)}

    import my_backend_sdk   # теперь безопасно
    ...

Два правила из модели безопасности в tools/lazy_deps.py:

Правило	Почему
Ключ вашей функции должен присутствовать в белом списке `LAZY_DEPS` в дереве исходников	Предотвращает установку произвольных пакетов по злонамеренной конфигурации — только спецификации, которые поставляет сам VibeOS, имеют право на установку
Спецификации — только по имени из PyPI	Без `--index-url`, `git+https://` или путей `file:`. Фиксируйте версии с помощью PEP 440 (`"my-sdk>=1.2,<2"`) внутри записи белого списка

Для сторонних плагинов, распространяемых через pip, объявите опциональные зависимости как [project.optional-dependencies] extras в вашем собственном pyproject.toml и скажите пользователям pip install your-plugin[backend] — этот путь не проходит через lazy_deps. Танец ленивой установки наиболее полезен для встроенных плагинов, где включение жёсткой зависимости в каждую установку раздуло бы базовый размер VibeOS.

Когда глобально установлено security.allow_lazy_installs: false, ensure() немедленно вызывает FeatureUnavailable с подсказкой по исправлению — ваш плагин должен перехватить это и корректно деградировать (вернуть результат с ошибкой, не ломая цикл инструментов).

Потокобезопасные ленивые синглтоны

Плагины часто кешируют дорогой объект — SDK-клиент, HTTP-сессию, пул соединений — в переменной уровня модуля, создаваемой при первом использовании:

_client = None

def get_client():
    global _client
    if _client is not None:
        return _client
    _client = ExpensiveClient(...)   # ← TOCTOU race condition
    return _client

Это минное поле. VibeOS запускает несколько потоков в одном процессе (делегированные вызовы инструментов, фоновые рабочие процессы, форк самоулучшения), поэтому два потока могут вызвать get_client() до того, как _client будет установлен, оба пройдут проверку is not None, оба выполнят дорогостоящее создание, и вторая запись перезатрёт первую — утечка ресурса, который открыл проигравший (соединение, файловый дескриптор, фоновый поток).

Не изобретайте блокировку вручную. Используйте хелперы из plugins/plugin_utils.py:

from plugins.plugin_utils import lazy_singleton, SingletonSlot

# Аксессор без аргументов → декорируйте его:
@lazy_singleton
def get_client():
    return ExpensiveClient(load_config())   # выполняется ровно один раз

client = get_client()    # безопасно для потоков
get_client.reset()       # удалить экземпляр (тесты / завершение)


# Аксессор, принимающий аргумент для создания → используйте слот:
_slot: SingletonSlot = SingletonSlot()

def get_client(config=None):
    return _slot.get(lambda: ExpensiveClient(resolve(config)))

def reset_client():
    _slot.reset()

Оба сериализуют конкурентные первые вызовы с double-checked locking и выполняют фабрику не более одного раза. Если фабрика вызывает исключение, ничего не кешируется, и следующий вызов повторяет попытку. Плагин памяти honcho (plugins/memory/honcho/client.py) является эталонным потребителем.

Эмпирическое правило: каждый раз, когда вы пишете global _something с последующей проверкой is None и созданием, используйте один из этих хелперов.

Условная доступность инструментов

Для инструментов, зависящих от опциональных библиотек:

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = инструмент скрыт от модели
)

Переопределение встроенного инструмента

Чтобы заменить встроенный инструмент своей реализацией (например, заменить инструмент браузера по умолчанию на headed-Chrome CDP бэкенд или заменить web_search на пользовательский корпоративный индекс), передайте override=True:

def register(ctx):
    ctx.register_tool(
        name="browser_navigate",             # то же имя, что и у встроенного
        toolset="plugin_my_browser",         # ваше собственное пространство имён toolset
        schema={...},
        handler=my_custom_navigate,
        override=True,                       # явное согласие
    )

Без override=True реестр отклоняет любую регистрацию, которая затенила бы существующий инструмент из другого набора инструментов — это предотвращает случайные перезаписи. Переопределение логируется на уровне INFO, чтобы его можно было проверить в ~/.vibeos/logs/agent.log. Плагины загружаются после встроенных инструментов, поэтому порядок регистрации корректен: ваш обработчик заменяет встроенный.

Регистрация нескольких хуков

def register(ctx):
    ctx.register_hook("pre_tool_call", before_any_tool)
    ctx.register_hook("post_tool_call", after_any_tool)
    ctx.register_hook("pre_llm_call", inject_memory)
    ctx.register_hook("on_session_start", on_new_session)
    ctx.register_hook("on_session_end", on_session_end)

Справочник хуков

Каждый хук полностью документирован в Справочнике хуков событий — сигнатуры колбэков, таблицы параметров, когда именно срабатывает, и примеры. Вот сводка:

Хук	Срабатывает когда	Сигнатура колбэка	Возвращает
`pre_tool_call`	Перед выполнением любого инструмента	`tool_name: str, args: dict, task_id: str`	игнорируется
`post_tool_call`	После возврата любого инструмента	`tool_name: str, args: dict, result: str, task_id: str, duration_ms: int`	игнорируется
`pre_llm_call`	Один раз за ход, перед циклом вызова инструментов	`session_id: str, user

Что вы создаёте​

Шаг 1: Создайте каталог плагина​

Шаг 2: Напишите манифест​

Шаг 3: Напишите схемы инструментов​

Шаг 4: Напишите обработчики инструментов​

Шаг 5: Напишите регистрацию​

Шаг 6: Протестируйте​

Отладка обнаружения плагина​

Финальная структура вашего плагина​

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

Поставлять файлы данных​

Встраивать навыки​

Блокировка по переменным окружения​

Ленивая установка опциональных Python-зависимостей​

Потокобезопасные ленивые синглтоны​

Условная доступность инструментов​

Переопределение встроенного инструмента​

Регистрация нескольких хуков​

Справочник хуков​