Claude Code v2.1.311 更新解析：长上下文压缩与 MCP 稳定性修复

Claude Code 发布 v2.1.311，一次以「稳定性」为主线的版本更新。这个版本没有引入全新的大功能模块，但修复清单长到需要滚动好几屏，几乎覆盖了过去一段时间用户吐槽最集中的几类问题：启动卡顿、MCP 连接挂起、长文件编辑冻结、子代理工具不可用，以及云端与远程控制会话的各类边界情况。

长上下文与压缩逻辑的实质性改进

超出 200K token 后自动压缩

最值得关注的修复之一，是标准上下文会话在请求超过 200K token 时不再直接报出「Usage credits required for 1M context」而停止工作。Claude Code 现在会主动压缩对话并继续执行。对日常需要处理大仓库、长文档的开发者来说，这消除了一个此前必须手动介入的中断点。

什么是 1M 上下文与 200K token 门槛

大模型的「上下文窗口」指单次请求中模型能同时看到的最大 token 数量，token 是模型处理文本的基本切分单位，大致对应英文的单词片段或中文的单字。Claude 系列历史上分为标准上下文（约 200K token）与扩展到 100 万 token 的长上下文模式。长上下文并非默认开启，通常需要额外计费或在特定套餐下授权，未获授权时请求一旦跨过 200K 门槛就会返回类似「Usage credits required for 1M context」的错误并中断。

自动压缩（compaction）则是绕过这一硬限制的常规手段：当对话接近窗口上限时，客户端先让模型把已有历史总结成一段精简摘要，用它替换原始消息序列，从而腾出空间继续工作。两者结合意味着，即便没有长上下文授权，只要压缩策略足够可靠，超长任务也能连续推进，代价是部分历史细节被摘要取代。

压缩后的文件新鲜度

另一个隐蔽但影响真实的问题：自动压缩之后，Claude 会看到过期的 MEMORY.md 和 CLAUDE.md 内容——尤其是这些文件在会话早期被编辑过的情况下。修复后，压缩不再让模型基于旧快照做判断。同时，当模型回复中没有包含摘要时，Claude Code 通常会再请求一次摘要，然后才替换对话，压缩质量因此更可控。

MCP、子代理与中断行为修复

中断不再等超时

此前，如果某个 MCP 服务器没有响应资源读取请求，或者某个 skill 仍在下载中，用户按下中断键后要等超时才会真正生效。这个版本的修复让中断即时生效。同一批修复还包括：子代理现在可以使用那些在子代理启动之后才连接完成的 MCP 服务器提供的工具。

MCP 的资源读取与连接生命周期

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，用统一的客户端-服务器模型把外部工具、数据源和提示模板接入 AI 应用。服务器可以暴露三类能力：tools（可被调用的函数）、resources（可被读取的数据，如文件、数据库记录）和 prompts（预置提示模板）。协议基于 JSON-RPC，连接需要经历初始化握手、能力协商，之后才进入正常请求阶段。

文中提到的「资源读取请求」正对应 resources 能力，「skill 仍在下载中」则属于连接尚未就绪的中间态。由于 RPC 请求是异步的，早期实现会在等待响应时保留阻塞状态，用户触发中断后必须等到底层超时才会释放。改为中断即时生效，本质上是让取消信号贯穿到在途的 RPC 调用，而不是任由其自然超时。

子代理钩子与工作树

SubagentStop 钩子此前会以大约每分钟两次的频率对每个运行中的子代理触发，而不是在其完成时触发一次——这属于明显的资源浪费。此外，当子代理启动的后台代理仍在隔离工作树中工作时，该工作树不再被提前删除。自动模式下的后台代理也不会在每次唤醒时都启动一个新的主对话轮次。

子代理、钩子与隔离工作树

子代理（subagent）指主对话派生出的独立执行单元，拥有自己的上下文与工具权限，用于并行处理搜索、重构等子任务，避免污染主对话历史。钩子（hook）是 Claude Code 提供的事件回调机制，允许用户在会话生命周期的特定节点（如工具调用前后、子代理结束）注入自定义脚本，常用于格式化、审计或通知。SubagentStop 即子代理结束时触发的事件，应当是每次完成触发一次而非周期性轮询。

隔离工作树借用了 Git 的 worktree 概念：在同一仓库下创建相互独立的工作目录与分支，使后台代理的改动与主工作区互不干扰。工作树被提前删除会导致仍在其中运行的进程失去文件系统依托，因此删除时机必须与代理生命周期严格对齐。

大文件编辑卡顿

对包含数千行改动的文件执行 Write 和 Edit，此前可能停顿长达 5 秒，并错误报告为 0 行变更。这一体验问题在本次更新中得到修复。

自托管运行器与命令行工具

新增空闲会话保持参数

自托管运行器新增了 --hold-idle-file 和 --max-hold-min 两个参数，用于在宿主机报告仍有遗留进程运行时保持空闲会话。这为自建 CI 或长时任务环境提供了更细的控制粒度。

MCP 命令与配置修复

claude mcp add、claude mcp remove 和 /mcp 在仓库根目录以下运行时，此前会错误地命名当前文件夹，而不是 ~/.claude.json 中持有 local-scope 服务器的项目条目。claude mcp list 与 claude mcp get 在连接失败时重复显示错误码（如 ENOENT: ENOENT: …）的问题也已修正。

配置作用域与 local-scope 服务器

Claude Code 的 MCP 服务器配置分为多个作用域：user（用户级，对所有项目生效）、project（项目级，随仓库共享给团队）和 local（仅对当前项目在本机生效）。不同作用域写入不同的配置文件，用户级配置存放于家目录下的 ~/.claude.json。

local-scope 服务器的特殊之处在于，其条目在配置文件中以项目路径作为键进行索引。此前的缺陷在于命令从仓库子目录运行时，程序把当前文件夹路径当作键，导致新增、删除和列表操作找不到既有条目，出现「加了却看不到」的现象。修复的关键是向上解析到仓库根目录再匹配项目条目，使配置读写与项目身份保持一致，不受执行目录影响。

输出与启动行为调整

• --output-format json 和 stream-json 现在会把字符串中的 DEL、C1 控制符和 Unicode 格式字符写成 \uXXXX 转义，解析后的值不变。
• 模型名称和 ID 中去掉了无实际作用的 [1m] 后缀及其标签，但该后缀仍被接受。
• 仅由选项及其值构成的启动参数（如 claude --model opus）启动更快。
• Pro 和 Max 账户在上次检查后一小时内启动时，会跳过两次网络请求，从而加快启动。

交互体验与 IDE 集成

ultrathink 在交互式终端中的行为有调整：在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上通过 Anthropic API 以 xhigh effort 运行该轮对话；在 Claude 工作时键入则提升该轮剩余部分的努力程度。彩虹效果只在关键词确实能提升努力度时出现，被引号包裹或位于文件路径中时不显示。

VS Code 扩展方面，代码块新增了语法着色（覆盖浅色、深色和高对比度深色主题），并为执行较慢的 UserPromptSubmit 钩子增加了加载状态与屏幕阅读器播报。同时修复了从 VS Code 或 JetBrains 面板发送自定义 skill 和斜杠命令时丢失当前打开文件或选中行的问题（#102799），以及 macOS 和 Linux 上登录 shell 执行启动文件读取 PATH 时扩展宿主冻结的问题。

远程控制与云端会话同样有多处修补：网络代理阻断启动请求时，Remote Control 会话不再卡在「Connecting」约两分钟；通过 Remote Control 或云会话发送、但因磁盘已满无法保存的附件，Claude 现在会被告知失败原因；超过 20 个的附件被遗漏时也会告知。WebFetch 和 WebSearch 在停滞响应上不再无限挂起，未完成的请求会在 300 秒后失败。

一个值得注意的信号

从修复密度看，这个版本的主题是「让复杂场景不崩」。MCP 超时中断、子代理工具发现、压缩后的文件一致性、云端会话的连接韧性——这些都是重度用户才会撞上的问题，也恰恰是决定工具能否长期留在工作流里的关键。对已经把 Claude Code 嵌入日常开发的团队，升级是明确划算的；对新用户，这个版本降低了踩坑概率。

完整变更清单可在发布页查看。