第3章 · 启动系统与多模式架构
第3章 · 启动系统与多模式架构
3.1 入口点 cli.tsx
Claude Code的启动从 entrypoints/cli.tsx 开始。这个文件实现了一套多层快速路径（Fast Path）系统，其设计哲学是：尽可能早地判断用户意图，尽可能少地加载代码。
启动流程可以分为三个阶段：
阶段一：零导入检查（<5ms）
// 在任何模块导入之前执行
if (args.includes('--version') || args.includes('-v')) {
// 直接从编译时常量读取，不加载任何模块
console.log(VERSION);
process.exit(0);
}这个优化把最常见的CI场景（claude --version 检查）压缩到了毫秒级。不加载任何模块，不初始化任何服务。
阶段二：模式分流（10+ 快速路径）
在加载完整初始化逻辑之前，cli.tsx 会检查一系列特殊模式：
--daemon-worker：Daemon工作进程模式remote-control/rc/bridge：Bridge远程控制模式--dump-system-prompt：导出系统提示（调试用）mcp：MCP服务器模式sdk：SDK入口模式
每种模式有独立的快速启动路径，避免加载不必要的模块。
阶段三：完整初始化
对于需要完整功能的模式（交互式、无头等），进入三步初始化：
init() → setup() → main()init() 负责：配置加载、环境变量设置、网络初始化、后台任务启动（MDM轮询、钥匙链访问、API预连接并行执行）。
setup() 负责：会话初始化、工作树创建、钩子配置、权限检查、Trust对话框。
main() 负责：模式检测、命令/Agent加载、工具库构建、REPL启动。
3.2 编译时特性标志系统
这是理解Claude Code架构的关键。源码使用Bun的 bun:bundle 模块实现编译时条件分支：
import { feature } from 'bun:bundle';
if (feature('KAIROS')) {
const assistantModule = require('./assistant/index.js');
// 这整块代码在外部版本中物理不存在
}Bun打包器在编译时将 feature() 调用替换为常量布尔值，然后通过Dead Code Elimination将不可达的分支彻底移除。这不是运行时的条件跳过——是编译产物中物理上不存在这些代码。
16个主要特性标志完整清单：
| # | 特性标志 | 功能描述 | 出现文件数 | 出现次数 |
|---|---|---|---|---|
| 1 | KAIROS | 7×24自主助手模式 | 57 | 158 |
| 2 | KAIROS_BRIEF | 精简交互视图 | 12 | ~20 |
| 3 | KAIROS_CHANNELS | MCP通道通知 | 5 | ~8 |
| 4 | KAIROS_PUSH_NOTIFICATION | 推送通知 | 3 | ~5 |
| 5 | KAIROS_GITHUB_WEBHOOKS | GitHub事件订阅 | 2 | ~3 |
| 6 | KAIROS_DREAM | 自主做梦/记忆 | 2 | ~3 |
| 7 | COORDINATOR_MODE | 多Agent协调器 | 15 | 32 |
| 8 | BRIDGE_MODE | 远程控制系统 | 8 | ~15 |
| 9 | VOICE_MODE | 语音交互 | 5 | ~10 |
| 10 | PROACTIVE | 主动式Agent | 10 | ~20 |
| 11 | ULTRAPLAN | 远程浏览器规划 | 3 | ~5 |
| 12 | TRANSCRIPT_CLASSIFIER | AI权限分类器 | 5 | ~8 |
| 13 | WORKFLOW_SCRIPTS | 工作流脚本 | 3 | ~5 |
| 14 | TEAMMEM | 团队记忆共享 | 4 | ~6 |
| 15 | CCR_MIRROR | CCR镜像同步 | 2 | ~3 |
| 16 | BUDDY | 虚拟宠物系统 | 2 | ~3 |
此外还有73个次要/内部特性标志（如AGENT_TRIGGERS, MONITOR_TOOL, FORK_SUBAGENT, UDS_INBOX, TORCH, ULTRATHINK, ULTRAPLAN等），代码库中共计89个特性标志。完整清单详见附录B。
3.3 10种运行模式
Claude Code的单一代码库支持以下运行模式：
1. 交互模式（Interactive） —— 默认模式。用户在终端中与Claude对话，支持完整的TUI界面、工具调用、权限审批。
2. 无头模式（Headless / Print） —— 通过 -p 参数触发。无TUI界面，直接输出结果到stdout。用于脚本集成和CI/CD流水线。
3. Bridge远程控制 —— 通过 claude bridge 子命令启动。接受来自手机/Web的远程连接，允许远程操控CLI。
4. KAIROS助手模式 —— 通过 claude assistant 子命令启动。7×24小时自主运行的AI助手，通过GitHub Webhook和MCP Channel感知环境变化，主动执行任务。
5. Coordinator协调器 —— 通过 --agent-teams 参数启动。一个Leader Claude协调多个Worker Claude并行工作。
6. Daemon守护进程 —— 通过 --daemon-worker 启动。后台常驻进程，接收调度任务。
7. 语音模式（Voice） —— 通过 /voice 命令激活。使用 voice_stream 端点实现实时语音对话。
8. SDK模式 —— 通过 entrypoints/sdk/ 入口。为第三方开发者提供编程式API。
9. MCP服务器模式 —— 通过 claude mcp 启动。Claude Code自身作为MCP服务器运行，供其他MCP客户端调用。
10. SSH远程模式 —— 通过 claude ssh <host> 启动。在远程主机上启动Claude Code会话。
3.4 main.tsx 逐段解读
main.tsx 是整个应用的心脏，4,683行代码。其核心流程可以分为以下阶段：
行1-100：模块导入与条件加载
const coordinatorModeModule = feature('COORDINATOR_MODE')
? require('./coordinator/coordinatorMode.js') : null;
const assistantModule = feature('KAIROS')
? require('./assistant/index.js') : null;使用 require() 而非 import 是有意为之——这是Lazy Require模式，用于打破循环依赖并延迟模块加载。
行100-500：CLI参数解析
使用Commander.js构建命令行参数。特性标志门控的选项通过条件添加：
if (feature('PROACTIVE') || feature('KAIROS')) {
program.addOption(new Option('--proactive', '...'));
}行500-1000：初始化阶段
并行执行：MDM策略获取、钥匙链访问、API预连接、GrowthBook初始化。Terminal.app和iTerm2的备份自动恢复也在此阶段执行。
行1000-2000：模式激活
KAIROS激活路径、Coordinator模式检测、Proactive模式设置、Brief模式配置。这是特性标志密度最高的区域。
行2000-3000：工具库构建
调用 tools.ts 的 getAllBaseTools() 构建工具池，应用权限过滤，配置延迟加载。
行3000-4000：REPL启动
根据模式选择进入交互式REPL、无头模式、Bridge模式或KAIROS模式。
行4000-4683：辅助函数
Proactive激活、Brief激活、CLI解析辅助等。