企业官网建设流程全解析

Roo Code 3.14 版本深度解析：Gemini 缓存、Boomerang 编排模式与文件编辑工具链升级

【免费下载链接】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.14 是一组以“成本、效率与体验”为核心主题的重要更新：它为 Gemini 系列模型带来了提示词缓存（Prompt Caching）能力，将原先需要手工配置的 Boomerang Mode 正式内置为 Orchestrator 模式，同时重构了文件编辑工具链（引入search_and_replace、insert_content，弃用append_to_file），并首次加入俄语国际化支持。本文以官方 3.14 更新记录为骨架，结合仓库源码与配套文档，逐一解析这些更新的使用方式、配置细节与底层实现，帮助你在升级后快速上手并规避已知的坑。

一、Gemini 2.5 提示词缓存：省钱的开关怎么用

1.1 支持范围与使用前提

从 3.14 起，提示词缓存（Prompt Caching）对以下 Gemini 模型开放：

• Gemini 1.5 Flash
• Gemini 2.0 Flash
• Gemini 2.5 Pro Preview

对应可用的 Provider 为 Requesty、Google Gemini 与 OpenRouter。更新记录同时说明：Vertex Provider 与Gemini 2.5 Flash Preview的缓存支持“即将到来”，也就是说在当前版本中这两类通道尚不能使用该功能。

1.2 手动缓存开关：Google Gemini 与 OpenRouter 专属

针对Google Gemini和OpenRouter两个 Provider，设置界面新增了一个缓存复选框（Provider Settings 中的 “Enable prompt caching”）。勾选后，后续请求将使用带提示缓存的模型以降低输入 token 的重复计费成本。

为什么需要手动开关？更新记录给出的原因很直白：这是为规避 Google 缓存机制在这两个 Provider 通道上偶尔出现的响应延迟而提供的临时性变通方案。因此在默认情况下，这两个 Provider不会自动启用缓存——你需要按需手动勾选。

1.3 Requesty：自动缓存

与上面两个 Provider 不同，Requesty通道对受支持模型保持自动缓存，无需任何手动配置。如果你主要走 Requesty，升级到 3.14 后缓存即默认生效。

1.4 缓存的成本计算与源码印证

缓存功能并非只影响请求发送，还牵扯到费用统计。在 Gemini Provider 实现 中，响应里读取usageMetadata.cachedContentTokenCount作为cacheReadTokens，并将其计入请求轨迹（trace）的成本明细。随后的成本计算逻辑（gemini.ts）会将总输入 token 拆分为“未缓存输入”与“缓存读取”两部分：

• 未缓存输入按inputPrice计费；
• 缓存读取部分按cacheReadsPrice（即缓存读取价格）计费，计算公式为cacheReadsPrice * (cacheReadTokens / 1_000_000)，且在未定义cacheReadsPrice时按 0 处理。

也就是说，启用缓存后你会在成本统计中看到cacheRead独立成项，方便直接对比“省下了多少输入 token 费用”。

二、Boomerang Orchestrator 模式：任务编排正式内置

2.1 从自定义模式到内置模式

此前，“Boomerang Mode”需要用户通过自定义模式文件手动创建；3.14 起它成为内置模式：🪃 Orchestrator（Boomerang Mode）。你不再需要任何自定义配置即可直接选用。

内置模式的选择入口可从新主页的模式下拉列表中看到（Code、Architect、Ask、Debug 等模式并列，其中 Orchestrator 被勾选）。仓库中还保留了一份该模式前身的完整自定义配置示例，见 apps/docs/static/downloads/boomerang-tasks/roomodes.json，其中定义了slug: "boomerang-mode"、roleDefinition（战略工作流编排者）与详细customInstructions，可作为理解内置 Orchestrator 行为逻辑的参考蓝本。

2.2 它解决什么问题

编排（Orchestration）的核心价值在于“分工”：

• 拆解复杂任务：把“构建一个完整功能”这类大目标拆成设计、实现、文档等聚焦子任务；
• 善用专用模式：将子任务自动委托给最合适的模式（如💻 Code、🏗️ Architect、🪲 Debug）；
• 隔离上下文、保持专注：每个子任务拥有独立的对话历史与上下文，父任务不会被代码 diff、文件分析等执行细节淹没，只需基于子任务返回的精炼摘要推进整体流程；
• 结果流转：一个子任务的产出可作为下一个子任务的输入，形成顺畅流水线（例如架构决策直接喂给编码任务）。

2.3 工作流程：父任务挂起 → 子任务执行 → 摘要回归

1. 处于 Orchestrator 模式时，Roo 分析复杂任务并建议将其拆分为子任务；
2. 父任务（Orchestrator 模式）暂停，新子任务在另一个专用模式中启动；
3. 子任务达成目标后，通过attempt_completion工具报告完成；
4. 父任务恢复，只接收子任务的最终摘要，并据此继续主流程。

三个关键数据通道与new_task/attempt_completion两个工具的参数一一对应：

相关工具说明可查阅 new-task 文档 与 attempt-completion 文档。

2.4 关键注意事项

• 默认需要审批：每个子任务的创建与完成默认都要你确认，可通过 Auto-Approving Actions 设置自动化；
• 上下文不自动继承：子任务完全隔离，父任务上下文必须显式向下传递（初始指令）并显式回收（最终摘要），且只有摘要会回到父任务；
• 导航：Roo 界面会展示任务层级（谁是父、谁是子），可在活跃任务与挂起任务之间切换；
• 刻意限制能力：Orchestrator 模式默认不能读文件、写文件、调用 MCP 或执行命令——这是设计使然，旨在防止其上下文被文件读取填满、从而偏离编排职责，也有助于避免 context poisoning 引发的上下文污染。

如果确实需要给 Orchestrator 模式加回“读文件”等能力，可参考 custom-modes 配置优先级 的覆盖规则：在命令面板选择“Edit Global Modes”，粘贴一份带groups: ["read"]的同名orchestrator模式配置并保存即可（完整 JSON 示例见 boomerang-tasks.mdx）。注意此类扩展应谨慎为之，否则会削弱其“专注编排”的默认定位。

三、文件编辑工具链：search_and_replace上线、insert_content上岗、append_to_file退役

3.14 对文件编辑工具做了一次系统性梳理，核心变更如下：

• search_and_replace新工具：在文件内按字面字符串或正则表达式查找并替换文本，可选限定在指定行范围内执行；
• insert_content新工具（现已退役）：在文件指定位置或末尾插入新行，不修改已有内容；
• append_to_file弃用：其职责由insert_content承接，等价写法为insert_content的line: 0；
• apply_diff兼容性增强：对Google Gemini 2.5及其他模型的配合更好，同时补上了更清晰的进度指示；
• write_to_file兜底优化：当因“缺失行数”导致写入失败时，正确回滚变更并建议改用其他工具；
• 编辑后自动关文件：apply_diff、insert_content、search_and_replace、write_to_file等编辑工具产生的文件在你审批变更后会被自动关闭，避免编辑器被 Roo 打开的文件占满，也让界面只保留你刻意打开的文件，上下文更清晰。

从源码结构看，这些工具的实现与校验集中在 src/core/tools/ 目录：例如工具用法的合法性校验位于 validateToolUse.ts，apply_diff与write_to_file的完整说明可参见 apply-diff 文档 与 write-to-file 文档。迁移建议很明确：如果此前习惯用append_to_file在文件头部插入内容，3.14 之后请改用insert_content并传入line: 0。

四、终端修复：回退符与回车符的显示校正

终端输出在 3.14 中得到了两处显示层面的修复：

• 退格符（backspace）：改进了对终端输出中退格字符的处理，输出展示更干净；
• 回车符（carriage return）：修复了回车符处理，使进度条（progress bar）能正确显示。

这两处修复分别由 KJ7LNW 与 Yikai-Liao 贡献，直接改善了长命令输出、进度动画等场景下的可读性。

五、国际化：俄语支持上线

3.14 新增了**俄语（Russian）**语言支持。结合仓库现状，Roo Code 的本地化资源位于 src/i18n/locales/ 与 package.nls.*.json 等文件中，ru目录与package.nls.ru.json即对应本次新增的俄语语言包。用户可在 VSCode 语言设置中切换界面语言，Roo Code 会随之应用对应的界面文案。

六、Context Mentions：引用图标的材料化升级

上下文引用（Context Mentions）组件在 3.14 获得了一批体验优化（均由 elianiva 贡献）：

• 文件与文件夹的引用图标改用Material Icons；
• 修复了 Linux 上图标渲染的问题；
• 改进了aftercursor内容在 mentions 中的处理。

这些改动让“在输入框中 @ 引用文件/目录”时的视觉呈现与跨平台一致性更好。

七、Footgun Prompting：上下文变量插值与覆盖提示

“Footgun Prompting”（防止误操作的提示工程）在 3.14 引入了两项能力：

• 上下文变量插值：自定义系统提示词覆盖文件（system prompt override）中现在可以插入以下上下文变量，使提示词随运行环境动态变化：

• 覆盖警告指示器：当当前模式存在生效的系统提示词覆盖时，聊天输入框会显示警告指示器，提醒你“当前正被自定义提示词接管”，避免在不知情的情况下触发非预期行为。

八、MCP 与 Provider 侧更新

8.1 MCP 调整

• 支持在MCP 配置中注入环境变量；
• 修复将扩展拖拽到其他侧边栏时出现的 MCP hub 错误；
• 改进长 MCP 工具参数的显示。

8.2 Provider 更新

• Amazon Bedrock：允许使用 BedrockMarketplace ARNs（由 mlopezr 贡献），拓展了模型接入范围；
• Requesty：改进了模型列表拉取逻辑；
• VS Code LM Provider：现在能正确显示模型信息，并移除了不必要的计算步骤；
• Unbound Provider：默认模型 ID 从claude-3.5-sonnet更新为claude-3.7-sonnet。

九、杂项 Bug 修复与体验优化（QOL）

• list_files更高效：更智能地排除.git/等目录，减少无关扫描；
• 任务体积计算性能提升：token 估算更高效，减少“灰屏”出现概率；
• 聊天行给出更好的加载反馈；
• 更合理的任务导出图标；
• 修复Windows 与 SSH 隧道场景下的文件拖放问题；
• 修复 “add to context” 代码操作的插值 bug；
• 修复恢复任务时冗余的 “TASK RESUMPTION” 提示；
• 修复编辑器没有工作区根目录时打开文件失败的问题；
• 切换 API Provider 时不再立刻报模型 ID 错误；
• focusInput命令更可靠；
• 在 evals 中追踪工具使用错误；
• webview 源文件改用路径别名；
• 对 FakeAI “controller” 对象处理更健壮；
• 保留编辑器状态、避免 diff 期间标签页被取消固定；
• 清理内部设置数据模型，提升可维护性；
• 对不支持 reasoning 的模型，API 调用中省略 reasoning 参数，减少无效开销；
• 修正 Roo 消息标题的换行；
• 澄清了自定义设置相关文档的表述。

十、升级建议与使用要点小结

• 想省 Gemini 输入成本：Google Gemini / OpenRouter 通道请手动勾选缓存开关；Requesty 通道自动生效；Vertex 与Gemini 2.5 Flash Preview需等待后续版本。
• 想用任务编排：直接切换到内置🪃 Orchestrator模式即可，无需再手动创建 Boomerang 自定义模式；注意其默认“只编排、不执行细节”的能力边界，必要时按配置优先级扩展。
• 做文件编辑：新代码优先使用apply_diff与search_and_replace；在文件头部插入内容使用insert_content（line: 0）替代已弃用的append_to_file；编辑完成后文件会自动关闭，保持工作区整洁。
• 注意覆盖提示：若输入框出现系统提示词覆盖警告，请先确认当前模式的 prompt override 是否符合预期，再继续操作。

本版本变更的官方出处为 v3.14.md，更细粒度的 3.14.0 变更清单见 v3.14.0.md；如需了解 Orchestrator 模式的完整用法与 FAQ，可直接阅读 boomerang-tasks.mdx。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code