Lzh on GitHub

自定义模式

创建自定义模式可以让你为特定的任务和工作流定制 Roo Code 的行为。这些模式可以是 全局的(适用于所有项目)或 项目特定的(仅限于单个项目),让你能够根据需求精准配置 AI 的行为。

创建自定义模式可以让你为特定的任务和工作流定制 Roo Code 的行为。这些模式可以是 全局的(适用于所有项目)或 项目特定的(仅限于单个项目),让你能够根据需求精准配置 AI 的行为。

模式吸附,高效工作流
每个模式(包括自定义模式)都具有 模型吸附 功能。这意味着 Roo Code 会自动记住并选择你用于特定模式的最后一个模型。这使你能够为不同任务分配不同的首选模型,而无需持续重新配置,因为当你切换模式时,Roo 也会随之切换模型。
发现社区模式
正在寻找即用型自定义模式?访问 Roo Code Marketplace,一键浏览和安装社区贡献的模式。市场提供了针对各种任务(如 React 开发、文档编写、测试等)的专用模式,所有这些都由 Roo Code 社区创建和共享。

为什么使用自定义模式?

使用自定义模式能带来许多好处:

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

所有模式(包括自定义模式)都具有 黏性模型 功能,这意味着 Roo Code 会记住你上次与某个模式一起使用的模型,让你无需持续重新配置,从而实现高效的工作流。

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

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

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

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

导入/导出模式

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

主要功能

  • 可分享的设置: 将模式及其规则打包到一个文件中,方便与你的团队分享。
  • 轻松备份: 保存你的自定义模式配置,这样你永远不会丢失它们。
  • 项目模板: 为不同类型的项目创建标准化的模式模板。
  • 简单迁移: 毫不费力地在你的全局设置和特定项目之间移动模式。
  • 灵活的 Slug 更改: 在导出的文件中更改模式 slug,无需手动编辑路径。

使用案例

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

有了此功能后: 单击即可将模式及其所有规则导出到 YAML 文件。再单击一下即可导入它,自动设置所有内容。你现在可以在导出的文件中更改 slug,导入过程会自动处理所有路径更新。

工作原理

导入/导出功能在 “模式” 视图中进行管理。

导出模式

  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: "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."

导入时更改 Slug

导入模式时,你可以在导入前在导出的 YAML 文件中更改 slug:

  1. 导出 slug 为 original-mode 的模式。
  2. 编辑 YAML 文件并将 slug 更改为 new-mode
  3. 导入文件 - 导入过程将:
  • 使用更新后的 slug 创建新模式。
  • 更新规则文件路径以匹配新的 slug。
导入期间的自动 slug 更改处理确保当你更改导出的文件中的模式 slug 时,规则文件路径会正确更新。

常见问题解答

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

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

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

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

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

  • 可以。如果你自定义了内置模式(例如,通过更改其指令),你可以导出它来保存你的自定义。

“如果我将一个带规则的模式导入到全局级别,会发生什么?”

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

“slug 更改功能是如何工作的?”

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

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

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

1. 询问 Roo!(推荐)

你可以通过让 Roo Code 为你创建来快速创建一个基本的自定义模式。例如:

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

Roo Code 将引导你完成此过程,提示你填写 “自定义模式中包含哪些内容?”表格中描述的属性所需的信息。Roo 将使用首选的 YAML 格式创建模式。为了以后的微调或进行特定调整,你可以使用“提示”选项卡或手动配置。

2. 使用“提示”选项卡

  1. 打开 “提示” 选项卡: 在 Roo Code 顶部菜单栏中点击 🤖 图标。
  2. 创建新模式: 点击 “模式” 标题右侧的 ➕ 按钮。
  3. 填写字段:
  • 自定义模式创建界面,显示了名称、slug、描述、保存位置、角色定义、可用工具、自定义指令的字段。
  • 该界面提供了名称Slug描述保存位置角色定义何时使用(可选)、可用工具自定义指令的字段。填写完这些内容后,点击“创建模式”按钮。Roo Code 将以 YAML 格式保存新模式。

参考“自定义模式中包含哪些内容?”表格以获取每个属性的概念性解释。可以要求 Roo 或通过手动 YAML/JSON 配置来为“编辑”工具组添加文件类型限制。

3. 手动配置 (YAML & JSON)

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

  • 全局模式: 编辑 custom_modes.yaml(首选)或 custom_modes.json 文件。通过“提示”选项卡 > ⚙️ (“全局提示”旁边的设置菜单图标)> “编辑全局模式” 来访问它。
  • 项目模式: 编辑项目根目录中的 .roomodes 文件(可以是 YAML 或 JSON)。通过“提示”选项卡 > ⚙️ (“项目提示”旁边的设置菜单图标)> “编辑项目模式”来访问它。

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

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:一个可选的字符串,描述限制。
    • 有关更复杂的模式,请参见“理解自定义模式中的正则表达式”。
  • YAML 示例:
    groups:
      - read
      - - edit  # First element of tuple
        - fileRegex: \.(js|ts)$  # Second element is the options object
          description: JS/TS files only
      - command
    
  • JSON 示例:
    "groups": [
      "read",
      ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }],
      "command"
    ]
    

whenToUse

  • 目的: (可选)为 Roo 的自动化决策提供指导,特别是针对模式选择和任务编排。
  • 格式: 一个字符串,描述此模式的理想场景或任务类型。
  • 用法: 此字段用于 Roo 的自动化决策,并且不会显示在模式选择器 UI 中——这由 description 字段处理。如果填充了此字段,Roo 将使用此描述进行编排和模式切换;否则,将使用 roleDefinition 的第一句话。
  • YAML 示例: whenToUse: This mode is best for refactoring Python code.
  • JSON 示例: "whenToUse": "This mode is best for refactoring Python code."

customInstructions

  • 目的: 一个包含模式附加行为准则的字符串。
  • 放置: 这段文字被添加到系统提示的末尾。
  • 补充: 可以通过“通过文件/目录提供的模式特定指令”进行补充。
  • YAML 示例(多行):
    customInstructions: |-
      When writing tests:
      - Use describe/it blocks
      - Include meaningful descriptions
    
  • JSON 示例: "customInstructions": "Focus on explaining concepts and providing examples."

YAML 格式的优势

YAML 现在是定义自定义模式的首选格式,因为它比 JSON 有几个优势:

  • 可读性: YAML 基于缩进的结构通常更易于人类阅读和理解复杂的配置。
  • 注释: YAML 允许使用注释(以 # 开头的行),从而可以对你的模式定义进行注释。
    customModes:
      - slug: security-review
        name: 🔒 Security Reviewer
        # This mode is restricted to read-only access
        roleDefinition: You are a security specialist reviewing code for vulnerabilities.
        whenToUse: Use for security reviews and vulnerability assessments.
        # Only allow reading files, no editing permissions
        groups:
          - read
          - browser
    
  • 多行字符串: YAML 为多行字符串(例如,用于 roleDefinitioncustomInstructions)提供了更简洁的语法,使用 |(字面量块)或 >(折叠块)。
    customModes:
      - slug: test-engineer
        name: 🧪 Test Engineer
        roleDefinition: >-
          You are a test engineer with expertise in:
          - Writing comprehensive test suites
          - Test-driven development
          - Integration testing
          - Performance testing
        customInstructions: |-
          When writing tests:
          - Use describe/it blocks
          - Include meaningful descriptions
          - Test edge cases
          - Ensure proper coverage
        # ... other properties
    
  • 更少的标点符号: 与 JSON 相比,YAML 通常需要更少的标点符号(如逗号和大括号),从而减少语法错误。
  • 编辑器支持: 大多数现代代码编辑器都为 YAML 文件提供出色的语法高亮和验证,进一步增强了可读性并减少了错误。

尽管 JSON 仍然得到完全支持并且不会被弃用,但通过 UI 或询问 Roo 创建的新模式将默认为 YAML。.roomodes 文件和全局配置文件都可以是 YAML 或 JSON 格式。

使用 YAML 的技巧

手动编辑 YAML 时,请记住以下几点:

  • 缩进是关键: YAML 使用缩进(空格,而不是制表符)来定义结构。不正确的缩进是错误最常见的来源。确保嵌套元素的一致间距。
  • 冒号用于键值对: 键后必须跟一个冒号和一个空格(例如,slug: my-mode)。
  • 连字符用于列表项: 列表项以一个连字符和一个空格开头(例如,- read)。
  • 验证你的 YAML: 如果你遇到问题,请使用在线 YAML 验证器或你编辑器的内置验证来检查语法错误。

迁移到 YAML 格式

  • 全局模式: 当 Roo Code 启动时,只有在以下条件下,才会自动将全局模式从 custom_modes.json 迁移到 custom_modes.yaml
    • Roo Code 启动。
    • custom_modes.json 文件存在。
    • custom_modes.yaml 文件尚不存在。迁移过程会读取现有的 JSON 文件,将其转换为 YAML 格式,创建一个新的 custom_modes.yaml 文件,并保留原始 JSON 文件(例如,通过重命名它)以供回滚。如果 custom_modes.yaml 已经存在,它将被使用,并且不会发生 custom_modes.json 的自动迁移。
  • 项目模式 (.roomodes):
    • 没有自动启动迁移: 与全局模式不同,项目特定的 .roomodes 文件在 Roo Code 启动时不会自动从 JSON 转换为 YAML。对于现有的 JSON .roomodes 文件,需要手动转换。
    • 格式检测: Roo Code 可以读取 YAML 或 JSON 格式的 .roomodes 文件。Roo Code 会首先尝试将 .roomodes 文件解析为 YAML 来自动检测格式。
    • UI 编辑时转换: 如果你通过 Roo Code UI(例如,通过“提示”选项卡)编辑项目特定的模式,并且现有的 .roomodes 文件是 JSON 格式,Roo Code 将以 YAML 格式保存更改。这实际上将文件转换为 YAML。原始的 JSON 内容将被 YAML 覆盖。
    • 手动转换: 如果你想在不进行 UI 编辑的情况下将现有的 .roomodes JSON 文件转换为 YAML,你需要手动进行。你可以:
      1. 打开你现有的 JSON .roomodes 文件。
      2. 将其内容转换为 YAML(你可以让 Roo 帮助完成此操作,或使用在线转换器)。
      3. 用新的 YAML 内容替换你的 .roomodes 文件的内容,或重命名旧文件(例如,.roomodes.json.bak)并将新内容保存到名为 .roomodes 的文件中。确保生成的 YAML 是有效的。
对于 .roomodes 文件的手动转换,你可以使用在线 JSON 到 YAML 转换器或让 Roo 帮助将特定的模式配置从 JSON 重新格式化为 YAML。在保存之前,务必验证你的 YAML。

通过文件/目录提供的模式特定指令

模式特定指令文件位置
你可以在工作区内使用专用文件或目录为自定义模式提供指令。这与仅使用 customInstructions 属性相比,可以更好地组织和版本控制。
  • 首选方法:目录 (.roo/rules-{mode-slug}/)
    .
    ├── .roo/
    │   └── rules-docs-writer/  # Example for mode slug "docs-writer"
    │       ├── 01-style-guide.md
    │       └── 02-formatting.txt
    └── ... (other project files)
    
  • 备用方法:单个文件 (.roorules-{mode-slug})
    .
    ├── .roorules-docs-writer  # Example for mode slug "docs-writer"
    └── ... (other project files)
    
  • 遗留备用:.clinerules-{mode-slug} 为了向后兼容,系统还会检查 .clinerules-{mode-slug} 文件作为附加备用,尽管不推荐新项目使用此方法。
如果目录方法存在且包含文件,则它优先。
  • 规则目录范围:
    • 全局模式: 规则存储在 ~/.roo/rules-{slug}/ 中(注意末尾的斜杠)。
    • 项目模式: 规则存储在 {workspace}/.roo/rules-{slug}/ 中(注意末尾的斜杠)。

除了 customInstructions 属性之外,你还可以通过工作区中的文件提供模式特定指令。这对于以下情况特别有用:

  • 将冗长或复杂的指令组织成多个可管理的文件。
  • 通过版本控制轻松管理指令。
  • 允许非技术团队成员修改指令而无需编辑 YAML/JSON。

Roo Code 有两种加载这些指令的方式,并且明确偏爱较新的基于目录的方法:

1. 首选方法:基于目录的指令 (.roo/rules-{mode-slug}/)

  • 结构: 在你的工作区根目录中创建一个名为 .roo/rules-{mode-slug}/ 的目录。将 {mode-slug} 替换为你的模式的 slug(例如,.roo/rules-docs-writer/)。
  • 内容: 将一个或多个包含指令的文件(例如,.md.txt)放入此目录中。你可以使用子目录进一步组织指令。在 .roo/rules-{mode-slug}/ 目录中的文件将按文件名(不区分大小写)的字母顺序递归读取和追加。
  • 加载: 在此目录结构中找到的所有指令文件都将加载并应用于指定的模式。系统文件(.DS_Store、.swp 等)和缓存文件会自动被排除。
  • 高级功能: 系统支持带有循环检测的符号链接,以实现高级文件组织。

2. 备用(向后兼容):基于文件的指令 (.roorules-{mode-slug})

  • 结构: 如果 .roo/rules-{mode-slug}/ 目录不存在或为空,Roo Code 将在你的工作区根目录中查找一个名为 .roorules-{mode-slug} 的单一文件(例如,.roorules-docs-writer)。
  • 加载: 如果找到,此单一文件的内容将作为模式的指令加载。

优先权:

  • 基于目录的方法 (.roo/rules-{mode-slug}/) 优先。如果此目录存在且包含文件,则对于该模式,任何相应的根级 .roorules-{mode-slug} 文件都将被忽略
  • 这确保了迁移到新目录结构的项目行为可预测,而使用单一文件方法的旧项目仍然兼容。

customInstructions 结合:

  • 从目录或备用文件加载的指令与模式配置中定义的 customInstructions 属性相结合。
  • 通常,来自文件/目录的内容会追加在来自 customInstructions 属性的内容之后。

配置优先权

模式配置按以下顺序应用:

  1. 项目级模式配置(来自 .roomodes - YAML 或 JSON)
  2. 全局模式配置(来自 custom_modes.yaml,如果未找到 YAML 则来自 custom_modes.json
  3. 默认模式配置

重要提示:.roomodes 和全局设置中存在具有相同 slug 的模式时,.roomodes 版本将完全覆盖全局版本。这适用于所有属性,而不仅仅是部分。例如,如果你有一个全局的“code”模式和一个项目特定的 .roomodes 中的“code”模式,当你在该项目中工作时,将使用项目版本,并且全局版本的所有属性都将被忽略。

你可以通过在你的全局或项目特定配置中包含一个具有相同 slug 的模式来覆盖任何默认模式。

关于指令文件的注意: 在从文件系统加载模式特定指令时,目录 .roo/rules-{mode-slug}/ 优先于在工作区根目录中找到的单一文件 .roorules-{mode-slug}

覆盖默认模式

你可以用自定义版本覆盖 Roo Code 的内置模式(如 💻 Code、🪲 Debug、❓ Ask、🏗️ Architect、🪃 Orchestrator)。这可以通过创建一个与默认模式具有相同 slug 的自定义模式来完成(例如,codedebug)。

全局覆盖模式

要跨所有项目自定义默认模式:

  1. 打开“提示”选项卡: 点击 🤖 图标。
  2. 访问设置菜单: 点击“全局提示”旁边的 ⚙️ 图标。
  3. 编辑全局模式: 选择“编辑全局模式”以编辑 custom_modes.yaml(或 custom_modes.json)。
  4. 添加你的覆盖:

YAML 示例:

customModes:
  - slug: code # Matches the default 'code' mode slug
    name: 💻 Code (Global Override) # Custom display name
    roleDefinition: You are a software engineer with global-specific constraints.
    whenToUse: This globally overridden code mode is for JS/TS tasks.
    customInstructions: Focus on project-specific JS/TS development.
    groups:
      - read
      - - edit
        - fileRegex: \.(js|ts)$
          description: JS/TS files only

JSON 替代方案:

{
  "customModes": [{
    "slug": "code",
    "name": "💻 Code (Global Override)",
    "roleDefinition": "You are a software engineer with global-specific constraints",
    "whenToUse": "This globally overridden code mode is for JS/TS tasks.",
    "customInstructions": "Focus on project-specific JS/TS development",
    "groups": [
      "read",
      ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }]
    ]
  }]
}

这个例子用一个仅限于 JavaScript 和 TypeScript 文件的版本替换了默认的 💻 Code 模式。

项目特定的模式覆盖

要仅为一个项目覆盖默认模式:

  1. 打开“提示”选项卡: 点击 🤖 图标。
  2. 访问设置菜单: 点击“项目提示”旁边的 ⚙️ 图标。
  3. 编辑项目模式: 选择“编辑项目模式”以编辑 .roomodes 文件(YAML 或 JSON)。
  4. 添加你的覆盖:

YAML 示例:

customModes:
  - slug: code # Matches the default 'code' mode slug
    name: 💻 Code (Project-Specific) # Custom display name
    roleDefinition: You are a software engineer with project-specific constraints for this project.
    whenToUse: This project-specific code mode is for Python tasks within this project.
    customInstructions: Adhere to PEP8 and use type hints.
    groups:
      - read
      - - edit
        - fileRegex: \.py$
          description: Python files only
      - command

JSON 替代方案:

{
  "customModes": [{
    "slug": "code",
    "name": "💻 Code (Project-Specific)",
    "roleDefinition": "You are a software engineer with project-specific constraints for this project.",
    "whenToUse": "This project-specific code mode is for Python tasks within this project.",
    "customInstructions": "Adhere to PEP8 and use type hints.",
    "groups": [
      "read",
      ["edit", { "fileRegex": "\\.py$", "description": "Python files only" }],
      "command"
    ]
  }]
}

项目特定的覆盖优先于全局覆盖。

覆盖默认模式的常见用例

  • 限制文件访问: 将模式限制为特定文件类型。
  • 特化行为: 为你的技术栈定制专长。
  • 添加自定义指令: 集成项目标准。
  • 更改可用工具: 删除工具以防止不必要的操作。
覆盖默认模式时,请仔细测试。在进行重大更改之前,考虑备份配置。

理解自定义模式中的正则表达式

正则表达式 (fileRegex) 提供对文件编辑权限的细粒度控制。

让 Roo 帮你构建正则表达式模式
与其手动编写复杂的正则表达式,不如询问 Roo:
Create a regex pattern that matches JavaScript files but excludes test files
Roo 将生成模式。记住要根据 YAML(通常是单个反斜杠)或 JSON(双反斜杠)进行调整。

当你指定 fileRegex 时,你正在创建一个文件路径必须匹配的模式。

fileRegex 的重要规则:

  • JSON 中的转义: 在 JSON 字符串中,反斜杠(\)必须双重转义(例如,\\.md$)。
  • YAML 中的转义: 在无引号或单引号的 YAML 字符串中,通常单个反斜杠就足以用于正则表达式特殊字符(例如,\.md$)。然而,YAML 中带引号的正则表达式模式可能需要类似于 JSON 的双重转义。
  • 路径匹配: 模式匹配的是从工作区根目录开始的完整相对文件路径(例如,src/components/button.js)。
  • 大小写敏感: 正则表达式模式默认是大小写敏感的。
  • 验证: 无效的正则表达式模式将因“无效的正则表达式模式”错误消息而被拒绝。

常见模式示例: 在下表中,“模式(概念性 / 类似 YAML)” 列显示了它们在 YAML 中出现的模式。对于 JSON,请记住双重转义反斜杠。

模式(概念性 / 类似 YAML)JSON fileRegex匹配不匹配
\.md$"\\.md$"readme.md, docs/guide.mdscript.js, readme.md.bak
^src/.*"^src/.*"src/app.js, src/components/button.tsxlib/utils.js, test/src/mock.js
`.(cssscss)$``"\.(cssscss)$"`
docs/.*\.md$"docs/.*\\.md$"docs/guide.md, docs/api/reference.mdguide.md, src/docs/notes.md
^(?!.*(test|spec))\.(js |ts)$"^(?!.*(test|spec))\\.(js | ts)$"app.js, utils.tsapp.test.js, utils.spec.js, app.jsx

关键的正则表达式构建块:

  • \.:匹配一个字面量点。(YAML:\.,JSON:\\.
  • $:匹配字符串的结尾。
  • ^:匹配字符串的开头。
  • .*:匹配任意字符(除换行符外)零次或多次。
  • (a|b):匹配“a”或“b”。(例如,\.(js|ts)$
  • (?!...):负向先行断言。

测试你的模式:

  • 在示例文件路径上进行测试。在线正则表达式测试器很有帮助。
  • 记住 JSON 与 YAML 的转义规则。
  • 从简单开始,逐步构建复杂性。

错误处理

当模式尝试编辑一个与其 fileRegex 模式不匹配的文件时,你将看到一个 FileRestrictionError,其中包括:

  • 模式名称
  • 允许的文件模式
  • 描述(如果提供)
  • 尝试的文件路径
  • 被阻止的工具

此信息可帮助你了解操作被阻止的原因以及当前模式允许的文件类型。

附加功能

内置模式自定义

当导出内置模式(如 Code、Architect、Ask、Debug)时,你所做的任何自定义都包含在导出中。这使你能够与他人分享你个性化版本的内置模式。

模式删除和规则

当通过 UI 删除模式时,Roo Code 将提示你是否删除关联的规则文件夹,并在删除前显示确切的路径。这有助于防止意外丢失自定义指令。

全局规则目录

除了模式特定的规则目录之外,还有一个通用的 .roo/rules/ 目录(没有模式后缀),可用于所有模式共享的规则。

故障排除

常见问题:

  • 模式未出现: 创建或导入模式后,你可能需要重新加载 VS Code 窗口,它才会出现在模式选择器中。
  • 无效的正则表达式模式: 如果你的 fileRegex 模式无效,你将收到错误消息。在应用它们之前,使用在线正则表达式测试器测试你的模式。
  • 优先权混淆: 记住项目模式会完全覆盖具有相同 slug 的全局模式 - 不会合并任何属性。