# Step 01: 从 Hello World 到架构总览
一句话导读：这一步不写任何功能，只做两件事——用最小依赖跑起一个 TypeScript 进程，并把「Claude Code 到底分几层」这张地图钉在墙上，为后面 50 步定坐标。
# 一、这一步做了什么（What）
step01/index.ts 只有几十行，全是 console.log：打印 Node 版本 / 平台，画一张六层架构图，列一份「5 阶段 × 10 步」的路线图。没有 readline、没有 API、没有工具。它的产出不是代码能力，而是认知框架：先知道要盖一栋六层楼，再从地基一层层往上砌。
# 二、面试官视角：为什么第一步是「什么都不做」？（Why）
面试题：一个 AI 编程助手，技术栈里为什么可以没有 Web 框架、没有数据库、没有构建工具？
因为 Claude Code 的本质被很多人误判了。它看起来像个「大型 AI 产品」，直觉上该有后端服务、消息队列、状态存储。但打开 step01/package.json，依赖只有三个：
@anthropic-ai/sdk—— 跟 Claude 通信的官方 SDKtsx—— 直接跑.ts，免编译typescript—— 类型检查
不做这个减法会怎样？你会掉进「工程化噪音」陷阱——先花两天配 webpack、纠结用哪个状态库，结果一行 AI 逻辑都还没写。第一步刻意把技术栈砍到骨头，就是要让学习者看清一个反直觉的事实：
| 直觉认为需要 | 实际情况 |
|---|---|
| Web 后端 / 数据库 | 无——它是本地 CLI，状态就在内存的对话历史里 |
| 复杂构建管线 | 无——tsx 直接解释执行 |
| 前端框架 | 有，但是 React + Ink（渲染到终端，不是浏览器） |
一句话：Claude Code 是「终端里的 AI 对话客户端」，复杂度全在对话引擎和工具系统，不在基础设施。第一步用极简依赖，把这个判断刻进脑子。
# 三、原理：这张架构图怎么读（How）
index.ts 里的 layers 数组，是整个项目的骨架。从上到下（用户视角）是这样：
终端 UI React + Ink 渲染 ink/ + components/
对话引擎 QueryEngine 核心循环 QueryEngine.ts
工具系统 Tool 接口 + 注册表 Tool.ts + tools/
API 层 Anthropic SDK 通信 services/api/
服务层 MCP/压缩/技能/记忆 services/
工具库 权限/配置/Git/文件 utils/
2
3
4
5
6
关键不在于「有几层」，而在于每一层都对应真实 Claude Code 源码里的一个目录。这决定了学习顺序——数据是自底向上流动的：
用户敲字 → 终端 UI 捕获
↓
对话引擎组装 messages
↓
API 层发给 Claude → Claude 说「调用 Read 工具」
↓
工具系统查注册表，找到 Read → 执行
↓
结果回灌对话引擎 → 再发给 Claude → ... 循环
↓
最终文本 → 终端 UI 逐字渲染
2
3
4
5
6
7
8
9
10
11
50 步就是按这个数据流「从下往上」搭：先有工具库（utils）、再有 API 层、再有引擎、最后才是 UI。先把水管铺好，再接水龙头。
# 为什么用 tsx 而不是 ts-node / 先编译
tsx 基于 esbuild，启动快、零配置，npx tsx index.ts 直接跑。学习场景下，每一步都想「改完立刻看效果」，任何「先 tsc 编译再 node 运行」的两段式流程都是干扰。这就是它作为学习脚手架的价值——把工具链的存在感降到最低。
# 四、深入追问（面试常见 follow-up）
Q：架构分层只是画图好看，还是有实际约束力？ A：有约束力。分层意味着依赖方向单向向下——UI 可以依赖引擎，引擎不能反过来依赖具体某个 UI 组件；工具可以调 utils，utils 不该知道工具的存在。一旦某层反向依赖上层，就会出现循环依赖、无法单独测试。图不是装饰，是依赖规则。
Q：为什么按「层」而不是按「功能」拆学习步骤？ A：按功能拆（比如「先做完整的文件编辑功能」）会逼你同时碰 UI、引擎、工具、权限四层，一次性面对全部复杂度。按层拆则每一步只引入一个新概念——step02 只碰输入、step06 只碰 API、step11 才碰工具。复杂度是被「切片」消化的。
Q：这一步没有可运行的「产品」，学它有什么用？ A：它建立的是心智模型。后面每写一个模块，你都能立刻定位「这是六层里的哪一层、和上下游怎么接」。没有这张地图，写到 step30 你会迷失在几十个文件里不知道 QueryEngine 该依赖谁。先有地图，再上路。
# 五、设计权衡
极简依赖的代价是：这个 mini 版永远不等于真实 Claude Code。真实版有约 1400 个 .ts + 500 个 .tsx 文件、有 MCP 协议、有沙箱、有权限系统。第一步的三个依赖是教学取舍——用最小可运行集合换取「看得懂、跑得起」。学习项目的目标是理解机制，不是复刻产品，这个取舍是对的。
# 六、与真实源码的对照
| 我们的实现 | Claude Code 源码 |
|---|---|
index.ts 打印架构图 | src/ 真实六层目录结构 |
| 3 个依赖的 package.json | 真实版数十个依赖 + 内部 workspace |
| tsx 直接执行 | 真实版打包为可分发 CLI |
| 「对话引擎」一行字 | QueryEngine.ts 数千行核心循环 |
# 七、一句话总结
Step 01 = 一张地图 + 一次减法：用三个依赖证明「AI 助手 = 终端对话客户端」，用六层架构图钉死后续 50 步的自底向上顺序。不写功能，只建坐标系——但没有这个坐标系，后面每一步都会迷路。
# 下一步
cd step02 && npm start —— 看看 Claude Code 是怎么读到用户输入的那行文字的。