用途
该技能面向需要将 Claude API 与 TypeScript SDK 集成到应用中的开发者，提供生产可用的集成模式。适用场景包括：在 Node.js/TypeScript 应用中集成 Claude API、实现实时流式对话、构建使用 Claude 工具调用（函数调用）的应用、以重试逻辑优雅处理 API 错误、优化令牌用量与控制成本、将 Claude 功能部署到生产环境、构建带上下文管理的多轮对话，以及为高吞吐处理实现消息批处理。
主要能力
技能以代码模式的形式组织，涵盖以下方面：
- Messages API 基础：模型选择（Opus、Sonnet、Haiku）、messages 数组（user/assistant 角色）、max_tokens、系统提示、流式输出。
- SDK 架构：类型安全的 API 客户端、流式辅助工具、工具执行框架、错误处理工具、消息批处理、事件驱动架构。
- 流式模式：基础流式、事件处理器流式、带中止控制的流式。
- 工具调用模式：使用 Zod 定义工具、工具运行器自动执行、流式工具执行。
- 错误处理模式：综合错误处理、指数退避重试。
- 令牌优化模式：令牌计数、上下文窗口管理。
- 消息批处理模式：批量处理请求并轮询结果。
- 生产模式：请求超时配置、自定义请求头与元数据。
使用方式
安装 SDK：
npm install @anthropic-ai/sdk
# 或
yarn add @anthropic-ai/sdk
初始化客户端：
import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
});
技能中给出的代表性模式包括：
基础消息创建：
const message = await anthropic.messages.create({
model: 'claude-sonnet-4-5-20250929',
max_tokens: 1024,
messages: [
{ role: 'user', content: 'Hello, Claude!' }
],
});
多轮对话：在 messages 数组中依次传入 user 与 assistant 的历史消息。
系统提示：通过 system 字段设定助手角色与行为。
基础流式：设置 stream: true，遍历事件并处理 content_block_delta 中的 text_delta。
事件处理器流式：使用 anthropic.messages.stream() 并注册 text、message、error 事件，最后调用 finalMessage()。
流中止控制：调用 stream.abort()，并捕获 Anthropic.APIUserAbortError。
Zod 工具定义：使用 @anthropic-ai/sdk/helpers/zod 的 betaZodTool，定义 name、inputSchema、description 与 run 函数。
工具运行器：使用 anthropic.beta.messages.toolRunner 传入 tools 数组自动执行工具。
流式工具执行：在 toolRunner 中设置 stream: true，遍历消息流。
综合错误处理：捕获 Anthropic.APIError，根据 status 分别处理 429（限流）、401（密钥无效）、400（错误请求）。
指数退避重试：对 429 错误按 baseDelay * 2^attempt 延迟重试，超过最大重试次数后抛出错误。
令牌计数：使用 gpt-tokenizer 的 encode 估算令牌数，并据此截断或摘要。
上下文窗口管理：维护消息列表与令牌总量，超过上限时裁剪较早消息。
批量处理：使用 anthropic.messages.batches.create 提交带 custom_id 的请求，再通过 batches.retrieve 轮询结果。
超时配置：在客户端初始化时设置 timeout 与 maxRetries。
自定义请求头：在请求第二个参数中传入 headers，例如 anthropic-beta。
适用场景
- 聊天机器人与对话式界面
- 多步骤工作流与上下文相关交互
- 专用助手与角色扮演场景
- 实时用户界面、长文本生成、交互式体验
- 用户可取消的操作、超时处理、资源管理
- 类型安全的工具定义与输入校验
- AI 智能体与函数调用
- 生产应用中的健壮错误恢复
- 高吞吐应用与限流处理
- 成本优化、令牌预算管理、大输入处理
- 长对话的上下文管理与成本控制
- 批量处理与离线工作流
最佳实践（来自资料）
- API 密钥管理：不要硬编码密钥，使用环境变量（如 .env 中的 ANTHROPIC_API_KEY）。
- 模型选择：Opus 能力最强、适合复杂推理；Sonnet 性能与速度均衡；Haiku 最快、适合简单任务；使用最新模型版本。
- 流式考虑：面向用户的应用、长文本（超过 500 令牌）、实时交互应使用流式；后端批处理、需要预先确定输出、简单 API 集成可不用流式。
- 错误处理：始终捕获 API 错误，对瞬时故障实现重试，记录错误日志，提供用户友好的错误信息。
- 令牌管理：调用前估算令牌，设置合适的 max_tokens，监控令牌用量，对长对话实现上下文裁剪。
限制与排查
资料给出的常见问题与解决方向：
- 限流错误（429）：实现指数退避、对批量操作使用消息批处理、升级到更高限流层级。
- 超时错误：对长响应使用流式、增大超时配置、减少 max_tokens。
- 密钥无效（401）：确认环境变量已设置、检查密钥格式（以 sk-ant- 开头）、确认密钥未被轮换。
- 上下文长度超限：实现对话裁剪、摘要较早消息、使用合适的上下文窗口限制。
版本与兼容性
- 技能版本：1.0.0
- 最后更新：2025 年 10 月
- 兼容性：@anthropic-ai/sdk 0.30.0+
关于收费、价格、具体平台支持范围等信息，资料中暂未提供。