grok-build 0.2.36 版本解读：MCP 大结果智能落盘、doom-loop 误判修复与推理内容压缩崩溃修复-育师

人工智能
大模型
AI Agent
代码智能体
CLI
工具调用
MCP Clients

【免费下载链接】grok-build

SpaceXAI's coding agent harness and TUI. Fullscreen, mouse interactive, extensible.

项目地址：https://gitcode.com/gh_mirrors/gr/grok-build

导读

本文以 grok-build 仓库中 xai-grok-shell 0.2.36 变更日志为线索，深入剖析该版本的 1 项功能增强与 2 项缺陷修复：大型 MCP 工具结果以正确扩展名落盘并附带查询提示、并行工具调用批量失败时不再触发 doom-loop 误判终止、恢复含推理（reasoning）内容的会话时自动压缩不再崩溃。读完本文，你将理解这三处变更的触发场景、底层实现原理与相关配置项，并能据此排查同类问题。

版本变更总览

0.2.36 是 xai-grok-shell（grok-build 的核心 shell 组件，也是整个仓库体量最大的 crate，源码位于 crates/codegen/xai-grok-shell/src）的一个小版本。完整的机器可读变更条目记录在同目录下的 0.2.36.json 中，三项变更均标记为breaking_change: false，即对既有配置与行为向后兼容：

类别	变更内容	对应源码/测试
Features	大型 MCP 工具结果以正确扩展名保存，模型获得更好的查询提示	mcp_truncate.rs
Fixes	修复同一批次中多个并行工具调用一起失败时导致的 doom-loop 误判终止	tool_calls.rs
Fixes	修复恢复包含推理内容的会话时自动压缩可能发生的崩溃	session_compact_reasoning_compaction_regression_tests.rs

功能增强：大型 MCP 工具结果的智能落盘与查询提示

背景：超大结果为什么必须落盘

在编码 Agent 的日常使用中，MCP 服务器可能返回非常大的工具结果（例如 Sentry 附件、base64 资源、长日志）。这些超大载荷如果完整进入聊天状态（chat state），会显著抬高 token 估算、触发过早的自动压缩（auto-compact），甚至撑爆上下文窗口。

为此，mcp_truncate.rs 实现了"内联限额 + 全文落盘"的双层策略：模型上下文里只保留截断后的预览，完整结果写入会话目录下的mcp/子目录，供模型按需用 shell 工具查询。0.2.36 的改进在于——落盘文件不再一律使用固定扩展名，而是按内容类型智能选择.json或.txt，并且截断消息中会附带针对内容类型的"如何查询这份文件"的提示。

扩展名分类：McpDumpKind

落盘扩展名由McpDumpKind::classify()决定（mcp_truncate.rs），它从两个维度对文本分类：

是否合法 JSON：去掉首尾空白后以{或[开头，且serde_json::from_str::<IgnoredAny>能成功解析；
是否存在超长行：任一行长度超过LONG_LINE_BYTES = 2000字节。

两个维度组合出四种类型，映射到两种扩展名（extension()）：

分类	判定条件	扩展名
`LongLineJson`	合法 JSON 且含超长行	`.json`
`Json`	合法 JSON 且无超长行	`.json`
`LongLineText`	非 JSON 但含超长行	`.txt`
`Other`	普通文本	`.txt`

这一改动的意义在于：此前（0.2.36 之前）落盘文件统一使用一个固定扩展名，JSON 结果如果被存成.txt，模型用grep/read_file查询时无法利用 JSON 结构化查询工具（如 jq）；而普通文本若被存成.json，同样会让模型误以为可以按 JSON 结构查询。正确的扩展名让模型可以"按图索骥"。

落盘路径与文件名安全

截断发生时，完整输出被写入{session_folder}/mcp/{sanitized_call_id}.{ext}（truncate_mcp_text）。其中：

session_folder来自会话资源中的SessionFolder；
文件名中的 call_id 经过sanitized_stem()清洗（mcp_truncate.rs）：仅保留 ASCII 字母数字与-/_，其余字符一律替换为_。这样即使 wire 传入的 id 含/或..（服务端仅校验非空），也无法逃逸出会话的mcp/目录——这是一个明确的路径穿越防护。

写文件失败不会导致工具调用失败：仅记录一条tracing::warn!（Failed to write full MCP output to file）并继续返回截断预览，属于尽力而为（best-effort）设计。

查询提示（hints）：引导模型用正确的工具

落盘之后，截断消息会追加一段由McpDumpKind::steer()生成的提示（mcp_truncate.rs），按内容类型区分引导策略：

LongLineJson：提示"完整输出是带超长行的合法 JSON，grep/read_file对它无效——请用{shell}查询已保存的文件"，并附上 JSON 查询工具的示例子句（examples_clause(&tools.json_tools())）；
Json：提示"完整输出是合法 JSON，已保存到上面提到的文件，请用{shell}查询它"，同样附 JSON 工具示例；
LongLineText：提示"输出含超长行，grep/read_file无效——请用{shell}切片/搜索已保存的文件"，附文本工具示例；
Other：不生成提示。

QueryTools::detect()负责探测当前工具集里可用的 JSON / 文本查询工具；shell工具名则从TemplateRenderer按ToolKind::Execute解析，缺省回退为bash。最终注入模型上下文的消息格式为：

{截断后的预览} [MCP output truncated: showing first 20.0 KB of 1.2 MB. Full output written to: {path}.{hint}]

截断阈值配置与优先级

内联限额的默认值是MCP_MAX_OUTPUT_BYTES = 20_000字节（注意：按字节而非 token 截断，因为截断实现是字节导向的truncate_str）。有效限额的解析优先级从高到低为（mcp_truncate.rs 与 resolve/mcp.rs）：

TruncationCfg资源：按工具/MCP 细粒度设置（例如某个仓库级[mcp] max_output_bytes配置，由 shell 按会话种子注入）；
宿主进程注入值：shell 在启动/远程配置刷新时一次性解析完整栈并调用set_mcp_max_output_bytes()写入进程级原子变量；
环境变量：宿主未注入（原子值为 0）时，读取GROK_MAX_MCP_OUTPUT_BYTES（Grok 原生，两者同时设置时优先）或MAX_MCP_OUTPUT_BYTES；
内置默认值20_000。

shell 侧的完整解析在 resolve/mcp.rs：

配置文件键为 TOML 的[mcp] max_output_bytes（正整数），可出现在requirements.toml或生效的config.toml中；
全局路径的优先级为：requirements.toml> 环境变量 >config.toml> 远程设置 > 默认值；
项目级路径（.grok/config.toml链，从 git 根到 cwd，越深者胜出）受文件夹信任门控（folder_trust::project_scope_allowed）保护——不信任的检出不得提高限额，否则仓库可以借此塞入超大内容抬高成本。

与 MCP 参数文件输入的关系

同样值得注意的关联实现是 MCP 大参数的文件化输入提示（mcp.rs）：当 MCP 参数过大时，提示模型"准备一份完整的 UTF-8 JSON 文件，并用use_tool以{"file": "/tmp/mcp-call.json"}形式传入"。这与本版本"大结果落盘 + 查询提示"构成对称设计：大输入走文件、大输出落盘文件，共同把 MCP 交互中的超大载荷从上下文窗口中剥离。

缺陷修复：并行工具调用批量失败不再触发 doom-loop 误判

doom-loop 机制回顾

doom-loop（死循环）检测是采样链路中的一项生成循环防护：推理 API 在流式/v1/responses请求上报告检测器命中的触发标签，wire 契约定义在 xai-grok-sampling-types/src/doom_loop.rs，触发标签语法为：

tail_repetition:{threshold}@{channel}（尾部重复，channel 如thinking/response）；
exact_repetition:{tokens}x{copies}@{channel}（精确重复）；
low_logprob@{channel}（低概率输出）。

报告经两种渠道到达客户端：非标准的流中 SSE 事件response.doom_loop_check（携带累计触发集），以及终态响应对象上的doom_loop_check字段。客户端由 xai-grok-sampler/src/doom_loop.rs 中的DoomLoopSignalCollector负责吸收与去重（同一尝试内最多收集 64 个信号、单个信号原始标签最多 256 字节），再由DoomLoopRecoveryPolicy判定置信度并决定是否中止当前尝试、触发重采样恢复。

误判根因：错误连击被当作循环信号

0.2.36 修复前的隐患在于：会话侧除了服务端报告的触发标签外，本地统计的"错误次数连击"（error-count streaks）也会被喂给 doom-loop 检测器。当模型在单个批次中并行发起多个工具调用、而这些调用恰好一起失败（例如某个服务不可用、权限批量拒绝、临时网络故障）时，会瞬间积累一大批工具失败记录，本地检测器据此误判模型陷入了死循环，从而错误地终止会话——这正是 changelog 所说 "false-positive doom-loop terminations when many parallel tool calls fail together in one batch" 的场景。

修复后，工具失败与 doom-loop 检测彻底解耦。在 tool_calls.rs 中，handle_tool_error的文档注释明确写道：

Tool failures are not fed to the doom-loop detector (error-count streaks were removed). This therefore never warns/terminates and returns no deferred follow-ups today.

即：工具失败不再进入 doom-loop 检测器（错误连击逻辑已被移除），handle_tool_error现在只负责记录遥测（signals_handle().record_tool_failure()）、把失败结果以ConversationItem::tool_result写回聊天状态，以及推送ToolCallStatus::Failed会话更新，而不会再产生"警告/终止"之类的下游动作。

工具失败仍然会被如实统计——在 signals.rs 中，SignalEvent::RecordToolFailure会递增tool_failure_count与error_count（"工具失败也计为错误"），但这些计数现在只服务于遥测/统计（如每轮增量delta_tool_failures、成功率delta_successful_tool_uses等指标），不再参与循环判定。doom-loop 判定的唯一事实来源回归到服务端上报的触发标签。

恢复策略参数（DoomLoopRecoveryPolicy）

doom-loop 恢复策略由DoomLoopRecoveryPolicy控制（doom_loop.rs），相关可调参数与取值范围如下：

参数	语义	默认	范围
`max_threshold`	仅在`tail_repetition:{t}@thinking`且`t`≤ 该值时行动；阈值越低表示循环越紧、越可信	64	2..=64
`max_retries`	每个回合接受响应前的重采样预算	2	0..=5
`window_tokens`	通过请求头`x-grok-doom-loop-check`下发的检测器窗口（token 数）	见默认常量	—

恢复只对thinking通道行动（可见输出里的循环留给用户判断，常量THINKING_CHANNEL = "thinking"）。此外，请求还会携带x-grok-exact-repetition-check头（精确重复检测器，客户端默认最小窗口 64 token）。

当判定为循环时，采样器会触发恢复重试：doom_loop_recovery.rs 会把失败的回合内容（仅限模型推理与可见文本）以硬上限（推理 8 KB、文本 4 KB，超出部分以[…truncated]标记）回放进重试请求，并追加固定的系统提醒RECOVERY_REMINDER（提示消息被标记为循环重复）。值得注意的边界：凡调用过工具（MCP 调用）或含压缩检查点的回合一律整体丢弃、不回放（record_unreplayable/veto_replay），因为工具调用会绑定其前的推理条目，孤儿推理条目会被 API 拒绝——这从另一个侧面保证了"工具失败这类回合"绝不会被断章取义地回放成疑似循环内容。

缺陷修复：恢复含推理内容会话时的自动压缩崩溃

崩溃场景

第三项修复针对的是：会话中已包含推理（reasoning）内容（即模型思考链），在恢复（resume）该会话并触发自动压缩时，可能发生崩溃（crash）。这类崩溃通常源于压缩流程对"只含推理增量、不含正文"的流式结构处理不当——例如 ChatCompletions 流中先来一个reasoning_contentdelta（无content），随后才是正文 delta 与stop，压缩器在提取/拼接这些部分时未做空值防护或字符边界处理。

回归测试锁定的行为

该修复由专门的回归测试文件固化：session_compact_reasoning_compaction_regression_tests.rs。其中的关键用例包括：

chat_completions_compaction_extracts_summary_after_reasoning_delta：模拟"先 reasoning delta（无 content），再 content delta +stop"的 SSE 流，验证自动压缩能正确从该流中提取<summary>...</summary>摘要——即压缩器必须容忍并正确消费"推理增量之后才是正文"的到达顺序；
chat_completions_compaction_does_not_panic_on_reasoning_sibling：直接在用例名中点明"遇到推理兄弟条目时不得 panic"。

这类测试通过 axum 构造本地 SSE mock 服务（Router::new().route("/v1/chat/completions", ...)）驱动真实采样客户端，确保压缩流程在含推理内容的重放/恢复路径上不再 panic。

压缩流程中的推理防护

自动压缩的完整流程位于 session_compact.rs。它让模型在私有推理后输出单一<summary>...</summary>块（提示词明确要求"在私有推理中思考，不要输出独立的分析块"），并对推理过程设置了墙钟时间预算（wall-clock budget）兜底，防止压缩摘要本身的推理失控（full_replace_compaction.rs 中同样将该预算作为"失控推理的上限"，0表示禁用）。

从源码结构看，0.2.36 的崩溃修复核心是把"推理内容"作为压缩输入的一等公民对待：无论是按 output_index 归位推理条目，还是处理"仅推理无正文"的流式片段，都补上了空值保护与边界检查（与之相呼应的还有 compaction_context.rs 中对字符边界panic!的防御性处理）。恢复会话时，持久化的推理条目被正确重建进压缩上下文，而不是触发解析/索引越界。

小结

0.2.36 是一个典型的"小版本、高含金量"发布：

大 MCP 结果落盘（mcp_truncate.rs）把"按内容类型选择.json/.txt扩展名 + 附带针对性查询提示"落实到了截断全流程，配合[mcp] max_output_bytes的多级配置体系（requirements.toml/ 环境变量 /config.toml/ 远程设置 / 默认 20_000 字节），让模型既能获得预览，又能高效查询全文；
doom-loop 误判修复（tool_calls.rs）移除了错误连击对循环检测的输入，并行工具批量失败只产生遥测统计，不再错误终止会话；循环判定回归到服务端上报的触发标签，并由DoomLoopRecoveryPolicy（max_threshold默认 64、max_retries默认 2）控制恢复行为；
推理内容压缩崩溃修复由 session_compact_reasoning_compaction_regression_tests.rs 等回归用例锁定，压缩流程在恢复含 reasoning 内容的会话时具备完整的空值与边界防护。