# ИИ-помощник Amvera

**ИИ-помощник Amvera** — это встроенный агент для работы с проектами на платформе. Он помогает разбираться в коде и документации, вносить изменения, проверять результат в изолированной среде и подготавливать проект к публикации.

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

```{admonition} Коротко
AI Agent помогает быстрее переходить от идеи к проверенному результату: изучает проект, предлагает правки, меняет файлы и показывает результат в Sandbox до публикации.
```

---

## Что умеет ИИ-помощник

ИИ-помощник может:

- просматривать структуру проекта и читать файлы;
- искать нужные фрагменты в коде и документации;
- создавать и редактировать файлы;
- проверять сборку, тесты и работу приложения;
- запускать предпросмотр приложения;
- помогать с конфигурацией `amvera.yaml`;
- готовить изменения к публикации на платформе;
- анализировать логи сборки и запуска после деплоя.

Если задача связана с созданием нового проекта с нуля, на текущем этапе помощник лучше всего подходит для лендингов и Telegram-ботов. Для других типов приложений качество результата может зависеть от сложности требований и структуры проекта.

---

## Как работает процесс изменений

Обычно работа с помощником проходит так:

1. Вы описываете задачу обычным языком.
2. Помощник изучает проект и уточняет детали, если их не хватает.
3. Вносит изменения в sandbox-среде.
4. Запускает проверки или предпросмотр, если это применимо.
5. Сообщает, что изменено и как посмотреть результат.
6. После вашего подтверждения может подготовить публикацию изменений.

```{admonition} Важно
Sandbox-среда отделена от основной платформы. Это позволяет проверить правки до публикации и снизить риск сломать рабочее приложение.
```

---

## Предпросмотр результата

Если задача затрагивает приложение или страницу, помощник запускает проект в sandbox-среде и проверяет, что он отвечает на запросы.

Для предпросмотра приложение слушает порт `3000` в среде **Sandbox**.

После успешного запуска помощник сообщает ссылку на preview. По этой ссылке можно проверить результат до публикации.

---

## Публикация изменений

**Публикация выполняется только после подтверждения пользователя.**

Перед выкладкой помощник:

- проверяет актуальность конфигурации `amvera.yaml`;
- валидирует конфигурацию на стороне платформы;
- переносит изменения в основную ветку репозитория;
- смотрит логи сборки, запуска и событий платформы.

Пуш в основную ветку запускает сборку и деплой приложения на Amvera Cloud в соответствии с `amvera.yaml`.

---

## Что можно поручить помощнику

Примеры задач:

```text
Найди в документации все упоминания старого домена.
```

```text
Добавь новую страницу в документацию и включи её в меню.
```

```text
Проверь, почему приложение не запускается.
```

```text
Сделай лендинг для нового сервиса и запусти предпросмотр.
```

```text
Создай Telegram-бота и подготовь переменные окружения.
```

```text
Проверь amvera.yaml и исправь конфигурацию запуска.
```

---

## Рекомендации по постановке задач

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

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

Хороший пример запроса:

```text
Добавь в документацию страницу про ИИ-помощника Amvera, включи её в раздел AI-IDE и проверь сборку документации.
```

---

## Ограничения

ИИ-помощник работает как разработчик в sandbox-среде и не публикует изменения без разрешения. Он не должен использовать секреты, которые вы не передали явно, и не имеет доступа к закрытым внешним системам, если они не подключены к проекту.

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