Работа с ИИ-агентами

FlutterFlow CLI позволяет создавать и править приложения из терминала любым ИИ-агентом — Claude Code, Gemini CLI, Codex или другим MCP-совместимым клиентом. Вы описываете задачу словами, агент планирует и вносит изменения, а результат становится обычным проектом FlutterFlow, который открывается в визуальном редакторе.

Источник истины — сам проект FlutterFlow. CLI — лишь способ править его с локальной машины.

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

Как это устроено

Команда flutterflow ai init создаёт локальное рабочее пространство — папку с готовым файлом настройки MCP, указывающим на сервер FlutterFlow. Запущенный в этой папке агент находит сервер и получает набор инструментов для работы с облаком FlutterFlow:

1. Вы формулируете задачу.
2. Агент планирует изменения и вызывает инструменты сервера MCP.
3. Сервер применяет изменения к проекту FlutterFlow.
4. Вы проверяете результат в визуальном редакторе.

Рабочее пространство — просто папка на диске; сам проект лежит на сервере FlutterFlow.

Создание рабочего пространства

Откройте терминал в папке, где должно появиться рабочее пространство, и выполните:

flutterflow ai init

По умолчанию команда работает с рабочим окружением FlutterFlow. Для другого окружения укажите его явно:

flutterflow ai init --env beta
flutterflow ai init --env enterprise-india

Запустится интерактивный мастер:

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

   Workspace name
     Directory to scaffold the FlutterFlow AI workspace in.
   > mindfly

2. Идентификатор существующего проекта. Нажмите Enter, чтобы создать новое приложение, или вставьте идентификатор, чтобы привязаться к существующему.

   Existing project ID to edit (press Enter to create a new app)
   >

3. Ключ API FlutterFlow. Вставьте его и нажмите Enter — ввод скрыт.
4. Регистрация сервера MCP. Мастер просматривает PATH и предлагает зарегистрировать сервер у каждого найденного агента — Claude Code, Gemini CLI, Codex. Отвечайте Y для тех, которыми собираетесь пользоваться.

   Register FlutterFlow AI MCP server with coding CLIs
     Detected: claude, gemini, codex
     Register with claude? [Y/n]

5. Подтверждение. Мастер покажет сводку — проверьте и нажмите Enter.

   Ready to create:
     Workspace:  mindfly
     Project ID: (none, unlinked)
     API key:    set (***abcd)
     Base URL:   https://api.flutterflow.io  (built-in for prod)
     MCP CLIs:   claude, gemini, codex
   
   Proceed? [Y/n]

В папке появятся файлы настройки — по одному на каждого зарегистрированного агента:

• .mcp.json для Claude Code;
• .gemini/settings.json для Gemini CLI;
• .codex/config.toml для Codex.

Запуск агента

Перейдите в папку рабочего пространства и запустите агента. В примере это Claude Code, но схема одинакова для всех.

Пользователям Codex с установленным плагином FlutterFlow нужно начать новую задачу Codex из этой папки — см. раздел про Codex.

cd mindfly
claude

При первом открытии папки агент обнаружит новый сервер MCP и попросит подтверждения. Формулировка зависит от агента; у Claude Code она выглядит так:

New MCP server found in .mcp.json: flutterflow_ai

MCP servers may execute code or access system resources.
All tool calls require approval.

> 1. Use this and all future MCP servers in this project
  2. Use this MCP server
  3. Continue without using this MCP server

Выберите первый вариант — тогда сервер (и те, что появятся в этой папке позже) больше не будет спрашивать разрешения.

Без подтверждённого сервера MCP агент сможет править локальные файлы, но не сможет отправить изменения в проект FlutterFlow.

Создание приложения

Опишите, что хотите получить:

> create a minimalist meditation app

Формулировка свободная: a recipe-sharing app with a social feed, a habit tracker with streaks, a tip calculator for restaurants. Агент спланирует приложение, соберёт изменения, отправит их во FlutterFlow через сервер MCP и отчитается. Откройте проект в браузере — результат будет в визуальном редакторе.

Дальше рабочее пространство привязано к созданному приложению, и следующие запросы в том же сеансе считаются правками, а не новой генерацией. Агент сообщит об этом примерно так:

The project is bound, so I'll switch to edit mode.
Let me check the workspace and read the edit template.

С этого момента действуют те же правила, что и при правке существующего проекта.

Правка существующего проекта

Всё так же, как при создании нового, с одним отличием: на вопрос об идентификаторе существующего проекта вставьте свой вместо нажатия Enter:

Existing project ID to edit (press Enter to create a new app)
> mindfly-c9lbgr

Рабочее пространство привязано к проекту. Перейдите в его папку, запустите агента и опишите задачу: «добавь экран профиля», «смени основной цвет на бирюзовый», «подключи форму входа к Firebase Auth». Агент прочитает текущее состояние проекта, спланирует изменение и отправит его через сервер MCP.

Copy AI Selector

Щёлкните по виджету в редакторе правой кнопкой и выберите Copy AI Selector — в буфер попадёт точный адрес виджета. Вставьте его в запрос, и агент будет знать, какой именно виджет смотреть или менять.

Незаменимо, когда на странице повторяющиеся виджеты, вложенные компоненты или одинаковые подписи: описать нужный словами в таком случае почти невозможно.

Одновременная работа с редактором

Править проект визуально, пока работает агент, можно, но запись идёт по схеме оптимистичной блокировки: при отправке сервер сверяет время последнего изменения проекта с тем снимком, который был у агента. Если за это время проект менял кто-то ещё — вы, коллега или другой агент, — отправка отклоняется. Агент перечитает актуальное состояние и попробует снова, при необходимости перепланировав работу.

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

Что агент может править

Может:

• страницы, компоненты, состояние приложения, тему, навигацию, блоки действий, события приложения;
• собственные функции, действия, виджеты, классы и перечисления;
• эндпоинты API, запросы, свои типы данных и перечисления;
• зависимости из pub и библиотек, токены оформления, каталог GenUI, подключение Firebase Auth.

Не может:

• всё, что вне проекта FlutterFlow: запуск приложения, публикацию, создание проектов Firebase, работу с секретами, отправку в App Store.

Обновление устаревшего контекста

Если после последнего чтения проекта вы правили его визуально, снимок у агента устарел. Два способа это исправить:

• Попросить агента. Большинство агентов сами вызывают инструмент refresh-context, когда замечают расхождение, но можно сказать прямо: «обнови контекст проекта».
• Сделать это командой. flutterflow ai context-check покажет, отстал ли локальный снимок, а flutterflow ai refresh-context <project-id> подтянет актуальное состояние.

Полный список — в разделе инструментов MCP.

Живые сессии

Live Sessions позволяют агенту менять запущенное приложение и сразу показывать результат на подключённом устройстве. Так удобно доводить экраны до ума: попросить поправить, посмотреть логи, перезапустить с горячей перезагрузкой, снять скриншот — и тут же увидеть, что получилось.

Запустите приложение из десктопного приложения FlutterFlow на устройстве или симуляторе, затем активируйте агента. Убедитесь, что сессия началась, и дальше работайте запросами.

Ветки и откат

CLI работает с любой веткой проекта. У каждой ветки свой адрес, а значит и свой идентификатор проекта: откройте нужную ветку в редакторе, скопируйте идентификатор из адреса и вставьте его в мастер flutterflow ai init.

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

Переключение между проектами

Рабочее пространство привязано к одному проекту. Для другого проекта выполните flutterflow ai init в новой папке. В непустом каталоге команда не запустится, так что переприязать существующее пространство не получится.

Инструменты MCP

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

Полный список команд и флагов — flutterflow ai --help из папки рабочего пространства. Каждый вызов через MCP подчиняется правилам подтверждения вашего агента.