claude-code/learn/phase-1-startup-flow.md

# 第一阶段：启动流程详解

> 从 `bun run dev` 到用户看到交互界面的完整路径

## 启动链路总览

```
bun run dev
  → package.json scripts.dev: "bun run src/entrypoints/cli.tsx"
    → cli.tsx: polyfill 注入 + 快速路径检查
      → import("../main.jsx") → cliMain()
        → main.tsx: main() → run()
          → Commander 参数解析 → preAction 钩子
            → action handler: 服务初始化 → showSetupScreens
              → launchRepl()
                → replLauncher.tsx: <App><REPL /></App>
                  → REPL.tsx: 渲染交互界面，等待用户输入
```

---

## 1. cli.tsx（321 行）— 入口与快速路径分发

**文件路径**: `src/entrypoints/cli.tsx`

### 1.1 全局 Polyfill（第 1-53 行）

模块加载时立即执行的 side-effect，在 `main()` 之前运行。

#### feature() 桩函数（第 3 行）

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

原版 Claude Code 构建时，Bun bundler 通过 `bun:bundle` 提供 `feature()` 函数，用于**编译时 feature flag**（类似 C 的 `#ifdef`）。反编译版没有构建流程，所以直接定义为永远返回 `false`。

**效果**：所有 Anthropic 内部功能分支全部禁用，包括：
- `COORDINATOR_MODE` — 协调器模式
- `KAIROS` — 助手模式
- `DAEMON` — 后台守护进程
- `BRIDGE_MODE` — 远程控制
- `SSH_REMOTE` — SSH 远程
- `BG_SESSIONS` — 后台会话
- ... 等 20+ 个 flag

#### MACRO 全局对象（第 4-14 行）

```ts
globalThis.MACRO = {
    VERSION: "2.1.888",
    BUILD_TIME: new Date().toISOString(),
    FEEDBACK_CHANNEL: "",
    ISSUES_EXPLAINER: "",
    NATIVE_PACKAGE_URL: "",
    PACKAGE_URL: "",
    VERSION_CHANGELOG: "",
};
```

原版构建时 Bun 会把这些值内联到代码里。这里模拟注入，让后续代码读 `MACRO.VERSION` 时能拿到值。

#### 构建常量（第 16-18 行）

```ts
BUILD_TARGET = "external";   // 标记为"外部"构建（非 Anthropic 内部）
BUILD_ENV = "production";    // 生产环境
INTERFACE_TYPE = "stdio";    // 标准输入输出模式
```

这三个全局变量在代码各处被读取，用来区分运行环境。`"external"` 意味着很多 `("external" as string) === 'ant'` 的检查会返回 false。

#### 环境修补（第 22-33 行）

- 禁用 corepack 自动 pin（防止污染 package.json）
- 远程模式下设置 Node.js 堆内存上限 8GB

#### ABLATION_BASELINE（第 40-53 行）

```ts
if (feature("ABLATION_BASELINE") && ...) { ... }
```

`feature()` 返回 false，**永远不执行**。Anthropic 内部 A/B 测试代码。

### 1.2 main() 函数（第 60-317 行）

设计模式：**分层快速路径（fast path cascading）**——按开销从低到高逐级检查，命中即返回。

#### 快速路径列表

| 优先级 | 行号 | 检查条件 | 功能 | 开销 | 可执行 |
|--------|------|---------|------|------|--------|
| 1 | 64-72 | `--version` / `-v` | 打印版本号退出 | **零 import** | 是 |
| 2 | 81-94 | `feature("DUMP_SYSTEM_PROMPT")` | 导出系统提示 | - | 否（flag） |
| 3 | 95-99 | `--claude-in-chrome-mcp` | Chrome MCP 服务 | 动态 import | 是 |
| 4 | 101-105 | `--chrome-native-host` | Chrome Native Host | 动态 import | 是 |
| 5 | 108-116 | `feature("CHICAGO_MCP")` | Computer Use MCP | - | 否（flag） |
| 6 | 123-127 | `feature("DAEMON")` | Daemon Worker | - | 否（flag） |
| 7 | 133-178 | `feature("BRIDGE_MODE")` | 远程控制 | - | 否（flag） |
| 8 | 181-190 | `feature("DAEMON")` | Daemon 主进程 | - | 否（flag） |
| 9 | 195-225 | `feature("BG_SESSIONS")` | ps/logs/attach/kill | - | 否（flag） |
| 10 | 228-240 | `feature("TEMPLATES")` | 模板任务 | - | 否（flag） |
| 11 | 244-253 | `feature("BYOC_ENVIRONMENT_RUNNER")` | BYOC 运行器 | - | 否（flag） |
| 12 | 258-264 | `feature("SELF_HOSTED_RUNNER")` | 自托管运行器 | - | 否（flag） |
| 13 | 267-293 | `--tmux` + `--worktree` | tmux worktree | 动态 import | 是 |

#### 参数修正（第 296-307 行）

```ts
// --update/--upgrade → 重写为 update 子命令
if (args[0] === "--update") process.argv = [..., "update"];
// --bare → 设置简单模式环境变量
if (args.includes("--bare")) process.env.CLAUDE_CODE_SIMPLE = "1";
```

#### 最终出口（第 310-316 行）

```ts
const { startCapturingEarlyInput } = await import("../utils/earlyInput.js");
startCapturingEarlyInput();           // 捕获用户提前输入的内容
const { main: cliMain } = await import("../main.jsx");
await cliMain();                      // 进入 main.tsx 重型初始化
```

所有快速路径都没命中时（99% 的情况），才走到这里。

### 1.3 启动（第 320 行）

```ts
void main();
```

`void` 表示不关心 Promise 返回值。

### 1.4 关键设计思想

- **快速路径**：`--version` 零开销返回，不加载任何模块
- **动态 import**：`await import()` 替代静态 import，每条路径只加载自己需要的模块
- **feature flag 过滤**：`feature()` 返回 false 使大量内部功能成为死代码

---

## 2. main.tsx（4683 行）— 重型初始化与 Commander CLI

**文件路径**: `src/main.tsx`

整个项目最大的单文件，但结构清晰：**辅助函数 → main() → run()**。

### 2.1 Import 区（第 1-215 行）

200+ 行 import，加载几乎所有子系统。关键的是前三个 **side-effect import**（import 即执行）：

```ts
// 第 9 行：记录时间戳
profileCheckpoint('main_tsx_entry');

// 第 16 行：启动 MDM 子进程读取（macOS plutil）
startMdmRawRead();

// 第 20 行：启动 keychain 预读取（OAuth token、API key）
startKeychainPrefetch();
```

这三个在 import 阶段就**并行启动子进程**，和后续 ~135ms 的模块加载同时进行——**用并行隐藏延迟**。

### 2.2 辅助函数（第 216-584 行）

| 函数 | 行号 | 作用 |
|------|------|------|
| `logManagedSettings()` | 216 | 记录企业托管设置到分析日志 |
| `isBeingDebugged()` | 232 | 检测调试模式，**外部构建下直接 exit(1)**（第 266 行） |
| `logSessionTelemetry()` | 279 | Session 遥测（技能、插件） |
| `getCertEnvVarTelemetry()` | 291 | SSL 证书环境变量收集 |
| `runMigrations()` | 326 | 数据迁移（模型重命名、设置格式升级等） |
| `prefetchSystemContextIfSafe()` | 360 | 信任关系建立后安全预取系统上下文 |
| `startDeferredPrefetches()` | 388 | REPL 首次渲染后的延迟预取 |
| `eagerLoadSettings()` | 502 | 在 init() 之前提前加载 `--settings` 参数 |
| `initializeEntrypoint()` | 517 | 根据运行模式设置 `CLAUDE_CODE_ENTRYPOINT` |

还有 `_pendingConnect`、`_pendingSSH`、`_pendingAssistantChat` 三个状态变量（第 542-583 行），用于暂存子命令参数。

### 2.3 main() 函数（第 585-856 行）

`main()` 本身不长，做完环境检测后调用 `run()`：

```
main()
├── 安全设置（NoDefaultCurrentDirectoryInExePath）
├── 信号处理（SIGINT → exit, exit → 恢复光标）
├── feature flag 保护的特殊路径（全部跳过）
├── 检测 -p/--print / --init-only → 判断是否交互模式
├── clientType 判断（cli / sdk-typescript / remote / github-action 等）
├── eagerLoadSettings()
└── await run()  ← 进入真正的逻辑
```

### 2.4 run() 函数（第 884-4683 行）

占 3800 行，是整个文件的核心。

#### Commander 初始化 + preAction 钩子（第 884-967 行）

```ts
const program = new CommanderCommand()
    .configureHelp(createSortedHelpConfig())
    .enablePositionalOptions();
```

**preAction 钩子**（所有命令执行前都会运行）：

```
preAction
├── await ensureMdmSettingsLoaded()         ← 等 MDM 子进程完成
├── await ensureKeychainPrefetchCompleted() ← 等 keychain 预读完成
├── await init()                             ← 一次性初始化
├── initSinks()                              ← 分析日志接收器
├── runMigrations()                          ← 数据迁移
├── loadRemoteManagedSettings()              ← 企业远程设置（非阻塞）
└── loadPolicyLimits()                       ← 策略限制（非阻塞）
```

#### 主命令 Option 定义（第 968-1006 行）

定义了 40+ CLI 参数，关键的包括：

| 参数 | 作用 |
|------|------|
| `-p, --print` | 非交互模式，输出后退出 |
| `--model <model>` | 指定模型（如 sonnet、opus） |
| `--permission-mode <mode>` | 权限模式 |
| `-c, --continue` | 继续最近对话 |
| `-r, --resume` | 恢复指定对话 |
| `--mcp-config` | MCP 服务器配置文件 |
| `--allowedTools` | 允许的工具列表 |
| `--system-prompt` | 自定义系统提示 |
| `--dangerously-skip-permissions` | 跳过所有权限检查 |
| `--output-format` | 输出格式（text/json/stream-json） |
| `--effort <level>` | 推理努力级别（low/medium/high/max） |
| `--bare` | 最小模式 |

#### action 处理器（第 1006-3808 行）

主命令的执行逻辑，内部按阶段和场景分支：

```
action(async (prompt, options) => {
    │
    ├── [1007-1600] 参数解析与预处理
    │   ├── --bare 模式
    │   ├── 解析 model / permission-mode / thinking / effort
    │   ├── 解析 MCP 配置、工具列表、系统提示
    │   └── 初始化工具权限上下文
    │
    ├── [1600-2220] 服务初始化
    │   ├── MCP 客户端连接
    │   ├── 插件加载 + 技能初始化
    │   ├── 工具列表组装
    │   └── 初始 AppState 构建
    │
    ├── [2220-2315] UI 初始化（交互模式）
    │   ├── createRoot() — 创建 Ink 渲染根节点
    │   ├── showSetupScreens() — 信任对话框、OAuth 登录、引导
    │   └── 登录后刷新各种服务
    │
    ├── [2315-2582] 后续初始化
    │   ├── LSP 管理器、插件版本管理
    │   ├── session 注册、遥测日志
    │   └── 遥测上报
    │
    ├── [2584-3050] --print 非交互模式分支
    │   ├── 构建 headless AppState + store
    │   └── 交给 print.ts 执行
    │
    └── [3050-3808] 交互模式：启动 REPL（7 个分支）
        ├── --continue      → 加载最近对话 → launchRepl()
        ├── DIRECT_CONNECT  → ❌ flag 关闭
        ├── SSH_REMOTE      → ❌ flag 关闭
        ├── KAIROS assistant → ❌ flag 关闭
        ├── --resume <id>   → 恢复指定对话 → launchRepl()
        ├── --resume 无 ID  → 显示对话选择器
        └── 默认（无参数）  → launchRepl()  ★最常走的路径
})
```

#### 子命令注册（第 3808-4683 行）

| 子命令 | 行号 | 作用 |
|--------|------|------|
| `claude mcp` | 3892 | MCP 服务器管理（serve/add/remove/list/get） |
| `claude server` | 3960 | Session 服务器（❌ flag 关闭） |
| `claude auth` | 4098 | 认证管理（login/logout/status/token） |
| `claude plugin` | 4148 | 插件管理（install/uninstall/list/update） |
| `claude setup-token` | 4267 | 设置长期认证 token |
| `claude agents` | 4278 | 列出已配置的 agents |
| `claude doctor` | 4346 | 健康检查 |
| `claude update` | 4362 | 检查更新 |
| `claude install` | 4394 | 安装原生构建 |
| `claude log` | 4411 | 查看对话日志（内部） |
| `claude completion` | 4491 | Shell 自动补全 |

最后执行解析：

```ts
await program.parseAsync(process.argv);
```

### 2.5 main.tsx 学习建议

- **不要通读**。记住三段结构：辅助函数 → main() → run()
- `feature()` 返回 false 的分支全部跳过，可忽略 50%+ 代码
- `("external" as string) === 'ant'` 的分支也跳过（内部构建专用）
- 需要深入某功能时，通过搜索定位对应代码段

---

## 3. replLauncher.tsx（22 行）— 胶水层

**文件路径**: `src/replLauncher.tsx`

极其简单，就做一件事：

```tsx
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>);
}
```

- `App` — 全局 Provider（AppState、Stats、FpsMetrics）
- `REPL` — 交互界面组件
- `renderAndRun` — 把 React 元素渲染到 Ink 终端

动态 import 保持了按需加载的策略。

---

## 4. REPL.tsx（5009 行）— 交互界面

**文件路径**: `src/screens/REPL.tsx`

项目第二大文件，是用户直接交互的界面。一个巨型 React 函数组件。

### 4.1 文件结构

```
REPL.tsx (5009 行)
├── [1-310]     Import 区（150+ import）
├── [312-525]   辅助组件
│   ├── median()               — 数学工具函数
│   ├── TranscriptModeFooter   — 转录模式底栏
│   ├── TranscriptSearchBar    — 转录搜索栏
│   └── AnimatedTerminalTitle  — 终端标题动画
├── [527-571]   Props 类型定义
└── [573-5009]  REPL() 组件主体
    ├── [600-900]   状态声明（50+ 个 useState/useRef/useAppState）
    ├── [900-2750]  副作用与回调（useEffect/useCallback）
    ├── [2750-2860] onQueryImpl — 核心：执行 API 查询
    ├── [2860-3030] onQuery — 查询守卫与并发控制
    ├── [3030-3145] 查询相关辅助回调
    ├── [3146-3550] onSubmit — 用户提交处理
    ├── [3550-4395] 更多副作用与状态管理
    └── [4396-5009] JSX 渲染
```

### 4.2 Props

从 main.tsx 通过 launchRepl() 传入：

| Prop | 类型 | 含义 |
|------|------|------|
| `commands` | `Command[]` | 可用的斜杠命令 |
| `debug` | `boolean` | 调试模式 |
| `initialTools` | `Tool[]` | 初始工具集 |
| `initialMessages` | `MessageType[]` | 初始消息（恢复对话时有值） |
| `pendingHookMessages` | `Promise<...>` | 延迟加载的 hook 消息 |
| `mcpClients` | `MCPServerConnection[]` | MCP 服务器连接 |
| `systemPrompt` | `string` | 自定义系统提示 |
| `appendSystemPrompt` | `string` | 追加系统提示 |
| `onBeforeQuery` | `fn` | 查询前回调，返回 false 可阻止查询 |
| `onTurnComplete` | `fn` | 轮次完成回调 |
| `mainThreadAgentDefinition` | `AgentDefinition` | 主线程 Agent 定义 |
| `thinkingConfig` | `ThinkingConfig` | 思考模式配置 |
| `disabled` | `boolean` | 禁用输入 |

### 4.3 状态管理

分三层：

**全局 AppState（通过 useAppState 选择器读取）：**

```ts
const toolPermissionContext = useAppState(s => s.toolPermissionContext);
const verbose = useAppState(s => s.verbose);
const mcp = useAppState(s => s.mcp);
const plugins = useAppState(s => s.plugins);
const agentDefinitions = useAppState(s => s.agentDefinitions);
```

**本地状态（useState）：**

```ts
const [messages, setMessages] = useState(initialMessages ?? []);
const [inputValue, setInputValue] = useState('');
const [screen, setScreen] = useState<Screen>('prompt');
const [streamingText, setStreamingText] = useState(null);
const [streamingToolUses, setStreamingToolUses] = useState([]);
// ... 50+ 个状态
```

**关键 Ref：**

```ts
const queryGuard = useRef(new QueryGuard()).current;  // 查询并发控制
const messagesRef = useRef(messages);                  // 消息的同步引用（避免闭包问题）
const abortController = ...;                           // 取消请求控制器
const responseLengthRef = useRef(0);                   // 响应长度追踪
```

### 4.4 核心数据流：用户输入 → API 调用

```
用户按回车
    │
    ▼
onSubmit (第 3146 行)
    ├── 斜杠命令？→ immediate command 直接执行 或 handlePromptSubmit 路由
    ├── 空输入？→ 忽略
    ├── 空闲检测 → 可能弹出"是否开始新对话"对话框
    ├── 加入历史记录
    │
    ▼
handlePromptSubmit (外部函数，src/utils/handlePromptSubmit.ts)
    ├── 斜杠命令 → 路由到对应 Command handler
    ├── 普通文本 → 构建 UserMessage，调用 onQuery()
    │
    ▼
onQuery (第 2860 行) — 并发守卫层
    ├── queryGuard.tryStart() → 已有查询？排队等待
    ├── setMessages([...old, ...newMessages]) — 追加用户消息
    ├── onQueryImpl()
    │
    ▼
onQueryImpl (第 2750 行) — 真正执行 API 调用
    │
    ├── 1. 并行加载上下文:
    │   await Promise.all([
    │       getSystemPrompt(),      // 构建系统提示
    │       getUserContext(),        // 用户上下文
    │       getSystemContext(),      // 系统上下文（git、平台等）
    │   ])
    │
    ├── 2. buildEffectiveSystemPrompt() — 合成最终系统提示
    │
    ├── 3. for await (const event of query({...}))  ★核心★
    │   │   调用 src/query.ts 的 query() AsyncGenerator
    │   │   流式产出事件
    │   │
    │   └── onQueryEvent(event) — 处理每个流式事件
    │       ├── 更新 streamingText（打字机效果）
    │       ├── 更新 messages（工具调用结果）
    │       └── 更新 inProgressToolUseIDs
    │
    └── 4. 收尾：resetLoadingState()、onTurnComplete()
```

**核心代码（第 2797-2807 行）**：

```ts
for await (const event of query({
    messages: messagesIncludingNewMessages,
    systemPrompt,
    userContext,
    systemContext,
    canUseTool,
    toolUseContext,
    querySource: getQuerySourceForREPL()
})) {
    onQueryEvent(event);
}
```

`query()` 来自 `src/query.ts`，是第二阶段要学的核心函数。

### 4.5 QueryGuard 并发控制

防止同时发起多个 API 请求的状态机：

```
idle ──tryStart()──▶ running ──end()──▶ idle
                        │
                        └── tryStart() 返回 null（已在运行）
                            → 新消息排入队列
```

- `tryStart()` — 原子操作，检查并转换 idle→running，返回 generation 号
- `end(generation)` — 检查 generation 匹配后转换 running→idle
- 防止 cancel+resubmit 竞态条件

### 4.6 JSX 渲染

两个互斥的渲染分支：

#### Transcript 模式（第 4396-4493 行）

按 `v` 键切换，只读浏览对话历史，支持搜索：

```tsx
<KeybindingSetup>
  <AnimatedTerminalTitle />
  <GlobalKeybindingHandlers />
  <ScrollKeybindingHandler />
  <CancelRequestHandler />
  <FullscreenLayout
    scrollable={<Messages />}
    bottom={<TranscriptSearchBar /> 或 <TranscriptModeFooter />}
  />
</KeybindingSetup>
```

#### Prompt 模式（第 4552-5009 行）

主交互界面，从上到下：

```tsx
<KeybindingSetup>
  <AnimatedTerminalTitle />           // 终端 tab 标题
  <GlobalKeybindingHandlers />        // 全局快捷键
  <CommandKeybindingHandlers />       // 命令快捷键
  <ScrollKeybindingHandler />         // 滚动快捷键
  <CancelRequestHandler />           // Ctrl+C 取消
  <MCPConnectionManager>             // MCP 连接管理
    <FullscreenLayout
      overlay={<PermissionRequest />}  // 权限审批覆盖层
      scrollable={                     // 可滚动区域
        <>
          <Messages />                 // ★ 对话消息渲染
          <UserTextMessage />          // 用户输入占位
          {toolJSX}                    // 工具 UI
          <SpinnerWithVerb />          // 加载动画
        </>
      }
      bottom={                         // 固定底部
        <>
          {/* 各种对话框 */}
          <SandboxPermissionRequest />
          <PromptDialog />
          <ElicitationDialog />
          <CostThresholdDialog />
          <FeedbackSurvey />

          {/* ★ 用户输入框 */}
          <PromptInput
            onSubmit={onSubmit}
            commands={commands}
            isLoading={isLoading}
            messages={messages}
            // ... 20+ props
          />
        </>
      }
    />
  </MCPConnectionManager>
</KeybindingSetup>
```

### 4.7 REPL.tsx 学习建议

- 核心只有一条线：`onSubmit → onQuery → query() → onQueryEvent → 更新消息`
- 其余 4000+ 行是 UI 细节：快捷键、对话框、动画、边界情况处理
- `feature('...')` 保护的 JSX 全部跳过
- `("external" as string) === 'ant'` 的分支也跳过

---

## 关键设计模式总结

| 模式 | 位置 | 说明 |
|------|------|------|
| 快速路径 | cli.tsx | 按开销从低到高逐级检查，零开销处理简单请求 |
| 动态 import | cli.tsx / main.tsx | `await import()` 延迟加载，每条路径只加载需要的模块 |
| Side-effect import | main.tsx 顶部 | import 阶段就并行启动子进程，用并行隐藏延迟 |
| feature flag | 全局 | `feature()` 永远返回 false，编译时消除死代码 |
| preAction 钩子 | main.tsx run() | Commander.js 命令执行前统一初始化 |
| QueryGuard | REPL.tsx | 状态机防止并发 API 请求，带 generation 计数防竞态 |
| React/Ink | UI 层 | 用 React 组件模型渲染终端 UI，支持全屏和虚拟滚动 |

## 需要忽略的代码模式

| 模式 | 来源 | 说明 |
|------|------|------|
| `_c(N)` 调用 | React Compiler | 反编译产生的 memoization 样板代码 |
| `feature('FLAG')` 后面的代码 | Bun bundler | 全部是死代码，在当前版本不会执行 |
| `("external" as string) === 'ant'` | 构建目标检查 | 永远为 false（external !== ant） |
| tsc 类型错误 | 反编译 | `unknown`/`never`/`{}` 类型，不影响 Bun 运行 |
| `packages/@ant/` | stub 包 | 空实现，仅满足 import 依赖 |