claude-api— agent skill

---
name: claude-api
description: "使用 Claude API 或 Anthropic SDK 构建应用。触发条件：代码导入 `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`，或用户要求使用 Claude API、Anthropic SDKs 或 Agent SDK。不触发条件：代码导入 `openai`/其他 AI SDK、通用编程或机器学习/数据科学任务。"
license: 完整条款见 LICENSE.txt
---

# 使用 Claude 构建 LLM 驱动的应用

本技能帮助你使用 Claude 构建 LLM 驱动的应用。根据你的需求选择合适的层面，检测项目语言，然后阅读相关的特定语言文档。

## 默认设置

除非用户另有要求：

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

---

## 语言检测

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

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/` 读取

2.  **如果检测到多种语言** (例如，同时存在 Python 和 TypeScript 文件):

    - 检查用户当前的文件或问题与哪种语言相关
    - 如果仍然不明确，提问：“我检测到 Python 和 TypeScript 文件。您正在使用哪种语言进行 Claude API 集成？”

3.  **如果无法推断语言** (空项目、无源文件或不支持的语言):

    - 使用 AskUserQuestion 并提供选项：Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
    - 如果 AskUserQuestion 不可用，默认使用 Python 示例并注明：“正在显示 Python 示例。如果您需要其他语言，请告诉我。”

4.  **如果检测到不支持的语言** (Rust, Swift, C++, Elixir 等):

    - 建议使用 `curl/` 中的 cURL/raw HTTP 示例，并指出可能存在社区 SDK
    - 主动提出展示 Python 或 TypeScript 示例作为参考实现

5.  **如果用户需要 cURL/raw HTTP 示例**，从 `curl/` 读取。

### 特定语言功能支持

| 语言 | 工具运行器 | Agent SDK | 说明 |
| --- | --- | --- | --- |
| Python | 支持 (beta) | 支持 | 完全支持 — `@beta_tool` 装饰器 |
| TypeScript | 支持 (beta) | 支持 | 完全支持 — `betaZodTool` + Zod |
| Java | 支持 (beta) | 不支持 | 使用注解类的 Beta 版工具使用 |
| Go | 支持 (beta) | 不支持 | `toolrunner` 包中的 `BetaToolRunner` |
| Ruby | 支持 (beta) | 不支持 | Beta 版中的 `BaseTool` + `tool_runner` |
| cURL | 不适用 | 不适用 | 原始 HTTP，无 SDK 功能 |
| C# | 不支持 | 不支持 | 官方 SDK |
| PHP | 不支持 | 不支持 | 官方 SDK |

---

## 我应该使用哪个层面？

> **从简单开始。** 默认使用能满足你需求的最简单的层级。单个 API 调用和工作流可以处理大多数用例——只有当任务确实需要开放式的、由模型驱动的探索时，才使用 agent。

| 用例 | 层级 | 推荐层面 | 原因 |
| --- | --- | --- | --- |
| 分类、摘要、提取、问答 | 单个 LLM 调用 | **Claude API** | 一次请求，一次响应 |
| 批量处理或嵌入 | 单个 LLM 调用 | **Claude API** | 专用端点 |
| 带有代码控制逻辑的多步流水线 | 工作流 | **Claude API + 工具使用** | 你来编排循环 |
| 使用你自己的工具的自定义 agent | Agent | **Claude API + 工具使用** | 最大的灵活性 |
| 具有文件/网页/终端访问权限的 AI agent | Agent | **Agent SDK** | 内置工具、安全性和 MCP 支持 |
| Agentic 编码助手 | Agent | **Agent SDK** | 专为此用例设计 |
| 需要内置权限和护栏 | Agent | **Agent SDK** | 包含安全功能 |

> **注意：** Agent SDK 适用于当你希望开箱即用地获得内置的文件/网页/终端工具、权限和 MCP。如果你想用自己的工具构建一个 agent，Claude API 是正确的选择——使用工具运行器进行自动循环处理，或使用手动循环进行细粒度控制（批准门、自定义日志记录、条件执行）。

### 决策树

你的应用需要什么？

1. 单个 LLM 调用（分类、摘要、提取、问答）

└── Claude API — 一次请求，一次响应

1. Claude 是否需要读取/写入文件、浏览网页或运行 shell 命令

来作为其工作的一部分？（注意：不是你的应用读取文件并将其交给 Claude—— 是 Claude 本身需要发现和访问文件/网页/shell 吗？） └── 是 → Agent SDK — 内置工具，不要重复实现它们 示例：“扫描代码库以查找错误”、“摘要目录中的每个文件”、 “使用子 agent 查找错误”、“通过网络搜索研究一个主题”

1. 工作流（多步骤、代码编排、使用你自己的工具）

└── 使用工具的 Claude API — 你来控制循环

1. 开放式 agent（模型决定自己的轨迹，使用你自己的工具）

└── Claude API 的 agentic 循环（最大灵活性）

### 我应该构建一个 Agent 吗？

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

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

如果以上任何一项的答案是“否”，请停留在更简单的层级（单个调用或工作流）。

---

## 架构

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

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

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

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

**支持端点** — 批量（`POST /v1/messages/batches`）、文件（`POST /v1/files`）和令牌计数（Token Counting）为 Messages API 请求提供输入或支持。

---

## 当前模型 (缓存于: 2026-02-17)

| 模型 | 模型 ID | 上下文 | 输入 $/1M | 输出 $/1M |
| --- | --- | --- | --- | --- |
| Claude Opus 4.6 | `claude-opus-4-6` | 200K (1M beta) | $5.00 | $25.00 |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00 | $15.00 |
| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 |

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

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

一个说明：如果上述任何模型字符串对你来说看起来不熟悉，那很正常——这只意味着它们是在你的训练数据截止日期之后发布的。请放心，它们是真实模型；我们不会这样捉弄你。

---

## 思维与精力 (快速参考)

**Opus 4.6 — 自适应思维 (推荐):** 使用 `thinking: {type: "adaptive"}`。Claude 会动态决定何时以及进行多少思考。不需要 `budget_tokens`——`budget_tokens` 在 Opus 4.6 和 Sonnet 4.6 上已弃用，不得使用。自适应思维还自动启用交错思维（interleaved thinking）（不需要 beta header）。**当用户要求“扩展思维”、“思维预算”或 `budget_tokens` 时：始终使用带 `thinking: {type: "adaptive"}` 的 Opus 4.6。用于思考的固定令牌预算概念已被弃用——自适应思维取而代之。不要使用 `budget_tokens`，也不要切换到旧模型。**

**Effort 参数 (GA, 无 beta header):** 通过 `output_config: {effort: "low"|"medium"|"high"|"max"}`（在 `output_config` 内部，不是顶层）控制思维深度和总令牌消耗。默认为 `high`（相当于省略它）。`max` 仅适用于 Opus 4.6。适用于 Opus 4.5、Opus 4.6 和 Sonnet 4.6。在 Sonnet 4.5 / Haiku 4.5 上会出错。与自适应思维结合使用，以获得最佳的成本-质量权衡。对子 agent 或简单任务使用 `low`；对最深度的推理使用 `max`。

**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.6。

---

## 压缩 (快速参考)

**Beta, 仅限 Opus 4.6。** 对于可能超过 200K 上下文窗口的长时间对话，请启用服务器端压缩。当接近触发阈值（默认为 150K 令牌）时，API 会自动摘要较早的上下文。需要 beta header `compact-2026-01-12`。

**关键:** 在每一轮对话中，将 `response.content` (不仅仅是文本) 追加回你的消息列表。响应中的压缩块必须被保留——API 在下一次请求时使用它们来替换被压缩的历史记录。只提取文本字符串并追加它会悄无声息地丢失压缩状态。

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

---

## 阅读指南

在检测到语言后，根据用户的需求阅读相关文件：

### 快速任务参考

**单个文本分类/摘要/提取/问答:**
→ 只需阅读 `{lang}/claude-api/README.md`

**聊天 UI 或实时响应显示:**
→ 阅读 `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md`

**长时间运行的对话 (可能超过上下文窗口):**
→ 阅读 `{lang}/claude-api/README.md` — 参阅压缩部分

**函数调用 / 工具使用 / agents:**
→ 阅读 `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md`

**批量处理 (对延迟不敏感):**
→ 阅读 `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md`

**跨多个请求上传文件:**
→ 阅读 `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md`

**带有内置工具的 Agent (文件/网页/终端):**
→ 阅读 `{lang}/agent-sdk/README.md` + `{lang}/agent-sdk/patterns.md`

### Claude API (完整文件参考)

阅读**特定语言的 Claude API 文件夹** (`{language}/claude-api/`):

1.  **`{language}/claude-api/README.md`** — **首先阅读此文件。** 安装、快速入门、常见模式、错误处理。
2.  **`shared/tool-use-concepts.md`** — 当用户需要函数调用、代码执行、内存或结构化输出时阅读。涵盖概念基础。
3.  **`{language}/claude-api/tool-use.md`** — 阅读以获取特定语言的工具使用代码示例（工具运行器、手动循环、代码执行、内存、结构化输出）。
4.  **`{language}/claude-api/streaming.md`** — 当构建聊天 UI 或需要增量显示响应的界面时阅读。
5.  **`{language}/claude-api/batches.md`** — 当离线处理大量请求时（对延迟不敏感）阅读。以 50% 的成本异步运行。
6.  **`{language}/claude-api/files-api.md`** — 当在多个请求之间发送相同文件而无需重新上传时阅读。
7.  **`shared/error-codes.md`** — 在调试 HTTP 错误或实现错误处理时阅读。
8.  **`shared/live-sources.md`** — 用于获取最新官方文档的 WebFetch URL。

> **注意：** 对于 Java, Go, Ruby, C#, PHP, 和 cURL — 它们各自只有一个文件，涵盖了所有基础知识。阅读该文件，并根据需要阅读 `shared/tool-use-concepts.md` 和 `shared/error-codes.md`。

### Agent SDK

阅读**特定语言的 Agent SDK 文件夹** (`{language}/agent-sdk/`)。Agent SDK **仅适用于 Python 和 TypeScript**。

1.  **`{language}/agent-sdk/README.md`** — 安装、快速入门、内置工具、权限、MCP、钩子。
2.  **`{language}/agent-sdk/patterns.md`** — 自定义工具、钩子、子 agent、MCP 集成、会话恢复。
3.  **`shared/live-sources.md`** — 用于获取当前 Agent SDK 文档的 WebFetch URL。

---

## 何时使用 WebFetch

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

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

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

## 常见陷阱

- 在将文件或内容传递给 API 时，不要截断输入。如果内容太长无法放入上下文窗口，请通知用户并讨论选项（分块、摘要等），而不是悄悄地截断。
- **Opus 4.6 / Sonnet 4.6 思维:** 使用 `thinking: {type: "adaptive"}` — 不要使用 `budget_tokens` (在 Opus 4.6 和 Sonnet 4.6 上已弃用)。对于旧模型，`budget_tokens` 必须小于 `max_tokens` (最小为 1024)。如果搞错了，这会抛出错误。
- **Opus 4.6 移除了预填充:** 在 Opus 4.6 上，助手消息预填充 (last-assistant-turn prefills) 会返回 400 错误。请改用结构化输出 (`output_config.format`) 或系统提示指令来控制响应格式。
- **128K 输出令牌:** Opus 4.6 支持高达 128K 的 `max_tokens`，但 SDK 要求对大的 `max_tokens` 使用流式传输以避免 HTTP 超时。使用 `.stream()` 配合 `.get_final_message()` / `.finalMessage()`。
- **工具调用 JSON 解析 (Opus 4.6):** Opus 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、图表）并通过 Files API 返回它们——对于“报告”或“文档”类型的请求，可以考虑这种方式，而不是纯标准输出文本。