总体架构

见过太多项目把架构图画得漂漂亮亮，代码一团糟。Claude Code 的分层倒是实打实的——每一层的职责边界清晰，依赖方向严格自上而下。

六层架构

Claude Code 采用经典的分层架构，从底到顶：

┌─────────────────────────────────────┐
│  第6层  UI 交互层                    │  React + Ink 终端渲染
├─────────────────────────────────────┤
│  第5层  命令层                       │  120+ 斜杠命令路由
├─────────────────────────────────────┤
│  第4层  工具层                       │  40+ 工具的统一抽象
├─────────────────────────────────────┤
│  第3层  查询引擎                     │  AI 交互核心循环
├─────────────────────────────────────┤
│  第2层  服务层                       │  压缩/分析/MCP/LSP
├─────────────────────────────────────┤
│  第1层  基础设施                     │  状态/配置/工具函数
└─────────────────────────────────────┘

第 1 层：基础设施

地基。包括状态管理、配置系统、CLI 入口、常量定义和 300+ 工具函数。

这层没什么花哨的，但很重要——上面所有层都直接或间接依赖它。做过大项目的都知道，地基不稳，后面全是坑。

第 2 层：服务层

独立运行的后台模块：会话压缩、遥测分析、MCP 协议、LSP 语言服务器等。

这些服务之间互相不依赖，各跑各的。这个设计很老派但很靠谱——服务挂一个不影响其他的。

第 3 层：查询引擎

整个系统的心脏。AI 交互的核心逻辑就在这里：

接收用户输入
计算 Token 预算
裁剪上下文消息
调用 Claude API
解析流式响应
识别工具调用
执行工具（带权限检查）
将工具结果拼回消息
判断是否需要继续循环
处理错误和重试
更新状态
返回最终结果

一共 12 步，每一步都有讲究。后面查询引擎章节会细说。

第 4 层：工具层

40+ 个工具的统一抽象。每个工具都实现同一个接口：名称、描述、参数 Schema、执行逻辑。

文件读写、Bash 执行、代码搜索、Agent 子任务、Web 访问、MCP 桥接——所有工具对上层来说都是一样的接口。这个统一抽象做得很干净。

第 5 层：命令层

120+ 个斜杠命令，通过 commands.ts 统一路由。从简单的 /help 到复杂的 /mcp，全在这里。

命令和工具的区别：工具是给 AI 调的，命令是给人用的。但有些命令底层会调工具。

第 6 层：UI 交互层

基于自定义 Ink 渲染器的终端 UI 系统。不是简单的 console.log，是正经的 React 组件树：

200+ 组件
100+ Hook
Vim 模式
语音输入
虚拟滚动
状态栏

在终端里用 React 做 UI，这个选型很大胆但效果不错。

关键数据流

用户输入 → AI 响应

用户输入
  → PromptInput 组件捕获
  → 查询引擎接收
  → Token 预算计算
  → 上下文裁剪
  → Claude API 调用
  → 流式响应解析
  → 工具调用识别与执行
  → 结果回传
  → UI 渲染

工具执行流

AI 决定调用工具
  → 权限检查（白名单/黑名单/用户确认）
  → 参数校验（Zod Schema）
  → 工具执行（支持并发）
  → 结果序列化
  → 拼入消息流
  → 继续 AI 推理

构建系统

采用 Bun 作为构建工具，几个值得注意的点：

编译时特性消除：feature() 函数在构建时求值，未启用的功能整个代码分支被删掉
延迟 import：除入口外的模块全部动态加载
React Compiler：自动 memo 化，不用手写 useMemo/useCallback

这些优化加在一起，让一个 1500+ 文件的项目启动时间控制在 400ms 以内。

总体架构 ​

六层架构 ​

第 1 层：基础设施 ​

第 2 层：服务层 ​

第 3 层：查询引擎 ​

第 4 层：工具层 ​

第 5 层：命令层 ​

第 6 层：UI 交互层 ​

关键数据流 ​

用户输入 → AI 响应 ​

工具执行流 ​

构建系统 ​