摘要：本文深入剖析 Claude Code的 Agent 循环架构，揭示其如何通过 分层状态机、 流式工具执行和 自适应上下文管理，实现高效、可靠的 AI 驱动开发体验。我们从核心循环设计、多 Agent 协作、错误恢复机制三个维度展开分析，为构建生产级 AI Agent 系统提供实践参考。节省时间核心观点总结：构建好的Agent，核心在于将系统工程思维与AI的不确定性相结合：状态机驱动：让控制流显式化、可追溯。流式优先：优化延迟，提升交互体验。主动压缩：将上下文管理作为核心功能而非事后补救。分层恢复：预设多条降级路径，防止系统雪崩。隔离协作：通过松耦合通信保障多Agent系统的可维护性。工程严谨：通过特征门控和显式清理，确保长期运行的可靠性。核心认知：优秀的Agent不仅是提示词工程的胜利，更是深厚系统设计能力的体现。引言随着大语言模型在软件开发中的应用日益广泛，如何构建一个可靠、高效、可扩展的 Agent 系统成为关键挑战。Claude Code 作为 Anthropic 官方的命令行助手，其底层架构展现了一个成熟生产级 Agent 系统的設計范式。本文将深入源代码层面，解析 Claude Code 的核心循环机制，重点探讨以下问题：核心循环架构：如何将"思考 - 行动 - 观察"循环转化为可维护的代码结构？状态管理：如何在多轮对话中保持一致性并支持复杂的中断恢复？上下文优化：如何动态管理有限的 token 预算以支持长会话？多 Agent 协作：如何实现 Agent 间的松耦合通信与并发执行？一、核心循环架构设计1.1 主循环结构Claude Code 的核心引擎位于src/query.ts，采用异步生成器实现的无限循环结构：// query.ts:307 - 主循环入口 while (true) { // 1. 状态解构与准备 let { toolUseContext } = state const { messages, turnCount, ... } = state // 2. 预处理：上下文压缩、token 预算检查 messagesForQuery = await applyToolResultBudget(...) const microcompactResult = await deps.microcompact(...) // 3. API 调用：流式接收模型响应 for await (const message of deps.callModel({...})) { assistantMessages.push(message) if (hasToolUse) needsFollowUp = true } // 4. 工具执行：并行/串行执行工具调用 const toolUpdates = streamingToolExecutor ? streamingToolExecutor.getRemainingResults() : runTools(toolUseBlocks, ...) for await (const update of toolUpdates) { yield update.message toolResults.push(update.message) } // 5. 后处理：Hook 执行、队列命令附加 const queuedCommands = getCommandsByMaxPriority(...) for await (const attachment of getAttachmentMessages(...)) { yield attachment toolResults.push(attachment) } // 6. 继续判断：状态更新与循环决策 if (!needsFollowUp) return { reason: 'completed' } state = { messages: [...messagesForQuery, ...assistantMessages, ...toolResults], turnCount: turnCount + 1, // ...其他状态更新 } }设计亮点：生成器模式：使用AsyncGenerator实现流式输出，支持增量渲染和部分结果消费状态集中管理：通过State类型（第 204-217 行）携带跨迭代状态，避免参数爆炸解耦执行阶段：清晰分离"采样→执行→后处理"三阶段，便于独立优化和测试1.2 状态机设计循环本质上是一个带条件的状态转移系统，关键状态包括：// query.ts:204 - State 类型定义 type State = { messages: Message[] // 累积的消息历史 toolUseContext: ToolUseContext // 工具执行上下文 autoCompactTracking: AutoCompactTrackingState | undefined // 压缩追踪 maxOutputTokensRecoveryCount: number // 输出限制恢复计数 hasAttemptedReactiveCompact: boolean // 响应式压缩标志 maxOutputTokensOverride: number | undefined // 输出 token 覆盖 pendingToolUseSummary: Promise... | undefined // 待处理的工具摘要 stopHookActive: boolean | undefined // 停止 Hook 激活标志 turnCount: number // 回合计数器 transition: Continue | undefined // 上一轮的继续原因 }状态转移规则：| 当前状态 | 触发条件 | 下一状态 | 转移类型 ||---------|---------|---------|---------|| 任何状态 |abort信号 | 终止 |aborted_streaming|| 流式完成 |!needsFollowUp| 完成或恢复 |completed/recovery|| 有工具调用 |needsFollowUp=true| 工具执行 |next_turn|| Token 超限 | 达到阈值 | 压缩或错误 |reactive_compact_retry|| Hook 阻塞 |blockingErrors.length 0| 错误注入 |stop_ho