run_shell_command - 执行 Shell 命令

概述

run_shell_command 工具用于执行 shell 命令。命令以 bash -c <command> 的形式执行。可以使用 & 启动后台进程。命令作为子进程执行，并领导自己的进程组。

工具名称

• 内部名称: run_shell_command
• 显示名称: Shell
• 图标: 终端 (Terminal)

参数

必需参数

参数名	类型	说明
command	string	要执行的精确 bash 命令，以 bash -c <command> 的形式执行。

可选参数

参数名	类型	说明
description	string	命令的简要描述，供用户查看。要具体简洁，理想情况下是一句话。最多可以用 3 句话来表达清楚。不要换行。
directory	string	（可选）运行命令的目录，如果不是项目根目录。必须相对于项目根目录，并且必须已经存在。

功能说明

1. 命令执行：

   • 以 bash -c 形式执行命令
   • 支持所有 bash 语法和功能
   • 可以执行复杂的命令管道

2. 后台进程：

   • 使用 & 启动后台进程
   • 返回后台进程的 PID
   • 可以使用 kill 命令管理进程

3. 进程管理：

   • 命令在独立的进程组中执行
   • 可以使用 kill -- -PGID 终止进程组
   • 可以使用 kill -s SIGNAL -- -PGID 发送信号

4. 实时输出：

   • 支持实时流式输出
   • 可以看到命令执行的进度
   • 输出每秒更新一次

返回信息

工具返回以下信息：

• Command: 执行的命令
• Directory: 命令执行的目录（相对于项目根目录），或 (root)
• Stdout: 标准输出流的输出。可能是 (empty) 或在错误时部分输出，以及任何未等待的后台进程
• Stderr: 标准错误流的输出。可能是 (empty) 或在错误时部分输出，以及任何未等待的后台进程
• Error: 错误信息，如果没有错误则为 (none)
• Exit Code: 退出代码，如果被信号终止则为 (none)
• Signal: 信号编号，如果没有收到信号则为 (none)
• Background PIDs: 启动的后台进程列表，如果没有则为 (none)
• Process Group PGID: 启动的进程组，如果没有则为 (none)

使用示例

基本命令

{
  "command": "ls -la",
  "description": "列出当前目录的所有文件"
}

在特定目录执行

{
  "command": "npm install",
  "directory": "frontend",
  "description": "安装前端依赖"
}

后台进程

{
  "command": "node server.js &",
  "description": "启动开发服务器"
}

命令管道

{
  "command": "cat package.json | grep version",
  "description": "查找 package.json 中的版本号"
}

复杂命令

{
  "command": "find . -name '*.ts' -type f | xargs wc -l | sort -n",
  "description": "统计所有 TypeScript 文件的行数并排序"
}

条件执行

{
  "command": "npm run build && npm run test",
  "description": "构建项目并运行测试"
}

安全特性

1. 命令确认：

   • 在执行前显示命令预览
   • 用户可以批准或取消执行
   • 可以设置总是允许特定命令

2. 命令白名单：

   • 某些命令可以被加入白名单
   • 白名单命令不需要确认
   • 提高常用命令的执行效率

3. 目录限制：

   • 目录必须相对于项目根目录
   • 不能使用绝对路径
   • 目录必须已经存在

4. 命令验证：

   • 验证命令语法
   • 检查潜在的危险操作
   • 提供安全警告

错误处理

可能的错误情况：

1. 命令错误：

   • 命令不存在
   • 命令语法错误
   • 命令执行失败

2. 目录错误：

   • 目录不存在
   • 目录是绝对路径
   • 没有访问权限

3. 执行错误：

   • 进程被终止
   • 超时
   • 资源不足

后台进程管理

启动后台进程

node server.js &

查看后台进程

工具会返回后台进程的 PID：

Background PIDs: 12345
Process Group PGID: 12340

终止后台进程

# 终止特定进程
kill 12345

# 终止整个进程组
kill -- -12340

# 发送特定信号
kill -s SIGTERM -- -12340

命令示例

开发任务

# 启动开发服务器
npm run dev &

# 运行测试
npm test

# 构建项目
npm run build

# 代码检查
npm run lint

文件操作

# 查找文件
find . -name "*.ts"

# 搜索内容
grep -r "TODO" src/

# 统计行数
wc -l src/**/*.ts

# 复制文件
cp config.example.json config.json

Git 操作

# 查看状态
git status

# 提交更改
git add . && git commit -m "Update"

# 推送代码
git push origin main

# 查看日志
git log --oneline -10

系统信息

# 查看磁盘使用
df -h

# 查看内存使用
free -h

# 查看进程
ps aux | grep node

# 查看端口占用
lsof -i :3000

注意事项

1. 交互式命令：避免使用需要用户交互的命令（如 git rebase -i）。使用非交互式版本（如 npm init -y 而不是 npm init）。交互式命令可能导致挂起，直到用户取消。

2. 后台进程：对于不太可能自行停止的命令使用后台进程（如 node server.js &）。如果不确定，请询问用户。

3. 命令描述：提供清晰的命令描述，帮助用户理解命令的作用。

4. 错误处理：检查命令的退出代码和错误输出，适当处理错误。

5. 资源管理：注意命令可能消耗的资源（CPU、内存、磁盘）。

相关工具

• read_file: 读取命令输出文件
• write_file: 写入命令输入文件
• search_file_content: 搜索命令输出
• glob: 查找要处理的文件