从 51 万行源码看 AI Agent 架构：Claude Code 设计哲学拆解

你有没有想过一个 AI 编码 Agent凭什么敢直接操作你的文件系统、执行 shell 命令、甚至帮你 git commit它背后的架构到底长什么样才能做到既强大又不失控Anthropic 开源了 Claude Code 的完整源码51 万行 TypeScript。我花了两周时间通读核心模块今天把最有价值的架构设计提炼出来一次讲透。01 Claude Code 是什么不只是一个 CLI 工具Claude Code 是 Anthropic 官方推出的 AI 编码 Agent它不是一个简单的「命令行聊天工具」而是一个完整的 Agent 运行时。很多人第一次用 Claude Code以为它只是在终端里跟 AI 对话。但实际上它的架构复杂度远超你的想象51 万行 TypeScript 源码完整的 Agent Loop 驱动20 内置工具文件读写、Shell 执行、搜索、Git 操作等多层权限系统上下文窗口智能管理项目级配置CLAUDE.md加载机制// Claude Code 的核心入口结构简化interfaceClaudeCodeRuntimeagentLoopAgentLoop// Agent 循环引擎toolRegistryToolRegistry// 工具注册中心permissionSystemPermissionManager// 权限管理contextManagerContextManager// 上下文管理configLoaderConfigLoader// 配置加载器CLAUDE.md// 启动流程asyncfunctionmainconstawaitinitializeRuntimeconstawaitconfigLoaderloadHierarchicalconstawaittoolRegistryregisterAll// 进入 Agent LoopawaitagentLooprunpermissionspermissionSystemcontextcontextManager跟 Cursor我们第 19 篇拆解过的本质区别在于Cursor 是 IDE-firstAgent 能力嵌入编辑器Claude Code 是 Agent-first编码能力嵌入 Agent 运行时。这个设计选择决定了后续所有架构决策的走向。02 Agent Loop感知-决策-行动的核心循环Claude Code 的心脏是一个经典的 Agent Loop遵循「感知 → 决策 → 行动 → 观察」四步循环直到任务完成或用户中断。这个循环不是什么新概念但 Claude Code 的实现细节非常考究┌─────────────────────────────────────────────────┐ │ Agent Loop │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 感知 │───▶│ 决策 │───▶│ 行动 │ │ │ │ Perceive │ │ Decide │ │ Act │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ ▲ │ │ │ │ ┌──────────┐ │ │ │ └──────────│ 观察 │◀────────┘ │ │ │ Observe │ │ │ └──────────┘ │ │ │ │ 终止条件 │ │ 1. LLM 返回 end_turn不再调用工具 │ │ 2. 用户手动中断CtrlC │ │ 3. 达到最大迭代次数 │ │ 4. 上下文窗口耗尽 │ └─────────────────────────────────────────────────┘源码中的核心逻辑可以简化为// Agent Loop 核心实现简化自源码asyncfunctionagentLoop messages: Message[], tools: Tool[], maxIterations: number 200PromiseMessagelet0while// 1. 感知组装当前上下文constawaitbuildContext// 2. 决策调用 LLM 获取下一步动作constawaitcallLLMsystemsystemPromptmessagesmessagestoolsmapt toSchema// 3. 检查是否需要执行工具constextractToolCallsiflength0// LLM 决定不再调用工具循环结束pushroleassistantcontentcontentbreak// 4. 行动逐个执行工具调用forconstof// 权限检查关键constawaitcheckPermissionifpushcreateDeniedResultcontinue// 执行工具并收集结果constawaitexecuteToolpushcreateToolResult// 5. 观察工具结果已加入 messages回到循环顶部return✅正确理解Agent Loop 的每一轮都是一次完整的 LLM 调用LLM 根据历史消息和工具结果自主决定下一步❌常见误解以为 Agent Loop 是预设的流水线按固定步骤执行这里有一个关键设计循环的终止不是靠计数器而是靠 LLM 自己判断任务是否完成。当 LLM 认为不需要再调用任何工具时它会直接返回文本响应循环自然结束。这就是 Agent 的「自主性」所在。03 工具系统注册、Schema、沙箱执行Claude Code 的工具系统是一个标准化的注册-发现-执行框架每个工具都是一个独立模块通过统一的 Schema 描述自己的能力和参数。源码中有 20 多个内置工具包括工具名能力风险等级Read读取文件内容低Write写入/创建文件中Edit精确编辑文件字符串替换中Bash执行 Shell 命令高Glob文件名模式匹配低Grep内容搜索低WebFetch抓取网页内容中NotebookEdit编辑 Jupyter Notebook中每个工具的注册结构如下// 工具定义接口interfaceToolDefinitionnamestringdescriptionstring// JSON Schema 定义参数inputSchemaJSON// 是否需要用户确认requiresPermissionboolean// 工具的执行函数execute(params: Recordstring, unknown) PromiseToolResult// 工具能力的元数据metadatareadOnlyboolean// 是否只读needsSandboxboolean// 是否需要沙箱riskLevellowmediumhigh// 以 Bash 工具为例constbashToolToolDefinitionnameBashdescriptionExecutes a given bash command and returns its output.inputSchematypeobjectrequiredcommandpropertiescommandtypestringdescriptionThe command to executetimeouttypenumberdescriptionTimeout in millisecondsrequiresPermissiontrueexecuteasyncconst120000// 沙箱执行 超时控制returnawaitsandboxedExecmetadatareadOnlyfalseneedsSandboxtrueriskLevelhigh✅好的设计每个工具自描述风险等级和权限需求权限系统可以据此做分级控制❌反模式把所有工具逻辑塞进一个巨大的 switch-case无法扩展也无法独立测试工具的沙箱执行也非常有讲究。高风险工具如 Bash在 macOS 上使用sandbox-exec进行文件系统隔离在 Linux 上使用类似的沙箱机制┌──────────────────────────────────────┐ │ Tool Execution │ │ │ │ 用户请求 │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 权限检查 │──── 拒绝 ──▶ 返回错误│ │ └─────┬───────┘ │ │ │ 允许 │ │ ▼ │ │ ┌─────────────┐ │ │ │ 参数校验 │──── 失败 ──▶ 返回错误│ │ └─────┬───────┘ │ │ │ 通过 │ │ ▼ │ │ ┌─────────────┐ │ │ │ 沙箱执行 │ ← 文件系统隔离 │ │ │ 超时控制 │ ← 最大执行时间 │ │ └─────┬───────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 结果格式化 │ │ │ └─────────────┘ │ └──────────────────────────────────────┘04 上下文管理Context Window 的生存之道上下文窗口是 AI Agent 最稀缺的资源。Claude Code 采用了「压缩 摘要 智能裁剪」三级策略来管理上下文确保关键信息不丢失。这是很多人忽略的地方。Claude 的上下文窗口虽然有 200K tokens但在一个复杂的编码任务中几轮工具调用下来上下文就可能爆掉。Claude Code 是怎么处理的// 上下文管理策略interfaceContextManager// 当前上下文使用量getTokenUsageusednumbertotalnumberrationumber// 三级压缩策略compressmessagesMessagePromiseMessage// 策略一工具结果裁剪functiontruncateToolResultresult: ToolResult, maxTokens: numberToolResultifestimateTokenscontentreturn// 保留头尾截断中间constcontentslice00.4constcontentslice0.4returncontent${head}\n\n... [truncated ${estimateTokens(result.content) - maxTokens} tokens] ...\n\n${tail}// 策略二历史消息摘要asyncfunctionsummarizeOldMessages messages: Message[], threshold: numberPromiseMessageifestimateTokensreturn// 保留最近 N 轮对话对更早的对话生成摘要const10constsliceconstslice0constawaitgenerateSummaryreturnrolesystemcontent[Previous conversation summary]: ${summary}// 策略三智能文件缓存// 同一文件多次读取时后续读取引用之前的结果而非重复加入上下文functiondeduplicateFileReadsmessages: Message[]MessageconstnewMapstringnumber// filePath - messageIndexreturnmap(msg, idx) iftoolNameReadfilePathifhasfilePathreturncontent[File already read at message #${fileCache.get(msg.filePath)}]setfilePathreturn✅Claude Code 的做法分层压缩优先保留最近对话和关键工具结果❌粗暴做法直接截断最早的消息可能丢失重要的任务上下文上下文窗口管理策略 Token 使用量 0% 70% 85% 100% ├─────────────────────┼─────────────┼───────────┤ │ 正常运行 │ 启动裁剪 │ 启动摘要 │ │ 无压缩 │ 截断大结果 │ 压缩历史 │ └─────────────────────┴─────────────┴───────────┘ ▲ │ 超过 95% 时 强制丢弃最早消息05 CLAUDE.md项目级 AI 配置的分层加载CLAUDE.md 是 Claude Code 最巧妙的设计之一通过 Markdown 文件让 AI 理解项目约定且支持全局 → 项目 → 目录三级覆盖。这个机制解决了一个核心痛点每次跟 AI 对话都要重复说明「我们项目用 ESLint」「提交信息用 Conventional Commits」「不要用 any 类型」。有了 CLAUDE.md这些约定写一次永久生效。// CLAUDE.md 加载机制interfaceClaudeConfigsourceglobalprojectdirectorypathstringcontentstringprioritynumber// 数字越大优先级越高asyncfunctionloadClaudeConfigscwd: stringPromiseClaudeConfigconstconfigsClaudeConfig// 1. 全局配置~/.claude/CLAUDE.md优先级最低constjoinhomedir.claudeCLAUDE.mdifawaitfileExistspushsourceglobalpathcontentawaitreadFilepriority0// 2. 项目根目录配置project-root/CLAUDE.mdconstawaitfindProjectRootconstjoinCLAUDE.mdifawaitfileExistspushsourceprojectpathcontentawaitreadFilepriority10// 3. 当前目录配置cwd/CLAUDE.md优先级最高constjoinCLAUDE.mdifawaitfileExistspushsourcedirectorypathcontentawaitreadFilepriority20// 按优先级排序高优先级的配置在后面覆盖前面的returnsort(a, b) prioritypriority// 合并到 System PromptfunctionbuildSystemPromptconfigs: ClaudeConfig[]stringconstmapc # Instructions from ${c.source} config (${c.path}):\n${c.content}returnjoin\n\nCLAUDE.md 加载优先级 ~/.claude/CLAUDE.md ← 全局默认你的个人习惯 │ ▼ 被覆盖 project/CLAUDE.md ← 项目级团队约定提交到 Git │ ▼ 被覆盖 project/src/api/CLAUDE.md ← 目录级特定模块的规则✅推荐做法项目根目录的 CLAUDE.md 提交到 Git团队共享全局的放个人偏好❌不推荐把所有规则都塞在全局配置里导致不同项目之间规则冲突06 Permission 系统为什么 AI Agent 必须有权限管理Permission 系统是 Claude Code 安全架构的基石。核心原则很简单只读操作自动放行写操作必须用户确认高危操作需要明确授权。想象一下如果 AI Agent 可以不经确认就执行rm -rf /那后果不堪设想。Claude Code 的权限系统设计了三个层级// 权限等级定义enumPermissionLevel// 自动允许读取文件、搜索、glob 等只读操作AUTO_ALLOWauto_allow// 需要确认写文件、编辑文件等修改操作REQUIRES_CONFIRMATIONrequires_confirmation// 严格模式执行 Shell 命令、网络请求等高危操作STRICTstrict// 权限规则引擎classPermissionManagerprivaterulesPermissionRuleprivatesessionAllowListSetstringnewSetasynccheckPermissiontoolCallToolCallPromisePermissionResultconsttool// 1. 只读工具直接放行ifmetadatareadOnlyreturnallowedtruereasonread-only operation// 2. 检查用户是否在本次会话中已授权过同类操作constthismatchSessionRuleifreturnallowedtruereasonsession rule: ${pattern}// 3. 检查项目配置中的预授权规则constthismatchConfigRuleifreturnallowedtruereasonconfig rule: ${configRule}// 4. 需要用户实时确认constawaitthispromptUser// 5. 如果用户选择「本次会话始终允许」记住这个决定ifrememberForSessionthissessionAllowListaddpatternreturn在终端中你会看到这样的交互Claude wants to run: git commit -m fix: resolve null pointer Allow? Yes (y) Yes, and dont ask again for git commands (!) No (n)✅安全的做法分级权限 用户确认 会话级记忆兼顾安全和效率❌危险的做法默认允许所有操作或者只在启动时确认一次就放行所有操作07 Claude Code vs Cursor两种 Agent 架构哲学Claude Code 和 Cursor 代表了 AI 编码工具的两条路线Agent-native vs IDE-native。没有绝对的好坏但架构选择决定了能力边界。┌──────────────────────┐ ┌──────────────────────┐ │ Claude Code │ │ Cursor │ │ (Agent-native) │ │ (IDE-native) │ ├──────────────────────┤ ├──────────────────────┤ │ │ │ │ │ Terminal 为入口 │ │ VS Code 为入口 │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │ │ Agent Loop │ │ │ │ IDE 扩展层 │ │ │ │ (自主决策) │ │ │ │ (编辑器集成) │ │ │ └──────┬───────┘ │ │ └──────┬───────┘ │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │ │ 工具系统 │ │ │ │ LSP AST │ │ │ │ (Bash/File) │ │ │ │ (语义理解) │ │ │ └──────────────┘ │ │ └──────────────┘ │ │ │ │ │ │ 优势 │ │ 优势 │ │ · 任务自主性强 │ │ · 代码感知能力强 │ │ · 不依赖 IDE │ │ · 实时补全体验好 │ │ · CI/CD 可集成 │ │ · UI 交互丰富 │ │ · 复杂任务链 │ │ · 上下文自动感知 │ │ │ │ │ │ 劣势 │ │ 劣势 │ │ · 无实时补全 │ │ · 绑定 VS Code │ │ · 视觉反馈有限 │ │ · 自主性受限 │ │ · 学习曲线较陡 │ │ · 难以独立运行 │ └──────────────────────┘ └──────────────────────┘维度Claude CodeCursor入口TerminalVS CodeAgent 循环原生完整实现IDE 事件驱动工具执行沙箱 权限系统编辑器 API上下文来源文件读取 CLAUDE.mdLSP 打开的文件最佳场景复杂重构、跨文件任务日常编码、代码补全可编程性高CLI / SDK低GUI 为主✅正确的选择策略日常编码用 Cursor复杂任务、自动化流程用 Claude Code❌错误的思维非要选一个最好的实际上它们是互补关系08 设计哲学安全第一、用户控制、可预测行为通读 Claude Code 源码后我提炼出三条核心设计哲学安全第一Safety First、用户控制User in Control、可预测行为Predictable Behavior。这三条原则贯穿了整个架构安全第一—— 所有工具执行都在沙箱中运行。Bash 命令有超时限制默认 2 分钟文件写入需要确认危险命令rm -rf、git push --force会被特别标记。即便 LLM 产生幻觉也不会造成不可逆的破坏。用户控制—— 权限系统的核心就是「用户始终有最终决定权」。任何写操作都可以被拒绝用户可以随时 CtrlC 中断 Agent Loop。CLAUDE.md 让用户定义 AI 的行为边界而不是反过来。可预测行为—— 同样的输入、同样的项目配置Claude Code 的行为应该是一致的。这体现在工具的确定性执行、配置的层级覆盖规则、以及错误处理的标准化流程上。// 设计哲学在代码中的体现classSafetyGuard// 危险命令黑名单privatestaticDANGEROUS_PATTERNS/rm\s-rf\s\//// rm -rf //git\spush\s--force/// force push/chmod\s777/// 过度开放权限/(\/dev\/sda|\/dev\/disk)/// 直接写磁盘/mkfs\./// 格式化staticassesscommandstringRiskAssessmentforconstofthisDANGEROUS_PATTERNSiftestreturnlevelcriticalmessagePotentially destructive command detectedrequiresExplicitConfirmationtruereturnlevelnormalrequiresExplicitConfirmationfalse// 可预测行为标准化的错误处理classToolExecutionErrorextendsErrorconstructor public toolName: string, public originalError: Error, public suggestion: string // 始终给出建议而非黑盒报错 superTool ${toolName} failed: ${originalError.message}✅Claude Code 的态度宁可多问一次确认也不擅自执行危险操作❌错误的 Agent 设计为了效率跳过安全检查迟早出事常见坑坑 1以为 Agent Loop 是同步阻塞的。实际上 Claude Code 的工具执行是异步的多个独立工具可以并行执行。如果你自己实现 Agent Loop别忘了处理并发和竞态。坑 2上下文管理只做截断不做摘要。简单截断会丢失关键的任务上下文。Claude Code 的三级策略裁剪 → 摘要 → 丢弃是经过反复验证的最佳实践。坑 3权限系统做成全有或全无。要么全部允许要么全部拒绝——这两种极端都不对。分级权限 会话记忆才是正解。坑 4CLAUDE.md 写成了长篇小说。CLAUDE.md 的内容会占用上下文窗口。写得太长反而影响 Agent 的有效工作空间。建议控制在 500 tokens 以内只写最关键的项目约定。坑 5忽略工具的幂等性设计。Agent 可能因为网络抖动或 LLM 重试而重复调用工具。如果你的工具不是幂等的比如「追加写入」可能导致数据重复。总结这是系列的最后一篇让我把 Claude Code 架构中最重要的设计决策总结一下Agent Loop 是 AI Agent 的心脏「感知-决策-行动-观察」循环赋予了 Agent 自主完成复杂任务的能力。工具系统的核心不是能做什么而是如何安全地做——注册、校验、沙箱、权限四层防护缺一不可。上下文窗口管理是 Agent 工程化的核心挑战裁剪-摘要-丢弃三级策略是目前的最佳实践。CLAUDE.md 的分层加载机制全局 → 项目 → 目录是 AI 配置管理的范本设计值得在你自己的 Agent 项目中借鉴。安全第一、用户控制、可预测行为——这三条原则不只适用于 Claude Code它们是所有 AI Agent 都应该遵循的设计底线。Claude Code 和 Cursor 不是竞争关系而是互补关系。理解它们的架构差异才能在正确的场景选择正确的工具。学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%免费】