claude-code/learn/phase-1-qa.md

# 第一阶段 Q&A

## Q1：cli.tsx 的快速路径分发具体在做什么？

**核心思想**：根据用户输入的命令参数，尽早决定走哪条路，避免加载不需要的代码。cli.tsx 充当一个轻量级路由器，把简单请求就地处理，只有真正需要完整 CLI 时才加载 main.tsx。

### 场景对比

#### 场景 1：`claude --version`（命中快速路径）

```
cli.tsx main() 开始执行
  ├── args = ["--version"]
  ├── 命中第 64 行: args[0] === "--version" ✅
  ├── console.log("2.1.888 (Claude Code)")
  └── return  ← 立即退出，零 import，~10ms
```

#### 场景 2：`claude --claude-in-chrome-mcp`（命中中间路径）

```
cli.tsx main() 开始执行
  ├── 第 64 行: --version? ❌
  ├── 第 75 行: 加载 profileCheckpoint（仅此一个 import）
  ├── 第 81 行: feature("DUMP_SYSTEM_PROMPT") → false ❌
  ├── 第 95 行: --claude-in-chrome-mcp? ✅ 命中
  ├── await import("../utils/claudeInChrome/mcpServer.js")  ← 只加载这一个模块
  └── return  ← 没有加载 main.tsx 的 200+ import
```

#### 场景 3：`claude`（无参数，最常见，全部未命中）

```
cli.tsx main() 开始执行
  ├── --version?           ❌
  ├── profileCheckpoint 加载
  ├── feature(DUMP)?       ❌ (feature=false)
  ├── --chrome-mcp?        ❌
  ├── --chrome-native?     ❌
  ├── feature(CHICAGO)?    ❌ (feature=false)
  ├── feature(DAEMON)?     ❌ (feature=false)
  ├── feature(BRIDGE)?     ❌ (feature=false)
  ├── ... 所有快速路径逐一检查，全部未命中
  │
  ├── 走到第 310 行 ← 最终出口
  ├── await import("../main.jsx")  ← 加载完整 CLI（200+ import，~135ms）
  └── await cliMain()              ← 进入 main.tsx 重型初始化
```

### 性能对比

| 方式 | `claude --version` 耗时 |
|------|------------------------|
| 无快速路径（全部走 main.tsx） | ~200ms（加载 200+ import → 初始化 Commander → 解析参数 → 打印） |
| 有快速路径（cli.tsx 拦截） | ~10ms（读 args → 打印 → 退出） |

### feature() 的加速作用

大量快速路径被 `feature()` 守护：

```ts
if (feature("DAEMON") && args[0] === "daemon") { ... }
```

`feature()` 返回 false → `&&` 短路求值 → 连 `args[0]` 都不检查，直接跳过。在反编译版本中这些路径等于不存在，进一步加速了"全部没命中 → 走默认路径"的过程。

---

## Q2：main.tsx 中不同命令的具体执行流程是怎样的？

所有命令都会经过 main() → run()，但在 run() 内部根据 Commander 路由到不同分支。

### 场景 1：`claude`（无参数 — 启动交互 REPL）

最常见的场景，走完整条主命令路径：

```
main() (第 585 行)
  ├── 信号处理注册（SIGINT、exit）
  ├── feature flag 路径全部跳过
  ├── isNonInteractive = false（有 TTY，没有 -p）
  ├── clientType = 'cli'
  └── await run()
       │
       ▼
  run() (第 884 行)
  ├── Commander 初始化 + preAction 钩子 + 主命令选项注册
  ├── isPrintMode = false → 注册所有子命令
  └── program.parseAsync(process.argv)
       │  Commander 匹配到主命令，先执行 preAction
       ▼
  preAction (第 907 行)
  ├── await ensureMdmSettingsLoaded()        ← 等 side-effect import 的子进程完成
  ├── await ensureKeychainPrefetchCompleted() ← 等 keychain 预读完成
  ├── await init()                            ← 遥测、配置、信任
  ├── initSinks()                             ← 分析日志
  ├── runMigrations()                         ← 数据迁移
  └── loadRemoteManagedSettings() / loadPolicyLimits() ← 非阻塞
       │  然后执行 action handler
       ▼
  action(undefined, options) (第 1007 行)     ← prompt = undefined
  ├── [参数解析] permissionMode, model, thinkingConfig...
  ├── [工具加载] tools = getTools(toolPermissionContext)
  ├── [并行初始化]
  │   ├── setup()        ← worktree、CWD
  │   ├── getCommands()  ← 加载斜杠命令
  │   └── getAgentDefinitionsWithOverrides() ← 加载 agent 定义
  ├── [MCP 连接] 连接配置的 MCP 服务器
  ├── [构建初始状态] initialState = { tools, mcp, permissions, ... }
  │
  ├── [UI 初始化]（交互模式专属）
  │   ├── createRoot()          ← 创建 Ink 渲染根节点
  │   └── showSetupScreens()    ← 信任对话框 / OAuth / 引导
  │
  ├── [后续初始化] LSP、插件版本、session 注册
  │
  └── 默认分支 (第 3760 行) ← 没有 --continue/--resume/--print
      └── await launchRepl(root, {
              initialState
          }, {
              ...sessionConfig,
              initialMessages: undefined  ← 全新对话，无历史消息
          }, renderAndRun)
            │
            ▼
          REPL.tsx 渲染，用户看到空白对话界面
```

### 场景 2：`echo "explain this" | claude -p`（管道/非交互模式）

```
main() →
  ├── isNonInteractive = true（-p 标志 + stdin 不是 TTY）
  ├── clientType = 'sdk-cli'
  └── run()
       │
       ▼
  run()
  ├── Commander 初始化 + preAction + 主命令选项
  ├── isPrintMode = true
  │   → ★ 跳过所有子命令注册（节省 ~65ms）
  └── program.parseAsync()  ← 直接解析，Commander 路由到主命令 action
       │
       ▼
  preAction → init、迁移等（同场景 1）
       │
       ▼
  action("", { print: true, ... })
  ├── inputPrompt = await getInputPrompt("")
  │   ├── stdin.isTTY = false → 从 stdin 读数据
  │   ├── 等待最多 3s 读入: "explain this"
  │   └── 返回 "explain this"
  ├── tools = getTools()
  ├── setup() + getCommands()（并行）
  │
  ├── isNonInteractiveSession = true → 走 --print 分支（第 2584 行）
  │   ├── applyConfigEnvironmentVariables() ← -p 模式信任隐含
  │   ├── 构建 headlessInitialState（无 UI）
  │   ├── headlessStore = createStore(headlessInitialState)
  │   │
  │   ├── await import('src/cli/print.js')
  │   └── runHeadless(inputPrompt, ...)  ★ 不走 REPL
  │       ├── 发送 API 请求
  │       ├── 流式输出到 stdout
  │       └── 完成后 process.exit()
  │
  └── ← 不走 createRoot()、showSetupScreens()、launchRepl()
```

**关键差异**：
- 检测到 `-p` 后跳过子命令注册（节省 ~65ms）
- 不创建 Ink UI，不调用 `showSetupScreens()`
- 从 stdin 读取输入（`getInputPrompt` 第 857 行）
- 走 `print.js` 路径直接执行查询输出到 stdout

### 场景 3：`claude -c`（继续最近对话）

```
... main() → run() → preAction → action（前半部分同场景 1）
       │
       ▼
  action(undefined, { continue: true, ... })
  ├── [参数解析 + 工具加载 + 并行初始化 + UI 初始化]（同场景 1）
  │
  ├── options.continue = true → 命中第 3101 行
  │   ├── clearSessionCaches()       ← 清除过期缓存
  │   ├── result = await loadConversationForResume()
  │   │   └── 从 ~/.claude/projects/<cwd>/ 读最近的会话 JSONL
  │   │
  │   ├── result 为 null? → exitWithError("No conversation found")
  │   │
  │   ├── loaded = await processResumedConversation(result)
  │   │   ├── 解析 JSONL → messages[]
  │   │   ├── 恢复文件历史快照
  │   │   └── 重建 initialState
  │   │
  │   └── await launchRepl(root, {
  │           initialState: loaded.initialState
  │       }, {
  │           ...sessionConfig,
  │           initialMessages: loaded.messages,            ★ 带上历史消息
  │           initialFileHistorySnapshots: loaded.fileHistorySnapshots,
  │           initialAgentName: loaded.agentName
  │       }, renderAndRun)
  │         │
  │         ▼
  │       REPL.tsx 渲染，显示历史对话，用户继续聊天
  │
  └── ← 其他分支不执行
```

**关键差异**：`initialMessages` 有值（历史消息），REPL 启动时会渲染之前的对话内容。

### 场景 4：`claude mcp list`（子命令）

```
main() → run()
       │
       ▼
  run()
  ├── Commander 初始化 + preAction 钩子
  ├── 注册主命令 .action(...)
  ├── isPrintMode = false → 注册所有子命令
  │   ├── program.command('mcp') (第 3894 行)
  │   │   ├── mcp.command('serve').action(...)
  │   │   ├── mcp.command('add').action(...)
  │   │   ├── mcp.command('list').action(async () => {  ★
  │   │   │       const { mcpListHandler } = await import('./cli/handlers/mcp.js');
  │   │   │       await mcpListHandler();
  │   │   │   })
  │   │   └── ...
  │   ├── program.command('auth')
  │   ├── program.command('doctor')
  │   └── ...
  │
  └── program.parseAsync(["node", "claude", "mcp", "list"])
       │  Commander 匹配到 mcp → list
       ▼
  preAction (第 907 行)     ← 子命令也触发 preAction
  ├── await init()
  ├── initSinks()
  ├── runMigrations()
  └── ...
       │
       ▼  执行子命令自己的 action（不走主命令 action）
  mcp list action
  ├── await import('./cli/handlers/mcp.js')
  └── await mcpListHandler()
      ├── 读取 MCP 配置（user/project/local 三级）
      ├── 连接每个服务器做健康检查
      ├── 格式化输出到终端
      └── 退出

  ← 主命令的 action handler 完全不执行
  ← 没有 REPL、没有 Ink UI、没有 showSetupScreens
```

**关键差异**：
- Commander 路由到子命令，**主命令 action 完全跳过**
- `preAction` 仍然执行（基础初始化所有命令都需要）
- 子命令有自己独立的轻量 action

### 四种场景对比

| | `claude` | `claude -p` | `claude -c` | `claude mcp list` |
|---|---------|------------|------------|-------------------|
| preAction | 执行 | 执行 | 执行 | 执行 |
| 主命令 action | 执行 | 执行 | 执行 | **跳过** |
| 子命令注册 | 注册 | **跳过** | 注册 | 注册 |
| showSetupScreens | 执行 | **跳过** | 执行 | **跳过** |
| createRoot (Ink) | 执行 | **跳过** | 执行 | **跳过** |
| 加载历史消息 | 否 | 否 | **是** | 否 |
| 最终出口 | launchRepl | print.js | launchRepl | 子命令 action |