使用Claude构建基于LLM的应用

本技能可帮助您使用Claude构建基于LLM的应用。根据需求选择合适的交互方式，检测项目语言，然后阅读对应语言的相关文档。

默认设置

除非用户另有要求：

关于Claude模型版本，请使用Claude Opus 4.6，可通过精确的模型字符串

claude-opus-4-6

访问。对于任何稍微复杂的任务，请默认使用自适应思考（

thinking: {type: "adaptive"}

）。最后，对于任何可能涉及长输入、长输出或高

max_tokens

的请求，请默认使用流式传输——这可以避免请求超时。如果不需要处理单个流事件，请使用SDK的

.get_final_message()

.finalMessage()

助手来获取完整响应

语言检测

查看代码示例前，请先确定用户使用的开发语言：

查看项目文件推断语言：
- ```
*.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/
```
  目录下的内容
检测到多种语言时（例如同时存在Python和TypeScript文件）：
- 检查用户当前文件或问题涉及哪种语言
- 如果仍不明确，询问：“我检测到同时存在Python和TypeScript文件。您在集成Claude API时使用哪种语言？”
无法推断语言时（空项目、无源码文件或不支持的语言）：
- 使用AskUserQuestion提供选项：Python、TypeScript、Java、Go、Ruby、cURL/原生HTTP、C#、PHP
- 如果无法使用AskUserQuestion，默认展示Python示例并说明：“当前展示Python示例。如果您需要其他语言的示例，请告知。”
检测到不支持的语言时（Rust、Swift、C++、Elixir等）：
- 建议使用
```
curl/
```
  目录下的cURL/原生HTTP示例，并说明可能存在社区SDK
- 可提供Python或TypeScript示例作为参考实现
如果用户需要cURL/原生HTTP示例，读取
```
curl/
```
目录下的内容。

各语言功能支持情况

语言	工具运行器	Agent SDK	说明
Python	是（测试版）	是	完整支持 — `@beta_tool` 装饰器
TypeScript	是（测试版）	是	完整支持 — `betaZodTool` + Zod
Java	是（测试版）	否	使用注解类的测试版工具支持
Go	是（测试版）	否	`toolrunner` 包中的 `BetaToolRunner`
Ruby	是（测试版）	否	测试版中的 `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 — 一次请求，一次响应

2. Claude在工作中是否需要读取/写入文件、浏览网页或运行Shell命令？
   （注意：不是指您的应用读取文件后交给Claude——而是Claude自身是否需要发现并访问文件/网页/Shell？）
   └── 是 → Agent SDK — 内置工具，无需重新实现
       示例："扫描代码库查找漏洞"、"汇总目录中的所有文件"、
             "使用子Agent查找漏洞"、"通过网页搜索研究主题"

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

4. 开放式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计数功能为Messages API请求提供支持。

当前模型（缓存时间：2026-02-17）

模型	模型ID	上下文窗口	输入成本$/1M	输出成本$/1M
Claude Opus 4.6	`claude-opus-4-6`	200K（1M测试版）	$5.00	$25.00
Claude Sonnet 4.6	`claude-sonnet-4-6`	200K（1M测试版）	$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字符串——这些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上已被弃用，严禁使用。自适应思考还会自动启用交错思考（无需测试版头信息）。当用户要求“扩展思考”、“思考预算”或
budget_tokens
时：始终使用Opus 4.6并设置
thinking: {type: "adaptive"}
。固定思考Token预算的概念已被弃用——自适应思考已取代它。请勿使用
budget_tokens
，也不要切换到旧模型。

算力参数（正式发布，无需测试版头信息）： 通过

output_config: {effort: "low"|"medium"|"high"|"max"}

控制思考深度和整体Token消耗（位于

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和自适应思考。

压缩功能快速参考

测试版，仅适用于Opus 4.6。 对于可能超过200K上下文窗口的长对话，启用服务器端压缩。当接近触发阈值（默认：150K Token）时，API会自动总结早期上下文。需要测试版头信息

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

— 查看压缩部分

函数调用/工具使用/Agent： → 阅读

{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/

）：

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

注意： 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。

{language}/agent-sdk/README.md
— 安装、快速开始、内置工具、权限、MCP、钩子。
{language}/agent-sdk/patterns.md
— 自定义工具、钩子、子Agent、MCP集成、会话恢复。
shared/live-sources.md
— 当前Agent SDK文档的WebFetch链接。

何时使用WebFetch

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

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

实时文档链接位于

shared/live-sources.md

中。

常见陷阱

向API传递文件或内容时不要截断输入。如果内容太长无法放入上下文窗口，请通知用户并讨论解决方案（分块、摘要等），不要静默截断。
Opus 4.6 / Sonnet 4.6思考设置： 使用
```
thinking: {type: "adaptive"}
```
— 请勿使用
```
budget_tokens
```
（在这两个模型上已弃用）。对于旧模型，
```
budget_tokens
```
必须小于
```
max_tokens
```
（最小值1024）。如果设置错误会抛出错误。
Opus 4.6已移除预填充： 在Opus 4.6上，助手消息预填充（最后一轮助手消息预填充）会返回400错误。请使用结构化输出（
```
output_config.format
```
）或系统提示指令来控制响应格式。
128K输出Token： Opus 4.6支持最高128K的
```
max_tokens
```
，但SDK需要使用流式传输来避免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()
```
而非将
```
.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、图表）并通过Files API返回——对于“报告”或“文档”类请求，请考虑使用此方式，而非纯标准输出文本。",

claude-api

NPX安装

标签

SKILL.md 内容（中文）