理解claude code的最重要的一个前提，那就是知道api有哪些组成：

代码位置: 

``` typescript
query.ts: deps.callModel()
claude.ts: queryModel()
```

场景设计:

你输入:"帮我分析 D:\logs\server.log，找出所有 ERROR 级别的日志，按时间排序，生成一份 HTML 报告。"
  ┌─────────────────────────────────────────────────────────┐
  │  你的一句自然语言                                                       │
  │  "帮我分析日志文件，生成 HTML 报告"                      │
  │         ↓                                                                               │
  │  Claude Code 将它 + 上下文 + 工具 + 控制参数             │
  │  打包成下面这个 JSON，发给 Anthropic API                 │
  └─────────────────────────────────────────────────────────┘

// ========== Anthropic Messages API 请求体 ==========
  {
    // 1️⃣ 模型标识 — "用哪个大脑干活"
    model: "claude-sonnet-4-20250514",
    // 对应你设置里的 model，经过 normalizeModelStringForAPI 标准化

    // 2️⃣ 系统提示词 — "你是谁 + 你当前在什么环境"
    system: [
      // 官方人设：你是一个 AI 编程助手，行为准则...
      { type: "text", text: "You are Claude, an AI assistant... 用中文回答... 代码风格偏 React..." },

      // 环境上下文：自动注入的 git 状态、操作系统、当前目录等
      { type: "text", text: "<environment>OS: Windows 10, PWD: D:\\logs, Git: main branch...</environment>" },
      // 还有日期、用户角色（你是某9研究生）等
    ],

    // 3️⃣ 对话历史 — "我们刚刚聊了什么"
    messages: [
      // 用户上下文块（临时注入，不持久化到历史）
      { role: "user", content: [{ type: "text", text: "当前日期 2026-06-04，用户是某9研究生..." }] },
      // 正式对话历史
      { role: "user", content: [{ type: "text", text: "帮我分析 D:\\logs\\server.log，找出 ERROR 日志，生成 HTML 报告"
  }] },
      // ↑ 这就是你刚才说的那句话，进入了 messages 数组
    ],

    // 4️⃣ 工具定义 — "你可以用哪些工具"
    tools: [
      { name: "Read", description: "读取文件内容", input_schema: { properties: { file_path: "string" } } },
      { name: "Write", description: "写入文件", input_schema: { properties: { file_path: "string", content: "string" } }
  },
      { name: "Bash", description: "执行终端命令", input_schema: {...} },
      { name: "Grep", description: "正则搜索文件内容", input_schema: {...} },
      // ... 总共 20+ 个工具：Glob、Edit、Agent、WebSearch 等
    ],
    // Claude 会从这些工具里选着用——比如先 Read 日志，再 Grep 搜 ERROR，最后 Write 生成 HTML

    // 5️⃣ 输出控制 — "最多说多少话 + 要不要思考"
    max_tokens: 8192,                    // 模型最多输出 8192 个 token
    thinking: {
      type: "adaptive",                   // 让模型自己判断：这个问题要不要深思
      budget_tokens: 10000                // 如果要思考，最多用 10000 token 来想
    },
    // 对于"分析日志"这种有明显步骤的任务，模型会自动启用 extended thinking

    // 6️⃣ Beta 功能头 — "开启哪些实验功能"
    betas: [
      "prompt-caching-2024-07-31",        // 提示词缓存：system prompt 不变，下次调用直接复用，省 token
      "context-management-2025-04-01",    // 上下文管理：可以主动清理 thinking 等不再需要的内容
      "fast-mode-2025-05-14",             // 快速模式：生成速度更快
    ],

    // 7️⃣ 可选参数 — "行为微调"
    tool_choice: { type: "auto" },       // 模型自己决定何时调用工具
    temperature: 1,                       // 默认温度为 1（thinking 模式下固定）

    // 8️⃣ 元数据 — "谁在调用"
    metadata: {
      user_id: "uuid-abc-123",            // 标识是你这个用户
      session_id: "session-xyz-456"       // 标识这次会话
    },
    // 用于 Anthropic 侧的用量统计与安全审计

    // 9️⃣ 输出配置 — "干活预算"
    output_config: {
      effort: "high",                     // 告诉模型：认真干，不求快
      task_budget: { total: 500000 }      // 整个任务最多花 500K token（含多轮交互）
    },
    // 对于"分析日志→生成 HTML"这种多步任务，给足预算让它循环 Read → Grep → Write

    // 🔟 上下文管理 — "该扔的东西趁早扔"
    context_management: {
      clear_types: ["thinking"],          // 每轮结束后可以清除 thinking 内容
      clear_all_thinking: false           // 不强制清空所有 thinking
    }
    // 好处：thinking 内容很长但用完就没用了，清除后腾出空间给真正的对话
  }

## 一、**角色相关（Who you are / Who the user is）**

这些信息用于让模型知道“对话双方是谁”，建立身份认知和上下文。

- `system` 中的部分内容:
  - `"You are Claude, an AI assistant... 用中文回答..."`：这是 Claude 的官方人设。
  - `<environment>OS: Windows 10, PWD: D:\\logs...</environment>`：包含用户当前的操作环境（间接反映用户身份和上下文）。
  - “用户是某9研究生”：明确用户角色（出现在 `messages` 的临时上下文块中）。

✅ **作用**：让模型以合适的身份（AI 编程助手）与特定角色（如研究生）交互，并适配其技术背景和需求语气。

------

## 二、**写代码/任务执行相关（What to do / How to help）**

这些是直接驱动模型完成具体编程或自动化任务的核心要素。

- **`messages` 中的用户输入**：
  - `"帮我分析 D:\\logs\\server.log，找出 ERROR 日志，生成 HTML 报告"`：这是用户的**核心指令**，定义了任务目标。
- **`tools` 列表**：
  - `Read`, `Grep`, `Write`, `Bash` 等工具定义：告诉模型“你可以调用哪些能力来完成任务”。
- **`tool_choice: { type: "auto" }`**：
  - 允许模型自主决定何时使用工具，是实现自动化流程的关键。
- **`output_config.effort = "high"` 和 `task_budget`**：
  - 明确任务复杂度高，需认真处理，允许多轮工具调用。

✅ **作用**：构成“任务执行引擎”的骨架——模型据此规划步骤（如：读文件 → 过滤 ERROR → 生成 HTML → 写入），并调用工具链完成。

------

## 三、**Claude 模型能力相关（How the model thinks / behaves）**

这些参数控制模型自身的推理方式、输出风格和资源使用。

- **`model` 字段**：
  - 指定使用 `claude-sonnet-4-20250514`，决定了基础能力（速度、智能程度、上下文长度等）。
- **`thinking` 配置**：
  - `type: "adaptive"`, `budget_tokens: 10000`：启用**扩展推理**（extended thinking），让模型在复杂任务中“先想清楚再干”。
- **`max_tokens: 8192`**：
  - 控制单次响应的最大长度，影响能否完整输出代码或报告。
- **`temperature: 1`**：
  - 虽然通常 temperature=0 更确定，但在 thinking 模式下固定为 1，允许探索性推理。

✅ **作用**：激活和约束 Claude 的**高级推理能力**，使其能处理多步骤、有状态的任务（如日志分析 + 报告生成），而不仅是简单问答。

------

## 四、**Claude 识别/路由/优化相关（How the system routes and optimizes）**

这些是底层系统用于提升效率、安全性和可维护性的元信息。

- **`betas` 列表**：
  - `prompt-caching-2024-07-31`：缓存 system prompt，减少重复 token 消耗。
  - `context-management-2025-04-01`：支持动态清理上下文（如清除 thinking 内容）。
  - `fast-mode-2025-05-14`：启用更快的推理路径。
- **`metadata`**：
  - `user_id`, `session_id`：用于用量统计、审计、调试。
- **`context_management`**：
  - `clear_types: ["thinking"]`：任务完成后自动清理中间思考内容，节省上下文窗口。

✅ **作用**：**不直接影响任务逻辑**，但极大提升系统性能、降低成本、保障安全，属于“幕后基础设施”。