#Разработка плагинов для ИИ-сотрудников

В NocoBase плагины могут предоставлять свои бизнес-возможности ИИ-сотрудникам. За разные уровни отвечают три точки расширения:

• Tool (инструмент) — выполняет конкретные операции: запрашивает данные, вызывает API, изменяет записи и т. д.
• Skill (навык) — объясняет модели, когда использовать инструменты и в каком порядке выполнять задачу
• Встроенный ИИ-сотрудник (Built-in AI Employee) — объединяет профиль роли, системный промпт, навыки и инструменты в готового к работе сотрудника

Как правило, вызывать API регистрации вручную не нужно. Поместите файлы в предусмотренные каталоги src/ai плагина — NocoBase автоматически просканирует и зарегистрирует их при загрузке плагина. Регистрация во фронтенде в src/client-v2/plugin.tsx нужна, только если Tool требует пользовательской карточки, модального окна или логики, выполняемой в браузере.

Перед началом убедитесь, что в приложении установлен и включён @nocobase/plugin-ai. В коде плагина можно использовать типы и функции определения из @nocobase/ai и @nocobase/actions.

#Быстрый индекс

#Сначала выберите уровень расширения

Tool, Skill и встроенный ИИ-сотрудник — не три независимые функции, а последовательно объединяемые уровни возможностей. Не каждому плагину нужны все три уровня.

Tool：让 AI 能执行一个具体动作
  ↓
Skill：让 AI 按固定方法完成一类任务
  ↓
内置 AI 员工：把这些能力装配成一个固定角色和使用入口

Выбирайте начальный уровень в зависимости от задачи:

• Если ИИ должен только запрашивать данные, вызывать API или изменять записи, достаточно определить Tool
• Если требуется задать порядок вызова инструментов, этапы подтверждения и формат результата, добавьте для этих Tool соответствующий Skill
• Если после включения плагина должна сразу появиться фиксированная роль, создайте встроенного ИИ-сотрудника и привяжите к нему нужные Skill и Tool

Если используются все три уровня, задача выполняется в следующем порядке:

1. Пользователь ставит задачу ИИ-сотруднику
2. ИИ-сотрудник определяет по системному промпту, какой Skill нужен
3. Skill сообщает модели, какие Tool и в каком порядке вызывать
4. Tool выполняет запрос, запись или внешний вызов и возвращает результат
5. ИИ-сотрудник формирует итоговый ответ на основе результата Tool

Фронтенд-карточка Tool не является четвёртым уровнем. Она лишь дополняет ToolCall интерактивным интерфейсом, когда нужно подтверждение пользователя, выбор варианта или редактирование параметров.

#Размещение ИИ-ресурсов в src/ai

NocoBase обнаруживает ИИ-ресурсы плагина по соглашениям о каталогах. При стандартной структуре плагина достаточно поместить Tool, Skill и встроенных ИИ-сотрудников в src/ai; регистрировать каждый ресурс отдельно в load() файла src/server/plugin.ts не нужно.

Полную структуру каталогов можно организовать так:

src/ai/
├── tools/
│   └── searchDocs.ts
├── skills/
│   └── document-search/
│       ├── SKILLS.md
│       └── tools/
│           └── readDocument.ts
└── ai-employees/
    ├── translator.ts
    └── developer/
        ├── index.ts
        ├── prompt.md
        ├── skills/
        └── tools/

Для разных расположений действуют разные правила регистрации:

При загрузке плагина NocoBase выполняет следующие действия до вызова собственного load() плагина:

1. Сканирует и регистрирует Tool
2. Разбирает SKILLS.md и привязывает Tool из каталога Skill к соответствующему Skill
3. Загружает встроенных ИИ-сотрудников и объединяет их с файлами prompt.md, Skill и Tool из каталогов сотрудников

src/client-v2 не входит в набор автоматически сканируемых каталогов. Дополнительная регистрация в src/client-v2/plugin.tsx требуется только для Tool с фронтенд-карточкой, модальным окном или логикой, выполняемой в браузере.

#Краткий справочник по точкам расширения и каталогам

По умолчанию начните с Tool. Если нужен фиксированный рабочий процесс, добавьте Skill; если нужен отдельный вход для фиксированной роли, создайте встроенного ИИ-сотрудника. Фронтенд-карточку добавляйте только тогда, когда Tool требует взаимодействия в браузере.

#Связанные ссылки

• Создание первого плагина — создание и запуск плагина NocoBase с нуля
• Обзор ИИ-сотрудников — основные способы работы с ИИ-сотрудниками
• Руководство по проектированию промптов — создание системных промптов и ограничений задач