深入 Claude Code 核心：Agent 主循环 query() 的 AsyncGenerator 工作原理解析-北京尧图网络

【免费下载链接】claude-code-sourcemapclaude-code full original source code from source maps项目地址https://gitcode.com/gh_mirrors/cla/claude-code-sourcemap点击查看免费下载本文带你深入 Claude Code 的完整原始源码claude-code-sourcemap基于 source map 还原的 0.2.8 版本用通俗易懂的方式解析其 Agent 主循环核心函数query()如何借助 TypeScript 的 AsyncGenerator 实现模型调用 → 工具执行 → 递归追问的自动循环。无需深厚背景看完你就懂 AI 编程 Agent 是怎么自己干活的。一张图看懂 Agent 主循环先用一张流程概览把 src/query.ts 里query()的主循环逻辑浓缩成 5 个环节用户消息 │ ▼ ① 组装系统提示词 ──► ② 调用模型querySonnet │ │ │ ▼ │ ③ 从回复里提取 tool_use 块 │ │ │ 没有工具调用──► 结束本轮对话完成 │ │ 有 ▼ ▼ ⑤ 把 [历史助手消息工具结果] 递归传回 query() ◄── ④ 权限校验执行工具这个循环就是所有Agentic Coding工具的灵魂模型想干什么就调什么工具工具结果再喂回给模型直到它认为任务完成、不再请求工具为止。什么是 AsyncGenerator为什么 Agent 框架偏爱它AsyncGenerator异步生成器是 JavaScript/TypeScript 的一个语言特性函数用async function*声明就能一边暂停一边吐出数据。对 Agent 框架来说它几乎是完美方案原因有三流式推送模型每回复一条消息、工具每产出一个进度就能立刻yield给界面终端不用干等天然挂起等待用户执行写文件这类危险操作前权限检查可以在生成器内部卡住等用户点确认其余代码无需轮询递归无栈风险query()通过yield*递归调用自己src/query.ts#L234-L241因为每层都是生成器而非常规函数调用栈模型 ↔ 工具可以无限来回而不爆栈。query()的函数签名非常直观返回类型就是AsyncGeneratorMessage, voidsrc/query.ts#L124-L134参数作用messages迄今为止的完整对话历史systemPromptcontext系统提示词与附加上下文由formatSystemPromptWithContext合并canUseTool权限钩子决定这个工具让不让用toolUseContext运行环境工具列表、中止信号、思考 token 上限等它吐出的Message共有三种形态src/query.ts#L35-L66类型含义用途UserMessage工具执行结果tool_result拼回对话历史喂给下一轮模型AssistantMessage模型回复含costUSD成本与耗时展示给用户ProgressMessage工具执行中的中间进度仅供 UI 实时展示不进入对话历史四步拆解一次 query() 的完整旅程第 1 步请求模型query()内部定义了getAssistantResponse()它调用 querySonnet()把归一化后的消息、系统提示词、思考 token 上限和工具列表发给 Anthropic API。注意一个细节请求会被 VCR录像回放中间件包一层方便离线测试。第 2 步判断是否还要用工具模型回复后代码直接过滤出所有tool_use类型的 content 块src/query.ts#L171-L178源码注释特意提醒stop_reason tool_use不可靠不能总被正确设置——所以官方选择看实际内容而不是看状态码这是实战踩坑经验的直接体现。如果没有任何tool_use函数直接return本轮结束。第 3 步权限校验执行工具每个tool_use都会走 checkPermissionsAndCallTool() 的完整流水线Schema 校验用 Zod 验证模型生成的入参。源码里有一句幽默的注释——surprisingly, the model is not great at generating valid input出乎意料地模型生成合法入参的能力并不好校验失败会把InputValidationError作为错误结果返回给模型让它自我修正业务校验各工具自己的validateInput()权限询问调用canUseTool它背后是 useCanUseTool 钩子会弹出终端确认框用户按 Esc 取消时会触发abortController.abort()一次性中止所有挂起的工具调用真正执行tool.call()本身也是一个异步生成器result表示最终结果progress表示中间进度两者分别包装成UserMessage和ProgressMessage向外吐出。第 4 步排序结果递归再问所有工具执行完后toolResults会按与tool_use请求相同的顺序排序API 要求 tool_result 与 tool_use 一一对应src/query.ts#L223-L232然后执行最精妙的一行yield* await query([历史, 助手消息, 工具结果...], ...)yield*把子生成器的每一条输出原样转发给上层对话历史不断累积循环就这样一轮一轮推进直到模型交卷。并行与串行MAX_TOOL_USE_CONCURRENCY 的策略模型常常一条回复里同时请求多个工具。query()的策略是src/query.ts#L182-L216全部是只读工具如文件读取、grep 搜索→ 走runToolsConcurrently并行执行上限由 MAX_TOOL_USE_CONCURRENCY 10 控制只要有一个非只读工具如改文件、跑 shell→ 降级为runToolsSerially串行执行避免并发改坏状态。并行能力来自 utils/generators.ts 的 all()它用Promise.race从一批生成器中谁先吐数据就先转发谁实现带并发上限的合流是 AsyncGenerator 编程的教科书级用法。顺带一提Agent 可用工具全集在 src/tools.ts 中注册包括BashTool、FileEditTool、GrepTool、AgentTool子 Agent等十余种。消息流如何驱动终端 UI生成器是发动机而 REPL 界面是仪表盘。用户提交消息后onQuery只做一件事for await (const message of query(...)) { setMessages(old [...old, message]) // 每来一条就渲染一条 }模型回复、工具进度、执行结果逐条到达React 状态逐条追加——你在终端里看到的实时打字工具执行动画本质上就是这个for await循环在消费 AsyncGenerator。这也解释了为什么 Claude Code 支持随时 Esc 中断中止信号贯穿整条消息链任何一环都能立刻刹车。源码速查表跟着 Agent 主循环读代码想了解什么去哪里看Agent 主循环与递归逻辑src/query.ts工具并发合流all()src/utils/generators.ts模型 API 请求封装src/services/claude.ts权限确认钩子src/hooks/useCanUseTool.ts消息类型定义src/utils/messages.tsx工具注册表src/tools.tsUI 消费端 REPLsrc/screens/REPL.tsx小结Claude Code 的query()用一个不到 120 行的 AsyncGenerator 递归函数搭起了整个 Agent 的骨架生成器负责流式产出消息递归负责模型—工具无限循环yield*负责层层透传AbortController负责人类随时叫停。理解了这套模式你再看任何 AI Agent 框架的 ReAct 循环、工具调用管线都会发现殊途同归。延伸建议先通读query()全文约 516 行再对照all()与checkPermissionsAndCallTool()是掌握 Agent 主循环源码的最佳阅读路径。赞分享【免费下载链接】claude-code-sourcemapclaude-code full original source code from source maps项目地址https://gitcode.com/gh_mirrors/cla/claude-code-sourcemap点击查看免费下载相关推荐揭秘Claude Code Agent循环系统智能编程助手的核心引擎如何工作揭秘Claude Code Agent循环系统智能编程助手的核心引擎如何工作 Claude Code是Anthropic公司开发的官方CLI工具实现了一个完示例工程教程人工智能AI Agent代码智能体DouK-Downloader3 步拿到作品原声免转码的抖音音频提取指南DouK Downloader3 步拿到作品原声免转码的抖音音频提取指南晚上十点剪视频前发现想要的 BGM 藏在一个抖音作品里长按保存只能拿到带画面的网页爬虫CLI短视频Claude Code Agent 框架深度解析从源码拆解核心循环、提示词工程、工具系统与上下文压缩Claude Code Agent 框架深度解析从源码拆解核心循环、提示词工程、工具系统与上下文压缩导读本文基于当前开源仓库cc haha 工作区中的AI 应用桌面应用AI AgentAI 技能即时通讯GUI 自动化上一篇ASO Skills App Preview视频脚本30秒抓住用户的逐拍结构下一篇LightCraft命令行与JSON控制协议139个命令实现照片处理全流程自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

深入 Claude Code 核心：Agent 主循环 query() 的 AsyncGenerator 工作原理解析

相关推荐

《AI Agent原理与实战》2026版第22课编排实战：Supervisor 与 Orchestrator-Worker

FPGA版本迭代实践：如何通过影响域分析锁定待验证模块

30 分钟跑通一次 APK 逆向完整分析：Codex-X 提示词注入工具指南

更多资讯

PCA9422与PIC18F86J55嵌入式电源管理方案设计与实战

俄语字母Unicode映射与编码转换实战指南

微信公众号RSS聚合系统搭建原理与实践

PCA9422与STM32F303K8低功耗电源管理设计实战

Spring Boot应用接入ELK日志收集实战：从架构到踩坑全解析

Elo竞赛复盘：特征工程、目标编码与模型融合的实战指南

今日更新

MATLAB缩进快捷键与批量格式化实战指南

用Poco实现Qt风格信号与槽的跨平台C++方案

ESXi裸机虚拟化安装指南：从硬件兼容到虚拟机部署

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？