Cocos Terminal: терминал и AI CLI внутри редактора
Разработал расширение для Cocos Creator 3.8: встроенный терминал с настоящим PTY, интерактивными CLI и запуском агентных инструментов прямо в игровом проекте.
Исходный код на GitHubЗачем я встроил терминал в Cocos Creator
Во время разработки игры рядом со сценами и ресурсами постоянно нужны команды проекта: Git, сборка, скрипты и инструменты автоматизации. Я сделал dockable-панель, чтобы этот рабочий контекст оставался внутри Cocos Creator. Сессия запускается из каталога открытого проекта.
Важной задачей была поддержка интерактивных программ. Обычного вывода stdout недостаточно для полноэкранного интерфейса, управления курсором и непрерывного ввода. Для такого сценария я связал терминальную панель с настоящим псевдотерминалом.
Как устроено расширение
Я разделил решение на панель и управление процессами. В панели xterm.js отображает поток терминала и принимает ввод. SessionManager в main process хранит сессии, направляет события нужному получателю и освобождает backend при закрытии или замене сессии.
Между слоями используется система сообщений Editor.Message. Контракт ITerminalBackend объединяет ввод, запуск строки, изменение размера, остановку и освобождение ресурсов. Основной PtyBackend работает через @lydell/node-pty, а резервный SpawnBackend поддерживает построчный режим, если нативный модуль недоступен.
Сборка на esbuild создаёт отдельные CommonJS-модули для main process и панели. Нативную PTY-зависимость оставляю внешней: её бинарный модуль загружается из node_modules во время работы редактора.
Интерактивные инструменты и агентный сценарий
В raw-режиме нажатия отправляются в PTY, а вывод возвращается в xterm.js. Это позволяет запускать интерактивные CLI, в том числе Claude, рядом с игровым проектом. Агентный сценарий опирается на возможности запущенного CLI; выбор модели, авторизация и разрешения остаются в самом инструменте.
Размер панели синхронизируется с размером PTY через FitAddon и сообщения resize. Ctrl+C копирует выделение, а без выделения передаётся терминалу как прерывание. Кнопка Stop использует тот же управляющий сигнал. Добавлены вставка из буфера и контекстное меню, а шрифт и размер сохраняются в глобальном профиле редактора.
Что даёт такая архитектура
Единый backend-контракт позволил вынести управление сессиями из UI и проверять его с подставными реализациями. В репозитории есть тесты предпочтения PTY, перехода на fallback, маршрутизации ввода и resize, а также освобождения предыдущей сессии.
Отдельно тестируются история команд, построчный редактор и backend-логика. История fallback хранится в temp/terminal-history.json игрового проекта. При закрытии панели контроллер сохраняет историю, запрашивает закрытие сессии и освобождает xterm.
Интеграцию с Editor и поведение панели нужно проверять внутри Cocos Creator: открытие, перенастройку размера, интерактивный ввод, буфер обмена и остановку процесса. Наличие unit-тестов не заменяет эту проверку.
Что проверить
- Терминал запускается в контексте открытого игрового проекта.
- PTY поддерживает интерактивные CLI, ввод и изменение размера.
- При отсутствии нативного модуля включается явно обозначенный line mode.
- Закрытие панели освобождает терминал и связанную сессию.