深入拆解 Claude Code 源码一7 万行 TypeScript 揭秘全球最强 AI 编程助手的内部架构深入拆解 Claude Code 源码一7 万行 TypeScript 揭秘全球最强 AI 编程助手的内部架构系列深入拆解 Claude Code 源码 | 第 1 篇 / 共 8 篇关键词Claude Code, AI 编程助手, 源码分析, TypeScript, 架构设计写在前面2024 年底Anthropic 发布了 Claude Code —— 一个直接运行在终端里的 AI 编程助手。不同于 Cursor、Copilot 这类 IDE 插件Claude Code 选择了一条更极客的路线它就是一个 CLI 工具你敲claude回车它就开始帮你写代码。但你有没有想过当你在终端里输入一句话到 Claude 帮你改好代码、跑完测试、提交 PR这中间到底发生了什么我花了大量时间研究了 Claude Code v2.1.88 的恢复源码从 npm 包的 source map 中提取约 7 万行 TypeScript1884 个文件。这篇文章是这个系列的开篇我将带你从全局视角俯瞰整个系统的架构让你对这个最强 AI 编程助手有一个完整的认知地图。一、一句话理解 Claude Code如果只能用一句话概括 Claude Code 的本质我会说Claude Code 是一个基于 React Ink 的终端应用通过 Anthropic Messages API 实现流式对话内置 35 工具让 AI 能直接操作你的文件系统和命令行。拆开来看它解决了三个核心问题怎么和 AI 对话→ 流式 API 通信 消息历史管理怎么让 AI 操作电脑→ 工具系统读写文件、执行命令、搜索代码…怎么在终端里做出好看的界面→ React Ink 渲染引擎二、全局架构图先看一张鸟瞰图┌─────────────────────────────────────────────────────┐ │ 用户终端 (Terminal) │ │ ┌───────────────────────────────────────────────┐ │ │ │ React Ink 渲染层 (389 组件) │ │ │ │ App → Messages → PromptInput → StatusLine │ │ │ └──────────────────┬────────────────────────────┘ │ │ │ │ │ ┌──────────────────▼────────────────────────────┐ │ │ │ REPL 主循环 │ │ │ │ screens/REPL.tsx → QueryEngine.ts │ │ │ └──────────────────┬────────────────────────────┘ │ │ │ │ │ ┌──────────────────▼────────────────────────────┐ │ │ │ 核心引擎层 │ │ │ │ query.ts (API 调用) │ ContextManager │ │ │ │ messageState.ts │ tokenBudget.ts │ │ │ └────┬───────────┬────────────┬─────────────────┘ │ │ │ │ │ │ │ ┌────▼────┐ ┌────▼─────┐ ┌───▼──────┐ │ │ │ 35 工具 │ │ 77 命令 │ │ 20 服务 │ │ │ │ Bash │ │ /commit │ │ API 客户端│ │ │ │ FileEdit│ │ /review │ │ MCP 集成 │ │ │ │ Agent │ │ /compact │ │ OAuth │ │ │ │ Grep │ │ /mcp │ │ 插件系统 │ │ │ └─────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ 支撑系统状态管理 / Hooks / 类型 / 常量 │ │ │ │ Zustand Store │ 80 Hooks │ Feature Flags │ │ │ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ │ │ ▼ ▼ Anthropic Messages API MCP Servers (流式对话) (外部工具扩展)三、目录结构速览整个src/目录可以分为8 大模块模块路径文件数一句话说明入口与启动entrypoints/,main.tsx,replLauncher.tsx~15从命令行到 REPL 的启动链路核心引擎query.ts,QueryEngine.ts,ContextManager/~20对话循环、API 调用、上下文管理命令系统commands/77/commit,/review,/mcp等斜杠命令工具系统tools/~35文件读写、Shell 执行、Agent 调度服务层services/20 子系统API 客户端、MCP、OAuth、插件、分析组件系统components/389React Ink 终端 UI状态与 Hookshooks/,state/,context/100Zustand 状态管理、80 React Hooks其他系统skills/,tasks/,bridge/,vim/,ink/200技能、任务、远程控制、Vim 模式、渲染引擎四、一次完整对话的生命周期让我们跟踪一次用户输入到 AI 回答的完整流程这是理解整个架构最好的方式Step 1: 用户输入用户在终端输入 “帮我修复这个 bug”按回车。PromptInput 组件 → useInputHistory hook → 提交到 REPL 主循环Step 2: 消息构建REPL 主循环screens/REPL.tsx接收输入构建UserMessage// src/types/message.tstypeUserMessage{role:usercontent:ContentBlock[]// 文本 图片 工具结果uuid:stringtimestamp:number}Step 3: 系统提示词拼装constants/system.ts中的getCLISyspromptPrefix()拼装系统提示词包含基础指令当前日期、工作目录Git 状态已安装的技能描述工具使用规范Step 4: API 调用query.ts中的query()函数发起流式 API 请求// 核心调用链query(messages,tools,systemPrompt)→ AnthropicSDK:client.messages.create({stream:true})→ 流式处理 text/tool_use content blocks →yieldStreamingMessage 对象Step 5: 流式响应处理QueryEngine.ts接收流式响应实时渲染到终端API Stream → StreamProcessor → ContentBlockParser → React 状态更新 → Ink 重渲染如果 AI 决定使用工具比如BashTool进入 Step 6。Step 6: 工具执行// services/tools/toolOrchestration.tsrunTools(toolCalls,context)→partitionToolCalls()// 分区并发安全 vs 必须串行→runToolsConcurrently(batch)// 并发执行安全批次→runToolsSerially(toolCalls)// 串行执行敏感操作每个工具执行前经过validateInput()— 输入验证checkPermissions()— 权限检查plan/auto/bypass 模式runPreToolUsesHooks()— PreToolUse Hookcall()— 实际执行runPostToolUseHooks()— PostToolUse HookStep 7: 结果回传工具结果作为ToolResultMessage追加到消息历史再次调用 API形成工具调用闭环用户输入 → AI 回复(含 tool_use) → 工具执行 → 结果回传 → AI 继续回复 → ...这个循环会持续到 AI 不再请求工具为止。Step 8: 渲染输出React Ink 层将最终结果渲染到终端Messages.tsx → MessageRow.tsx → 各种内容组件代码高亮、Diff、表格…五、技术栈全景技术用途备注TypeScript主语言~7 万行React Ink终端 UIInk 是 React 的终端渲染器React Compiler自动优化_c()缓存函数免手写 memo/useCallbackCommander.jsCLI 参数解析在main.tsx中定义 50 参数Zustand状态管理AppState.tsxAppStateStore.tsZod v4Schema 验证工具输入、设置、Hook 响应Anthropic SDKAPI 通信流式 Messages APIBun运行时打包bun:bundlefeature flagsYoga布局引擎Ink 内部的 Flexbox 实现MCP工具扩展协议Model Context Protocol六、几个令人惊叹的设计决策1. 整个终端 UI 是一个 React 应用没错你在终端里看到的每一个字符、每一种颜色、每一个 spinner都是 React 组件通过 Ink 渲染出来的。components/目录有389 个文件包含完整的组件树、设计系统、主题切换、甚至模糊搜索选择器。2. Ink 是一个 fork 而不是依赖Anthropic 没有直接用 npm 上的 Ink而是 fork 了一份放在src/ink/76 文件做了大量优化双缓冲渲染— 只更新变化的字符CharPool 字符池复用— 避免重复分配HyperlinkPool— 超链接复用字素感知— 正确处理 emoji 和 CJK 字符3. Feature Flag 无处不在代码中大量使用feature(FLAG_NAME)这是 Bun 的编译时宏用于死代码消除。这意味着 Anthropic 可以通过不同的构建配置从同一份源码产出不同功能集的二进制文件。这是 A/B 测试和渐进发布的基础设施。4. 工具可以并发执行但有安全边界toolOrchestration.ts会将工具调用分为两类并发安全Read、Glob、Grep 等只读操作可以并行必须串行Bash、FileEdit、FileWrite 等写操作必须排队最大并发数由CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY环境变量控制默认 10。5. 推测执行AI 的预判Claude Code 有一个实验性的推测执行系统services/PromptSuggestion/speculation.ts992 行它会在等待用户输入时预判用户可能的下一步操作并提前执行结果放在 overlay 目录里。如果猜对了直接使用节省响应时间。七、模块间依赖关系entrypoints ──→ main.tsx ──→ REPL.tsx │ ┌───────────┼───────────┐ ▼ ▼ ▼ QueryEngine Commands Components │ │ │ ▼ │ │ query.ts │ │ │ │ │ ┌───────┼───────┐ │ │ ▼ ▼ ▼ ▼ ▼ Tools Services Hooks ◄──── State/Context │ │ ▼ ▼ MCP Servers OAuth八、系列目录本系列共 8 篇按模块从入口到输出逐层深入篇标题核心内容1全面拆解 Claude Code 架构← 你在这里全局鸟瞰、技术栈、生命周期2CLI 启动流程深度解析cli.tsx → main.tsx → REPL 的完整链路3核心对话引擎QueryEngine、流式处理、上下文管理477 个斜杠命令的设计艺术三种命令类型、插件迁移模式535 个内置工具的瑞士军刀buildTool 模式、并发安全、权限检查620 个后端服务的微服务架构MCP、OAuth、推测执行、记忆同步7终端里的 React 渲染引擎389 组件 Ink fork 的双缓冲渲染8状态管理、技能、Vim 与类型系统收尾篇串联剩余模块下篇预告第二篇CLI 启动流程深度解析当你在终端敲下claude并按下回车到看到那个闪烁的光标中间只经过了大约 100 毫秒。但这 100 毫秒里发生了什么cli.tsx如何快速判断是--version还是正常启动main.tsx的 4700 行 Commander.js 定义做了哪些初始化REPL 是如何被点燃的下一篇我们将逐行跟踪这 100ms 的启动链路。标签:Claude CodeAI 编程助手源码分析TypeScript架构设计AnthropicCLI 工具