基于对 Claude Code 源码的系统性分析本文从 11 个维度拆解其架构设计涵盖 Agent Loop、Context 管理、Tool 调用、Memory、权限安全、多智能体协作、可观测性等核心模块。一、整体架构Claude Code 是一个基于 TypeScript 的终端 Agent 应用构建在 Bun 运行时之上采用 React Ink 渲染 TUI。其架构设计遵循分层解耦、流式驱动、不可变状态三大原则。1.1 架构全景图1.2 入口架构src/main.tsx (~3000行)├── 参数解析 (argparse)├── Feature Flag 门控 (feature() from bun:bundle)├── 环境检测 (USER_TYPE, CLAUDE_CODE_ENTRYPOINT)├── 初始化 (迁移、设置、插件)├── 交互式 REPL 模式└── 无头模式 (-p/--print)多客户端支持通过入口点检测实现客户端检测方式CLI直接执行SDKCLAUDE_CODE_ENTRYPOINTsdkVSCodeExtension 调用DesktopElectron 进程RemoteWebSocket 会话GitHub ActionsCI 环境检测1.3 状态管理采用双轨状态架构Bootstrap State (全局单例, ~1758行)├── 模块级 getter/setter├── 会话生命周期管理├── Feature Flag 状态└── 全局配置AppState Store (不可变状态, ~50字段)├── DeepImmutableT 类型约束├── 函数式更新 setAppState(prev ({...prev, ...}))├── 选择器模式 (selectors)└── 按 Agent 隔离 (每个 subagent 独立副本)二、Agent Loop流式驱动的核心循环Agent Loop 是 Claude Code 的心脏采用async generator模式实现流式处理。2.1 Agent Loop 流程图2.2 核心实现src/query.ts(~1729行) 中的query()函数是一个async generatorexport async function* query(params: QueryParams): AsyncGenerator StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, Terminal { const consumedCommandUuids: string[] [] const terminal yield* queryLoop(params, consumedCommandUuids) // 完成后通知命令生命周期 for (const uuid of consumedCommandUuids) { notifyCommandLifecycle(uuid, completed) } return terminal}关键设计特性实现说明状态管理State对象跨迭代携带messages, toolUseContext, autoCompactTracking 等Token 预算createBudgetTracker()自动续接500k 自动继续错误恢复MAX_OUTPUT_TOKENS_RECOVERY_LIMIT 3最多 3 次重试Thinking 规则严格排序要求thinking/redacted_thinking 块必须保留在 trajectory 中命令队列processQueueIfReady()用户命令在 turn 之间处理2.3 错误恢复机制API 调用失败├── Prompt Too Long│ └── auto-compact / history snip / context collapse├── Max Output Tokens│ └── 重试 (最多3次) → 增加 max_tokens├── API Error│ └── 指数退避重试└── Fallback Model └── 切换到备用模型2.4 QueryEngine 封装src/QueryEngine.ts为 SDK/无头场景提供类封装class QueryEngine { async *submitMessage(): AsyncGeneratorSDKMessage { // 消息变异 → 转录记录 → 使用追踪 → 权限拒绝追踪 → 结构化输出 } async ask(): PromiseSDKMessage { // 一次性 prompt 执行的便捷包装 }}三、Context 系统上下文的全生命周期管理3.1 Context 架构图3.2 System Context 构建// src/context.ts - 带 memoizationgetSystemContext() // Git 状态、分支信息、最近提交getUserContext() // CLAUDE.md 内容、当前日期缓存失效策略可选的 system prompt injectionant-only 调试场景。3.3 上下文压缩策略策略触发条件实现Auto Compact接近上下文窗口限制自动压缩历史消息History SnipFeature-gated消息级裁剪Context CollapseFeature-gated激进上下文缩减Reactive Compact按需触发上下文压力驱动3.4 ToolUseContext工具调用的丰富上下文每个工具调用都会收到一个包含 ~15 类信息的上下文对象ToolUseContext├── options: { tools, commands, mcpClients, model, thinking }├── getAppState / setAppState├── abortController├── fileStateCache (LRU 缓存每 agent 独立)├── messages: Message[]├── agentId / agentType├── permissionContext├── denialTracking├── notificationHandlers└── promptRequestFactory四、Tool 调用机制43 个工具的编排艺术4.1 Tool 接口设计// src/Tool.ts - 泛型 Tool 接口 (~40个属性/方法)interface ToolInput, Output, Progress { // 核心方法 call(input: Input, context: ToolUseContext): PromiseOutput description(): string prompt(): string // 安全检查 isReadOnly(): boolean isDestructive(): boolean isConcurrencySafe(input: Input): boolean // 权限 checkPermissions(input, context): PermissionResult toAutoClassifierInput(): object // 渲染 renderToolUseMessage(): ReactElement renderToolResultMessage(): ReactElement renderToolUseProgressMessage(): ReactElement // 验证 validateInput(input): ValidationResult isEnabled(context): boolean}4.2 Tool 注册与过滤Tool 注册与过滤流程4.3 工具分类 (43 个)类别工具数量核心Bash, FileRead, FileEdit, FileWrite, Glob, Grep6网络WebSearch, WebFetch2任务管理TaskCreate, TaskGet, TaskUpdate, TaskList, TaskStop, TaskOutput6AgentAgentTool, TeamCreate, TeamDelete, SendMessage4MCPMCPTool, ListMcpResources, ReadMcpResource, McpAuth4规划EnterPlanMode, ExitPlanModeV2, TodoWrite3特殊SkillTool, ConfigTool, LSPTool, WorkflowTool, ScheduleCron5特性门控REPLTool, SleepTool, PushNotification, WebBrowser, SnipTool5其他NotebookEdit, BriefTool, Testing, Tungsten, AskUserQuestion 等84.4 工具编排读写分离的并发策略// src/services/tools/toolOrchestration.ts// 分区连续只读工具并发写入工具串行function partitionToolCalls(toolUses: ToolUseBlock[]) { // 将连续的 isConcurrencySafe 工具分组为并发批次 // 遇到非安全工具则独立为串行执行}async function runTools() { // 1. partitionToolCalls() - 分区 // 2. 并发组 → runToolsConcurrently() // 3. 串行组 → runToolsSerially() // 4. 最大并发度: CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY (默认 10)}并发控制策略工具调用列表├── [Read, Grep, Glob] → 并发执行 (只读组)├── [Edit] → 串行执行 (写入)├── [Read, Glob] → 并发执行 (只读组)└── [Bash] → 串行执行 (潜在写入)4.5 Tool Builder 模式// buildTool(def) 工厂函数 - 提供安全默认值buildTool({ name: MyTool, call: async (input, ctx) { ... }, // 以下方法有安全默认值 (fail-closed) // isEnabled: () true // isConcurrencySafe: () false ← 默认不安全 // isReadOnly: () false // isDestructive: () false})五、Memory 管理从个人记忆到团队同步5.1 Memory 架构图5.2 MEMORY.md 系统// src/memdir/memdir.tsconst MAX_ENTRYPOINT_LINES 200 // 200 行上限const MAX_ENTRYPOINT_BYTES 25_000 // ~25KB 上限// 双重截断先行截断再字节截断function truncateEntrypointContent(raw: string): EntrypointTruncation { // 行截断 → 字节截断 → 警告标记}5.3 记忆检索流程用户输入└── memoryScan.ts ├── 扫描记忆目录 ├── 按相关性排序 ├── 加载相关文件 └── 过滤重复记忆附件 └── 注入到 User Context5.4 Agent 记忆继承父 Agent└── agentMemorySnapshot() ├── 捕获当前状态 └── 传递给子 Agent ├── 同步 Agent: 共享快照 ├── 异步 Agent: 独立快照 └── Fork Agent: 继承父级 system prompt5.5 团队记忆同步// src/services/teamMemorySync/index.ts // 团队记忆同步服务watcher.ts // 文件变更监听secretScanner.ts // 密钥检测teamMemSecretGuard.ts // 密钥防护teamMemPaths.ts // 团队记忆路径teamMemPrompts.ts // 团队提示词安全特性团队记忆写入前经过密钥扫描防止敏感信息泄露。5.6 文件状态缓存// src/utils/fileStateCache.ts// LRU 缓存每个 agent 独立克隆// 异步 agent 有大小限制防止内存泄漏六、权限与安全五层决策引擎6.1 权限决策流程图6.2 权限模式 (6 种)模式行为适用场景default每次询问默认安全模式plan只读不允许编辑规划阶段acceptEdits自动允许编辑信任 Agent 的编辑能力bypassPermissions完全跳过权限检查完全信任dontAsk拒绝而不询问自动化场景autoML 分类器决策智能权限判断6.3 规则解析// permissionRuleParser.ts// 支持模式匹配如:// Bash(git *) → 允许所有 git 命令// Edit(src/**) → 允许编辑 src 目录下的文件// Bash(rm -rf *) → 拒绝危险删除操作6.4 拒绝追踪与降级// denialTracking.ts// 追踪连续拒绝次数// 超过阈值后降级为交互式询问const DENIAL_LIMITS { // 连续拒绝 N 次后 fallback}function shouldFallbackToPrompting(state: DenialTrackingState): boolean { // 连续拒绝过多 → 自动模式不可信 → 回退到用户确认}6.5 安全层权限系统├── Sandbox (macOS Seatbelt)│ └── sandbox-adapter.js├── Auto-mode Classifier│ ├── yoloClassifier.ts│ └── classifierDecision.ts├── Hook-based 权限检查│ ├── PreToolUse│ └── PostToolUse├── 密钥扫描│ └── teamMemSecretGuard.ts├── MDM Policy 限制│ └── 企业策略执行└── Remote Managed Settings └── 管理员配置控制七、多智能体系统Subagent / Team / Swarm / Coordinator7.1 多智能体架构全景7.2 Agent 类型对比类型阻塞父级共享 Abort执行方式适用场景Sync Agent✅✅阻塞父 turn需要立即结果的子任务Async Agent❌❌独立运行完成通知长时间运行的后台任务Background Agent初始阻塞 → 自动后台❌120s 后自动转后台超长时间任务Fork Agent✅✅缓存优化继承父 prompt需要 cache-identical prefix 的场景Built-in Agent视类型视类型预定义行为Explore/Plan/Verification7.3 AgentTool 实现// src/tools/AgentTool/AgentTool.tsx (~1400行)// src/tools/AgentTool/runAgent.ts (~973行)// 核心能力├── 子 Agent 生成├── 独立 query loop├── 工具池过滤 (deny rules)├── MCP 需求过滤├── Model 选择 (per-agent)├── Worktree 管理├── Agent 颜色管理├── 进度追踪├── 远程 Agent 支持└── Agent 元数据持久化7.4 Coordinator Mode// src/coordinator/coordinatorMode.ts// 通过 CLAUDE_CODE_COORDINATOR_MODE 环境变量启用// Worker 工具集 (受限)const ASYNC_AGENT_ALLOWED_TOOLS [ // 只允许基础工具]// Coordinator 专属工具const INTERNAL_WORKER_TOOLS new Set([ TEAM_CREATE_TOOL_NAME, TEAM_DELETE_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SYNTHETIC_OUTPUT_TOOL_NAME,])  ### 7.5 Agent Swarm plaintext src/utils/swarm/ (~18 文件)├── backends/│ ├── TmuxBackend.ts # Tmux 终端后端│ ├── ITermBackend.ts # iTerm2 终端后端│ └── InProcessBackend.ts # 进程内后端├── spawnInProcess.ts # 进程内 teammate 生成├── inProcessRunner.ts # 进程内执行器├── teammateInit.ts # Teammate 初始化├── teammateModel.ts # 每个 teammate 的模型选择├── teammateLayoutManager.ts # 终端面板布局├── permissionSync.ts (~928行) # 跨 agent 权限协调├── leaderPermissionBridge.ts # Leader 中介权限解析├── teamHelpers.ts # 团队文件操作└── reconnection.ts # 团队重连逻辑7.6 Swarm 权限同步 (Mailbox 模式)7.7 四种模式对比维度SubagentCoordinatorSwarmTeam复杂度低中高中高通信直接调用SendMessageMailboxTeam 文件权限继承/独立Coordinator 代理Leader 桥接共享终端共享共享独立面板独立面板适用子任务委托多 worker 编排并行探索团队协作后端进程内进程内Tmux/iTerm2/InProcessTmux/iTerm2八、可观测性22 种 Hook 与全链路追踪8.1 Hook 系统架构8.2 22 种 Hook 类型类别Hook 类型触发时机生命周期SessionStart会话开始SessionEnd会话结束Stop正常停止StopFailure异常停止工具PreToolUse工具执行前PostToolUse工具执行后PostToolUseFailure工具执行失败AgentSubagentStart子 Agent 启动SubagentStop子 Agent 停止上下文PreCompact上下文压缩前PostCompact上下文压缩后CwdChanged工作目录变更FileChanged文件变更权限PermissionDenied权限被拒绝PermissionRequest权限请求自定义UserPromptSubmit用户 prompt 提交前TaskCreated任务创建TaskCompleted任务完成ElicitationMCP 诱导请求ConfigChange配置变更InstructionsLoaded指令加载完成TeammateIdleTeammate 空闲8.3 Hook 执行模型// src/utils/hooks.ts (~5022行)// Hook 作为子进程执行const TOOL_HOOK_EXECUTION_TIMEOUT_MS 10 * 60 * 1000 // 10 分钟const SESSION_END_HOOK_TIMEOUT_MS_DEFAULT 1500 // 1.5 秒// 异步 Hook 注册表class AsyncHookRegistry { // 追踪待完成的异步 Hook}// Hook 执行流程executeHook(hookEvent, input) { // 1. 匹配 Hook (配置 frontmatter plugin session) // 2. 构建输入 JSON // 3. 生成子进程 // 4. 解析输出 (同步/异步) // 5. 处理响应 (消息注入/权限更新/...)}8.4 遥测与分析src/services/analytics/├── index.ts // 核心 analytics, logEvent()├── sink.ts // 事件 sink 管理├── sinkKillswitch.ts // sink 熔断├── datadog.ts // Datadog 集成├── growthbook.ts // Feature Flag 系统 (Statsig/GrowthBook)├── firstPartyEventLogger.ts // 第一方事件└── firstPartyEventLoggingExporter.ts // 事件导出8.5 追踪系统// OpenTelemetry Session TracingstartHookSpan(hookName) // Hook span 开始endHookSpan(span) // Hook span 结束// Perfetto Tracing (Agent 层级可视化)// 可视化 Agent 父子关系、工具调用链、时间线8.6 成本追踪// src/cost-tracker.tsgetModelUsage() // 模型使用统计getTotalCost() // 总成本 (USD)getTotalAPIDuration() // API 总耗时九、调度系统Cron、队列与 Loop 技能9.1 调度系统9.2 Cron 调度// src/tools/ScheduleCronTool/// 间隔解析: Ns, Nm, Nh, Nd → cron 表达式// 自动过期: DEFAULT_MAX_AGE_DAYS// 支持的间隔格式every 5 minutes → */5 * * * *every 2 hours → 0 */2 * * *every 3 days → 0 0 */3 * *9.3 Loop 技能// src/skills/bundled/loop.ts// /loop 命令 - 用户友好的循环任务调度// 解析自然语言间隔// 转换为 cron 表达式// 通过 CronCreateTool 调度9.4 消息队列// src/utils/queueProcessor.ts// src/utils/messageQueueManager.ts// 队列能力├── 用户 prompt 排队├── 任务通知排队├── Bash 命令排队├── 优先级队列├── Slash 命令检测与路由├── 非 slash 命令批量处理 (相同 mode)└── Agent 路由 (通过 agentId 寻址)队列处理策略消息队列├── 非 slash 命令 相同 mode → 批量处理├── Slash 命令 → 逐个处理├── Bash 命令 → 逐个处理└── 带 agentId → 路由到指定 Agent十、复用模式10 种架构模式总结10.1 模式一览表#模式应用场景核心文件1Async Generatorquery/submitMessage/runAgent/runTools 统一流式query.ts, QueryEngine.ts2Feature Flag编译时死代码消除bun:bundle, feature()3Context InjectionToolUseContext 统一注入Tool.ts4Tool Builder工厂 安全默认值buildTool(def)5Immutable StateDeepImmutable 函数式更新AppStateStore.ts6Mailbox跨 Agent 协调 (lockfile)permissionSync.ts7Cache-AwarePrompt cache content-hash多处8Lazy Schema打破循环依赖lazySchema()9Dead Code Elimination条件导入 用户类型分支require() 动态加载10Hook Event生命周期事件发射hooks.ts10.2 模式详解模式 1: Async Generator// 统一的流式处理模式async function* query(): AsyncGeneratorEvent, Terminal { ... }async function* submitMessage(): AsyncGeneratorSDKMessage { ... }async function* runAgent(): AsyncGeneratorMessage { ... }async function* runTools(): AsyncGeneratorMessageUpdate { ... }优势天然支持流式响应、增量处理、中间状态观察。模式 2: Feature Flag// 编译时死代码消除const reactiveCompact feature(REACTIVE_COMPACT) ? require(./reactiveCompact.js) : null// Schema 门控...(feature(TRANSCRIPT_CLASSIFIER) ? { auto: auto } : {})模式 3: Context Injection// 每个 tool 接收统一的 ToolUseContextcall(input: Input, context: ToolUseContext): PromiseOutput// Subagent 创建独立上下文createSubagentContext(parent, { shareAppState: true })模式 4: Tool BuilderbuildTool({ name: MyTool, call: async (input, ctx) { ... }, // 安全默认值 (fail-closed) // isConcurrencySafe: () false ← 默认不安全 // isReadOnly: () false})模式 5: Immutable Statetype AppState DeepImmutable{ messages: Message[] tools: Tools // ... 50 字段}// 函数式更新setAppState(prev ({ ...prev, messages: [...prev.messages, newMsg] }))模式 6: Mailbox文件级 Mailbox├── 写入: 创建 .json 文件到 mailbox 目录├── 读取: 扫描目录 解析 JSON├── 锁: lockfile 保证并发安全└── 清理: 处理后删除模式 7: Cache-Aware// Prompt cache break 检测// Content-hash 临时文件路径 (避免 UUID 导致的 cache miss)// Fork Agent 继承父级 system prompt (cache-identical prefix)// Turn 开始时冻结渲染的 system prompt十一、关键文件索引组件核心文件行数入口src/main.tsx~3000Agent Loopsrc/query.ts1729Query Enginesrc/QueryEngine.ts1295Tool 接口src/Tool.ts792Tool 注册src/tools.ts389Tool 编排src/services/tools/toolOrchestration.ts188权限引擎src/utils/permissions/permissions.ts1486权限模式src/utils/permissions/PermissionMode.ts141Hookssrc/utils/hooks.ts5022Agent Toolsrc/tools/AgentTool/AgentTool.tsx~1400Run Agentsrc/tools/AgentTool/runAgent.ts~973Coordinatorsrc/coordinator/coordinatorMode.ts369Swarm 权限src/utils/swarm/permissionSync.ts928Memorysrc/memdir/memdir.ts507Statesrc/bootstrap/state.ts~1758AppStatesrc/state/AppStateStore.ts569十二、总结Claude Code 的架构设计体现了几个核心理念流式优先从 Agent Loop 到 Tool 执行全部采用 async generator天然支持流式处理和增量渲染。安全默认Tool Builder 的 fail-closed 设计、权限系统的五层决策、Sandbox 隔离处处体现安全优先。不可变状态DeepImmutable 类型约束 函数式更新避免状态突变带来的难以追踪的 bug。模块化编排43 个工具通过统一的接口和编排器协同工作读写分离的并发策略兼顾了性能和安全。多智能体层次从简单的 Subagent 到复杂的 Swarm提供了不同复杂度的多智能体方案适应不同场景需求。可观测性内建22 种 Hook 类型 OpenTelemetry 追踪 Perfetto 可视化让系统行为完全可观测。Feature Flag 驱动通过bun:bundle的 feature() 实现编译时死代码消除同时支持灰度发布和 A/B 测试。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】
Claude Code 源码解读：包含Agent Loop、Context 管理、Tool 调用、Memory、Muti Agent等模块
基于对 Claude Code 源码的系统性分析本文从 11 个维度拆解其架构设计涵盖 Agent Loop、Context 管理、Tool 调用、Memory、权限安全、多智能体协作、可观测性等核心模块。一、整体架构Claude Code 是一个基于 TypeScript 的终端 Agent 应用构建在 Bun 运行时之上采用 React Ink 渲染 TUI。其架构设计遵循分层解耦、流式驱动、不可变状态三大原则。1.1 架构全景图1.2 入口架构src/main.tsx (~3000行)├── 参数解析 (argparse)├── Feature Flag 门控 (feature() from bun:bundle)├── 环境检测 (USER_TYPE, CLAUDE_CODE_ENTRYPOINT)├── 初始化 (迁移、设置、插件)├── 交互式 REPL 模式└── 无头模式 (-p/--print)多客户端支持通过入口点检测实现客户端检测方式CLI直接执行SDKCLAUDE_CODE_ENTRYPOINTsdkVSCodeExtension 调用DesktopElectron 进程RemoteWebSocket 会话GitHub ActionsCI 环境检测1.3 状态管理采用双轨状态架构Bootstrap State (全局单例, ~1758行)├── 模块级 getter/setter├── 会话生命周期管理├── Feature Flag 状态└── 全局配置AppState Store (不可变状态, ~50字段)├── DeepImmutableT 类型约束├── 函数式更新 setAppState(prev ({...prev, ...}))├── 选择器模式 (selectors)└── 按 Agent 隔离 (每个 subagent 独立副本)二、Agent Loop流式驱动的核心循环Agent Loop 是 Claude Code 的心脏采用async generator模式实现流式处理。2.1 Agent Loop 流程图2.2 核心实现src/query.ts(~1729行) 中的query()函数是一个async generatorexport async function* query(params: QueryParams): AsyncGenerator StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, Terminal { const consumedCommandUuids: string[] [] const terminal yield* queryLoop(params, consumedCommandUuids) // 完成后通知命令生命周期 for (const uuid of consumedCommandUuids) { notifyCommandLifecycle(uuid, completed) } return terminal}关键设计特性实现说明状态管理State对象跨迭代携带messages, toolUseContext, autoCompactTracking 等Token 预算createBudgetTracker()自动续接500k 自动继续错误恢复MAX_OUTPUT_TOKENS_RECOVERY_LIMIT 3最多 3 次重试Thinking 规则严格排序要求thinking/redacted_thinking 块必须保留在 trajectory 中命令队列processQueueIfReady()用户命令在 turn 之间处理2.3 错误恢复机制API 调用失败├── Prompt Too Long│ └── auto-compact / history snip / context collapse├── Max Output Tokens│ └── 重试 (最多3次) → 增加 max_tokens├── API Error│ └── 指数退避重试└── Fallback Model └── 切换到备用模型2.4 QueryEngine 封装src/QueryEngine.ts为 SDK/无头场景提供类封装class QueryEngine { async *submitMessage(): AsyncGeneratorSDKMessage { // 消息变异 → 转录记录 → 使用追踪 → 权限拒绝追踪 → 结构化输出 } async ask(): PromiseSDKMessage { // 一次性 prompt 执行的便捷包装 }}三、Context 系统上下文的全生命周期管理3.1 Context 架构图3.2 System Context 构建// src/context.ts - 带 memoizationgetSystemContext() // Git 状态、分支信息、最近提交getUserContext() // CLAUDE.md 内容、当前日期缓存失效策略可选的 system prompt injectionant-only 调试场景。3.3 上下文压缩策略策略触发条件实现Auto Compact接近上下文窗口限制自动压缩历史消息History SnipFeature-gated消息级裁剪Context CollapseFeature-gated激进上下文缩减Reactive Compact按需触发上下文压力驱动3.4 ToolUseContext工具调用的丰富上下文每个工具调用都会收到一个包含 ~15 类信息的上下文对象ToolUseContext├── options: { tools, commands, mcpClients, model, thinking }├── getAppState / setAppState├── abortController├── fileStateCache (LRU 缓存每 agent 独立)├── messages: Message[]├── agentId / agentType├── permissionContext├── denialTracking├── notificationHandlers└── promptRequestFactory四、Tool 调用机制43 个工具的编排艺术4.1 Tool 接口设计// src/Tool.ts - 泛型 Tool 接口 (~40个属性/方法)interface ToolInput, Output, Progress { // 核心方法 call(input: Input, context: ToolUseContext): PromiseOutput description(): string prompt(): string // 安全检查 isReadOnly(): boolean isDestructive(): boolean isConcurrencySafe(input: Input): boolean // 权限 checkPermissions(input, context): PermissionResult toAutoClassifierInput(): object // 渲染 renderToolUseMessage(): ReactElement renderToolResultMessage(): ReactElement renderToolUseProgressMessage(): ReactElement // 验证 validateInput(input): ValidationResult isEnabled(context): boolean}4.2 Tool 注册与过滤Tool 注册与过滤流程4.3 工具分类 (43 个)类别工具数量核心Bash, FileRead, FileEdit, FileWrite, Glob, Grep6网络WebSearch, WebFetch2任务管理TaskCreate, TaskGet, TaskUpdate, TaskList, TaskStop, TaskOutput6AgentAgentTool, TeamCreate, TeamDelete, SendMessage4MCPMCPTool, ListMcpResources, ReadMcpResource, McpAuth4规划EnterPlanMode, ExitPlanModeV2, TodoWrite3特殊SkillTool, ConfigTool, LSPTool, WorkflowTool, ScheduleCron5特性门控REPLTool, SleepTool, PushNotification, WebBrowser, SnipTool5其他NotebookEdit, BriefTool, Testing, Tungsten, AskUserQuestion 等84.4 工具编排读写分离的并发策略// src/services/tools/toolOrchestration.ts// 分区连续只读工具并发写入工具串行function partitionToolCalls(toolUses: ToolUseBlock[]) { // 将连续的 isConcurrencySafe 工具分组为并发批次 // 遇到非安全工具则独立为串行执行}async function runTools() { // 1. partitionToolCalls() - 分区 // 2. 并发组 → runToolsConcurrently() // 3. 串行组 → runToolsSerially() // 4. 最大并发度: CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY (默认 10)}并发控制策略工具调用列表├── [Read, Grep, Glob] → 并发执行 (只读组)├── [Edit] → 串行执行 (写入)├── [Read, Glob] → 并发执行 (只读组)└── [Bash] → 串行执行 (潜在写入)4.5 Tool Builder 模式// buildTool(def) 工厂函数 - 提供安全默认值buildTool({ name: MyTool, call: async (input, ctx) { ... }, // 以下方法有安全默认值 (fail-closed) // isEnabled: () true // isConcurrencySafe: () false ← 默认不安全 // isReadOnly: () false // isDestructive: () false})五、Memory 管理从个人记忆到团队同步5.1 Memory 架构图5.2 MEMORY.md 系统// src/memdir/memdir.tsconst MAX_ENTRYPOINT_LINES 200 // 200 行上限const MAX_ENTRYPOINT_BYTES 25_000 // ~25KB 上限// 双重截断先行截断再字节截断function truncateEntrypointContent(raw: string): EntrypointTruncation { // 行截断 → 字节截断 → 警告标记}5.3 记忆检索流程用户输入└── memoryScan.ts ├── 扫描记忆目录 ├── 按相关性排序 ├── 加载相关文件 └── 过滤重复记忆附件 └── 注入到 User Context5.4 Agent 记忆继承父 Agent└── agentMemorySnapshot() ├── 捕获当前状态 └── 传递给子 Agent ├── 同步 Agent: 共享快照 ├── 异步 Agent: 独立快照 └── Fork Agent: 继承父级 system prompt5.5 团队记忆同步// src/services/teamMemorySync/index.ts // 团队记忆同步服务watcher.ts // 文件变更监听secretScanner.ts // 密钥检测teamMemSecretGuard.ts // 密钥防护teamMemPaths.ts // 团队记忆路径teamMemPrompts.ts // 团队提示词安全特性团队记忆写入前经过密钥扫描防止敏感信息泄露。5.6 文件状态缓存// src/utils/fileStateCache.ts// LRU 缓存每个 agent 独立克隆// 异步 agent 有大小限制防止内存泄漏六、权限与安全五层决策引擎6.1 权限决策流程图6.2 权限模式 (6 种)模式行为适用场景default每次询问默认安全模式plan只读不允许编辑规划阶段acceptEdits自动允许编辑信任 Agent 的编辑能力bypassPermissions完全跳过权限检查完全信任dontAsk拒绝而不询问自动化场景autoML 分类器决策智能权限判断6.3 规则解析// permissionRuleParser.ts// 支持模式匹配如:// Bash(git *) → 允许所有 git 命令// Edit(src/**) → 允许编辑 src 目录下的文件// Bash(rm -rf *) → 拒绝危险删除操作6.4 拒绝追踪与降级// denialTracking.ts// 追踪连续拒绝次数// 超过阈值后降级为交互式询问const DENIAL_LIMITS { // 连续拒绝 N 次后 fallback}function shouldFallbackToPrompting(state: DenialTrackingState): boolean { // 连续拒绝过多 → 自动模式不可信 → 回退到用户确认}6.5 安全层权限系统├── Sandbox (macOS Seatbelt)│ └── sandbox-adapter.js├── Auto-mode Classifier│ ├── yoloClassifier.ts│ └── classifierDecision.ts├── Hook-based 权限检查│ ├── PreToolUse│ └── PostToolUse├── 密钥扫描│ └── teamMemSecretGuard.ts├── MDM Policy 限制│ └── 企业策略执行└── Remote Managed Settings └── 管理员配置控制七、多智能体系统Subagent / Team / Swarm / Coordinator7.1 多智能体架构全景7.2 Agent 类型对比类型阻塞父级共享 Abort执行方式适用场景Sync Agent✅✅阻塞父 turn需要立即结果的子任务Async Agent❌❌独立运行完成通知长时间运行的后台任务Background Agent初始阻塞 → 自动后台❌120s 后自动转后台超长时间任务Fork Agent✅✅缓存优化继承父 prompt需要 cache-identical prefix 的场景Built-in Agent视类型视类型预定义行为Explore/Plan/Verification7.3 AgentTool 实现// src/tools/AgentTool/AgentTool.tsx (~1400行)// src/tools/AgentTool/runAgent.ts (~973行)// 核心能力├── 子 Agent 生成├── 独立 query loop├── 工具池过滤 (deny rules)├── MCP 需求过滤├── Model 选择 (per-agent)├── Worktree 管理├── Agent 颜色管理├── 进度追踪├── 远程 Agent 支持└── Agent 元数据持久化7.4 Coordinator Mode// src/coordinator/coordinatorMode.ts// 通过 CLAUDE_CODE_COORDINATOR_MODE 环境变量启用// Worker 工具集 (受限)const ASYNC_AGENT_ALLOWED_TOOLS [ // 只允许基础工具]// Coordinator 专属工具const INTERNAL_WORKER_TOOLS new Set([ TEAM_CREATE_TOOL_NAME, TEAM_DELETE_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SYNTHETIC_OUTPUT_TOOL_NAME,])  ### 7.5 Agent Swarm plaintext src/utils/swarm/ (~18 文件)├── backends/│ ├── TmuxBackend.ts # Tmux 终端后端│ ├── ITermBackend.ts # iTerm2 终端后端│ └── InProcessBackend.ts # 进程内后端├── spawnInProcess.ts # 进程内 teammate 生成├── inProcessRunner.ts # 进程内执行器├── teammateInit.ts # Teammate 初始化├── teammateModel.ts # 每个 teammate 的模型选择├── teammateLayoutManager.ts # 终端面板布局├── permissionSync.ts (~928行) # 跨 agent 权限协调├── leaderPermissionBridge.ts # Leader 中介权限解析├── teamHelpers.ts # 团队文件操作└── reconnection.ts # 团队重连逻辑7.6 Swarm 权限同步 (Mailbox 模式)7.7 四种模式对比维度SubagentCoordinatorSwarmTeam复杂度低中高中高通信直接调用SendMessageMailboxTeam 文件权限继承/独立Coordinator 代理Leader 桥接共享终端共享共享独立面板独立面板适用子任务委托多 worker 编排并行探索团队协作后端进程内进程内Tmux/iTerm2/InProcessTmux/iTerm2八、可观测性22 种 Hook 与全链路追踪8.1 Hook 系统架构8.2 22 种 Hook 类型类别Hook 类型触发时机生命周期SessionStart会话开始SessionEnd会话结束Stop正常停止StopFailure异常停止工具PreToolUse工具执行前PostToolUse工具执行后PostToolUseFailure工具执行失败AgentSubagentStart子 Agent 启动SubagentStop子 Agent 停止上下文PreCompact上下文压缩前PostCompact上下文压缩后CwdChanged工作目录变更FileChanged文件变更权限PermissionDenied权限被拒绝PermissionRequest权限请求自定义UserPromptSubmit用户 prompt 提交前TaskCreated任务创建TaskCompleted任务完成ElicitationMCP 诱导请求ConfigChange配置变更InstructionsLoaded指令加载完成TeammateIdleTeammate 空闲8.3 Hook 执行模型// src/utils/hooks.ts (~5022行)// Hook 作为子进程执行const TOOL_HOOK_EXECUTION_TIMEOUT_MS 10 * 60 * 1000 // 10 分钟const SESSION_END_HOOK_TIMEOUT_MS_DEFAULT 1500 // 1.5 秒// 异步 Hook 注册表class AsyncHookRegistry { // 追踪待完成的异步 Hook}// Hook 执行流程executeHook(hookEvent, input) { // 1. 匹配 Hook (配置 frontmatter plugin session) // 2. 构建输入 JSON // 3. 生成子进程 // 4. 解析输出 (同步/异步) // 5. 处理响应 (消息注入/权限更新/...)}8.4 遥测与分析src/services/analytics/├── index.ts // 核心 analytics, logEvent()├── sink.ts // 事件 sink 管理├── sinkKillswitch.ts // sink 熔断├── datadog.ts // Datadog 集成├── growthbook.ts // Feature Flag 系统 (Statsig/GrowthBook)├── firstPartyEventLogger.ts // 第一方事件└── firstPartyEventLoggingExporter.ts // 事件导出8.5 追踪系统// OpenTelemetry Session TracingstartHookSpan(hookName) // Hook span 开始endHookSpan(span) // Hook span 结束// Perfetto Tracing (Agent 层级可视化)// 可视化 Agent 父子关系、工具调用链、时间线8.6 成本追踪// src/cost-tracker.tsgetModelUsage() // 模型使用统计getTotalCost() // 总成本 (USD)getTotalAPIDuration() // API 总耗时九、调度系统Cron、队列与 Loop 技能9.1 调度系统9.2 Cron 调度// src/tools/ScheduleCronTool/// 间隔解析: Ns, Nm, Nh, Nd → cron 表达式// 自动过期: DEFAULT_MAX_AGE_DAYS// 支持的间隔格式every 5 minutes → */5 * * * *every 2 hours → 0 */2 * * *every 3 days → 0 0 */3 * *9.3 Loop 技能// src/skills/bundled/loop.ts// /loop 命令 - 用户友好的循环任务调度// 解析自然语言间隔// 转换为 cron 表达式// 通过 CronCreateTool 调度9.4 消息队列// src/utils/queueProcessor.ts// src/utils/messageQueueManager.ts// 队列能力├── 用户 prompt 排队├── 任务通知排队├── Bash 命令排队├── 优先级队列├── Slash 命令检测与路由├── 非 slash 命令批量处理 (相同 mode)└── Agent 路由 (通过 agentId 寻址)队列处理策略消息队列├── 非 slash 命令 相同 mode → 批量处理├── Slash 命令 → 逐个处理├── Bash 命令 → 逐个处理└── 带 agentId → 路由到指定 Agent十、复用模式10 种架构模式总结10.1 模式一览表#模式应用场景核心文件1Async Generatorquery/submitMessage/runAgent/runTools 统一流式query.ts, QueryEngine.ts2Feature Flag编译时死代码消除bun:bundle, feature()3Context InjectionToolUseContext 统一注入Tool.ts4Tool Builder工厂 安全默认值buildTool(def)5Immutable StateDeepImmutable 函数式更新AppStateStore.ts6Mailbox跨 Agent 协调 (lockfile)permissionSync.ts7Cache-AwarePrompt cache content-hash多处8Lazy Schema打破循环依赖lazySchema()9Dead Code Elimination条件导入 用户类型分支require() 动态加载10Hook Event生命周期事件发射hooks.ts10.2 模式详解模式 1: Async Generator// 统一的流式处理模式async function* query(): AsyncGeneratorEvent, Terminal { ... }async function* submitMessage(): AsyncGeneratorSDKMessage { ... }async function* runAgent(): AsyncGeneratorMessage { ... }async function* runTools(): AsyncGeneratorMessageUpdate { ... }优势天然支持流式响应、增量处理、中间状态观察。模式 2: Feature Flag// 编译时死代码消除const reactiveCompact feature(REACTIVE_COMPACT) ? require(./reactiveCompact.js) : null// Schema 门控...(feature(TRANSCRIPT_CLASSIFIER) ? { auto: auto } : {})模式 3: Context Injection// 每个 tool 接收统一的 ToolUseContextcall(input: Input, context: ToolUseContext): PromiseOutput// Subagent 创建独立上下文createSubagentContext(parent, { shareAppState: true })模式 4: Tool BuilderbuildTool({ name: MyTool, call: async (input, ctx) { ... }, // 安全默认值 (fail-closed) // isConcurrencySafe: () false ← 默认不安全 // isReadOnly: () false})模式 5: Immutable Statetype AppState DeepImmutable{ messages: Message[] tools: Tools // ... 50 字段}// 函数式更新setAppState(prev ({ ...prev, messages: [...prev.messages, newMsg] }))模式 6: Mailbox文件级 Mailbox├── 写入: 创建 .json 文件到 mailbox 目录├── 读取: 扫描目录 解析 JSON├── 锁: lockfile 保证并发安全└── 清理: 处理后删除模式 7: Cache-Aware// Prompt cache break 检测// Content-hash 临时文件路径 (避免 UUID 导致的 cache miss)// Fork Agent 继承父级 system prompt (cache-identical prefix)// Turn 开始时冻结渲染的 system prompt十一、关键文件索引组件核心文件行数入口src/main.tsx~3000Agent Loopsrc/query.ts1729Query Enginesrc/QueryEngine.ts1295Tool 接口src/Tool.ts792Tool 注册src/tools.ts389Tool 编排src/services/tools/toolOrchestration.ts188权限引擎src/utils/permissions/permissions.ts1486权限模式src/utils/permissions/PermissionMode.ts141Hookssrc/utils/hooks.ts5022Agent Toolsrc/tools/AgentTool/AgentTool.tsx~1400Run Agentsrc/tools/AgentTool/runAgent.ts~973Coordinatorsrc/coordinator/coordinatorMode.ts369Swarm 权限src/utils/swarm/permissionSync.ts928Memorysrc/memdir/memdir.ts507Statesrc/bootstrap/state.ts~1758AppStatesrc/state/AppStateStore.ts569十二、总结Claude Code 的架构设计体现了几个核心理念流式优先从 Agent Loop 到 Tool 执行全部采用 async generator天然支持流式处理和增量渲染。安全默认Tool Builder 的 fail-closed 设计、权限系统的五层决策、Sandbox 隔离处处体现安全优先。不可变状态DeepImmutable 类型约束 函数式更新避免状态突变带来的难以追踪的 bug。模块化编排43 个工具通过统一的接口和编排器协同工作读写分离的并发策略兼顾了性能和安全。多智能体层次从简单的 Subagent 到复杂的 Swarm提供了不同复杂度的多智能体方案适应不同场景需求。可观测性内建22 种 Hook 类型 OpenTelemetry 追踪 Perfetto 可视化让系统行为完全可观测。Feature Flag 驱动通过bun:bundle的 feature() 实现编译时死代码消除同时支持灰度发布和 A/B 测试。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】
