name: claude-api
description: 构建、调试和优化 Claude API / Anthropic SDK 应用程序。使用此技能构建的应用应包含提示缓存。同时处理现有 Claude API 代码在不同 Claude 模型版本之间的迁移（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 时使用。

切勿混用两者——不要因为感觉更轻量就在 Python 或 TypeScript 项目中使用 requests/fetch。切勿回退到兼容 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.7，您可以通过确切的模型字符串 claude-opus-4-7 访问它。对于任何较为复杂的任务，请默认使用自适应思考（thinking: {type: "adaptive"}）。最后，对于可能涉及长输入、长输出或高 max_tokens 的请求，默认使用流式传输——这可以防止请求超时。如果您不需要处理单个流事件，请使用 SDK 的 .get_final_message() / .finalMessage() 辅助方法来获取完整响应。

---

子命令

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

---

语言检测

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

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 中没有显示，请从 shared/live-sources.md 中 WebFetch 相关条目，而不是猜测。C# 目前不支持托管代理；请使用针对 API 的 cURL 样式原始 HTTP 请求。

---

我应该使用哪种方式？

从简单开始。 默认选择满足您需求的最简单层级。单个 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” vs. “从该 PDF 中提取标题”）
• 价值——结果是否值得更高的成本和延迟？
• 可行性——Claude 在此类任务上是否有能力？
• 错误成本——能否捕获错误并从中恢复？（测试、审查、回滚）

如果对其中任何一项的回答是“否”，请停留在更简单的层级（单次调用或工作流程）。

---

架构

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

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

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

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

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

---

当前模型（缓存日期：2026-04-15）

始终使用 claude-opus-4-7，除非用户明确指定了不同的模型。 这是不可协商的。除非用户明确说“使用 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”时，请查询 Models API（client.models.retrieve(id) / client.models.list()）——请参阅 shared/models.md 了解字段参考和能力过滤示例。

---

思考与努力度（快速参考）

Opus 4.7——仅支持自适应思考： 使用 thinking: {type: "adaptive"}。thinking: {type: "enabled", budget_tokens: N} 在 Opus 4.7 上返回 400 错误——自适应是唯一可用的开启模式。{type: "disabled"} 和省略 thinking 都有效。采样参数（temperature、top_p、top_k）也已移除，将返回 400。请参阅 shared/model-migration.md → 迁移到 Opus 4.7 以获取完整的破坏性更改列表。

Opus 4.6——自适应思考（推荐）： 使用 thinking: {type: "adaptive"}。Claude 动态决定何时以及进行多少思考。无需 budget_tokens——budget_tokens 在 Opus 4.6 和 Sonnet 4.6 上已弃用，不应在新代码中使用。自适应思考还自动启用交错思考（无需 beta 标头）。当用户要求“扩展思考”、“思考预算”或 budget_tokens 时：始终使用 Opus 4.7 或 4.6 配合 thinking: {type: "adaptive"}。 固定的思考令牌预算的概念已弃用——自适应思考取而代之。不要在针对 4.6/4.7 的新代码中使用 budget_tokens，也不要切换到较旧的模型。*逐步迁移例外条款：* budget_tokens 在 Opus 4.6 和 Sonnet 4.6 上仍然可用，作为过渡性的备用方案——如果您正在迁移现有代码并且需要在调整 effort 之前设置硬性令牌上限，请参阅 shared/model-migration.md → 过渡性备用方案。注意：此例外条款不适用于 Opus 4.7——budget_tokens 在那里已完全移除。

Effort 参数（GA，无需 beta 标头）： 通过 output_config: {effort: "low"|"medium"|"high"|"max"}（在 output_config 内部，非顶层）控制思考深度和整体令牌消耗。默认值为 high（相当于省略它）。max 仅限 Opus 层级（Opus 4.6 及更高版本——Sonnet 或 Haiku 不支持）。Opus 4.7 添加了 "xhigh"（介于 high 和 max 之间）——这是 4.7 上大多数编码和代理用例的最佳设置，也是 Claude Code 中的默认设置；对于大多数对智能敏感的工作，请至少使用 high。适用于 Opus 4.5、Opus 4.6、Opus 4.7 和 Sonnet 4.6。在 Sonnet 4.5 / Haiku 4.5 上会报错。在 Opus 4.7 上，努力度比之前的任何 Opus 都更重要——迁移时请重新调整。与自适应思考结合使用，以实现最佳成本-质量权衡。较低的努力度意味着更少、更整合的工具调用、更少的前言和更简洁的确认——high 通常是平衡质量和令牌效率的最佳点；当正确性比成本更重要时使用 max；对于子代理或简单任务使用 low。

Opus 4.7——思考内容默认省略： thinking 块仍然会流式传输，但它们的文本为空，除非您通过 thinking: {type: "adaptive", display: "summarized"} 选择启用（默认值为 "omitted"）。静默更改——无错误。如果您将推理过程流式传输给用户，默认行为看起来像是在输出之前长时间停顿；设置 "summarized" 以恢复可见的进度指示。

任务预算（Beta，Opus 4.7）： output_config: {task_budget: {type: "tokens", total: N}} 告知模型它可以用于整个代理循环的令牌数量——它会看到正在运行的倒计时并自我调节（最小值 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.7 配合自适应思考。

---

压缩（快速参考）

Beta，适用于 Opus 4.7、Opus 4.6 和 Sonnet 4.6。 对于可能超出 1M 上下文窗口的长时间运行对话，启用服务器端压缩。当对话接近触发阈值（默认：150K 令牌）时，API 会自动总结较早的上下文。需要 beta 标头 compact-2026-01-12。

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

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

---

提示缓存（快速参考）

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

顶层自动缓存（在 messages.create() 上使用 cache_control: {type: "ephemeral"}）是当您不需要精细位置控制时最简单的选项。每个请求最多 4 个断点。可缓存的前缀最小约为 1024 个令牌——较短的前缀会静默地不缓存。

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

有关放置模式、架构指导以及静默失效因素检查清单，请阅读 shared/prompt-caching.md。语言特定语法：{lang}/claude-api/README.md（提示缓存部分）。

---

托管代理（Beta）

托管代理是第三种使用方式：服务器管理的状态化代理，由 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 <subcommand> 调用：

阅读指南： 从 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 中没有显示，请从 shared/live-sources.md 中 WebFetch 相关条目，而不是猜测。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.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 中没有显示，请从 shared/live-sources.md 中 WebFetch 相关条目，而不是猜测。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 vs. 专用工具、程序化工具调用、工具搜索/技能、上下文编辑 vs. 压缩 vs. 内存、缓存原则。
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。

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

---

何时使用 WebFetch

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

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

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

常见陷阱

• 在将文件或内容传递给 API 时，不要截断输入。如果内容太长无法放入上下文窗口，请通知用户并讨论选项（分块、摘要等），而不是静默截断。
• Opus 4.7 思考： 仅自适应。thinking: {type: "enabled", budget_tokens: N} 在 Opus 4.7 上返回 400——budget_tokens 在那里已完全移除（temperature、top_p、top_k 也是如此）。使用 thinking: {type: "adaptive"}。
• 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）。对于较旧模型，budget_tokens 必须小于 max_tokens（最小 1024）。如果设置错误，将会抛出错误。
• 4.6/4.7 系列预填充已移除： 助手的消息预填充（最后一个助手轮次的预填充）在 Opus 4.6、Opus 4.7 和 Sonnet 4.6 上返回 400 错误。请改用结构化输出（output_config.format）或系统提示指令来控制响应格式。
• 在编辑前确认迁移范围： 当用户要求将代码迁移到较新的 Claude 模型但未指定具体文件名、目录或文件列表时，请先询问要应用的迁移范围——是整个工作目录、某个子目录还是特定的一组文件。在用户确认之前，不要开始编辑。诸如“迁移我的代码库”、“将我的项目移至 X”、“升级到 Sonnet 4.6”或仅说“迁移到 Opus 4.7”之类的命令式措辞仍然是模糊的——它们告诉您要做什么但没有告诉您在哪里，因此请询问。仅当提示词中指定了确切文件名、特定目录或明确的文件列表（“迁移 app.py”、“迁移 services/ 下的所有内容”、“更新 a.py 和 b.py”）时才无需询问直接继续。请参阅 shared/model-migration.md 第 0 步。
• max_tokens 默认值： 不要将 max_tokens 设置得太低——达到上限会在思考中途截断输出，需要重试。对于非流式请求，默认为 ~16000（使响应保持在 SDK HTTP 超时之下）。对于流式请求，默认为 ~64000（超时不是问题，因此给模型留出空间）。只有在有硬性理由时才设置更低的值：分类（~256）、成本上限或故意短的输出。
• 128K 输出令牌： Opus 4.6 和 Opus 4.7 支持高达 128K 的 max_tokens，但 SDK 需要流式传输来处理如此大的值以避免 HTTP 超时。使用 .stream() 配合 .get_final_message() / .finalMessage()。
• 工具调用 JSON 解析（4.6/4.7 系列）： Opus 4.6、Opus 4.7 和 Sonnet 4.6 可能会在工具调用的 input 字段中产生不同的 JSON 字符串转义（例如，Unicode 或正斜杠转义）。始终使用 json.loads() / JSON.parse() 解析工具输入——绝不要对序列化的输入进行原始字符串匹配。
• 结构化输出（所有模型）： 在 messages.create() 上使用 output_config: {format: {...}} 而不是已弃用的 output_format 参数。这是通用的 API 更改，并非 4.6 特有。
• 不要重新实现 SDK 功能： SDK 提供了高级辅助方法——请使用它们而不是从头开始构建。具体来说：使用 stream.finalMessage() 而不是在 new Promise() 中包装 .on() 事件；使用类型化的异常类（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 文本。