1 · 入口层与启动流程

这一章讲：你在终端敲下 claude 到界面出现之间，程序做了什么。

1.1 四种启动形态

同一个可执行文件，根据参数进入四种完全不同的运行模式：

1.2 启动的第一个设计：快路径分派

entrypoints/cli.tsx 是真正的程序入口，只有 302 行。它的注释开门见山：

为什么这很重要

先解释一个背景概念：JavaScript 程序在「导入」一个模块时，那个模块的顶层代码会立刻执行。如果一个程序静态导入了几百个模块，那么光是启动就要把这几百个模块全部执行一遍，即使这次运行根本用不到它们。

Claude Code 打包后是一个 300 MB 的单文件程序，模块数量极其庞大。如果每次运行都全量加载，claude --version 这种只想看一眼版本号的命令也要等好几秒。

所以入口文件用的是动态导入 —— 只有真的走到某条分支时，才去加载那条分支需要的模块：

async function main(): Promise<void> {
  const args = process.argv.slice(2);          // 取命令行参数

  // 快路径 1：--version，零模块加载
  if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
    console.log(`${MACRO.VERSION} (Claude Code)`);   // 版本号在编译期就被写死进来了
    return;                                     // 直接返回，什么都没加载
  }

  // 其余路径才加载启动性能分析器
  const { profileCheckpoint } = await import('../utils/startupProfiler.js');
  profileCheckpoint('cli_entry');               // 打一个时间戳

  // 快路径 2：--dump-system-prompt（导出系统提示词，用于评测）
  if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {
    const { enableConfigs } = await import('../utils/config.js');
    ...
    return;
  }

  // 快路径 3：浏览器扩展的本地宿主进程
  if (process.argv[2] === '--claude-in-chrome-mcp') { ... return; }

  // 快路径 4：守护工作进程（由主进程派生，对性能敏感）
  if (feature('DAEMON') && args[0] === '--daemon-worker') {
    const { runDaemonWorker } = await import('../daemon/workerRegistry.js');
    await runDaemonWorker(args[1]);
    return;
  }
  ...
  // 全部快路径都不匹配 → 加载完整的命令行程序
}

claude-code/src/entrypoints/cli.tsx

MACRO.VERSION 里的 MACRO 是编译期宏 —— 打包时被替换成字面量字符串。所以拿版本号连读配置文件都不需要。

1.3 命令行参数：60 多个选项

完整的命令行接口定义在 main.tsx 里，用的是 Commander.js 这个库。选项数量非常多，下面按用途分组梳理：

模式与输入输出

权限与安全

模型与预算

会话与恢复

扩展与集成

1.4 --bare：一个值得单独讲的极简模式

这个选项的官方描述很长，值得逐条拆开看，因为它等于列出了「一次正常启动到底做了多少额外的事」：

反过来读这句话，正常启动时会做这些事：

--bare 模式还有一个关键的行为改变，描述里写得很明确：

1.5 启动时序

走完快路径分派之后，完整启动大致是这个顺序：

1.6 系统提示词的三段结构

第 ⑦ 步返回的三个部分不是随意划分的，它们对应三个不同的缓存稳定性等级：

对应的代码在主循环里是这样调用的：

// query.ts
const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext)     // 系统提示词 + 系统上下文
)
...
messages: prependUserContext(messagesForQuery, userContext)   // 用户上下文 + 消息