name: claude-api
description: 构建、调试和优化 Claude API / Anthropic SDK 应用。使用此技能构建的应用应包含提示缓存。同时处理在 Claude 模型版本之间迁移现有的 Claude API 代码（4.5 → 4.6、4.6 → 4.7、已退役模型替换）。**触发条件**：代码导入 `anthropic`/`@anthropic-ai/sdk`；用户询问 Claude API、Anthropic SDK 或 Managed Agents；用户在文件中添加、修改或调优 Claude 功能（缓存、思考、压缩、工具使用、批处理、文件、引用、记忆）或模型（Opus/Sonnet/Haiku）；关于 Anthropic SDK 项目中提示缓存/缓存命中率的问题。**跳过**：文件导入 `openai`/其他提供商 SDK，文件名类似 `*-openai.py`/`*-generic.py`，提供商无关的代码，通用编程/机器学习。
license: Complete terms in LICENSE.txt

使用 Claude 构建 LLM 驱动的应用

本技能帮助您使用 Claude 构建 LLM 驱动的应用。根据您的需求选择正确的接口，检测项目语言，然后阅读相应的语言特定文档。

开始之前

扫描目标文件（如果没有目标文件，则扫描提示和项目）中非 Anthropic 提供商的标记——import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5、文件名称如 agent-openai.py 或 *-generic.py，或任何明确要求保持代码与提供商无关的说明。如果找到，请停止并告知用户本技能生成的是 Claude/Anthropic SDK 代码；询问他们是否希望将文件切换到 Claude，或希望使用非 Claude 实现。不要用 Anthropic SDK 调用编辑非 Anthropic 文件。

输出要求

当用户要求您添加、修改或实现 Claude 功能时，您的代码必须通过以下方式之一调用 Claude：

1. 项目的语言对应的官方 Anthropic SDK（anthropic、@anthropic-ai/sdk、com.anthropic.* 等）。只要项目有支持的 SDK，这就是默认选择。
2. 原始 HTTP（curl、requests、fetch、httpx 等）——仅当用户明确要求 cURL/REST/原始 HTTP、项目是 shell/cURL 项目，或者该语言没有官方 SDK 时。

切勿混用两者——不要因为感觉更轻量就使用 requests/fetch 代替 Python 或 TypeScript 项目中的 SDK。永远不要退回到 OpenAI 兼容的 shim。

切勿猜测 SDK 用法。 函数名、类名、命名空间、方法签名和导入路径必须来自明确的文档——要么是本技能中的 {lang}/ 文件，要么是 shared/live-sources.md 中列出的官方 SDK 仓库或文档链接。如果您需要的绑定在技能文件中没有明确记录，请在编写代码前 WebFetch shared/live-sources.md 中的相关 SDK 仓库。不要从 cURL 形状或其他语言的 SDK 推断 Ruby/Java/Go/PHP/C# API。

默认值

除非用户另有要求：

对于 Claude 模型版本，请使用 Claude Opus 4.8，您可以通过精确的模型字符串 claude-opus-4-8 访问它。对于任何稍微复杂的情况，请默认使用自适应思考（thinking: {type: "adaptive"}）。最后，对于可能涉及长输入、长输出或高 max_tokens 的任何请求，请默认使用流式传输——它避免了请求超时。如果您不需要处理单个流事件，可以使用 SDK 的 .get_final_message() / .finalMessage() 辅助方法来获取完整响应。

---

子命令

如果本提示底部的用户请求是一个裸子命令字符串（没有文字说明），请搜索本文档中的每个子命令表格——包括下方附加的任何部分——并直接执行匹配的操作列。这允许用户通过 /claude-api <子命令> 调用特定流程。如果文档中没有表格匹配，则将请求视为普通文字说明。

---

语言检测

在阅读代码示例之前，确定用户正在使用哪种语言：

1. 查看项目文件以推断语言：

• *.py、requirements.txt、pyproject.toml、setup.py、Pipfile → Python — 从 python/ 阅读
• *.ts、*.tsx、package.json、tsconfig.json → TypeScript — 从 typescript/ 阅读
• *.js、*.jsx（没有 .ts 文件） → TypeScript — JS 使用相同的 SDK，从 typescript/ 阅读
• *.java、pom.xml、build.gradle → Java — 从 java/ 阅读
• *.kt、*.kts、build.gradle.kts → Java — Kotlin 使用 Java SDK，从 java/ 阅读
• *.scala、build.sbt → Java — Scala 使用 Java SDK，从 java/ 阅读
• *.go、go.mod → Go — 从 go/ 阅读
• *.rb、Gemfile → Ruby — 从 ruby/ 阅读
• *.cs、*.csproj → C# — 从 csharp/ 阅读
• *.php、composer.json → PHP — 从 php/ 阅读

1. 如果检测到多种语言（例如，同时存在 Python 和 TypeScript 文件）：

• 检查用户当前文件或问题涉及哪种语言
• 如果仍然不明确，询问：“我检测到 Python 和 TypeScript 文件。您使用哪种语言进行 Claude API 集成？”

1. 如果无法推断语言（空项目、没有源文件或不受支持的语言）：

• 使用 AskUserQuestion 提供选项：Python、TypeScript、Java、Go、Ruby、cURL/原始 HTTP、C#、PHP
• 如果 AskUserQuestion 不可用，默认使用 Python 示例并注明：“显示 Python 示例。如果您需要其他语言，请告知。”

1. 如果检测到不受支持的语言（Rust、Swift、C++、Elixir 等）：

• 建议从 curl/ 获取 cURL/原始 HTTP 示例，并说明可能存在社区 SDK
• 提供 Python 或 TypeScript 示例作为参考实现

1. 如果用户需要 cURL/原始 HTTP 示例，从 curl/ 阅读。

语言特定功能支持

托管代理代码示例：为 Python、TypeScript、Go、Ruby、PHP、Java 和 cURL 提供了专门的语言特定 README（{lang}/managed-agents/README.md、curl/managed-agents.md）。请阅读您的语言的 README 以及语言无关的 shared/managed-agents-*.md 概念文件。代理是持久化的——创建一次，通过 ID 引用。 存储 agents.create 返回的代理 ID，并将其传递给每个后续的 sessions.create 调用；不要在请求路径中调用 agents.create。Anthropic CLI 是从版本控制的 YAML 创建代理和环境的一种便捷方式——其 URL 在 shared/live-sources.md 中。如果您需要的绑定在 README 中没有显示，请 WebFetch shared/live-sources.md 中的相关条目，而不是猜测。C# 目前不支持托管代理；请使用 cURL 风格的原始 HTTP 请求访问 API。

---

我应该使用哪个接口？

从简单开始。 默认使用满足您需求的最简单层级。单次 API 调用和工作流可以处理大多数用例——只有当任务需要开放式的、模型驱动的探索时才使用代理。

注意： 当您希望 Anthropic 运行代理循环并且托管工具执行的容器时，托管代理是正确的选择——文件操作、bash、代码执行都在每会话的工作空间中运行。如果您希望自己托管计算或运行自己的自定义工具运行时，Claude API + 工具使用是正确的选择——使用工具运行器进行自动循环处理，或使用手动循环进行精细控制（审批门、自定义日志记录、条件执行）。

第三方提供商（Amazon Bedrock、Google Vertex AI、Microsoft Foundry）： 托管代理在 Bedrock、Vertex 或 Foundry 上不可用。如果您通过任何第三方提供商部署，请对所有用例（包括原本推荐托管代理的用例）使用 Claude API + 工具使用。

决策树

您的应用程序需要什么？

0. 您是否通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 部署？
   └── 是 → Claude API（对于代理使用 + 工具使用）——托管代理仅限第一方。
   否 → 继续。

1. 单次 LLM 调用（分类、摘要、提取、问答）
   └── Claude API — 一个请求，一个响应

2. 您是否希望 Anthropic 运行代理循环并托管每会话的
   容器，让 Claude 在其中执行工具（bash、文件操作、代码）？
   └── 是 → 托管代理 — 服务器管理的会话、持久化的代理配置、
       SSE 事件流、技能 + MCP、文件挂载。
       示例：“每个任务带工作空间的有状态编码代理”、
              “长时间运行的研究代理，将事件流式传输到 UI”、
              “跨多个会话使用的持久化、版本化配置的代理”

3. 工作流（多步骤、由代码编排、使用自己的工具）
   └── Claude API 使用工具 — 您控制循环

4. 开放式代理（模型决定其自己的轨迹、您自己的工具、您托管计算）
   └── Claude API 代理循环（最大灵活性）

我应该构建代理吗？

在选择代理层级之前，检查所有四个标准：

• 复杂性 — 任务是否多步骤且难以完全预先指定？（例如，“将此设计文档转化为 PR”与“从 PDF 中提取标题”）
• 价值 — 结果是否值得更高的成本和延迟？
• 可行性 — Claude 在任务类型上是否有能力？
• 错误成本 — 错误能否被捕获并恢复？（测试、审查、回滚）

如果对任何一个问题回答“否”，则保持在更简单的层级（单次调用或工作流）。

---

架构

所有内容都通过 POST /v1/messages 进行。工具和输出约束是这个单一端点的功能——而不是独立的 API。

用户定义的工具 — 您定义工具（通过装饰器、Zod 模式或原始 JSON），SDK 的工具运行器处理 API 调用、执行您的函数并循环直到 Claude 完成。要完全控制，您可以手动编写循环。

服务端工具 — Anthropic 托管的在 Anthropic 基础设施上运行的工具。代码执行完全在服务端（在 tools 中声明，Claude 自动运行代码）。计算机使用可以服务器托管或自托管。

结构化输出 — 约束消息 API 响应格式（output_config.format）和/或工具参数验证（strict: true）。推荐的方法是 client.messages.parse()，它会根据您的模式自动验证响应。注意：旧的 output_format 参数已弃用；请在 messages.create() 上使用 output_config: {format: {...}}。

辅助端点 — 批处理（POST /v1/messages/batches）、文件（POST /v1/files）、Token 计数和模型（GET /v1/models、GET /v1/models/{id}——实时能力和上下文窗口发现）为消息 API 请求提供支持。

---

当前模型（缓存于：2026-05-26）

始终使用 claude-opus-4-8，除非用户明确指定了不同的模型。 这是不可协商的。除非用户明确说出“使用 sonnet”或“使用 haiku”，否则不要使用 claude-sonnet-4-6、claude-sonnet-4-5 或任何其他模型。永远不要为了降低成本而降级——那是用户的决定，不是您的。

关键：只使用上表中精确的模型 ID 字符串——它们完整且不变。不要附加日期后缀。 例如，使用 claude-sonnet-4-5，永远不要使用 claude-sonnet-4-5-20250514 或您可能从训练数据中回忆起的任何其他日期后缀变体。如果用户请求表中没有的旧模型（例如“opus 4.5”、“sonnet 3.7”），请阅读 shared/models.md 获取精确 ID——不要自己构造。

注意：如果以上任何模型字符串看起来不熟悉，这是正常的——这意味着它们是在您的训练数据截止日期之后发布的。请放心，它们是真实存在的模型；我们不会那样误导您。

实时能力查询： 上表是缓存。当用户询问“X 的上下文窗口是多少”、“X 是否支持视觉/思考/努力”或“哪些模型支持 Y”时，查询模型 API（client.models.retrieve(id) / client.models.list()）——请参见 shared/models.md 以获取字段参考和能力过滤示例。

---

思考与努力（快速参考）

Opus 4.8 / 4.7 — 仅自适应思考： 使用 thinking: {type: "adaptive"}。thinking: {type: "enabled", budget_tokens: N} 会返回 400——自适应是唯一的开启模式。{type: "disabled"} 和省略 thinking 都可以。采样参数（temperature、top_p、top_k）也被移除，使用会返回 400。Opus 4.8 保持与 4.7 相同的请求接口（没有新的破坏性变更）——请参见 shared/model-migration.md → 迁移到 Opus 4.8 了解行为重新调整，以及 → 迁移到 Opus 4.7 了解从 4.6 或更早版本迁移时的完整破坏性变更列表。注意：当 thinking 禁用时，Opus 4.8 可能会在可见响应中写入更长的推理内容——请保持自适应思考开启，或添加仅最终答案的指令（参见迁移指南）。

Opus 4.6 — 自适应思考（推荐）： 使用 thinking: {type: "adaptive"}。Claude 动态决定何时以及思考多少。不需要 budget_tokens——budget_tokens 在 Opus 4.6 和 Sonnet 4.6 上已弃用，不应用于新代码。自适应思考还会自动启用交错思考（不需要 beta 标头）。当用户要求“扩展思考”、“思考预算”或 budget_tokens 时：始终使用 Opus 4.8、4.7 或 4.6 并搭配 thinking: {type: "adaptive"}。固定 token 预算用于思考的概念已弃用——自适应思考取代了它。不要在新 4.6/4.7/4.8 代码中使用 budget_tokens，也不要切换到旧模型。 *渐进迁移豁免：* 在 Opus 4.6 和 Sonnet 4.6 上，budget_tokens 仍然作为过渡性逃生舱口可用——如果您正在迁移现有代码且需要在调优 effort 之前设置硬 token 上限，请参见 shared/model-migration.md → 过渡性逃生舱口。注意：此豁免不适用于 Opus 4.7 或 4.8——budget_tokens 在那里已完全移除。

努力参数（GA，无 beta 标头）： 通过 output_config: {effort: "low"|"medium"|"high"|"max"}（在 output_config 内部，不是顶层）控制思考深度和整体 token 消耗。默认为 high（等同于省略它）。max 仅 Opus 层级可用（Opus 4.6 及更高版本——不是 Sonnet 或 Haiku）。Opus 4.7 添加了 "xhigh"（介于 high 和 max 之间）——对于 Opus 4.7/4.8 上的大多数编码和代理用例来说是最好的设置，也是 Claude Code 中的默认值；对于大多数对智能敏感的工作，至少使用 high。适用于 Opus 4.5、Opus 4.6、Opus 4.7、Opus 4.8 和 Sonnet 4.6。在 Sonnet 4.5 / Haiku 4.5 上会出错。在 Opus 4.7 和 4.8 上，努力参数比任何以前的 Opus 更重要——迁移时重新调优，并在给定完整任务规范的情况下使用 high/xhigh 运行长周期/代理任务。结合自适应思考以获得最佳成本-质量权衡。较低的努力意味着更少且更合并的工具调用、更少的前置信息和更简洁的确认——high 通常是平衡质量和 token 效率的甜蜜点；当正确性比成本更重要时使用 max；对子代理或简单任务使用 low。

Opus 4.8 / 4.7 — 思考内容默认省略： thinking 块仍然会流式传输，但其文本为空，除非您选择使用 thinking: {type: "adaptive", display: "summarized"}（默认是 "omitted"）。静默变更——没有错误。如果您向用户流式传输推理，默认看起来像是在输出前长时间暂停；设置 "summarized" 以恢复可见进度。

任务预算（测试版，Opus 4.7 / 4.8）： output_config: {task_budget: {type: "tokens", total: N}} 告诉模型它在整个代理循环中有多少 token——它看到一个正在运行的倒计时并自我调节（最低 20,000；beta 标头 task-budgets-2026-03-13）。与 max_tokens 不同，后者是模型无法感知的强制单响应上限。请参见 shared/model-migration.md → 任务预算。

Sonnet 4.6： 支持自适应思考（thinking: {type: "adaptive"}）。budget_tokens 在 Sonnet 4.6 上已弃用——改用自适应思考。

旧模型（仅在明确请求时）： 如果用户特别要求 Sonnet 4.5 或其他旧模型，请使用 thinking: {type: "enabled", budget_tokens: N}。budget_tokens 必须小于 max_tokens（最低 1024）。永远不要因为用户提到 budget_tokens 而选择旧模型——改用 Opus 4.8 搭配自适应思考。

---

压缩（快速参考）

测试版，Opus 4.8、Opus 4.7、Opus 4.6 和 Sonnet 4.6。 对于可能超过 1M 上下文窗口的长时间对话，启用服务端压缩。API 会在接近触发阈值（默认：150K token）时自动总结较早的上下文。需要 beta 标头 compact-2026-01-12。

关键： 在每轮对话中，将 response.content（而不仅仅是文本）追加回您的消息。响应中的压缩块必须保留——API 使用它们在下一次请求中替换被压缩的历史记录。仅提取文本字符串并追加会静默丢失压缩状态。

有关代码示例，请参见 {lang}/claude-api/README.md（压缩部分）。完整文档请通过 WebFetch 在 shared/live-sources.md 中获取。

---

提示缓存（快速参考）

前缀匹配。 前缀中任何字节的更改都会使之后的所有内容失效。渲染顺序是 tools → system → messages。首先放置稳定的内容（冻结的系统提示、确定性的工具列表），将易变的内容（时间戳、每次请求的 ID、变化的提问）放在最后一个 cache_control 断点之后。

顶级自动缓存（在 messages.create() 上使用 cache_control: {type: "ephemeral"}）是最简单的选项，当您不需要精细放置时。每个请求最多 4 个断点。最小可缓存前缀约为 1024 个 token——更短的前缀将静默不缓存。

使用 usage.cache_read_input_tokens 验证——如果它在重复请求中为零，则存在静默的无效化器（系统提示中的 datetime.now()、未排序的 JSON、变化的工具集）。

有关放置模式、架构指导和静默无效化器审计清单：请阅读 shared/prompt-caching.md。语言特定语法：{lang}/claude-api/README.md（提示缓存部分）。

---

托管代理（测试版）

托管代理 是第三种接口：服务端管理的有状态代理，具有 Anthropic 托管的工具执行。您创建一个持久化、版本化的代理配置（POST /v1/agents），然后启动引用它的会话。每个会话配置一个容器作为代理的工作空间——bash、文件操作和代码执行在那里运行；代理循环本身在 Anthropic 的编排层上运行，并通过工具对容器执行操作。会话流式传输事件；您将消息和工具结果发回。

托管代理仅限第一方。 它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。对于第三方提供商上的代理，请使用 Claude API + 工具使用。

强制流程： 代理（一次）→ 会话（每次运行）。model/system/tools 位于代理上，不在会话上。参见 shared/managed-agents-overview.md 以获取完整的阅读指南、beta 标头和陷阱。

Beta 标头： managed-agents-2026-04-01——SDK 会自动为所有 client.beta.{agents,environments,sessions,vaults,memory_stores}.* 调用设置此标头。技能 API 使用 skills-2025-10-02，文件 API 使用 files-api-2025-04-14，但您不需要在 /v1/skills 和 /v1/files 以外的端点上显式传递它们。

子命令——直接用 /claude-api <子命令> 调用：

阅读指南： 从 shared/managed-agents-overview.md 开始，然后是主题性的 shared/managed-agents-*.md 文件（核心、环境、工具、事件、结果、多代理、webhook、内存、客户端模式、入门、API 参考）。对于 Python、TypeScript、Go、Ruby、PHP 和 Java，阅读 {lang}/managed-agents/README.md 以获取代码示例。对于 cURL，阅读 curl/managed-agents.md。代理是持久化的——创建一次，通过 ID 引用。 存储 agents.create 返回的代理 ID，并将其传递给每个后续的 sessions.create 调用；不要在请求路径中调用 agents.create。Anthropic CLI 是从版本控制的 YAML 创建代理和环境的一种便捷方式（URL 在 shared/live-sources.md 中）。如果您需要的绑定在语言 README 中没有显示，请 WebFetch shared/live-sources.md 中的相关条目，而不是猜测。C# 目前不支持托管代理；请使用 curl/managed-agents.md 中的原始 HTTP 作为参考。

当用户想从头开始设置托管代理时（例如“如何开始”、“请引导我创建一个”、“设置一个新代理”）：阅读 shared/managed-agents-onboarding.md 并执行其访谈——与 managed-agents-onboard 子命令相同的流程。

当用户问“如何为 X 编写客户端代码”时： 查阅 shared/managed-agents-client-patterns.md——涵盖无损流重连、processed_at 排队/处理门、中断、tool_confirmation 往返、正确的空闲/终止中断门、空闲后状态竞争、流优先排序、文件挂载陷阱、通过自定义工具将凭据保留在主机端等。

---

阅读指南

检测语言后，根据用户需要阅读相关文件：

快速任务参考

单次文本分类/摘要/提取/问答：

→ 仅阅读 {lang}/claude-api/README.md

聊天 UI 或实时响应显示：

→ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/streaming.md

长时间运行的对话（可能超出上下文窗口）：

→ 阅读 {lang}/claude-api/README.md——参见压缩部分

迁移到更新模型（Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6）或替换已退役模型：

→ 阅读 shared/model-migration.md

提示缓存 / 优化缓存 / “为什么我的缓存命中率低”：

→ 阅读 shared/prompt-caching.md + {lang}/claude-api/README.md（提示缓存部分）

函数调用 / 工具使用 / 代理：

→ 阅读 {lang}/claude-api/README.md + shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md

代理设计（工具接口、上下文管理、缓存策略）：

→ 阅读 shared/agent-design.md

批处理（非延迟敏感）：

→ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/batches.md

跨多个请求上传文件：

→ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/files-api.md

托管代理（服务端管理的有状态代理，带工作空间）：

→ 阅读 shared/managed-agents-overview.md + 其他 shared/managed-agents-*.md 文件。对于 Python、TypeScript、Go、Ruby、PHP 和 Java，阅读 {lang}/managed-agents/README.md 以获取代码示例。对于 cURL，阅读 curl/managed-agents.md。代理是持久化的——创建一次，通过 ID 引用。 存储 agents.create 返回的代理 ID，并将其传递给每个后续的 sessions.create 调用；不要在请求路径中调用 agents.create。Anthropic CLI 是从版本控制的 YAML 创建代理和环境的一种便捷方式（URL 在 shared/live-sources.md 中）。如果您需要的绑定在语言 README 中没有显示，请 WebFetch shared/live-sources.md 中的相关条目，而不是猜测。C# 目前不支持托管代理——使用 curl/managed-agents.md 中的原始 HTTP 作为参考。

Claude API（完整文件参考）

阅读语言特定的 Claude API 文件夹（{language}/claude-api/）：

1. {language}/claude-api/README.md — 首先阅读此文件。 安装、快速入门、常见模式、错误处理。
2. shared/tool-use-concepts.md — 当用户需要函数调用、代码执行、内存或结构化输出时阅读。涵盖概念基础。
3. shared/agent-design.md — 设计代理时阅读：bash 与专用工具、程序化工具调用、工具搜索/技能、上下文编辑与压缩与内存、缓存原则。
4. {language}/claude-api/tool-use.md — 阅读语言特定的工具使用代码示例（工具运行器、手动循环、代码执行、内存、结构化输出）。
5. {language}/claude-api/streaming.md — 构建聊天 UI 或增量显示响应的界面时阅读。
6. {language}/claude-api/batches.md — 离线处理多个请求时阅读（非延迟敏感）。异步运行，成本降低 50%。
7. {language}/claude-api/files-api.md — 在多个请求中发送相同文件而不重新上传时阅读。
8. shared/prompt-caching.md — 添加或优化提示缓存时阅读。涵盖前缀稳定性设计、断点放置以及静默使缓存失效的反模式。
9. shared/error-codes.md — 调试 HTTP 错误或实现错误处理时阅读。
10. shared/model-migration.md — 升级到更新模型、替换已退役模型或将 budget_tokens / 预填充模式转换为当前 API 时阅读。
11. shared/live-sources.md — WebFetch URL，用于获取最新的官方文档。

注意： 对于 Java、Go、Ruby、C#、PHP 和 cURL——每个语言都有一个文件涵盖所有基础知识。阅读该文件以及按需阅读 shared/tool-use-concepts.md 和 shared/error-codes.md。

注意： 有关托管代理的文件参考，请参见上面的 ## 托管代理（测试版） 部分——它列出了每个 shared/managed-agents-*.md 文件和语言特定的 README。

---

何时使用 WebFetch

在以下情况下使用 WebFetch 获取最新文档：

• 用户询问“最新”或“当前”信息
• 缓存数据似乎不正确
• 用户询问此处未涵盖的功能

实时文档 URL 在 shared/live-sources.md 中。

常见陷阱

• 将文件或内容传递给 API 时，不要截断输入。如果内容太长无法适应上下文窗口，请通知用户并讨论选项（分块、摘要等），而不是静默截断。
• Opus 4.8 / 4.7 思考： 仅自适应。thinking: {type: "enabled", budget_tokens: N} 返回 400——budget_tokens 已完全移除（以及 temperature、top_p、top_k）。使用 thinking: {type: "adaptive"}。Opus 4.8 从 4.7 继承了此接口，没有新的破坏性变更。
• Opus 4.6 / Sonnet 4.6 思考： 使用 thinking: {type: "adaptive"}——不要在新 4.6 代码中使用 budget_tokens（在 Opus 4.6 和 Sonnet 4.6 上已弃用；对于现有代码的渐进迁移，请参见 shared/model-migration.md 中的过渡性逃生舱口——注意此豁免不适用于 Opus 4.7 或 4.8）。对于旧模型，budget_tokens 必须小于 max_tokens（最低 1024）。如果弄错，会抛出错误。
• 4.6/4.7/4.8 系列预填充已移除： 助手消息预填充（最后助手轮次预填充）在 Opus 4.6、Opus 4.7、Opus 4.8 和 Sonnet 4.6 上返回 400 错误。请使用结构化输出（output_config.format）或系统提示指令来控制响应格式。
• 编辑前确认迁移范围： 当用户要求将代码迁移到更新的 Claude 模型，但没有指定特定文件、目录或文件列表时，先询问要应用的范围——整个工作目录、特定子目录还是特定文件集。在用户确认之前不要开始编辑。命令式措辞如“迁移我的代码库”、“将我的项目移到 X”、“升级到 Sonnet 4.6”或裸的“迁移到 Opus 4.8”仍然是不明确的——它们告诉您要做什么，但没有告诉您在哪里做，所以请询问。只有当提示命名了确切文件、特定目录或显式文件列表（“迁移 app.py”、“迁移 services/ 下的所有内容”、“更新 a.py 和 b.py”）时才无需询问直接进行。参见 shared/model-migration.md 步骤 0。
• max_tokens 默认值： 不要低估 max_tokens——达到上限会在思考中途截断输出并需要重试。对于非流式请求，默认值约为 ~16000（使响应保持在 SDK HTTP 超时以下）。对于流式请求，默认值约为 ~64000（超时不是问题，给模型留出空间）。只有在有硬性理由时才设置更低：分类（~256）、成本上限或故意短输出。
• 128K 输出 token： Opus 4.6、Opus 4.7 和 Opus 4.8 支持高达 128K 的 max_tokens，但 SDK 需要流式传输来处理这么大的值以避免 HTTP 超时。使用 .stream() 和 .get_final_message() / .finalMessage()。
• 工具调用 JSON 解析（4.6/4.7/4.8 系列）： Opus 4.6、Opus 4.7、Opus 4.8 和 Sonnet 4.6 可能产生不同的 JSON 字符串转义在工具调用 input 字段中（例如 Unicode 或正斜杠转义）。始终使用 json.loads() / JSON.parse() 解析工具输入——永远不要对序列化输入进行原始字符串匹配。
• 结构化输出（所有模型）： 使用 output_config: {format: {...}} 代替已弃用的 output_format 参数在 messages.create() 上。这是一个通用的 API 变更，不是 4.6 特有的。
• 不要重新实现 SDK 功能： SDK 提供了高级辅助方法——请使用它们，而不是从头构建。具体来说：使用 stream.finalMessage() 而不是将 .on() 事件包装在 new Promise() 中；使用类型化的异常类（Anthropic.RateLimitError 等）而不是字符串匹配错误消息；使用 SDK 类型（Anthropic.MessageParam、Anthropic.Tool、Anthropic.Message 等）而不是重新定义等效接口。
• 不要为 SDK 数据结构定义自定义类型： SDK 为所有 API 对象导出了类型。对消息使用 Anthropic.MessageParam，对工具定义使用 Anthropic.Tool，对工具结果使用 Anthropic.ToolUseBlock / Anthropic.ToolResultBlockParam，对响应使用 Anthropic.Message。定义自己的 interface ChatMessage { role: string; content: unknown } 会复制 SDK 已提供的内容并失去类型安全性。
• 报告和文档输出： 对于生成报告、文档或可视化结果的任务，代码执行沙箱预装了 python-docx、python-pptx、matplotlib、pillow 和 pypdf。Claude 可以生成格式化文件（DOCX、PDF、图表）并通过文件 API 返回它们——对于“报告”或“文档”类型的请求，考虑这一点，而不是仅使用纯文本 stdout。