Claude Code 源码架构深度解析V2.0

核心观点与关键数据

• 代码库规模与设计意图：Claude Code的npm包包含近4756个文件，远超其他开源coding agent，体现了平台化设计。入口层通过CLI工具和MCP协议等支持多种运行时，并通过fast-path分发逻辑优化性能。
• 引擎与Prompt编排：系统通过主循环（query.ts，1729行）执行请求，采用状态机管理迭代状态。通过四道压缩机制优化上下文，并支持流式工具执行和Prompt缓存经济学。
• 工具系统与治理：工具接口设计包含丰富的元数据和方法，42个工具按功能分类，并通过工具执行流水线进行治理，包括输入校验、权限检查、风险预判等。
• 多Agent体系：系统包含多个内建Agent，如Explore Agent、Verification Agent等，通过分工和调度实现协同工作。AgentTool.tsx作为调度中心，处理不同路径的分支，并通过Fork path的cache优化提升效率。
• 安全层：权限系统通过PermissionMode、PermissionRule等模型进行管理，并引入Hook系统和三层防护网（Speculative Classifier、Hook Policy Layer、Permission Decision）确保安全。

研究结论与设计原则

• 生态扩展：通过Skill、Plugin、MCP等机制扩展系统能力，并通过让模型“感知到”自己的能力，实现生态的真正发挥作用。
• 上下文经济学：通过四道压缩机制、Reactive Compact、Token Budget等机制优化上下文管理，将Token视为预算进行控制。
• 产品化：系统注重生命周期管理，通过Bridge系统、State管理、UI层、Telemetry等实现产品化。
• 设计原则：从源码中提炼出七项设计原则，包括不信任模型的自觉性、角色拆分、工具调用治理、上下文是预算、安全层互不绕过、模型感知和产品化处理第二天问题。

附录：核心文件索引

• 入口与主循环：cli.tsx、main.tsx、query.ts、QueryEngine.ts、Tool.ts
• Prompt系统：prompts.ts、systemPromptSections.ts、工具prompt.ts
• 工具执行：toolExecution.ts、toolHooks.ts、toolOrchestration.ts、StreamingToolExecutor.ts
• Agent系统：AgentTool.tsx、runAgent.ts、forkSubagent.ts、内建Agent.tsx
• 权限与安全：permissions/目录下的文件、bashClassifier.ts、dangerousPatterns.ts
• 生态扩展：skills/目录、plugins/目录、mcp/目录
• 上下文管理：compact/目录、SessionMemory/目录、tokenBudget.ts