Roo Code 3.3.0 实战指南Code Actions、智能模式切换、Markdown 编辑与 AWS Profile 配置【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code本篇技术指南以 Roo Code 3.3.0 版本更新为核心逐一拆解该版本引入的四大关键能力原生 VS Code Code Actions、智能模式切换switch_mode、针对特定模式开放的 Markdown 编辑支持、以及自定义模式的文件类型白名单限制同时覆盖 Bedrock 提供商新增的 AWS Profile 认证配置。读完本文你将能够在 VS Code 编辑器中直接对选区执行解释/修复/改进等 AI 操作能让 Roo Code 在不同模式间自主建议切换能为自定义模式如Technical Writer配置.md文件编辑白名单并能基于 AWS SSO 或短期凭证以 Profile 方式接入 Bedrock。版本概览Roo Code 3.3.0 是一次聚焦编辑器原生体验的迭代。依据 v3.3.0 发布说明本次更新的五个核心特性分别为Code Actions 支持在编辑器内直接集成 VS Code 原生 code actions提供快速修复quick fixes与重构建议。更智能的模式切换模式可以自主、合理地请求切换到其他模式例如在 Architect 模式下需要改代码时主动建议切换到 Code 模式。增强的 Markdown 支持Ask 与 Architect 模式现在可以编辑 Markdown 文件。自定义文件模式限制可为自定义模式限定可编辑的文件类型例如允许Technical Writer模式只编辑.md文件。Bedrock 的 AWS Profiles支持通过 AWS Profile 配置 Bedrock 提供商对使用 SSO 或没有长期凭证的集成场景尤其有用。下面分别深入每一项功能的实现与用法。一、原生 Code Actions在编辑器中直接调用 Roo1.1 什么是 Code ActionsCode Actions 是 VS Code 的原生交互机制灯泡图标 通常出现在代码存在诊断信息错误、警告或用户主动调用的位置。Roo Code 3.3.0 注册了一个CodeActionProvider把 AI 能力以原生 code action 的形式暴露在编辑器中用户选中一段代码即可触发。从 CodeActionProvider.ts 可以看到Roo Code 提供五个操作动作名称Code Action 标题说明EXPLAINExplain with Roo Code解释选中的代码FIXFix with Roo Code修复诊断中列出的问题IMPROVEImprove with Roo Code改进代码质量ADD_TO_CONTEXTAdd to Roo Code将选区加入对话上下文NEW_TASKNew Roo Code Task基于选区/输入创建新任务其中NEW_TASK在 Code Action 面板中并不与选区直接绑定它由命令面板入口handleTask触发其余四个动作都针对当前选中的文本范围。1.2 触发逻辑有诊断与无诊断的差异provideCodeActions 的实现 展示了核心触发逻辑首先检查配置项enableCodeActions默认true关闭后整个 Provider 直接返回空数组不会出现在灯泡菜单中通过EditorUtils.getEffectiveRange计算有效的选择范围若光标处无可选内容则直接返回空无论是否有诊断信息始终提供Add to Roo Code无诊断信息时提供EXPLAIN与IMPROVE两个动作有诊断信息如 ESLint/TS 报错时不再提供 EXPLAIN/IMPROVE而是改提供FIX动作并且只在与当前选区相交的诊断上生效hasIntersectingRange过滤。这一点在测试 CodeActionProvider.spec.ts 中得到印证默认无诊断场景返回 3 个动作Add to Context、Explain、Improve存在诊断时返回 2 个动作Add to Context、Fix。1.3 底层命令与提示词模板每个 code action 都对应一个内部命令由 registerCodeActions.ts 注册registerCodeAction(context, explainCode, EXPLAIN) registerCodeAction(context, fixCode, FIX) registerCodeAction(context, improveCode, IMPROVE) registerCodeAction(context, addToContext, ADD_TO_CONTEXT)注册的命令处理器支持两种调用路径来自 Code Action 面板参数中携带filePath、selectedText、startLine、endLine与可选的diagnostics来自命令面板直接执行通过EditorUtils.getEditorContext()从当前编辑器状态中读取同样的上下文。随后这些参数会被交给 ClineProvider.handleCodeActionADD_TO_CONTEXT会将提示词写入聊天输入框并聚焦输入区等待用户确认发送其余动作则直接createTask(prompt)创建新任务。提示词模板定义在 support-prompt.ts 中例如EXPLAIN模板要求模型解释该代码的目的与功能、关键组件及其交互、使用的重要模式与技巧FIX模板要求逐一处理上方列出的所有诊断问题并识别其他潜在 Bug给出修正后的代码及修复原因IMPROVE模板聚焦可读性与可维护性、性能优化、最佳实践与错误处理。用户也可以利用customSupportPrompts覆盖这些模板。1.4 如何启用与使用Code Actions 功能默认开启对应配置项为roo-cline.enableCodeActionsboolean默认true在 package.json 中声明。需要关闭或重新开启时在 VS Code 设置中搜索roo-cline.enableCodeActions即可。使用方式在编辑器中选中一段代码等待灯泡图标出现或按下快捷键默认Ctrl./Cmd.打开 Quick Fix 菜单选择 Explain with Roo Code、Improve with Roo Code 或 Fix with Roo CodeRoo Code 面板会基于选区与当前模式创建任务并执行。另外终端输出区域同样有对等的操作terminalAddToContext、terminalFixCommand、terminalExplainCommand实现在 registerTerminalActions.ts可以把终端中的报错内容一键交给 Roo 修复或解释。二、智能模式切换switch_mode 工具2.1 工作流程更智能的模式切换落地为switch_mode工具。Architect 等规划类模式在梳理出实现方案后不再需要用户手动切换模式——模型可以直接调用switch_mode请求切换到 Code、Debug 等实施类模式。从 SwitchModeTool.ts 可以看到该工具的完整执行流程参数校验需要mode_slug目标模式标识与reason切换原因。缺少mode_slug会直接记录错误并提示模式存在性校验通过getModeBySlug(mode_slug, customModes)验证目标模式是否存在自定义模式优先其次内置模式不存在则返回Invalid mode: xxx重复切换检查若当前模式与目标模式相同返回 Already in xxx mode.用户审批构造{tool: switchMode, mode, reason}消息并调用askApproval(tool, ...)请求用户批准——切换始终需要用户确认不会静默发生执行切换调用ClineProvider.handleModeSwitch(mode_slug)真正切换并延迟 500ms 让模式变更生效后再继续执行下一个工具。handleModeSwitchClineProvider.ts在切换前会先将新模式持久化到任务历史taskHistoryStore只有持久化成功后才更新任务内存中的模式保证任务历史与当前状态一致。2.2 模型侧的引导内置模式的提示词中明确写入了这一协作方式。以 Architect 模式为例在 mode.ts 中的 DEFAULT_MODES 可以看到其customInstructions明确要求Use the switch_mode tool to request that the user switch to another mode to implement the solution.这意味着 Architect 模式完成计划与待办清单后会调用switch_mode请求切换到实施模式而用户仍保有最终审批权。这也是 3.3.0 所称智能的边界——建议由 AI 提出决定权始终在用户手中。三、Markdown 编辑支持与自定义文件模式限制3.1 Ask / Architect 模式开始支持编辑 Markdown3.3.0 之前Ask 模式只能阅读不能写入Architect 模式的编辑范围也较窄。本版本为这两个模式开放了 Markdown 编辑能力。其底层机制正是下面要讲的文件模式限制在 mode.ts 的 Architect 默认配置 中其groups声明为groups: [read, [edit, { fileRegex: \\.md$, description: Markdown files only }], mcp]其中[edit, {...}]这种元组形式即为 3.3.0 引入的带选项的工具组edit组被限定为只允许匹配\.md$正则的文件并附上人类可读的说明 Markdown files only。Ask 模式同样通过此类配置获得.md文件的编辑权其其余组保持read、mcp。3.2 Group Options 的数据模型该能力的 schema 定义在 packages/types/src/mode.tsexport const groupOptionsSchema z.object({ fileRegex: z.string().optional().refine((pattern) { if (!pattern) return true try { new RegExp(pattern) return true } catch { return false } }, { message: Invalid regular expression pattern }), description: z.string().optional(), }) export const groupEntrySchema z.union([toolGroupsSchema, z.tuple([toolGroupsSchema, groupOptionsSchema])])要点fileRegex一个可选的、必须是合法正则表达式的字符串用于限定该工具组可操作的文件路径description可读描述会在限制被触发时展示给用户GroupEntry支持两种写法纯字符串edit无限制或元组[edit, { fileRegex, description }]带限制。3.3 运行时如何强制限制限制并非只在提示词层面建议而是在工具调用验证阶段强制执行。见 validateToolUse.ts对于edit组若配置了fileRegex则取出工具参数中的path/file_path只有真正的编辑操作EDIT_OPERATION_PARAMS中的参数存在才校验避免流式输出路径时的误拦截对于apply_patch工具会从 patch 内容中提取所有文件路径逐一校验patch 中任何文件不匹配正则都会抛出FileRestrictionError不匹配时抛出FileRestrictionError其错误信息定义在 modes.ts形如Tool apply_patch in mode technical-writer can only edit files matching pattern: \.md$ (Markdown files only). Got: src/main.ts3.4 实战创建一个只编辑 Markdown 的Technical Writer模式自定义模式通过全局customModes设置文件或项目级.roomodes文件维护读取与合并逻辑见 CustomModesManager.ts项目级.roomodes优先级高于全局。一个典型的 YAML 配置如下customModes: - slug: technical-writer name: Technical Writer roleDefinition: | You are an expert technical writer. You refine and polish Markdown documentation. whenToUse: | Use this mode when the user needs to write, review, or edit documentation. customInstructions: | Keep language concise and precise. Preserve code fences and YAML front matter. groups: - read - - edit - fileRegex: \\.md$ description: Markdown files only - mcp配置要点slug仅允许字母、数字与连字符schema 强制/^[a-zA-Z0-9-]$/见 mode.tsroleDefinition为必填项groups中[edit, {...}]将编辑工具限定为只处理.md文件若需要同时允许多种类型可扩展正则例如\\.(md|mdx)$全局自定义模式存放在~/.roo/customModes.yaml写入逻辑见 getCustomModesFilePath项目级则放入工作区根目录的.roomodes修改后文件监听器watchCustomModesFiles会自动重载合并后的模式无需重启 VS Code。注意正则校验发生在validateToolUse层对EditTool等逐文件编辑与apply_patch的批处理编辑均生效可有效防止模式越权修改文件。四、Bedrock 提供商新增 AWS Profile 认证4.1 背景与价值以往使用 Amazon Bedrock 通常需要在 Roo Code 中填写长期 Access Key / Secret Key这对使用 AWS SSO、IAM Roles Anywhere 或临时令牌的组织并不友好。3.3.0 新增的AWS Profiles 支持让 Roo Code 直接复用~/.aws/credentials/~/.aws/config中已配置的命名 Profile尤其适合通过aws sso login获取的 SSO 会话凭证使用短期 STS 凭证的环境团队统一管理 AWS 凭证、不在 IDE 里明文保存密钥的场景。4.2 配置项相关配置字段在 packages/types/src/provider-settings.ts 的bedrockSchema中声明配置项类型说明awsProfilestring可选要使用的 AWS 命名 Profile 名称awsUseProfileboolean可选是否启用 Profile 认证awsRegionstring可选目标区域如us-west-2awsAccessKey/awsSecretKey/awsSessionTokenstring可选原有直连凭证方案awsUseApiKey/awsApiKeyboolean / string可选基于 token 的认证方案awsCustomArnstring可选自定义 ARN含推理 ProfileawsBedrockEndpointEnabled/awsBedrockEndpointboolean / string可选自定义 Endpoint如 LiteLLM 透传4.3 认证优先级与底层实现bedrock.ts 中客户端凭据的构建顺序是优先awsUseApiKey awsApiKey—— 使用 Bearer Token 认证httpBearerAuth适合经 LiteLLM 等网关透传其次awsUseProfile awsProfile—— 通过fromIni({ profile, ignoreCache: true })从~/.aws读取命名 Profile 的凭证ignoreCache: true保证每次都能拿到最新凭证对 SSO 刷新尤为重要兜底awsAccessKey awsSecretKey—— 直接使用填写在设置中的长期凭证可附带awsSessionToken。同时客户端还注入了userAgentAppId: RooCode#version、region来自awsRegion或从自定义 ARN 解析并支持通过awsBedrockEndpoint覆盖默认 Endpoint。4.4 配置步骤在命令行完成 AWS 凭证准备例如 SSO 场景aws configure sso # 按向导配置 SSO Profile aws sso login --profile your-profile或在~/.aws/credentials中手动维护[your-profile]条目打开 Roo Code 设置 → Providers → Amazon Bedrock填写awsRegion如us-west-2勾选启用awsUseProfile并在awsProfile中填入 Profile 名称与aws sso login --profile的名称一致选择 Bedrock 模型并发送一条消息验证连通性。4.5 其他 Bedrock 增强与 Profile 支持一并相关的 Bedrock 能力还包括跨区域推理 ProfileawsUseCrossRegionInference、全局推理 ProfileawsUseGlobalInference、自定义推理 ARN、STANDARD/FLEX/PRIORITY服务层级awsBedrockServiceTier以及 Bedrock 专属的 1M 上下文 BetaawsBedrock1MContext。这些字段均在 provider-settings.ts 的 schema 中声明可按需组合使用。五、版本更新带来的协作范式变化综合来看3.3.0 的这几项能力共同构成了一套更贴近编辑器原生工作流的协作模式交互入口更短Code Actions 把选中代码 → 灯泡 → 交给 AI压缩到两步配合终端操作用户在报错现场即可启动修复分工更智能switch_mode让规划模式Architect与实施模式Code/Debug的交接自动化且始终保留用户审批权权限更精细fileRegex限制让文档型、审查型模式在拥有编辑能力的同时不会越权触碰源码模式之间的职责边界更清晰接入更合规AWS Profile 支持让企业用户在 SSO 与短期凭证体系下也能顺畅使用 Bedrock。六、总结Roo Code 3.3.0 从编辑器内交互与模式权限精细化两个维度打磨了日常使用体验通过 CodeActionProvider.ts 与 registerCodeActions.ts 提供 Explain / Fix / Improve / Add to Context 四类原生操作通过 SwitchModeTool.ts 实现带用户审批的智能模式切换通过 mode.ts 的GroupEntry元组语法 validateToolUse.ts 的运行时校验实现 Ask/Architect 的 Markdown 编辑与自定义模式的文件类型白名单通过 bedrock.ts 的fromIni集成让 Bedrock 支持 AWS Profile含 SSO认证。无论是想要更顺手的编辑器内 AI 操作还是需要为团队配置细粒度的模式权限都可以从本文对应的配置与源码路径入手在本地 VS Code 中直接验证这些能力。【免费下载链接】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），仅供参考