启动链路

职责概述

解决的问题：用户在终端输入 claude 后到出现交互界面，中间需要完成认证、环境检测、配置加载、权限初始化等一系列前置工作。启动链路将这些步骤编排为一条可靠的初始化管道，确保首次安装和日常使用都能快速进入交互状态。

应用场景：① 首次安装后的 OAuth 认证引导 ② 每次启动时的环境检测（Node 版本、终端类型、代理配置）③ 从 CI/CD、IDE 插件、SDK 等不同入口点进入时的差异化初始化 ④ 断线恢复和会话续接。

一句话理解：就像电脑的开机流程——从按下电源键到桌面出现，中间的 BIOS 自检、驱动加载、登录界面都在这一层。

架构设计

核心数据流

// entrypoints/cli.tsx:37-42
if (args.length === 1 && (args[0] === '--version' || ...)) {
  console.log(`${MACRO.VERSION} (Claude Code)`);
  return;
}

// main.tsx:803-812
const isNonInteractive = hasPrintFlag || hasInitOnlyFlag || hasSdkUrl || !process.stdout.isTTY;
setIsInteractive(!isNonInteractive);
initializeEntrypoint(isNonInteractive);
eagerLoadSettings();

// main.tsx:907-967
program.hook('preAction', async thisCommand => {
  await Promise.all([ensureMdmSettingsLoaded(), ensureKeychainPrefetchCompleted()]);
  await init();
  // ... initSinks, loadRemoteManagedSettings, loadPolicyLimits 等
});

// setup.ts:160-161
setCwd(cwd);
captureHooksConfigSnapshot(); // 在 setCwd 之后，确保 hooks 从正确目录加载

// replLauncher.tsx:12-22
export async function launchRepl(root, appProps, replProps, renderAndRun) {
  const { App } = await import('./components/App.js');
  const { REPL } = await import('./screens/REPL.js');
  await renderAndRun(root, <App {...appProps}><REPL {...replProps} /></App>);
}

关键类型与接口

Bootstrap 全局状态 (bootstrap/state.ts)

// bootstrap/state.ts:45-120 (核心字段)
type State = {
  originalCwd: string           // 原始工作目录
  projectRoot: string           // 项目根目录（稳定，不随 worktree 变化）
  sessionId: SessionId          // 当前会话 ID
  isInteractive: boolean        // 是否交互式会话
  clientType: string            // 客户端类型 (cli/sdk/github-action 等)
  modelUsage: { [modelName: string]: ModelUsage }  // 模型使用统计
  // ...遥测、日志、OpenTelemetry 状态
  agentColorMap: Map<string, AgentColorName>  // Agent 颜色映射
  allowedSettingSources: SettingSource[]     // 允许的设置来源
}

AppState 类型 (state/AppStateStore.ts)

// state/AppStateStore.ts:89+
export type AppState = DeepImmutable<{
  settings: SettingsJson
  verbose: boolean
  mainLoopModel: ModelSetting
  toolPermissionContext: ToolPermissionContext
  tasks: Record<string, TaskState>
  mcp: { clients: MCPServerConnection[]; tools: ... }
  speculationState: SpeculationState
  fastMode: FastModeState
  effortValue: EffortValue | undefined
  fileHistory: FileHistoryState
  attribution: AttributionState
  // ... teammate、bridge、denial tracking 等字段
}>

通用状态容器 (state/store.ts)

// state/store.ts:4-34
export type Store<T> = {
  getState: () => T
  setState: (updater: (prev: T) => T) => void
  subscribe: (listener: Listener) => () => void
}
// 不可变比较优化：Object.is(next, prev) 时跳过通知
export function createStore<T>(initialState: T, onChange?: OnChange<T>): Store<T>

AppWrapperProps (replLauncher.tsx)

// replLauncher.tsx:7-11
type AppWrapperProps = {
  getFpsMetrics: () => FpsMetrics | undefined;
  stats?: StatsStore;
  initialState: AppState;
};

设计模式与亮点

1. 渐进式加载与快速路径 (Fast-Path Dispatch)

cli.tsx 采用策略模式分发到十几种快速路径，每种路径只加载所需模块。这利用了 Bun 的 feature() 函数在构建时进行死代码消除（DCE），确保外部构建不包含内部功能。

2. 副作用排序 (Side-Effect Ordering)

main.tsx:1-20 在所有 import 之前执行三个并行副作用：启动性能分析标记、MDM 子进程启动、macOS Keychain 预取。这些操作与其余 135ms 的模块 import 重叠执行，显著减少首屏延迟。

3. 延迟预取 (Deferred Prefetch)

将非首屏必需的预取工作（插件加载、Git 归因钩子、SessionMemory 初始化等）推迟到 startDeferredPrefetches() 在 REPL 渲染后才执行，避免阻塞首次渲染。

4. 不可变状态容器 (Immutable Store)

state/store.ts 实现了一个极简的不可变状态容器：setState 接受 updater 函数返回新状态，通过 Object.is 比较避免不必要通知。AppStateProvider 在 React 层封装并提供 onChangeAppState 回调，实现状态变更的副作用管理（如权限模式变更时通知 SDK）。

5. 信任边界 (Trust Boundary)

系统区分"安全"和"完整"环境变量：applySafeConfigEnvironmentVariables() 在信任对话框之前执行，applyConfigEnvironmentVariables() 在信任确认之后执行。这防止了不受信任的工作目录通过 settings.json 注入危险环境变量。

◈ 可视化处理拓扑图

启动链路是一条漏斗式管线：CLI 入口以零加载代价快速分流特殊路径，未匹配的请求依次经过安全预处理、Commander 注册、全局初始化、环境准备和交互设置，最终启动 REPL。每个快速路径在 cli.tsx 就地返回，只加载自身所需模块。

⇉ 核心处理流程详解

Claude Code 的启动过程采用"漏斗式"架构：先在轻量入口快速分流特殊路径，再逐步加载重量级模块。整个过程从进程启动到 REPL 渲染，经过了 8 个关键阶段，每一层都精心控制了模块加载范围以优化冷启动时间。

★ 设计精华

1. feature() 编译时特性消除

所有功能开关通过 import { feature } from 'bun:bundle' 引入。Bun 打包器在构建时对 feature('XXX') 进行死代码消除——外部构建直接移除内部功能代码块，使产物体积最小化。这比运行时 if 检查更安全：即使代码中引用了内部包名，它们也不会出现在外部构建中。

// entrypoints/cli.tsx:86 — 编译时决定是否包含此代码
if (feature('CHICAGO_MCP') && process.argv[2] === '--computer-use-mcp') {
  const { runComputerUseMcpServer } = await import('../utils/computerUse/mcpServer.js');
  await runComputerUseMcpServer();
  return; // 外部构建中此分支完全不存在
}

2. 快速路径漏斗 — 零加载分派

cli.tsx 是整个系统最薄的一层。它通过字符串匹配 process.argv 快速分流 ~15 个子路径，每个子路径只 await import() 自己需要的模块。这意味着 claude --version 的开销几乎等于一次 console.log，而 claude daemon 完全不会加载 React、权限系统或工具定义。

// cli.tsx:37-41 — 最快的快速路径，零模块加载
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`);
  return; // 不加载 profiler、config、任何业务模块
}

// cli.tsx:100-106 — daemon worker 只加载自己
if (feature('DAEMON') && args[0] === '--daemon-worker') {
  const { runDaemonWorker } = await import('../daemon/workerRegistry.js');
  await runDaemonWorker(args[1]);
  return;
}

3. preAction 延迟初始化钩子

main.tsx:907-967 的 preAction 钩子解决了"何时初始化"的经典问题：用户输入 claude --help 时不需要连接网络、加载设置或初始化遥测——只有真正执行命令（action handler 触发）时才做昂贵操作。这种设计将帮助文本的响应时间从数百毫秒降到数十毫秒。

// main.tsx:907-916
program.hook('preAction', async thisCommand => {
  // 只在真正执行命令时才触发，--help 不会进入这里
  await Promise.all([ensureMdmSettingsLoaded(), ensureKeychainPrefetchCompleted()]);
  await init(); // 全局初始化（配置、网络、遥测）
  // ...
  void loadRemoteManagedSettings(); // 非阻塞，企业设置热加载
  void loadPolicyLimits();           // 非阻塞，策略限制
});

4. 信任门控的安全边界

在恶意仓库中，.claude/settings.json 和 .claude/agents/ 是攻击者可控的。系统在 main.tsx:1042-1048 附近实现了信任门控：checkHasTrustDialogAccepted() 必须在启用 assistant 模式、加载 agent 定义或执行 hooks 之前通过。这确保即使攻击者构造了恶意配置，也不会在用户明确信任工作目录前生效。

// main.tsx:1067-1069
if (!checkHasTrustDialogAccepted()) {
  console.warn('Assistant mode disabled: directory is not trusted.');
} else {
  kairosEnabled = assistantModule.isAssistantForced()
    || (await kairosGate.isKairosEnabled());
  // ... 只有信任后才初始化团队和 agent
}

5. profileCheckpoint 性能遥测管线

启动路径中散布的 profileCheckpoint() 调用（cli.tsx:48,292,296、main.tsx:586,607,885,903,1007 等）构建了一个细粒度的启动时间线。每个 checkpoint 记录时间戳和标签，用于回归检测——如果某次提交导致 cli_before_main_import 到 cli_after_main_import 的时间增长超过阈值，CI 会自动报警。

// cli.tsx 中关键 checkpoint 序列
profileCheckpoint('cli_entry');           // L48: 入口开始
profileCheckpoint('cli_before_main_import'); // L292: 加载 main.tsx 前
profileCheckpoint('cli_after_main_import');  // L296: 加载完成
profileCheckpoint('cli_after_main_complete'); // L298: main() 返回后

// main.tsx 中继续
profileCheckpoint('main_function_start');     // L586
profileCheckpoint('run_function_start');      // L885
profileCheckpoint('preAction_start');         // L908
profileCheckpoint('action_handler_start');    // L1007

◈ Agent 实践借鉴 — 客服 Agent 启动设计

场景映射：客服 Agent 启动时会遇到什么真实问题？

一个客服 Agent 上线时要面对的远不止"加载代码"这么简单。真实痛点是：

• 多系统集成：CRM（查客户画像）、订单系统（查订单详情）、支付系统（查退款状态）、知识库（查商品 FAQ）。这四个系统任何一个连接慢，客户都在等待。
• 渠道差异：电话客服坐席需要 ASR/TTS 通道，在线客服需要富文本消息能力，工单处理只需要后台 API。如果把所有渠道的初始化都跑一遍，50% 的工作是浪费的。
• 冷启动即客户等待：坐席签到后，客户电话就打进来了。如果 Agent 还在连接 CRM，客户听到的是沉默。
• 可选依赖：SMS 通知只在部分渠道开启，情感分析只在电话渠道需要。这些不应该拖慢其他渠道的启动。

借鉴 CC：Claude Code 是怎么解决启动问题的？

CC 的启动是一个"漏斗式"管线：cli.tsx 先做零依赖的快速路径分流（如 --version 直接返回），不匹配快速路径的才进入主初始化管线。主管线内部采用渐进式加载：先展示 REPL 界面 → 再加载工具定义 → 再连接 MCP 服务器。整个过程通过 profileCheckpoint() 在每个阶段打点，方便定位哪个阶段慢了。

// CC 的启动管线（简化）
// cli.tsx: 零依赖快速路径
if (args[0] === '--version') { console.log(VERSION); return; }

// 主路径：渐进式加载
profileCheckpoint('cli_entry');
startCapturingEarlyInput();                // 并行捕获用户输入
const { cliMain } = await import('./main.js');  // ~135ms
profileCheckpoint('cli_after_import');

// main.tsx preAction: 只在命令执行时初始化
program.hook('preAction', async () => {
  await Promise.all([loadMDM(), prefetchKeychain()]);  // 并行预取
  await init();          // 全局初始化（配置、网络、遥测）
  void loadRemoteSettings();  // 发射即忘，不阻塞启动
});

// 最后：渲染 REPL 界面，后台继续加载工具和 MCP
launchRepl();
startDeferredPrefetches();  // 插件、git 状态、skills 延迟加载

客服 Agent 怎么改：多阶段启动管线

借鉴 CC 的渐进式加载思路，但不用 feature flag 编译时消除（客服 Agent 不需要同一份代码出两个构建产物，用运行时配置区分渠道即可）。改造后的启动管线分三个阶段：

// 客服 Agent 多阶段启动管线
type ChannelType = 'phone' | 'online' | 'ticket';

async function bootstrapAgent(channel: ChannelType, config: AgentConfig) {
  const checkpoints = new Map<string, number>();
  const mark = (label: string) => checkpoints.set(label, Date.now());

  // ===== 阶段 1：建立对话能力（类比 CC 的 cli.tsx → 展示 REPL）=====
  // 目标：让坐席看到界面，客户能发消息，即使后面系统还没连上
  mark('stage1_start');
  const chatEngine = initChatEngine(channel);  // 同步，<10ms
  const basicPrompt = buildSystemPrompt(config.basePrompt);
  mark('stage1_complete');
  // 此时坐席已经能看到对话界面，客户消息已能接收（暂存在队列中）

  // ===== 阶段 2：加载业务工具（类比 CC 的工具注册 + REPL 渲染）=====
  // 目标：Agent 能开始处理基础问题（查 FAQ、查知识库）
  mark('stage2_start');
  const baseTools = loadBaseTools();           // 查知识库、查 FAQ、转人工（所有渠道通用）
  const channelTools = loadChannelTools(channel); // 按渠道加载
  // online 渠道才有"发优惠券"，phone 渠道才有"查通话录音"
  const allTools = [...baseTools, ...channelTools];
  mark('stage2_complete');
  // 此时 Agent 已经能回答常见问题、查知识库

  // ===== 阶段 3：连接外部系统（类比 CC 的 MCP 连接 + 延迟预取）=====
  // 目标：Agent 能处理需要外部系统的请求（查订单、查物流、退款）
  // 这些连接异步进行，不阻塞前面的阶段
  mark('stage3_start');
  const externalConnections: Record<string, Promise<any>> = {};

  // 并行连接所有外部系统
  const connectPromises = {
    crm:     connectCRM(config.crmUrl),           // 客户画像
    order:   connectOrderSystem(config.orderUrl),  // 订单查询
    payment: connectPaymentSystem(config.payUrl),  // 退款状态
    sms:     channel === 'online' ? connectSMS(config.smsUrl) : Promise.resolve(null),
    // ↑ SMS 只在在线渠道连接，电话/工单渠道跳过（懒加载）
  };

  // 不等待连接完成，先让 Agent 上线
  // 工具调用时检查连接状态，未就绪则返回"系统加载中，请稍后"
  externalConnections.ready = Promise.allSettled(Object.values(connectPromises))
    .then(() => { mark('stage3_complete'); });

  return {
    chatEngine,
    basicPrompt,
    allTools,
    externalConnections,
    getCheckpoints: () => Object.fromEntries(checkpoints),
  };
}

// 渠道差异化工具加载（运行时配置，不需要编译时 feature flag）
function loadChannelTools(channel: ChannelType): Tool[] {
  const toolMap: Record<ChannelType, string[]> = {
    online: ['sendCoupon', 'sendLink', 'richTextReply'],
    phone:  ['checkCallRecording', 'transferCall'],
    ticket: ['createTicket', 'updateTicket', 'assignTicket'],
  };
  return toolMap[channel].map(name => buildTool(toolDefs[name]));
}

启动遥测：定位"慢在哪里"

// 借鉴 CC 的 profileCheckpoint 模式
// 客服场景需要监控每个阶段的耗时，方便定位启动瓶颈
interface StartupReport {
  totalMs: number;
  stages: {
    stage1_dialogReady: number;   // 目标 < 50ms
    stage2_toolsReady: number;    // 目标 < 200ms
    stage3_externalReady: number; // 目标 < 2000ms（异步，不阻塞）
  };
  channel: ChannelType;
  timestamp: string;
}

// 每次启动上报到监控面板
// 告警规则：stage1 > 100ms 触发 P1 告警（客户等待）
// 告警规则：stage3 的某个系统连接 > 5s 触发 P2 告警（降级服务）

落地清单

代码索引