### 整体摘要
本次文档更新重点在于优化配置管理的一致性、细化 Hooks 系统的超时控制，并针对“程序化工具调用”提供了具体的性能基准数据与安全边界澄清。
### 关键变更主题
* **MCP 配置集成增强**：桌面端应用 (`claude_desktop_config.json`) 现自动将 MCP 服务器加载至 Code 标签页，减少了重复配置的需求。
* **性能与成本透明化**：明确指出了插件重载会导致 Prompt Cache 失效从而增加 Token 成本，并提供了程序化工具调用在具体场景下的性能提升数据。
* **API 行为微调与修正**：缩短了 `MessageDisplay` Hook 的默认超时时间（降至 10秒），并修正了 1M 上下文窗口后缀 `[1m]` 对 `opusplan` 的覆盖规则。
* **安全性概念澄清**：明确了 `allowed_callers` 仅作为模型调用指导，而非硬性的 API 级安全拦截机制。
### 影响等级：中等 (Medium)
**理由**：
1. **潜在运行时错误**：`MessageDisplay` Hook 的默认超时时间大幅缩短（从隐含的较长等待或未定义变为严格的 10秒），可能导致现有处理逻辑较慢的 Hook 超时失败。
2. **配置逻辑变更**：MCP 服务器的加载逻辑发生变化（桌面配置现在生效），虽然主要是增强，但改变了预期的配置作用域。
3. **安全假设修正**：`allowed_callers` 的性质澄清要求开发者重新评估现有的权限校验策略。
### 开发者行动项
* **检查 Hook 超时设置**：如果你使用了 `MessageDisplay` Hook，请务必检查其执行时间。如果处理逻辑超过 10 秒，必须在配置中显式设置更长的 `timeout`。
* **利用 MCP 配置同步**：评估是否可以移除 `.mcp.json` 中与 `claude_desktop_config.json` 重复的 MCP 服务器定义，直接利用桌面端配置的自动同步功能；对于独立 CLI，使用新的导入命令。
* **加强客户端鉴权**：在使用程序化工具调用时，不要依赖 `allowed_callers` 作为安全边界，务必在应用客户端代码层面实现对敏感工具的直接调用校验。
* **注意 `opusplan` 上下文限制**：在使用 `[1m]` 后缀时，请知晓 `opusplan` 模式下的 Opus 规划阶段仍受限于 200K 上下文窗口。
* **避免频繁重载插件**：在开发过程中，特别是当插件包含 MCP 服务器且未启用 tool search 时，应谨慎使用重载功能，以免因缓存失效导致 Token 成本激增。
💭 Model Reasoning
1. **Analyze the Request:**
* **Role:** World-class programmer with expertise in dev tools/docs.
* **Task:** Analyze 7 documentation changes (diffs provided) as a single batch.
* **Output Format:** Markdown.
* **Language:** Chinese.
* **Content Requirements:** Overall Summary, Key Themes, Impact Level (with reasoning), Action Items (max 5).
2. **Analyze the Diffs (Page by Page):**
* **Page 1: `desktop.md`**
* *Change:* Updated note about MCP (Model Context Protocol) servers.
* *Old:* Desktop app `claude_desktop_config.json` is separate from CLI/Code tab. To use in Code tab, configure in `.mcp.json`.
* *New:* Desktop app *now loads* `claude_desktop_config.json` servers into the Code tab alongside local configs. CLI standalone *does not* read it, but has an import command (`claude mcp add-from-claude-desktop`).
* *Impact:* Better integration between Desktop App and Code tab. Less manual config duplication for Desktop users.
* **Page 2: `discover-plugins.md`**
* *Change:* Added info about token costs when reloading plugins.
* *New:* Reloading plugins invalidates prompt cache, increasing cost on the next request because new components announce themselves. If plugins provide MCP servers and tools aren't deferred, the cache is invalidated.
* *Impact:* Performance/Cost warning. Developers need to be aware that hot-reloading isn't "free" in terms of tokens.
* **Page 3: `hooks.md`**
* *Change:* Updated `MessageDisplay` hook behavior and timeout defaults.
* *New:* `MessageDisplay` default timeout is 10 seconds. Added examples for stripping markdown. Clarified that it holds rendering until the hook returns (keep it fast). Updated the general table: `UserPromptSubmit` defaults to 30s, `MessageDisplay` defaults to 10s for command/http/mcp_tool types.
* *Impact:* Refinement of hook API. Crucial to know the new 10s timeout for UI display hooks to avoid failures.
* **Page 4: `hooks-guide.md`**
* *Change:* Updated timeout table for hooks.
* *New:* Consistent with Page 3: `MessageDisplay` lowers timeouts to 10s.
* *Impact:* Consistency check.
* **Page 5: `model-config.md`**
* *Change:* Clarified 1M context window suffix `[1m]`.
* *New:* Applies to `opus` and `sonnet` aliases. *Crucially*, it does *not* extend the plan-mode Opus phase of `opusplan` (remains 200K).
* *Impact:* Corrects a potential misunderstanding about context limits in planning mode.
* **Page 6: `structured-outputs.md`**
* *Change:* Availability updates for models on Amazon Bedrock.
* *New:* Removed "Claude Opus 4.8" from the "Generally Available" list for Bedrock? Wait, let me check the diff closely.
* *Diff:* Old: "generally available for Claude Opus 4.8, Claude Opus 4.6..." -> New: "generally available for Claude Opus 4.6..." (4.8 removed). Note says 4.8 is available via "Claude in Amazon Bedrock" (the Messages-API Bedrock endpoint).
* *Impact:* Availability/Platform specific change. Likely minor unless you are specifically using Opus 4.8 on standard Bedrock.
* **Page 7: `programmatic-tool-calling.md`**
* *Change:* Performance data, behavior clarification of `allowed_callers`, and error updates.
* *New:* Added specific performance benchmarks (11% improvement, 24% fewer tokens in benchmarks; 38% reduction in 75-tool benchmark). Clarified `allowed_callers` is not a hard security block (guidance only). Updated error codes (`tool_not_allowed` -> `invalid_request_error`). Added "Less ideal use cases".
* *Impact:* Significant clarity on performance trade-offs and security expectations.
3. **Synthesize the Themes:**
* *Performance & Cost:* Focus on token usage (plugin reloading, programmatic tool calling stats).
* *Integration & Configuration:* MCP servers now auto-sync from Desktop to Code tab; Context window limits clarified.
* *API Refinements:* Hook timeouts reduced for UI updates; Security guidance on `allowed_callers` softened (it's guidance, not a firewall).
4. **Drafting the Summary (in Chinese):**
* *Summary:* 此次更新重点增强了桌面应用与 CLI 之间的配置集成，优化了 Hooks 和插件系统的性能细节，并提供了关于“程序化工具调用”的更详尽的性能数据与安全边界说明。
* *Themes:*
* **MCP 集成增强**: 桌面端配置现自动加载至 Code tab，减少重复配置。
* **性能与成本控制**: 明确了插件重载的 Token 成本，以及程序化工具调用的实际节省数据。
* **API 行为微调**: 调整了 `MessageDisplay` hook 的超时限制，并澄清了 `allowed_callers` 的安全属性。
5. **Assessing Impact Level:**
* Is it "Breaking"? No, mostly clarifications and additions.
* Is it "High"? The timeout change in hooks (`MessageDisplay` defaults to 10s) could break existing hooks that took 11-20s. The MCP change is a feature addition/enhancement. The `allowed_callers` change is a security concept clarification.
* Let's go with **Medium**. The hook timeout change is the most likely to affect existing runtime behavior, and the MCP integration changes workflow. The programmatic calling updates are informational but important for architecture decisions.
6. **Formulating Action Items:**
* Check MCP config: You might be able to clean up duplicate configs now, or use the import command.
* Check Hooks: If you use `MessageDisplay`, verify it runs under 10s or explicitly set `timeout`.
* Tool Calling Security: Don't rely solely on `allowed_callers` for security; add client-side checks.
* Context Windows: Note that `opusplan` doesn't get the full 1M context upgrade via suffix.
7. **Refining the Output (translating and polishing):**
* *Summary:* 本次更新主要集中在提升配置管理的一致性、优化 Hooks 机制的响应速度，以及澄清关键 API（如程序化工具调用）的性能表现与安全边界。
* *Themes:*
* **配置一体化**: 桌面端 MCP 服务器配置现自动同步至 Code 标签页。
* **性能与资源消耗**: 明确了插件重载的 Token 成本，并提供了程序化工具调用的具体收益数据。
* **API 行为澄清**: 缩短了显示类 Hook 的默认超时时间，并修正了模型上下文窗口的覆盖范围。
* *Impact:* **Medium**.
* Reasoning: `MessageDisplay` hook 默认超时从 600s 降至 10s，可能导致现有的耗时 Hook 失败。MCP 配置逻辑的改变虽是增强，但也需要开发者了解新的同步行为。
* *Action Items:*
* **审查 Hook 超时**: 检查现有 `MessageDisplay` hook 的执行时间，如超过 10 秒需显式设置 `timeout` 字段。
* **清理 MCP 配置**: 利用桌面端配置自动同步至 Code tab 的新特性，移除 `.mcp.json` 中可能存在的重复服务器定义。
* **注意安全边界**: 使用程序化工具调用时，切勿将 `allowed_callers` 视为唯一的鉴权手段，应在客户端代码中添加必要的权限校验。
* **理解插件成本**: 在开发调试中避免频繁重载提供 MCP 服务器的插件，以防 Token 计费异常升高。
* **核对模型限制**: 若使用 `[1m]` 后缀开启长上下文，请注意 `opusplan` 的规划阶段仍限制在 200K。
8. **Final Review:** Does this match the "world-class programmer" persona? Yes, concise, technical, and actionable.