execute_command

execute_command 工具用于在用户的系统上运行命令行界面（CLI）命令。它允许 Roo 执行系统操作、安装依赖项、构建项目、启动服务器以及完成用户目标所需的其他基于终端的任务。

参数

该工具接受以下参数：

• command（必需）：要执行的 CLI 命令。必须对用户的操作系统有效。
• cwd（可选）：执行命令的工作目录。如果未提供，则使用当前工作目录。

功能与使用时机

该工具直接在用户的系统上执行终端命令，可实现从文件操作到运行开发服务器等广泛的操作。命令在托管的终端实例中运行，并捕获实时输出，与 VS Code 的终端系统集成，以实现最佳性能和安全性。

它在以下情况中使用：

• 安装项目依赖项（npm install、pip install 等）。
• 构建或编译代码（make、npm run build 等）。
• 启动开发服务器或运行应用程序。
• 初始化新项目（git init、npm init 等）。
• 执行其他工具无法提供的文件操作。
• 运行测试或 linting 操作。
• 执行特定技术的专用命令。

主要功能

• 与 VS Code shell API 集成，实现可靠的终端执行。
• 通过注册表系统尽可能重用终端实例。
• 逐行捕获命令输出，提供实时反馈。
• 支持在后台持续运行的长时间命令。
• 允许指定自定义工作目录。
• 在命令执行过程中保持终端历史记录和状态。
• 处理适合用户 shell 的复杂命令链。
• 提供详细的命令完成状态和退出代码解释。
• 支持带有用户反馈循环的交互式终端应用程序。
• 在执行期间显示终端以提高透明度。
• 使用 shell-quote 解析来验证命令的安全性。
• 阻止潜在危险的子 shell 执行模式。
• 与 RooIgnore 系统集成，用于文件访问控制。
• 处理终端转义序列，以实现干净的输出。

局限性

• 命令访问：可能受到 RooIgnore 规则和安全验证的限制。
• 权限提升：需要更高权限的命令可能需要用户进行额外配置。
• 行为差异：某些命令在不同操作系统上的行为可能有所不同。
• 长时间运行：长时间运行的命令可能需要特殊处理。
• 文件路径：文件路径应根据操作系统的 shell 规则进行正确的转义。
• 远程开发：并非所有终端功能都适用于远程开发场景。

工作原理

当 execute_command 工具被调用时，它遵循以下过程：

命令验证与安全检查

• 使用 shell-quote 解析命令以识别其组件。
• 根据安全限制（子 shell 使用、受限文件）进行验证。
• 根据 RooIgnore 规则检查文件访问权限。
• 确保命令符合系统安全要求。

终端管理

• 通过 TerminalRegistry 获取或创建一个终端。
• 设置工作目录上下文。
• 准备事件监听器以捕获输出。
• 显示终端以便用户可见。

命令执行与监控

• 通过 VS Code 的 shellIntegration API 执行命令。
• 捕获带有转义序列处理的输出。
• 对输出处理进行节流（100 毫秒间隔）。
• 监控命令完成或错误。
• 检测像编译器这样的“热门”进程以进行特殊处理。

结果处理

• 从输出中去除 ANSI/VS Code 转义序列以获得干净的输出。
• 解释带有详细信号信息的退出代码。
• 如果命令更改了工作目录，则更新工作目录跟踪。
• 提供带有适当上下文的命令状态。

终端实现细节

该工具使用复杂的终端管理系统：

1. 第一优先级：终端重用

• TerminalRegistry 在可能的情况下尝试重用现有终端。
• 这减少了终端实例的增殖并提高了性能。
• 终端状态（工作目录、历史记录）在命令之间得到保留。

2. 第二优先级：安全验证

• 命令使用 shell-quote 进行解析以进行组件分析。
• $(...) 和反引号等危险模式被阻止。
• 命令会根据 RooIgnore 规则进行检查以控制文件访问。
• 一个基于前缀的允许列表系统用于验证命令模式。

3. 性能优化

• 输出以 100 毫秒的节流间隔进行处理，以防止 UI 过载。
• 零拷贝缓冲区管理使用基于索引的跟踪来提高效率。
• 对编译和 “热” 进程进行特殊处理。
• 针对 Windows PowerShell 进行平台特定优化。

4. 错误和信号处理

• 退出代码被映射到详细的信号信息（SIGTERM, SIGKILL 等）。
• 检测关键故障的核心转储。
• 自动跟踪和处理工作目录更改。
• 从终端断开连接的场景中干净恢复。

使用示例

• 当设置一个新项目时，Roo 会运行 npm init -y 等初始化命令，然后安装依赖项。
• 当构建一个 Web 应用程序时，Roo 会执行 npm run build 等构建命令来编译资产。
• 当部署代码时，Roo 会运行 Git 命令来提交并将更改推送到仓库。
• 当排查问题时，Roo 会执行诊断命令来收集系统信息。
• 当启动一个开发服务器时，Roo 会启动相应的服务器命令（例如 npm start）。
• 当运行测试时，Roo 会为项目的测试框架执行测试运行器命令。

用法示例

在当前目录中运行一个简单命令：

<execute_command>
  <command>npm run dev</command>
</execute_command>

为一个项目安装依赖项：

<execute_command>
  <command>npm install express mongodb mongoose dotenv</command>
</execute_command>

按顺序运行多个命令：

<execute_command>
  <command>mkdir -p src/components && touch src/components/App.js</command>
</execute_command>

在特定目录中执行命令：

<execute_command>
  <command>git status</command>
  <cwd>./my-project</cwd>
</execute_command>

构建然后启动一个项目：

<execute_command>
  <command>npm run build && npm start</command>
</execute_command>