Roo Code 模式系统与核心能力深度解析把一整支 AI 开发团队装进你的编辑器【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-CodeRoo Code 是一个运行在 VS Code 中的 AI 编程代理Agent扩展它通过 Modes模式系统将规划—编码—提问—调试—编排的完整开发流程内置为五种人格化角色并以可扩展的自定义模式Custom Modes机制满足团队级工作流定制需求。本文以仓库根目录的 README.md 为骨架结合 modes.ts、mode.ts、tools.ts 等源码实现系统讲解 Roo Code 的核心能力、内置模式、切换方式、自定义配置方法与底层原理帮助你快速上手并把 Roo Code 融入日常开发。一、Roo Code 是什么编辑器里的 AI 开发团队Your AI-Powered Dev Team, Right in Your Editor这是 Roo Code 在项目 README.md 中的自我定位将一支 AI 驱动的开发团队内置在代码编辑器里。它并非单一代码补全工具而是一个能够理解自然语言、调用真实开发工具读写文件、执行命令、搜索代码、访问 MCP 服务器的自主代理可围绕规划—执行—验证的闭环独立推进任务。从仓库结构看Roo Code 是一个 pnpm turbo 管理的 monorepo见 package.json包含 VS Code 扩展本体src/extension.ts、Webview 界面webview-ui/src/App.tsx、核心类型包packages/types/src/mode.ts以及完整的官方文档站点apps/docs等子包。其中与本文主题最直接相关的是扩展侧的模式调度逻辑与工具权限模型。二、Roo Code 能为你做什么七大核心能力README.md 用一句话功能清单概括了 Roo Code 的能力边界能力说明自然语言生成代码根据自然语言描述与规格说明specs生成代码模式化适配通过 Code、Architect、Ask、Debug 以及自定义模式切换工作方式重构与调试存量代码对既有代码进行重构、排查与修复编写与更新文档自动撰写、维护项目文档回答代码库相关问题针对你的代码库进行问答与解释自动化重复任务将重复性工作交给代理批量完成接入 MCP 服务器通过 Model Context Protocol 扩展外部工具与数据源其中模式化适配是 Roo Code 区别于普通 AI 助手的核心设计——同一套模型权重通过切换系统提示词与工具权限就能在不同任务语境下表现出不同专家的行为。下一节我们深入这个机制。三、Modes 模式系统五种内置角色Modes 是 Roo Code 的核心抽象每个模式都是一个专门的人格persona拥有不同的能力、专业领域和工具访问级别。官方文档 using-modes.md 对这一设计给出了明确的定义。3.1 五种内置模式速览根据 README.md 与 mode.ts 中的DEFAULT_MODES常量内置模式共五种模式名称职责工具组groupsCode Code默认模式日常编码、编辑、文件操作全能软件工程师read、edit、command、mcp全量Architect️ Architect规划系统、规格说明与迁移方案先调研后出计划read、受限edit仅 Markdown、mcpAsk❓ Ask快速问答、解释、查阅文档不修改代码read、mcpDebug Debug追踪问题、加日志、隔离根因并修复read、edit、command、mcp全量Orchestrator Orchestrator复杂任务编排分解后委派给各专业模式无直接工具仅通过new_task委派在源码层面每种模式的人设由三个字符串字段共同决定见 mode.ts 的modeConfigSchemaroleDefinition模式的核心身份与专业能力描述会被放到系统提示词system prompt的最前面whenToUse告诉 Roo 何时该使用该模式供 Orchestrator 自动决策模式选择customInstructions附加的行为准则追加在系统提示词尾部。例如 Code 模式的roleDefinition是You are Roo, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices.mode.ts而 Debug 模式则内置了先反思 5–7 种可能的故障源、浓缩为 1–2 个最可能项、加日志验证假设、修复前先请用户确认的排错方法论mode.ts。3.2 工具组模式权限的底层模型内置模式的groups字段引用了 tools.ts 中定义的TOOL_GROUPS工具组配置这是模式权限体系的地基工具组包含工具说明readread_file、search_files、list_files、codebase_search文件读取、目录列举、正则搜索、代码库语义搜索editapply_diff、write_to_file、generate_image另有edit、search_replace等自定义工具文件修改与创建、图像生成commandexecute_command、read_command_output终端命令执行与输出回读mcpuse_mcp_tool、access_mcp_resource调用 MCP 服务器工具、读取 MCP 资源modesswitch_mode、new_taskalwaysAvailable: true模式切换与子任务委派对所有模式常驻此外还有一组ALWAYS_AVAILABLE_TOOLStools.ts——ask_followup_question、attempt_completion、switch_mode、new_task、update_todo_list、run_slash_command、skill——它们不依赖任何工具组对所有模式永久可用。这正是 Ask 模式虽然只有read/mcp两个组却依然能请求切换模式的原因switch_mode本身是常驻工具。getToolsForModemodes.ts的实现印证了这一模型它遍历模式的groups把每个组的工具集合收集起来再无条件并入ALWAYS_AVAILABLE_TOOLS最终得到该模式的实际工具清单。3.3 模式切换的四种方式官方文档 using-modes.md 列出了四种切换模式的方法下拉菜单点击聊天输入框左侧的模式选择器斜杠命令在消息开头输入/architect、/ask、/debug、/code、/orchestrator即可切换并清空输入框键盘快捷键循环切换所有可用模式操作系统快捷键macOS⌘ .WindowsCtrl .LinuxCtrl .接受建议当 Roo 判断任务适合另一模式时会给出切换建议点击即可采纳。值得注意的是模式切换最终都会落到switch_mode工具上其参数mode_slug/reason见 tools.ts 的NativeToolArgs定义因此 Agent 自身也可以在合适的时机主动请求切换。3.4 Sticky Models模式与模型的记忆绑定官方文档特别强调了Sticky Models粘性模型特性每个模式都会记住你上次使用的模型。切换模式时 Roo 会自动选中该模式上次使用的模型无需手动重选。你可以为不同模式绑定不同模型例如 Architect 用 Gemini、Code 用 Claude并在每次切换时自动跟随。同时当前选中的模式会在会话之间持久化下次打开仍是你上次使用的模式。该特性同样适用于自定义模式。四、自定义模式打造属于你的专属专家内置五种模式之外Roo Code 允许创建自定义模式Custom Modes可分为全局模式所有项目可用与项目模式仅当前工作区可用两类。详细配置指南见 custom-modes.mdx。4.1 模式配置的六个字段自定义模式由以下字段定义与modeConfigSchema一一对应见 mode.ts字段必填作用slug是唯一内部标识符必须匹配/^[a-zA-Z0-9-]$/仅字母、数字、连字符用于引用模式与关联规则文件目录如.roo/rules-{slug}/name是显示在 UI 中的名称可含空格与大小写roleDefinition是模式的核心身份置于系统提示词开头description否简短的用户友好摘要显示在模式选择器 UI 中模式名下方whenToUse否供 Orchestrator 自动决策的何时使用指引不在 UI 显示若留空则回退到roleDefinition首句customInstructions否追加在系统提示词尾部的行为准则groups是允许的工具组与文件权限限制字符串或元组形式4.2 三种创建方式直接让 Roo 创建推荐在对话中提出需求例如Create a new mode called Documentation Writer. It should only be able to read files and write Markdown files.Roo 会引导你补全各字段并用 YAML 格式生成配置Modes 页面可视化创建打开 Roo Code 面板 → 点击聊天框下方模式菜单的齿轮图标 → 在 Modes 页面点击新建填写名称、slug、描述、角色定义、工具等字段手动编辑配置文件全局模式编辑settings/custom_modes.yaml或 JSON 版本项目模式编辑项目根目录的.roomodes文件。4.3 配置文件示例YAML 与 JSONYAML 示例全局custom_modes.yaml或项目.roomodescustomModes: - 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 onlyJSON 替代写法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 }] ] } ] }4.4groups与fileRegex精细的文件编辑权限groups的结构有两种形式定义见 mode.ts 的groupEntrySchema纯字符串无限制访问如edit元组[edit, { fileRegex, description }]用正则限制该组可操作的文件。fileRegex的匹配对象是从工作区根目录开始的完整相对路径如src/components/button.js默认大小写敏感非法正则会被拒绝并提示Invalid regular expression pattern该校验逻辑见 mode.ts 的groupOptionsSchema。常用模式对照表注意 JSON 中反斜杠需双重转义目标YAML 写法JSON 写法仅 Markdown 文件\.md$\\.md$仅src/目录下文件^src/.*^src/.*CSS/SCSS 文件\.(css\|scss)$\\.(css\|scss)$docs/下的 Markdowndocs/.*\.md$docs/.*\\.md$排除 test/spec 的 JS/TS^(?!.*(test\|spec))\.(js\|ts)$^(?!.*(test\|spec))\\.(js\|ts)$当模式试图编辑不匹配fileRegex的文件时会抛出FileRestrictionError见 modes.ts错误信息中包含模式名、允许的匹配模式、描述、被阻止的文件路径与工具名方便你定位原因。4.5 配置优先级与内置模式覆盖模式配置的生效顺序由高到低项目级配置.roomodes全局级配置custom_modes.yaml其次custom_modes.json默认内置模式配置。关键规则当项目与全局存在相同slug的模式时项目版本会整体覆盖全局版本所有属性都不做合并详见 custom-modes.mdx。这意味着你可以通过同 slug 覆盖的方式改造内置模式例如把默认 Code模式覆盖为只允许编辑.js/.ts的受限版本。这一优先级在源码中的体现是 modes.ts 的getAllModes它先载入内置模式数组再遍历自定义模式——遇到相同 slug 就地替换否则追加到末尾。而getModeSelectionmodes.ts则遵循自定义模式优先、否则内置模式、最后回退默认模式的选择链。4.6 模式专属指令文件除了customInstructions字段还可以用文件/目录提供模式指令便于版本化管理与协作首选目录方式.roo/rules-{slug}/如.roo/rules-docs-writer/目录内文件按文件名不区分大小写字母序递归读取并追加回退单文件方式.roorules-{slug}兼容旧项目兼容方式.clinerules-{slug}历史遗留不推荐新项目使用。目录方式优先只要.roo/rules-{slug}/存在且非空同级单文件即被忽略。文件内容会追加在customInstructions之后共同生效。全局模式对应的规则目录位于用户主目录下的~/.roo/rules-{slug}/。五、Orchestrator 与 MCP扩展 Roo Code 的边界5.1 Orchestrator任务编排的核心Orchestratoraka Boomerang Mode是五种内置模式中最特殊的一个——它的groups为空数组mode.ts意味着它没有任何直接操作工具只能通过常驻的new_task工具把子任务委派给其他专业模式执行。其内置指令要求委派时在message参数中提供完整上下文、明确子任务范围、要求子任务以attempt_completion汇报结果、并声明本指令优先级高于子任务模式自身的通用指令mode.ts。new_task的参数结构为{ mode, message, todos }见 tools.ts配套的switch_mode参数为{ mode_slug, reason }。围绕这两个工具仓库还提供了完整的委派事件测试如 delegation-events.spec.ts、new-task-delegation.spec.ts和工具单测newTaskTool.spec.ts可作为理解委派闭环的参考。5.2 MCP外部工具与数据接入MCPModel Context Protocol是 Roo Code 与外部工具生态对接的标准通道。mcp工具组提供两个工具use_mcp_tool调用 MCP 服务器暴露的工具参数为{ server_name, tool_name, arguments }access_mcp_resource读取 MCP 服务器暴露的资源参数为{ server_name, uri }。Roo Code 甚至支持原生 MCP 调用在原生模式下MCP 工具可直接以其带前缀的名称如mcp_serverName_toolName被模型调用而不必经由use_mcp_tool包装见 tools.ts 的McpToolUse说明。配置了 MCP 服务器后任何拥有mcp组的模式Code、Architect、Ask、Debug都能与外部系统交互从而让 Roo Code 的能力超出编辑器本身。六、项目状态、资源与许可6.1 项目现状说明README.md 中有一段重要的Disclaimer免责声明Roo Code 扩展已于2026 年 5 月 15 日停止运营。README 同时说明如需替代方案可关注由 Roo Code 社区发起的 fork 项目以及 Roo Code 的起源项目付费用户在计费问题上有专门的联系渠道billingroocode.com。另外仓库的 CHANGELOG.md 显示在 3.53.0 版本中已有社区团队接手继续维护该插件README 与 CHANGELOG 的说明以仓库内实际文件为准。Roo Code, Inc. 不对该扩展关联的任何代码、模型、第三方工具及输出结果作任何明示或默示的保证所有使用风险含知识产权侵权、网络安全、偏差、错误、病毒、停机、财产损失与人身伤害等均由使用者自行承担。6.2 进一步学习的资源官方文档apps/docs/docs 目录下收录了安装、配置与进阶使用指南其中 using-modes.md 讲解模式使用custom-modes.mdx 讲解自定义模式available-tools 介绍全部可用工具多语言 README仓库提供 17 种语言的 README位于 locales 目录如简体中文版 locales/zh-CN/README.md模式类型定义所有模式与工具组的 schema 定义集中在 packages/types/src/mode.ts 与 src/shared/tools.ts模式调度实现模式解析、合并与提示词组装逻辑见 src/shared/modes.ts。6.3 开源许可Roo Code 采用 Apache License 2.0 开源许可© 2026 Roo Code, Inc.允许自由使用、修改与再分发具体条款以 LICENSE 文件为准。结语Roo Code 的价值不在于单一模型的调用能力而在于**模式 × 工具组 × 系统提示词三层架构**带来的工程化灵活性内置五种模式覆盖了规划Architect→ 编码Code→ 提问Ask→ 调试Debug→ 编排Orchestrator的完整开发闭环而自定义模式、fileRegex文件权限、模式专属规则目录与 MCP 接入则让团队可以把组织规范直接固化进 AI 工作流。理解 mode.ts 与 tools.ts 中的数据结构是深度定制 Roo Code 行为的第一步——无论你打算为它配置专属专家还是用它编排复杂的多步骤任务这套模式系统都是你与 AI 开发团队协作的指挥中枢。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考