用 Claude/Anthropic API 构建 LLM…

当提示中出现 Claude/Anthropic（含 anthropic、@anthropic-ai、claude-*、us.anthropic.*、[1m]）或任务是 LLM 形态（agent/MCP/工具定义/多 agent/RAG/LLM 裁判/生成-摘要-抽取-分类-改写-对话/调试拒答、截断、流式、工具调用、token）时，按此流程产出基于官方 Anthropic SDK 的可用代码。

适用场景

解决思路

1. 先扫描目标文件（无目标文件则扫提示与项目）找非 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 标记记入报告假设）。
2. 代码必须通过官方 Anthropic SDK 调用 Claude（Python `anthropic`、TypeScript `@anthropic-ai/sdk`、Java `com.anthropic.*` 等），这是有受支持 SDK 时的默认；只有用户明确要求 cURL/REST/raw HTTP、项目本身是 shell/cURL 项目、或该语言没有官方 SDK 时才用原始 HTTP，绝不在 Python/TypeScript 项目里图省事改用 `requests`/`fetch`，也绝不退回 OpenAI 兼容 shim。
3. 绝不猜 SDK 用法：函数名、类名、命名空间、方法签名、导入路径必须来自明确文档——技能内的 `{lang}/` 文件，或 `shared/live-sources.md` 里的官方 SDK 仓库/文档链接；需要的绑定没被明确记录就先 WebFetch 对应 SDK 仓库，不要从 cURL 形状或别的语言 SDK 反推 Ruby/Java/Go/PHP/C# API。
4. 若 WebFetch 或仓库访问失败（网络受限、超时、clone 被阻），不要反复重试：按 `{lang}/` 文件里的模式和命名空间/包表格把代码写出来，用编译器或解释器跑，依据错误输出迭代；静态类型 SDK（C#/Java/Go）用「编译-修复」循环比卡在网络研究更快得到可运行代码。
5. 始终默认 `claude-opus-5`，除非用户明确点名别的模型；不要为省钱擅自降级（那是用户的决定），只在用户明确要 Claude Fable 5.1、'fable' 或最强模型时才用 `claude-fable-5-1`。
6. 只用模型表中精确的 model ID 字符串，绝不追加日期后缀（是 `claude-sonnet-4-6`，不是 `claude-sonnet-4-6-20251114` 之类）；用户要表里没有的旧模型（如 'opus 4.5'、'sonnet 3.7'）时读 `shared/models.md` 取准确 ID，不要自己拼。
7. 默认对任何稍有复杂的任务启用自适应思考 `thinking: {type: "adaptive"}`。
8. 默认对可能长输入、长输出或高 `max_tokens` 的请求使用流式，避免请求超时；不需要处理单个流事件时用 SDK 的 `.get_final_message()` / `.finalMessage()` 拿完整响应。
9. 写代码前把记忆中的写法对照 'API Drift' 表核验：thinking 从 `budget_tokens` 变为 `{type: "adaptive"}`；web search/web fetch 类型用 `web_search_20260209`/`web_fetch_20260209`；PHP 顶层命名参数改 camelCase（`maxTokens`）而嵌套键按文档逐个照抄；Managed Agents 凭证改用 vault `environment_variable`；Files/Skills 已出 beta，用 `client.files.*`/`client.skills.*` 且不带 beta 头——以 `{lang}/` 文件为准。
10. 识别到裸子命令字符串（无散文）时，遍历文档中所有 Subcommands 表并按 Action 列执行：`migrate` 读 `shared/model-migration.md` 并按其顺序执行（Step 0 先问清要改哪些文件/目录，Step 1 分类每个文件，再按目标模型的破坏性变更执行，最后按 `shared/prompt-audit.md` 审计范围内提示文本、工具描述与请求代码）；`prompt-audit` 读 `shared/prompt-audit.md`，非交互地建立范围与目标模型、做清单与来源追溯、跑模式扫描，完整产出审计报告（`file:line`、模式、为何对目标模型过时、置信度）与建议 diff，只在请求明确要求时才落盘；`upgrade` 读 `{lang}/claude-api/sdk-upgrade.md`（当前只有 Python 的 `anthropic` 0.x→1.x）；`cost-optimize` 读 `shared/cost-optimization.md`。不要只总结指南，要真正执行。
11. `upgrade` 场景：若检测到或用户点名的语言在该技能里没有 `sdk-upgrade.md`，就说明该 SDK 尚未内置大版本升级指南，并指向其 CHANGELOG（仓库见 `shared/live-sources.md`），不要照搬 Python 指南自行发挥；这不是模型迁移，迁移模型请走 `migrate`。
12. `cost-optimize` 场景：先确定范围、质量基线与基线成本，token 画像优先用 Usage and Cost Admin API（用户有 Admin API key 时），其次用应用自身 `response.usage` 日志（先问用户），否则从代码估算；然后给按省钱排序的杠杆短名单（按可得数据源用美元、账单百分比或相对档位报价），先列免费收益（缓存、输入 token 卫生、循环卫生、输出 token 卫生、batch）再列权衡（预算、effort、模型选择、多模型）；每个采纳的杠杆单独成一个 diff（默认只提议；用户要求并同意后才应用并针对覆盖该流量的评测测量），「不建议改动」也是合法结论；每次跑模型都花真钱，动手前先拿用户批准；上下文缺失就与用户交互式补齐，不要指望一次跑完。
13. 按项目文件推断实现语言再读对应 `{lang}/` 目录：`*.py`/`requirements.txt`/`pyproject.toml`/`setup.py`/`Pipfile` → Python；`*.ts`/`*.tsx`/`package.json`/`tsconfig.json` → TypeScript；`*.js`/`*.jsx`（无 `.ts`）→ TypeScript（共用同一 SDK）；`*.java`/`pom.xml`/`build.gradle`、`*.kt`/`*.kts`/`build.gradle.kts`、`*.scala`/`build.sbt` → Java；`*.go`/`go.mod` → Go；`*.rb`/`Gemfile` → Ruby；`*.cs`/`*.csproj` → C#；`*.php`/`composer.json` → PHP。
14. 同时检测到多种语言时，按用户当前文件或问题判断该用哪种；仍不明确就问「我同时检测到 Python 和 TypeScript 文件，Claude API 集成用哪种语言？」；完全无法推断（空项目、无源码、不支持的语言）时用 AskUserQuestion 给出 Python/TypeScript/Java/Go/Ruby/cURL-raw HTTP/C#/PHP 选项，不可用时默认给 Python 示例并注明可换语言。
15. 遇到不支持的语言（Rust、Swift、C++、Elixir 等）时，建议改用 `curl/` 的原始 HTTP 示例、说明可能存在社区 SDK，并可提供 Python 或 TypeScript 示例作参考实现；用户要 cURL/raw HTTP 时读 `curl/`。
16. 选择最简可用层级：分类/摘要/抽取/问答、批处理或嵌入用单次 Claude API 调用；代码控制逻辑的多步流水线与自定义工具 agent 用 Claude API + tool use；需要 Anthropic 托管循环与每会话沙箱、持久化/版本化 agent 配置、带文件挂载的长时多轮会话、定时运行的才用 Managed Agents。
17. 构建 agent 前先核对四项判据：复杂度（是否多步且难以事先完全指定）、价值（结果是否值更高成本与延迟）、可行性（Claude 在该任务类型上是否够强）、错误成本（错误能否被测试/评审/回滚拦住）；任一为「否」就停在更简层级（单次调用或工作流）。
18. 区分 Tool Runner 与 Claude Agent SDK：Tool Runner 属于常规 Anthropic SDK（`client.beta.messages.tool_runner`），只驱动你自己定义的工具，没有内置工具、文件系统或沙箱，你和你的基础设施负责托管；Claude Agent SDK（`claude-agent-sdk` / `@anthropic-ai/claude-agent-sdk`）是 Claude Code 打包成的独立库，带内置 Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch 与 MCP、子代理。本技能只覆盖 Claude API 与 Managed Agents，用户真想要 Agent SDK 就指向 `code.claude.com/docs/en/agent-sdk`，不要拿 Tool Runner 顶替，也不要反向替换。
19. `ANTHROPIC_API_KEY` 未设置并不代表没有凭证：不要直接向用户要 key，先跑 `ant auth status` 看当前凭证来源与 profile。
20. `ant auth status` 报告有活跃 profile 时：SDK 代码或 `ant` CLI 直接运行（零参构造器与所有 `ant` 子命令自动读取 profile，无需环境变量）；raw curl/HTTP 则用 `ant auth print-credentials --access-token` 取短期 token，以 `Authorization: Bearer <token>` 头加 `anthropic-beta: oauth-2025-04-20` 头发送（OAuth 用 Bearer，不是 `x-api-key`），务必带 `--access-token`，无参形式输出的是 JSON 而非裸 token。
21. 只有 `ant auth status` 显示无可用凭证来源（或没装 `ant`）时才向用户要 key：优先建议 `ant auth login`（profile 存在 `~/.config/anthropic/` 供 SDK 自动读取），其次建议导出 `ANTHROPIC_API_KEY`；更多细节（命名 profile、scope、API key 遮蔽 profile 的坑、refresh token 过期）看 `shared/anthropic-cli.md`。
22. 按模型设置思考参数：Fable 5/Claude Fable 5.1/Mythos 用 `{type: "adaptive"}` 或直接省略（`disabled` 会 400，强制 `tool_choice` 的 `any`/`tool` 也 400）；Opus 5 省略即默认自适应，`disabled` 仅在 effort ≤ high 时被接受；Opus 4.8/4.7 和 Sonnet 5 必须显式设 `{type: "adaptive"}`/接受 `disabled`；老的 Sonnet 4.5/Haiku 4.5 才用 `{type: "enabled", budget_tokens: N}`（必须小于 `max_tokens` 且 ≥1024）。
23. 用 `output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"}` 调深度（放在 `output_config` 内，不是顶层；默认 `high` 等同省略）：编码与长时 agent 任务用 `xhigh`，智能敏感工作最低用 `high`，正确性比成本重要时用 `max`，子代理或简单任务用 `low`，大量/延迟敏感的路由常可降到 `low` 并把 `medium` 当保质的降档；在真实请求样本上测量后再改默认，并按路由而非全局调优。
24. 用户提「extended thinking」「thinking budget」或 `budget_tokens` 时，用 Fable 5/5.1、Opus 5/4.8/4.7/4.6 配 `thinking: {type: "adaptive"}`，新代码不要用 `budget_tokens`，也不要因为用户提到它就切回旧模型；只有 Opus 4.6/Sonnet 4.6 上的既有代码可用 `budget_tokens` 作过渡逃生舱。
25. 要把推理流式展示给用户时，显式设 `thinking: {type: "adaptive", display: "summarized"}`，因为 Fable 5/Claude Fable 5.1/Mythos 5/5.1/Opus 5/4.8/4.7/Sonnet 5 默认是 `display: "omitted"`（`thinking` 块文本为空，看起来像长时间静默）；同一模型续聊时把 thinking 块原样回传，其他模型会静默忽略。
26. 长会话可能超过 1M 上下文时启用服务端 compaction（beta 头 `compact-2026-01-12`，默认约 150K token 触发）；关键做法是每轮把整个 `response.content`（不只是文本）追加回 `messages`，否则 API 无法在下一次请求里用压缩块替换历史，压缩状态会被静默丢失。
27. 配置 prompt caching 时按前缀匹配的原则：渲染顺序是 `tools` → `system` → `messages`，把稳定内容（冻结的系统提示、确定性的工具列表）放最前，把易变内容（时间戳、每请求 ID、变化的问题）放在最后一个 `cache_control` 断点之后；不需要精细放置时在 `messages.create()` 上直接加顶层 `cache_control: {type: "ephemeral"}`，单请求最多 4 个断点。
28. 用 `usage.cache_read_input_tokens` 验证缓存是否生效：重复请求它一直是 0 就说明存在隐形失效源（系统提示里的 `datetime.now()`、未排序的 JSON、随请求变化的工具集）；最小可缓存前缀随模型不同（512-4096 token），前缀更短会静默不缓存。
29. 长会话中要中途加操作指令，就在 `messages[]` 里追加 `{"role": "system", "content": "..."}` 而不是改顶层 `system`，以保住已缓存的历史前缀（可用模型：Opus 5、Opus 4.8、Fable 5/5.1、Mythos 5/5.1，不含 Sonnet 5，无需 beta 头）；该消息必须跟在 user 消息（或以服务端工具调用结尾的 assistant 消息）之后，且要么是 `messages` 最后一条、要么后面接 assistant，不能当 `messages[0]`。
30. 需要更高输出速度且用 Opus 5/Opus 4.8 时启用 fast mode：走 beta 端点 `client.beta.messages....`，传 beta 旗标 `fast-mode-2026-02-01`，并在顶层请求参数设 `speed: "fast"`（不是 header，也不放 `extra_body`）；用 `response.usage.speed` 确认实际速度，遇 429 就按 `retry-after` 重试或去掉 `speed` 回退标准模式（注意切换速度会使 prompt cache 失效）。
31. 用 task budget 给 agent 循环一个模型自知的 token 上限：在 `output_config` 里设 `task_budget`（`type` 固定 `"tokens"`、`total` 最小 20000、`remaining` 默认等于 `total`），用 `client.beta.messages.stream(...)` 配较大 `max_tokens` 以免 HTTP 超时，并带 beta 旗标 `task-budgets-2026-03-13`。
32. 累计 `response.usage.output_tokens`（加上你追加的工具结果块 token）来展示预算消耗；正常循环里不要自己传 `remaining`（服务端自己倒数），只有在两次请求之间做了压缩或重写历史、服务端无法推导先前消耗时才传 `remaining`。
33. 定位到第三方平台时用该平台的专用客户端类，而不是给第一方 `Anthropic()` 客户端塞 `base_url`：Amazon Bedrock 用 Mantle 客户端（`AnthropicBedrockMantle`、`AnthropicBedrockMantle`/`bedrock-sdk` 的 `AnthropicBedrockMantle`、Go `bedrock.NewMantleClient`、Java `BedrockMantleBackend`、C# `AnthropicBedrockMantleClient`、PHP `Anthropic\Bedrock\MantleClient`、Ruby `Anthropic::BedrockMantleClient`），模型 ID 带 `anthropic.` 前缀（如 `anthropic.claude-opus-5`）且 region 必填；不要用旧 `bedrock-runtime` InvokeModel 路径（`AnthropicBedrock`/`BedrockClient`/`BedrockBackend`）。
34. Microsoft Foundry 用 `AnthropicFoundry`（Python）/ `AnthropicFoundry`（`@anthropic-ai/foundry-sdk`）/ Java `FoundryBackend.fromEnv()` / C# `AnthropicFoundryClient` / PHP `Foundry\Client::withCredentials(...)`；Go 与 Ruby SDK 当前不支持 Foundry，Ruby 退回 `Anthropic::Client.new(base_url: "<foundry endpoint>")`（不内置 Entra ID 认证）。
35. Google Cloud Vertex AI 用 `AnthropicVertex`（Python 需装 `anthropic[vertex]`，需 `project_id` 与 `region` 两个必填构造参数，`region` 可为 `global`），模型 ID 不带前缀（如 `claude-opus-5`），日期快照版用 `@` 分隔（`claude-opus-4-5@20251101`），认证走 GCP ADC（`gcloud auth application-default login`），不用 Anthropic API key；构造后同样用 `messages.create` / `.stream`。
36. 需要清掉旧工具结果或思考块时用 context editing：在 `client.beta.messages.*` 上传 `context_management.edits` 并带 beta `context-management-2025-06-27`，策略类型为 `clear_tool_uses_20250919`（可加 `clear_tool_inputs: true` 连工具参数一起清）或 `clear_thinking_20251015`；它是清空不是压缩，别把 `compact_20260112` / `compact-2026-01-12` 混用进来。
37. 搭建 Managed Agent 时走强制流程 Agent（一次）→ Session（每次运行）：用 `POST /v1/agents` 创建持久化版本化 agent 并保存返回的 ID，每次运行用 `sessions.create` 引用它，`model`/`system`/`tools` 只放在 agent 上、绝不放 session；推荐用版本控制 YAML 配合 `ant` CLI 管控制面（创建/更新 agent），代码只管数据面 `sessions.create`，不要在请求路径里调 `agents.create()`。
38. 写 Managed Agents 客户端代码时按 `shared/managed-agents-client-patterns.md` 实现：无损流重连、`processed_at` 的排队/已处理门控、interrupt、`tool_confirmation` 往返、正确的 idle/terminated 跳出条件、idle 后状态竞态、stream-first 顺序、文件挂载的坑。
39. Managed Agents 的凭证首选 vault 的 `environment_variable` 凭证（由 Anthropic 存储、在出口替换、沙箱内不可见）；只有 vault 凭证不适用时（如自托管沙箱）才退回在宿主侧用自定义工具保管密钥。
40. 处理工具审批与权限时读 `shared/managed-agents-tools.md` § Permission Policies，用 `always_allow` / `always_ask` / `auto`，并处理 `auto` 的三种结果（执行、因高风险被拒、不确定时暂停），以及工具使用事件上的 `evaluated_permission` / `evaluation`。
41. 要让 agent 定时运行（cron、'每晚'、'周报'）就读 `shared/managed-agents-scheduled-deployments.md` 用 deployments（含每次触发的 run 记录与暂停/恢复/归档等生命周期控制）；工作要扇出（多来源调研、逐文件/逐记录处理）或单个循环会把上下文塞满时读 `shared/managed-agents-multiagent.md`，先用只含 `{"type": "self"}` 的 roster 让 agent 委派给自己，再把读量大的子任务移给按 ID 引用的更便宜 worker（如 Claude Haiku 4.5）。
42. 使用服务端工具时在 `tools` 里声明、结果作为同一响应中的 content block 返回：优先用模型支持的最新类型变体，`web_search_20260209` / `web_fetch_20260209` 需 Opus 5/4.8/4.7/4.6、Sonnet 5/4.6，老模型用 `web_search_20250305` / `web_fetch_20250910`（Vertex 只有基础 `web_search_20250305`，无 web fetch）；带动态过滤的变体已在底层跑代码执行，不要再单独声明 `code_execution`（两个执行环境会让模型困惑）。
43. 服务端工具类型按需照抄：代码执行用 `code_execution_20260521`（Go 上它位于 `client.Beta.Messages.New` 且需 beta `code-execution-2025-08-25`，其他语言用普通 `client.messages.create`；`code_execution_20260120` 到处都用非 beta 的 `client.Messages.New`）；工具搜索用 `tool_search_tool_regex_20251119` 或 `tool_search_tool_bm25_20251119` 并把其他工具标 `defer_loading: true`。
44. 传入 PDF 时用 `{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": <b64>}}` 放在文本块之前，base64 串不能有换行，限制为请求 32MB、600 页（200K 上下文模型 100 页）；Java 用 `ContentBlockParam.ofDocument(... Base64PdfSource.builder().data(...))`。
45. 跨多次请求复用同一文件时走 Files API：`client.files.upload(...)` 拿响应 `id` 作为 `file_id`，PDF/文本引用为 `{"type": "document", "source": {"type": "file", "file_id": "..."}}`，图片用 `{"type": "image", ...}`，content block 类型必须与文件 MIME 类型匹配；从 `files-api-2025-04-14` 迁移时 WebFetch `shared/live-sources.md` 的 Files API 行。
46. 要引用来源就在每个 `document` content block 上设 `citations: {enabled: true}`（要么全开要么全关，与 `output_config.format` 不兼容否则 400）；响应会拆成多个 `text` 块，被引用的块带 `citations` 数组，每条含 `cited_text`、`document_index`、`document_title` 及按类型的定位（纯文本 `char_location`，PDF `page_location`（1 起）、自定义内容 `content_block_location`）。
47. 严格工具用工具定义上的顶层 `strict: true`（与 `name`/`description`/`input_schema` 同级，不是放在 `tool_choice`），schema 必须含 `additionalProperties: false` 与 `required`；Go 用 `Strict: anthropic.Bool(true)` 加 `InputSchema.ExtraFields` 传 `additionalProperties`，Java 用 `.strict(true)` 加 `.putAdditionalProperty("additionalProperties", JsonValue.from(false))`。
48. 并行工具调用默认开启：一条 assistant 消息可能含多个 `tool_use` 块，并发执行它们，然后把**全部** `tool_result` 放进**同一条** user 消息（拆成多条会静默训练 Claude 不再并行调用）；工具失败也要返回 `tool_result` 并带 `is_error: true`，不要丢弃。
49. 用 Tool Runner 自动驱动工具循环（SDK beta 助手，走 `client.beta.messages.*`）：Python `@beta_tool` 装饰器 + `client.beta.messages.tool_runner(...)` 后 `runner.until_done()`；TypeScript `betaZodTool({...})`（来自 `@anthropic-ai/sdk/helpers/beta/zod`）+ `client.beta.messages.toolRunner(...)` 后 `await runner`；Go `toolrunner.NewBetaToolFromJSONSchema(...)` + `client.Beta.Messages.NewToolRunner(...)` 后 `.RunToCompletion(ctx)`；Java 需 `.addBeta("structured-outputs-2025-11-13")`；Ruby `Anthropic::BaseTool` 子类 + `tool_runner`；PHP `BetaRunnableTool` + `->toolRunner(...)`；C# 用原始 JSON schema 工具 + `client.Beta.Messages.ToolRunner(...)`。
50. 让 Claude 从代码执行里调用你的自定义工具（程序化工具调用）时，加 `{"type": "code_execution_20260120", "name": "code_execution"}` 并在自定义工具上设 `"allowed_callers": ["code_execution_20260120"]`（Opus 4.5+/Sonnet 4.5+）；回复待处理的程序化调用时，user 消息只能含 `tool_result` 块、不能有文本；它与 `strict: true`、`disable_parallel_tool_use`、强制 `tool_choice`、MCP 工具不兼容。
51. 做批处理用 Message Batches：`client.messages.batches.create(requests=[{custom_id, params}, ...])` → 轮询 `client.messages.batches.retrieve(id).processing_status` 直到 `"ended"` → 流式读 `client.messages.batches.results(id)`；每个结果含 `.custom_id` 与 `.result.type`（`succeeded`/`errored`/`canceled`/`expired`），成功时读 `.result.message.content`；Python 用 `Request(custom_id=..., params=MessageCreateParamsNonStreaming(...))` 包装，结果顺序任意，一律按 `custom_id` 索引而非位置。
52. 需要模型能力或上下文窗口数据时查 Models API（无 beta）：`client.models.list()`（自动分页）与 `client.models.retrieve("claude-opus-5")`；模型对象有 `id`、`display_name`、`created_at`，以及 2026 年 3 月起的 `max_input_tokens`（上下文窗口）、`max_tokens`（输出上限）和 `capabilities`——没有 `context_window` 字段。
53. 读取 `response.stop_details` 前先判断 `stop_reason == "refusal"`：它只在该情况下有值（`type: "refusal"`、开放集合的 `category` 如 `cyber`/`bio`/`reasoning_extraction`/`frontier_llm` 或 `null`、`explanation`），其他 `stop_reason`（`end_turn`、`max_tokens`、`tool_use`、`pause_turn` 等）下恒为 `null`。
54. 错误处理写成最具体优先的异常链而不是一个宽泛 catch：例如 `NotFoundError` → `RateLimitError` → `APIStatusError` → `APIConnectionError`（Go 等价写法是 `errors.As` 成 `*anthropic.Error` 后 `switch apierr.StatusCode { case 404: ...; case 429: ...; default: ... }`），以区分可重试（429、≥500、网络）与不可重试（400/404）；各语言类名与命名空间见 `shared/error-codes.md`。
55. 配置客户端时注意单位差异：`timeout` 默认 10 分钟，但 Python/Ruby 是秒、TypeScript 是**毫秒**、Go 用 `option.WithRequestTimeout(time.Duration)`、Java 用 `Duration`、C# 用 `TimeSpan`；`max_retries`/`maxRetries` 默认 2（重试 408/409/429/5xx 与连接错误）；超时也会被重试，实际墙钟可达 `timeout × (max_retries+1)`；用 `base_url`（或 `ANTHROPIC_BASE_URL` 环境变量），按请求覆写用 Python `client.with_options(timeout=5.0).messages.create(...)`、TypeScript `client.messages.create({...}, {timeout: 5_000})`、Ruby `request_options: {timeout: 5}`。
56. 设置 `max_tokens` 时不要压低：非流式默认约 16000（让响应落在 SDK HTTP 超时内），流式默认约 64000（超时不是问题，给模型空间）；只有分类（约 256）、成本上限、刻意短输出或缓存预热（`max_tokens: 0`）才更低，撞上限会中途截断并需要重试。
57. 不要重实现 SDK 已提供的能力：用 `stream.finalMessage()` 而不是把 `.on()` 事件包进 `new Promise()`；用类型化异常类（`Anthropic.RateLimitError` 等）而不是字符串匹配错误消息；用 SDK 导出的类型（`Anthropic.MessageParam`、`Anthropic.Tool`、`Anthropic.Message`、`Anthropic.ToolUseBlock`/`ToolResultBlockParam` 等）而不是自定义 `interface ChatMessage { role: string; content: unknown }`。
58. 不要为查 SDK 类型名先做研究：文档里没展示的类型名，就直接按语言文档的命名空间/包表格把源文件写出来，让编译器报错指向正确名字；用 `strings` / `jar tf` / `javap` 对着已安装 SDK 快速定位是允许的（秒级返回），但不要升级成 WebFetch、clone SDK 仓库或专门写反射程序。一个类型名写错的文件可修，一次什么都没写出来的探索会话不可修。
59. 处理工具与特殊能力时按这些硬规则：bash 与文本编辑器是 Anthropic 定义的无 schema 工具，声明为 `{"type": "bash_20250124", "name": "bash"}` / `{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}`（自己起名叫 `bash` 的自定义工具是另一个东西）；advisor 工具的 `model` 必须至少与请求顶层 `model` 同等能力（如执行 `claude-sonnet-5` → 顾问 `claude-opus-4-8`/`claude-opus-4-7`），不合法配对返回 400；memory 工具类型是 `memory_20250818`（Python/TypeScript 提供 `BetaAbstractMemoryTool`/`betaMemoryTool` 实现后端）。
60. 要 Claude 生成 `.pptx`/`.xlsx` 等文件时用 Agent Skills：调 `client.beta.messages.create` 并带 `container={"skills": [...]}`、`code_execution_20260521` 工具和 `code-execution-2025-08-25` beta（Skills 已出 beta，不需要 `skills-2025-10-02` 头）；不要用 `client.beta.agents`/`sessions`/`environments`，那是 Managed Agents 而非 Agent Skills。
61. 接 MCP 连接器要两半都写：只给 `mcp_servers=[{type:"url", url, name}]` 会因校验错误被拒，必须同时加 `tools=[{type:"mcp_toolset", mcp_server_name:<同名>}]` 并带 beta `mcp-client-2025-11-20`。
62. `inference_geo` 是直接的顶层请求参数（`client.messages.create(..., inference_geo="us")` / `.inferenceGeo("us")`），不要放进 `extra_body`/`putAdditionalBodyProperty`；注意在 Managed Agents 上它嵌在 agent 的 `model` 对象里、从不放顶层；支持 Opus 4.6/Sonnet 4.6 及以后，用 `response.usage.inference_geo` 确认实际推理位置。
63. 细粒度工具流式不是 beta 功能：在工具定义上设 `eager_input_streaming: true`，然后调常规 `client.messages.stream(...)`，没有 beta 头也没有 `client.beta.*` 路径；缓存诊断才是 beta，用 `client.beta.messages.*` 配 beta `cache-diagnosis-2026-04-07`，首轮传 `diagnostics: {previous_message_id: null}`、后续传上一响应的 id，结果在 `response.diagnostics`。
64. 写调用代码时还能用的具体修正：结构化输出统一用 `output_config: {format: {...}}` 而不是已弃用的 `output_format`；工具调用的 `input` 一律用 `json.loads()` / `JSON.parse()` 解析，绝不对序列化字符串做原始匹配（Fable 5/5.1、Opus 5、4.6/4.7/4.8、Sonnet 4.6 的转义方式可能不同）；Fable 5/5.1、Opus 5、Sonnet 5、4.6/4.7/4.8 上 assistant prefill 一律 400（改用结构化输出或系统提示控制格式）；Fable 5.1/Mythos 5.1 上强制 `tool_choice`（`any`/`tool`）返回 400（改用 `{type: "auto"}` 加点名工具的指令、工具 `strict: true` 或结构化输出，`{type: "none"}` 不受影响，`disable_parallel_tool_use` 仍可与 `auto` 同用）。
65. 处理服务端工具错误时记住它们不抛异常：web search/web fetch 出错返回 HTTP 200 且 `web_search_tool_result`/`web_fetch_tool_result` 的 `content` 是单个错误对象（如 `{error_code: "max_uses_exceeded"}`）；web search 成功时 `content` 是列表、出错时是对象，索引前先分支判断。
66. 遍历 `response.content` 时匹配正确的块类型：`code_execution_20260521` 返回 `bash_code_execution_tool_result`（读 `.content.stdout`/`.stderr`/`.return_code`），不是旧的裸 `code_execution_tool_result`；Managed Agents 的 web 工具忽略环境的 `networking` 设置，用工具集 `configs` 里的 `allowed_domains` **或** `blocked_domains`（二者不能同时给，1-64 个纯主机名、含子域，IP、裸 TLD、单标签和 `localhost` 类名字两个工具都拒，路径后缀只在 `web_search` 上允许）来限制。
67. 工具搜索时不要把一切都 defer：搜索工具自身不能带 `defer_loading: true`，且 `tools` 里至少有一个工具未 defer，否则 API 返回 400 `All tools have defer_loading set`。
68. 迁移模型时先确认范围：用户要求迁移代码到更新的 Claude 模型但没点名具体文件、目录或文件清单时，先问清是整个工作目录、某个子目录还是一组具体文件，得到确认再动手；'migrate my codebase'、'move my project to X'、'upgrade to Sonnet 4.6' 这类祈使句和光秃秃的 'migrate to Opus 4.8' 都算模糊（只说做什么不说在哪），必须问；只有提示里点名了确切文件、具体目录或明确清单（'migrate `app.py`'、'migrate everything under `services/`'、'update `a.py` and `b.py`'）才直接开工。
69. 给 Claude Fable 5.1/Opus 5 写代码时默认带上服务端 `fallbacks` 参数并告知用户你已启用（用户拒绝才去掉）：最简形式是 `betas: ["server-side-fallback-2026-07-01"]` 加 `fallbacks: "default"`（按拒答类别路由，不用维护模型列表），旧数组形式 `betas: ["server-side-fallback-2026-06-01"]` + `fallbacks: [{"model": "claude-opus-4-8"}]` 仍可用；Bedrock/Vertex/Foundry 上用 SDK 的客户端侧 `BetaRefusalFallbackMiddleware` + `BetaFallbackState`。
70. 不要静默截断喂给 API 的文件或内容：内容太长装不进上下文窗口时，告知用户并一起讨论分块、摘要等方案，而不是悄悄截断。
71. 把工作当成可检查的输出：报告、文档或可视化任务可让 Claude 在代码执行沙箱里用预装的 `python-docx`、`python-pptx`、`matplotlib`、`pillow`、`pypdf` 生成 DOCX/PDF/图表，再通过 Files API 返回，而不是只输出纯文本 stdout。
72. 需要最新信息时用 WebFetch 取 `shared/live-sources.md` 里的实时文档 URL，包括：用户要求「最新/当前」信息、缓存数据看起来不对、问到本文未覆盖的功能；注意 Fable 5.1 有 30 天数据保留要求（ZDR 组织除非 Anthropic 明确授权否则返回 `400 invalid_request_error`）。

适用边界 · 注意事项

• 查询里点名了其他供应商（OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama），或项目里 `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` 有命中（未点名供应商时先跑这条 grep）——此时跳过全部触发条件，不要用本技能产出 Anthropic SDK 代码。
• 用户真正要的是 Claude Agent SDK（`claude-agent-sdk` / `@anthropic-ai/claude-agent-sdk`）而不是 Claude API / Tool Runner / Managed Agents 时，应指向其官方文档，不要拿 API 的 Tool Runner 顶替。
• 项目语言没有官方 Anthropic SDK（Rust、Swift、C++、Elixir 等）时不适用 SDK 方案，只能给 `curl/` 原始 HTTP 示例或说明可能有社区 SDK。