aiagent/clode/architecture.md

Claude Code 系统架构分析

1. 分层架构

┌─────────────────────────────────────────────────────────────┐
│  CLI Entry Layer  (entrypoints/)                            │
│  cli.tsx → 命令行参数路由、MACRO 注入、启动配置               │
├─────────────────────────────────────────────────────────────┤
│  UI Layer  (screens/ + components/ + ink/)                   │
│  REPL.tsx (900KB) 主导航 | 120+ React/Ink 组件              │
│  终端渲染引擎：ink.tsx (253KB)、screen.ts、output.ts         │
├─────────────────────────────────────────────────────────────┤
│  State Layer  (state/ + context/ + hooks/)                   │
│  AppStateStore 全局状态 | React Context (通知/模态/语音)     │
│  80+ React Hooks (useReplBridge 116KB 最大)                  │
├─────────────────────────────────────────────────────────────┤
│  Business Logic Layer                                       │
│  ┌──────────┬──────────┬──────────┬──────────┬────────────┐ │
│  │ Query    │ Tasks    │ Bridge   │ Memory   │ Skills/    │ │
│  │ Engine   │ System   │ System   │ System   │ Plugins    │ │
│  ├──────────┼──────────┼──────────┼──────────┼────────────┤ │
│  │ Commands │ Tools    │ Hook     │ Cron     │ Voice      │ │
│  │ (60+)    │ (50+)    │ System   │ Scheduler│ System     │ │
│  └──────────┴──────────┴──────────┴──────────┴────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  Services Layer  (services/)                                │
│  Claude API | MCP | OAuth | LSP | Analytics | Voice STT     │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure Layer  (utils/)                             │
│  config | git | file | auth | session | telemetry | ssh     │
│  sandbox | ripgrep | diff | editor | image | terminal       │
└─────────────────────────────────────────────────────────────┘

2. 核心入口启动流程

终端输入: bun run dev
    │
    ▼
src/entry.ts
    │ 注册 bun:bundle polyfill 插件
    ▼
src/main.tsx
    │ 启动 Ink 渲染器，挂载 <App> 组件
    ▼
src/components/App.tsx
    │ 加载配置、认证检查、预检
    │ 根据参数选择渲染屏幕
    ├── 默认: <REPL> (src/screens/REPL.tsx, 900KB)
    ├── doctor: <Doctor>
    ├── resume: <ResumeConversation>
    └── teleport: <TeleportResumeWrapper>

3. 核心模块详解

3.1 QueryEngine (src/QueryEngine.ts)

QueryEngine 是对话引擎的核心，负责：

• API 通信：封装对 Anthropic API 的调用（通过 @anthropic-ai/sdk）
• 上下文管理：构建系统提示词、拼接历史消息、控制 Token 预算
• 工具调用循环：发送用户输入 → 接收响应 → 解析工具调用 → 执行工具 → 回传结果 → 循环
• 会话持久化：flushSessionStorage() 保存到磁盘，recordTranscript() 记录对话
• 错误处理：可重试 API 错误分类、退避重试
• 用量统计：Token 计数、成本计算

QueryEngine 输入输出:
  输入: ProcessUserInputContext (用户消息 + 历史 + 系统提示词)
  输出: Stream<SDKMessage> (助手消息 + 工具调用结果)

3.2 全局状态管理 (src/state/)

AppState (全局单例状态树):
├── messages: Message[]           # 当前会话消息列表
├── tasks: TaskState[]            # 活动任务列表
├── session: SessionInfo          # 会话元数据
├── settings: Settings            # 用户配置
├── toolPermissionContext         # 工具权限模式
├── model: string                 # 当前模型
├── fastMode: boolean             # 快速模式状态
├── thinking: ThinkingConfig      # 思考开关配置
├── statusLine: StatusLineState   # 状态栏信息
├── bridge: BridgeState           # 远程桥接状态
├── voice: VoiceState             # 语音输入状态
└── ui: UIState                   # UI 状态 (全屏/弹窗等)

状态通过 createStore() (基于 React useSyncExternalStore) 实现，配合 AppStateProvider 在组件树中注入。

3.3 REPL 主界面 (src/screens/REPL.tsx)

REPL.tsx 是最大的单个文件（约 900KB），包含整个交互式对话界面：

• 消息列表: VirtualMessageList 虚拟滚动渲染对话
• 输入区域: TextInput / VimTextInput 多行输入 + 补全
• 状态栏: StatusLine 显示模型/成本/任务数等信息
• 模态层: 权限请求、OAuth 流程、设置面板等弹窗
• 键盘导航: 全局快捷键绑定 (KeybindingProviderSetup)

3.4 消息系统 (src/utils/messages.ts, 198KB)

消息是系统的核心数据结构：

Message 类型层级:
├── UserMessage           # 用户输入
├── AssistantMessage      # 模型回复 (含 thinking/content/tool_use)
│   ├── ThinkingBlock     # 扩展思考块
│   ├── TextBlock         # 文本回复
│   └── ToolUseBlock      # 工具调用
├── ToolResult            # 工具执行结果
├── SystemMessage         # 系统级别的消息
├── CompactBoundaryMessage # 压缩边界标记
└── StatusMessage         # 状态更新 (不持久化)

消息处理的辅助模块：

• messages/mappers.ts — Anthropic SDK 消息 ↔ 内部 Message 映射
• messages/systemInit.ts — 构建系统初始化消息
• messagePredicates.ts — 消息类型判断工具函数
• messageQueueManager.ts — 消息队列管理
• groupToolUses.ts — 工具调用分组
• collapseReadSearch.ts — 折叠连续的读/搜索操作

3.5 Bridge 系统 (src/bridge/)

Bridge 系统实现远程会话功能（约 500KB 代码），支持：

• 远程 REPL: replBridge.ts (102KB) — 将本地 REPL 状态同步到远程
• 会话桥接: bridgeMain.ts (118KB) — WebSocket 双向通信
• 消息传递: bridgeMessaging.ts — 结构化消息序列化
• 会话创建: createSession.ts — 远程会话创建流程
• 权限同步: bridgePermissionCallbacks.ts — 远程权限交互
• JWT 认证: jwtUtils.ts — 设备信任和会话认证

Bridge 模式状态机：

DISCONNECTED → CONNECTING → HANDSHAKE → CONNECTED → SYNCED
                                          │
                                          └── RECONNECTING → ...

3.6 Task 系统 (src/tasks/)

Task 类型:
├── LocalMainSessionTask    # 主会话任务 (核心对话)
├── LocalAgentTask          # 子 Agent 任务 (AgentTool 创建)
├── RemoteAgentTask         # 远程 Agent 任务
├── LocalShellTask          # Shell 命令任务 (后台执行)
├── LocalWorkflowTask       # 工作流任务
├── InProcessTeammateTask   # 队友（协程）任务
├── MonitorMcpTask          # MCP 监控任务
└── DreamTask               # "梦想"任务（后台思考）

任务生命周期：

pending → running → completed
                  → failed
                  → cancelled (用户中断)

3.7 终端渲染层 (src/ink/)

对 Ink 框架的深度定制和增强：

模块	大小	功能
ink.tsx	253KB	Ink 主渲染器 (useInput/useStdin/useStdout 等)
screen.ts	50KB	屏幕缓冲区管理
output.ts	26KB	终端输出渲染
selection.ts	35KB	文本选择/复制
render-node-to-output.ts	64KB	虚拟 DOM → ANSI 输出
Ansi.tsx	33KB	ANSI 转义序列处理
log-update.ts	27KB	日志输出更新管理
parse-keypress.ts	24KB	按键解析
reconciler.ts	15KB	React Reconciler 适配
styles.ts	21KB	样式系统 (颜色/边框/布局)
searchHighlight.ts	3KB	搜索高亮

3.8 内存/记忆系统 (src/memdir/)

持久的项目级和用户级记忆：

memdir/
├── memdir.ts              # 核心：加载/保存 MEMORY.md 文件
├── memoryTypes.ts         # 记忆类型定义 (user/feedback/project/reference)
├── findRelevantMemories.ts # 语义检索相关记忆
├── memoryScan.ts          # 扫描记忆目录
├── memoryAge.ts           # 记忆新鲜度计算
├── paths.ts              # 记忆文件路径管理
├── teamMemPaths.ts       # 团队共享记忆路径
└── teamMemPrompts.ts     # 团队记忆提示词拼装

记忆文件格式（位于 ~/.claude/projects/<project>/memory/）：

---
name: <记忆名>
description: <一行描述>
type: user|feedback|project|reference
---

<记忆内容>

4. 组件树（简化版）

<App>
├── <AppStateProvider>              # 全局状态注入
│   ├── <MailboxProvider>           # 消息邮箱
│   ├── <VoiceProvider>             # 语音 (ANT Only)
│   ├── <KeybindingProviderSetup>   # 键盘快捷键
│   ├── <Notifications>             # 通知系统
│   ├── <OverlayProvider>           # 模态层管理
│   │
│   ├── <REPL>                      # 主界面 [仅默认模式]
│   │   ├── <FullscreenLayout>      # 全屏布局容器
│   │   ├── <StatusLine>            # 底部状态栏
│   │   ├── <VirtualMessageList>    # 虚拟滚动消息列表
│   │   │   └── <MessageRow> ×N     # 单条消息行
│   │   │       └── <Message>       # 消息渲染
│   │   │           ├── <Markdown>  # Markdown 渲染
│   │   │           ├── <FileEditToolDiff> # Diff 展示
│   │   │           └── <ToolUseLoader>    # 工具调用动画
│   │   ├── <TextInput>             # 输入框 (支持 Vim 模式)
│   │   ├── <TaskListV2>            # 任务列表面板
│   │   └── <Spinner>               # 加载动画
│   │
│   ├── <Doctor>                    # 诊断界面
│   └── <ResumeConversation>        # 恢复会话界面
│
└── 模态层 (通过 OverlayProvider 按需渲染)
    ├── <PermissionsDialog>
    ├── <ModelPicker>
    ├── <Feedback>
    ├── <Onboarding>
    ├── <SettingsPanel>
    ├── <GlobalSearchDialog>
    └── <ExportDialog>

5. 关键设计模式

5.1 Feature Flag 死代码消除 (DCE)

bun:bundle 的 feature() 函数在构建时进行死代码消除：

import { feature } from 'bun:bundle'

// PROACTIVE=false 时，整个 if 块在构建产物中被移除
if (feature('PROACTIVE')) {
  const proactive = require('./commands/proactive.js').default
}

使用的 Feature Flags 包括： PROACTIVE, KAIROS, VOICE_MODE, DAEMON, BRIDGE_MODE, AGENT_TRIGGERS, MONITOR_TOOL, COMPUTER_USE, CHICAGO_MCP 等。

5.2 ANT/External 双轨制

大量代码通过 process.env.USER_TYPE === 'ant' 区分内部和外部构建：

• 内部版包含更多工具（REPLTool, SuggestBackgroundPRTool）
• 外部版使用 Stub 替代原生模块

5.3 动态 Import

为减少启动时模块加载量，大量使用 await import() 延迟加载：

// cli.tsx 中的 fast-path 模式
async function main() {
  if (args[0] === '--version') {
    console.log(`${MACRO.VERSION}`);
    return;  // 零额外模块加载
  }
  const { profileCheckpoint } = await import('../utils/startupProfiler.js');
  // ...
}

5.4 虚拟滚动

VirtualMessageList (149KB) 实现消息列表的虚拟滚动，支持数十万条消息的高效渲染。

---

本文档基于 2026-06-11 源码状态生成