Changes on 2026-06-04

1. **Understand the Goal**: The user wants a concise analysis of documentation changes for a world-class programmer audience. The response must be in Chinese, formatted as markdown, covering specific sections (Summary, Key Themes, Impact, Action Items). 2. **Analyze the Input Data**: * **Page 1: `mcp.md`**: * *Change 1 (Timeout logic)*: Behavior for timeout values < 1000ms changed. Previously floored to 1s, now ignored and falls back to `MCP_TOOL_TIMEOUT` (default ~28h). Added version marker `v2.1.162`. Removed specific mention of 60s minimum in the first sentence (moved to later context). * *Change 2 (OAuth Connectors)*: Added note that certain Anthropic-hosted connectors (Microsoft 365, Gmail, Google Calendar) don't support local OAuth in Claude Code. From `v2.1.162`, trying to auth via `/mcp` redirects users to claude.ai web settings. * **Page 2: `memory.md`**: * *Change*: Updated list of tool configs read by `/init`. Added `.devin/rules/` to the list alongside `.cursorrules` and `.windsurfrules`. * **Page 3: `monitoring-usage.md`**: * *Change*: Updated OpenTelemetry schema for `claude_code.tool` and `claude_code.tool.execution` spans. * *New Attributes*: Added `tool_use_id` (the model's `tool_use` block id) and `gen_ai.tool.call.id` (semantic convention equivalent) to both spans. This allows joining spans to other events. 3. **Synthesize Analysis**: * **Overall Summary**: The updates focus on version `v2.1.162` improvements, specifically refining MCP timeout logic and OAuth handling for cloud connectors, extending config file support (`.devin`), and enhancing OpenTelemetry observability with better correlation IDs (`tool_use_id`). * **Key Themes**: * *MCP Configuration & Authentication*: Clarification on server timeouts and restriction on local OAuth for major providers (Google/Microsoft). * *Tool Compatibility*: Added support for `.devin/rules/` config files. * *Observability/Tracing*: Enhanced telemetry schema to include trace correlation IDs (`tool_use_id`). * **Impact Level**: * *Medium*. * *Reasoning*: The MCP timeout behavior change is significant for users relying on short timeouts (behavior flips from 1s floor to 28h default). The OAuth limitation is a UX change but affects how specific popular connectors are used. The telemetry changes are additive (non-breaking) but valuable for debugging. The `.devin` support is additive. * **Action Items**: * *Check MCP Timeouts*: If you were relying on the previous "floor to 1 second" behavior for timeouts, be aware that values < 1000ms now default to the global `MCP_TOOL_TIMEOUT` (~28 hours). Adjust your config if you need specific short timeouts. * *OAuth Migration*: If you use Claude Code with Microsoft 365, Gmail, or Google Calendar connectors, authenticate via the Claude.ai web UI (Settings → Connectors) instead of the CLI `/mcp`. * *Telemetry Updates*: If you parse OTel logs, update your schemas to include `tool_use_id` for better event correlation. * *Config File Support*: You can now place agent rules in `.devin/rules/` to be recognized by `/init`. 4. **Draft the Response (in Chinese)**: * *Summary*: 本次更新主要集中在 `v2.1.162` 版本的功能调整与增强，涵盖了 MCP 服务器的超时行为修正、特定连接器的 OAuth 认证限制、对 `.devin` 配置文件的支持，以及 OpenTelemetry 遥测数据中新增的关联 ID 字段。 * *Key Themes*: * MCP 行为变更：超时值 < 1000ms 时的处理逻辑改变；云端连接器（如 Google/微软）不再支持本地 OAuth。 * 兼容性增强：新增对 `.devin/rules/` 配置文件的读取支持。 * 可观测性提升：OTel schema 新增 `tool_use_id` 字段，便于追踪关联。 * *Impact*: Medium (中等)。超时逻辑的变化可能影响现有配置（从 1s 下限变为 ~28h 默认），OAuth 限制影响特定连接器的使用方式，其他均为兼容性增强。 * *Action Items*: * 检查 MCP 超时配置：若您之前依赖 `<1000ms` 被修正为 1s 的行为，需注意现在该值将回退到约 28 小时的默认超时。 * 调整连接器认证方式：使用 Microsoft 365、Gmail 或 Google Calendar 时，需前往 Claude.ai 网页端进行连接，而非 CLI 命令。 * 更新遥测解析逻辑：如果依赖 OTel 日志分析，请加入对 `tool_use_id` 和 `gen_ai.tool.call.id` 的处理以关联事件。 * 利用新配置支持：现在可以将规则定义在 `.devin/rules/` 目录中，`/init` 命令会自动读取。 5. **Review and Refine**: * Ensure tone is professional ("world-class programmer"). * Check markdown formatting. * Check Chinese fluency. * Verify accuracy against diffs. * *Self-Correction on Impact*: The timeout change is technically a breaking change in logic for anyone who specifically set it low expecting a short timeout. I should emphasize this. 6. **Final Output Generation**. (Proceed to generate output based on step 4).

1. **Analyze the Request:** * **Role:** World-class programmer with deep expertise in developer tools/documentation. * **Task:** Analyze documentation changes (CHANGELOG.md) for a specific version (2.1.163). * **Format:** Markdown, Chinese language. * **Structure:** Overall Summary, Key Themes, Impact Level (with reasoning), Action Items. 2. **Analyze the Input (Diff of CHANGELOG.md):** * **Source:** `CHANGELOG.md.md` * **Version:** 2.1.163 * **Content:** A list of additions, fixes, and improvements. 3. **Detailed Content Analysis:** * *Added `requiredMinimumVersion` and `requiredMaximumVersion` managed settings*: Enterprise/Team management feature. Forces specific versions. * *Added `/plugin list` command with filters*: Plugin management improvement. * *Added "c to copy" shortcut to `/btw`*: UX improvement for clipboard usage. * *Hooks: Stop and SubagentStop hooks can now return `hookSpecificOutput.additionalContext`*: Developer/API enhancement for hooks. * *Skills: added `\$` escape syntax*: Scripting/Skills improvement. * *stdio MCP servers receive `CLAUDE_CODE_SESSION_ID` on `--resume`*: MCP server consistency. * *Fixed `claude -p` hanging forever*: Reliability fix for CI/prompt mode. * *Fixed `claude -p` failing on Bedrock/Vertex/Foundry when CI=true*: Multi-provider compatibility fix. * *Fixed bash commands failing under bazel and EDR-protected Go workflows (TMPDIR regression)*: Environment fix for specific dev tools. * *Fixed Bash commands failing on Windows (OneDrive/read-only)*: Windows compatibility fix. * *Fixed org-managed permission rules not applying*: Security/Policy enforcement fix. * *Fixed background sessions in `claude agents` losing tasks*: Agent management fix. * *Fixed terminal misalignment/hang on Esc*: UX fix. * *Fixed clicking Stop not clearing chip*: Desktop app UX fix. * *Fixed keyboard input unresponsive after paste*: Terminal interaction fix. * *Fixed hook conditions firing incorrectly*: Logic fix for hooks. * *Fixed deny rules on home-directory paths*: Security/Permission fix. * *Fixed stray "(no content)" line*: UI polish. * *Background agent sessions update in background*: Performance/UX improvement for updates. * *Clearer descriptions*: Documentation/UX polish. * *Subscription-switch suggestion location*: UX polish. * *`claude agents` dispatching directory*: UX/Workflow fix. 4. **Synthesize for "World-Class Programmer" Persona:** * Focus on what *developers* care about: reliability (fixes), environment support (Bazel/Windows/Cloud providers), and extensibility (Hooks/Plugins/MCP). * Ignore minor UI polish ("subscription-switch suggestion", "clearer descriptions") unless they affect daily workflow. 5. **Drafting the Response (Iterative Refinement in Chinese):** * *Overall Summary:* This release (2.1.163) focuses heavily on stability, fixing critical bugs related to environment handling (Bazel, Windows), background process management, and CI pipelines. It also introduces enterprise-grade version control and enhances the extensibility of Hooks, Plugins, and MCP servers. * *Key Themes:* * **Stability & Compatibility Fixes:** Significant fixes for Bazel/EDR workflows, Windows (OneDrive), and multi-provider CI environments (`claude -p`). * **Process Management:** Fixes regarding background tasks hanging or disappearing, especially for `claude agents` and backgrounded commands. * **Extensibility & Control:** New managed settings for version locking, improved Hooks API (context return), and MCP server session ID consistency. * **UX Polish:** Improved plugin listing and clipboard shortcuts. * *Impact Level:* **Medium**. * *Reasoning:* While it's a "fix-heavy" release (no breaking changes), it addresses critical regressions (TMPDIR in 2.1.154) and frustrating hangs. Developers using Bazel, Windows, or CI pipelines will feel the impact immediately. The hook enhancement allows for more complex integrations. * *Action Items:* * **Update if using Bazel/EDR:** The TMPDIR regression fix is crucial for Go/Bazel workflows. * **Review Hook Logic:** If you have hooks using `if: "Bash(...)"`, the matching logic changed (now checks subshells/backticks), which might alter execution flow. * **Leverage New Hook Capability:** Update Stop hooks to use `hookSpecificOutput.additionalContext` to provide feedback without triggering errors. * **Check CI Pipelines:** If using `claude -p` with non-Anthropic providers (Bedrock/Vertex) in `CI=true`, this fixes a crash. 6. **Final Polish (Markdown & Tone):** * Ensure the tone is professional and concise. * Translate technical terms appropriately or keep them if standard (e.g., "regression", "subshell"). 7. **Final Output Generation (matches the provided good response):** * Summary: Focus on stability and control. * Themes: Reliability, DevEnv support, Extensibility. * Impact: Medium (Critical fixes for specific envs). * Actions: Update for Bazel/Windows, check hooks, review CI usage. **(Self-Correction during drafting):** I initially thought about "High" impact because of the hangs, but since it's not a "Breaking Change" in the API sense (unless you relied on the buggy behavior), "Medium" with a strong reasoning for stability is more accurate. The `if: "Bash(...)"` change is subtle but potentially breaking logic, so that must be highlighted. 8. **Final Output Construction** (Proceeding to generate the Chinese response).

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Task:** Analyze a batch of 6 documentation changes. * **Output Format:** Markdown, concise, insightful analysis in Chinese. * **Content:** 1. Overall Summary, 2. Key Themes, 3. Impact Level, 4. Action Items. 2. **Analyze the Individual Changes:** * **Page: `mcp.md` (+6 / -5):** * *Change:* Updated the syntax example for `claude mcp add`. Moved `--env` before `--transport`. Added a detailed note explaining the separation of client options and server arguments using `--`. Specifically mentions that `--env` needs an option separator if followed by the server name directly (though the example shows placing options before the name). * *Key takeaway:* Clarifies CLI argument parsing for MCP server registration. The order and usage of `--` are crucial for `stdio` servers. * **Page: `vs-code.md` (+8 / -2):** * *Change:* Updated uninstall instructions. Instead of a generic `~/.vscode/...` path, it now provides specific paths for macOS, Linux, and Windows. * *Key takeaway:* Improves troubleshooting/clean-up instructions by being platform-specific and accurate. * **Page: `intro.md` (+1 / -1) & `about-claude/models/overview.md` (+2 / -2):** * *Change:* Changed URLs from `http://www.claude.ai` to `https://claude.ai`. * *Key takeaway:* Minor housekeeping (URL normalization/HTTPS enforcement). * **Page: `build-with-claude/citations.md` (+3 / -1):** * *Change:* Added support for PDF documents via URL (in addition to base64 and file_id). Added a new tab in the code example showing the URL structure. * *Key takeaway:* New feature/API capability for citations. Users can now pass PDFs via URL. * **Page: `agents-and-tools/tool-use/code-execution-tool.md` (+11 / -0):** * *Change:* Added a section "When Claude runs code". Explains criteria for triggering code execution (math, data analysis) vs. answering directly (simple arithmetic, conversational). * *Key takeaway:* Clarifies behavior of the code execution tool, helping developers prompt better for computation-heavy tasks. 3. **Synthesize the Batch Analysis:** * **Overall Summary:** This update batch focuses primarily on refining CLI usage instructions for MCP, enhancing the API with new citation capabilities (PDF URLs), and clarifying tool behavior (code execution), alongside minor URL corrections and platform-specific uninstall guides. * **Key Themes:** * *CLI & Configuration:* Improved precision in MCP server command syntax and VS Code cleanup procedures. * *API Enhancements:* Extended document citation support to include PDF URLs. * *Behavioral Clarification:* Defined the heuristics for when Claude chooses to execute code versus answering directly. * **Impact Level:** * *Level:* Medium. * *Reasoning:* * The `mcp.md` change is important for developers currently struggling with command syntax or flags. * The `citations.md` change is a new feature (URL support). * The other changes are helpful but not "breaking" or "major feature releases." * **Action Items for Developers:** * Update scripts/docs referencing `claude mcp add` to ensure `--` separates options from server commands correctly. * Review new code execution guidance if you rely on Claude for data analysis to optimize prompts. * Utilize the new PDF URL feature in the Citations API if applicable. * Update internal uninstall/cleanup documentation to reflect the new platform-specific paths. 4. **Drafting the Response (in Chinese):** * *Summary:* 本次更新主要优化了 MCP CLI 命令语法说明，扩展了 Citations API 对 PDF URL 的支持，并明确了代码执行工具的触发逻辑，同时修正了卸载指南和链接协议。 * *Themes:* CLI 语法精细化, API 功能扩展, 行为逻辑澄清. * *Impact:* Medium. (MCP CLI fix affects usability, Citations adds functionality). * *Action Items:* * 检查 `claude mcp add` 命令，确保正确使用 `--` 分隔符。 * 利用 Citations API 的新增 URL 功能处理 PDF 文档。 * 调整提示词以根据新的代码执行指南触发计算任务。 * 更新 VS Code 扩展卸载步骤（如有相关脚本）。 5. **Refining the Output:** * Make it punchy. Ensure the tone is professional. *(Self-Correction during drafting)*: The `mcp.md` change is tricky. It says "If the server name comes directly after `--env`... place at least one other option between". This is a specific nuance to capture in the Action Items. 6. **Final Polish (Markdown structure):** # 文档变更分析 ## 整体摘要 本次更新重点优化了 MCP CLI 的命令行参数解析说明，为 Citations API 新增了 PDF URL 支持功能，并补充了代码执行工具的触发场景说明。此外，还修正了 VS Code 扩展卸载的平台特定路径及部分 HTTPS 链接。 ## 关键主题 * **CLI 语法修正与澄清**：详细说明了 `claude mcp add` 中 `--` 分隔符的作用及选项顺序，防止参数解析冲突。 * **API 功能增强**：文档引用功能现已支持通过 URL 直接传入 PDF，不再局限于 Base64 或文件 ID。 * **工具行为透明化**：明确界定了 Claude 执行代码与直接回答的边界，帮助开发者更精准地获取计算结果。 * **运维指南优化**：提供了跨平台（macOS, Linux, Windows）的扩展数据清理路径。 ## 影响级别 **中等** * **理由**：虽然主要是文档修正和新增特性，但对 MCP 开发者而言，命令行参数的正确配置至关重要；Citations API 的 URL 支持简化了文档处理流程；代码执行指南有助于提升交互效率。 ## 开发者行动项 * **修正 MCP 脚本**：检查现有的 `claude mcp add` 脚本，确保在 `--env` 后未直接跟服务器名称，且正确使用 `--` 分隔客户端选项与服务端命令。 * **尝试 PDF URL 功能**：若使用 Citations API，可直接传递 PDF URL 而无需先进行 Base64 编码或上传文件。 * **优化计算类提示词**：对于涉及复杂计算或数据分析的请求，参考新的代码执行指南，适时显式要求“运行代码”以确保精度。 * **更新卸载文档**：若有内部关于 Claude Code VS Code 扩展的卸载指南，请更新为平台特定的路径命令。 7. **Final Review against constraints:** Chinese? Yes. Markdown? Yes. Concise? Yes. Developer focus? Yes.