Инструмент 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, optional): Запускать ли команду в фоновом режиме. Если не указано, по умолчанию используется false (выполнение в активном режиме). Установите значение true для долго работающих процессов, таких как серверы разработки, watchers или демоны, которые должны продолжать работать без блокировки последующих команд.

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

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

Параметр `is_background`

is_background является необязательным — схема инструмента требует только command — и если он опущен, команда выполняется в активном режиме. Следовательно, явным должно быть другое решение: команда, которая не остановится сама по себе, должна быть помечена как is_background: true, потому что оставление её в активном режиме блокирует ход до истечения времени ожидания.

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

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

Используйте фоновое выполнение (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
Любых команд, которые должны выполняться бесконечно до ручной остановки

Используйте активное выполнение (по умолчанию) для команд, которые завершаются сами по себе, таких как сборки, установки, git-операции и запуски тестов.

Чтение и поиск файлов вообще не являются кандидатами для этого инструмента: используйте специализированные инструменты (read_file, grep_search, glob) вместо cat, grep или find, что исключается в описании самого инструмента.

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

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

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 является необязательным. Его отсутствие означает выполнение команды в активном режиме, поэтому явный true нужен для команды, которая не остановится сама по себе.

Примеры `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)

Примечание: явный & не является управляемым фоновым механизмом. При is_background: true инструмент отклоняет завершающий & перед выполнением команды; при is_background=false оболочка отделяет процесс, поэтому вызов возвращается без отслеживания процесса — у него нет записи фоновой задачи, и task_stop не может его достичь. Всегда используйте is_background=true для команды, которая должна выполняться в фоновом режиме.

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


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-программы, работают корректно.

Если параметр не задан, явные разовые запросы используют child_process; интерактивные сеансы TUI, ACP, stream-json ввода, stdin-only и file-input используют PTY. В сборках Windows <= 19041 (до Windows 10 версии 2004) режим PTY переключается на child_process, поскольку старые реализации 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 запускает отслеживаемый фоновый процесс: инструмент немедленно возвращает идентификатор оболочки и PID, а процесс продолжает выполняться. Оболочечный & не создает такой процесс — при is_background: true инструмент отклоняет завершающий &, а при is_background=false оболочка отделяет команду без отслеживания инструментом.
Выбор фонового выполнения: Параметр is_background является необязательным (схема требует только command); установите is_background: true для команды, которая не остановится сама по себе, потому что оставление её в активном режиме блокирует ход до истечения времени ожидания. Используйте 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

Параметр is_background

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

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

Примеры run_shell_command

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

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

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

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

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

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

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

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

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

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

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

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

Параметр `is_background`

Примеры `run_shell_command`

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