Skip to main content

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工具时，它遵循以下流程：

  1. 命令验证和安全检查：

    • 使用shell-quote解析命令以识别组件
    • 根据安全限制验证(子shell使用、受限文件)
    • 检查RooIgnore规则的文件访问权限
    • 确保命令满足系统安全要求

  2. 终端管理：

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

  3. 命令执行和监控：

    • 通过VS Code的shellIntegration API执行
    • 捕获带有转义序列处理的输出
    • 节流输出处理(100ms间隔)
    • 监控命令完成或错误
    • 检测编译器等"热"进程进行特殊处理

  4. 结果处理：

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

终端实现细节​

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

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

    • TerminalRegistry尽可能重用现有终端
    • 减少终端实例扩散并提高性能
    • 跨命令保留终端状态(工作目录、历史记录)

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

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

  3. 性能优化

    • 输出以100ms节流间隔处理以防止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>