01 — 总架构概览

一句话描述

Claude Code 是一个 基于终端的交互式 AI 编程助手，用 TypeScript (Bun) 编写，采用 React (Ink) 渲染 TUI，通过 Anthropic API 与 Claude 模型交互，并提供丰富的 Tool / MCP / LSP / Agent 能力。

分层架构

整个系统可以分为 五个层次，从上到下依次是：入口层、UI 层、核心逻辑层、服务层、基础设施层。理解这五层之间的职责边界和交互方式，是阅读整个代码库的前提。

层间交互原则

入口层决定运行模式（交互式 REPL / 非交互 --print / SDK 嵌入 / MCP 服务端），但所有模式最终都通过 Query 循环 与 Claude API 通信。
UI 层只负责渲染和用户输入采集，不直接调用 API。它通过 State Store 获取数据，通过回调函数触发操作。
核心逻辑层是真正的大脑：query.ts 驱动对话循环，Tool 系统处理模型的工具调用，Command 系统处理用户的斜杠命令。
服务层封装所有外部通信（API、MCP、LSP），以及内部的上下文压缩（Compact）和遥测（Analytics）。
基础设施层提供运行环境支撑：IDE 集成（Bridge）、远程会话（Remote）、多 Agent 协作（Swarm）、沙箱隔离（Sandbox）、用户钩子（Hooks）。

核心数据流 — 一个完整对话轮次

理解 Claude Code 最重要的一件事是：每个对话轮次都是一个 query() 生成器函数的一次完整执行。以下时序图展示了从用户输入到最终回复的完整流程：

关键设计决策

这个数据流中有几个值得注意的设计决策：

query.ts 是生成器（AsyncGenerator），不是简单的 async 函数。它通过 yield 向 REPL 实时推送事件，同时在内部维护一个状态机来处理多轮对话、错误恢复和上下文压缩。
Tool 执行是在 API streaming 期间就开始的。StreamingToolExecutor 在接收到 tool_use 块后立即入队执行，而不是等整个 API 响应结束。这样只读工具可以与模型的后续输出并行执行。
权限检查是"四方竞速"模式：IDE Bridge、移动端 Channel、用户 Hook、ML 分类器同时运行，第一个返回结果的胜出（通过原子性 claim() 保证唯一决策）。

目录结构总览

src/
├── main.tsx                 # [入口] CLI 主入口，Commander.js 参数解析
├── setup.ts                 # [入口] 会话初始化 (Git root, Session ID, Hooks)
├── replLauncher.tsx          # [入口] REPL 启动桥接
├── query.ts                  # [核心] 对话循环生成器 (最重要的文件之一)
├── Tool.ts                   # [核心] Tool 接口 + ToolUseContext 定义
├── commands.ts               # [核心] Command 注册中心
├── context.ts                # [核心] System/User context 构建 (Git, CLAUDE.md)
├── history.ts                # [核心] 命令历史
│
├── entrypoints/              # [入口] CLI / SDK / MCP 入口点
├── screens/                  # [UI] 全屏视图 (REPL, Doctor, Resume)
├── state/                    # [状态] AppState Store + Selectors
├── ink/                      # [UI] 自研终端渲染引擎 (Yoga, DOM, 事件)
├── components/               # [UI] 100+ React 组件
├── hooks/                    # [UI] 80+ React Hooks
├── context/                  # [UI] React Context Providers
│
├── tools/                    # [工具] 30+ 内置工具实现
├── commands/                 # [命令] 90+ 斜杠命令实现
├── services/                 # [服务] API / MCP / LSP / Analytics / Compact...
├── tasks/                    # [任务] 后台任务系统
│
├── bridge/                   # [基建] IDE Bridge (远程控制)
├── remote/                   # [基建] Remote Session
├── server/                   # [基建] Direct Connect Server
├── cli/                      # [IO] CLI 输出 / 结构化 IO / 传输层
│
├── utils/                    # [工具] 工具函数 (最大的目录)
│   ├── settings/             #   配置管理 (分层: MDM > Remote > User > Project)
│   ├── permissions/          #   权限逻辑
│   ├── swarm/                #   Multi-agent Swarm
│   ├── hooks/                #   用户钩子执行
│   ├── sandbox/              #   沙箱隔离
│   ├── git/                  #   Git 操作
│   ├── model/                #   模型选择/切换
│   ├── messages/             #   消息处理/序列化
│   └── ...                   #   (30+ 子目录)
│
├── skills/                   # [扩展] Skill 系统 (可复用 prompt 模板)
├── plugins/                  # [扩展] 插件系统
├── keybindings/              # [辅助] 快捷键系统
├── memdir/                   # [辅助] 持久化 Memory 系统
├── vim/                      # [辅助] Vim 编辑模式
├── voice/                    # [辅助] 语音输入
├── buddy/                    # [彩蛋] 虚拟伙伴精灵
├── migrations/               # [运维] 配置迁移脚本
├── schemas/                  # [类型] JSON Schema
├── constants/                # [类型] 常量定义
├── types/                    # [类型] TypeScript 类型
├── native-ts/                # [底层] 原生 TS 实现 (Yoga Layout, Color Diff)
├── coordinator/              # [实验] Coordinator 模式
├── assistant/                # [实验] Assistant (Kairos) 模式
├── outputStyles/             # [配置] 输出风格
├── query/                    # [配置] Query 引擎配置
├── moreright/                # [UI] 扩展右侧面板
└── upstreamproxy/            # [网络] 上游代理

核心设计理念

理念	说明
Tool-Centric	一切能力都抽象为 Tool。模型通过 `tool_use` 驱动操作，人类通过 UI 确认权限。扩展 Claude Code 的首选方式是添加新 Tool（通过 MCP 或 Plugin）。
Permission-First	每个写操作都必须通过权限系统审核。权限决策支持四种来源竞速，确保安全的同时不阻塞自动化场景。
Streaming-Everything	API 调用全部 streaming，工具执行结果实时 yield，UI 实时渲染。用户永远不会看到"空白等待"。
Generator-based Query Loop	`query.ts` 使用 `AsyncGenerator` 实现协程式状态机，支持 6 种错误恢复路径（413 压缩、token 上限升级、多轮恢复、Hook 阻塞等）。
Compile-time Feature Flags	通过 `bun:bundle` 的 `feature()` 在构建时消除死代码，不同发行版本可以包含不同功能（Coordinator、Kairos、Voice 等）。
四大扩展点	MCP（外部工具服务器）、Skills（可复用 prompt）、Plugins（完整扩展包）、Hooks（Shell 钩子）——覆盖从轻量到重量的所有扩展需求。

01 — 总架构概览 ​

一句话描述 ​

分层架构 ​

层间交互原则 ​

核心数据流 — 一个完整对话轮次 ​

关键设计决策 ​

目录结构总览 ​

核心设计理念 ​