Roo Code 2.2.33 深度解析：Enhance Prompt 一键增强提示词与 OpenAI 兼容 Provider 模型列表支持

Roo Code 2.2.33 深度解析：Enhance Prompt 一键增强提示词与 OpenAI 兼容 Provider 模型列表支持

【免费下载链接】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 2.2.33 是一次聚焦于"输入体验"与"Provider 兼容性"的小版本迭代，核心包含两大变化：为聊天输入框引入 "Enhance Prompt"（提示词增强）按钮，让 AI 在发送前自动改写、润色你的原始请求；同时为 OpenAI 兼容 Provider 增加模型列表拉取能力，使模型下拉菜单不再依赖硬编码。本文将基于仓库中的 2.2.33 发布说明、Enhance Prompt 功能文档 以及相关源码与测试，逐层拆解这两个功能的使用方式、配置要点与底层实现原理。

一、版本概览：2.2.33 带来了什么

根据 v2.2.33 发布说明，本次发布围绕两个能力展开：

• 新增 "Enhance Prompt" 按钮：最初仅面向 OpenRouter 模型开放，用于在发送消息前自动增强提示词；
• 新增 OpenAI 兼容 Provider 的模型列表支持：允许从 Provider 动态拉取可用模型列表（社区贡献来自 @samhvw8）。

在 2.2 系列版本发布说明 的 "QOL Improvements & UI" 一节中，这两项也被并列记录为 "Enhance prompt" Button (OpenRouter) 与 "List Models for OpenAI Compatible"，可见它们是该版本周期内重要的质量提升项。其中 "Enhance Prompt" 后来演变为一个覆盖所有支持completePrompt能力的 Provider 的通用功能，并有独立的 功能文档 详细描述。

下面分别深入这两项能力。

二、Enhance Prompt：一键优化你的提问

2.1 为什么需要增强提示词

在把消息发送给模型之前，用户的原始输入往往存在表达含糊、上下文缺失、指令不完整等问题。Enhance Prompt 的作用就是让 Roo Code 在发送前自动重写这段输入，带来以下收益（详见 enhance-prompt.md）：

• 提升清晰度：把口语化、零散的描述改写成模型更易理解的规范表达；
• 补充上下文：可在提示词中加入当前文件路径、选中的代码等上下文信息；
• 强化指令：为模型补充输出格式、详细程度等指导性要求；
• 消除歧义：避免模型对用户意图产生多种解读；
• 保持一致性：Roo 以统一的模板风格向模型发送增强请求，输出格式稳定；
• 上下文感知建议：开启后，会结合最近的会话历史生成更贴合当前工作语境的增强结果。

2.2 使用步骤

按照功能文档，Enhance Prompt 的使用非常简单：

1. 输入原始提示词：像平常一样在 Roo Code 聊天输入框中输入请求，可以是一句简单的提问，也可以是一段复杂的任务描述；
2. 点击魔棒图标（Wand Icon）：不要按 Enter，而是点击输入框右上角的魔棒按钮。处理期间魔棒会旋转，提示正在工作；
3. 审查增强结果：Roo Code 会用增强后的版本替换你的原始输入。请确认它准确反映了你的意图，也可以继续手动微调；如果对结果不满意，按Ctrl+Z（Mac 为Cmd+Z）即可撤销增强，恢复原始提示词；
4. 发送增强后的提示词：按 Enter 或点击发送按钮，将增强结果发送给 Roo Code。

2.3 特殊行为

• 空输入增强：如果输入框为空就点击增强按钮，Roo 会显示一条说明信息，解释该功能的用途，方便新用户了解。
• 消息队列支持：即使当前处于"消息发送被禁用"的状态，增强按钮依然可用。这样你可以先把消息排队，再逐条增强，稍后统一发送（见 ChatTextArea.tsx 中handleEnhancePrompt对输入为空的兜底处理）。

从 ChatTextArea.tsx 的源码可以看到前端的行为：handleEnhancePrompt会先对输入做trim()，非空则置位增强状态并通过vscode.postMessage({ type: "enhancePrompt", text })把请求发给扩展宿主；为空则直接在输入框填入功能说明文案。

三、自定义增强过程：模板、占位符与测试

3.1 默认增强模板

Enhance Prompt 使用可定制的提示词模板，其默认模板为：

Generate an enhanced version of this prompt (reply with only the enhanced prompt - no conversation, explanations, lead-in, bullet points, placeholders, or surrounding quotes): ${userInput}

其中${userInput}是占位符，实际发送时会被替换成你的原始提示词。模板严格约束模型"只输出增强后的提示词本身"——不要对话、解释、铺垫、项目符号、占位符或引号——这是保证增强结果可直接回填到输入框的关键设计。

在源码中，这一默认模板定义于 support-prompt.ts 的ENHANCE配置项。该文件是一个"支持型提示词"的集中管理模块，除ENHANCE外还统一定义了CONDENSE（对话压缩）、EXPLAIN（解释代码）、FIX（修复问题）、IMPROVE（改进代码）、ADD_TO_CONTEXT（加入上下文）等模板，supportPrompt.get()会优先读取用户自定义模板，未定义时才回退到默认模板。

3.2 修改增强模板

打开设置面板（点击 Roo Code 面板中的齿轮图标），进入Prompts（提示词）标签页，在下拉菜单中选择ENHANCE，即可查看并编辑增强提示词模板。你可以按需修改，使其更贴合目标模型的提示词风格。

3.3 自定义模板如何生效

从测试用例 enhance-prompt.spec.ts 可以看到自定义模板的解析逻辑：当提供自定义模板"You are a custom prompt enhancer\n\n${userInput}"时，supportPrompt.create("ENHANCE", { userInput: "Test prompt" }, customPrompts)会先把${userInput}替换为实际输入，再将完整文本交给singleCompletionHandler，最终调用底层 API 的completePrompt方法。

3.4 测试你的自定义提示词

Prompts 设置界面内置了测试区：

1. 编辑完增强提示词后，找到 "Test Enhancement" 区域；
2. 输入一条示例提示词；
3. 点击 "Test" 预览你的自定义模板实际增强效果；
4. 根据结果继续调整模板。

对应 UI 实现在 PromptsSettings.tsx，它会监听类型为enhancedPrompt的返回消息并展示增强预览。

四、API 配置：为增强单独指定 Provider

默认情况下，Enhance Prompt 复用当前 Roo Code 任务所使用的 API 配置；但你也可以为增强功能单独指定一个 Provider/模型：

1. 打开 Roo Code 设置；
2. 进入Prompts标签页；
3. 在下拉菜单选择ENHANCE；
4. 在 "API Configuration" 下拉框中选择一个已有的 API 配置，此后所有增强请求都会发往该配置对应的 Provider 与模型。

底层实现位于 messageEnhancer.ts：enhanceMessage会先检查是否设置了enhancementApiConfigId，若该 ID 能在listApiConfigMeta中找到，就通过providerSettingsManager.getProfile({ id })取回该配置并使用；否则回退到当前任务的apiConfiguration。UI 上的选择结果通过enhancementApiConfigId消息类型持久化（见 webviewMessageHandler.ts 中的enhancementApiConfigId分支）。

五、上下文感知增强：让历史对话参与改写

5.1 工作原理

当开启"任务历史上下文"后，增强过程会把当前会话的最近 10 条消息作为上下文提供给模型，使其能够：

• 理解你正在进行的实际工作；
• 与之前的讨论保持一致；
• 避免提出无关或错误的增强建议；
• 给出更具针对性的提示词改进。

5.2 开启方式

1. 打开 Roo Code 设置；
2. 进入Prompts标签页；
3. 选择ENHANCE；
4. 勾选或取消 "Include task history in enhancement" 选项。关闭后，增强只基于当前输入的提示词，不携带任何会话上下文。

5.3 源码视角的实现细节

在 messageEnhancer.ts 中，extractTaskHistory方法负责从ClineMessage[]中筛选可用消息：

• 仅保留两类消息：用户消息（type === "ask"且含文本）与助手文本消息（type === "say"且say === "text"）；
• 通过.slice(-10)只取最近 10 条，避免上下文爆炸；
• 每条消息按User:/Assistant:前缀拼接，且单条内容截断到 500 字符（超出部分以...结尾）。

随后，enhanceMessage会把历史拼接进待增强文本：${text}\n\nUse the following previous conversation context as needed:\n${taskHistory}，再交给supportPrompt.create("ENHANCE", ...)组装完整请求（见 messageEnhancer.ts）。

六、底层调用链：从魔棒图标到增强文本

综合上面的分析，Enhance Prompt 的完整链路是：

1. 前端：ChatTextArea.tsx 的魔棒按钮触发handleEnhancePrompt，通过vscode.postMessage({ type: "enhancePrompt", text })发往扩展宿主；
2. 宿主消息分发：webviewMessageHandler.ts 的enhancePrompt分支读取全局状态（apiConfiguration、customSupportPrompts、enhancementApiConfigId、includeTaskHistoryInEnhance等），调用MessageEnhancer.enhanceMessage；成功后把结果以enhancedPrompt消息回传 Webview，失败则弹出错误提示；
3. 增强逻辑：messageEnhancer.ts 负责选择 API 配置、拼装上下文历史、调用supportPrompt.create生成完整提示词，最后交给singleCompletionHandler；
4. 轻量完成请求：single-completion-handler.ts 是整个机制的关键——它不创建完整的 Cline 任务或任务历史，只用 API 的单次补全能力完成增强。它会校验输入非空、存在有效的 API 配置，并检测 handler 是否实现了completePrompt方法，若 Provider 不支持则抛出 "The selected API provider does not support prompt enhancement"；
5. Provider 层：以 OpenAI 兼容 Provider 为例，base-openai-compatible-provider.ts 的completePrompt会构造单条user消息的 Chat Completions 请求，按需附带 reasoning 参数，最终返回response.choices[0].message.content。

对应的单元测试 enhance-prompt.spec.ts 覆盖了默认模板增强、自定义模板增强、空输入报错（"No prompt text provided"）、缺少 API 配置报错（"No valid API configuration provided"）、不支持的 Provider 报错，以及 API 错误传播等场景，可作为理解行为边界的参考。

七、视觉反馈与 UI 细节

• 按钮外观：魔棒图标默认 60% 透明度，悬停时变为 100% 不透明；位于输入框右上角，并带有用于键盘可达性的焦点环；
• 加载状态：处理增强请求期间，魔棒图标旋转，提供明确的"正在工作"反馈；
• 工具提示：悬停显示 "Enhance prompt with additional context"，帮助新用户理解按钮用途。

八、限制与最佳实践

• 实验性功能：提示词增强目前属于实验性能力，增强质量会随请求复杂度和底层模型能力而变化；
• 务必审查：发送前一定确认增强结果符合你的意图，Roo 的改写有时可能与你的本意有偏差；
• 可迭代使用：可以多次点击增强按钮，逐步迭代打磨提示词；
• 不能替代清晰的原始输入：增强是辅助手段，从源头上写出清晰、具体的需求仍然重要。

九、OpenAI 兼容 Provider 的模型列表支持

9.1 功能背景

在 2.2.33 之前，Roo Code 的模型选择主要依赖预置的模型清单。对于自定义 Base URL 的 OpenAI 兼容服务（如自建网关、本地推理服务），维护一份完整的模型清单既不现实也不及时。v2.2.33 引入的模型列表支持，允许从 Provider 动态拉取可用模型。

9.2 核心实现：双层模型缓存

模型拉取的统一入口是 modelCache.ts。getModels()采用两层缓存策略（见该文件第 100-141 行的注释与实现）：

1. 内存缓存（Memory cache）：短期存储，供同一次运行内快速命中；
2. 文件缓存（File cache）：以${router}_models.json为文件名写入全局存储目录，长期复用，避免每次启动都发起网络请求。

写入文件使用safeWriteJson，且只有模型数量大于 0 时才写入缓存——注释明确指出："空结果可能意味着 API 故障而非真的没有模型"，防止把失败的响应持久化。读取时会先用 Zod schema 校验缓存结构（modelRecordSchema），损坏的缓存会被安全跳过。

9.3 各 Provider 的模型端点

fetchModelsFromProvider通过switch按 Provider 分发请求（见 modelCache.ts）：

以 openrouter.ts 的getOpenRouterModels为例，它请求/models端点，用 Zod 校验响应结构，遍历模型列表时跳过输出模态为image的图片生成模型，再通过parseOpenRouterModel转换为统一的ModelInfo。

而 LM Studio 与 Vercel AI Gateway 的取数逻辑（见 lmstudio.ts 及其测试中的断言）直接请求${baseUrl}/v1/models，这正是 OpenAI 兼容 Provider 的标准模型列表端点格式，也是本次"OpenAI 兼容模型列表"能力的通用基础。

9.4 刷新与并发保护

refreshModels()用于强制刷新、绕过缓存：它使用inFlightRefreshMap 记录进行中的刷新请求，避免同一 Provider 的并发刷新互相覆盖（见 modelCache.ts）。刷新失败时，如果缓存数据存在且更完整，会回退到既有缓存，保证用户始终有可用的模型列表。模型缓存的单元测试位于 modelCache.spec.ts，覆盖了按 Provider 分发、缓存命中与刷新等关键路径。

说明：模型列表拉取是一个持续演进的能力。在后续版本中，该机制不断扩展（例如 CLI 中apps/cli/src/commands/cli/list.ts也提供了模型列表命令），本文讨论的代码以当前仓库实际内容为准。

十、总结

Roo Code 2.2.33 用两个看似轻量的改动，分别提升了"发送前"与"选择时"两个环节的体验：

• Enhance Prompt把提示词工程的部分工作内置到聊天输入框：点击魔棒即可让模型按可自定义的模板改写请求，支持独立 API 配置与最近 10 条会话历史上下文；其实现以singleCompletionHandler的轻量补全机制为核心，避免创建完整任务的开销；
• OpenAI 兼容 Provider 模型列表通过 modelCache.ts 的双层缓存与各 Provider 端点适配，让模型下拉菜单数据可以动态刷新，并以内存量与文件量双重保障可用性。

如果你想进一步验证或自定义这两个功能，可以依次阅读 Enhance Prompt 功能文档、v2.2 系列发布说明，再对照 messageEnhancer.ts、support-prompt.ts、single-completion-handler.ts 与 modelCache.ts 的源码，即可获得从 UI 到 API 的完整认知。

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