Claude Code v2.1.300 更新：OpenTelemetry 增强与多项核心修复

Claude Code v2.1.300 是一次以稳定性修复和可观测性增强为主的版本更新，涵盖 OpenTelemetry 事件细化、VS Code 扩展交互优化、后台代理与云会话的多个边界问题修复。对于依赖 Claude Code 进行日常开发的团队而言，这个版本值得优先升级。

OpenTelemetry 可观测性显著增强

本次更新在可观测性方面投入明显。api_request 事件新增 cache_creation_5m_tokens 和 cache_creation_1h_tokens 两个字段，将缓存写入按生命周期拆分，便于团队精确分析不同缓存策略的成本与命中效果。

同时，trace span 中加入了 GenAI 语义约定属性，包括 gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name 和 error.type。这意味着接入现有 OpenTelemetry 生态的监控平台时，Claude Code 的追踪数据能直接被标准化的 GenAI 仪表盘识别，省去自定义映射的工作。

对使用 git commit -q 并采用 reftable 引用存储的仓库，tool_result 事件此前缺失 git_commit_id 的问题也已修复。

OpenTelemetry 是一套由 CNCF 托管、厂商中立的可观测性框架，统一了 traces（追踪）、metrics（指标）和 logs（日志）三类信号的采集与导出协议。所谓 "事件"（event）和 "trace span" 是其中的核心数据模型：span 表示一次操作的起止时间与上下文，多个 span 通过 trace id 串联成一次完整调用链；事件则是挂在 span 上的带时间戳的结构化记录。

GenAI 语义约定（semantic conventions）是 OpenTelemetry 社区为生成式 AI 场景定义的属性命名规范，例如 gen_ai.provider.name 标识模型提供方、gen_ai.tool.name 标识被调用的工具、gen_ai.conversation.id 关联同一会话。遵循这套约定的好处是数据可被 Grafana、Datadog、Honeycomb 等平台的现成 GenAI 面板直接解析，无需团队自行维护字段映射逻辑。

Mod 与插件系统的能力扩展

针对 mod 开发者，v2.1.300 增加了多个 API。virtualText 允许在提示框中绘制不会进入草稿或提交内容的文本，适合做提示类装饰。新增的 $.ui.view({ agentId }) 让 mod 能在主视图中展示某个 agent 的对话记录，$.ui.view({}) 则返回。

agent.spawn 钩子现在支持重写工作流 agent 的 prompt 和 model，此前只能拒绝工作流 agent。新增的 prompt.change 钩子会在提示框文本非手动编辑而变化时触发，例如召回历史记录、清空、撤销或插件填充。

Text 组件新增 dir 属性，用于从右到左文本的渲染，在 Windows 和 VS Code 终端中该行会按从右到左方向排列并靠右对齐。

修复方面，mod 的 prompt.submit 钩子重写或丢弃的提示不再被错误记录为手动输入；prompt.edit 钩子现在也能响应通过 chat:newline 键位（Ctrl+J 或重新绑定的 Enter）输入换行的情况。

在 Claude Code 的语境中，"mod" 指通过官方 API 扩展客户端行为的第三方插件，可理解为在 IDE 或终端宿主中注入自定义 UI 与逻辑的模块。文中提到的 "钩子"（hook）是典型的扩展点设计：宿主在特定生命周期节点（如提示提交前、文本变化时）调用注册的回调，让插件有机会观察或改写数据。

prompt.submit、prompt.edit、prompt.change、agent.spawn 都属于此类钩子，区别在于触发时机与可干预程度——有的只能读取，有的允许重写或拒绝。$.ui、agent、Text 则是暴露给 mod 的运行时对象与组件，用于渲染界面或操控 agent 行为。理解这套模型有助于判断某次版本更新是新增了能力面，还是仅仅修正了钩子的调用一致性。

代理与云会话的关键修复

后台代理和云会话场景修复了多个影响使用的问题。子代理在收到消息后不久从 /tasks 消失的问题已解决，完成后的父代理不会再从面包屑导航中掉出。当云会话容器被替换时，已恢复过一次的后台代理不再被错误标记为丢失。

claude agents 在拉取请求数据不完整时不再停止刷新所有 PR 状态。云会话在任何组织策略无法读取时，不再每轮挂起 5 分钟，而是快速结束并说明原因。

一个值得注意的修复是：当 API 拒绝某个 MCP 工具的输入 schema 时，Claude Code 会在本轮对话的剩余部分以无参数方式发送该工具，避免每轮都因 400 错误而失败。

MCP（Model Context Protocol）是一套让模型以标准方式调用外部工具与数据源的开放协议，Anthropic 于 2024 年底开源。每个 MCP 工具通过 JSON Schema 声明输入参数结构，模型据此生成调用参数，服务端校验通过后才执行。

当服务端拒绝某个工具的输入 schema 时，意味着模型生成的参数不符合声明，请求会返回 400 错误。若不做处理，在同一轮对话的后续交互中模型往往会重复生成同类参数，导致连续失败。文中提到的修复策略是：一旦发生 schema 拒绝，就在本轮剩余部分以无参数方式调用该工具，相当于降级处理，保证对话能继续推进而不被反复中断。

VS Code 扩展的交互细节优化

VS Code 扩展修复了大量具体问题。Windows 上 Shift+拖拽文件到提示框不再插入不可读的 /c:/… 路径；WSL、SSH 和 Dev Container 窗口中 Shift+拖拽不再插入空内容。

新增 claudeCode.attachSelection 设置，可阻止编辑器选中文本被自动加入消息。Thinking 开关在始终思考的模型上不再显示，避免误导。快速模式在使用额度耗尽后会自动关闭，而不是继续发送被拒绝的请求。

Ctrl+Alt+F 现在正确打开查找而非切换 Focus 视图。macOS 上检查其他窗口会话的进程改为直接启动 /bin/ps，不再每次搜索 PATH。

Claude Desktop 与远程控制更新

Claude Desktop 的 Code 标签页现在会在 forceLoginGatewayUrl 指定 Anthropic 运营的网关时应用托管设置。远程控制服务器的连接续期不再因短暂的登录错误（如钥匙串锁定）而放弃，会重试并提示运行 claude /login。

远程控制的 diff 视图修复了将删除和重命名文件显示为修改的问题，需要本机 Claude Code v2.1.296 或更高版本。claude remote-control 移除了无效的 --sandbox 和 --no-sandbox 标志，传入会报错退出，应在设置中使用 sandbox.enabled。

其他改进与行为变更

Claude in Slack 新增 Slack Connect 频道支持，所有者或 Claude Tag 管理员可让 Claude 在与其他组织共享的频道中回答，默认关闭。新增私密的 Allow once / Deny 卡片，让连接器操作等待审批而非直接拒绝。

工具搜索（ENABLE_TOOL_SEARCH=auto）在对话中途因 MCP 服务器重连而关闭的问题已修复。/branch 在遇到 Unicode 行分隔符时不再丢消息，claude purge 不再跳过包含此类字符的子文件夹项目。

默认已对大请求启用 gzip 压缩，即使遥测关闭也生效，可通过 CLAUDE_CODE_GZIP_REQUEST_BODIES=0 关闭。本地会话记录现在还保存每次 API 请求的系统提示、工具和参数，便于分享的会话记录完整复现请求。

gzip 压缩是 HTTP 层面的正文压缩方式，可显著降低大请求体的网络传输量，代价是客户端与服务端各承担一次压缩/解压的 CPU 开销。对发送大量上下文（长提示、工具定义、文件内容）的编码代理而言，请求体动辄数十万 token，启用 gzip 通常能带来明显的延迟与带宽收益，因此此次更新将其设为默认开启，并允许通过环境变量 CLAUDE_CODE_GZIP_REQUEST_BODIES=0 回退。

本地会话记录保存每次 API 请求的完整系统提示、工具列表与参数，则解决的是可复现性问题：过去分享会话记录时只保留消息内容，接收方无法还原当时模型看到的真实输入，排障与对比实验容易失真。完整快照让会话具备可重放性，也便于审计提示词与工具配置的变更影响。