Claude Code v2.1.299 更新：空闲压缩与50+修复详解

Claude Code 发布 v2.1.299 版本，这是继 2.1.296 之后的一次大规模维护更新。更新日志列出了数十项新增、修复和改动，其中「空闲压缩」机制和文件提及环境变量最值得关注。本文梳理其中对开发者日常使用影响最大的几项变化。

空闲压缩：解决长对话的缓存过期问题

这是本次更新中最具实用价值的新功能。

在终端中使用 Claude Code 时，如果一段超过 200K token 的对话空闲约 54 分钟，系统会在其一小时 prompt 缓存过期之前主动进行压缩。这样下次发消息时就不需要重新处理全部上下文，既节省时间也减少 token 消耗。

该行为的几个控制方式：

• 通过 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 调整触发压缩的最低 token 数（默认 200K）
• 在 settings.json 中设置 "idleCompaction": false 可完全关闭
• 以上两项都需要 v2.1.290 或更高版本

对于经常开着 Claude Code 处理大型项目、中途去开会或做其他事的开发者，这个机制能显著减少"回来一问就要等很久"的情况。

Prompt 缓存（prompt caching）是 Anthropic API 的一项能力：当请求的前缀部分（系统提示、历史消息、工具定义等）与上一次请求完全一致时，服务端可以直接复用已计算好的中间状态，跳过重复的预填充计算。这让多轮长对话的响应更快、输入 token 的计费更低。但它有存活时间限制，Claude Code 场景下约为 1 小时，一旦过期，下一次请求就得把全部上下文从头处理一遍——对 200K token 级别的对话来说，这意味着可观的等待时间和 token 开销。空闲压缩正是针对这个时间窗口设计的：在缓存失效前主动把历史对话做一次摘要压缩，用一个更短的新上下文接续会话，这样即便缓存过期，重建成本也小得多。理解「压缩」与「缓存」是两个层次的机制，有助于判断什么时候该开、什么时候该关这个功能。

文件提及与媒体处理的新环境变量

新增 CLAUDE_CODE_DISABLE_FILE_MENTIONS 环境变量。启用后，Claude 在使用 @ 文件提及时拿到的是文件路径而非文件内容，由它自己的文件工具去读取。这对处理大文件或敏感文件时更可控。

另一个新增项是 $.prompt.media，允许通过 managed settings 安装的 mod 的 prompt.submit hook 读取提示中附加的图片或文档字节。配合新增的 $.session.identity()（用于判断会话登录方式、组织与邮箱），插件生态在权限和上下文感知上更加完整。

模型与努力度控制的交互改进

Agent 视图中新增 /effort 和 /fast 命令，用于设定新会话的默认参数。直接输入 /model、/effort 或 /fast 会打开选择器。

/usage 也新增了对 max effort、workflows、always-on context 以及大工具结果的警告提示。此外还修复了 /usage 和状态栏有时显示超过 100% 使用率的问题。

对后台会话，agents 视图的 peek 面板新增 "safe mode" 状态行，当会话以 --safe-mode 启动时会显示。同时修复了以 --safe-mode 启动的后台会话在被唤醒或重启后静默退出安全模式的问题。

网络、MCP 与代理层的稳定性修复

这批修复针对企业环境和自托管场景。

通过自定义 ANTHROPIC_BASE_URL 的流式请求，如果在 180 秒内没有数据到达会被中止，现在延长到 300 秒，无论 feature flags 是否加载。同时修复了向 Anthropic 发送的 feature flag、启动、fast mode、profile 和反馈请求错误携带第三方网关 API key 的问题——Anthropic 的 API key 仍正常发送。

MCP 方面修复了几类边界情况：

• 名为 constructor 或 prototype 的 MCP server 此前永远无法连接，现已修复
• 策略检查阻止的 MCP server 不再被启动，直接报告为 blocked
• HTTP 连接在服务器不结束响应体时会挂起 30 秒的问题已修复

MCP（Model Context Protocol）是 Anthropic 主导的开放协议，用于让 Claude 以统一方式接入外部工具和数据源，Claude Code 通过它连接数据库、代码托管平台、内部系统等。每个 MCP server 以名称注册，客户端再按名称调用。文中提到的 constructor、prototype 问题属于典型的原型链污染边角情况：由于这些名字同时是 JavaScript 对象的原型属性，用它们做键名查表时会命中原型链上的成员而非真实注册项，导致连接逻辑被错误跳过。ANTHROPIC_BASE_URL 则是把请求指向自定义网关的入口，企业常借此接入自建代理做审计、限流或区域路由，因此「feature flag 等请求误带第三方网关 API key」这类问题在自托管环境中风险较高，属于需要优先升级的修复。

开发者最该关注的三项修复

更新日志近 60 条，以下三项对日常开发体验影响最直接：

2.1.296 回归问题的修复。 云端和无头会话在重启恢复时，如果新消息到达，可能导致已批准的工具调用执行两次。同时修复了 Cowork 和 claude.ai 云端会话中 Edit/Retry 在 hook 运行期间停止消息失败的问题。

调试内存泄漏。 重度调试日志（--debug、--debug-file）下的内存增长问题已修复，同时修复了调试输出写入 stderr 而父进程停止读取时的内存无限增长，以及调试日志位于停止接受写入的磁盘或网络挂载点时的退出挂起。

终端宽字符渲染。 修复了 CJK 与 emoji 混排文本在换行时丢失最后一行或留下空行、宽字符旁的文字被截断、emoji 在颜色变化处消失等一系列终端渲染瑕疵。对于中文用户，这几项修复的体感改善应该比较明显。

小结

v2.1.299 是偏底层的维护版本，没有颠覆性新功能，但空闲压缩的引入补齐了长会话体验的一块短板。大量针对 MCP 边界情况、企业代理配置和终端渲染的修复，说明项目正处在大规模打磨阶段。建议使用自定义网关或 MCP 服务器的团队尽快升级。