用途
本技能面向使用 Claude Messages API 构建应用的开发者，重点解决结构化输出、错误预防与高级模式使用问题。资料标注最后更新于 2025-11-22，技能版本 2.0.0。
主要能力
结构化输出（v0.69.0，2025-11-14）
保证响应严格遵循 JSON schema，提供两种模式：
- JSON Outputs（output_format）：用于数据提取与格式化。示例中通过
betas: ['structured-outputs-2025-11-13']与output_format指定json_schema，并设置strict: true。 - 严格工具使用（strict: true）：用于校验函数参数，在 tools 的 input_schema 中设置
strict: true保证 schema 合规。
要求：Beta 头 structured-outputs-2025-11-13（通过 betas 数组传入）；仅支持 Claude Sonnet 4.5、Claude Opus 4.1；需要 SDK v0.69.0+。
限制：不支持递归 schema；不支持数值约束（minimum、maximum）；正则支持有限（不支持反向引用/前瞻）；与 citations 和消息预填充不兼容；语法编译在首次请求时增加延迟（缓存 24 小时）。
适用场景：从非结构化文本提取数据、API 响应格式化、需要校验工具输入的智能体工作流、消除 JSON 解析错误。
模型变更（2025 年 10 月，破坏性变更）
已退役（返回错误）：Claude 3.5 Sonnet（所有版本）；Claude 3.7 Sonnet 已弃用（2025-10-28）。
当前可用模型（2025 年 11 月）：
- Claude Sonnet 4.5，ID
claude-sonnet-4-5-20250929，200k 上下文，均衡性能，$3/$15（输入/输出，每 MTok） - Claude Opus 4，ID
claude-opus-4-20250514，200k 上下文，最高能力，$15/$75 - Claude Haiku 4.5，ID
claude-3-5-haiku-20241022，200k 上下文，接近前沿且快速，$1/$5
上下文管理（2025-10-28）
Clear Thinking Blocks：通过 betas: ['clear_thinking_20251015'] 自动清理 thinking 块。
Agent Skills API（2025-10-16）
面向 Office 文件（PowerPoint、Excel、Word、PDF）的预构建技能，通过 betas: ['skills-2025-10-02'] 使用，需要启用代码执行工具。
流式响应（SSE）
关键错误模式：错误发生在初始 200 响应之后。需为 stream 添加 error 与 abort 事件监听器，实现回退或重试逻辑。
提示缓存（约 90% 成本节省）
关键规则：cache_control 必须放在最后一个块上。可通过 message.usage.cache_read_input_tokens 与 cache_creation_input_tokens 监控缓存使用。最低要求：Claude Sonnet 4.5 为 1,024 tokens，Claude Haiku 4.5 为 2,048 tokens；TTL 5 分钟（每次使用刷新）；缓存仅与完全相同的内容共享。
工具使用（函数调用）
支持严格工具使用；工具结果中 tool_use_id 必须与 tool_use 块 id 匹配；工具执行失败时返回 is_error: true 与错误内容供 Claude 处理。
视觉（图像理解）
格式：JPEG、PNG、WebP、GIF（非动画）；单图最大 5MB；Base64 约增加 33% 体积；图像计入 token 限制；重复图像分析可考虑缓存。
扩展思考模式
模型兼容性：Claude 3.7 Sonnet 已弃用（2025-10-28）；Claude 3.5 Sonnet 已退役（不支持）；Claude Sonnet 4.5 与 Claude Opus 4 支持扩展思考。注意：thinking 块不可缓存；需要更高的 max_tokens；使用前检查模型。
速率限制
建议实现指数退避并尊重 retry-after 头。速率限制响应头包括：anthropic-ratelimit-requests-limit、anthropic-ratelimit-requests-remaining、anthropic-ratelimit-requests-reset。
错误处理
常见错误码：400 invalid_request_error（参数错误）、401 authentication_error（API key 无效）、403 permission_error（无功能访问权限）、404 not_found_error（端点无效）、429 rate_limit_error（请求过多）、500 api_error（内部错误）、529 overloaded_error（系统过载）。注意：流式错误发生在初始 200 响应之后；始终为流实现错误事件监听器；429 时尊重 retry-after 头；关键操作准备回退策略。
使用方式
资料提供 TypeScript 示例，使用 @anthropic-ai/sdk，通过 new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) 初始化，调用 anthropic.messages.create 或 anthropic.messages.stream。结构化输出、严格工具使用、上下文管理、Agent Skills 等均通过 betas 数组传入对应 Beta 头。
适用场景
数据提取、API 响应格式化、需要校验工具输入的智能体工作流、消除 JSON 解析错误、图像理解、长上下文成本优化、流式应用错误处理。
限制
结构化输出不支持递归 schema、数值约束与完整正则；与 citations 和消息预填充不兼容；首次请求有语法编译延迟。扩展思考仅限 Sonnet 4.5 与 Opus 4，且 thinking 块不可缓存。提示缓存有最低 token 要求与 5 分钟 TTL。API key 不应暴露在客户端代码中，应仅在服务端使用环境变量。
已知问题预防
资料列出 12 个可预防问题：429 速率限制无退避、流式 SSE 解析错误、提示缓存未激活（cache_control 位置错误）、工具使用响应格式错误、视觉图像格式问题、计费 token 计数不匹配、系统提示顺序问题（应放在 messages 之前）、上下文窗口超限（200k）、在错误模型上使用扩展思考、客户端代码暴露 API key、速率限制层级混淆、Message Batches Beta 头缺失（需 anthropic-beta: message-batches-2024-09-24）。
官方文档
Claude API：https://platform.claude.com/docs/en/api Messages API：https://platform.claude.com/docs/en/api/messages Structured Outputs：https://platform.claude.com/docs/en/build-with-claude/structured-outputs Prompt Caching：https://platform.claude.com/docs/en/build-with-claude/prompt-caching Tool Use：https://platform.claude.com/docs/en/build-with-claude/tool-use Vision：https://platform.claude.com/docs/en/build-with-claude/vision Rate Limits：https://platform.claude.com/docs/en/api/rate-limits Errors：https://platform.claude.com/docs/en/api/errors TypeScript SDK：https://github.com/anthropics/anthropic-sdk-typescript Context7 Library ID：/anthropics/anthropic-sdk-typescript
包版本
最新：@anthropic-ai/sdk@0.70.1（2025-11-20）。依赖示例：@anthropic-ai/sdk: ^0.70.1；开发依赖：@types/node: ^20.0.0、typescript: ^5.3.0、zod: ^3.23.0。
Token 效率
无技能时约 8,000 tokens；使用技能时约 4,200 tokens；节省约 48%（约 3,800 tokens）；预防 12 个已记录问题。