自定义模式

自定义模式将专业角色、可用工具与项目约定保存为可复用配置。全局模式适用于所有项目；项目模式仅适用于当前工作区。可以创建只编辑文档的写作助手、只读代码审查助手，或使用特定 MCP 服务的任务助手。

为什么使用自定义模式

自定义模式用于缩小工具范围、固定团队规范和减少重复提示。为模式设置清晰的名称与描述，让助手及协作者理解其边界。本地模式不绑定独立供应商，所有模式使用当前唯一供应商配置。

模式包含什么

• slug：唯一标识，使用字母、数字和连字符；规则目录与引用依赖该标识。
• name：界面显示名称；description：简短用途说明。
• roleDefinition：角色专业能力、职责与行为。
• whenToUse：说明何时应该选择或委派到此模式。
• groups：工具组以及编辑文件限制。
• customInstructions：针对角色的额外要求。
• allowedMcpServers：本地模式级服务器限制，详见下方权限说明。

导入与导出

在模式页面选择导出，将单个模式保存为 YAML；使用导入读取配置并选择全局或项目范围。导入前检查角色、工具、命令和 MCP 权限，不要盲目信任共享配置。如果标识冲突，检查覆盖提示或更换 slug；重命名后同步规则目录。

YAML 示例

customModes:
  - slug: docs-reviewer
    name: 文档审查
    description: 审查并更新项目文档
    roleDefinition: 你是一名技术文档审查员，优先核查事实与链接。
    whenToUse: 需要审查 Markdown 文档时使用。
    groups:
      - read
      - [edit, {fileRegex: '\.(md|mdx)$', description: '只编辑文档'}]
      - mcp
    allowedMcpServers: [docs-search]
    customInstructions: 不修改业务代码，完成后报告验证结果。

创建与配置方式

请求助手创建

描述角色、任务、允许编辑的文件和工具范围，让助手生成配置；保存前审查每个字段，不授予任务不需要的权限。

使用模式页面

打开模式页面，添加模式、选择保存范围，填写角色和自定义指令，勾选工具组。启用 MCP 工具组后可配置允许的服务器。

手动配置

通过界面打开全局模式配置，或在项目的 .roomodes（历史兼容文件名） 中维护项目模式。优先使用 YAML；已有 JSON 配置按扩展兼容机制加载。修改前备份，不要同时维护相互矛盾的配置。

字段与权限

fileRegex 是文件路径的正则匹配限制，YAML 单引号可减少反斜杠转义；JSON 中需要双重转义。正则只限制 edit 工具，不会自动限制终端命令或外部服务器。验证表达式能同时允许预期文件并拒绝敏感文件。

模式级 MCP 权限

必须首先启用 mcp 工具组。allowedMcpServers 未设置表示不额外限制服务器；空数组表示禁止所有服务器；非空数组仅允许列出的服务器名。服务器还必须已连接且未禁用，工具也必须启用。不在白名单中的服务器不会因为自动批准而获得访问权限。保留未连接的已选服务器可表达将来的权限，界面会提示未连接状态。

模式专属规则

在 .aigo123/rules-docs-reviewer/ 中保存规则，目录名后缀必须等于 slug。全局对应目录位于用户目录下 .aigo123/rules-docs-reviewer/。通用规则放在 .aigo123/rules/。详见 规则指南。

配置优先级

项目模式覆盖同 slug 的全局模式，全局自定义配置可覆盖同 slug 的内置模式。覆盖是整个模式替换，不是逐字段合并，因此要保留完整角色、工具组与所需限制。

覆盖内置模式

使用内置 slug 定义完整配置，可改变角色与权限。先确认不会破坏任务委派流程；团队共享时建议使用清晰的新 slug，减少与默认行为混淆。

文件正则示例

\.md$              # Markdown 文件
\.(ts|tsx)$        # TypeScript 文件
^docs/.*\.md$      # docs 目录下的 Markdown

实际路径匹配方式以扩展为准，配置后用允许与禁止的文件分别验证；不要把文件正则当作终端沙箱。

删除模式与规则

删除模式时，界面会提示是否同时删除关联规则目录。确认前核对路径并备份；选择删除规则会直接操作磁盘，不能靠丢弃普通设置恢复。不要误删被其他流程使用的文件。

全局规则

共享约定放在用户目录 .aigo123/rules/，模式专项要求放在 rules-{slug}/。规则管理页面的创建、打开和删除直接操作文件，不属于可撤销的普通设置缓存。

故障排查

• 模式未出现：确认配置范围与格式，必要时重新加载 VS Code 窗口。
• 不能编辑：检查 edit 工具组和 fileRegex。
• MCP 不可见：检查全局开关、mcp 工具组、服务器白名单、连接与工具状态。
• 配置看似丢失：检查项目配置是否完全覆盖同名全局模式。