使用 Claude 构建 LLM 驱动的应用程序
本技能帮助您使用 Claude 构建 LLM 驱动的应用程序。根据您的需求选择合适的入口，检测项目语言，然后阅读相关的语言特定文档。
开始之前
扫描目标文件（如果无目标文件，则扫描提示词和项目）中是否存在非 Anthropic 提供商标记——import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5、文件名如 agent-openai.py 或 *-generic.py，或任何明确指示保持代码与提供商无关的说明。如果发现任何此类标记，请停止并告知用户，此技能生成的是 Claude/Anthropic SDK 代码；询问他们是否希望将文件切换为使用 Claude，或需要非 Claude 的实现。请勿使用 Anthropic SDK 调用编辑非 Anthropic 文件。（例外情况：prompt-audit 子命令为非交互式，在此处不会停止——它会在其报告的假定条件中记录非 Anthropic 提供商标记，并且从不建议将非 Anthropic 文件切换到 Anthropic SDK。）
输出要求
当用户要求您添加、修改或实现 Claude 功能时，您的代码必须通过以下方式之一调用 Claude：
- 对应项目语言的官方 Anthropic SDK（
anthropic、@anthropic-ai/sdk、com.anthropic.*等）。只要项目存在支持的 SDK，这就是默认选项。 - 原始 HTTP（
curl、requests、fetch、httpx等）——仅当用户明确要求使用 cURL/REST/原始 HTTP、项目是 shell/cURL 项目，或该语言没有官方 SDK 时才使用。
切勿混用两者——不要仅仅因为感觉更轻量就在 Python 或 TypeScript 项目中使用 requests/fetch。切勿回退到 OpenAI 兼容的 shim 层。
切勿猜测 SDK 用法。 函数名、类名、命名空间、方法签名和导入路径必须来自明确的文档——要么是本技能中的 {lang}/ 文件，要么是 shared/live-sources.md 中列出的官方 SDK 仓库或文档链接。如果需要使用的绑定在技能文件中没有明确记录，请在编写代码之前 WebFetch 来自 shared/live-sources.md 的相关 SDK 仓库。请勿从 cURL 形状或其他语言的 SDK 推断 Ruby/Java/Go/PHP/C# API。
如果 WebFetch 或仓库访问失败（网络受限、超时、克隆被阻止）：不要一直重试——根据 {lang}/ 文件中的模式和命名空间/包表编写代码，运行编译器或解释器，然后根据错误输出进行迭代。对于静态类型 SDK（C#、Java、Go），针对本地错误进行编译-修复循环能比被阻止的网络研究更快地获得可工作的代码。
默认值
除非用户另有要求：
对于 Claude 模型版本，请使用 Claude Opus 5.5，您可以通过确切的模型字符串 claude-opus-5-5 访问它。对于任何稍显复杂的内容，请默认使用自适应思维（thinking: {type: "adaptive"}）。最后，对于任何可能涉及长输入、长输出或高 max_tokens 的请求，请默认使用流式传输——这可以避免请求超时。如果您不需要处理单个流事件，请使用 SDK 的 .get_final_message() / .finalMessage() 辅助方法获取完整响应。当流式请求定义了用户定义的（客户端）工具时，在每个此类工具上设置 eager_input_streaming: true，以便大型工具输入（文件内容、代码、文档）在生成时立即流式传输，而不是在服务器缓冲完毕后一次性到达；客户端负责验证：SDK 的宽容解析器可能返回静默截断的输入而不会引发异常，因此应在运行每个解析后的工具输入之前根据其 schema 进行验证（类型化的运行器辅助方法如 betaZodTool / 类型化的 @beta_tool 会执行此操作；betaTool() JSON-Schema 工具和手动循环必须自行验证），将失败视为无效的 JSON（当您持有 block 时，返回 INVALID_JSON 错误 tool_result，否则重新发出），在运行工具前检查 max_tokens / refusal 停止原因，并且仅捕获 SDK 的 JSON 错误，而非其类型化的 API 错误——模式见 shared/tool-use-concepts.md -> 急切输入流式传输。对于非流式请求、服务器工具以及当请求通过代理或拒绝该字段的旧版 Bedrock 模型部署时，请保持此设置关闭。
警告：API 漂移——您的训练先验知识可能已过时
几种常见的 Claude API 格式在 2025-2026 年发生了变化。如果您回忆起某个模式，请在编写代码前对照本技能中的 {lang}/ 文件进行验证——下表列出了最常见的漂移点：
| 方面 | 过时的先验知识 | 当前 API |
|---|---|---|
| 扩展思维 | thinking: {type: "enabled", budget_tokens: N} | 在 Claude 4.6+ 模型上：thinking: {type: "adaptive"}。budget_tokens 在 Opus 4.6 / Sonnet 4.6 上已被弃用，在 Fable 5/5.1 / Sonnet 5.5 / Sonnet 5 / Opus 5.5 / 5 / 4.8 / 4.7 上返回 400 错误被拒绝。4.6 之前的模型仍然使用 budget_tokens。 |
| Web 搜索 / Web 获取工具类型 | web_search_20250305、web_fetch_20250910 | web_search_20260209、web_fetch_20260209（动态过滤）在 Opus 5.5/5/4.8/4.7/4.6、Sonnet 5.5、Sonnet 5 和 Sonnet 4.6 上。旧模型保留基本变体；在 Vertex AI 上，仅提供基本的 web_search_20250305（Web 获取在 Vertex 上不可用）——请参阅下面的服务器工具快速参考 (QR)。 |
| PHP 参数名 | 蛇形 (snake_case) 线缆格式作为命名参数 (max_tokens) | 顶级命名参数为驼峰 (camelCase) 格式 (maxTokens)。嵌套数组键因功能而异（例如 'taskBudget'、'skillID'、'mcp_server_name'）——请从文档中的示例复制确切的键；请勿批量转换。 |
| 托管智能体凭据 | 通过自定义工具将密钥保存在主机端（Vaults 发布前的唯一选项） | Vault environment_variable 凭据——由 Anthropic 存储，在出口时替换，在沙箱中永不可见（shared/managed-agents-tools.md -> Vaults）。主机端自定义工具仍然是自托管沙箱的备选方案。 |
| 文件 API / 技能 | client.beta.files.* / client.beta.skills.* 附带 beta 头 files-api-2025-04-14 / skills-2025-10-02 | 已结束测试：client.files.* / client.skills.*，无需 beta 头。当前 SDK 中的 client.beta.files / client.beta.skills 与之前版本相比有破坏性的格式更改，与稳定的命名空间相匹配——请按照 shared/live-sources.md -> 文件 API / 技能指南进行迁移。 |
本技能中的 {lang}/ 文件对回忆的模式具有权威性。
子命令
如果此提示底部的用户请求是裸子命令字符串（无叙述性文字），则搜索本文档中的所有子命令表——包括下面附加的部分中的表——并直接遵循匹配的“操作”列。这允许用户通过 /claude-api <子命令> 调用特定流程。如果文档中没有表匹配，则将该请求视为普通叙述性文字。
| 子命令 | 操作 |
|---|---|
migrate | 将现有 Claude API 代码迁移到更新的模型。立即阅读 shared/model-migration.md 并按顺序遵循：步骤 0（确认范围——在编辑前询问哪些文件/目录），步骤 1（对每个文件进行分类），然后按目标执行破坏性更改部分。不要总结指南——执行它。如果用户未指定目标模型，请在同一个轮次中询问要迁移到哪个模型。在应用了按目标更改后，对照 shared/prompt-audit.md 审核范围内的提示文本、工具描述和请求代码——为源模型编写的提示是每次迁移的一部分，并且不会自行宣布。 |
prompt-audit | 审核现有的提示、工具描述、技能和智能体配置文件（CLAUDE.md、规则文件、命令、子智能体）中是否存在过时的模式（“积垢”）：为旧模型编写的文本，以及仓库已不再需要或相互矛盾的指令。立即阅读 shared/prompt-audit.md 并按顺序遵循：步骤 0（根据请求和仓库确定范围和目标模型——在报告中说明假设条件，不要停下来询问），清单、溯源，然后是模式扫描。完整生成两个交付物——审核报告（查找结果包含 文件:行号、模式、为何过时、置信度）和建议的 diff——无需等待确认；仅当请求明确要求时才应用编辑。不要总结指南——执行它。 |
upgrade | 在主要版本之间升级项目的 Anthropic SDK 依赖——目前是 Python SDK anthropic 0.x -> 1.x。后面的单词可能指定语言和/或范围（upgrade python、upgrade python sdk src/）。立即阅读 python/claude-api/sdk-upgrade.md 并按顺序遵循：步骤 0（确认范围，然后确定当前和目标版本——在编写版本锁之前，必须存在已发布的 1.x），步骤 1 清单，每个编号部分，然后是验证和报告。不要总结指南——执行它。如果检测到或指定的语言在本技能中没有 sdk-upgrade.md，则说明尚未为该 SDK 打包主要版本升级指南，并将用户指向该 SDK 的 CHANGELOG（仓库见 shared/live-sources.md）；请勿从 Python 指南即兴创作一个。这不是模型迁移——要将代码移动到更新的 Claude 模型，请使用 migrate。 |
cost-optimize | 在不牺牲输出质量的情况下，降低现有 Claude API 代码的运行成本。立即阅读 shared/cost-optimization.md 并按顺序遵循：步骤 0（确定范围、质量标准基线和基线），Token 配置文件——通过使用情况和成本管理 API（当用户拥有管理 API 密钥时）测量，来自应用程序自身的 response.usage 日志（如果存在，询问用户），否则从代码估计——然后是按节省排序的杠杆候选列表（以美元、账单百分比或相对桶为单位，具体取决于您拥有的数据源）、免费胜利（缓存、输入 Token 卫生、循环卫生、输出 Token 卫生、批处理），然后是权衡（预算、工作量、模型选择、多模型）；任何获得位置的杠杆都会生成自己的 diff——默认提议，在用户要求并批准后应用于覆盖其所涉及流量的评估并进行测量——“不推荐更改”是一个有效的结果。两条固定规则：每次运行模型都会花费真金白银，因此首先获得用户的批准；当缺少杠杆的上下文时，与用户进行交互式处理——此工作流不期望一次性完成审核。不要总结指南——执行它；向用户展示配置文件和排序计划是执行的一部分。 |
build-eval | 帮助用户为其基于 Claude 的应用程序构建评估集。立即阅读 shared/evals/build-eval.md 并运行其采访：步骤 0（评估对象），步骤 1（提示来源——现有评估 / 记录 / 合成），步骤 2（评分方法），步骤 3（可运行脚本 + 测量成本）。在生成评估之前，获得用户对输入、评分方法和成本的明确确认。 |
preserved-thinking-migration | 使现有集成与保留思维兼容——这是一种检查，确保思维块仅在其产生的对话中保持有效。立即阅读 shared/preserved-thinking-migration.md 并按顺序遵循：步骤 0（范围、流量类别、平台和模型、强制执行状态、质量标准、基线），步骤 0.5（使用三请求自测证明检查正在运行），步骤 1（捕获请求体，使用 shared/preserved-thinking-migration/prefix_diff.py 比对连续对，扫描代码查找原因，命名每个编辑并判断其是否有意），步骤 2（在 thinking-binding-controls-2026-08-01 头下使用 prefix_mismatch_behavior: "drop_block" 重放测试切片，计算每个对话中新增的丢弃块，存在诊断头时读取），步骤 3（每次编辑一个原因，按推理丢失的顺序排列——默认提议，在用户要求时应用——然后重新测量，保留或回滚；当存在评估时的三臂协议），模型切换部分（在 shared/preserved-thinking-migration/causes.md 中，包含原因表和保留列表）当路由在模型之间切换时，步骤 4（中断概况和更改）。两条固定规则：每次重放都会花费真金白银，因此首先获得用户对测量预算的批准；并且“不推荐更改”——切片重放了思维并且没有任何内容被丢弃——是一个有效的结果。仅在较新的测试版下具有追加形式的原因（保留尾部和后台压缩：compact-2026-09-04；同名工具更改：inline-tools-2026-09-15），如果该测试版不可用，则进行测量和决定，而不是重写。至于原因（三步检查、追加编辑表），它链接着 shared/model-migration.md -> 破坏性更改 3；不要总结指南——执行它。 |
hillclimb | 根据现有评估迭代改进用户的应用程序。立即阅读 shared/evals/eval-hillclimb.md 并按顺序遵循：步骤 0（确认存在可运行的评估——如果没有，则转向 build-eval），步骤 1（更改内容 / 禁止改动内容），步骤 2（预算 + 来自测量单次运行成本的停止条件），获得计划批准，然后进行读取->提议->应用->运行->记录循环，带磁盘状态和训练/验证/测试拆分。 |
语言检测
在阅读代码示例之前，确定用户正在使用哪种语言（例外情况：对于 prompt-audit 子命令，跳过此部分的询问步骤——审核是非交互式的，其清单与语言无关；当无法推断语言时，继续前进而不询问，并在报告中说明假设条件）：
- 查看项目文件以推断语言：
*.py、requirements.txt、pyproject.toml、setup.py、Pipfile-> Python——从python/读取*.ts、*.tsx、`packag