Инструмент Shell (`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 или явно добавляя & к командам. Инструмент возвращает подробную информацию о выполнении, включая:

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

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

Выполнение в фоне vs на переднем плане

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

Используйте выполнение в фоне (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 определяет, будут ли команды оболочки выполняться через 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 и 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(<команда>). Например, "tools": {"core": ["run_shell_command(git)"]} разрешит только команды git. Включение общего run_shell_command действует как подстановочный знак, разрешая любую команду, не заблокированную явно.
tools.exclude: Чтобы заблокировать определённые команды, добавьте записи в список exclude в категории tools в формате run_shell_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: Разрешено

Блокировать все команды оболочки

Чтобы заблокировать все команды оболочки, добавьте подстановочный знак 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

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

Выполнение в фоне vs на переднем плане

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

Примеры run_shell_command

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

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

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

Установка пейджера

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

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

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

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

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

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

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

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

Примеры `run_shell_command`

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