claude-api — Anthropic API 开发

Claude Code 内置技能 · 构建、调试与优化 Claude API / Anthropic SDK 应用

一、技能概述

claude-api 是 Claude Code 内置的开发技能，专为使用 Anthropic API 和官方 SDK（Python / TypeScript）构建 AI 应用的开发者设计。当代码中引入 anthropic 或 @anthropic-ai/sdk 时自动激活，提供从 Prompt Caching 到模型迁移的全程支持。

核心定位：帮助开发者利用 Claude 全部高级功能（缓存、思考、工具调用、批处理、文件处理、引用、记忆）构建生产级应用，并在模型版本迭代时平滑迁移。

二、适用目的

本技能主要服务于以下开发场景：

构建 Claude API 应用：使用 Anthropic Python SDK 或 TypeScript SDK 快速搭建对话、分析、内容生成等服务
集成高级功能：在应用中正确配置 Prompt Caching、Extended Thinking、Tool Use 等 Claude 独有特性
模型版本迁移：当 Claude 模型从 4.5 升级到 4.6 再到 4.7 时，自动或半自动迁移调用代码
性能调优：通过缓存命中率分析、上下文压缩、请求合并等手段降低延迟和成本
调试与排错：识别 API 调用中的常见错误，提供针对性修复建议

三、Prompt Caching 支持

Prompt Caching 是 Anthropic API 降低延迟与成本的关键特性。claude-api 技能会在生成 App 代码时默认包含缓存支持。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20260506",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一位资深中医专家...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "请分析这个方剂"}]
)

最佳实践：将系统提示词和长上下文前缀标记为可缓存（cache_control: {"type": "ephemeral"}），可显著提升缓存命中率。首次调用会写入缓存（写入延迟），后续相同前缀的请求将大幅降低响应时间。

四、模型迁移指南

Claude 模型迭代频繁，claude-api 技能提供了从旧版本到新版本的迁移路径：

4.5 → 4.6：主要变更包括 Thinking 预算参数调整、Tool Use 响应格式优化。需将 thinking 配置中的 budget_tokens 下限从 1024 提高至 2048
4.6 → 4.7：引入了 Compaction（智能上下文压缩）和增强的 Batch API。需在初始化 Messages 时添加 compaction: "auto" 参数
Retired Model 替换：已退役模型（如 claude-2、claude-instant）自动替换为当前等效模型（claude-sonnet-4）

# 迁移示例：4.6 → 4.7
response = client.messages.create(
    model="claude-sonnet-4-20260506",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 4096},
    compaction="auto",         # 4.7 新增
    messages=messages
)

关键提示：模型迁移不仅是字符串替换——需要关注参数变更、响应格式差异和行为变化。claude-api 技能会自动检测旧模型标识并给出迁移建议。

五、触发条件

该技能在以下场景会被自动触发：

导包检测：文件中出现 import anthropic（Python）或 @anthropic-ai/sdk（TypeScript）
API 相关请求：用户直接询问 Claude API、Anthropic SDK 或 Managed Agents 相关问题
功能调优操作：用户添加、修改或调优以下功能：Caching、Thinking、Compaction、Tool Use、Batch、Files、Citations、Memory
模型变更：在代码中切换 Claude 模型版本（Opus / Sonnet / Haiku），或者涉及已退役模型

注意：如果项目中 import 的是 openai 或其他第三方 SDK，或者文件包含 -openai / -generic 等后缀，技能将跳过激活。

六、核心功能详解

claude-api 覆盖 Anthropic API 的全部高级特性，以下是各项功能的简要说明与代码示意：

1. Prompt Caching（缓存） — 将系统提示词或长上下文前缀标记为缓存，降低重复请求的延迟与成本。适用于固定指令、知识库前缀等场景。

system = [{"type": "text", "text": long_context,
           "cache_control": {"type": "ephemeral"}}]

2. Extended Thinking（思考） — 让模型在回答前进行深度推理，适用于数学、逻辑、代码审查等复杂任务。

response = client.messages.create(
    model="claude-sonnet-4-20260506",
    thinking={"type": "enabled", "budget_tokens": 8192},
    ...
)

3. Compaction（上下文压缩） — Claude 4.7 引入的新特性，自动压缩对话历史以保持上下文窗口高效利用。

response = client.messages.create(
    ..., compaction="auto"
)

4. Tool Use（工具调用） — 允许模型调用外部工具（函数、API、数据库查询等），实现 Agent 能力。

tools = [
    {"name": "get_weather", "description": "获取天气",
     "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}}
]

5. Batch API（批处理） — 通过 Message Batches API 批量发送请求，适用于异步、大规模处理场景。

batch = client.messages.batches.create(requests=batch_requests)

6. Files（文件处理） — 支持上传文档（PDF、文本等）供模型阅读分析，适用于文档审核、报告生成等场景。

response = client.messages.create(
    messages=[{"role": "user", "content": [
        {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": text}}
    ]}]
)

7. Citations（引用） — 模型回答时自动标注信息来源，增强回答的可信度与可追溯性。

response = client.messages.create(
    ..., citations={"enabled": true}
)

8. Memory（记忆） — 跨对话维护用户偏好与上下文，实现持续性交互体验。

# 通过 system prompt 显式注入记忆
system_prompt = "用户信息: " + user_profile + "\n历史偏好: " + preferences

七、应用场景

claude-api 技能在以下实际场景中发挥核心作用：

智能客服系统：利用 Tool Use + Citations + Memory 构建能查询订单、引用知识库、记住用户偏好的客服机器人
文档分析平台：通过 Files + Caching + Thinking 处理大量 PDF 文档，进行合同审查、报告摘要、合规检查
代码生成与审查：借助 Extended Thinking + Tool Use 实现复杂代码生成、重构建议和自动化测试
内容创作流水线：使用 Batch API 批量生成文章、翻译内容或 SEO 元数据，配合 Caching 降低成本
研究辅助工具：结合 Citations + Compaction 分析多篇论文，生成带引用的综述报告
教育辅导应用：利用 Memory 记录学习者进度与薄弱环节，定制个性化学习路径

八、最佳实践

1. 缓存策略：将不变的长文本（系统指令、知识库前缀）标记为缓存，动态内容放在其后。监控 cache_hit_rate 指标，目标 > 60%。

2. Thinking 预算：复杂推理任务分配 4096–8192 tokens；简单任务 1024–2048。过高的预算会增加延迟而没有实质收益。

3. 错误重试：对 429（限流）和 500+（服务器错误）实现指数退避重试。使用 anthropic.RetryingAnthropic() 简化重试逻辑。

4. 模型选择：Sonnet 适合日常任务（速度与质量平衡），Opus 适合高难度推理，Haiku 适合简单分类与提取。

5. 版本锁定：在生产环境中始终指定精确的模型版本（如 claude-sonnet-4-20260506），避免自动升级导致行为变化。

6. 监控与日志：记录每次 API 调用的 model、input_tokens、output_tokens、cache_hit 和 latency，用于成本分析与性能优化。

九、核心总结

claude-api 技能要点：
• 专为 Anthropic API / SDK 开发设计，自动检测 anthropic 导包
• 默认集成 Prompt Caching，降低延迟与成本
• 支持 Claude 模型全生命周期管理（4.5 → 4.6 → 4.7 迁移）
• 覆盖 8 大高级功能：Caching、Thinking、Compaction、Tool Use、Batch、Files、Citations、Memory
• 适用于客服、文档分析、代码生成、内容创作、研究辅助、教育辅导等场景
• 强调缓存策略、Thinking 预算、错误重试、模型选择、版本锁定、监控日志六大最佳实践