Shell 工具 (run_shell_command)

¥Shell Tool (run_shell_command)

本文档描述了run_shell_commandGemini CLI 的工具。

¥This document describes the run_shell_command tool for the Gemini CLI.

描述

¥Description

使用run_shell_command与底层系统交互、运行脚本或执行命令行操作。run_shell_command执行给定的 shell 命令。在 Windows 上，该命令将使用cmd.exe /c在其他平台上，该命令将使用bash -c。

¥Use run_shell_command to interact with the underlying system, run scripts, or perform command-line operations. run_shell_command executes a given shell command. On Windows, the command will be executed with cmd.exe /c. On other platforms, the command will be executed with bash -c.

参数

¥Arguments

run_shell_command采用以下参数：

¥run_shell_command takes the following arguments:

• command（字符串，必需）：要执行的精确 shell 命令。

  ¥command (string, required): The exact shell command to execute.

• description（字符串，可选）：命令目的的简要描述，将显示给用户。

  ¥description (string, optional): A brief description of the command's purpose, which will be shown to the user.

• directory（字符串，可选）：要在其中执行命令的目录（相对于项目根目录）。如果未提供，则命令将在项目根目录中运行。

  ¥directory (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.

如何使用run_shell_command使用 Gemini CLI

¥How to use run_shell_command with the Gemini CLI

使用时run_shell_command，该命令作为子进程执行。run_shell_command可以使用以下方式启动后台进程&。该工具返回有关执行的详细信息，包括：

¥When using run_shell_command, the command is executed as a subprocess. run_shell_command can start background processes using &. The tool returns detailed information about the execution, including:

• Command：执行的命令。

  ¥Command: The command that was executed.

• Directory：运行命令的目录。

  ¥Directory: The directory where the command was run.

• Stdout：从标准输出流输出。

  ¥Stdout: Output from the standard output stream.

• Stderr：来自标准错误流的输出。

  ¥Stderr: Output from the standard error stream.

• Error：子进程报告的任何错误消息。

  ¥Error: Any error message reported by the subprocess.

• Exit Code：命令的退出代码。

  ¥Exit Code: The exit code of the command.

• Signal：如果命令由信号终止，则为信号编号。

  ¥Signal: The signal number if the command was terminated by a signal.

• Background PIDs：已启动的任何后台进程的 PID 列表。

  ¥Background PIDs: A list of PIDs for any background processes started.

用法：

¥Usage:

run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")

run_shell_command示例

¥run_shell_command examples

列出当前目录中的文件：

¥List files in the current directory:

run_shell_command(command="ls -la")

在特定目录中运行脚本：

¥Run a script in a specific directory:

run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")

启动后台服务器：

¥Start a background server:

run_shell_command(command="npm run dev &", description="Start development server in background")

重要说明

¥Important notes

• 安全：执行命令时要小心谨慎，尤其是那些由用户输入构建的命令，以防止出现安全漏洞。

  ¥Security: Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.

• 交互式命令：避免使用需要用户交互输入的命令，因为这可能会导致工具挂起。如果可用，请使用非交互式标志（例如，npm init -y）。

  ¥Interactive commands: Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., npm init -y).

• 错误处理：检查Stderr，Error， 和Exit Code字段来确定命令是否执行成功。

  ¥Error handling: Check the Stderr, Error, and Exit Code fields to determine if a command executed successfully.

• 后台进程：当命令在后台运行时&，该工具将立即返回，并且该进程将继续在后台运行。Background PIDs字段将包含后台进程的进程 ID。

  ¥Background processes: When a command is run in the background with &, the tool will return immediately and the process will continue to run in the background. The Background PIDs field will contain the process ID of the background process.

环境变量

¥Environment Variables

什么时候run_shell_command执行命令时，它会设置GEMINI_CLI=1子进程环境中的环境变量。这允许脚本或工具检测它们是否在 Gemini CLI 中运行。

¥When run_shell_command executes a command, it sets the GEMINI_CLI=1 environment variable in the subprocess's environment. This allows scripts or tools to detect if they are being run from within the Gemini CLI.

命令限制

¥Command Restrictions

您可以限制run_shell_command通过使用coreTools和excludeTools配置文件中的设置。

¥You can restrict the commands that can be executed by the run_shell_command tool by using the coreTools and excludeTools settings in your configuration file.

• coreTools：限制run_shell_command对于特定的命令集，将条目添加到coreTools格式列表run_shell_command(<command>)。 例如，"coreTools": ["run_shell_command(git)"]仅允许git命令。包括通用run_shell_command充当通配符，允许任何未明确阻止的命令。

  ¥coreTools: To restrict run_shell_command to a specific set of commands, add entries to the coreTools list in the format run_shell_command(<command>). For example, "coreTools": ["run_shell_command(git)"] will only allow git commands. Including the generic run_shell_command acts as a wildcard, allowing any command not explicitly blocked.

• excludeTools：要阻止特定命令，请将条目添加到excludeTools格式列表run_shell_command(<command>)。 例如，"excludeTools": ["run_shell_command(rm)"]将会阻止rm命令。

  ¥excludeTools: To block specific commands, add entries to the excludeTools list in the format run_shell_command(<command>). For example, "excludeTools": ["run_shell_command(rm)"] will block rm commands.

验证逻辑设计得安全且灵活：

¥The validation logic is designed to be secure and flexible:

1. 命令链已禁用：该工具会自动拆分链接的命令&&，||， 或者;并分别验证每个部分。如果链中的任何部分被禁止，则整个命令都会被阻止。

   ¥Command Chaining Disabled: The tool automatically splits commands chained with &&, ||, or ; and validates each part separately. If any part of the chain is disallowed, the entire command is blocked.

2. 前缀匹配：该工具使用前缀匹配。例如，如果您允许git，你可以运行git status或者git log。

   ¥Prefix Matching: The tool uses prefix matching. For example, if you allow git, you can run git status or git log.

3. 黑名单优先级： 这excludeTools始终会首先检查列表。如果命令与阻止的前缀匹配，则会被拒绝，即使它也与允许的前缀匹配coreTools。

   ¥Blocklist Precedence: The excludeTools list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in coreTools.

命令限制示例

¥Command Restriction Examples

仅允许特定的命令前缀

¥Allow only specific command prefixes

仅允许git和npm命令，并阻止所有其他命令：

¥To allow only git and npm commands, and block all others:

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

• git status：允许

  ¥git status: Allowed

• npm install：允许

  ¥npm install: Allowed

• ls -l：已阻止

  ¥ls -l: Blocked

阻止特定的命令前缀

¥Block specific command prefixes

阻止rm并允许所有其他命令：

¥To block rm and allow all other commands:

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

• rm -rf /：已阻止

  ¥rm -rf /: Blocked

• git status：允许

  ¥git status: Allowed

• npm install：允许

  ¥npm install: Allowed

黑名单优先

¥Blocklist takes precedence

如果命令前缀同时出现在coreTools和excludeTools，它将被阻止。

¥If a command prefix is in both coreTools and excludeTools, it will be blocked.

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

• git push origin main：已阻止

  ¥git push origin main: Blocked

• git status：允许

  ¥git status: Allowed

阻止所有 shell 命令

¥Block all shell commands

要阻止所有 shell 命令，请添加run_shell_command通配符excludeTools：

¥To block all shell commands, add the run_shell_command wildcard to excludeTools:

{
  "excludeTools": ["run_shell_command"]
}

• ls -l：已阻止

  ¥ls -l: Blocked

• any other command：已阻止

  ¥any other command: Blocked

安全说明excludeTools

¥Security Note for excludeTools

命令特定的限制excludeTools为了run_shell_command基于简单的字符串匹配，很容易被绕过。此功能不是安全机制不应依赖它来安全地执行不受信任的代码。建议使用coreTools明确选择可以执行的命令。

¥Command-specific restrictions in excludeTools for run_shell_command are based on simple string matching and can be easily bypassed. This feature is not a security mechanism and should not be relied upon to safely execute untrusted code. It is recommended to use coreTools to explicitly select commands that can be executed.