1. Claude Code CLI 架构全景解析
Claude Code CLI 远非一个简单的命令行工具,而是一个功能强大的平台运行时环境。通过分析其源码结构,我们可以清晰地看到它的多入口设计理念和分层架构思想。
1.1 平台运行时的多入口设计
在 src/entrypoints/ 目录中,我们可以看到 Claude Code 支持多种交互方式:
- 终端 CLI (
cli.tsx):最核心的交互入口,提供丰富的命令行功能 - 桌面应用:通过 Bridge 层与 Claude Desktop 无缝连接
- Web 界面:支持远程会话访问
- IDE 扩展:为 VS Code 和 JetBrains 系列 IDE 提供深度集成
- 编程 SDK:通过
QueryEngine.ts暴露的无头 API - MCP 服务器 (
mcp.ts):作为被集成方提供服务
所有这些入口最终都会汇聚到同一个 QueryEngine,共享统一的工具注册表、权限系统和记忆存储(CLAUDE.md)。这种设计使得用户可以在不同环境中获得一致的体验。
1.2 五层架构设计哲学
Claude Code 的代码组织采用了清晰的五层分离架构:
- 入口层:处理不同环境的用户交互
- UI 渲染层:负责信息的可视化展示
- 业务逻辑层:实现核心功能
- 引擎层:提供基础服务
- 工具层:各种具体功能的实现
这种分层设计的核心理念是:每一层只依赖它下面的层。入口层不需要了解具体工具的实现,引擎层不关心 UI 渲染方式,工具层不知道自己会被哪个入口调用。这种解耦设计使得系统能够在不修改核心引擎的前提下,快速接入新的入口点。
提示:这种架构模式特别适合需要支持多种交互方式的复杂应用,开发者可以专注于某一层的开发而不必担心影响其他部分。
1.3 核心数据流分析
一次用户查询在系统中的完整生命周期遵循以下路径:
- 用户输入通过某个入口进入系统
- 输入被转换为统一的内部表示
- 查询引擎处理请求
- 可能需要调用各种工具
- 结果返回给原始入口
- 入口以适当方式呈现结果
这种数据流设计确保了无论通过哪种方式访问系统,都能获得一致的处理逻辑和结果。
1.4 Agent 循环的本质
在 query.ts 中,我们可以看到 Claude Code 的核心是一个简单的循环结构:
code复制User → messages[] → Claude API → response
│
stop_reason == "tool_use"?
/ \
yes no
│ │
execute tools return text
append tool_result
loop back ──────────────────> messages[]
这个看似简单的循环上,Claude Code 构建了包括权限检查、流式执行、并发调度、上下文压缩等在内的 12+ 个子系统。这种设计哲学告诉我们:不要替换简单的东西,而是在它上面生长复杂的功能。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码目录深度解析
2.1 项目目录结构概览
Claude Code 的源码组织非常清晰,主要目录结构如下:
code复制src/
├── main.tsx # REPL 引导入口
├── query.ts # 核心 Agent 循环
├── QueryEngine.ts # 查询生命周期引擎
├── Tool.ts # 工具接口定义
├── tools.
