从零手写 Mini Claude Code 的过程中,逐步揭开一个 AI 编程助手的内幕。
这个系列记录了我逐行学习 Claude Code 源码的过程。不追求面面俱到,而是抓住每个模块最核心的设计思想,用简化的实现把概念落地。
每篇按面试题式深度讲解组织:What(做了什么)→ Why(面试官视角:为什么要做、不做会怎样)→ How(原理 + 真实代码 + 数据流)→ 深入追问(面试 follow-up Q&A)→ 踩坑/权衡 → 与真实源码对照 → 一句话总结。代码片段均取自各 step 的真实源码,可对照阅读。
项目仓库在 claude-learn/,路线总长 75 步,目前主线已完成:headless 内核、引擎化、Agent 内核、协议/外部世界、安全/性能底层、Web/Bridge 多前端,以及全面源码巡礼收尾。完整路线见 大纲.md,以下是已发布的文章。
| # | 标题 | 核心主题 | 日期 |
|---|---|---|---|
| 01 | 从 Hello World 到架构总览 | 项目结构、六层架构、50 步路线图 | 2026-06-24 |
| 02 | REPL 循环与用户输入 | readline、CLI 交互模式、事件驱动 | 2026-06-24 |
| 03 | 模块化拆分 | 代码组织、单例模式、类型分离 | 2026-06-24 |
| 04 | 异步编程基础 | Promise、串行 vs 并行、超时控制 | 2026-06-24 |
| 05 | API Key 与环境变量 | 配置读取、多级回退策略 | 2026-06-24 |
| 06 | 真实 API 调用 | Anthropic SDK、消息历史、Token 统计 | 2026-06-24 |
| 07 | 流式输出 | SSE 协议、逐字输出、回调模式 | 2026-06-24 |
| 08 | 对话管理 | System Prompt、斜杠命令、Token 估算 | 2026-06-24 |
| 09 | 会话持久化 | 保存/加载、文件存储、上下文警告 | 2026-06-24 |
| 10 | 源码对照 | 我们 vs 真实 Claude Code | 2026-06-24 |
| 11 | 工具系统 | Tool 接口、注册表、EchoTool | 2026-06-24 |
| 12 | Bash 工具 | shell 命令执行、/run | 2026-06-24 |
| 13 | Read 工具 | 文件读取、常用场景 | 2026-06-24 |
| 14 | Write 工具 | 文件写入、补丁模式 | 2026-06-24 |
| 15 | Glob 搜索工具 | 文件模式匹配 | 2026-06-24 |
| 16 | Grep 搜索工具 | 文件内容搜索 | 2026-06-24 |
| 17 | Tool Calling 循环 | AI 自动调用工具 | 2026-06-24 |
| 18 | 多轮并行调用 | Promise.all 并行执行 | 2026-06-24 |
| 19 | 权限询问系统 | y/Y/n/a 四级控制 | 2026-06-24 |
| 20 | 错误处理 | 重试 + 超时 + 错误分类 | 2026-06-24 |
| 21 | System Prompt 构建 | 专用模块 + 工具指南 | 2026-06-24 |
| 22 | Token 预算控制 | 三级预算 + 费用控制 | 2026-06-24 |
| 23 | 成本追踪 | 每轮费用 + 累计 | 2026-06-24 |
| 24 | 对话压缩 | 摘要历史对话 | 2026-06-24 |
| 25 | 模型切换 | Token 预算驱动的切换 | 2026-06-24 |
| 26 | 配置持久化 | .claude-settings.json | 2026-06-24 |
| 27 | 输出格式控制 /style | 提示词驱动风格、容错输入 | 2026-06-25 |
| 28 | 源码对照 我们 vs QueryEngine | 17 模块对回真实源码、~40% 覆盖 | 2026-06-25 |
| 29 | 压缩切点修复 | 别切散工具对、孤儿 tool_result→400 | 2026-06-25 |
| 30 | 抽象出 QueryEngine 类 | 循环搬家、依赖注入、引擎不碰 I/O | 2026-06-25 |
| 31 | 统一消息内容模型 ContentBlock | 判别联合、类型收窄、知识收口 | 2026-06-25 |
| 32 | 流式事件系统 | 回调→async generator、yield* 委托 | 2026-06-25 |
| 33 | Extended Thinking 思考模式 | thinking 块、按块边界发事件、/think | 2026-06-25 |
| 34 | 源码对照② 引擎 vs QueryEngine | 形状抄对了、差距全在生产化外壳 | 2026-06-25 |
| 35 | 斜杠命令框架 | 命令注册表、AppState、主循环瘦身 | 2026-06-25 |
| 36 | Hooks 生命周期 | PreToolUse/PostToolUse、拦截/改写/观察 | 2026-06-25 |
| 37 | TodoWrite 工具 | 工厂函数注入、全量替换、可勾选清单 | 2026-06-25 |
| 38 | 子代理 AgentTool | fork 子 QueryEngine、上下文隔离、防递归 | 2026-06-25 |
| 39 | 多代理编排 AgentBatch | 并行 fan-out + 汇总、mapLimit 并发上限 | 2026-06-26 |
| 40 | 记忆系统 CLAUDE.md | 用户级+项目级记忆注入、# 快捷记忆 |
2026-06-26 |
| 41 | Skills 系统 | 渐进式披露、按需加载 SKILL.md | 2026-06-26 |
| 42 | Plan Mode 计划模式 | 只读研究、三道写护栏、ExitPlanMode 审批 | 2026-06-26 |
| 43 | 上下文工程 | 环境注入、目录树、@文件展开 |
2026-06-26 |
| 44 | 真实对话压缩 | 结构化 6 段摘要、compact_boundary | 2026-06-26 |
| 45 | Phase 4 整合演示 | 35–44 十项能力串成流水线 | 2026-06-26 |
| 46 | 网页工具 WebSearch/WebFetch | 客户端工具 vs 服务端工具的机制差异 | 2026-06-29 |
| 47 | MCP 协议入门 | JSON-RPC over stdio、握手、tools/list | 2026-06-29 |
| 48 | MCP 工具动态注册 | 适配器包装、mcp__server__tool 命名 |
2026-06-29 |
| 49 | MCP 资源 / prompts | resources 只读上下文、prompts 模板 | 2026-06-29 |
| 50 | 接入真实 MCP server | @playwright/mcp 驱动浏览器、协议互操作 | 2026-06-29 |
| 51 | 用官方 SDK 重写 MCP 客户端 | 换引擎不换接口、多 transport | 2026-06-29 |
| 52 | 插件系统 | 一个目录打包工具/命令/钩子、动态 import | 2026-06-29 |
| 53 | LSP 集成 | 编译器的眼睛、推送式诊断、闭环自纠 | 2026-07-01 |
| 55 | 本地 REPL Bridge | 前端与引擎解耦、TCP 广播 EngineEvent | 2026-07-01 |
| 57 | 权限引擎深化 | allow/deny 参数级规则、路径越界校验 | 2026-07-01 |
| 59 | Bash 风险分类器 | 启发式+LLM 两段、堵"换工具绕过" | 2026-07-07 |
| 58 | 安全沙箱 | 环境擦除、写入边界、诚实标注边界 | 2026-07-07 |
| 60 | Prompt Caching:缓存稳定前缀 | system/tools 缓存断点、缓存感知计费 | 2026-07-07 |
| 61 | 多层设置系统合并 | 五层深合并、规则累加、provenance | 2026-07-07 |
| 62 | 遥测 / 日志 / 错误上报 | 结构化事件、PII 擦洗、opt-out | 2026-07-07 |
| 63 | 源码对照②:安全 / 性能层 | 权限/沙箱/缓存/遥测对照真实源码 | 2026-07-07 |
| 64 | 最小终端渲染引擎:手写 Ink 地基 | box/text 虚拟节点、行级 diff 渲染 | 2026-07-08 |
| 65 | 接 React reconciler:用 JSX 描述界面 | JSX、函数组件、useState、reconcile | 2026-07-08 |
| 66 | 转 Web①:agent 后端服务 | QueryEngine → HTTP + SSE 事件流 | 2026-07-08 |
| 67 | 转 Web②:WebSocket 双向通道与权限 | permission_request/response 跨网络审批 | 2026-07-08 |
| 68 | 转 Web③:最简 web 前端 | 聊天气泡、流式打字机、权限弹窗 | 2026-07-08 |
| 69 | 转 Web④:工具调用 UI 与 Markdown 渲染 | 可折叠工具卡、marked 渲染 | 2026-07-08 |
| 70 | 统一内核 createCore:终端与 Web 共用 | 单一装配、多前端注入、功能 parity | 2026-07-08 |
| 71 | Web UI 打磨②:状态栏与多会话 | SessionManager、token/cost/cache 状态栏 | 2026-07-10 |
| 72 | 源码对照③:内核 + 前端拆分 | SDK/Bridge/Remote/sessionStorage 对照 | 2026-07-13 |
| 75 | 全面源码巡礼收尾 | 架构脑图、2039 文件源码树、构建对照 | 2026-07-13 |
| 76 | Agent 设计模式地图 | Google 12 模式 × claude-learn × Claude Code 源码 | 2026-07-13 |
01–29 已是一个完整的 headless(无 UI)mini Claude Code:REPL、5 工具、Tool Calling 循环、并行执行、权限、错误处理/重试/超时、System Prompt 构建、Token 预算、成本追踪、对话压缩、模型切换、配置持久化、输出格式控制。 30–34 第一次质变(脚本 → 引擎):抽出
QueryEngine类、统一 ContentBlock、回调升级为 async-generator 事件流、Extended Thinking、引擎源码对照——Phase 3.5 收尾。 35–45 第二次质变(工具调用 → 自主 Agent):命令注册表 + AppState、Hooks 生命周期、TodoWrite、子代理 AgentTool、多代理编排、记忆、Skills、Plan Mode、上下文工程、真实压缩——Phase 4 完成。 46–55 协议与外部世界(Phase 5):网页工具、MCP(入门→动态注册→资源/prompts→接真实 server→官方 SDK)、插件系统、LSP、REPL Bridge。(54/56 跳过) 57→59→58→60→61→62→63 安全·性能·底层(Phase 6):权限规则引擎、Bash 风险分类器、安全沙箱、Prompt Caching、多层设置、遥测、源码对照②。 64–72 第三次质变(内核长出多前端):手写 Ink 地基、mini-React、HTTP/SSE、WebSocket 权限、Web 前端、工具 UI、createCore统一装配、多会话、源码对照③。 75 全面源码巡礼收尾:架构脑图 + 我们 vs 真实 2039 文件源码树 + 构建/运行对照。
三次质变已经闭环:① 脚本 → 引擎(✅ 30–34);② 工具调用 → 自主 Agent(✅ 35–45);③ 内核长出多前端(✅ 64–72)。Phase 8 也已用 step75 做全面源码巡礼收尾。
注:代码实际步序与早期大纲有偏移,部分步骤按真实构建顺序推进而非编号顺序(如 57→59→58→60→61→62→63);54/56 属于账号/远程基建分支,主线跳过。
- 每篇文章都对应一个可以运行的 step,建议配合代码阅读:
cd stepXX && npm install && npm start - 文章会比代码多一些背景思考和设计权衡,适合先读文章再看代码