Интеграция с терминалом в SourceCraft Code Assistant

Интеграция с терминалом — это ключевая функция, которая позволяет Code Assistant выполнять команды в вашем терминале и обрабатывать их вывод. Эта двусторонняя связь между ИИ и вашей средой разработки открывает мощные возможности автоматизации.

Интеграция с терминалом автоматически включена в Code Assistant и напрямую подключается к жизненному циклу выполнения команд в вашем терминале без необходимости настройки. Эта встроенная функция позволяет Code Assistant:

• Выполнять команды от вашего имени через инструмент execute_command.
• Читать вывод команд в реальном времени без необходимости копирования и вставки.
• Автоматически обнаруживать и исправлять ошибки в работающих приложениях.
• Отслеживать коды завершения команд для определения успеха или неудачи.
• Отслеживать изменения рабочего каталога по мере навигации по вашему проекту.
• Реагировать на вывод терминала без вмешательства пользователя.
• Останавливать выполняющиеся команды прямо из интерфейса чата с помощью кнопки остановки, которая появляется рядом с сообщением о выполнении команды.

Когда вы просите Code Assistant выполнить такие задачи, как установка зависимостей, запуск сервера разработки или анализ ошибок сборки, интеграция с терминалом работает скрыто, чтобы сделать эти взаимодействия плавными и эффективными.

Настройка интеграции с терминалом

Code Assistant предоставляет подробную настройку взаимодействия с терминалами. Чтобы получить доступ к этим настройкам:

1. На верхней панели чата нажмите кнопку Settings.
2. На левой панели перейдите в раздел Terminal.

Основные настройки

Terminal output limit

Настройка управляет объемом вывода, который Code Assistant захватывает из ваших команд:

• Рассмотрите возможность уменьшения, если вы беспокоитесь о расходе токенов или если Code Assistant кажется медленным при обработке очень длинных выводов.
• Рассмотрите возможность увеличения, если вам часто требуется больше содержимого из длинных команд, но учитывайте возможные затраты токенов. По умолчанию: 500 строк.

Compress progress bar output

Оставьте опцию включенной (по умолчанию) для более чистого вывода и экономии токенов. Это позволяет Code Assistant обрабатывать динамический вывод, такой как прогресс-бары или спиннеры, показывая только конечное состояние. Отключайте только в случаях, когда вам нужно отладить промежуточный, необработанный вывод прогресс-бара или аналогичного динамического отображения.

Расширенные настройки

Inherit environment variables

Эта настройка управляет тем, будут ли терминальные сессии Code Assistant использовать те же переменные окружения (например, PATH, API-ключи и т. д.), что и ваша основная среда VS Code.

Она напрямую отражает глобальную настройку VS Code terminal.integrated.inheritEnv.

Оставьте эту настройку включенной (по умолчанию для VS Code), если вы хотите, чтобы команды Code Assistant работали в том же контексте и с теми же инструментами, что и ваш обычный терминал VS Code. Рассмотрите возможность отключения только в том случае, если вам нужна полностью чистая, изолированная среда для задач терминала Code Assistant или вы устраняете сложные конфликты переменных окружения.

Среда выполнения

На macOS (и, возможно, других операционных системах) среда, предоставляемая VS Code, а следовательно, и Code Assistant, может отличаться в зависимости от того, как был запущен VS Code.

Если VS Code запущен из терминала с помощью команды vscode, VS Code и Code Assistant унаследуют среду из оболочки, которая их запустила, и все, как правило, будет работать корректно.

Если VS Code запущен из Finder, Dock или Spotlight, переменные окружения, экспортированные из .zshrc или .zprofile, скорее всего, будут отсутствовать. Если у вас есть переменные окружения, установленные в одном из этих файлов, и вы обнаружите, что они отсутствуют при запуске VS Code, переместите их в .zshenv и выполните выход и повторный вход в систему, чтобы менеджер окон подхватил новые настройки окружения.

Disable terminal shell integration

Эта настройка определяет, как Code Assistant выполняет команды терминала.

• Включено — Code Assistant будет выполнять команды, используя встроенный терминал, отображая вывод непосредственно в интерфейсе чата. Этот метод, как правило, надежен, обеспечивает четкий вывод и является предпочтительным способом для большинства пользователей для взаимодействия с командами терминала через Code Assistant. Он гарантирует выполнение команд в согласованной среде, управляемой Code Assistant.

• Выключено — Code Assistant попытается выполнять команды непосредственно в активной панели терминала VS Code. Этот альтернативный метод может быть полезен для специфических случаев, когда вам необходимо, чтобы команды выполнялись в полностью настроенной среде оболочки VS Code, или требовалось взаимодействие с определенными функциями терминала VS Code для выполнения команды. Однако это может быть менее надежным в зависимости от настроек вашей оболочки и версии VS Code.

Следующие настройки являются дополнительными опциями, которые применяются, только если вы выключили опцию Disable terminal shell integration:

Terminal shell integration timeout

Если интеграция оболочки включена, но вы все еще видите сообщение Интеграция оболочки недоступна, особенно при сложных настройках оболочки, например Zsh с множеством плагинов или в медленной корпоративной среде, ваша оболочка может занимать слишком много времени для инициализации. Увеличьте это значение, чтобы дать вашей оболочке больше времени для сигнала о готовности Code Assistant. Попробуйте увеличивать на 5–10 секунд. Значение по умолчанию — 5 секунд.

Terminal command delay

Если вывод команды кажется неполным или Code Assistant пропускает конец вывода команды даже при включенной интеграции оболочки, небольшая задержка может помочь. Введите небольшую задержку, например 50 или 100 мс. Это дает терминалу больше времени для вывода всех данных перед тем, как Code Assistant посчитает команду завершенной. Это обходной путь для возможных проблем с синхронизацией в терминале VS Code или определенных оболочках (см. ошибку VS Code #237208). Значение по умолчанию — 0 мс.

Enable PowerShell counter workaround

Специфично для пользователей PowerShell. Включите опцию, если вы обнаружите, что Code Assistant испытывает трудности с выполнением одной и той же команды PowerShell несколько раз подряд, или если захват вывода команд PowerShell ненадежен. Это добавляет уникальный счетчик к командам, чтобы помочь PowerShell различать их.

Clear ZSH EOL mark

Специфично для пользователей Zsh. Иногда Zsh добавляет специальный символ (часто %) в конце строки, если она не заканчивается новой строкой. Включите опцию, если Code Assistant неправильно интерпретирует или путает вывод команд Zsh, особенно если последняя строка вывода включает неожиданный символ. Code Assistant попытается удалить этот маркер (PROMPT_EOL_MARK='').

Enable Oh My Zsh integration

Специфично для пользователей популярного фреймворка Oh My Zsh для Zsh. Включите опцию, если вы используете Oh My Zsh и сталкиваетесь с общими проблемами выполнения команд терминала или отображения вывода, которые не решаются другими настройками. Это помогает Code Assistant согласовать работу с механизмами интеграции Oh My Zsh, устанавливая параметр ITERM_SHELL_INTEGRATION_INSTALLED=Yes. Может потребоваться перезапуск VS Code.

Enable Powerlevel10k integration

Специфично для пользователей темы Powerlevel10k для Zsh. Включите опцию, если ваш сложный промт Powerlevel10k мешает Code Assistant правильно определять границы команд, анализировать вывод или отслеживать текущую рабочую директорию. Эта опция устанавливает параметр POWERLEVEL9K_TERM_SHELL_INTEGRATION=true.

Enable ZDOTDIR handling

Дополнительная опция для пользователей Zsh с кастомизированными местоположениями файлов запуска Zsh. Включите опцию, если вы используете ZDOTDIR для указания пользовательской директории для конфигурационных файлов Zsh, например .zshrc. Эта настройка помогает Code Assistant корректно работать с такими конфигурациями, создавая изолированный временный ZDOTDIR для своих собственных скриптов интеграции и предотвращая конфликты с вашей персональной средой Zsh.

Как работает интеграция оболочки

Интеграция оболочки подключает Code Assistant к процессу выполнения команд терминала в реальном времени:

• Когда вы открываете терминал, VS Code устанавливает специальное соединение с вашей оболочкой.
• VS Code отслеживает вашу активность в терминале, определяя:
  • Появление нового приглашения.
  • Ввод команды.
  • Начало выполнения команды.
  • Завершение выполнения команды (и удачное, и с ошибкой).
  • Текущую директорию.
• Каждый тип оболочки (Bash, Zsh, PowerShell, Fish) реализует это немного по-разному, но все они предоставляют Code Assistant одинаковую функциональность.
• Code Assistant может видеть, какие команды выполняются, где они выполняются, сколько времени они занимают, успешны ли они и их полный вывод — без необходимости копировать и вставлять что-либо.

Устранение неполадок интеграции с терминалом

Интеграция с терминалом встроена в Code Assistant и работает автоматически в большинстве случаев. Если вы видите сообщение Shell Integration Unavailable или сталкиваетесь с проблемами выполнения команд, попробуйте следующие решения:

• Обновите VS Code до последней версии. Требуется VS Code версии 1.93 и выше.
• Убедитесь, что выбран совместимый терминал: вызовите Command palette (Ctrl + Shift + P или Cmd + Shift + P) → Terminal: Select Default Profile → выберите bash, zsh, PowerShell или fish.
• Пользователи Windows PowerShell: выполните Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, затем перезапустите VS Code.
• Пользователи WSL: добавьте . "$(code --locate-shell-integration-path bash)" в ваш ~/.bashrc.

Резервный механизм выполнения команд

Code Assistant имеет резервный механизм для выполнения команд. Это наиболее актуально, если вы выбрали опцию Disable terminal shell integration.

Если Code Assistant настроен на использование интеграции терминала VS Code, но не может подключиться или сталкивается с проблемами, он может автоматически попытаться выполнить команду напрямую, используя фоновый процесс. Это резервное решение, чтобы все же попытаться выполнить команду.

Если используется этот резервный механизм, вы получите сообщение в интерфейсе чата, указывающее, что команда выполняется без полной функциональности либо встроенного терминала Code Assistant, либо интеграции терминала VS Code. Например, в таком случае потоковый вывод в реальном времени или точное определение кода завершения могут быть ограничены.

Политика выполнения PowerShell

PowerShell по умолчанию ограничивает выполнение скриптов. Для настройки:

1. Откройте PowerShell от имени администратора.
2. Проверьте текущую политику: Get-ExecutionPolicy.
3. Установите подходящую политику: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser.

Основные политики:

• Restricted — скрипты запрещены (по умолчанию).
• RemoteSigned — локальные скрипты можно выполнять; загруженные скрипты должны быть подписаны.
• Unrestricted — все скрипты выполняются с предупреждениями.
• AllSigned — все скрипты должны быть подписаны.

Ручная установка интеграции с оболочкой

Если автоматическая интеграция не удалась, добавьте соответствующую строку в конфигурацию вашей оболочки:

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"

if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

Проблемы с настройкой терминала с темой Powerlevel10k

Добавьте строку в ~/.zshrc перед подключением Powerlevel10k:

typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

Также вы можете включить опцию Powerlevel10k Integration в настройках Code Assistant.

Проверка статуса интеграции с оболочкой

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

set | grep -i '[16]33;'
echo "$PROMPT_COMMAND" | grep vsc
trap -p DEBUG | grep vsc

functions | grep -i vsc
typeset -p precmd_functions preexec_functions

Get-Command -Name "*VSC*" -CommandType Function
Get-Content Function:\Prompt | Select-String "VSCode"

functions | grep -i vsc
functions fish_prompt | grep -i vsc

Визуальные индикаторы активной интеграции с оболочкой:

1. Индикатор интеграции оболочки в заголовке терминала.
2. Подсветка обнаружения команд.
3. Обновления рабочего каталога в заголовке терминала.
4. Отчеты о длительности выполнения команд и кодах завершения.

Методы интеграции терминала WSL

При использовании Windows Subsystem for Linux (WSL) существуют следующие способы использования VS Code с WSL, каждый из которых имеет свои особенности для интеграции с оболочкой:

VS Code для Windows с терминалом WSL

• VS Code работает нативно в Windows.
• Вы используете функцию интеграции терминала WSL в VS Code.
• Команды оболочки выполняются через мост WSL.
• Возможна дополнительная задержка из-за взаимодействия Windows и WSL.
• Маркеры интеграции оболочки могут быть затронуты переходом WSL-Windows: убедитесь, что source "$(code --locate-shell-integration-path <shell>)" загружается для вашей оболочки в среде WSL, так как это может не происходить автоматически.

VS Code, работающий внутри WSL

• Вы запускаете VS Code непосредственно из WSL с помощью команды code ..
• Сервер VS Code работает нативно в среде Linux.
• Обеспечивается прямой доступ к файловой системе и инструментам Linux.
• Лучшая производительность и надежность интеграции с оболочкой.
• Интеграция с оболочкой загружается автоматически, так как VS Code работает нативно в среде Linux.
• Рекомендуемый подход для разработки с использованием WSL.

Для оптимальной интеграции с оболочкой в WSL мы рекомендуем:

1. Откройте ваш WSL-дистрибутив.
2. Перейдите в каталог вашего проекта.
3. Запустите VS Code с помощью code ..
4. Используйте встроенный терминал в VS Code.

Интеграция с Cygwin (bash, zsh)

Cygwin предоставляет Unix-подобную среду на системах Windows. Чтобы настроить Cygwin как ваш терминал в VS Code:

1. Установите Cygwin с https://www.cygwin.com/.

2. Откройте настройки VS Code:

   1. Выберите File → Preferences → Settings.
   2. В правом верхнем углу нажмите Open Settings (JSON).

3. Добавьте в settings.json внутри верхнего уровня фигурных скобок {} следующую конфигурацию:

   {
     "terminal.integrated.profiles.windows": {
       "Cygwin": {
         "path": "C:\\cygwin64\\bin\\bash.exe",
         "args": ["--login"],
         "env": {"CHERE_INVOKING": "1"}
       }
     },
     "terminal.integrated.defaultProfile.windows": "Cygwin"
   }
   

   Где:

   • path — указывает на исполняемый файл Bash в вашей установке Cygwin.
   • args — флаг --login гарантирует, что оболочка читает файлы профиля.
   • env — переменная окружения CHERE_INVOKING указывает Cygwin использовать текущий каталог в качестве рабочего.
   • terminal.integrated.defaultProfile.windows — устанавливает Cygwin как профиль терминала по умолчанию.

   Примечание

   Если у вас установлена 32-битная версия Cygwin, используйте "C:\\cygwin\\bin\\bash.exe" для пути.

4. Чтобы открыть новый терминал Cygwin, нажмите Ctrl + Shift + ****. Также вы можете нажать **F1**, ввести Terminal: Create New Terminal (with Profile)` и выбрать Cygwin.

Если вы столкнулись с проблемами интеграции оболочки с Cygwin, убедитесь, что вы добавили соответствующие хуки интеграции оболочки в ваш профиль bash Cygwin.

Ресурсы для устранения неполадок

При возникновении проблем с интеграцией оболочки проверьте журналы отладки:

1. Откройте Help → Toggle Developer Tools → Console.
2. Чтобы увидеть все сообщения журнала, выберите Show All Levels.
3. Ищите сообщения, содержащие текст [Terminal Process].