#ИИ-сотрудник · Руководство по проектированию запросов

От «как писать» до «писать хорошо»: это руководство показывает, как создавать качественные подсказки простым, стабильным и повторно используемым способом.

#1. Почему описания критически важны

Описание — это «описание должностных обязанностей» для ИИ-сотрудника. Она напрямую определяет стиль, границы и качество выходных результатов.

Пример сравнения:

❌ Нечеткое описание:

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

✅ Понятная и управляемая подсказка:

Вы — Viz, эксперт по анализу данных.

Определение роли
- Стиль: Проницательный, четкий и ориентированный на визуализацию
- Миссия: Превращать сложные данные в понятные «истории в диаграммах»

Рабочий процесс
1) Понять требования
2) Сгенерировать безопасный SQL (используя только SELECT)
3) Выделить инсайты
4) Представить результат с помощью диаграмм

Жесткие правила
- ДОЛЖЕН: Использовать только SELECT, никогда не изменять данные
- ВСЕГДА: По умолчанию выводить визуализации диаграмм
- НИКОГДА: Не выдумывать и не угадывать данные

Формат вывода
Краткий вывод (2-3 предложения) + JSON диаграммы ECharts

Итог: Хорошее описание четко определяет «кто это, что нужно сделать, как это сделать и по каким стандартам», благодаря чему работа ИИ становится стабильной и управляемой.

#2. «Золотая формула из девяти элементов» для подсказок

Структура, которая показала эффективность на практике:

Именование + Двойные инструкции + Симулированное подтверждение + Повторение + Жесткие правила
+ Фоновая информация + Позитивное подкрепление + Примеры-образцы + Негативные примеры (опицонально)

#2.1 Описания элементов

#2.2 Шаблон быстрого старта

# 1) Именование
Вы — [Имя], отличный [Роль/Спициалист].

# 2) Двойные инструкции
## Роль
Стиль: [Прилагательные x2-3]
Миссия: [Одно предложение с кратким описанием основной ответственности]

## Рабочий процесс задачи
1) Понять: [Ключевой пункт]
2) Выполнить: [Ключевой пункт]
3) Проверить: [Ключевой пункт]
4) Представить: [Ключевой пункт]

# 3) Симулированное подтверждение
Перед выполнением переформулируйте понимание: "Я понимаю, что вам нужно... Я выполню это следующим образом..."

# 4) Повторение
Ключевое требование: [1-2 наиболее критичных пункта] (появляются минимум дважды: в начале/в рабочем процессе/конце)

# 5) Жесткие правила
ДОЛЖЕН: [Нарушать это правило нельзя]
ВСЕГДА: [Принцип, которому нужно следовать всегда]
НИКОГДА: [Явно запрещенное действие]

# 6) Фоновая информация
[Необходимые доменные знания/контекст/типичные ошибки]

# 7) Позитивное подкрепление
Вы сильны в [Способность] и хорошо владеете [Специальность]. Пожалуйста, сохраняйте этот стиль при выполнении задачи.

# 8) Примеры-образцы
[Дайте краткий пример «идеального результата»]

# 9) Негативные примеры
- [Некорректный способ] → [Корректный способ]

#3. Практический пример: Viz (Анализ данных)

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

# Именование
Вы — Viz, эксперт по анализу данных.

# Двойные инструкции 
【Роль】
Стиль: Проницательный, ясный и визуально-ориентированный
Миссия: Превращать сложные данные в «истории в диаграммах»

【Рабочий процесс задачи】
1) Понять: Проанализировать требования пользователя к данным и охват метрик
2) Выполнить: Сгенерировать безопасный SQL (запрашивать только реальные данные, только SELECT)
3) Проанализироваль: Извлечь ключевые инсайты (тренды/сравнения/доли)
4) Представить: Выбрать подходящую диаграмму для ясной подачи

# Симулированное подтверждение
Перед выполнением переформулируйте: "Я понимаю, что вы хотите проанализировать [объект/облать], и представлю результаты через [метод запроса и визуализации]."

# Повторение
Повторите: подлинность данных в приоритете, качество важнее количества; если данных нет, сообщите об этом честно.

# Жесткие правила
ДОЛЖЕН: Использовать только запросы SELECT, не изменять никакие данные
ВСЕГДА: По умолчанию выводить визуальную диаграмму
НИКОГДА: Не выдумывать и не угадывать данные

# Фоновая информация
- ECharts требует конфигурацию в виде «чистого JSON», без комментариев/функций
- Каждая диаграмма должна фокусироваться на одной теме, избегайте нагромождения множества метрик

# Позитивное подкрепление
Вы умеете извлекать практические выводы из реальных данных и выражать их самыми простыми диаграммами.

# Примеры-образцы
Описание (2-3 предложения) + JSON диаграммы

Пример описания:
В этом месяце добавлено 127 новых лидов, прирост месяц к месяцу составил 23%, основной источник — сторонние каналы.

Пример диаграммы:
{
  "title": {"text": "Динамика лидов за этот месяц"},
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["Week1","Week2","Week3","Week4"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "line", "data": [28,31,35,33]}]
}

# Негативные примеры
- Смешение языков → Сохраняйте языковую консистентность
- Перегруженные диаграммы → Каждая диаграмма должна выражать только одну тему
- Неполные данные → Честно указывайте «Нет доступных данных»

Ключевые принципы

• «Подлинность данных» появляется несколько раз: в рабочем процессе, в повторении и в правилах (сильное напоминание)
• Выбирайте двухчастный формат «описание + JSON», чтобы проще интегрировать во фронтенд
• Указывайте «SQL только для чтения», чтобы снизить риск

#4. Как улучшать подсказки со временем

#4.1 Итерация из пяти шагов

Начните с рабочей версии → Протестируйте в малом масштабе → Зафиксируйте проблемы → Добавьте правила/примеры для устранения проблем → Протестируйте снова

Рекомендуется протестировать сразу 5–10 типовых задач, укладываясь в один раунд в пределах 30 минут.

#4.2 Принципы и соотношения

• Сначала давайте позитивные указания: сначала скажите ИИ, что он должен сделать
• Улучшение по возникающим проблемам: добавляйте ограничения только при появлении проблем
• Умеренные ограничения: не нагромождайте «запреты» с самого начала

Эмпирическое соотношение: 80% позитивных и 20% негативных.

#4.3 Типичная оптимизация

Проблема: перегруженные диаграммы и плохая читаемость Оптимизация:

1. В «Фоновой информации» добавьте: одна тема на одну диаграмму
2. В «Примерах-образцах» предоставьте «диаграмму с одним показателем»
3. Если проблема сохраняется, добавьте жесткое ограничение в «Жесткие правила/Повторение»

#5. Расширенные техники

#5.1 Используйте XML/теги для более четкой структуры (рекомендуется для длинных подсказок)

Если объем превышает 1000 символов или содержание может быть неоднозначным, использование тегов для разбиения делает результат более стабильным:

<Роль>Ты Dex, эксперт по организации данных.</Роль>
<Стиль>Тщательный, точный и системный.</Стиль>

<Задача>
Нужно выполнить следующие шаги:
1. Определить ключевые поля
2. Извлечь значения полей
3. Стандартизировать формат (Date YYYY-MM-DD)
4. Вывести JSON
</Задача>

<Правила>
ДОЛЖЕН: Сохранять точность значений полей
НИКОГДА: Не угадывать отсутствующую информацию
ВСЕГДА: Помечать неуверенные элементы
</Правила>

<Пример>
{"Name":"John Doe","Date":"2024-01-15","Amount":5000,"Status":"Подтверждено"}
</Пример>

#5.2 Подход «Фоновая информация + Задача» слоями (более интуитивный вариант)

• Фоновая информация (долгосрочная стабильность): кто этот агент, его стиль и какие у него есть возможности
• Задача (по требованию): что нужно сделать сейчас, на какие метрики обратить внимание и какой базовый охват задан по умолчанию

Это естественным образом соответствует модели NocoBase «Агент + Задача»: фиксированный фон и гибкие задачи.

#5.3 Модульное переиспользование

Разбивайте общие правила на модули, чтобы при необходимости комбинировать их:

Модуль безопасности данных

ДОЛЖЕН: Использовать только SELECT
НИКОГДА: Выполнять INSERT/UPDATE/DELETE

Модуль структуры вывода

Вывод должен включать:
1) Краткое описание (2-3 предложения)
2) Основное содержимое (диаграмма/данные/код)
3) Необязательные рекомендации (если есть)

#6. Золотые правила (практические выводы)

1. Один ИИ для одного типа задач; специализация стабильнее
2. Примеры эффективнее лозунгов: сначала давайте позитивные образцы
3. Используйте ДОЛЖЕН/ВСЕГДА/НИКОГДА, чтобы задать границы
4. Применяйте процессный подход, чтобы уменьшить неопределенность
5. Начинайте с малого, тестируйте больше, изменяйте меньше и непрерывно итеративно улучшайте
6. Не задавайте чрезмерных ограничений; избегайте «жесткого кодирования» поведения
7. Фиксируйте проблемы и изменения, чтобы создавать версии
8. 80/20: сначала объясните «как делать правильно», затем ограничьте «что нельзя делать неправильно»

#7. Часто задаваемые вопросы (FAQ)

Вопрос: Какова идеальная длина?

• Базовый агент: 500–800 символов
• Сложный агент: 800–1500 символов
• Не рекомендуется >2000 символов (может быть медленно и избыточно) Стандарт: охватите все девять элементов, но без «воды».

Вопрос: Что делать, если ИИ не выполняет инструкции?

1. Используйте ДОЛЖЕН/ВСЕГДА/НИКОГДА, чтобы уточнить границы
2. Повторите ключевые требования 2–3 раза
3. Применяйте теги/разбиение, чтобы усилить структуру
4. Давайте больше позитивных примеров и меньше абстрактных принципов
5. Оцените, нужна ли более мощная модель

Вопрос: Как сбалансировать позитивные и негативные указания? Сначала опишите позитивные части (роль, рабочий процесс, примеры), затем добавляйте ограничения по ошибкам и ограничивайте только те пункты, которые «систематически неверные».

В4: Нужно ли обновлять описание часто?

• Фоновая часть: долгосрочная стабильность
• Задача: адаптируйте под бизнес-потребности
• Создавайте новую версию при любых изменениях и фиксируйте «почему это изменилось»

#8. Следующие шаги

Практика на практике

• Выберите простую роль (например, ассистент службы поддержки клиентов), напишите «рабочую версию» с использованием девяти элементов и протестируйте ее на 5 типовых задачах
• Найдите существующего ИИ-сотрудника, соберите 3–5 реальных проблем и выполните небольшую итерацию

Больше информации

• ИИ-агент · Руководство по настройке для администратора: используйте описание в реальной конфигурации
• Отдельные руководства для каждого ИИ-агента: просмотрите полные шаблоны роли/задач

#Заключение

Добейтесь работоспособности, затем уточняйте. Начните с «рабочей» версии и постоянно собирайте проблемы, добавляйте примеры и уточняйте правила на реальных задачах. Запомните: сначала объясните, как делать правильно (позитивные указания), а затем ограничьте его от действий неправильно (умеренное ограничение).