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

Этот документ описывает инструмент run_shell_command для Qwen Code.

Описание

Используйте run_shell_command для взаимодействия с базовой системой, запуска скриптов или выполнения операций в командной строке. run_shell_command выполняет указанную shell-команду. В 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: Любое сообщение об ошибке, сообщенное subprocess.
• 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)

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

• Безопасность: Будьте осторожны при выполнении команд, особенно тех, что собраны из пользовательского ввода, чтобы избежать уязвимостей безопасности.
• Интерактивные команды: Избегайте команд, требующих интерактивного ввода от пользователя, так как это может привести к зависанию инструмента. Используйте флаги для неинтерактивного режима, если они доступны (например, npm init -y).
• Обработка ошибок: Проверяйте поля 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, используя настройки coreTools и excludeTools в вашем конфигурационном файле.

• coreTools: Чтобы ограничить run_shell_command определённым набором команд, добавьте записи в список coreTools в формате run_shell_command(<command>). Например, "coreTools": ["run_shell_command(git)"] разрешит только команды git. Если указать общий run_shell_command, это будет работать как wildcard, разрешая любые команды, которые явно не заблокированы.
• excludeTools: Чтобы заблокировать определённые команды, добавьте записи в список excludeTools в формате run_shell_command(<command>). Например, "excludeTools": ["run_shell_command(rm)"] заблокирует команды rm.

Логика валидации разработана так, чтобы быть безопасной и гибкой:

1. Цепочки команд отключены: Инструмент автоматически разделяет команды, объединённые с помощью &&, || или ;, и проверяет каждую часть отдельно. Если какая-либо часть цепочки запрещена, вся команда блокируется.
2. Сопоставление по префиксу: Инструмент использует сопоставление по префиксу. Например, если вы разрешаете git, вы можете выполнять git status или git log.
3. Приоритет чёрного списка: Список excludeTools всегда проверяется первым. Если команда совпадает с заблокированным префиксом, она будет отклонена, даже если также совпадает с разрешённым префиксом из coreTools.

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

Разрешить только определённые префиксы команд

Чтобы разрешить только команды git и npm, а все остальные блокировать:

{
  "coreTools": ["run_shell_command(git)", "run_shell_command(npm)"]
}

• git status: Разрешено
• npm install: Разрешено
• ls -l: Заблокировано

Блокировать определённые префиксы команд

Чтобы заблокировать rm и разрешить все остальные команды:

{
  "coreTools": ["run_shell_command"],
  "excludeTools": ["run_shell_command(rm)"]
}

• rm -rf /: Заблокировано
• git status: Разрешено
• npm install: Разрешено

Блокировка имеет приоритет

Если префикс команды указан и в coreTools, и в excludeTools, то он будет заблокирован.

{
  "coreTools": ["run_shell_command(git)"],
  "excludeTools": ["run_shell_command(git push)"]
}

• git push origin main: Заблокировано
• git status: Разрешено

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

Чтобы заблокировать все shell-команды, добавьте wildcard run_shell_command в excludeTools:

{
  "excludeTools": ["run_shell_command"]
}

• ls -l: Заблокировано
• любая другая команда: Заблокировано

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

Ограничения на уровне команд в excludeTools для run_shell_command основаны на простом сравнении строк и могут быть легко обойдены. Эта функция не является механизмом безопасности и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использовать coreTools для явного выбора команд, которые можно выполнять.