extended-thinking

扩展思考（Ultrathink）技能

为复杂推理任务启用 Claude 的扩展思考能力，在回答前进行内部推敲。

适用场景

• 复杂问题求解：需要多步推理
• 代码架构决策：涉及多种权衡
• 复杂问题调试：需要系统性分析
• 战略规划：涉及多个变量
• 数学或逻辑证明
• 安全分析：需要威胁建模
• 性能优化：涉及多个因素

支持的模型

模型	思考配置
Claude Fable 5 (claude-fable-5)	始终开启——省略 thinking 参数（或使用 {"type": "adaptive"}）；使用 {"type": "disabled"} 会返回 400
Claude Opus 4.8 / 4.7 (claude-opus-4-8)	使用 {"type": "adaptive"}（省略时为关闭）；budget_tokens 已移除——会返回 400
Claude Sonnet 5 (claude-sonnet-5)	省略 thinking 时默认采用自适应模式；budget_tokens 已移除——会返回 400
Claude Opus 4.6 / Sonnet 4.6	推荐使用 {"type": "adaptive"}；budget_tokens 已弃用（仅用于过渡）
较旧模型（Sonnet 4.5、Haiku 4.5 等）	使用 {"type": "enabled", "budget_tokens": N}——下文所述的手动预算机制

API 配置

自适应思考——当前模型（Python）

对于当前模型（Opus 4.6+、Sonnet 5、Fable 5），自适应思考取代了手动预算：Claude 会自行决定思考的时机和程度，而 output_config.effort 用于控制深度。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low | medium | high | xhigh | max
    messages=[{
        "role": "user",
        "content": "Analyze this complex architecture decision..."
    }]
)

# Access thinking and response
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

TypeScript 配置

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [
    {
      role: "user",
      content: "Analyze this complex architecture decision...",
    },
  ],
});

手动预算——仅适用于较旧模型（budget_tokens）

对于较旧模型（Sonnet 4.5 / Haiku 4.5 时代），扩展思考通过固定的令牌预算启用。budget_tokens 必须 >= 1,024 且 < max_tokens。请勿在当前模型上使用此配置——Opus 4.7+、Sonnet 5 和 Fable 5 已移除 budget_tokens，使用后会返回 400 错误（在 Opus 4.6 / Sonnet 4.6 上虽已弃用，但仍可用）。

response = client.messages.create(
    model="claude-sonnet-4-5",  # older model — manual budget still applies
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000  # Minimum 1,024
    },
    messages=[{"role": "user", "content": "..."}]
)

流式传输（大 max_tokens 值时必需）

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=32000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": prompt}]
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if hasattr(event.delta, "thinking"):
                print(event.delta.thinking, end="", flush=True)
            elif hasattr(event.delta, "text"):
                print(event.delta.text, end="", flush=True)

思考深度建议

当前模型——effort 级别（output_config: {"effort": ...}）

Effort	使用场景
low	简单澄清、对延迟敏感的任务、子 Agent
medium	代码审查、调试、设计决策（成本平衡较好）
high（默认）	架构规划、安全审计、对智能要求较高的工作
xhigh	最难的编码和 Agent 任务（Opus 4.7+、Sonnet 5、Fable 5）
max	正确性比成本更重要；可能容易过度思考

较旧模型——budget_tokens

任务复杂度	Budget Tokens	使用场景
轻量	1,024 - 4,000	简单澄清、基础分析
中等	4,000 - 10,000	代码审查、调试、设计决策
繁重	10,000 - 20,000	架构规划、安全审计
复杂	20,000 - 32,000	多系统分析、全面审查
最大	32,000+	预算超过 32k 时使用批处理 API

在扩展思考中使用工具

重要：在扩展思考中使用工具时，必须在对话历史中保留思考块。

# Initial request with thinking
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[{
        "name": "analyze_code",
        "description": "Analyze code for issues",
        "input_schema": {
            "type": "object",
            "properties": {"code": {"type": "string"}},
            "required": ["code"]
        }
    }],
    messages=[{"role": "user", "content": "Analyze this code..."}]
)

# MUST include ALL content blocks including thinking
tool_use_block = next(b for b in response.content if b.type == "tool_use")
tool_result = execute_tool(tool_use_block)

# Continue with thinking blocks preserved
follow_up = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[...],
    messages=[
        {"role": "user", "content": "Analyze this code..."},
        {"role": "assistant", "content": response.content},  # Includes thinking!
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": tool_result
        }]}
    ]
)

交错思考

对于当前模型（Opus 4.6+、Sonnet 5、Fable 5），自适应思考会在工具调用之间自动交错进行——无需 beta 标头：

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[...]
)

对于使用手动 budget_tokens 的较旧 Claude 4 模型，交错思考需要 interleaved-thinking-2025-05-14 beta 标头。

限制

• 当前模型（Opus 4.7+、Sonnet 5、Fable 5）：budget_tokens、temperature、top_p 和 top_k 均已移除——发送其中任何一个都会返回 400
• 较旧的模型：budget_tokens 最低为 1,024，且必须小于 max_tokens；temperature 必须为 1（默认值）；扩展思考模式下不能使用 top_k
• 最大输出：128k 个 token（思考 + 响应）；Haiku 4.5 的上限为 64k
• 需要流式传输：当 max_tokens 较大时（超过约 16k，以避免 SDK HTTP 超时）
• 系统提示词：完全兼容

最佳实践

1. 从保守设置开始：先使用较低的预算，并按需增加
2. 监控实际用量：跟踪响应用量中的 thinking_tokens
3. 使用流式传输：获得更好的用户体验并支持更大的输出
4. 保留思考块：这对多轮工具调用至关重要
5. 批量处理重负载任务：预算超过 32k 个 token 时使用批处理 API
6. 让预算与任务相匹配：简单任务无需分配过多预算

与 Claude Code 集成

在 Claude Code CLI 中使用扩展思考模型时：

# The CLI automatically handles extended thinking for supported models
# Use opus or sonnet models for complex tasks

claude --model claude-opus-4-8 "Analyze this codebase architecture"

另请参阅

• [[complex-reasoning]] - 多步骤推理模式
• [[deep-analysis]] - 分析思考模板
• [[llm-integration]] - 通用 LLM API 模式