sanspie
5eb1832907
ci-platforms / darwin amd64 smoke (push) Skipped
ci / build (amd64, linux, ubuntu-24.04) (push) Failing after 15m28s
ci / release (push) Skipped
ci-platforms / windows amd64 smoke (push) Skipped
ci-platforms / darwin arm64 smoke (push) Skipped
ci / checks (push) Successful in 7m47s
125 lines
15 KiB
Markdown
125 lines
15 KiB
Markdown
---
|
||
id: agents
|
||
title: Работа с ИИ-агентами
|
||
---
|
||
|
||
# Работа с ИИ-агентами
|
||
|
||
`aego mcp` отдаёт проект ИИ-агенту по протоколу Model Context Protocol. Агент правит сцены, префабы и ассеты данных теми же операциями, что и редактор, читает документацию и схему типов и запускает сцены без окна, чтобы проверить свою работу. Команды редактирования проекта доступны и из CLI. Операции, которым нужен открытый документ или Game View, предоставляет редактор.
|
||
|
||
## Подключение
|
||
|
||
### Внутри редактора
|
||
|
||
Откройте панель **Агент** и выберите **Claude Code** или **Codex** в строке провайдера. Выбор, путь к CLI и заданная модель сохраняются в настройках редактора для проекта. У существующих проектов по умолчанию остаётся Claude Code.
|
||
|
||
Для Codex установите официальный CLI версии 0.166.0 или новее и один раз войдите в аккаунт через терминал:
|
||
|
||
```sh
|
||
npm install -g @openai/codex
|
||
codex login
|
||
```
|
||
|
||
Редактор использует существующую авторизацию CLI. В **Настройках агента** выберите модель из списка или начните вводить название для поиска; модели Codex и поддерживаемые уровни рассуждения берутся из установленного CLI. Наличие модели в списке не гарантирует доступ к ней для вашего аккаунта. Можно ввести свой ID модели, задать свой уровень рассуждения или выбрать **По умолчанию CLI**, чтобы использовать настройки CLI. Для Claude Code доступны обычные имена моделей. Ошибка запуска или входа показывается в панели; после установки или входа нажмите **Проверить снова**, чтобы обновить список. В поле пути можно указать имя программы или полный путь; нажмите Enter, чтобы применить его.
|
||
|
||
Оба провайдера используют общие инструменты проекта, предложения изменений, вопросы и историю Undo. Правки открытых документов остаются несохранёнными до команды сохранения. **Стоп** отменяет текущий ответ и отклоняет ожидающие предложения. Переключайте провайдера и его настройки после завершения ответа: начинается новый разговор, а предыдущая переписка остаётся в истории сеансов с названием провайдера.
|
||
|
||
### Из внешнего CLI
|
||
|
||
Claude Code, из папки проекта:
|
||
|
||
claude mcp add aego -- aego mcp --project . --watch
|
||
|
||
или файл `.mcp.json` рядом с `project.aego`:
|
||
|
||
{"mcpServers": {"aego": {"command": "aego", "args": ["mcp", "--watch"]}}}
|
||
|
||
Для внешнего сеанса Codex, запущенного из папки проекта:
|
||
|
||
```sh
|
||
codex mcp add aego -- aego mcp --project . --watch
|
||
```
|
||
|
||
Другие клиенты принимают ту же команду. Сервер говорит по MCP через stdio; журнал идёт в stderr. Проект с нативным кодом обслуживает его собственный исполняемый файл, поэтому его компоненты известны.
|
||
|
||
### Проверка сцены и изображений
|
||
|
||
В Agent Settings → Diagnostics видны провайдер, проект, открытый документ и результат последнего вызова. Переподключение создаёт новую привязку диалога. «Объясни сцену» прикладывает выделение, ревизию, краткое дерево и ссылки на скрипты текущего документа. Читать несохранённую сцену можно без Auto-apply. Для Codex панель проверяет каталог и вызывает bridge из того же диалога.
|
||
|
||
`asset_view` возвращает миниатюру Assets, исходные пиксели или импортированный регион. `asset_contact_sheet` принимает папку, последовательность кадров или список ассетов. `editor_view_capture` показывает текущий Game View или Scene View. Для повторяемого сравнения укажи одну сцену, камеру, ввод, seed и кадр в двух вызовах `scene_run`, затем передай оба идентификатора в `scene_compare_frames`. PNG можно посмотреть прямо в карточке вызова.
|
||
|
||
`asset_paint` меняет исходный PNG одной обратимой операцией. Внешняя генерация доступна при подключённом адаптере; перед запросом редактор показывает референсы и общий лимит оплаты. Для проверки сохранённой игры используй `project_export_game` и `project_run_export`. Auto-apply не даёт разрешения исполнять произвольный нативный код или публиковать результат.
|
||
|
||
## Инструменты
|
||
|
||
Каждый инструмент назван по своей команде с подчёркиваниями (`scene set` — это `scene_set`) и принимает те же аргументы; `aego scene help` перечисляет их, а в справочнике CLI есть полная таблица. `docs_search` и `docs_read` читают документацию. Инструменты записи принимают `dry-run`: он сообщает об изменениях и ничего не записывает. Инструменты скриптов отвечают тем, что компилятор говорит о новом тексте, — теми же ошибками `AES`, что `aego check`. В редакторе у агента есть ещё `ask_user`: он кладёт в панель «Агент» вопрос с вариантами и ждёт ответа.
|
||
|
||
## Ресурсы
|
||
|
||
| URI | Содержимое |
|
||
|---|---|
|
||
| `aego://project/manifest` | `project.aego` |
|
||
| `aego://project/problems` | то, что сообщает `project_validate` |
|
||
| `aego://docs/index`, `aego://docs/<id>` | документация |
|
||
| `aego://schema/index`, `aego://schema/<type>` | типы и их поля |
|
||
| `aego://file/<path>` | сцена, префаб, ассет данных или таблица в виде текста |
|
||
|
||
С `--watch` сервер опрашивает проект и, когда файлы меняются, отправляет `resources/updated` для ресурсов, на которые есть подписка, в том числе при изменениях из редактора.
|
||
|
||
## Типичный сеанс
|
||
|
||
1. `scene_tree` и `schema_show` — посмотреть, что есть в сцене и что принимает компонент.
|
||
2. Изменения через `scene_set`, `scene_add_node`, `scene_add_comp`, `prefab_instantiate` или несколько сразу через `scene_apply`; если не уверены, сначала `dry-run`. `scene_add_comp` вешает и скрипт по имени его типа (`EnemyAI`), а экспортированные поля скрипта читаются и задаются так же, как поля компонентов (`EnemyAI.PointA`). Поле-ссылка на узел принимает путь к узлу вида `Root/PatrolA1`.
|
||
3. `scene_validate`, затем `scene_run` с числом кадров: в журнале будут предупреждения и ошибки, а хеш состояния показывает, одинаково ли ведут себя два запуска. `watch` перечисляет узлы, чьи позиции отчёт снимает по ходу запуска, чтобы проверить, что что-то движется. В редакторе `scene_run` запускает сцену такой, какая она в редакторе, с несохранёнными правками, в отдельном процессе.
|
||
4. Сыграйте так, как сыграл бы игрок, и проверьте результат в том же запуске:
|
||
- `input` нажимает действия по кадрам: `30 press Jump; 10-60 hold Right; 90 release Right; 0-40 axis Move 1`. Имена — действия ввода из `project.aego`.
|
||
- `assert` проверяет значения на кадре или на любом кадре запуска: `@120 Player.transform.position.y < 3; EnemyLeft.Health.hp == 0; Enemy.script/Enemy.hp ~= 2.5; exists Ledge; @60 gone Coin`. Пути те же, что принимает `scene_set`; `~=` сравнивает числа с допуском 0.01. Отчёт пишет `ok` или `failed` с найденным значением и кадром; непрошедшая проверка проваливает запуск, и CLI выходит с кодом 2.
|
||
- `shot` снимает до трёх кадров: `shot=30,90`. В ответе — картинки шириной 640 пикселей (`scale` меняет ширину) и пути полных кадров в `.aego/cache/runs/`. Для снимков нужен дисплей: на сервере запускайте агента или `aego mcp` под `xvfb-run -a` (в Debian и Ubuntu: `apt install xvfb`) или уберите `shot`. Без того и другого прогон останавливается с этим советом.
|
||
|
||
```sh
|
||
aego scene run scenes/main.aescene --frames 120 --input "1-80 axis Move 1; 40 press Jump" --assert "Player.transform.position.x > -10" --shot 60
|
||
```
|
||
|
||
## Рисование спрайтов
|
||
|
||
Агент рисует нужные ему картинки, а не собирает персонажей из цветных прямоугольников. Оба инструмента пишут PNG в `assets/`, импортируют его и отвечают картинкой-превью, так что агент может посмотреть и перерисовать с `replace`; `dry-run` только показывает превью.
|
||
|
||
- `asset_pixels` принимает пиксель-арт текстом: каждый символ `grid` — пиксель, `palette` сопоставляет символам цвета, `.` прозрачна. Строки вида `idle:` и `run1:` начинают кадры одного размера; из них получается один атлас со спрайтом на кадр (`hero_idle`, `hero_run1`) и зацикленный клип-флипбук `hero.aeanim`, готовый для Animation Player. `scale` повторяет каждый пиксель; текстуры фильтруются как пиксели.
|
||
|
||
```
|
||
asset_pixels path=assets/sprites/hero.png scale=4
|
||
palette: {"r": "#d0312d", "s": "#f4c7a1", "b": "#2b4fd8"}
|
||
grid:
|
||
idle:
|
||
..rrrr..
|
||
.rrrrrr.
|
||
.ssbss..
|
||
run1:
|
||
..rrrr..
|
||
.rrrrrr.
|
||
..sbbs..
|
||
```
|
||
|
||
- `asset_svg` рисует SVG-документ размером `width`×`height`: `path`, `rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon`, группы, `fill`, `stroke`, прозрачность и `transform`. Фильтры, градиенты и текст не рисуются; ответ называет, что пропущено. Для тайлов, интерфейса и иконок предметов.
|
||
|
||
Проект держит рисунки в одном стиле блоком `art` в `project.aego`:
|
||
|
||
```
|
||
art {
|
||
palette=["#1a1c2c", "#5d275d", "#b13e53", "#ef7d57", "#ffcd75", "#a7f070"]
|
||
pixelsPerUnit=16
|
||
}
|
||
```
|
||
|
||
Без аргумента `palette` инструмент `asset_pixels` берёт эту палитру, её цвета — `0`–`9` и `a`–`z`; `pixelsPerUnit` — пиксели рисунка на единицу мира, и рисунок увеличивается до `pixelsPerUnit` рендера. **Состояние проекта** перечисляет пиксельные спрайты с цветами вне палитры.
|
||
|
||
## При открытом редакторе
|
||
|
||
Редактор и агент могут работать с одним проектом. Пока редактор открыт, команды `aego` и `aego mcp` идут через него: редактор пишет адрес своего прокси в `.aego/editor.lock`, и CLI отправляет каждую команду туда.
|
||
|
||
- Изменение — шаг отмены открытой сцены с пометкой, откуда оно пришло: `via CLI: Rename` или `via agent: <клиент>: Add Ledge` для агента, подключённого через `aego mcp`. Файл меняется при сохранении, как и с вашими правками.
|
||
- **Окно → Подтверждать изменения внешних агентов** (`editor.proxy.confirm`, по умолчанию выключено) ставит такие изменения в очередь панели агента, как изменения её собственного агента.
|
||
- Слежка за агентом показывает, где работает внешний агент, так же, как агента панели.
|
||
- Команды, создающие ассеты, работают: ассеты создаёт редактор. `prefab_create` в открытой сцене с несохранёнными изменениями создаёт префаб и связывает с ним узел шагом Undo; сцена остаётся несохранённой.
|
||
- Если редактор не отвечает, CLI работает с файлами сам. Сцена, префаб или ассет данных, изменённые на диске, перезагружаются в редакторе, если в них нет несохранённых изменений; если они есть, редактор спрашивает, перезагрузить файл или оставить свою версию.
|