Инструмент 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, обязательный): Точная shell-команда для выполнения.
description (string, опциональный): Краткое описание цели команды, которое будет показано пользователю.
directory (string, опциональный): Директория (относительно корня проекта), в которой нужно выполнить команду. Если не указана, команда выполняется в корне проекта.
is_background (boolean, обязательный): Определяет, следует ли запускать команду в фоновом режиме. Этот параметр обязателен, чтобы явно указать режим выполнения команды. Установите значение true для долгоживущих процессов, таких как серверы разработки, наблюдатели или демоны, которые должны продолжать работу, не блокируя выполнение других команд. Установите значение false для одноразовых команд, которые должны завершиться до продолжения работы.

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

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

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

Пример settings.json:


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

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

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

Пример settings.json:


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

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

Пример settings.json:


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

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

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

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

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

Безопасность: Будьте осторожны при выполнении команд, особенно тех, что формируются на основе пользовательского ввода, чтобы избежать уязвимостей безопасности.
Обработка ошибок: Проверяйте поля Stderr, Error и Exit Code, чтобы определить, успешно ли выполнена команда.
Фоновые процессы: Когда is_background=true или когда команда содержит &, инструмент немедленно возвращает управление, а процесс продолжает выполняться в фоне. Поле Background PIDs будет содержать ID фонового процесса.
Выбор фонового выполнения: Параметр 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-команды, добавьте wildcard 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

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

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

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

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

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

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

Настройка Pager

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

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

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

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

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

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

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

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

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

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