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

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, OpenCode. Отвечайте 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;
• opencode.json для OpenCode.

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

Перейдите в папку рабочего пространства и запустите агента. В примере это 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;
• нативные конфигурационные файлы — AndroidManifest.xml, Info.plist, Podfile и другие. Разблокировка и обратная блокировка файла всегда требуют вашего согласия.

Не может:

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

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

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

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

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

Живые сессии

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

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

Нативные конфигурационные файлы

Агент может править те же нативные конфигурационные файлы, что и вы в разделе Custom Code редактора: AndroidManifest.xml, build.gradle, proguard-rules.pro, MainActivity.kt, Info.plist, Runner.entitlements, AppDelegate.swift и Podfile.

Каждый файл либо заблокирован, либо разблокирован:

• Locked — файл генерирует FlutterFlow. Агент добавляет фрагменты кода (snippets) в те места, которые редактор предлагает для этого файла, и заводит переменные уровня файла для плейсхолдеров {{variableName}} из фрагментов. Значение переменной — текст или одна из констант приложения. В MainActivity.kt и Podfile мест для фрагментов нет, поэтому агент может менять их только после разблокировки.
• Unlocked — файл целиком принадлежит проекту, и FlutterFlow перестаёт обновлять его при подключении новых интеграций. Агент может заменить содержимое целиком, но фрагменты к разблокированному файлу не применяются.

Если фрагмент использует плейсхолдер {{variableName}}, который агент не объявил переменной, запуск завершится ошибкой. Редактор в такой ситуации сам создаёт пустую переменную.

Согласие на разблокировку и блокировку

Редактор спрашивает подтверждение, прежде чем разблокировать или заблокировать файл. Агент подчиняется тому же правилу: run никогда не меняет состояние блокировки, и обойти ошибку разблокировкой агент не может. Если ему нужно переписать заблокированный файл целиком, он постарается обойтись фрагментом, а если не выйдет — попросит вас разблокировать файл.

Дать согласие можно двумя способами:

• Выполнить команду самому. flutterflow ai native-file unlock FILE и flutterflow ai native-file lock FILE описывают, что произойдёт, и спрашивают Continue? [y/N]. Разблокировка берёт за основу сгенерированное FlutterFlow содержимое, так что результат тот же, что при разблокировке в редакторе. Флаг --yes добавляйте, только если терминал не умеет задавать вопросы — без него команда там не запустится. Агенту передавать --yes не позволяйте.
• Одобрить вызов инструмента агентом. Инструменты native_file.unlock и native_file.lock срабатывают только после вашего одобрения в агенте. Если блокировка выбросит какое-то содержимое, агент сначала покажет его и заблокирует файл, только когда вы подтвердите и одобрите второй вызов. Если коллега успеет сохранить файл в промежутке, агент покажет новое содержимое и спросит снова.

Проверить состояние файлов можно командами только для чтения — или попросить об этом агента:

flutterflow ai native-file list
flutterflow ai native-file show Podfile

list показывает, заблокирован ли каждый файл и сколько в нём фрагментов и переменных. show перечисляет фрагменты и переменные файла и печатает содержимое так, как его показывает редактор, — с плейсхолдерами {{variableName}} на местах. Обе команды по умолчанию работают с проектом рабочего пространства; чтобы взять другой, укажите ID проекта после имени файла.

Ветки и откат

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

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

Работа с библиотеками

У рабочего пространства один основной проект (primary project), но оно может отслеживать и библиотеки, от которых этот проект зависит. Тогда агент правит и библиотеку, и использующее её приложение из одного рабочего пространства.

Если запустить flutterflow ai init с ID существующего проекта, CLI скачает все библиотеки, от которых он зависит, включая библиотеки библиотек. Каждая получит свою папку в libraries/ со своими dsl/, generated_code/ и PROJECT_CONTEXT.md. Основной проект остаётся в корне.

workspace/
├── dsl/                    (основной проект)
├── generated_code/         (основной проект)
├── PROJECT_CONTEXT.md      (основной проект)
└── libraries/
    ├── auth_kit/
    │   ├── dsl/
    │   ├── generated_code/
    │   └── PROJECT_CONTEXT.md
    └── design_system/

Какие библиотеки скачивать, задаёт флаг --with-libraries:

Какой проект меняет команда

Команды run, validate, refresh-context, codegen refresh и status принимают флаг --target:

• --target primary (по умолчанию) — основной проект;
• --target lib:NAME_OR_ID — библиотека с таким именем локальной папки или ID проекта.

Если библиотеки в рабочем пространстве нет, команда завершится ошибкой, а не переключится молча на основной проект. Флаг --all у refresh-context и codegen refresh обновляет основной проект и все библиотеки сразу.

flutterflow ai run libraries/design_system/dsl/edit.dart --target lib:design_system
flutterflow ai refresh-context --all

Инструменты run и validate, которые агент вызывает через сервер MCP, тоже принимают аргумент target.

Управление зависимостями

Эти команды меняют набор библиотек основного проекта:

Создать библиотеку из CLI — flutterflow ai create-project --name NAME --library; с --attach она сразу станет зависимостью основного проекта. Чтобы основной проект нового рабочего пространства был библиотекой, запустите flutterflow ai init --as-library.

Замороженные и живые версии

Зависимость от библиотеки закрепляется одним из двух способов, и от этого зависит, дойдут ли правки библиотеки до основного проекта:

• Frozen — номер версии, например 1.3.0. Основной проект использует этот опубликованный снимок. Чтобы получить изменения, опубликуйте новую версию и обновите закрепление.
• Live — current или latest. Основной проект берёт последнее сохранённое состояние библиотеки, и правки видны в нём сразу.

flutterflow ai status пишет (live) или (frozen) рядом с каждой библиотекой. add-library без --version закрепляет зависимость за старшей опубликованной версией — то есть замораживает её. Чтобы дорабатывать библиотеку и приложение вместе, переключите зависимость на живую версию:

flutterflow ai update-library design_system --version current

Когда библиотека готова, опубликуйте её и обновите основной проект одной командой:

flutterflow ai publish-library --version 1.3.0 --target lib:design_system --and-update-primary

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

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

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

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

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