基于 2026 年 3 月公开的 Claude Code 源码快照，深度分析这个当今最受欢迎 AI 编程助手的架构设计。

---

目录

• 项目概览
• 核心架构分析
• 工具系统深度解析
• 权限系统设计
• 查询引擎与主循环
• UI 架构：终端上的 React
• 工程实践亮点
• AI Agent 设计启示
• 总结

---

项目概览

基本数据

指标	数值
总文件数	~1,900
代码行数	512,000+
语言	TypeScript (strict)
运行时	Bun
UI 框架	React + Ink
工具数量	~40
命令数量	~50
UI 组件数	~140+

项目定位

Claude Code 是 Anthropic 推出的AI 编程辅助 CLI 工具，核心定位是：

• 在终端环境直接与 Claude 交互
• AI 可以直接读写你的文件、执行命令、搜索代码
• 人机协作完成编程任务
• 支持子代理、MCP 协议、技能系统等高级特性

---

核心架构分析

整体架构图

分层架构

Claude Code 采用清晰的分层设计：

层级	职责	位置
入口层	CLI 解析、启动优化、Ink 初始化	src/main.tsx
注册层	工具和命令的注册发现	src/tools.ts, src/commands.ts
引擎层	主循环、API 调用、工具分发	src/QueryEngine.ts
工具层	具体工具实现	src/tools/
命令层	用户命令实现	src/commands/
服务层	外部服务集成	src/services/
UI 层	终端 React 组件	src/components/

核心抽象

1. Tool 接口

// 核心抽象简化
interface Tool {
  name: string;
  description: string;
  inputSchema: z.AnyZodObject;
  permissionType: PermissionType;
  isEnabled?: (context: Context) => boolean;
  execute: (
    args: z.infer<this['inputSchema']>,
    context: Context
  ) => Promise<ToolResult>;
}

设计点评：

• ✅ 每个工具自包含：schema、权限、执行都在一处
• ✅ 使用 Zod 做运行时验证，同时生成 JSON schema 给 LLM
• ✅ 符合开闭原则：新增工具不修改其他代码

2. Command 接口

interface Command {
  name: string;
  description: string;
  getHint?: (context: Context) => string | undefined;
  isEnabled?: (context: Context) => boolean;
  invoke: (context: Context, args: string) => Promise<void>;
}

设计点评：

• ✅ 命令和工具分离：命令是用户主动调用，工具是 AI 主动调用
• ✅ 清晰区分：用户意图 vs AI 工作流

---

工具系统深度解析

工具分类

类别	工具示例	特点
文件操作	ReadTool, WriteTool, EditTool	需要权限检查，处理大文件
搜索	GlobTool, GrepTool	结果截断，避免上下文爆炸
系统	BashTool	最高风险，每次都要确认
Web	WebFetchTool, WebSearchTool	网络请求，内容处理
Agent	AgentTool, TeamCreateTool	子代理生成，上下文隔离
扩展	MCPTool, SkillTool	外部能力接入
任务	TaskCreateTool, TaskUpdateTool	任务管理
其他	CronCreateTool, NotebookEditTool 等	特定场景

代表性工具分析

FileEditTool - 增量编辑设计

FileEditTool 是最常用的工具之一，它不重写整个文件，只修改需要改的部分：

用户要求：修改第 50-60 行的函数 → 提取原有内容 → 做字符串替换 → 写回文件

关键设计点：

1. 模糊匹配：如果 LLM 提供的内容和磁盘上不完全匹配，会用相似度找最接近的区域
2. 多轮匹配：允许多个替换同时进行
3. 权限检查：修改文件必须用户批准

为什么这么设计？

• 增量编辑比全文件重写快很多
• LLM 不需要输出整个文件内容，节省 token
• 出错概率更小

---

更多完整内容，请到微信公众号查看