Outil Shell (`run_shell_command`)

Ce document décrit l’outil run_shell_command pour Qwen Code.

Description

Utilisez run_shell_command pour interagir avec le système sous-jacent, exécuter des scripts ou effectuer des opérations en ligne de commande. run_shell_command exécute une commande shell donnée, y compris les commandes interactives qui nécessitent une saisie utilisateur (par exemple, vim, git rebase -i) si le paramètre tools.shell.enableInteractiveShell est défini sur true.

Sur Windows, les commandes sont exécutées avec cmd.exe /c. Sur d’autres plateformes, elles sont exécutées avec bash -c.

Arguments

run_shell_command prend les arguments suivants :

command (chaîne de caractères, requis) : La commande shell exacte à exécuter.
description (chaîne de caractères, optionnel) : Une brève description de l’objectif de la commande, qui sera affichée à l’utilisateur.
directory (chaîne de caractères, optionnel) : Le répertoire (relatif à la racine du projet) dans lequel exécuter la commande. Si non fourni, la commande s’exécute dans la racine du projet.
is_background (booléen, requis) : Indique s’il faut exécuter la commande en arrière-plan. Ce paramètre est obligatoire pour garantir une décision explicite concernant le mode d’exécution de la commande. Définir sur true pour les processus longs comme les serveurs de développement, les observateurs ou les démons qui doivent continuer à fonctionner sans bloquer les commandes suivantes. Définir sur false pour les commandes ponctuelles qui doivent se terminer avant de poursuivre.

Comment utiliser `run_shell_command` avec Qwen Code

Lors de l’utilisation de run_shell_command, la commande est exécutée en tant que sous-processus. Vous pouvez contrôler si les commandes s’exécutent en arrière-plan ou en avant-plan en utilisant le paramètre is_background, ou en ajoutant explicitement & aux commandes. L’outil renvoie des informations détaillées sur l’exécution, notamment :

Paramètre obligatoire `is_background`

Le paramètre is_background est requis pour toutes les exécutions de commandes. Cette conception garantit que le LLM (et les utilisateurs) doivent explicitement décider si chaque commande doit s’exécuter en arrière-plan ou en avant-plan, favorisant ainsi un comportement d’exécution intentionnel et prévisible. En rendant ce paramètre obligatoire, nous évitons les retours involontaires à une exécution en avant-plan, ce qui pourrait bloquer les opérations suivantes lors du traitement de processus longs.

Exécution en arrière-plan vs en premier plan

L’outil gère intelligemment l’exécution en arrière-plan et en premier plan selon votre choix explicite :

Utilisez l’exécution en arrière-plan (is_background: true) pour :

Serveurs de développement longs : npm run start, npm run dev, yarn dev
Observateurs de construction : npm run watch, webpack --watch
Serveurs de base de données : mongod, mysql, redis-server
Serveurs web : python -m http.server, php -S localhost:8000
Toute commande prévue pour s’exécuter indéfiniment jusqu’à son arrêt manuel

Utilisez l’exécution en premier plan (is_background: false) pour :

Commandes ponctuelles : ls, cat, grep
Commandes de construction : npm run build, make
Commandes d’installation : npm install, pip install
Opérations Git : git commit, git push
Exécutions de tests : npm test, pytest

Informations sur l’exécution

L’outil renvoie des informations détaillées sur l’exécution, notamment :

Command : La commande qui a été exécutée.
Directory : Le répertoire dans lequel la commande a été exécutée.
Stdout : La sortie du flux de sortie standard.
Stderr : La sortie du flux d’erreur standard.
Error : Tout message d’erreur rapporté par le sous-processus.
Exit Code : Le code de sortie de la commande.
Signal : Le numéro du signal si la commande a été terminée par un signal.
Background PIDs : Une liste des PID pour tous les processus en arrière-plan démarrés.

Utilisation :


run_shell_command(command="Vos commandes.", description="Votre description de la commande.", directory="Votre répertoire d'exécution.", is_background=false)

Remarque : Le paramètre is_background est obligatoire et doit être explicitement spécifié pour chaque exécution de commande.

Exemples de `run_shell_command`

Lister les fichiers dans le répertoire courant :


run_shell_command(command="ls -la", is_background=false)

Exécuter un script dans un répertoire spécifique :


run_shell_command(command="./my_script.sh", directory="scripts", description="Exécuter mon script personnalisé", is_background=false)

Démarrer un serveur de développement en arrière-plan (approche recommandée) :


run_shell_command(command="npm run dev", description="Démarrer le serveur de développement en arrière-plan", is_background=true)

Démarrer un serveur en arrière-plan (alternative avec & explicite) :


run_shell_command(command="npm run dev &", description="Démarrer le serveur de développement en arrière-plan", is_background=false)

Exécuter une commande de build en avant-plan :


run_shell_command(command="npm run build", description="Construire le projet", is_background=false)

Démarrer plusieurs services en arrière-plan :


run_shell_command(command="docker-compose up", description="Démarrer tous les services", is_background=true)

Configuration

Vous pouvez configurer le comportement de l’outil run_shell_command en modifiant votre fichier settings.json ou en utilisant la commande /settings dans Qwen Code.

Activation des commandes interactives

Pour activer les commandes interactives, vous devez définir le paramètre tools.shell.enableInteractiveShell sur true. Cela utilisera node-pty pour l’exécution des commandes shell, ce qui permet des sessions interactives. Si node-pty n’est pas disponible, le système reviendra à l’implémentation child_process, qui ne prend pas en charge les commandes interactives.

Exemple settings.json :


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

Affichage de la couleur dans la sortie

Pour afficher la couleur dans la sortie du shell, vous devez définir le paramètre tools.shell.showColor sur true. Remarque : Ce paramètre s’applique uniquement lorsque tools.shell.enableInteractiveShell est activé.

Exemple settings.json :


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

Vous pouvez définir un pager personnalisé pour la sortie du shell en configurant le paramètre tools.shell.pager. Le pager par défaut est cat. Remarque : Ce paramètre s’applique uniquement lorsque tools.shell.enableInteractiveShell est activé.

Exemple de settings.json :


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

Commandes Interactives

L’outil run_shell_command prend désormais en charge les commandes interactives grâce à l’intégration d’un pseudo-terminal (pty). Cela vous permet d’exécuter des commandes nécessitant une saisie utilisateur en temps réel, telles que des éditeurs de texte (vim, nano), des interfaces utilisateur basées sur le terminal (htop) et des opérations de contrôle de version interactives (git rebase -i).

Lorsqu’une commande interactive est en cours d’exécution, vous pouvez lui envoyer des entrées depuis Qwen Code. Pour donner le focus au shell interactif, appuyez sur ctrl+f. La sortie du terminal, y compris les interfaces TUI complexes, sera correctement affichée.

Notes importantes

Sécurité : Soyez prudent lors de l’exécution de commandes, en particulier celles construites à partir d’entrées utilisateur, afin d’éviter les vulnérabilités de sécurité.
Gestion des erreurs : Vérifiez les champs Stderr, Error et Exit Code pour déterminer si une commande s’est exécutée avec succès.
Processus en arrière-plan : Lorsque is_background=true ou lorsqu’une commande contient &, l’outil retournera immédiatement et le processus continuera de s’exécuter en arrière-plan. Le champ Background PIDs contiendra l’identifiant du processus en arrière-plan.
Choix d’exécution en arrière-plan : Le paramètre is_background est obligatoire et permet un contrôle explicite sur le mode d’exécution. Vous pouvez également ajouter & à la commande pour une exécution manuelle en arrière-plan, mais le paramètre is_background doit tout de même être spécifié. Ce paramètre clarifie l’intention et gère automatiquement la configuration de l’exécution en arrière-plan.
Descriptions de commandes : Lors de l’utilisation de is_background=true, la description de la commande inclura un indicateur [background] pour montrer clairement le mode d’exécution.

Variables d’environnement

Lorsque run_shell_command exécute une commande, elle définit la variable d’environnement QWEN_CODE=1 dans l’environnement du sous-processus. Cela permet aux scripts ou outils de détecter s’ils sont exécutés depuis l’interface CLI.

Restrictions de commandes

Vous pouvez restreindre les commandes pouvant être exécutées par l’outil run_shell_command en utilisant les paramètres tools.core et tools.exclude dans votre fichier de configuration.

tools.core : Pour limiter run_shell_command à un ensemble spécifique de commandes, ajoutez des entrées à la liste core sous la catégorie tools au format run_shell_command(<commande>). Par exemple, "tools": {"core": ["run_shell_command(git)"]} n’autorisera que les commandes git. Inclure le terme générique run_shell_command agit comme un joker, autorisant toute commande non explicitement bloquée.
tools.exclude : Pour bloquer des commandes spécifiques, ajoutez des entrées à la liste exclude sous la catégorie tools au format run_shell_command(<commande>). Par exemple, "tools": {"exclude": ["run_shell_command(rm)"]} bloquera les commandes rm.

La logique de validation est conçue pour être sécurisée et flexible :

Chaînage de commandes désactivé : L’outil divise automatiquement les commandes chaînées avec &&, || ou ; et valide chaque partie séparément. Si une partie de la chaîne est interdite, la commande entière est bloquée.
Correspondance par préfixe : L’outil utilise la correspondance par préfixe. Par exemple, si vous autorisez git, vous pouvez exécuter git status ou git log.
Priorité de la liste de blocage : La liste tools.exclude est toujours vérifiée en premier. Si une commande correspond à un préfixe bloqué, elle sera refusée, même si elle correspond également à un préfixe autorisé dans tools.core.

Exemples de restriction de commandes

Autoriser uniquement des préfixes de commande spécifiques

Pour autoriser uniquement les commandes git et npm, et bloquer toutes les autres :


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

git status : Autorisé
npm install : Autorisé
ls -l : Bloqué

Bloquer des préfixes de commande spécifiques

Pour bloquer rm et autoriser toutes les autres commandes :


{
  "tools": {
    "core": ["run_shell_command"],
    "exclude": ["run_shell_command(rm)"]
  }
}

rm -rf / : Bloqué
git status : Autorisé
npm install : Autorisé

La liste de blocage est prioritaire

Si un préfixe de commande se trouve à la fois dans tools.core et tools.exclude, il sera bloqué.


{
  "tools": {
    "core": ["run_shell_command(git)"],
    "exclude": ["run_shell_command(git push)"]
  }
}

git push origin main : Bloqué
git status : Autorisé

Bloquer toutes les commandes shell

Pour bloquer toutes les commandes shell, ajoutez le joker run_shell_command à tools.exclude :


{
  "tools": {
    "exclude": ["run_shell_command"]
  }
}

ls -l : Bloqué
toute autre commande : Bloquée

Note de sécurité pour `excludeTools`

Les restrictions spécifiques aux commandes dans excludeTools pour run_shell_command reposent sur une simple correspondance de chaînes de caractères et peuvent être facilement contournées. Cette fonctionnalité n’est pas un mécanisme de sécurité et ne doit pas être utilisée pour exécuter en toute sécurité du code non fiable. Il est recommandé d’utiliser coreTools pour sélectionner explicitement les commandes pouvant être exécutées.

Outil Shell (run_shell_command)