Shell Tool (`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 для долгоживущих процессов, таких как серверы разработки, вотчеры или демоны, которые должны продолжать работу, не блокируя последующие команды. Установите 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
Вотчеров сборки: 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. Примечание: Этот параметр применяется только при включенном 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 и 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 действует как подстановочный знак, разрешая любые команды, которые не заблокированы явно.
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 Tool (run_shell_command)

Описание

Аргументы

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

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

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

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

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

Настройка

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

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

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

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

Важные примечания

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

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

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

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

Shell Tool (`run_shell_command`)

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

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

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