<!-- zh-only -->

# 用 Claude 构建 LLM 应用

帮助使用 **Claude API** 与 **Anthropic SDK** 构建 LLM 应用。按需求选对 **产品面（surface）**，检测项目语言，再读对应语言的文档节选。

## 默认约定

除非用户另有要求：

- **模型**：使用 **Claude Opus 4.6**，模型字符串 **`claude-opus-4-6`**。  
- **思考**：凡略复杂任务，默认 **`thinking: { type: "adaptive" }`**（自适应思考）。  
- **流式**：输入长、输出长或 `max_tokens` 高时，**默认流式**，避免请求超时；若不需要逐事件处理，可用 SDK 的 `.get_final_message()` / `.finalMessage()` 取完整回复。

---

## 语言检测

读代码示例前，先判断用户用的语言：

1. **看项目文件推断：**  
   - `*.py`、`requirements.txt`、`pyproject.toml` 等 → **Python**，读 `python/`  
   - `*.ts`、`*.tsx`、`package.json`、`tsconfig.json` → **TypeScript**，读 `typescript/`  
   - 仅 `*.js`、`*.jsx` 且无 `.ts` → 仍按 **TypeScript** SDK 读 `typescript/`  
   - `*.java`、`pom.xml`、`build.gradle` → **Java**，读 `java/`  
   - `*.kt`、`*.kts` → **Kotlin**，用 Java SDK，读 `java/`  
   - `*.scala`、`build.sbt` → **Scala**，读 `java/`  
   - `*.go`、`go.mod` → **Go**，读 `go/`  
   - `*.rb`、`Gemfile` → **Ruby**，读 `ruby/`  
   - `*.cs`、`*.csproj` → **C#**，读 `csharp/`  
   - `*.php`、`composer.json` → **PHP**，读 `php/`  

2. **多语言并存：** 看用户当前文件或问题指向哪一侧；仍模糊则问：「检测到 Python 与 TypeScript，Claude API 集成主要用哪边？」

3. **无法推断：** 用 AskUserQuestion 给选项：Python、TypeScript、Java、Go、Ruby、cURL/原始 HTTP、C#、PHP；若无该工具，默认展示 Python 并说明可换语言。

4. **不支持的语言**（Rust、Swift、C++、Elixir 等）：建议 `curl/` 的原始 HTTP，并说明可能有社区 SDK；也可提供 Python/TS 作参考。

5. **需要 cURL/原始 HTTP：** 读 `curl/`。

### 各语言功能支持（Tool Runner / Agent SDK）

| 语言 | Tool Runner | Agent SDK | 说明 |
|------|-------------|-----------|------|
| Python | 有（beta） | 有 | 完整，`@beta_tool` |
| TypeScript | 有（beta） | 有 | 完整，`betaZodTool` + Zod |
| Java | 有（beta） | 无 | 注解类 beta tool |
| Go | 有（beta） | 无 | `toolrunner` 包 |
| Ruby | 有（beta） | 无 | `BaseTool` + `tool_runner` |
| cURL | 不适用 | 不适用 | 原始 HTTP |
| C# | 无 | 无 | 官方 SDK |
| PHP | 有（beta） | 无 | `BetaRunnableTool` + `toolRunner()` |

---

## 该用哪种产品面？

> **从简：** 默认选 **能满足需求的最简单一层**。单次调用与工作流覆盖多数场景；只有真需要 **开放-ended、模型主导探索** 时再上升为 Agent。

| 场景 | 层级 | 推荐 | 原因 |
|------|------|------|------|
| 分类、摘要、抽取、问答 | 单次调用 | **Claude API** | 一问一答 |
| 批处理或向量 | 单次调用 | **Claude API** | 专用端点 |
| 多步流水线，逻辑由代码编排 | 工作流 | **Claude API + 工具** | 你控制循环 |
| 自定义工具的智能体 | Agent | **Claude API + 工具** | 最灵活 |
| 需要内置文件/网页/终端 | Agent | **Agent SDK** | 内置工具、安全、MCP |
| 编程助手类 Agent | Agent | **Agent SDK** | 面向该场景 |
| 要内置权限与护栏 | Agent | **Agent SDK** | 安全能力开箱即用 |

**说明：** Agent SDK 适合要 **内置文件/网页/终端、权限、MCP** 的场景。若 **工具全自建**，用 **Claude API** 即可——可用 tool runner 自动循环，或手写循环做审批、日志、条件分支。

### 决策树（简述）

1. 单次 LLM（分类/摘要/抽取/问答）→ **Claude API**  
2. 是否 **Claude 本人** 要读写文件、浏览网页、执行 shell（不是你读好再喂给模型）？是 → **Agent SDK**  
3. 多步工作流 + 自有工具 → **Claude API + 工具**  
4. 开放轨迹 + 自有工具 → **Claude API 的 agentic 循环**

### 是否该做「Agent」？

先过四问：**复杂度**（是否多步且难事先写死）、**价值**（是否值得更高成本与延迟）、**可行性**（模型是否擅长）、**错误成本**（能否用测试/审查/回滚兜住）。任一为「否」则留在更简单层级。

---

## 架构要点

统一走 **`POST /v1/messages`**；工具与输出约束都是该端点能力，不是另一套 API。

- **用户自定义工具**：用装饰器、Zod 或原始 JSON 定义；SDK tool runner 负责请求、执行函数、循环直到结束；也可手写循环精细控制。  
- **服务端工具**：Anthropic 托管；代码执行在服务端；Computer use 可托管或自托管。  
- **结构化输出**：约束回复格式（`output_config.format`）与工具参数（`strict: true`）；推荐 `client.messages.parse()`。**已弃用** 顶层 `output_format`，改用 `output_config: { format: {...} }`。  
- **配套端点**：Batches、Files、Token 计数、Models（`GET /v1/models` 等）服务于上述流程。

---

## 当前模型（缓存日期见上游 SKILL）

| 模型 | 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`。** 不要擅自为省钱改 Sonnet/Haiku。  

**只用表中精确 ID，不要自造日期后缀**（如误用 `claude-sonnet-4-5-20250514`）。用户要旧版时读 `shared/models.md` 取官方 ID。

**实时能力查询：** 用户问上下文、是否支持 vision/thinking/effort 等时，用 Models API（`client.models.retrieve` / `list`），见 `shared/models.md`。

---

## 思考与 Effort（速查）

**Opus 4.6 — 自适应思考（推荐）：** `thinking: { type: "adaptive" }`；**不要** 在 Opus 4.6 上使用 `budget_tokens`（已弃用）。用户说要「扩展思考」「思考预算」时，仍用 Opus 4.6 + adaptive。

**Effort（GA，无需 beta 头）：** `output_config: { effort: "low"|"medium"|"high"|"max" }`（在 `output_config` 内，非顶层）；默认 `high`；`max` 仅 Opus 4.6；与 Sonnet 4.5 / Haiku 4.5 组合会报错。可与 adaptive 联用。

**Sonnet 4.6：** 支持 adaptive；同样弃用 `budget_tokens`。

**仅当用户明确要求旧模型时：** 如 Sonnet 4.5 等可用 `thinking: { type: "enabled", budget_tokens: N }`，且 `budget_tokens` < `max_tokens`（至少 1024）。**不要** 仅因用户提到 `budget_tokens` 就换旧模型——优先 Opus 4.6 + adaptive。

---

## 压缩（Compaction）速查

**Beta，Opus 4.6 / Sonnet 4.6。** 长对话可能超 200K 时可开服务端压缩；接近阈值（默认约 150K）时自动摘要更早上下文。需 beta 头 `compact-2026-01-12`。

**关键：** 每轮要把 **`response.content` 整体** 拼回 messages，不能只抽文本丢掉压缩块，否则 **丢失压缩状态**。

示例见 `{lang}/claude-api/README.md` 的 Compaction 节；更多见 `shared/live-sources.md`。

---

## 提示缓存（Prompt Caching）速查

**前缀匹配：** 前缀任意字节变化会使其后缓存全部失效。渲染顺序：`tools` → `system` → `messages`。稳定内容（固定 system、确定性工具列表）放前，易变内容（时间戳、每次不同的 ID）放在最后一个 `cache_control` 断点之后。

**顶层自动缓存：** `messages.create()` 上 `cache_control: { type: "ephemeral" }` 最简单；每请求最多 4 个断点；可缓存前缀约 ≥1024 tokens，更短则 **静默不缓存**。

用 **`usage.cache_read_input_tokens`** 验证；反复为 0 说明有 **静默失效因素**（如 system 里 `datetime.now()`、JSON 键无序、工具集每轮变化等）。

详见 `shared/prompt-caching.md` 与各语言 README 对应章节。

---

## 阅读指南

按语言进入 `{lang}/` 下文件夹，按需打开：

**快捷：**  
- 单次文本任务 → `{lang}/claude-api/README.md`  
- 聊天 UI / 流式展示 → 加 `{lang}/claude-api/streaming.md`  
- 超长对话 → README 中 Compaction  
- 缓存优化 → `shared/prompt-caching.md` + README 缓存节  
- 工具/智能体 → README + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md`  
- 批处理 → `batches.md`  
- 跨请求复用文件 → `files-api.md`  
- 内置工具 Agent → `{lang}/agent-sdk/README.md` + `patterns.md`  

**Agent SDK** 仅 **Python / TypeScript** 有完整文档树。

## 何时用 WebFetch 拉最新文档

用户要「最新」、本地缓存疑似过时、或问到本文未覆盖的功能时；URL 列表在 `shared/live-sources.md`。

## 常见陷阱

- 向 API 传文件或长内容时 **不要静默截断**；超长则告知用户并讨论分块、摘要等。  
- Opus 4.6 / Sonnet 4.6：**用 adaptive，不用 `budget_tokens`**。  
- Opus 4.6 **禁止** 助手消息 prefill（会 400）；改用结构化输出或 system 约束格式。  
- **`max_tokens` 不要太小**，否则思考/输出中途被截断需重试；非流式默认可给约 16000；流式可更高（如约 64000）。分类等极短输出再降低。  
- 128K 输出需 **流式** + `get_final_message` 等，避免 HTTP 超时。  
- Opus 4.6 工具调用 `input` 的 JSON 转义可能与旧版不同；**始终** `JSON.parse` / `json.loads`，不要对原始字符串做脆弱匹配。  
- 结构化输出用 **`output_config.format`**，不要用已弃用的 `output_format`。  
- **不要重复造 SDK 轮子**：用 `stream.finalMessage()`、SDK 异常类型、SDK 导出类型（`MessageParam`、`Tool` 等），不要自造一套弱类型接口。  
- 需要报告/文档/图表时，代码执行沙箱预装 docx/pptx/matplotlib/pillow/pypdf 等，可考虑 **Files API** 返回文件，而非只打 stdout。