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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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