ПроектыEsc
Антон Ишинкин2 мин чтения

Cocos Terminal: терминал и AI CLI внутри редактора

Разработал расширение для Cocos Creator 3.8: встроенный терминал с настоящим PTY, интерактивными CLI и запуском агентных инструментов прямо в игровом проекте.

  • TypeScript
  • Cocos Creator
  • xterm.js
  • PTY
  • Electron
Исходный код на 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.
  • Закрытие панели освобождает терминал и связанную сессию.

Источники и документация