Shell 工具 (`run_shell_command`)

Shell 工具 (run_shell_command)

本文档介绍了 Gemini CLI 的 run_shell_command 工具。

描述

使用 run_shell_command 与底层系统交互，运行脚本，或执行命令行操作。run_shell_command 执行给定的 Shell 命令，包括需要用户输入的交互式命令（例如，vim，git rebase -i），如果 tools.shell.enableInteractiveShell 设置为 true。

在 Windows 上，命令使用 powershell.exe -NoProfile -Command 执行（除非你明确指定 ComSpec 使用其他 Shell）。在其他平台上，它们使用 bash -c 执行。

参数

run_shell_command 接受以下参数：

• command (字符串，必填)：要执行的精确 Shell 命令。
• description (字符串，可选)：命令目的的简短描述，将展示给用户。
• directory (字符串，可选)：执行命令的目录（相对于项目根目录）。如果未提供，命令将在项目根目录运行。

如何使用 Gemini CLI 中的 run_shell_command

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

• 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.")

run_shell_command 示例

列出当前目录中的文件：

run_shell_command(command="ls -la")

在特定目录下运行脚本：

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

启动后台服务器：

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

配置

你可以通过修改 settings.json 文件或使用 Gemini CLI 中的 /settings 命令来配置 run_shell_command 工具的行为。

启用交互式命令

要启用交互式命令，你需要将 tools.shell.enableInteractiveShell 设置为 true。这将使用 node-pty 进行 shell 命令执行，允许交互式会话。如果 node-pty 不可用，它将回退到 child_process 实现，后者不支持交互式命令。

示例 settings.json：

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

在输出中显示颜色

要在 shell 输出中显示颜色，你需要将 tools.shell.showColor 设置为 true。注意：此设置仅在 tools.shell.enableInteractiveShell 启用时应用。

示例 settings.json：

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

设置分页器

你可以通过设置 tools.shell.pager 来为 shell 输出设置自定义分页器。默认分页器是 cat。注意：此设置仅在 tools.shell.enableInteractiveShell 启用时应用。

示例 settings.json：

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

交互式命令

run_shell_command 工具现在支持通过集成伪终端（pty）进行交互式命令。这允许你运行需要实时用户输入的命令，如文本编辑器（vim，nano），基于终端的用户界面（htop），以及交互式的版本控制操作（git rebase -i）。

当交互式命令正在运行时，你可以从 Gemini CLI 向其发送输入。要聚焦于交互式 shell，请按 ctrl+f。终端输出，包括复杂的 TUIs，将被正确渲染。

重要说明

【要求】 只返回翻译后的中文文本,不要添加任何解释或注释。

**安全：**在执行命令时需谨慎，尤其是那些由用户输入构建的命令，以防止安全漏洞。 **错误处理：**检查Stderr、Error和Exit Code字段，以确定命令是否成功执行。 **后台进程：**当使用&在后台运行命令时，工具将立即返回，而进程将继续在后台运行。Background PIDs字段将包含后台进程的进程ID。

环境变量

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

命令限制

您可以通过在配置文件中使用tools.core和tools.exclude设置，限制run_shell_command工具可以执行的命令。

• tools.core：要将run_shell_command限制为特定的命令集，请在tools类别的core列表中以run_shell_command(<command>)的格式添加条目。例如，"tools": {"core": ["run_shell_command(git)"]}只允许git命令。包含通用的run_shell_command作为通配符，允许任何未明确禁止的命令。
• tools.exclude：要阻止特定的命令，请在tools类别的exclude列表中以run_shell_command(<command>)的格式添加条目。例如，"tools": {"exclude": ["run_shell_command(rm)"]}将阻止rm命令。

验证逻辑旨在既安全又灵活：

【翻译文本】

1. 命令链禁用：该工具会自动拆分使用 &&、|| 或 ; 链接的命令，并对每一部分单独进行验证。如果链中的任何部分被禁止，整个命令将被阻止。
2. 前缀匹配：该工具使用前缀匹配。例如，如果你允许 git，你可以运行 git status 或 git log。
3. 阻止列表优先：总是首先检查 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 命令，请在 tools.exclude 中添加 run_shell_command 通配符：

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

• ls -l: 阻止
• any other command: 阻止

关于 excludeTools 的安全说明

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