整体架构

架构总览

Claude Code 采用分层架构，从入口到渲染共分为 6 层：

数据流

一次完整的用户交互流程如下：

模块依赖关系

核心设计模式

1. 延迟加载 (Lazy Loading)

cli.tsx 的快速路径设计使得 --version 等简单命令无需加载完整的 main.tsx（~4700 行）。重型模块如 OpenTelemetry 也通过动态 import() 按需加载。

// cli.tsx — 快速路径
if (args.includes('--version')) {
  console.log(MACRO.VERSION);
  process.exit(0);
  // 不会加载 main.tsx
}

// 只有完整 CLI 路径才加载
const { main: cliMain } = await import('../main.jsx');

2. 特性标志 (Feature Flags)

所有实验性功能通过 feature() 函数控制。在反编译版本中，该函数始终返回 false：

const feature = (_name: string) => false;

// 使用示例
if (feature('BRIDGE_MODE')) {
  // 永远不会执行 — 死代码
  await bridgeMain(args);
}

3. 记忆化初始化 (Memoized Init)

init() 使用 memoize() 包装，确保只执行一次：

export const init = memoize(async (): Promise<void> => {
  enableConfigs();
  applySafeConfigEnvironmentVariables();
  setupGracefulShutdown();
  // ... 20+ 初始化步骤
});

4. 工具即插件 (Tools as Plugins)

每个工具是一个独立目录，遵循统一接口：

interface Tool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  call(input: unknown): Promise<ToolResult>;
  // 可选：React 组件用于渲染结果
}

5. React 驱动的终端 UI

使用 Ink 框架将 React 组件渲染到终端：

// 像写 Web 组件一样写终端 UI
<Box flexDirection="column">
  <Messages messages={messages} />
  <PromptInput onSubmit={handleSubmit} />
</Box>

下一步

• 运行与构建 — 了解 Bun 运行时和构建配置
• 入口与引导 — 深入启动流程