Playbook MCP-агента Bot Builder

Этот документ задаёт обязательный порядок работы агента с MCP. Агент должен опираться на ответы инструментов и существующие рабочие ноды, а не угадывать формат project.json по памяти.

В профиле compact сначала найдите необходимые действия через search_actions и изучите describe_actions; имена инструментов ниже используются как action_id для call_action. Общие правила подтверждения записи и защиты черновика: сохранение и конфликты. Они доступны и через get_rule_docs (rule_name: "persistence").

1. Обязательный порядок действий

Перед созданием или изменением сценария:

1. Определи цель пользователя и перечисли входы, переменные, ветвления и результат.
2. Вызови list_node_types, чтобы убедиться, что нужный тип ноды существует.
3. Вызови get_node_schema для каждого нового типа.
4. Вызови get_node_example и скопируй его форму data.
5. Собери или измени JSON небольшими операциями.
6. Вызови validate_bot_project.
7. Проверь переходы: входящие связи, исходящие связи, кнопки и цели autoTransitionTo.
8. Вызови generate_bot_code и проверь, что генерация завершилась без ошибок.
9. Только после этого сохраняй файл или вызывай update_project_db.
10. Для live-бота отдельно проверь статус, логи запуска и тестовый сценарий.

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

2. Каноничный сценарий сбора ввода

message задаёт вопрос, а отдельная input ждёт следующий ответ и сохраняет его. Нельзя добавлять поля сбора ввода в message.

command_trigger(/start)
  -> message(«Введите первое число»)
  -> input(inputVariable: «first_number»)
  -> message(«Введите второе число»)
  -> input(inputVariable: «second_number»)
  -> keyboard(кнопки операций)
  -> input(inputVariable: «operation»)
  -> code или set_variable(результат)
  -> message(«Результат: {answer}»)

Для кнопочного ввода callback должен быть сохранён явно. Если схема input или keyboard предлагает поле для переменной, используй его; не придумывай action. Сначала вызови get_node_schema и get_node_example.

3. Переменные и состояние

• В текстах используется {name}, а не {{name}}, ${name} или name.
• В поле имени переменной указывается чистое имя: answer, без скобок.
• Пользовательские переменные доступны последующим нодам текущего диалога.
• /start должен вести на узел, который начинает новый сценарий. Если старые значения влияют на результат, добавь явное обнуление через set_variable.
• Не называй переменную last_input, num1 или num2, пока она не создана конкретной нодой или не описана схемой как системная.
• Значение callback-кнопки не равно тексту кнопки. Проверь, какая переменная сохраняется выбранной схемой (callback_data, button_text или заданное имя).

Пример корректного текста:

📊 Результат: {answer}

Пример некорректного текста:

📊 Результат: {{answer}}

4. Правила для input и валидации

До генерации проверь, что каждый input имеет сохранение ответа и следующий переход. Для чисел предусмотрите невалидный ввод, повторный запрос и деление на ноль. Если встроенная проверка не подтверждена get_node_schema, не утверждай, что она существует: используй отдельную проверку через condition или code согласно доступной схеме.

В одной пользовательской ветке нельзя ставить несколько параллельных input: FSM ожидает один следующий ответ. Нельзя помещать input внутрь ветвей condition, если это создаёт конкурирующие ожидания.

5. Переходы и кнопки

• autoTransitionTo — это переход после завершения текущей ноды; его цель должна существовать.
• goto — переход кнопки; его цель также должна существовать.
• Кнопка без проверенной цели не считается рабочей навигацией.
• Не смешивай автоматический переход и кнопку как два способа продолжить один и тот же ввод без явного понимания приоритета из схемы и примера.
• После изменения кнопок вызови db_report_button_navigation или аналогичную проверку, если работа идёт с live-БД.

6. Работа с live-БД и MCP

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

После записи:

1. перечитай проект;
2. повторно вызови валидатор;
3. вызови db_auto_layout, если добавлены узлы и расположение важно;
4. сгенерируй код;
5. запусти или перезапусти только нужный токен;
6. проверь db_bot_status и db_bot_logs.

Не сообщай «готово», если проверен только JSON, но не проверен live-бот.

7. Диагностика неработающего сценария

Агент должен воспроизвести путь пользователя по шагам и составить таблицу:

Шаг	Вход пользователя	Ожидаемая нода	Переменные	Фактический результат
1	/start	триггер	сброшены	...
2	3	первый input	first_number=3	...
3	2	второй input	second_number=2	...
4	-	keyboard/input	operation=-	...
5	—	code/set_variable	answer=1	...

Если в сообщении виден литерал {answer} или {{answer}}, сначала проверь имя переменной и синтаксис подстановки, затем узел, который должен записать значение. Если ответ повторяется, ищи дублирующие переходы и повторный вход в узел результата через db_find_inbound и отчёт навигации.

8. Безопасность и границы

• Не придумывай MCP-инструменты, поля нод или операторы.
• Не меняй чужой проект без подтверждённого project_id и доступа.
• Не публикуй токены, Bearer-ключи и секреты из ответов инструментов.
• Команды command_trigger содержат только латиницу, цифры и _.
• Для массовых, необратимых или удаляющих действий сначала запроси явное подтверждение пользователя.

Основные справочники: mcp/bot-builder, bot-json-prompt, features/NODE_TYPES и mcp/bot-logs.