自定义模式

itBuilder允许您创建自定义模式来定制Roo的行为以适应特定任务或工作流程。自定义模式可以是全局的(在所有项目中可用)或项目特定的(在单个项目中定义)。

高效工作流的粘性模型

每个模式(包括自定义模式)都具备粘性模型功能。这意味着itBuilder会自动记住并选择您上次在特定模式下使用的模型。这使您可以为不同任务分配不同的首选模型，而无需在切换模式时不断重新配置。

---

为什么使用自定义模式?

• 专业化: 创建针对特定任务优化的模式，如"文档编写者"、"测试工程师"或"重构专家"
• 安全性: 限制模式对敏感文件或命令的访问。例如，"审查模式"可以限制为只读操作
• 实验性: 安全地尝试不同的提示和配置，而不会影响其他模式
• 团队协作: 与团队共享自定义模式以标准化工作流程

itBuilder创建和管理自定义模式的界面

---

自定义模式包含哪些内容?

自定义模式由几个关键属性定义。理解这些概念将帮助您有效地定制Roo的行为。

UI字段/YAML属性	概念描述
Slug (slug)	模式的唯一内部标识符。itBuilder使用它来引用模式，特别是用于关联通过文件/目录的模式特定指令
名称 (name)	在itBuilder用户界面中显示的显示名称。这应该是人类可读且描述性的
描述 (description)	在模式选择器UI中显示的简短、用户友好的摘要 - 此文本出现在重新设计的模式选择器中模式名称下方，为用户提供对模式功能的快速理解 - 保持简洁并专注于模式为用户提供的功能
角色定义 (roleDefinition)	定义模式的核心身份和专业领域。此文本放置在系统提示的开头 - 其主要功能是定义当此模式激活时Roo的个性和行为 - 随着description字段的引入，roleDefinition应提供模式身份的详细描述，而description字段处理UI的简短摘要 - whenToUse属性现在在自动上下文(如任务编排)中优先用于摘要
可用工具 (groups)	定义模式可以使用的允许工具集和文件访问权限 - 在UI中，这对应于选择模式可以使用的通用工具类别(如读取文件、编辑文件、浏览或执行命令) - UI在每个模式下的"允许文件"部分显示哪些文件可以编辑 - "edit"组的文件类型限制通常通过手动YAML/JSON配置或要求Roo设置来管理，如groups的属性详情中所述
何时使用 (可选) (whenToUse)	(可选)为Roo的自动决策提供指导，特别是模式选择和任务编排 - 此文本由Roo使用，特别是🪃 Orchestrator模式用于编排任务(例如通过new_task工具) - 它还帮助Roo决定在切换模式(例如通过switch_mode工具)时哪种模式合适 - 此字段不显示在模式选择器UI中 - 这是由description字段处理的
自定义指令 (可选) (customInstructions)	模式的特定行为准则或规则 - 这些指令添加到系统提示的末尾，以在roleDefinition之外进一步优化Roo的行为 - 可以直接在配置中提供或通过单独的指令文件提供

---

导入/导出模式

轻松共享、备份和模板化您的自定义模式。此功能允许您将任何模式及其关联规则导出为单个可移植的YAML文件，可以导入到任何项目中。

主要功能

• 可共享的设置: 将模式及其规则打包到一个文件中，轻松与团队共享
• 轻松备份: 保存您的自定义模式配置，确保永不丢失
• 项目模板: 为不同类型的项目创建标准化的模式模板
• 简单迁移: 轻松在全局设置和特定项目之间移动模式

---

使用案例

之前: 为每个新项目或团队成员手动重新创建自定义模式并复制.roo/rules-{slug}/文件夹。这既繁琐又容易出错。

使用此功能: 单击一次即可将模式及其所有规则导出到YAML文件。再单击一次即可导入，自动设置所有内容。

工作原理

导入/导出功能从模式视图管理。

导出模式

1. 导航到模式视图
2. 选择要导出的模式
3. 单击导出模式按钮(下载图标)
4. 选择保存.yaml文件的位置

Roo将模式的配置和项目.roo/rules-{slug}/目录中找到的任何规则打包到YAML文件中。

导入模式

1. 在模式视图中单击导入模式按钮(上传图标)
2. 选择模式的YAML文件
3. 在出现的对话框中选择导入级别:
   • 项目: 模式仅在当前工作区可用。它被添加到.roomodes文件中，其规则保存到项目内的.roo/rules-{slug}/目录
   • 全局: 模式在所有项目中可用。它被添加到您的全局设置中，其规则存储在系统的全局Roo配置目录中(例如~/.roo/rules-{slug}/)

---

导出的YAML文件格式:

customModes:
  - slug: "my-custom-mode"
    name: "我的自定义模式"
    roleDefinition: "你是一个乐于助人的助手"
    groups: ["read", "edit"]
    rulesFiles:
      - relativePath: "rules-my-custom-mode/rules.md"
        content: "这是我的自定义模式的规则"

---

常见问题

"如果我导入一个与现有模式'slug'相同的模式会怎样?"

• 现有模式将被导入文件中的配置覆盖

"全局导入和项目导入的主要区别是什么?"

• 全局模式在所有VS Code项目中可用。项目模式特定于导入它们的工作区，并存储在项目根目录的.roomodes文件中

"我可以导出内置模式如Code或Architect吗?"

• 可以。如果您自定义了内置模式(例如更改其指令)，您可以导出它以保存您的自定义设置

"如果我在全局级别导入带有规则的模式会怎样?"

• 规则仍然保留。它们存储在用户主目录中的全局rules-{slug}文件夹中(例如~/.roo/rules-my-custom-mode/)，而不是项目特定的.roo文件夹

---

创建和配置自定义模式的方法

您可以通过几种方式创建和配置自定义模式:

1. 询问Roo!(推荐)

您可以通过要求itBuilder为您快速创建一个基本的自定义模式。例如:

创建一个名为"文档编写者"的新模式。它应该只能读取文件和编写Markdown文件。

itBuilder将引导您完成流程，提示输入自定义模式包含哪些内容?表中描述的属性所需的信息。Roo将使用首选的YAML格式创建模式。如需稍后进行微调或特定调整，您可以使用Prompts选项卡或手动配置。

2. 使用Prompts选项卡

1. 打开Prompts选项卡: 点击itBuilder顶部菜单栏中的图标
2. 创建新模式: 点击Modes标题右侧的按钮
3. 填写字段:

自定义模式创建界面，显示名称、slug、描述、保存位置、角色定义、可用工具、自定义指令等字段

界面提供Name、Slug、Description、Save Location、Role Definition、When to Use (optional)、Available Tools和Custom Instructions字段。填写这些后，点击"Create Mode"按钮。itBuilder将以YAML格式保存新模式。

有关每个属性的概念解释，请参考自定义模式包含哪些内容?表。可以通过要求Roo或通过手动YAML/JSON配置添加"edit"工具组的文件类型限制。

3. 手动配置(YAML & JSON)

您可以直接编辑配置文件来创建或修改自定义模式。此方法提供对所有属性的最大控制。itBuilder现在支持YAML(首选)和JSON格式。

• 全局模式: 编辑custom_modes.yaml(首选)或custom_modes.json文件。通过Prompts Tab > (设置菜单图标，位于"Global Prompts"旁边) > "Edit Global Modes"访问
• 项目模式: 编辑项目根目录中的.roomodes文件(可以是YAML或JSON)。通过Prompts Tab > (设置菜单图标，位于"Project Prompts"旁边) > "Edit Project Modes"访问

这些文件定义了一个自定义模式的数组/列表。

YAML示例(custom_modes.yaml或.roomodes):

customModes:
  - slug: docs-writer
    name: 📝 文档编写者
    description: 专门用于编写和编辑技术文档的模式
    roleDefinition: 你是一位专注于清晰文档的技术写作者
    whenToUse: 在编写和编辑文档时使用此模式
    customInstructions: 专注于文档的清晰性和完整性
    groups:
      - read
      - - edit # 此组允许编辑特定文件
        - fileRegex: \.(md|mdx)$ # Markdown文件的正则表达式
          description: 仅限Markdown文件
      - browser
  - slug: another-mode
    name: 其他模式
    # ... 其他属性

JSON替代方案(custom_modes.json或.roomodes):

{
  "customModes": [
    {
      "slug": "docs-writer",
      "name": "📝 文档编写者",
      "description": "专门用于编写和编辑技术文档的模式",
      "roleDefinition": "你是一位专注于清晰文档的技术写作者",
      "whenToUse": "在编写和编辑文档时使用此模式",
      "customInstructions": "专注于文档的清晰性和完整性",
      "groups": [
        "read",
        ["edit", { "fileRegex": "\\.(md|mdx)$", "description": "仅限Markdown文件" }],
        "browser"
      ]
    },
    {
      "slug": "another-mode",
      "name": "其他模式"
    }
  ]
}

YAML/JSON属性详情

slug

• 目的: 模式的唯一标识符
• 格式: 使用小写字母、数字和连字符
• 用法: 内部使用，并用于模式特定规则的文件/目录名称(例如.roo/rules-{slug}/)
• 建议: 保持简短且描述性
• YAML示例: slug: docs-writer
• JSON示例: "slug": "docs-writer"

name

• 目的: 在itBuilder UI中显示的显示名称
• 格式: 可以包含空格和适当的大小写
• YAML示例: name: 📝 文档编写者
• JSON示例: "name": "文档编写者"

description

• 目的: 在模式选择器UI中显示在模式名称下方的简短、用户友好的摘要
• 格式: 保持简洁并专注于模式为用户提供的功能
• UI显示: 此文本出现在重新设计的模式选择器中，为用户提供对模式功能的快速理解
• YAML示例: description: 专门用于编写和编辑技术文档的模式
• JSON示例: "description": "专门用于编写和编辑技术文档的模式"

roleDefinition

• 目的: 详细描述模式的角色、专业领域和个性
• 位置: 当模式激活时，此文本放置在系统提示的开头
• 更新角色: 随着description字段的引入，roleDefinition应提供模式身份的详细描述，而description字段处理UI的简短摘要。whenToUse属性现在在自动上下文中优先用于摘要
• YAML示例(多行):

  roleDefinition: >-
    你是一位测试工程师，擅长:
    - 编写全面的测试套件
    - 测试驱动开发

• JSON示例: "roleDefinition": "你是一位专注于清晰文档的技术写作者"

groups

• 目的: 数组/列表定义模式可以访问哪些工具组以及任何文件限制
• 可用工具组(字符串): "read", "edit", "browser", "command", "mcp"
• "edit"组的文件限制:
  • 要应用文件限制，"edit"条目变为一个列表(YAML)或数组(JSON)，其中第一个元素是"edit"，第二个是定义限制的映射/对象
  • fileRegex: 控制模式可以编辑哪些文件的正则表达式字符串
    • 在YAML中，通常对正则表达式特殊字符使用单反斜杠(例如\.md$)
    • 在JSON中，反斜杠必须双转义(例如\\.md$)
  • description: 描述限制的可选字符串
  • 对于更复杂的模式，请参阅理解自定义模式中的正则表达式
• YAML示例:

  groups:
    - read
    - - edit # 带限制的"edit"工具开始
      - fileRegex: \.(js|ts)$ # JS/TS文件的限制映射
        description: 仅限JS/TS文件
    - command

• JSON示例:

  "groups": [
    "read",
    ["edit", { "fileRegex": "\\.(js|ts)$", "description": "仅限JS/TS文件" }],
    "command"
  ]

whenToUse

• 目的: (可选)为Roo的自动决策提供指导，特别是模式选择和任务编排
• 格式: 描述此模式的理想场景或任务类型的字符串
• 用法: 此字段由Roo用于自动决策，不显示在模式选择器UI中 - 这是由description字段处理的。如果填写，Roo使用此描述进行编排和模式切换；否则使用roleDefinition的第一句话
• YAML示例: whenToUse: 此模式最适合重构Python代码
• JSON示例: "whenToUse": "此模式最适合重构Python代码"

customInstructions

• 目的: 包含模式附加行为准则的字符串
• 位置: 此文本添加到系统提示的末尾
• 补充: 可以通过通过文件/目录的模式特定指令补充
• YAML示例(多行):

  customInstructions: |-
    编写测试时:
    - 使用describe/it块
    - 包含有意义的描述

• JSON示例: "customInstructions": "专注于解释概念和提供示例"

YAML格式的优势

YAML现在是定义自定义模式的首选格式，相比JSON有几个优势:

• 可读性: YAML基于缩进的结构通常更易于人类阅读和理解复杂配置
• 注释: YAML允许注释(以#开头的行)，可以注释您的模式定义

  customModes:
    - slug: security-review
      name: 🔒 安全审查员
      # 此模式限制为只读访问
      roleDefinition: 你是一位审查代码漏洞的安全专家
      whenToUse: 用于安全审查和漏洞评估
      # 仅允许读取文件，无编辑权限
      groups:
        - read
        - browser

• 多行字符串: YAML为多行字符串(例如roleDefinition或customInstructions)提供了更清晰的语法，使用