Инструмент Shell (`run_shell_command`)

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

Описание

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

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

Аргументы

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

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

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

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

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

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

Фоновое и активное выполнение

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

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

Долго работающих серверов разработки: npm run start, npm run dev, yarn dev
Watchers для сборок: 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="Your commands.", description="Your description of the command.", directory="Your execution 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="Run my custom script", is_background=false)

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


run_shell_command(command="npm run dev", description="Start development server in background", is_background=true)

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


run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false)

Запуск команды сборки в активном режиме:


run_shell_command(command="npm run build", description="Build the project", is_background=false)

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


run_shell_command(command="docker-compose up", description="Start all services", is_background=true)

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

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

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

Параметр tools.shell.enableInteractiveShell определяет, будут ли shell-команды выполняться через 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
    }
  }
}

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

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

Пример settings.json:


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

Настройка пейджера

Вы можете задать пользовательский пейджер для вывода shell, установив параметр tools.shell.pager. Пейджер по умолчанию — cat на платформах, отличных от Windows. В Windows пейджер по умолчанию не задан. Установите для tools.shell.pager пустую строку, чтобы отключить переменные окружения пейджера. Примечание: Этот параметр применяется только тогда, когда включен tools.shell.enableInteractiveShell.

Пример settings.json:


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

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

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

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

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

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

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

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

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

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

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

Логика валидации разработана с учетом безопасности и гибкости:

Объединение команд отключено: Инструмент автоматически разделяет команды, объединенные с помощью &&, || или ;, и проверяет каждую часть отдельно. Если какая-либо часть цепочки запрещена, блокируется вся команда.
Сопоставление по префиксу: Инструмент использует сопоставление по префиксу. Например, если вы разрешите git, вы сможете запускать git status или git log.
Приоритет списка блокировок: Список 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: Разрешено

Блокировка всех shell-команд

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


{
  "tools": {
    "exclude": ["run_shell_command"]
  }
}

ls -l: Заблокировано
любая другая команда: Заблокировано

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

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

Инструмент Shell (run_shell_command)

Описание

Аргументы

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

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

Фоновое и активное выполнение

Информация о выполнении

Примеры run_shell_command

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

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

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

Настройка пейджера

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

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

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

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

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

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

Инструмент Shell (`run_shell_command`)

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

Примеры `run_shell_command`

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