mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 13:55:50 +00:00
c742018b15
保留五层架构框架，将源码追踪改为设计意图分析。 增加层间通信原则、入口概览表和导航指引， 设计原则从 Accordion 展开为独立章节。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
132 lines
6.7 KiB
Plaintext
132 lines
6.7 KiB
Plaintext
---
|
||
title: "架构总览"
|
||
description: "从交互层到通信层，理解 Claude Code 的五层架构设计。每层的职责、边界和设计考量。"
|
||
keywords: ["Claude Code 架构", "五层架构", "Agentic Loop", "数据流"]
|
||
og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
|
||
---
|
||
|
||
## 五层架构
|
||
|
||
Claude Code 从上到下分为五个层次。每一层职责清晰、边界分明，层与层之间通过明确的接口通信。
|
||
|
||
<Frame caption="Claude Code 五层架构">
|
||
<img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
|
||
</Frame>
|
||
|
||
| 层次 | 职责 | 设计考量 |
|
||
|------|------|----------|
|
||
| **交互层** | 终端 UI、用户输入、消息展示 | 为什么用 React/Ink 而不是 readline？因为需要组件化渲染工具权限确认、进度条等复杂 UI |
|
||
| **编排层** | 多轮对话管理、会话持久化、成本追踪 | 为什么需要独立的编排层？因为 agentic loop 本身不应该关心"会话保存"和"token 计费" |
|
||
| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | 这是整个系统的心脏。为什么用 AsyncGenerator？因为流式输出需要逐步 yield，工具执行需要可取消 |
|
||
| **工具层** | AI 的"双手"——读写文件、执行命令等 50+ 工具 | 为什么工具是独立层？因为工具可以动态增减（MCP 扩展），不应该硬编码在核心循环中 |
|
||
| **通信层** | 与 Claude API 的流式通信 | 为什么支持 7 种 Provider？因为不同用户使用不同的 API 端点（直连、AWS Bedrock、Google Vertex 等） |
|
||
|
||
### 层间通信原则
|
||
|
||
- **交互层 → 编排层**：用户消息和指令（如斜杠命令）
|
||
- **编排层 → 核心循环层**：上下文参数（消息历史、工具列表、权限上下文）
|
||
- **核心循环层 → 工具层**：工具调用请求（工具名 + 参数）
|
||
- **工具层 → 核心循环层**：工具执行结果
|
||
- **核心循环层 → 通信层**：API 请求（消息数组 + 系统提示 + 工具定义）
|
||
- **通信层 → 核心循环层**：流式响应事件
|
||
|
||
每层只依赖下一层的接口，不跨层访问。这种约束使得：
|
||
- 通信层可以替换 Provider 而不影响核心循环
|
||
- 工具层可以新增工具而不影响编排逻辑
|
||
- 交互层可以替换为 Web UI 而不影响底层
|
||
|
||
## 核心数据流
|
||
|
||
<Frame caption="核心数据流">
|
||
<img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
|
||
</Frame>
|
||
|
||
整个系统的运转可以浓缩为一条循环数据流。以下是每一步的设计意图：
|
||
|
||
### 1. 用户输入 → 交互层
|
||
|
||
用户输入经过预处理管道：斜杠命令解析、文件附件处理、图片编码等。设计上，输入处理是可扩展的——新的输入类型（如语音）只需要在预处理管道中添加一个处理器。
|
||
|
||
### 2. 交互层 → 编排层
|
||
|
||
编排层是会话的"大脑"。它管理三类关键状态：
|
||
- **对话状态**：消息数组、工具权限上下文——决定 AI 看到什么
|
||
- **成本状态**：token 用量累计——决定何时触发压缩或警告用户
|
||
- **持久化状态**：对话序列化到磁盘——支持会话恢复和 undo
|
||
|
||
### 3. 编排层 → 核心循环（Agentic Loop）
|
||
|
||
核心循环是一个 `while(true)` 的迭代：
|
||
|
||
```
|
||
上下文预处理 → API 调用 → 解析响应 → 工具执行 → 结果回传 → 再次调用 → 循环
|
||
```
|
||
|
||
**上下文预处理管道**是循环中最精巧的部分。在每次 API 调用前，系统会依次检查：
|
||
- 单条工具输出是否过长 → 截断
|
||
- 对话历史是否接近 token 上限 → 自动压缩
|
||
- 是否需要紧急压缩 → API 返回 token 超限错误时触发
|
||
|
||
这套管道确保 AI 始终在有效的上下文窗口内工作。
|
||
|
||
### 4. 核心循环 → 工具层
|
||
|
||
工具执行支持**并行和串行两种模式**。多个独立的工具调用可以并行执行（如同时读两个文件），有依赖关系的调用则串行执行。这个设计直接影响用户体验——并行意味着更快的响应速度。
|
||
|
||
### 5. 工具层 → 核心循环 → 通信层
|
||
|
||
工具执行结果回传到核心循环，拼入消息数组，再次调用 API。AI 根据工具结果决定：
|
||
- 继续调用工具（任务未完成）
|
||
- 返回最终回答（任务完成）
|
||
- 请求用户输入（需要决策）
|
||
|
||
### 6. 终止条件
|
||
|
||
循环不是无限运行的。终止条件包括：
|
||
- AI 不再请求工具调用（任务完成）
|
||
- 用户主动中断
|
||
- 达到最大 turn 数限制
|
||
- Token 预算耗尽
|
||
|
||
## 四个核心设计原则
|
||
|
||
### 流式优先（Streaming-first）
|
||
|
||
所有 API 通信都是流式的。用户看到 AI "逐字打出"回答，工具执行在流式过程中就开始并行执行，不需要等流结束。
|
||
|
||
当模型需要降级（如从 Opus 降到 Sonnet）时，已收集的响应被标记为历史记录，整个流式请求重新发起。
|
||
|
||
### 工具即能力（Tool as Capability）
|
||
|
||
每个工具是一个结构化的类型定义，包含输入验证、权限检查和执行逻辑三个阶段。工具列表在每次 API 调用时动态组装（不是全局缓存），因为工具的可用性可能随运行时状态变化（如 MCP 服务器连接状态）。
|
||
|
||
### 权限即边界（Permission as Boundary）
|
||
|
||
每次工具调用经过"输入验证 → 权限检查"双重检查。权限规则从五个来源汇聚（会话级 → 项目级 → 用户级 → 管理级 → 默认级），优先级从高到低。
|
||
|
||
这个分层设计意味着：团队可以为整个项目设置统一的权限策略（项目级），同时允许个人覆盖（用户级），管理员还可以强制执行安全策略（管理级）。
|
||
|
||
### 上下文即记忆（Context as Memory）
|
||
|
||
System Prompt 在每轮调用时动态组装，包含项目结构、git 状态、用户指令（CLAUDE.md）等信息。组装策略是"不变内容在前、变化内容在后"，利用 API 的前缀缓存机制减少重复计算。
|
||
|
||
自动压缩在每轮迭代前评估 token 阈值，超出时用 AI 自身来总结之前的对话，保留语义信息的同时减少 token 占用。
|
||
|
||
## 入口概览
|
||
|
||
| 入口 | 说明 | 使用场景 |
|
||
|------|------|----------|
|
||
| CLI 启动 | 加载配置、认证、启动 REPL | 日常交互式使用 |
|
||
| 管道模式 | 从 stdin 读取输入，输出到 stdout | 嵌入 CI/CD 和脚本 |
|
||
| 远程控制 | 通过 Bridge API 远程控制 CLI | 从 claude.ai 或手机发送指令 |
|
||
| Daemon 模式 | 长驻后台的 supervisor 进程 | 持续运行的自动化任务 |
|
||
|
||
## 接下来
|
||
|
||
现在你已经理解了整体架构。以下是推荐的深入路径：
|
||
|
||
- **Agent Loop** — 深入核心循环的每一轮迭代细节
|
||
- **工具系统** — 了解 50+ 工具的设计和分类
|
||
- **上下文工程** — 理解 token 预算和自动压缩机制
|
||
- **安全机制** — 了解权限模型和沙箱设计
|