### 文档变更分析摘要
#### 1. 总体摘要
本次文档更新正式发布并全面集成了 **Claude Sonnet 5.5**。此次更新将其确立为 Sonnet 系列的最新旗舰模型，重点强调了其在上下文窗口、推理能力上的提升，以及与早期模型（如 Opus 5.5 和 Fable）类似的强制推理策略和新引入的 API 行为约束。
#### 2. 关键变更主题
* **Claude Sonnet 5.5 正式发布**：文档全量引入 Sonnet 5.5，包括模型规格、定价（与 Sonnet 5 相同的 $2/$10 结构）、速率限制及生命周期（2027 年 9 月退役）。
* **强制推理与新增思维模式**：与 Opus 5.5 和 Fable 类似，Sonnet 5.5 **不允许**禁用思考（`thinking.type: "disabled"`）。文档引入了新的 `thinking.type: "between_tools"` 模式，用于在低延迟场景下禁用“前置思考”，但仍允许工具间思考。
* **模型能力对齐**：Sonnet 5.5 现在支持 **1M token 上下文窗口**、保留思考块和对话中系统消息注入等功能，使其在架构上更接近高端模型。
* **Effort（努力程度）重新校准**：Sonnet 5.5 默认使用 `high` 努力程度，但与 Sonnet 5 相比，其各层级（`low`, `medium`, `high` 等）的推理深度和行为已重新校准，不再直接等同于旧版本。
* **API 错误处理更新**：增加了针对 Sonnet 5.5 特定行为的错误说明，特别是关于在 `xhigh`/`max` effort 下尝试使用 `between_tools` 时的 `400 invalid_request_error`，以及对强制的工具使用（`tool_choice`）的限制。
#### 3. 影响程度
**高**
**理由**：这不仅是一个新模型的发布，还引入了**破坏性的 API 行为变更**。如果开发者现有的代码逻辑中包含“禁用思考”的配置，直接迁移到 Sonnet 5.5 将会导致 API 报错。此外，努力程度的重新校准意味着现有的性能基准和成本配置需要重新评估。
#### 4. 开发者行动项
* **更新模型标识**：将模型 ID 更新为 `claude-sonnet-5-5`，或使用 `sonnet` 别名（目前 `sonnet` 仍指向 Sonnet 5，但需关注 Alias 解析变化，文档显示 `sonnet` 别名行为未变，但 5.5 已加入列表，未来可能切换）。
* **修正推理配置逻辑**：**切勿**对 Sonnet 5.5 发送 `thinking: {"type": "disabled"}`。如需禁用前置思考，请使用 `thinking: {"type": "between_tools"}`；如需控制深度，请使用 `adaptive` 模式配合 `output_config.effort`。
* **处理新增错误代码**：在 API 错误处理逻辑中增加对 Sonnet 5.5 特定错误的捕获（例如在 `xhigh` effort 下错误使用 `between_tools` 的错误），并相应回退到 `adaptive` 模式或降低 effort。
* **重新评估 Effort 设置**：由于努力程度已重新校准，建议基于 Sonnet 5.5 重新运行评估。对于通用任务默认保持 `high`，对于复杂 Agent 任务从 `medium` 开始测试。
* **检查上下文配置**：利用 Sonnet 5.5 新增的 1M 上下文窗口和会话中系统消息功能，优化长对话和复杂任务的 Prompt 结构。
💭 Model Reasoning
1. **Understand the Goal:** The user wants a concise, insightful analysis of a batch of documentation changes (34 pages provided, but I see diffs for about 15-20 key pages) in Markdown format. I need to act as a world-class programmer. The response must be in Chinese.
2. **Scan the Diffs for Patterns:**
* **Page: costs.md:** "You can't turn off thinking on Opus 5.5, Sonnet 5.5, or the Fable models..." -> Addition of Sonnet 5.5 to the list of models with forced extended thinking.
* **Page: desktop.md:** "Has no effect on Opus 5.5, Sonnet 5.5, or the Fable models..." & "Fable models, Sonnet 5 and later..." -> Sonnet 5.5 added to "always thinking" list and "adaptive reasoning only" list.
* **Page: interactive-mode.md:** "Has no effect on Opus 5.5, Sonnet 5.5, or the Fable models..." -> Shortcut key change explanation for Sonnet 5.5.
* **Page: model-config.md:** Table update. "No effect when `sonnet` already resolves to Sonnet 5.5 or Sonnet 5..." -> Model alias resolution includes Sonnet 5.5.
* **Page: intro.md:** "Claude Sonnet 5.5... New" -> Announcement of Sonnet 5.5.
* **Page: about-claude/models/overview.md:** Table update. Added Sonnet 5.5 row. 1M context, Adaptive thinking, specific cutoff dates (Jan 2026 knowledge).
* **Page: about-claude/models/migration-guide.md:** Link update to Sonnet 5.5 guide.
* **Page: about-claude/pricing.md:** Added Sonnet 5.5 pricing rows ($2/$10 input/output or similar structures).
* **Page: about-claude/model-deprecations.md:** Added Sonnet 5.5 lifecycle date (Sept 28, 2027).
* **Page: api/client-sdks.md:** Title/Description change (minor).
* **Page: api/rate-limits.md:** Added Sonnet 5.5 rate limits.
* **Page: api/service-tiers.md:** Added Sonnet 5.5 to exclusion list for Priority Tier.
* **Page: api/errors.md:** Major addition. Errors specific to Sonnet 5.5 thinking behavior (`between_tools`, `disabled` not supported). Added Sonnet 5.5 to "Forced tool use not supported" and "Thinking block no longer matches".
* **Page: build-with-claude/extended-thinking.md:** Added Sonnet 5.5 to migration warning list.
* **Page: build-with-claude/prompt-caching.md:** Added Sonnet 5.5 to pricing and "minimum cacheable prompt" (512 tokens). Added to "Dropped thinking blocks" logic.
* **Page: build-with-claude/batch-processing.md:** Added Sonnet 5.5 to pricing and "Extended output" support.
* **Page: build-with-claude/context-windows.md:** Added Sonnet 5.5 to 1M token list.
* **Page: build-with-claude/context-editing.md:** Added Sonnet 5.5 to "server-side context management" logic.
* **Page: build-with-claude/structured-outputs.md:** Added Sonnet 5.5 to supported list.
* **Page: build-with-claude/effort.md:** Added Sonnet 5.5 to supported list. New section "Recommended effort levels for Claude Sonnet 5.5". Defaults to `high`. Mention of `between_tools` thinking type.
* **Page: build-with-claude/working-with-messages.md:** Added Sonnet 5.5 to "System role in messages" support.
* **Page: build-with-claude/claude-on-amazon-bedrock.md:** Added Sonnet 5.5 to Bedrock support lists (Context window, System messages).
* **Page: build-with-claude/claude-on-vertex-ai.md:** Added Sonnet 5.5 ID and context window info.
* **Page: build-with-claude/claude-in-microsoft-foundry.md:** Added Sonnet 5.5 support (Global Standard only).
* **Page: build-with-claude/prompt-engineering/prompting-tools.md:** Added Sonnet 5.5 to the list of current models and guidance links.
3. **Synthesize the "What":**
* The primary change is the **introduction and documentation of Claude Sonnet 5.5**.
* It is positioned as the latest model (tagged "New" in intro).
* It shares characteristics with other 5.x models: 1M context window, adaptive reasoning.
* **Critical constraint:** Like Opus 5.5 and Fable, Sonnet 5.5 *cannot* have thinking turned off (it's always on).
* **New API nuance:** It introduces a specific thinking type `between_tools` to handle the "lowest setting" scenario since `disabled` is rejected.
* **Pricing/Rate Limits:** It appears alongside Sonnet 5, likely replacing it or being a parallel upgrade (same price point listed as Sonnet 5 in some tables, but distinct ID).
* **Effort defaults:** Defaults to `high` on API, recommends `medium` for agentic work.
4. **Determine the "Why it Matters":**
* **Feature parity:** It brings high-end features (1M context, preserved thinking, mid-conversation system messages) to the Sonnet tier.
* **API Breaking/Behavioral Changes:** If developers try to disable thinking on Sonnet 5.5, they will get errors. They must use `between_tools` or adaptive thinking.
* **Effort Levels:** Effort levels are "recalibrated" compared to Sonnet 5, so existing configurations might need tuning.
* **Cost/Performance:** It seems to be a direct upgrade path for Sonnet 5 users.
5. **Draft the Response (in Chinese):**
* *Summary:* This update officially launches **Claude Sonnet 5.5**, integrating it into the ecosystem. It adds comprehensive documentation regarding its capabilities, pricing, and specific behavioral constraints, particularly regarding forced adaptive reasoning and new thinking modes.
* *Key Themes:*
* **Sonnet 5.5 Release:** A major new model added across all docs.
* **Reasoning Constraints:** Unlike previous versions, Sonnet 5.5 forces adaptive reasoning (extended thinking). You cannot set `thinking.type: "disabled"`.
* **New API Behavior:** Introduction of `thinking.type: "between_tools"` for low-latency requests on Sonnet 5.5.
* **1M Context & Parity:** Sonnet 5.5 now supports the 1M token context window, preserved thinking blocks, and mid-conversation system messages (features previously reserved for Opus/Fable).
* **Recalibrated Effort:** Effort levels (like `high`, `xhigh`) are different from Sonnet 5; defaults to `high`.
* *Impact Level:* **High**. It's a new flagship model in the Sonnet family with specific API constraints (no disabling thinking) that will break existing logic if not handled.
* *Action Items:*
* Update model IDs to `claude-sonnet-5-5` (or alias `sonnet`).
* **Handle Thinking Logic:** Remove code that forces `thinking.type: "disabled"` on Sonnet 5.5. Use `between_tools` or `adaptive` instead.
* **Check Error Handling:** Add handling for the new `invalid_request_error` regarding `between_tools` and effort level conflicts.
* **Re-evaluate Effort:** Since effort is recalibrated, re-run evals (start with `high` default).
* **Update Configs:** Note that `MAX_THINKING_TOKENS=0` has no effect on this model.
6. **Refine the Language (Professional & Concise):**
* Use terms like "强制推理" (forced reasoning), "上下文窗口" (context window), "API 行为变更" (API behavior changes).
7. **Final Review against constraints:**
* Markdown format? Yes.
* Chinese? Yes.
* Concise? Yes.
* 5 action items max? Yes.
*(Self-Correction during drafting)*: Make sure to mention the `between_tools` nuance clearly, as that's a specific implementation detail developers will hit. Also, clarify that "Sonnet 5" still exists but 5.5 is the new "latest" for the alias.
*Final Polish:*
Summary: Introduction of Claude Sonnet 5.5.
Themes: New model, forced thinking, 1M context, new error codes.
Impact: High (API constraints).
Actions: Update model ID, fix thinking config, handle errors, re-test effort levels.
Looks good. Proceeding to generate output.