# 第一阶段 · 模块一 · 第二节：cli.tsx bootstrap 机制深度解析
cli.tsx 的 bootstrap 机制是什么？动态导入如何实现零模块加载？feature() Bun DCE 的作用是什么？快速路径的设计有什么讲究？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 入口层（entrypoints/） │
│ │
│ cli.tsx ──> main.tsx ──> REPL.tsx (交互模式) │
│ └──> QueryEngine.ts (SDK/headless) │
│ │
│ ← 本节内容 │
└──────────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 查询引擎层（query.ts / QueryEngine.ts） │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/entrypoints/cli.tsx` 第 1-302 行
| 指标 | 数值 |
| 总行数 | 302 行 |
| 快速路径数 | 10+ 个 |
| 动态导入数 | 20+ 个 |
cli.tsx 的核心职责是在加载任何业务逻辑之前，先检查特殊标志。
// cli.tsx 的结构
async function main(): Promise<void> {
const args = process.argv.slice(2);
// 快速路径 1：--version
if (...) { return; }
// 快速路径 2：--dump-system-prompt
if (...) { return; }
// ... 更多快速路径
// 最后：加载完整 CLI
const { main: cliMain } = await import('../main.js');
await cliMain();
}
源码位置：`src/entrypoints/cli.tsx` 第 36-41 行
// Fast-path for --version/-v: zero module loading needed
if (
args.length === 1 &&
(args[0] === '--version' || args[0] === '-v' || args[0] === '-V')
) {
// MACRO.VERSION is inlined at build time
console.log(`${MACRO.VERSION} (Claude Code)`);
return; // ⚠️ 关键：直接返回，不加载任何模块
}
问 1：为什么 --version 需要零模块加载？
用户期望 `--version` 立即响应（毫秒级）：
用户心理模型：
$ claude --version
claude-code 2.1.88 ← 期望立即看到输出
实际情况（如果没有零模块加载）：
$ claude --version
[等待数百毫秒加载所有模块]
[然后才打印版本号]
问 2：MACRO.VERSION 是什么？
// MACRO 是 Bun 的编译时内建变量
// 在构建时从 package.json + git describe 注入
console.log(`${MACRO.VERSION} (Claude Code)`);
// 输出：claude-code 2.1.88
MACRO 是在编译时确定的值，运行时直接使用，不需要任何模块加载。
问 3：动态导入的本质是什么？
// 静态导入
import { main } from '../main.js';
// 编译时就确定，运行时立即加载所有依赖
// 动态导入
const { main } = await import('../main.js');
// 运行时才加载，执行到这里才触发
| 导入方式 | 加载时机 | 适用场景 |
| 静态导入 | 编译时 | 始终需要的模块 |
| 动态导入 | 运行时 | 按需加载的模块 |
问 4：cli.tsx 顶部有静态导入吗？
// cli.tsx 第 1 行
import { feature } from 'bun:bundle'; // ⚠️ 唯一的静态导入
唯一的静态导入是 `feature` from `bun:bundle`，因为：
- `feature()` 需要在模块加载时就可用
- Bun bundle 的 feature flag 是编译时常量
问 5：--version 之后的其他标志为什么用动态导入？
因为 `--version` 是最高频的命令，其他命令（如 `--help`、`claude "hello"`）可以接受稍长的加载时间。
源码位置：`src/entrypoints/cli.tsx` 第 28-302 行
cli.tsx main()
│
├── --version / -v / -V
│ └── console.log(MACRO.VERSION) ← 零模块加载
│ 源码：第 36-41 行
│
├── --dump-system-prompt
│ └── 加载 config.js + prompts.js
│ 源码：第 54-75 行
│
├── --claude-in-chrome-mcp
│ └── 加载 mcpServer.js
│ 源码：第 79-85 行
│
├── --chrome-native-host
│ └── 加载 chromeNativeHost.js
│ 源码：第 86-91 行
│
├── --computer-use-mcp
│ └── 加载 computerUse/mcpServer.js
│ 源码：第 92-99 行
│
├── --daemon-worker=<kind>
│ └── 加载 workerRegistry.js
│ 源码：第 110-115 行
│
├── remote-control / rc / remote / sync / bridge
│ └── 加载 bridgeMain.js
│ 源码：第 117-158 行
│
├── daemon
│ └── 加载 daemon/main.js
│ 源码：第 169-179 行
│
├── ps / logs / attach / kill / --bg / --background
│ └── 加载 cli/bg.js
│ 源码：第 190-206 行
│
├── new / list / reply
│ └── 加载 templateJobs.js
│ 源码：第 217-224 行
│
├── environment-runner
│ └── 加载 environment-runner/main.js
│ 源码：第 235-241 行
│
├── self-hosted-runner
│ └── 加载 self-hosted-runner/main.js
│ 源码：第 252-258 行
│
└── [其他命令]
└── 加载 main.js ← 完整 CLI
源码：第 292-298 行
源码位置：`src/entrypoints/cli.tsx` 第 47 行
// 每次进入一个快速路径时调用
profileCheckpoint('cli_version_path'); // --version 路径
profileCheckpoint('cli_daemon_path'); // --daemon 路径
profileCheckpoint('cli_bg_path'); // --bg 路径
作用：记录启动性能，用于分析用户使用模式和性能瓶颈。
问 1：为什么 --dump-system-prompt 需要加载 config.js？
// --dump-system-prompt 需要渲染完整的系统提示词
// 但系统提示词依赖配置（如模型选择、工具列表）
const { enableConfigs } = await import('../utils/config.js');
enableConfigs(); // 加载配置
const { getSystemPrompt } = await import('../constants/prompts.js');
const prompt = await getSystemPrompt([], model);
问 2：--bg 和 daemon 有什么区别？
| 特性 | --bg | daemon |
| 用途 | 后台会话管理 | 长运行守护进程 |
| 生命周期 | 用户控制 | 系统级服务 |
| 加载模块 | cli/bg.js | daemon/main.js |
问 3：为什么 remote-control 需要那么多检查？
// 1. 认证检查
const { getClaudeAIOAuthTokens } = await import('../utils/auth.js');
if (!getClaudeAIOAuthTokens()?.accessToken) {
exitWithError(BRIDGE_LOGIN_ERROR); // 必须登录
}
// 2. 版本检查
const versionError = checkBridgeMinVersion();
if (versionError) { exitWithError(versionError); }
// 3. 策略检查
if (!isPolicyAllowed('allow_remote_control')) {
exitWithError("Remote Control is disabled by your organization's policy.");
}
remote-control 涉及安全敏感操作，所以需要多层检查。
源码位置：`src/entrypoints/cli.tsx` 第 1 行
import { feature } from 'bun:bundle';
`feature()` 是 Bun 的编译时内建函数，用于条件编译。
源码位置：`src/entrypoints/cli.tsx` 第 92-99 行
// feature() 必须在 if 条件内 inline
// 否则 DCE（Dead Code Elimination）可能失效
if (feature('CHICAGO_MCP') && process.argv[2] === '--computer-use-mcp') {
const { runComputerUseMcpServer } = await import('../utils/computerUse/mcpServer.js');
await runComputerUseMcpServer();
return;
}
问 1：Dead Code Elimination (DCE) 是什么？
构建前（feature='CHICAGO_MCP'=false）：
if (feature('CHICAGO_MCP') && process.argv[2] === '--computer-use-mcp') {
// 100行 computerUse 相关代码
}
构建后（消除后）：
// 整个 if 块被删除，0行代码
问 2：为什么需要 DCE？
| 问题 | 解决方案 |
| CLI 功能太多 | 用 feature flag 选择性包含 |
| 某些用户不需要 daemon | 构建时消除 |
| 某些功能仅限内部使用 | 构建时消除 |
| 减少最终产物大小 | DCE |
问 3：为什么注释说 "must stay inline"？
// ✓ 正确：feature() 在 if 条件内 inline
if (feature('DAEMON') && args[0] === 'daemon') { }
// ✗ 错误：提取到变量可能破坏 DCE
const isDaemon = feature('DAEMON'); // 可能被优化掉
if (isDaemon && args[0] === 'daemon') { }
问 4：feature() 和动态导入的区别？
| 机制 | 作用时机 | 效果 |
| 动态导入 | 运行时 | 延迟加载，但代码仍存在于产物中 |
| feature() | 构建时 | 代码被完全消除，不存在于产物中 |
问 5：外部构建和内部构建的区别？
// --dump-system-prompt 是 Ant-only（内部使用）
// 注释说明：Ant-only: eliminated from external builds via feature flag
if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {
// ...
}
外部用户构建时，`DUMP_SYSTEM_PROMPT` 为 false，整个 block 被消除。
源码位置：`src/entrypoints/cli.tsx` 第 288-290 行
// --bare: set SIMPLE early so gates fire during module eval / commander
// option building (not just inside the action handler).
if (args.includes('--bare')) {
process.env.CLAUDE_CODE_SIMPLE = '1';
}
问 1：为什么 --bare 需要提前设置环境变量？
// 问题：某些模块在 import 时就检查环境变量
// 如果在 main.js 里才设置，模块级别的检查已经错过了
// cli.tsx 在加载任何模块之前就设置
if (args.includes('--bare')) {
process.env.CLAUDE_CODE_SIMPLE = '1'; // 提前设置
}
// main.tsx 里才能正确检测到这个变量
问 2：CLAUDE_CODE_SIMPLE 控制什么？
根据注释，它影响：
- 模块级别的 gate 检查
- Commander option building
问 3：为什么注释说 "not just inside the action handler"？
// Commander 的 option building 在 action 执行之前
// 如果在 action handler 里才设置，某些检查已经错过了
program
.option('--bare')
.action(async (options) => {
// 如果在这里设置，Commander 已经构建完选项了
process.env.CLAUDE_CODE_SIMPLE = '1'; // 太晚了
});
process.argv
│
├── --version → 直接返回
├── --daemon → daemonMain
├── --bg → bgHandler
└── [其他] → main.js
每个特殊标志对应一个处理器，形成责任链。
const { daemonMain } = await import('../daemon/main.js');
// 按需加载，不是所有用户都需要 daemon
if (feature('DAEMON') && args[0] === 'daemon') {
// 构建时被消除
}
// 如果匹配快速路径，立即 return
// 不执行后续代码
if (args[0] === '--version') {
console.log(MACRO.VERSION);
return; // 早早退出
}
问题：如果 `main.js` 加载失败，用户的体验是什么？如何改进？
答案：
用户会看到难以理解的错误：
Error: Cannot find module '../main.js'
SyntaxError: /path/to/main.js:123
改进方案：
try {
const { main: cliMain } = await import('../main.js');
await cliMain();
} catch (error) {
exitWithError(
`Failed to load Claude Code. This may be caused by a corrupted installation.\n` +
`Try reinstalling: npm install -g @anthropic-ai/claude-code\n` +
`Error: ${error.message}`
);
}
问题：如果 `--version` 也用 `feature()` 包裹，构建时消除后会发生什么？
答案：
// 假设这样写：
if (feature('VERSION') && args[0] === '--version') {
console.log(`${MACRO.VERSION} (Claude Code)`);
return;
}
如果 `feature('VERSION')` 在构建时为 `false`，整个 if 块被消除：
// 构建后：
if (false && args[0] === '--version') { ... } // 永远不执行
// 用户执行：
claude --version
// → 程序跳过检查
// → 尝试加载 main.js（而不是打印版本）
// → 用户看到完整 CLI 启动，而不是版本号
结论：`--version` 不能用 `feature()` 包裹，因为它是一个必须始终存在的功能。
问题：假设要添加一个新命令 `--backup`，它应该用快速路径还是普通路径？判断标准是什么？
答案：
判断标准：
| 标准 | 快速路径 | 普通路径 |
| 执行频率 | 高（如 --version, --help） | 低 |
| 启动耗时 | 必须 <50ms | 可以接受 200ms+ |
| 依赖模块 | 少或无 | 多 |
| 是否需要完整初始化 | 否 | 是 |
分析 `--backup`：
场景 A：用户备份配置
claude --backup
// 需要：读取配置 → 写入备份文件
// 依赖：config.js, fs 模块
// 耗时：~100ms
// 建议：普通路径
场景 B：用户查看备份工具帮助
claude --backup --help
// 需要：显示帮助信息
// 依赖：help 模块
// 耗时：~50ms
// 建议：快速路径
通用决策树：
新命令需要加载多少模块？
│
├── ≤ 1 个模块 → 快速路径
│
└── ≥ 2 个模块 → 执行频率高吗？
├── 高 → 快速路径（值得优化）
└── 低 → 普通路径
| 文件 | 行数 | 核心内容 |
| `src/entrypoints/cli.tsx` | 302 | Bootstrap 入口 |
| `src/main.tsx` | 4683 | 主程序 |
| `src/daemon/main.js` | ? | 守护进程 |
| `src/cli/bg.js` | ? | 后台会话管理 |
下一节我们将深入 main.tsx 的 preAction 钩子：
- 为什么 `claude --help` 不触发初始化？
- preAction 如何实现惰性初始化？
- init() 函数的职责
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*