# 文档变更分析
### 总体摘要
本次文档更新主要集中在将 API 文档中的“兼容性”信息迁移至结构化的 `featureMetadata` 前端元数据,同时对 Claude 的桌面端、VS Code 扩展及 CLI 工具进行了多项功能增强和用户体验改进。
### 关键主题
* **文档结构标准化**:大量 API 功能页面(如 PDF 支持、结构化输出、代码执行等)将原本的文本兼容性说明统一迁移为 `featureMetadata` 格式,明确了支持状态、ZDR 资格、支持模型及平台列表。
* **工件与网络配置**:为 Artifacts 增加了对 `unpkg.com` 的支持,允许加载更多第三方 JavaScript 库。
* **VS Code 扩展增强**:新增了“复制响应”功能、改进了 Agent 地图(包含后台任务)、优化了“努力级别”的持久化逻辑,并新增了登出选项。
* **可观测性提升**:新增了 OTEL 相关的环境变量和追踪属性(如 `effort` 级别和托管设置),便于更详细的监控。
* **交互模式优化**:新增快捷键(`Ctrl+Enter`)用于立即发送排队消息,并细化了后台任务在内存压力下的清理说明。
### 影响程度
**低**
本次更新主要是文档元数据的重构和工具功能的增量优化,不包含破坏性 API 变更或行为改变。开发者主要关注网络配置的变更和新的监控字段即可。
### 开发者行动项
1. **更新网络防火墙规则**:如果你在生产环境中限制 Artifacts 的外部请求,请将 `unpkg.com` 加入允许列表,以确保 React 等库能正常加载。
2. **适配监控解析**:如果你使用 OpenTelemetry 监控 Claude Code,请更新解析逻辑以支持新增的 `effort` 属性和 `managed_settings` 事件。
3. **审查 VS Code 新特性**:检查 VS Code 扩展更新(需 v2.1.277+),利用新的 `/copy` 命令和增强的 Agent 地图来管理后台任务。
4. **留意 CLI 快捷键**:在终端交互模式下,可使用新的 `Ctrl+Enter` 快捷键强制发送排队消息。
💭 Model Reasoning
1. **Analyze the Request:**
* **Role:** World-class programmer analyzing documentation changes.
* **Format:** Markdown, concise, insightful, Chinese response.
* **Input:** Diffs from 17 pages.
* **Output Structure:** Overall Summary, Key Themes, Impact Level, Action Items.
2. **Analyze the Diffs (Page by Page):**
* **`desktop.md` & `network-config.md`**: Added `unpkg.com` to the list of allowed external hosts for loading JavaScript libraries in Artifacts.
* *Impact:* Minor feature expansion for Artifacts.
* **`discover-plugins.md`**: Updated instructions for installing plugins when `/plugin` isn't available. Added VS Code extension as an option (previously only mentioned desktop app and cloud sessions).
* *Impact:* Improved UX/Docs clarity for plugin installation across different environments.
* **`interactive-mode.md`**:
* Added `Ctrl+Enter` or `Ctrl+X Ctrl+S` to send queued messages immediately.
* Clarified memory pressure logic for background tasks (macOS/Linux): "terminates" -> "stops", added debug log mention.
* *Impact:* New keyboard shortcut, better observability for background task management.
* **`monitoring-usage.md`**:
* Added `OTEL_LOG_MANAGED_SETTINGS` environment variable.
* Added `effort` attribute to traces.
* *Impact:* Enhanced observability/telemetry capabilities.
* **`vs-code.md`**:
* Effort levels: Clarified that non-`max` levels are saved to user settings as defaults.
* Added "Sign out" option in Settings (v2.1.277).
* Added "Copy a response" feature (hover + button or `/copy` command) (v2.1.277).
* Agent map: Now lists background tasks (shell/monitors) alongside subagents.
* *Impact:* Significant UX improvements for VS Code extension users (copying, signing out, task monitoring).
* **`build-with-claude/overview.md` & `text-generation.md`**: Updated "Compaction" link to "Compaction at a token threshold".
* *Impact:* Doc navigation update.
* **`build-with-claude/*.md` (pdf-support, citations, structured-outputs, effort, files, computer-use-tool, code-execution-tool, programmatic-tool-calling, mcp-connector)**:
* *Common Pattern:* Replaced the text-based "Compatibility" section with a structured `featureMetadata` frontmatter block.
* *Content:* Standardized info on status (GA/Beta), ZDR eligibility, supported models (lists), and supported platforms.
* *Specifics:* No actual logic changes, just structural metadata migration for better documentation generation/management.
3. **Synthesize Key Themes:**
* **Standardization/Metadata Migration:** A bulk update to move compatibility info into `featureMetadata` frontmatter across multiple API pages.
* **Artifact/Environment Enhancements:** Added `unpkg.com` support and new keyboard shortcuts.
* **Observability:** New OTEL flags and trace attributes.
* **VS Code UX Improvements:** Better agent map, copy command, effort level persistence, sign out.
* **Plugin Installation:** Clarified paths for different environments (specifically VS Code).
4. **Determine Impact Level:**
* *Most changes are doc structure (metadata)*: Low impact on code, but good to know.
* *API changes*: None in logic, just links and metadata.
* *Tooling changes (VS Code/Desktop/CLI)*: New shortcuts (`Ctrl+Enter`), new endpoints allowed (`unpkg.com`), new telemetry fields. These are "nice to have" or "need to know for monitoring" but not "breaking".
* *Verdict*: **Low to Medium**. It's mostly documentation structure updates (metadata migration) and minor feature additions/clarifications for the tools.
5. **Draft Action Items:**
* Update firewall/proxy rules to include `unpkg.com` for Artifacts.
* Check VS Code extension updates for new "Copy response" and "Agent map" features.
* Update telemetry parsing if using OTEL to handle new `effort` and `managed_settings` fields.
* Review `featureMetadata` in API docs if you rely on scraping/programmatic doc reading.
6. **Refine the Output (Chinese):**
* *Summary*: Mainly structural updates to API documentation (metadata migration) and minor feature enhancements for Claude tools (VS Code, Desktop, CLI).
* *Themes*: Metadata migration, Artifact support expansion, Observability improvements, VS Code UX.
* *Impact*: Low.
* *Action Items*: Whitelist unpkg.com, parse new OTEL fields, check VS Code updates.
7. **Final Polish (Reviewing against the generated diffs):**
* Did I miss anything? The "Compaction at a token threshold" link change is minor but part of the API updates.
* The `interactive-mode` change about "memory pressure" is a refinement of existing behavior description, not a behavioral change per se, but good for debugging.
* The `vs-code` change about "Effort" saving to settings is a behavior change to note for users.
8. **Construct Final Response:** (Proceeding to generate markdown).