自定义模式

Roo Code 允许您创建自定义模式，以定制 Roo 的行为，满足特定任务或工作流的需求。自定义模式可以是全局的（在所有项目中可用）或项目特定的（在单个项目内定义）。

高效工作流的粘性模型

每个模式（包括自定义模式）都具备粘性模型功能。这意味着 Roo Code 会自动记住并选择您在特定模式中最后使用的模型。这允许您为不同任务分配不同的首选模型，而无需频繁重新配置，因为当您切换模式时，Roo 会自动在模型间切换。

探索社区模式

寻找现成的自定义模式？访问 Roo Code 市场浏览和一键安装社区贡献的模式。市场提供针对各种任务的专业模式，如 React 开发、文档编写、测试等——均由 Roo Code 社区创建和分享。

为什么使用自定义模式？

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

Roo Code 的自定义模式创建和管理界面。

自定义模式包含什么？

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

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

导入/导出模式

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

主要功能

可共享设置：将模式和规则打包到一个文件中，便于与团队共享。
简单备份：保存自定义模式配置，永不丢失。
项目模板：为不同类型的项目创建标准化模式模板。
简单迁移：在全局设置和特定项目之间轻松移动模式。
灵活的 Slug 更改：在导出文件中更改模式 slugs，无需手动编辑路径。

用例

之前：手动重新创建自定义模式并复制每个新项目或团队成员的 .roo/rules-{slug}/ 文件夹。更改 slugs 需要手动更新 YAML 文件中的路径。

使用此功能：单击导出模式和所有规则到 YAML 文件。另一键导入，自动设置一切。现在您可以在导出文件中更改 slug，导入过程会自动处理所有路径更新。

工作原理

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

导出模式

导航到模式视图。
选择要导出的模式。
点击导出模式按钮（下载图标）。
选择保存 .yaml 文件的位置。

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

导入模式

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

注意：导出带规则的模式时，所有文件路径都标准化为使用正斜杠以实现跨平台兼容性。这确保模式可以在使用不同操作系统的团队成员之间共享。

导出 YAML 文件格式：

customModes:
  - slug: "my-custom-mode"
    name: "My Custom Mode"
    roleDefinition: "You are a helpful assistant."
    groups: ["read", "edit"]
    rulesFiles:
      - relativePath: "rules-my-custom-mode/rules.md"
        content: "These are the rules for my custom mode."

导入时更改 Slugs

导入模式时，您可以在导入前在导出的 YAML 文件中更改 slug：

导出模式，slug 为 original-mode
编辑 YAML 文件，将 slug 更改为 new-mode
导入文件 - 导入过程将：
- 使用更新的 slug 创建新模式
- 更新规则文件路径以匹配新 slug

注意：导入时的自动 slug 更改处理确保当您在导出文件中更改模式 slug 时，规则文件路径会正确更新。

常见问题

“如果我导入一个 slug 与现有模式相同的模式会发生什么？”

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

“全局导入和项目导入的主要区别是什么？”

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

“我可以导出内置模式如 Code 或 Architect 吗？”

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

“如果我在全局级别导入带规则的模式会怎样？”

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

“slug 更改功能如何工作？”

当您在导入前更改导出 YAML 文件中的 slug 时，导入过程会更新规则文件路径以匹配新 slug。这确保模式以其新身份正确工作。

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

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

要配置模式，打开 Roo Code 面板，点击聊天框下方的模式菜单，然后点击。然后使用“编辑全局模式”打开 settings/custom_modes.yaml，或使用“编辑项目模式 (.roomodes)”打开工作区级配置。

1. 询问 Roo！（推荐）

您可以通过请求 Roo Code 创建基本自定义模式来快速完成。例如：

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

Roo Code 将引导您完成此过程，提示您为 What's Included in a Custom Mode? 表中描述的属性提供必要信息。Roo 将使用首选的 YAML 格式创建模式。如需以后进行微调或进行特定调整，您可以使用模式页面或手动配置。

2. 使用模式页面

打开模式页面：打开 Roo Code 面板，点击聊天框下方的模式菜单，然后点击。
创建新模式：点击模式标题右侧的按钮。
填写字段：

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

界面为 Name、Slug、Description、Save Location、Role Definition、When to Use (optional)、Available Tools 和 Custom Instructions 提供字段。填写后，点击“创建模式”按钮。Roo Code 将以 YAML 格式保存新模式。

参考 What's Included in a Custom Mode? 表以获取每个属性的概念解释。编辑工具组的文件类型限制可以通过询问 Roo 或通过手动 YAML/JSON 配置添加。

3. 手动配置（YAML 和 JSON）

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

全局模式：编辑 custom_modes.yaml（首选）或 custom_modes.json 文件。从模式页面点击“编辑全局模式”打开 settings/custom_modes.yaml。
项目模式：编辑项目根目录中的 .roomodes 文件（可以是 YAML 或 JSON）。从模式页面点击“编辑项目模式 (.roomodes)”打开或创建工作区文件。

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

YAML 示例（custom_modes.yaml 或 .roomodes）：

customModes:
  - slug: docs-writer
    name: 📝 Documentation Writer
    description: A specialized mode for writing and editing technical documentation.
    roleDefinition: You are a technical writer specializing in clear documentation.
    whenToUse: Use this mode for writing and editing documentation.
    customInstructions: Focus on clarity and completeness in documentation.
    groups:
      - read
      - - edit  # First element of tuple
        - fileRegex: \.(md|mdx)$  # Second element is the options object
          description: Markdown files only
      - browser
  - slug: another-mode
    name: Another Mode
    # ... other properties

JSON 替代方案（custom_modes.json 或 .roomodes）：

{
  "customModes": [
    {
      "slug": "docs-writer",
      "name": "📝 Documentation Writer",
      "description": "A specialized mode for writing and editing technical documentation.",
      "roleDefinition": "You are a technical writer specializing in clear documentation.",
      "whenToUse": "Use this mode for writing and editing documentation.",
      "customInstructions": "Focus on clarity and completeness in documentation.",
      "groups": [
        "read",
        ["edit", { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" }],
        "browser"
      ]
    },
    {
      "slug": "another-mode",
      "name": "Another Mode"
    }
  ]
}

YAML/JSON 属性详情

`slug`

用途：模式的唯一标识符。
格式：必须匹配模式 /^[a-zA-Z0-9-]+$/（仅字母、数字和连字符）。
用途：在内部使用，并在模式特定规则的文件/目录名中使用（例如 .roo/rules-{slug}/）。
建议：保持简短且描述性。
注意：source 属性由系统自动添加，不应手动设置。
YAML 示例：slug: docs-writer
JSON 示例："slug": "docs-writer"

`name`

用途：在 Roo Code UI 中显示的显示名称。
格式：可以包含空格和适当的大小写。
YAML 示例：name: 📝 Documentation Writer
JSON 示例："name": "Documentation Writer"

`description`

用途：在模式选择器 UI 中显示在模式名称下方的简短、用户友好的摘要。
格式：保持简洁并专注于模式对用户的作用。
UI 显示：此文本显示在重新设计的模式选择器中，为用户提供模式功能的快速理解。
YAML 示例：description: A specialized mode for writing and editing technical documentation.
JSON 示例："description": "A specialized mode for writing and editing technical documentation."

`roleDefinition`

用途：模式角色、专业知识和个性的详细描述。
位置：此文本在模式激活时放置在系统提示的开头。
更新角色：随着 description 字段的引入，roleDefinition 应提供模式身份的详细描述，而 description 字段处理 UI 的简短摘要。whenToUse 属性现在在自动化上下文中优先用于摘要。

YAML 示例（多行）：

roleDefinition: >-
  You are a test engineer with expertise in:
  - Writing comprehensive test suites
  - Test-driven development

JSON 示例："roleDefinition": "You are a technical writer specializing in clear documentation."

`groups`

用途：定义模式可以访问的工具组和任何文件限制的数组/列表。
可用工具组（字符串）："read"、"edit"、"browser"、"command"、"mcp"。
结构：groups 属性使用特定结构：
- 简单字符串表示无限制访问："edit"
- 元组（两元素数组）表示受限访问：["edit", { fileRegex: "pattern", description: "optional" }]
“编辑”组的文件限制：
- 要应用文件限制，“编辑”条目变成元组（YAML 列表或 JSON 数组），其中第一个元素是 "edit"，第二个是定义限制的映射/对象。
- fileRegex：控制模式可以编辑哪些文件的正则表达式字符串。
  - 在 YAML 中，通常对正则表达式特殊字符使用单反斜杠（例如 \.md$）。
  - 在 JSON 中，反斜杠必须双转义（例如 \\.md$）。
- description：描述限制的可选字符串。
- 对于更复杂的模式，请参阅 [Understanding Regex in Custom Modes](#understanding-regex-in-custom

为什么使用自定义模式？​

自定义模式包含什么？​

导入/导出模式​

主要功能​

用例​

工作原理​

导出模式​

导入模式​

导出 YAML 文件格式：​

导入时更改 Slugs​

常见问题​

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

1. 询问 Roo！（推荐）​

2. 使用模式页面​

3. 手动配置（YAML 和 JSON）​

YAML/JSON 属性详情​

slug​

name​

description​

roleDefinition​

groups​