Skip to Content
Руководство для разработчиковИнструментыОболочка

Инструмент оболочки (run_shell_command)

В этом документе описывается инструмент run_shell_command для Qwen Code.

Описание

Используйте run_shell_command для взаимодействия с базовой операционной системой, запуска скриптов или выполнения операций из командной строки. run_shell_command выполняет указанную команду оболочки, включая интерактивные команды, требующие ввода пользователя (например, vim, git rebase -i), если параметр tools.shell.enableInteractiveShell установлен в значение true.

В Windows команды выполняются с помощью cmd.exe /c. На других платформах они выполняются с помощью bash -c.

Аргументы

Функция run_shell_command принимает следующие аргументы:

  • command (строка, обязательный): Точная команда оболочки для выполнения.
  • description (строка, необязательный): Краткое описание цели команды, которое будет отображаться пользователю.
  • directory (строка, необязательный): Каталог (относительно корня проекта), в котором следует выполнить команду. Если не указан, команда выполняется в корне проекта.
  • is_background (логический тип, обязательный): Указывает, следует ли выполнять команду в фоновом режиме. Этот параметр обязателен, чтобы обеспечить явное принятие решения о режиме выполнения команды. Установите значение true для длительных процессов, таких как серверы разработки, наблюдатели или демоны, которые должны продолжать работать без блокировки последующих команд. Установите значение false для однократных команд, которые должны завершиться перед переходом к следующему шагу.

Как использовать run_shell_command с Qwen Code

При использовании run_shell_command команда выполняется как дочерний процесс. Вы можете управлять тем, будет ли команда запущена в фоновом или переднем режиме, с помощью параметра is_background или явно добавив символ & к команде. Инструмент возвращает подробную информацию о выполнении, включая:

Обязательный параметр фонового режима

Параметр is_background обязателен для всех выполнений команд. Такой подход гарантирует, что ИИ-модель (и пользователи) должны явно указать, должна ли каждая команда выполняться в фоновом или переднем режиме, обеспечивая целенаправленное и предсказуемое поведение при выполнении команд. Сделав этот параметр обязательным, мы исключаем неявный переход к выполнению в переднем режиме, который может заблокировать последующие операции при работе с длительными процессами.

Фоновое и переднее выполнение

Инструмент умно обрабатывает фоновое и переднее выполнение в зависимости от вашего явного выбора:

Используйте фоновое выполнение (is_background: true) для:

  • Долгозапускаемых серверов разработки: npm run start, npm run dev, yarn dev
  • Следящих за сборкой процессов: npm run watch, webpack --watch
  • Серверов баз данных: mongod, mysql, redis-server
  • Веб-серверов: python -m http.server, php -S localhost:8000
  • Любых команд, которые должны выполняться неограниченно долго до их ручной остановки

Используйте переднее выполнение (is_background: false) для:

  • Однократных команд: ls, cat, grep
  • Команд сборки: npm run build, make
  • Команд установки: npm install, pip install
  • Операций Git: git commit, git push
  • Запуска тестов: npm test, pytest

Информация об исполнении

Инструмент возвращает подробную информацию об исполнении, включая:

  • Command — команда, которая была выполнена.
  • Directory — каталог, в котором выполнялась команда.
  • Stdout — вывод из стандартного потока вывода.
  • Stderr — вывод из стандартного потока ошибок.
  • Error — любое сообщение об ошибке, выданное дочерним процессом.
  • Exit Code — код завершения команды.
  • Signal — номер сигнала, если команда была завершена сигналом.
  • Background PIDs — список идентификаторов процессов (PID) для всех фоновых процессов, запущенных командой.

Использование:

run_shell_command(command="Ваши команды.", description="Описание вашей команды.", directory="Каталог выполнения.", is_background=false)

Примечание: Параметр is_background является обязательным и должен быть явно указан при каждом выполнении команды.

Примеры использования run_shell_command

Список файлов в текущем каталоге:

run_shell_command(command="ls -la", is_background=false)

Запуск скрипта в определённом каталоге:

run_shell_command(command="./my_script.sh", directory="scripts", description="Запустить пользовательский скрипт", is_background=false)

Запуск сервера разработки в фоновом режиме (рекомендуемый способ):

run_shell_command(command="npm run dev", description="Запустить сервер разработки в фоновом режиме", is_background=true)

Запуск сервера в фоновом режиме (альтернативный способ с явным символом &):

run_shell_command(command="npm run dev &", description="Запустить сервер разработки в фоновом режиме", is_background=false)

Выполнение команды сборки в переднем плане:

run_shell_command(command="npm run build", description="Собрать проект", is_background=false)

Запуск нескольких фоновых сервисов:

run_shell_command(command="docker-compose up", description="Запустить все сервисы", is_background=true)

Конфигурация

Поведение инструмента run_shell_command можно настроить, изменив файл settings.json или воспользовавшись командой /settings в Qwen Code.

Включение интерактивных команд

Параметр tools.shell.enableInteractiveShell определяет, выполняются ли команды оболочки через node-pty (интерактивный PTY) или через стандартную реализацию на базе child_process. При включении корректно работают интерактивные сессии, такие как vim, git rebase -i и программы с текстовым пользовательским интерфейсом (TUI).

По умолчанию значение этого параметра — true на большинстве платформ. В сборках Windows <= 19041 (до версии Windows 10 2004) значение по умолчанию — false, поскольку в более ранних реализациях ConPTY известны проблемы надёжности (отсутствие вывода, зависания). Это соответствует тому же пороговому значению, используемому в VS Code (microsoft/vscode#123725 ). Если node-pty недоступен во время выполнения, средство автоматически переключается на child_process, независимо от значения данного параметра.

Чтобы явно переопределить значение по умолчанию, задайте его в файле settings.json:

Пример settings.json:

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true
    }
  }
}

Отображение цвета в выводе

Чтобы отображать цвет в выводе оболочки, установите параметр tools.shell.showColor в значение true. Примечание. Этот параметр действует только при включённом параметре tools.shell.enableInteractiveShell.

Пример файла settings.json:

{
  "tools": {
    "shell": {
      "showColor": true
    }
  }
}

Настройка постраничного просмотра

Вы можете задать пользовательский постраничный просмотрщик для вывода оболочки, указав параметр tools.shell.pager. По умолчанию используется cat. Примечание. Этот параметр действует только при включённом параметре tools.shell.enableInteractiveShell.

Пример файла settings.json:

{
  "tools": {
    "shell": {
      "pager": "less"
    }
  }
}

Интерактивные команды

Инструмент run_shell_command теперь поддерживает интерактивные команды за счёт интеграции псевдотерминала (pty). Это позволяет запускать команды, требующие немедленного ввода от пользователя, например текстовые редакторы (vim, nano), интерфейсы, работающие в терминале (htop), и интерактивные операции системы контроля версий (git rebase -i).

Пока выполняется интерактивная команда, вы можете отправлять ей ввод из Qwen Code. Чтобы сфокусироваться на интерактивной оболочке, нажмите ctrl+f. Вывод терминала, включая сложные TUI, будет корректно отображаться.

Важные замечания

  • Безопасность: Будьте осторожны при выполнении команд, особенно тех, которые формируются на основе пользовательского ввода, чтобы предотвратить уязвимости безопасности.
  • Обработка ошибок: Проверяйте поля Stderr, Error и Код завершения, чтобы определить, успешно ли выполнилась команда.
  • Фоновые процессы: При is_background=true или если команда содержит символ &, инструмент вернёт управление немедленно, а процесс продолжит выполняться в фоновом режиме. В поле PID фоновых процессов будет указан идентификатор процесса (PID) фонового процесса.
  • Выбор режима фонового выполнения: Параметр is_background является обязательным и обеспечивает явное управление режимом выполнения. Вы также можете добавить символ & в команду для ручного запуска в фоновом режиме, однако параметр is_background всё равно должен быть указан. Этот параметр делает намерение более понятным и автоматически настраивает фоновое выполнение.
  • Описания команд: При использовании is_background=true в описании команды будет присутствовать индикатор [фоновый], что наглядно покажет выбранный режим выполнения.

Переменные окружения

Когда run_shell_command выполняет команду, он устанавливает переменную окружения QWEN_CODE=1 в окружении дочернего процесса. Это позволяет скриптам или инструментам определить, запускаются ли они из CLI.

Ограничения команд

Вы можете ограничить набор команд, которые может выполнять инструмент run_shell_command, с помощью параметров tools.core и tools.exclude в конфигурационном файле.

  • tools.core: Чтобы разрешить выполнение run_shell_command только для определённого набора команд, добавьте элементы в список core в категории tools в формате run_shell_command(<команда>). Например, запись "tools": {"core": ["run_shell_command(git)"]} разрешает выполнение только команд git. Указание обобщённой формы run_shell_command действует как шаблон-«звёздочка» и разрешает любые команды, явно не заблокированные в других настройках.
  • tools.exclude: Чтобы заблокировать конкретные команды, добавьте элементы в список exclude в категории tools в формате run_shell_command(<команда>). Например, запись "tools": {"exclude": ["run_shell_command(rm)"]} блокирует выполнение команд rm.

Логика проверки спроектирована так, чтобы быть одновременно безопасной и гибкой:

  1. Отключена цепочка команд: Инструмент автоматически разделяет команды, объединённые операторами &&, || или ;, и проверяет каждую часть отдельно. Если какая-либо часть цепочки запрещена, вся команда блокируется.
  2. Сопоставление по префиксу: Инструмент использует сопоставление по префиксу. Например, если разрешена команда git, вы можете выполнять git status или git log.
  3. Приоритет чёрного списка: Список tools.exclude всегда проверяется первым. Если команда совпадает с заблокированным префиксом, она будет отклонена, даже если она также совпадает с разрешённым префиксом из tools.core.

Примеры ограничений команд

Разрешение только определённых префиксов команд

Чтобы разрешить только команды git и npm, а все остальные заблокировать:

{
  "tools": {
    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
  }
}
  • git status: Разрешено
  • npm install: Разрешено
  • ls -l: Заблокировано

Блокировка определённых префиксов команд

Чтобы заблокировать команды rm и разрешить все остальные:

{
  "tools": {
    "core": ["run_shell_command"],
    "exclude": ["run_shell_command(rm)"]
  }
}
  • rm -rf /: Заблокировано
  • git status: Разрешено
  • npm install: Разрешено

Список блокировки имеет приоритет

Если префикс команды присутствует как в tools.core, так и в tools.exclude, он будет заблокирован.

{
  "tools": {
    "core": ["run_shell_command(git)"],
    "exclude": ["run_shell_command(git push)"]
  }
}
  • git push origin main: Заблокировано
  • git status: Разрешено

Блокировка всех команд оболочки

Чтобы заблокировать все команды оболочки, добавьте шаблон run_shell_command в tools.exclude:

{
  "tools": {
    "exclude": ["run_shell_command"]
  }
}
  • ls -l: Заблокировано
  • любая другая команда: Заблокировано

Примечание по безопасности для параметра excludeTools

Командные ограничения, заданные в excludeTools для run_shell_command, основаны на простом сравнении строк и могут быть легко обойдены. Эта функция не является механизмом безопасности, и полагаться на неё для безопасного выполнения непроверенного кода нельзя. Рекомендуется использовать coreTools, чтобы явно указать разрешённые к выполнению команды.

Last updated on
Чтение нескольких файловЗапись задач