Roo Code 3.7.5 版本解析：Thinking 模型配置更新与输入输出成本修正实践

Roo Code 3.7.5 版本解析：Thinking 模型配置更新与输入输出成本修正实践

【免费下载链接】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.7.5 的官方更新说明（apps/docs/docs/update-notes/v3.7.5.md）为核心脉络，聚焦该版本引入的独立:thinking模型版本机制、thinking budget（思考预算）配置、上下文窗口计算与输入/输出成本解析修复，以及"按住 Shift 拖拽文件实现 @-mention"的新交互，并结合仓库源码还原其底层实现原理。读完本文，你将掌握：如何在 Provider 设置中正确选择 thinking 模型版本并调整思考预算滑块、理解上下文窗口与 max_tokens 的约束关系、看懂模型成本计算的修正逻辑，以及熟练使用文件 @-mention 的拖拽操作。

版本概览

Roo Code 3.7.5 于 2025-02-26 发布，是一次聚焦"推理/思考模型（thinking models）配置体验"的更新。官方 release notes 将其要点概括为三部分：

• 模型配置更新：为 Anthropic 与 OpenRouter 的 Sonnet 3.7 模型引入独立的:thinking版本，以支持可配置的思考预算（thinking budget）；之前使用思考功能的用户需要在 Provider 设置中选择这些新模型版本，并按需调整思考预算滑块。
• Bug 修复：修复上下文窗口计算错误（"input length and max_tokens exceed context limit"）、模型选择器 UI 的多个问题、以及模型输入/输出成本解析问题（后两项由社区成员 System233 贡献）。
• 功能亮点：新增在 File Explorer 中按住 Shift 拖拽文件到聊天输入框、实现 @-mention 文件的能力。

下文将逐一展开，并在每个环节给出对应源码证据，方便读者按图索骥深入阅读。

一、Thinking 模型配置更新：独立:thinking模型版本

1.1 为什么要引入:thinking后缀版本

Claude 3.7 Sonnet 是 Anthropic 首款"混合推理（Hybrid Reasoning）"模型：它既能像常规模型一样快速应答，也能开启扩展思考（extended thinking）模式，在给出最终答案前进行逐步推理。思考模式消耗的 token 由"思考预算"（thinking budget，即budget_tokens）控制。

在 3.7.5 之前，Roo Code 无法针对同一模型区分"是否开启思考"以及"思考预算多少"。为此，3.7.5 在模型注册表中引入了带:thinking后缀的虚拟模型 ID，用于显式声明"这是一个必须开启推理预算的混合推理模型"，从而把"开启思考"与"思考预算可配置"变成模型级的能力。

在仓库中可以看到该虚拟模型的具体定义（packages/types/src/providers/anthropic.ts）：

"claude-3-7-sonnet-20250219:thinking": { maxTokens: 128_000, // 需向 API 传入 beta 标志解锁，否则为 64k contextWindow: 200_000, supportsImages: true, supportsPromptCache: true, inputPrice: 3.0, // 每百万输入 token 3 美元 outputPrice: 15.0, // 每百万输出 token 15 美元 cacheWritesPrice: 3.75, cacheReadsPrice: 0.3, supportsReasoningBudget: true, requiredReasoningBudget: true, // 关键：强制要求启用推理预算 },

对照不带后缀的普通版本"claude-3-7-sonnet-20250219"（packages/types/src/providers/anthropic.ts）：

"claude-3-7-sonnet-20250219": { maxTokens: 8192, // 已提供 :thinking 虚拟模型，故不再设置 supportsReasoningBudget contextWindow: 200_000, supportsImages: true, supportsPromptCache: true, inputPrice: 3.0, outputPrice: 15.0, cacheWritesPrice: 3.75, cacheReadsPrice: 0.3, },

两者的差异一目了然：

1.2 API 层的后缀剥离与 beta 标志注入

:thinking只是 Roo Code 内部的虚拟模型 ID，Anthropic API 实际识别的模型 ID 并不带该后缀。因此 Provider 层在构造请求时必须做"拆壳"处理。见 src/api/providers/anthropic.ts：

// `:thinking` 后缀表示这是一个 "Hybrid"（混合）推理模型， // 且必须启用推理（reasoning）。Anthropic API 实际识别的模型 ID 不含此后缀。 return { id: id === "claude-3-7-sonnet-20250219:thinking" ? "claude-3-7-sonnet-20250219" : id, info, betas: id === "claude-3-7-sonnet-20250219:thinking" ? ["output-128k-2025-02-19"] : undefined, ...params, }

这段代码做了两件事：

1. 将claude-3-7-sonnet-20250219:thinking还原为 API 识别的claude-3-7-sonnet-20250219；
2. 当选择了:thinking版本时，自动附加 beta 标志output-128k-2025-02-19，这正是该虚拟模型maxTokens: 128_000能被解锁的原因（否则上限为 64k）。

1.3 OpenRouter 侧的:thinking模型

OpenRouter 同样以:thinking后缀暴露这类混合推理模型。在 packages/types/src/providers/openrouter.ts 中，Roo Code 维护了一个"必须启用推理预算"的模型集合：

// 带有 `:thinking` 后缀的（虚拟）模型 ID 总是要求启用推理预算， // 为保证向后兼容，这些模型仍然必须开启预算。 // 注意：不应再向此集合添加新模型。 export const OPEN_ROUTER_REQUIRED_REASONING_BUDGET_MODELS = new Set([ "anthropic/claude-3.7-sonnet:thinking", "google/gemini-2.5-pro", "google/gemini-2.5-flash-preview-05-20:thinking", ])

同时OPEN_ROUTER_REASONING_BUDGET_MODELS（packages/types/src/providers/openrouter.ts）则维护了"支持但可开关推理预算"的模型列表，并刻意将anthropic/claude-3.7-sonnet:thinking等必需模型一并纳入，因为必需集合的优先级更高。OpenRouter 场景下思考预算通过max_tokens参数透传（详见下文 2.3 节）。

1.4 升级注意事项（针对既有 thinking 用户）

按 release notes 的说明，3.7.5 之后：

• 必须重新选择模型：此前使用思考功能的用户，需要在 Provider 设置中手动切换到带:thinking后缀的新模型版本（例如从claude-3-7-sonnet切到claude-3-7-sonnet:thinking）；
• 调整思考预算滑块：切换后按任务复杂度重新设置 thinking budget 滑块；
• 普通模型行为不变：不带后缀的普通版本维持原有快速应答行为，不会因本次更新而强制开启思考。

二、思考预算（Thinking Budget）的底层计算规则

2.1 触发条件：shouldUseReasoningBudget

是否启用 thinking budget，由shouldUseReasoningBudget统一裁决（src/shared/api.ts）：

export const shouldUseReasoningBudget = ({ model, settings, }: { model: ModelInfo settings?: ProviderSettings }): boolean => !!model.requiredReasoningBudget || (!!model.supportsReasoningBudget && !!settings?.enableReasoningEffort)

即满足下列任一条件即启用：

1. 模型声明了requiredReasoningBudget（如claude-3-7-sonnet-20250219:thinking，强制开启，与用户设置无关）；
2. 模型支持思考预算（supportsReasoningBudget）且用户在设置中开启了enableReasoningEffort。

2.2 预算的默认值与钳制规则

预算数值的计算集中在 src/api/transform/model-params.ts，其规则可以概括为"先取默认、再按上下限钳制"：

// 若未显式指定 customMaxThinkingTokens，则使用默认值。 // Gemini 2.5 Pro 默认 128，其他模型默认 8192 const defaultThinkingTokens = isGemini25Pro ? GEMINI_25_PRO_MIN_THINKING_TOKENS : DEFAULT_HYBRID_REASONING_MODEL_THINKING_TOKENS reasoningBudget = customMaxThinkingTokens ?? defaultThinkingTokens // 推理预算不得超过 maxTokens 的 80% if (maxTokens && reasoningBudget > Math.floor(maxTokens * 0.8)) { reasoningBudget = Math.floor(maxTokens * 0.8) } // 推理预算不得低于最小 token 数 // Gemini 2.5 Pro 最小为 128，其他模型最小为 1024 const minThinkingTokens = isGemini25Pro ? GEMINI_25_PRO_MIN_THINKING_TOKENS : 1024 if (reasoningBudget < minThinkingTokens) { reasoningBudget = minThinkingTokens } // 混合推理模型要求 temperature 固定为 1.0 temperature = 1.0

默认值常量定义于 src/shared/api.ts：

export const DEFAULT_HYBRID_REASONING_MODEL_MAX_TOKENS = 16_384 export const DEFAULT_HYBRID_REASONING_MODEL_THINKING_TOKENS = 8_192 export const GEMINI_25_PRO_MIN_THINKING_TOKENS = 128

可归纳为一张实用速查表：

对应测试用例可参考 src/api/transform/tests/reasoning.spec.ts，其中覆盖了budget_tokens正常透传、0 值、超大值等边界情况。

2.3 预算如何下发到各家 API

最终构造出的 reasoning 参数因厂商而异，全部集中在 src/api/transform/reasoning.ts：

• Anthropic（reasoning.ts#L107-L112）：

export const getAnthropicReasoning = ({ model, reasoningBudget, settings, }: GetModelReasoningOptions): AnthropicReasoningParams | undefined => shouldUseReasoningBudget({ model, settings }) ? { type: "enabled", budget_tokens: reasoningBudget! } : undefined

即生成 Anthropic 原生thinking: { type: "enabled", budget_tokens }参数（测试断言见 src/api/providers/tests/anthropic.spec.ts 附近，实际样例为thinking: { type: "enabled", budget_tokens: 4096 }）。

• OpenRouter（reasoning.ts#L44-L56）：通过max_tokens字段携带预算{ max_tokens: reasoningBudget }；
• OpenAI 系 / Gemini：OpenAI 系走reasoning_effort，Gemini 走thinkingConfig+thinkingLevel，属于另一套 effort 机制（见 reasoning.ts#L114-L130），不在 3.7.5 的思考预算范围内，此处不展开。

2.4 会话历史中的 reasoning 块过滤

开启思考后，流式响应中会包含thinking/thinking_delta内容，Provider 层将其转换为{ type: "reasoning" }块（见 src/api/providers/anthropic.ts 对thinking与thinking_delta分支的处理）。而内部推理内容不会被回传给模型：在 src/api/providers/tests/anthropic.spec.ts#L339-L410 的 "reasoning block filtering" 测试组中，验证了发送到 API 的消息会过滤掉历史对话中的reasoning块，且当过滤后消息为空时整条消息会被丢弃。这解释了为什么切换 thinking 模型后历史会话依然能安全复用，不会把推理痕迹泄露回上下文。

三、Bug 修复一：上下文窗口计算错误

release notes 中修复的 "input length and max_tokens exceed context limit" 报错，根因在于 max_tokens 与上下文窗口（context window）之间的约束关系处理不当。修复后，Roo Code 对输出 token 上限的判定遵循更严谨的规则，核心逻辑位于 src/shared/api.ts 的getModelMaxOutputTokens：

export const getModelMaxOutputTokens = ({ modelId, model, settings, format, }: { modelId: string model: ModelInfo settings?: ProviderSettings format?: "anthropic" | "openai" | "gemini" | "openrouter" }): number | undefined => { if (shouldUseReasoningBudget({ model, settings })) { return settings?.modelMaxTokens || DEFAULT_HYBRID_REASONING_MODEL_MAX_TOKENS } const isAnthropicContext = modelId.includes("claude") || format === "anthropic" || (format === "openrouter" && modelId.startsWith("anthropic/")) // 对于 "Hybrid" 推理模型，在 Anthropic 场景下丢弃其模型自带 maxTokens if (model.supportsReasoningBudget && isAnthropicContext) { return ANTHROPIC_DEFAULT_MAX_TOKENS } ... }

关键规则包括：

1. 启用思考预算时：使用用户配置的modelMaxTokens，缺省回退到DEFAULT_HYBRID_REASONING_MODEL_MAX_TOKENS = 16_384；
2. Anthropic 上下文中的混合推理模型：即使模型注册表写了 128k 的 maxTokens，也统一回退到ANTHROPIC_DEFAULT_MAX_TOKENS = 8192，避免 128k 输出上限与 200k 上下文窗口叠加时触发超限错误；
3. 其余场景下，max_tokens 取模型声明值与上下文窗口的合理比例。

getModelMaxOutputTokens的行为在 src/shared/tests/api.spec.ts 中有大量参数化测试，例如：当 maxTokens 超过上下文窗口 20% 时会被钳制（api.spec.ts#L101-L127），以及"恰好等于 20% 阈值时不做钳制"（api.spec.ts#L142-L159）等边界场景。

对读者而言的实操含义：若在聊天中遇到 "input length and max_tokens exceed context limit"，升级到 3.7.5 后应首先检查两处——当前模型的 max output tokens 设置是否过大，以及是否误选了带超大 maxTokens 的 thinking 模型；修复逻辑会自动将混合推理模型的输出上限钳制到合理区间。

四、Bug 修复二：模型输入/输出成本解析

成本计算依赖模型注册表中的inputPrice/outputPrice/cacheWritesPrice/cacheReadsPrice（单位均为"每百万 token 的美元价格"）。3.7.5 修复了这部分价格解析的偏差，尤其是 thinking 模型——它额外消费推理 token，若价格字段解析错误，费用统计会严重失真。

成本计算核心在 src/shared/cost.ts：

inputPrice: modelInfo.inputPrice !== undefined && pricing.inputPriceMultiplier !== undefined ? modelInfo.inputPrice * pricing.inputPriceMultiplier : modelInfo.inputPrice, outputPrice: modelInfo.outputPrice !== undefined && pricing.outputPriceMultiplier !== undefined ? modelInfo.outputPrice * pricing.outputPriceMultiplier : modelInfo.outputPrice,

以及：

const baseInputCost = ((modelInfo.inputPrice || 0) / 1_000_000) * inputTokens const outputCost = ((modelInfo.outputPrice || 0) / 1_000_000) * outputTokens

修复点体现在：

1. 支持价格倍率（multiplier）：可通过倍率调整实际计费价格，未配置倍率时回退到注册表原值；
2. 统一的百万 token 归一化：所有价格统一按"每百万 token"换算，避免量级不一致导致的偏差。

在模型注册表中，以:thinking虚拟模型为例（packages/types/src/providers/anthropic.ts#L132-L137），其输入/输出价格与普通版本（anthropic.ts#L144-L147）一致（$3/$15 每百万 token），但思考过程产生的推理 token 会计入输出侧的实际用量。OpenRouter 侧还维护了支持提示缓存的模型白名单（packages/types/src/providers/openrouter.ts#L21-L56），其中就包含anthropic/claude-3.7-sonnet:thinking，确保启用 prompt caching 的 thinking 模型在成本统计时能正确计 cache 读写费用。

实操含义：升级后，任务历史中的 token 消耗与费用估算会恢复准确；若你手动在 Provider 配置中调整过价格，请确认与 3.7.5 的倍率逻辑不冲突。

五、Bug 修复三：模型选择器（Model Picker）UI

3.7.5 还修复了模型选择器的多处 UI 问题（由 System233 贡献）。模型选择器实现在 webview-ui/src/components/settings/ModelPicker.tsx，它是一个支持搜索、自定义模型输入与自动拉取模型的弹层组件：

• 支持按关键字过滤模型列表（searchPlaceholder/noMatchFound，ModelPicker.tsx#L231-L248）；
• 未匹配时允许直接以自定义 model id 使用（useCustomModel，ModelPicker.tsx#L275）；
• 针对支持列表自动拉取的 Provider 显示简化说明文案（ModelPicker.tsx#L291-L308）。

结合 3.7.5 新增的:thinking模型，此修复的实际意义在于：claude-3-7-sonnet-20250219:thinking这类虚拟模型现在能正确显示在可选列表中，并且选择/切换后 UI 状态与设置面板保持一致。模型选择器只在"通用模型选择"场景启用（判断逻辑见 webview-ui/src/components/settings/ApiOptions.tsx#L706-L708 中的shouldUseGenericModelPicker）。

六、功能亮点：Shift + 拖拽实现文件 @-mention

3.7.5 新增：在文件资源管理器（File Explorer）中按住 Shift 键拖拽文件到聊天输入框，即可将文件以 @-mention 形式插入输入内容。这在长对话中尤其有用——不用手动输入路径，也不会误触发普通文件/图片拖拽。

6.1 交互判定：按住 Shift 才允许拖放

拖拽区事件处理位于 webview-ui/src/components/chat/ChatTextArea.tsx#L954-L980：

onDrop={handleDrop} onDragOver={(e) => { // 只有在按下 Shift 键时才允许放置文件/图片。 if (!e.shiftKey) { setIsDraggingOver(false) return } e.preventDefault() setIsDraggingOver(true) e.dataTransfer.dropEffect = "copy" }}

即dragOver阶段就拦截：未按 Shift 时直接取消拖放高亮并阻止 drop，按下 Shift 才preventDefault()并显示可放置状态。

6.2 落盘处理：路径转 @-mention

handleDrop（ChatTextArea.tsx#L809-L912）的核心流程：

1. 优先读取拖拽携带的文本数据text/plain或 VS Code 的资源列表application/vnd.code.uri-list（同时兼容从编辑器标签页拖出的场景）；
2. 按换行切分得到多文件路径列表，逐行调用convertToMentionPath(line, cwd)转换为 mention 格式，并以空格分隔插入光标位置；
3. 若无文本型路径数据，则回退到dataTransfer.files处理图片：仅接受png/jpeg/webp，通过FileReader转成 Data URL 后经vscode.postMessage({ type: "draggedImages", dataUrls })发送给扩展侧（ChatTextArea.tsx#L855-L899）。

多语言文案也已同步更新，例如中文为"Shift+拖拽文件/图片"、日文为"ファイルをドラッグするにはShiftキーを押したまま"（见 webview-ui/src/i18n/locales/zh-CN/chat.json#L118-L119 与 webview-ui/src/i18n/locales/ja/chat.json#L118-L119），输入框占位符中也会按shouldDisableImages动态提示支持的文件类型（ChatTextArea.tsx#L926）。

6.3 使用步骤

1. 在 VS Code 的 File Explorer 中选中一个或多个文件；
2. 按住 Shift 键，将文件拖入 Roo Code 聊天输入框；
3. 松开后，路径会自动转换为@/path/to/file形式的 mention 并插入光标处，可继续编辑后发送；
4. 若拖入的是 png/jpeg/webp 图片且模型支持图片输入，则会作为图片附件发送。

七、总结

Roo Code 3.7.5 虽是小版本，却完成了"思考模型配置体系"的定型：

1. 模型层：以:thinking后缀虚拟模型承载"必须开启推理"的语义，Anthropic API 侧自动剥离后缀并注入 beta 标志（src/api/providers/anthropic.ts#L344-L353），OpenRouter 侧通过必需/可选两个集合管理推理预算（packages/types/src/providers/openrouter.ts#L65-L90）；
2. 参数层：shouldUseReasoningBudget决定是否启用，model-params.ts完成默认值与 80%/1024 上下限钳制，reasoning.ts按厂商生成budget_tokens/max_tokens等最终参数；
3. 可靠性：上下文窗口计算修正解决了 "input length and max_tokens exceed context limit" 报错，成本解析修复保证费用统计准确；
4. 交互层：Shift + 拖拽让文件 @-mention 与图片拖拽各归其位，互不干扰。

对于仍在思考模型与快速模型之间切换的用户，记住一条主线即可：要扩展思考就选带:thinking后缀的版本并调节思考预算滑块，要快速应答就留在普通版本，其余细节（预算钳制、beta 解锁、成本统计）均由 3.7.5 的修复逻辑自动兜底。

相关文件索引

• 更新说明原文：apps/docs/docs/update-notes/v3.7.5.md
• Anthropic 模型注册表（含:thinking虚拟模型）：packages/types/src/providers/anthropic.ts
• OpenRouter 推理预算模型集合：packages/types/src/providers/openrouter.ts
• 预算裁决与输出上限计算：src/shared/api.ts
• 预算钳制与参数组装：src/api/transform/model-params.ts
• 各厂商 reasoning 参数生成：src/api/transform/reasoning.ts
• Anthropic Provider（后缀剥离与 beta 注入）：src/api/providers/anthropic.ts
• 成本计算：src/shared/cost.ts
• 模型选择器 UI：webview-ui/src/components/settings/ModelPicker.tsx
• Shift+拖拽 @-mention 实现：webview-ui/src/components/chat/ChatTextArea.tsx

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