getting-started.ru.md

Быстрый старт

English · Русский · 简体中文 · Документация

Требования

• Node.js и npm.
• Нативный toolchain для сборки node-pty, поддерживаемый на вашей платформе.
• Графическая сессия рабочего стола, в которой можно запустить Electron.
• При необходимости — Go 1.21 или новее, чтобы собрать нативный хелпер агентов (npm run build:helpers, его же вызывает npm run build). Без Go приложение использует JavaScript-хелперы.
• При необходимости в Linux — bubblewrap (bwrap) для изоляции агентов.
• При необходимости — CLI codex, claude, qwen, kimi, opencode, hermes, grok, omp или pi, установленные и доступные в PATH для тех лаунчеров, которыми вы планируете пользоваться.

В настройках агентов есть ссылки на официальные инструкции установки и повторная проверка. CanvasTTY не устанавливает CLI агентов и не проходит за вас авторизацию. Сначала выполните штатный вход у самого провайдера — только после этого заработают его сессии и лимиты подписки.

Установка и запуск

npm install
npm run dev

npm install также подготавливает Electron и пересобирает нативный модуль node-pty. Команда разработки запускает настоящее Electron-приложение, а не браузерный макет.

Первая сессия

1. Откройте Terminal на Home, чтобы сразу запустить shell в последнем каталоге проекта.
2. Откройте Codex, Claude, Kimi, OpenCode, Hermes или Grok Build, чтобы выбрать каталог проекта и режим запуска (по умолчанию Авто) для этого провайдера (провайдер в диалоге зафиксирован).
3. Откройте Browser на Home, чтобы создать или восстановить карточку встроенного браузера. Agent-сессии, запущенные CanvasTTY, могут работать с открытыми вкладками, пока включено Настройки → Браузер → Доступ агентов.
4. Перемещайте и меняйте размер живого терминала и браузера на одном канвасе.
5. Отдалитесь, чтобы ориентироваться по смысловым сводкам; приблизьтесь, чтобы работать с xterm или native browser page.
6. Вернитесь на Home, чтобы посмотреть реальные сессии, подключённых browser agents и окна квоты провайдера, которые отдают их адаптеры.

Режимы запуска — Авто (по умолчанию), Вручную, Правки, План и Обход; каждый предлагается только там, где его поддерживает CLI. Слои защиты вокруг них описаны в разделе Установка и безопасность. Обход (YOLO) отключает защитные запросы провайдера там, где провайдер такой режим поддерживает, и подчиняется базовой защите и изоляции агентов, если они включены. Для OpenCode CanvasTTY добавляет только на время запуска inline override permission: "allow", сохраняя остальную объединённую конфигурацию OpenCode. Hermes получает штатный --yolo, а Grok Build — штатный --always-approve только для этого запуска. CanvasTTY просит подтвердить его один раз для каждого CLI и никогда не передаёт субагенту; используйте его только в каталоге, который вы готовы отдать агенту на изменение.

У Kimi 2.4+ четыре варианта запуска: Авто (Ask When Needed, --yolo), Вручную, План (--plan) и Обход (Never Ask, --auto). Отдельного режима «Правки» нет. Дополнительные штатные варианты: «Только чтение» Cursor (Ask), явный режим подтверждений, запоминание разрешений OMP, «Без запросов» Claude/Grok/Codex и Autonomous Devin с собственной песочницей. Режимы, доступные только через настройки или плагины, не выдаются за флаги запуска. Полная таблица режимов и границы проверки также описывает требования к версии и песочнице Antigravity.

Анимированные фоны терминалов

Фон выбирается в Настройки → Оформление → Фоны терминалов. Чтобы анимация была видна в OpenCode, обязательно выберите внутри него системную тему: введите /theme и выберите system. Эта тема использует стандартный фон терминала; обычные темы OpenCode рисуют собственную непрозрачную заливку поверх анимации. Подробнее: темы OpenCode.

Для других TUI-агентов, которые заливают экран своим цветом, выберите аналогичный режим системной темы, стандартного фона терминала или прозрачности, если он поддерживается. Это условие отображения анимированного фона, а не требование для обычного запуска агента в CanvasTTY. Собственная заливка отдельных панелей, поля ввода и выделений TUI может сохраняться.

Параметр Фоны терминалов → Настройка → Читаемость текста добавляет затемнение под текстом. Если оно выглядит как тёмные полоски на анимации, уменьшите Затемнение под текстом или выключите читаемость, чтобы сравнить. Обрезанные или пропавшие части самих символов не являются ожидаемым эффектом.

Ввод и управление терминалом

• Нажмите на любую живую карточку терминала, чтобы выбрать и сфокусировать её. Input focus не зависит от selection, поэтому будущий multi-selection сохранит одну однозначную цель для keyboard и wheel.
• Клик вне всех виджетов сбрасывает input focus. Клик по декоративному или action-only виджету не делает его целью wheel.
• Настройки → Управление → Автофокус при наведении переносит input focus после задержки: медленно 500ms, обычно 250ms или быстро 80ms. Уход только отменяет ещё не сработавший перенос; назначенный focus сохраняется, а selection не меняется. По умолчанию автофокус выключен.
• В свежем профиле обычный scroll над canvas, unfocused-виджетами и нефокусируемыми виджетами перемещает canvas по обеим осям, а pinch и Cmd/Ctrl + scroll масштабируют вокруг указателя. Focused input-виджет оставляет обычный wheel/pinch себе в Off или при отпущенном Key. Это относится и к live Browser page: в focus она прокручивается нативно; unfocused Browser, On, активный Key binding, pinch и Cmd/Ctrl + scroll передают события канвасу. Browser summary/placeholder всегда передаёт их канвасу. Настройки → Управление → Зум обычным скроллом возвращает wheel zoom. Свежий профиль использует Key с Command на macOS или Ctrl на остальных платформах. Отдельный полный navigation override по умолчанию использует Option/Alt, разрешает одиночный Command/Ctrl, дополнительно перехватывает drag и при удержании показывает курсор-руку.
• Направления колеса для прокрутки терминала и навигации канваса настраиваются независимо. Canvas inversion применяется к обеим осям pan и к обычному wheel zoom.
• Shift+Enter отправляет модифицированный Enter и в совместимых промптах агента вставляет перенос строки без отправки. Обычный Enter сохраняет штатное поведение PTY.
• По умолчанию выделенный текст копируется через Ctrl+C на Windows, Ctrl+Shift+C на Linux и Cmd+C на macOS. Вставка: Ctrl+Shift+V на Windows/Linux и Cmd+V на macOS. Сочетания можно изменить в настройках. Обычный Ctrl+C без выделения остаётся прерыванием PTY.

Горячие клавиши редактора Codex

Клавиши отправки и переноса строки из Настройки → Основные → Горячие клавиши → Codex применяются к новым и перезапущенным карточкам Codex, включая обычный CLI. Открытая карточка сохраняет привязки своего запуска. CanvasTTY переводит выбранные физические сочетания, включая Command/Meta и русскую раскладку, в отправку и перенос. Поиск, копирование, вставка и перезапуск терминала проверяются до общего обработчика Enter с модификаторами: освободившееся сочетание с Enter можно назначить терминальной команде.

Штатный Codex получает только на время запуска параметры -c tui.keymap, закрепляющие отправку за Enter и сохраняющие штатные сочетания переноса, включая Shift+Enter. При этом запуске они имеют приоритет над личными привязками отправки и переноса; сам ~/.codex/config.toml не меняется. Штатные Enter и Shift+Enter остаются запасными клавишами, если их не забрала настроенная команда CanvasTTY. Подсказки Codex могут показывать эти клавиши вместо выбранного сочетания. Конфигурация сверена с исходниками Codex 0.163.0; более старые версии не проверены. Настройки не влияют на Codex, запущенный вручную в обычной shell-карточке.

В штатном Codex 0.163.0 нет настраиваемого действия «выделить весь черновик»: обычно Ctrl+A перемещает курсор в начало строки. Запись сочетания не добавляет отсутствующее действие; выделение всего черновика требует совместимого комплектного frontend. Подтверждения, голосовой ввод и остальные штатные команды сохраняют собственный keymap.

Ссылки на файлы

Нажмите на путь к локальному файлу, например src/main.ts:42:7, в выводе терминала или агента: файл откроется в приложении по умолчанию, выбранном в операционной системе. Поддерживаются абсолютные пути, пути с пробелами в кавычках и локальные гиперссылки file:// и vscode://file/. Относительные пути отсчитываются от каталога запуска сессии терминала. Открываются только существующие обычные файлы.

Выберите нужное приложение через системные ассоциации файлов. CanvasTTY не выбирает редактор и не передаёт системному приложению номер строки и колонки. HTTP(S)-ссылки по-прежнему открываются в браузере, выбранном в настройках.

Управление браузером и действия

• Browser использует те же независимые правила selection и input focus, что и terminal cards. Hover над native page переносит focus после настроенной задержки; уход со страницы его не сбрасывает. В Off или при отпущенном Key этот focus также позволяет обычному wheel прокручивать live page. Pinch и Cmd/Ctrl + scroll по-прежнему масштабируют canvas. Страница также прокручивается через scrollbar drag, клавиатуру или элементы сайта.
• Доверенные tab strip и navigation bar работают с HTTP(S)-страницами. Скрытие карточки сохраняет вкладки; Закрыть все удаляет их после подтверждения.
• Настройки → Браузер управляют доступом агентов и восстановлением вкладок и показывают недавние загрузки и команды.
• Очистить данные браузера удаляет вкладки, site data, cache, auth cache, staged uploads и текущий список загрузок, но намеренно сохраняет постоянный очищенный audit log.
• Журнал находится в Electron userData/browser/audit, ротируется при 100 МБ и при инициализации или ротации удаляет ротированные файлы старше 30 дней. Перед ручной обработкой или удалением прочитайте руководство по браузеру и журналу.

Полезные команды

Команда	Назначение
npm run dev	Запустить Electron-сборку для разработки
npm test	Запустить Node-тесты
npm run typecheck	Проверить типы main/preload и renderer
npm run build	Собрать нативный хелпер, проверить типы и собрать production-бандлы
npm run preview	Запустить собранное приложение для проверки production-сценария

Перед сдачей изменений выполните тесты, typecheck и build, затем проверьте затронутый сценарий в реальном окне Electron.

Где хранится локальное состояние

Настройки валидирует и сохраняет SettingsStore в main-процессе. Живое состояние терминалов и ограниченный scrollback принадлежат TerminalManager; renderer не является источником истины для истории PTY. Site data браузера остаются в постоянном Chromium partition, безопасный restore state — в userData/browser-state.json, а очищенный hash-chain audit — в userData/browser/audit. Учётные данные провайдеров остаются у установленных CLI и доверенных адаптеров main-процесса и никогда не возвращаются через IPC.

Точные границы описаны в архитектуре, а правила поведения и внешнего вида — в UI-контракте.

Если что-то не работает

Не собирается node-pty

Установите компилятор, Python и системные заголовки для вашей ОС, затем снова выполните npm install. Не заменяйте нативный PTY подставным терминалом: работа с реальными локальными процессами — базовое ограничение продукта.

Агент запускается, но лимиты недоступны

Работающая CLI-сессия и читаемый API квот подписки — это разные возможности. Посмотрите причину в CanvasTTY; повторный вход нужен при ошибке авторизации. API лимитов Claude может отвечать HTTP 429, даже когда сам CLI работает. CanvasTTY ждёт указанного сервером срока повтора (пять минут, если пригодный срок не указан) и сохраняет последнее показание как устаревшее, если оно было. Обновление списка CLI не обходит это ожидание. Некоторые типы аккаунтов не отдают окно подписки; интерфейс должен показать недоступность, а не 0%.

Терминал открыт, но не отмечен как работающий

CanvasTTY показывает живые idle/working/needs_approval для Codex, Claude Code, Qwen Code, Kimi Code, OpenCode, Hermes и Grok Build по provider lifecycle hooks. До первого машинного сигнала агент остаётся unavailable; наличие PTY и текст терминала не являются телеметрией активности.

Дальше: браузер и журнал аудита, создание виджетов или метрики и телеметрия.