第 3 课：SDK 核心——query() 函数

query() 是什么？

query() 是 Claude Agent SDK 最核心的函数。你可以把它理解为：给 AI 下一个任务，然后 AI 自己去完成。

打个比方：

code

query() 就像你给一个超级助手发微信：
  "帮我查一下张三的背景资料，然后写份简历"

然后这个助手会：
  - 自己去上网搜索
  - 自己整理信息
  - 自己写代码生成文档
  - 最后告诉你"搞定了"

最简单的 query() 调用

先看一个最简版本，去掉所有花哨的东西：

code
import { query } from '@anthropic-ai/claude-agent-sdk';

// 给 AI 一个任务
const q = query({
  prompt: "帮我写个 Hello World",
  options: {
    model: 'sonnet',
  },
});

// 接收 AI 的回复（它是一条一条发回来的）
for await (const msg of q) {
  console.log(msg);
}

就这么简单。三步走： 1. 导入 query 2. 调用 query()，传入你的任务 3. 用 for await 循环接收 AI 发回来的消息

resume-generator 里的 query() 长什么样？

现在看看实际项目里是怎么调用的：

bash
const q = query({
  prompt: `Research "${personName}" and create a professional
           1-page resume as a .docx file.`,
  options: {
    maxTurns: 30,           // AI 最多可以"操作"30 轮
    cwd: process.cwd(),     // 工作目录
    model: 'sonnet',        // 用 Sonnet 模型
    allowedTools: [         // 允许 AI 使用哪些工具
      'Skill',              // 读取技能文件
      'WebSearch',          // 搜索网页
      'WebFetch',           // 抓取网页内容
      'Bash',               // 执行命令行命令
      'Write',              // 写文件
      'Read',               // 读文件
      'Glob'                // 查找文件
    ],
    settingSources: ['project'],  // 从项目目录加载配置（技能文件）
    systemPrompt: SYSTEM_PROMPT,  // 系统提示词
  },
});

别慌，我们一个一个参数来看。

参数详解

prompt —— 你要 AI 做什么

code
prompt: `Research "${personName}" and create a professional
         1-page resume as a .docx file.`

这就是你"发给 AI 的消息"。越清楚越好。这里告诉 AI： - 搜索某个人的信息 - 生成一份专业的 1 页简历 - 输出为 .docx 格式

model —— 用哪个 AI 模型

code
model: 'sonnet'

可选值：

模型	特点	适合场景
`sonnet`	速度快、性价比高	大多数任务（推荐）
`opus`	最聪明、最贵	特别复杂的任务
`haiku`	最快、最便宜	简单任务

简历生成用 Sonnet 就够了。

maxTurns —— AI 最多可以操作多少轮

code
maxTurns: 30

一"轮"就是 AI 做一次动作。比如搜索一次是一轮，写一个文件是一轮。30 轮的意思是：AI 最多可以做 30 个动作来完成你的任务。

code

轮次示意：
  第 1 轮：搜索 "Elon Musk LinkedIn"
  第 2 轮：搜索 "Elon Musk education"
  第 3 轮：抓取搜索结果页面
  第 4 轮：写 generate_resume.js 文件
  第 5 轮：执行 node generate_resume.js
  ...
  完成！（实际可能用不了 30 轮）

设 30 是给 AI 足够的空间。如果任务简单，AI 可能只用 5-10 轮就搞定了。

cwd —— 工作目录

code
cwd: process.cwd()

告诉 AI "你在哪个文件夹干活"。AI 创建文件、执行命令都是基于这个目录的。

allowedTools —— 允许使用哪些工具

bash
allowedTools: ['Skill', 'WebSearch', 'WebFetch', 'Bash', 'Write', 'Read', 'Glob']

这是"工具箱"。不在这个列表里的工具，AI 不能用。下一课会详细讲每个工具。

settingSources —— 从哪里加载配置

code
settingSources: ['project']

'project' 表示从项目目录的 .claude/ 文件夹加载配置和技能文件。这样 AI 就能读到 .claude/skills/docx/ 下面的文档创建技能了。

systemPrompt —— 系统提示词

code
systemPrompt: SYSTEM_PROMPT

"系统提示词"相当于 AI 的"工作手册"——告诉它是什么角色、该怎么干活、输出什么格式。第 6 课会专门讲。

query() 返回什么？

query() 返回一个"异步迭代器"——说人话就是：它会一条一条地把 AI 的消息发回来。

code
for await (const msg of q) {
  // msg 就是一条消息
  // msg.type 告诉你这是什么类型的消息
}

消息类型：

code

msg.type 可能的值：

  "assistant"    ← AI 说了一段话（或者要用工具）
  "result"       ← 工具执行完了，返回结果

在 resume-generator 里，代码是这样处理消息的：

code
for await (const msg of q) {
  if (msg.type === 'assistant' && msg.message) {
    // AI 发来的消息
    for (const block of msg.message.content) {
      if (block.type === 'text') {
        // AI 说了一段文字
        console.log(block.text);
      }
      if (block.type === 'tool_use') {
        // AI 要用工具了
        console.log(`🔧 Using tool: ${block.name}`);
      }
    }
  }
  if (msg.type === 'result') {
    // 工具返回了结果
    console.log(`↳ Result: ${JSON.stringify(msg.content)}`);
  }
}

用图来表示这个消息流：

bash

query() 开始
    │
    ├─ assistant: "我来搜索一下这个人的信息"
    ├─ assistant: tool_use → WebSearch("Elon Musk")
    ├─ result: 搜索结果...
    ├─ assistant: "找到了，我来整理一下"
    ├─ assistant: tool_use → Write("generate_resume.js")
    ├─ result: 文件已创建
    ├─ assistant: tool_use → Bash("node generate_resume.js")
    ├─ result: 代码执行成功
    ├─ assistant: "简历已生成！"
    │
query() 结束

query() vs ClaudeSDKClient

SDK 里其实有两种用法：

	query()	ClaudeSDKClient
模式	一次性任务	对话式交互
比喻	发一条微信等回复	开一个微信群聊天
适合	明确的任务	需要来回沟通的场景
本项目用的	✅	❌

resume-generator 用的是 query()，因为任务很明确："搜索+生成简历"，不需要来回对话。

本课小结

query() 是 SDK 的核心函数，"给 AI 一个任务，AI 自己去完成"
关键参数：prompt（任务）、model（模型）、maxTurns（最多操作轮数）、allowedTools（工具箱）
它返回一个消息流，你可以用 for await 逐条接收
消息分两类：assistant（AI 说话/用工具）和 result（工具返回结果）

课后练习

试着把 maxTurns 改成 5，看看 AI 会不会来不及完成任务
把 model 改成 'haiku'，对比一下生成的简历质量
从 allowedTools 里去掉 'WebSearch'，看看 AI 没法搜索时会怎么办