findscripter 本条目改写自 Anthropic 官方 claude-api 技能（Apache-2.0），保留其关键约束与默认值，面向 AI Agent 直接消费。
何时使用
满足以下任一条件时使用：
- 代码 import 了
anthropic/@anthropic-ai/sdk（或com.anthropic.*等官方 SDK）。 - 用户要求构建、调试或优化 Claude API / Anthropic SDK / Managed Agents 应用。
- 用户在文件中新增或调参某个 Claude 特性（缓存、思考、压缩 compaction、工具调用、批处理、文件、引用、记忆）或切换模型（Opus/Sonnet/Haiku）。
- 关于提示缓存 / 缓存命中率的问题。
- 在 Claude 模型版本间迁移代码（如 4.6→4.7→4.8，或替换已退役模型）。
不该用的边界（命中即停手并说明）：
- 文件 import 了
openai或其它厂商 SDK，文件名形如*-openai.py/*-generic.py，或代码刻意保持 provider-neutral——本技能只产出 Claude/Anthropic 代码，应先询问用户是否切换到 Claude，不要在非 Anthropic 文件里塞入 Anthropic 调用。 - 通用编程或 ML 问题，与 Claude API 无关。
- 切勿用 OpenAI 兼容垫片（compat shim）冒充 Claude 调用。
步骤
- 入场扫描：检查目标文件/项目是否含非 Anthropic 标记（
import openai、gpt-4/5、langchain_openai等）。命中则停手询问，不要继续。 - 语言识别：按项目文件推断语言并读取对应官方文档——
*.py→Python，*.ts/.js→TypeScript（JS 共用 TS SDK），*.java/.kt/.scala→Java，*.go→Go，*.rb→Ruby，*.cs→C#，*.php→PHP。无法判断时询问用户，默认 Python。 - 选对调用面（surface）：
- 单次调用（分类/摘要/抽取/问答、批处理、嵌入）→ Claude API 单请求。
- 多步、由代码编排的流水线，或自带工具的自定义 Agent → Claude API + 工具调用（自己控制循环）。
- 需要 Anthropic 托管 Agent 循环并提供 per-session 容器沙箱 → Managed Agents（仅一方 1P，Bedrock/Vertex/Foundry 不支持，这些平台一律用 Claude API + 工具调用）。
- 默认从最简层级起步，只有任务确需开放式、模型自主探索时才上 Agent。
- 写出 SDK 代码：函数名、类名、方法签名、import 路径必须来自明确文档，不得凭 cURL 形状或别的语言 SDK 臆测；缺失绑定时先 WebFetch 官方仓库再写。
- 默认就加提示缓存（本技能产出的应用应包含缓存）。
- 自检缓存与产物：用
usage.cache_read_input_tokens验证缓存是否命中。
指令（默认值，除非用户另有要求）
- 模型：默认用 Claude Opus 4.8，模型串严格为
claude-opus-4-8。只用文档表中的精确模型 ID，不要追加日期后缀（用claude-sonnet-4-6，不是claude-sonnet-4-6-20250514）。绝不为省成本擅自降级——那是用户的决定。需要更老的模型时查shared/models.md，不要自己拼。 - 思考：Opus 4.8/4.7 仅支持自适应思考
thinking: {type: "adaptive"}；{type: "enabled", budget_tokens: N}会返回 400（budget_tokens、temperature、top_p、top_k均已移除）。Opus 4.6 / Sonnet 4.6 也用 adaptive，budget_tokens已弃用。用户说"extended thinking / 思考预算 / budget_tokens"时，一律改用 Opus 4.8 + adaptive，不要切到老模型。 - Effort：
output_config: {effort: "low"|"medium"|"high"|"max"}（在output_config内，非顶层），默认high；max仅 Opus 级；Opus 4.7/4.8 新增"xhigh"，编码/智能体任务推荐。Sonnet 4.5 / Haiku 4.5 用 effort 会报错。 - 流式：任何可能长输入、长输出或高
max_tokens的请求默认流式，避免 HTTP 超时；用.get_final_message()/.finalMessage()取完整响应。128K 输出必须流式。 - max_tokens：非流式默认
~16000，流式默认~64000；分类等场景才下调到~256。不要 lowball，否则会截断需重试。 - 结构化输出：用
output_config: {format: {...}}（旧output_format已弃用）；推荐client.messages.parse()自动校验。 - Prefill 移除：4.6/4.7/4.8 家族（含 Sonnet 4.6）最后一条 assistant 消息 prefill 会 400，改用结构化输出或 system 指令控制格式。
示例
最小 Python 调用（注意 response.content 是内容块列表，需判 .type）：
import anthropic
client = anthropic.Anthropic() # 读 ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive"},
messages=[{"role": "user", "content": "法国的首都是哪里？"}],
)
for block in response.content:
if block.type == "text":
print(block.text)
提示缓存（前缀匹配，渲染序为 tools → system → messages，把稳定内容放前、易变内容放最后一个断点之后）：
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
system=[{"type": "text", "text": "<大段共享系统提示>",
"cache_control": {"type": "ephemeral"}}],
messages=[{"role": "user", "content": "<每次都变的问题>"}],
)
print(response.usage.cache_read_input_tokens) # 跨请求若恒为 0 说明有静默失效源
注意事项
- 提示缓存只认前缀：前缀里任一字节变化（system 里插
datetime.now()、未排序的 JSON、变动的工具集）都会让后续全部失效。系统提示要冻结，动态上下文放到靠后的 message；工具按 name 排序、对话中途不改 tools/model。最小可缓存前缀约 1024 token，每请求最多 4 个断点。 - 不要静默截断输入：内容超窗时告知用户并讨论分块/摘要，别偷偷砍。
- 解析工具入参：4.6/4.7/4.8 家族工具调用
input的 JSON 转义可能不同，务必json.loads()/JSON.parse()，禁止对序列化串做裸字符串匹配。 - Compaction（beta）：长会话开启服务端压缩需 beta 头
compact-2026-01-12；每轮把整个response.content（不只是文本）追加回 messages，否则压缩状态会静默丢失。 - 迁移先确认范围：用户说"迁移我的代码库/升级到 X"但未指明文件/目录时，先问范围再动手。
- 不要重造 SDK：用
stream.finalMessage()、SDK 类型（Anthropic.MessageParam/Tool/Message）与具名异常类（RateLimitError等），别自定义等价类型或字符串匹配错误。 - Managed Agents 流程固定：Agent 创建一次（
model/system/tools在 Agent 上）→ 每次运行起 Session；保存agents.create返回的 ID 复用，不要在请求路径里反复创建。 - 遇到"最新/当前"信息或本条未覆盖的特性，用 WebFetch 查官方实时文档（源清单见
shared/live-sources.md）。
互见
- 设计 Claude 的提示词与少样本结构：见 prompt-template-designer。
- 把检索上下文喂给 Claude 做 RAG：见 rag-pipeline-builder。
- 把 Claude 工具/智能体能力封装为 MCP server：见 mcp-builder。
- 审查生成的 SDK 调用代码、排查依赖：见 code-reviewer、dependency-auditor。