首发 | claude code源码架构拆解:16 章完整拆解 Bun+TS+React Ink 设计精髓

大家好，我是程序员虎哥，跟踪学习、不定期同步以 OpenClaw 为代表的 Agent 技术。技术发展应该为劳动者减负，而不应该增加焦虑和内耗~

claude code源码架构解析

“

公开技术文档 | 不含源码细节

前言

本文档旨在深入剖析现代智能编码助手的整体架构设计思想，为技术团队提供系统设计的参考框架。作为面向公众的技术分享，本文档聚焦于架构哲学、设计模式和系统协同，不涉及任何具体实现代码。

项目概述与技术选型
整体架构设计
核心启动流程
Tool 抽象设计模式
上下文协议集成
权限管理体系
钩子扩展机制
状态管理系统
查询引擎设计
远程会话系统
技能命令系统
子代理架构
性能优化策略
安全机制设计
模块协同工作流
扩展开发指南

1. 项目概述与技术选型

1.1 项目定位

智能编码助手是一款面向开发者的终端交互式 AI 编程工具，通过将自然语言指令转化为代码操作，实现智能化的开发辅助。

1.2 核心技术栈

层级	技术选型	选型理由
语言	TypeScript	类型安全、开发效率、生态完善
运行时	Bun	启动速度快、内存占用低、原生 TypeScript 支持
UI 框架	React + Ink	声明式终端 UI、组件化开发
CLI 框架	Commander.js	成熟的命令行解析、丰富的插件生态
AI SDK	Anthropic SDK	官方支持、流式响应、工具调用
协议	MCP (Model Context Protocol)	标准化的上下文交换协议

1.3 设计原则

终端优先：所有交互设计围绕终端环境优化
零配置启动：开箱即用，无需复杂配置
渐进式能力：基础功能简单，高级功能可按需启用
安全可控：所有敏感操作需用户确认或明确授权
可扩展性：通过钩子和 MCP 协议支持第三方扩展

2. 整体架构设计

2.1 分层架构

┌─────────────────────────────────────────────────────────┐
│                    用户交互层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  终端 UI    │  │  CLI 命令   │  │  技能命令   │      │
│  │  (React)    │  │  (Commander)│  │  (Slash)    │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    核心引擎层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  查询引擎   │  │  工具调度   │  │  权限控制   │      │
│  │  (Query)    │  │  (Tool)     │  │  (Permission)│     │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  钩子系统   │  │  状态管理   │  │  会话管理   │      │
│  │  (Hooks)    │  │  (State)    │  │  (Session)  │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    服务集成层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  MCP 客户端  │  │  桥接服务   │  │  遥测服务   │      │
│  │  (MCP)      │  │  (Bridge)   │  │  (Telemetry) │     │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  Git 服务    │  │  配置服务   │  │  日志服务   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    基础工具层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  文件操作   │  │  进程执行   │  │  网络请求   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  代码搜索   │  │  模式匹配   │  │  数据处理   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘

3. 核心启动流程

3.1 启动阶段划分

阶段 1: CLI 解析
   └─ 解析命令行参数和选项
   └─ 加载 .env 环境变量
   └─ 处理 --version, --help 等特殊标志

阶段 2: 前置检查
   └─ 验证 Node.js/Bun 版本
   └─ 检查终端兼容性
   └─ 加载本地配置文件

阶段 3: 状态初始化
   └─ 创建全局状态容器
   └─ 加载历史会话记录
   └─ 初始化遥测系统

阶段 4: 服务启动
   └─ 启动 MCP 客户端
   └─ 连接远程桥接服务（如启用）
   └─ 注册钩子处理器

阶段 5: UI 渲染
   └─ 初始化 React 根组件
   └─ 渲染终端界面
   └─ 显示欢迎消息

阶段 6: 就绪待命
   └─ 进入命令循环
   └─ 等待用户输入

3.2 配置加载优先级

配置系统采用多层覆盖策略，优先级从高到低：

命令行参数：最高优先级，如 --model, --permission
项目配置：.claude/settings.local.json
用户配置：~/.claude/settings.json
默认值：代码中定义的默认配置

4. Tool 抽象设计模式

4.1 设计思想

Tool 模式是整个系统的核心抽象，其设计哲学是：将所有可执行操作统一为工具调用。

这种设计的优势：

一致性：所有操作遵循相同的调用协议
可组合：工具可以链式调用和组合
可审计：每次调用都有完整的输入输出记录
可控制：统一的权限检查和错误处理

4.2 工具分类体系

工具分类
├── 核心工具（始终可用）
│   ├── Agent - 子代理管理
│   ├── Bash - 命令执行
│   ├── 文件读取
│   ├── 文件编辑
│   └── 文件写入
│
├── 搜索工具
│   ├── 全局文件搜索
│   └── 内容搜索
│
├── 任务管理工具
│   ├── 任务创建
│   ├── 任务更新
│   └── 任务列表
│
├── 网络工具
│   ├── 网页获取
│   └── 网络搜索
│
├── 扩展工具（条件启用）
│   ├── MCP 工具
│   ├── 技能工具
│   └── 第三方工具
│
└── 特殊工具
    ├── 权限询问
    └── 计划模式退出

5. 上下文协议集成

5.1 MCP 协议概述

MCP（Model Context Protocol）是用于 AI 模型与外部系统交换上下文的标准协议。

核心概念：

Server：提供上下文信息的服务端
Client：消费上下文信息的客户端
Resource：可读取的上下文资源
Tool：可执行的远程操作

5.2 连接管理架构

MCP 连接管理器负责：

连接池管理（按服务器名称缓存连接）
自动重连机制
超时控制
传输层抽象（stdio、SSE、HTTP/HTTPS、WebSocket）

5.3 工具注册流程

MCP 服务器启动并暴露工具列表
客户端发现并拉取工具定义
工具包装为本地代理对象
注册到全局工具池
参与权限过滤和调用

6. 权限管理体系

6.1 权限设计哲学

权限系统遵循最小权限原则和显式授权原则：

默认拒绝所有敏感操作
用户必须明确授予额外权限
权限粒度可精细到单次调用

6.2 权限模式

模式	行为	适用场景
default	标准确认流程	日常使用
accept	自动接受所有请求	可信环境
auto	基于规则自动决策	高度自动化
bypass	跳过权限检查	内部测试

6.3 权限规则引擎

规则引擎支持以下匹配模式：

精确匹配：工具名完全匹配
通配符匹配：支持 * 通配符
MCP 服务器匹配：按服务器前缀匹配
正则匹配：复杂模式匹配

7. 钩子扩展机制

7.1 钩子设计理念

钩子系统的设计目标是：在不修改核心代码的前提下，支持用户自定义行为。

7.2 钩子事件类型

事件类型	触发时机	典型用途
`SessionStart`	会话启动时	初始化配置、加载环境
`PreToolUse`	工具调用前	参数验证、日志记录
`PostToolUse`	工具调用后	结果处理、状态更新
`MessageSubmitted`	消息提交后	消息预处理
`LoopDetection`	检测到循环时	循环处理策略
`BeforeExit`	退出前	清理工作、状态保存

7.3 钩子执行模型

事件触发 → 收集注册的钩子 → 按优先级排序 → 顺序执行钩子 → 处理钩子结果

钩子支持异步执行，支持修改上下文，可继续/中断/修改执行流程。

8. 状态管理系统

8.1 状态设计哲学

状态管理采用单一事实来源原则：

所有状态集中在一个全局容器中
状态变更通过发布 – 订阅模式通知
支持状态快照和恢复

8.2 状态分类

全局状态
├── 会话状态（当前对话历史、已用 token 统计、会话配置）
├── 工具状态（已注册工具列表、工具调用历史、MCP 连接状态）
├── UI 状态（界面尺寸、主题配置、渲染模式）
├── 配置状态（用户配置、项目配置、环境变量）
└── 运行时状态（子进程列表、任务队列、错误状态）

8.3 状态更新模式

状态更新遵循不可变原则：

旧状态 → 创建副本 → 应用变更 → 发布通知 → 新状态

9. 查询引擎设计

9.1 引擎职责

查询引擎是 AI 对话的核心协调者，负责：

管理对话历史
协调工具调用
处理权限决策
流式响应渲染

9.2 查询生命周期

用户消息 → 消息预处理 → API 请求 → 流式接收 → 响应解析 
    → 工具执行 → 权限检查 → 循环检测 → 响应完成 → 状态保存

9.3 流式处理策略

流式响应采用分块处理：

文本块：直接渲染到终端
工具调用块：触发工具执行流程
思考块：可选显示或隐藏

10. 远程会话系统

10.1 桥接架构

桥接系统支持本地会话与远程终端的同步：

本地会话 (Host) ←WebSocket→ 桥接服务 (Remote) → 远程终端 (Client)

10.2 同步消息类型

消息类型	方向	内容
`system`	双向	连接建立、心跳
`user-message`	上行	用户输入消息
`assistant-message`	下行	AI 响应消息
`tool-use`	下行	工具调用通知
`tool-result`	上行	工具执行结果
`state-sync`	双向	状态同步

10.3 断线重连策略

指数退避重连
会话状态缓存
消息队列重放

11. 技能命令系统

11.1 技能设计理念

技能系统是将复杂操作封装为简单命令的机制：

用户自定义：支持用户编写技能脚本
多源加载：支持用户/项目/全局多来源
组合执行：支持多个工具调用的组合

11.2 技能文件格式

技能文件采用 Markdown + Frontmatter 格式：

---
name: 技能名称
description: 技能描述
version: 1.0.0
---

# 技能执行步骤

1. 第一步操作描述
2. 第二步操作描述
...

11.3 技能来源优先级

用户技能目录：~/.claude/skills/
项目技能目录：.claude/skills/
策略技能目录：系统预设

12. 子代理架构

12.1 设计动机

子代理系统解决复杂任务的并行处理问题：

大任务拆解为小任务
多个子任务并行执行
结果汇总后统一响应

12.2 代理模式

模式	描述	适用场景
General Purpose	通用任务处理	代码搜索、复杂分析
Explore	代码库探索	快速查找文件/模式
Plan	方案设计	架构设计、实现规划

12.3 任务委派流程

主代理接收复杂任务 → 任务分析与拆解 → 创建子代理 → 子代理并行执行 → 结果汇总 → 统一响应给用户

12.4 上下文隔离

每个子代理拥有独立的对话历史、状态副本和工具调用上下文。

13. 性能优化策略

13.1 启动优化

延迟加载：非核心模块按需加载
缓存利用：配置文件缓存解析结果
Bundle 优化：生产环境代码打包压缩，Tree-shaking 移除死代码

13.2 运行时优化

内存管理：历史对话分块存储、大文件流式处理、定期垃圾回收
响应优化：流式响应减少等待、增量渲染提升感知速度、工具调用并行化

13.3 网络优化

MCP 连接：连接池复用、请求批处理、失败重试限制
API 调用：请求压缩、响应缓存、速率限制处理

14. 安全机制设计

14.1 安全分层

第一层：权限控制（工具调用权限检查、文件访问范围限制）
第二层：沙盒隔离（文件系统沙盒、进程执行沙盒）
第三层：审计日志（所有工具调用记录、完整输入输出日志）
第四层：异常检测（循环调用检测、异常频率检测）

14.2 敏感操作保护

以下操作默认需要用户确认：

文件系统写操作
外部进程执行
网络请求
环境变量访问

14.3 安全最佳实践

最小权限：只授予必要的权限
显式确认：敏感操作必须确认
审计日志：保留完整操作记录
定期审查：定期检查权限配置

15. 模块协同工作流

15.1 完整请求处理流程

用户输入 → CLI 层接收 → 查询引擎处理 → 调用 AI API → 流式接收响应
    → 检测到工具调用 → 权限系统检查 → 钩子系统触发 → 工具执行
    → 状态系统更新 → 钩子系统触发 → 查询引擎继续 → 响应完成 → 保存会话状态

15.2 关键协作模式

责任链：请求依次经过多个处理器，每个处理器可修改或中断请求
发布订阅：状态变更通知所有订阅者，UI 组件自动重新渲染
策略模式：不同模式使用不同策略，权限策略、工具策略可插拔

16. 扩展开发指南

16.1 自定义工具开发

定义工具类：实现工具名称和描述、定义输入参数 Schema、实现执行逻辑
注册工具：添加到工具注册表、配置启用条件
测试工具：单元测试、集成测试、权限测试

16.2 钩子开发

选择钩子事件：根据需求选择触发时机
编写钩子逻辑：Shell 命令或脚本、支持异步执行
配置钩子：添加到配置文件、设置执行条件

16.3 MCP 服务器开发

实现 MCP 协议：遵循协议规范、暴露工具和资源
配置连接：添加服务器配置、指定传输方式
测试集成：验证工具调用、验证资源读取

16.4 技能开发

创建技能文件：使用 Markdown 格式、编写 Frontmatter
定义执行步骤：描述工具调用序列、添加条件逻辑
测试技能：在测试项目中使用、验证执行结果

结语

本文档深入剖析了智能编码助手的整体架构设计，涵盖从启动流程到核心模块、从权限管理到扩展开发的完整知识体系。

架构设计的核心思想可总结为：

统一抽象：将所有操作统一为工具调用
分层设计：清晰的层次边界和依赖关系
扩展优先：通过钩子和 MCP 支持无限扩展
安全可控：多层安全防护和权限控制

希望本文档能为开发者理解智能编码助手的设计理念提供帮助，也能为类似系统的设计提供参考。

文档版本：1.0.0
最后更新：2026-04-01

我是程序员虎哥，跟踪学习、不定期同步以 OpenClaw 为代表的 Agent 技术。技术发展应该为劳动者减负，而不应该增加焦虑和内耗~

关注公众号「Agent 扫地僧」，一起探索 agent 技术的边界。