Skip to main content

run_slash_command

实验性功能

run_slash_command 工具是一个实验性功能，必须在设置中明确启用。导航到设置 > 实验性设置并启用“运行斜杠命令”以使用此工具。

run_slash_command 工具执行预定义的斜杠命令以检索特定指令或内容模板。这些命令作为常见任务的可重用指令集，提供 Roo 可以解释和执行的详细指导。命令可以在三个级别定义，具有清晰的优先级层次：项目 > 全局 > 内置。

参数​

该工具接受以下参数：

  • command（必需）：要执行的斜杠命令名称（不带前导斜杠）
  • args（可选）：传递给命令的额外参数或上下文

功能说明​

此工具检索并执行定义为命令目录中 Markdown 文件的指令模板。它通过共享命令模板启用标准化工作流、可重用任务指令和团队范围的一致性。该工具验证实验标志状态，通过优先级层次解析命令，并返回格式化的指令供 Roo 解释。

使用场景​

  • 当执行需要一致步骤的标准化工作流时
  • 当检索项目特定或团队范围的指令模板时
  • 当使用分析和文档初始化代码库时
  • 当将复杂的多步骤流程作为单个命令访问时
  • 当维护团队开发实践的一致性时

主要特性​

  • 三级命令系统：内置、全局（~/.roo/commands/）和项目特定（.roo/commands/）命令
  • 优先级层次：项目命令覆盖全局命令，全局命令覆盖内置命令
  • 基于 Markdown 的模板：使用可选 YAML frontmatter 的简单 .md 文件用于元数据
  • 动态参数：传递特定上下文参数以自定义命令执行
  • 自动发现：命令从其各自的目录自动找到
  • 安全执行：命令仅为文本指令，需要用户批准，而非可执行代码
  • 元数据支持：可选的 frontmatter 用于描述和参数提示
  • 错误恢复：优雅处理，提供有用的错误消息和命令建议
  • 无需注册：只需将 .md 文件放在命令目录中

要求​

此工具需要明确启用：

  1. 打开 VS Code 设置
  2. 导航到实验性设置
  3. 启用“运行斜杠命令”
  4. 如有必要，重启 VS Code

局限性​

  • 实验状态：功能默认禁用，需要选择启用
  • 仅文本指令：命令提供指令，而非直接代码执行
  • 需要批准：所有命令执行都需要用户批准
  • 基于目录：命令必须位于特定目录位置
  • 区分大小写：命令名称区分大小写匹配
  • 单命令：每次工具调用只能执行一个命令

工作原理​

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

  1. 实验标志验证：

    • 检查 runSlashCommand 实验是否启用
    • 如果功能禁用，返回描述性错误
    • 提供启用功能的说明

  2. 参数处理：

    • 验证必需的 command 参数
    • 捕获可选的 args 以自定义命令
    • 为缺失参数递增错误计数器

  3. 命令解析：

    • 首先搜索项目目录（.roo/commands/）
    • 回退到全局目录（~/.roo/commands/）
    • 最后检查内置命令
    • 如果命令不存在则返回 undefined

  4. 命令加载：

    • 读取命令的 markdown 文件
    • 使用 gray-matter 解析可选的 YAML frontmatter
    • 提取描述和参数提示（如果存在）
    • 返回不带 frontmatter 的命令内容

  5. 响应格式化：

    • 包含命令名称和源位置
    • 如果可用，添加描述和参数提示
    • 显示提供的参数以提供上下文
    • 返回完整的命令内容以供解释

  6. 错误处理：

    • 如果请求的命令未找到，列出可用命令
    • 提供有用的错误消息和替代方案
    • 跟踪连续错误以识别错误模式

命令结构​

文件格式​

命令是放置在指定目录中的 markdown 文件：

---
description: 此命令功能的简要描述
argument-hint: 此命令接受的参数
---

# 命令内容

任务的详细指令放在这里。
可以包括：
- 逐步程序
- 代码模板
- 配置示例
- 最佳实践

命名约定​

  • 文件名成为命令名
  • 使用 .md 扩展名
  • 示例：deploy.md 创建 /deploy 命令
  • 区分大小写匹配

目录位置​

  1. 内置命令：硬编码在源代码中
  2. 全局命令：~/.roo/commands/
  3. 项目命令：<project-root>/.roo/commands/

内置命令​

/init 命令​

当前唯一的内置命令分析您的代码库并创建文档：

  • 分析项目结构和架构
  • 创建 AGENTS.md 文档文件
  • 识别编码模式和约定
  • 记录非显而易见的实现细节
  • 提供对 AI 友好的项目上下文

创建自定义命令​

逐步指南​

  1. 创建命令目录：

    # 用于项目特定命令
    mkdir -p .roo/commands

    # 用于全局命令
    mkdir -p ~/.roo/commands

  2. 创建命令文件：

    # 创建部署命令
    touch .roo/commands/deploy.md

  3. 添加命令内容：

    ---
    description: 将应用程序部署到生产环境
    argument-hint: 环境名称（staging, production）
    ---

    ## 部署流程

    1. 运行测试套件确保所有测试通过
    2. 使用优化构建生产包
    3. 更新目标环境的环境变量
    4. 部署到指定环境
    5. 运行部署后健康检查
    6. 更新部署文档

  4. 使用命令： 命令立即可用于使用，无需注册。

命令优先级系统​

当存在多个同名命令时：

  1. 项目级别（最高优先级）

    • 位于 .roo/commands/
    • 允许项目特定覆盖
    • 提交到版本控制以供团队共享

  2. 全局级别（中等优先级）

    • 位于 ~/.roo/commands/
    • 在所有项目中共享
    • 用户特定自定义

  3. 内置级别（最低优先级）

    • 硬编码在扩展中
    • 提供默认功能
    • 始终可作为回退

使用场景示例​

  • 当初始化新项目时，Roo 执行 /init 以分析代码库结构并创建全面的文档。
  • 当部署应用程序时，Roo 检索针对项目基础设施特定的标准部署指令。
  • 当实现功能时，Roo 通过自定义命令访问团队商定的模式和最佳实践。
  • 当设置开发环境时，Roo 一致地遵循项目特定的设置指令。
  • 当执行代码审查时，Roo 使用定义为命令的标准审查清单。

使用示例​

执行内置初始化命令：

<run_slash_command>
<command>init</command>
</run_slash_command>

运行带参数的自定义部署命令：

<run_slash_command>
<command>deploy</command>
<args>使用零停机策略部署到生产环境</args>
</run_slash_command>

执行带特定焦点的测试命令：

<run_slash_command>
<command>test</command>
<args>专注于身份验证模块的集成测试</args>
</run_slash_command>

运行项目特定的构建命令：

<run_slash_command>
<command>build</command>
<args>为生产优化并包含源映射</args>
</run_slash_command>

访问团队编码标准：

<run_slash_command>
<command>standards</command>
<args>TypeScript 和 React 最佳实践</args>
</run_slash_command>

最佳实践​

命令设计​

  1. 清晰命名：使用描述性、面向操作的名称
  2. 全面指令：包含所有必要步骤
  3. 参数灵活性：设计命令以支持或不支持参数
  4. 元数据使用：始终包含描述和参数提示
  5. 版本控制：提交项目命令以确保团队一致性

组织策略​

  1. 分类：使用前缀对相关命令分组（例如，test-unit, test-integration）
  2. 文档：在命令目录中维护 README
  3. 模板：为常见模式创建模板命令
  4. 覆盖：使用项目级别自定义全局命令
  5. 维护：定期审查和更新命令内容

团队协作​

  1. 标准化：在全局目录中定义团队范围的命令
  2. 项目特定：使用项目级别覆盖进行自定义
  3. 文档：记录可用命令及其用法
  4. 审查流程：在代码审查中包含命令更改
  5. 培训：在团队成员间共享命令知识

故障排除​

常见问题​

功能未启用：

  • 错误："运行斜杠命令是一个实验性功能，必须在设置中启用"
  • 解决方案：在实验性设置中启用"运行斜杠命令"

命令未找到：

  • 错误："命令'X'未找到。可用命令：Y, Z"
  • 解决方案：检查命令名称拼写和可用命令列表

缺少参数：

  • 错误在连续错误计数器中跟踪
  • 解决方案：提供必需的 command 参数

调试命令​

  1. 验证文件位置：确保 .md 文件在正确目录中
  2. 检查文件名：命令名必须与不带扩展名的文件名匹配
  3. 验证 Frontmatter：确保 YAML frontmatter 格式正确
  4. 测试解析：尝试在不同级别使用相同命令名以测试优先级
  5. 审查内容：确保命令内容是格式正确的 markdown