用 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。