第 2 章启动链路与冷启动优化毫秒级 CLI 启动的工程艺术

// entrypoints/cli.tsx:33-42
async function main(): Promise<void> {
  const args = process.argv.slice(2);

  // 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;
  }
  // ...
}

// entrypoints/cli.tsx:100-106
if (feature('DAEMON') && args[0] === '--daemon-worker') {
  const { runDaemonWorker } = await import('../daemon/workerRegistry.js');
  await runDaemonWorker(args[1]);
  return;
}

// 动态 import —— 运行到此处时才加载模块
const { enableConfigs } = await import('../utils/config.js');
const { bridgeMain } = await import('../bridge/bridgeMain.js');

// main.tsx:1-20
// These side-effects must run before all other imports:
// 1. profileCheckpoint marks entry before heavy module evaluation begins
// 2. startMdmRawRead fires MDM subprocesses (plutil/reg query) so they run in
//    parallel with the remaining ~135ms of imports below
// 3. startKeychainPrefetch fires both macOS keychain reads (OAuth + legacy API
//    key) in parallel — isRemoteManagedSettingsEligible() otherwise reads them
//    sequentially via sync spawn inside applySafeConfigEnvironmentVariables()
//    (~65ms on every macOS startup)
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';
profileCheckpoint('main_tsx_entry');     // 立即打点！

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
startMdmRawRead();                      // 立即启动 MDM 子进程！

import { ensureKeychainPrefetchCompleted, startKeychainPrefetch }
  from './utils/secureStorage/keychainPrefetch.js';
startKeychainPrefetch();                // 立即启动 Keychain 读取！

import { feature } from 'bun:bundle';
import { Command as CommanderCommand, ... } from '@commander-js/extra-typings';
// ... 剩余上百个 import，源码注释称耗时 ~135ms

// utils/settings/mdm/rawRead.ts:120-123
export function startMdmRawRead(): void {
  if (rawReadPromise) return;    // 防重复
  rawReadPromise = fireRawRead();
}

// utils/settings/mdm/rawRead.ts:57-88
if (process.platform === 'darwin') {
  const plistPaths = getMacOSPlistPaths();
  const allResults = await Promise.all(
    plistPaths.map(async ({ path, label }) => {
      // Fast-path: skip plutil if file doesn't exist (~5ms savings per missing file)
      if (!existsSync(path)) {
        return { stdout: '', label, ok: false };
      }
      const { stdout, code } = await execFilePromise(PLUTIL_PATH, [
        ...PLUTIL_ARGS_PREFIX, path
      ]);
      return { stdout, label, ok: code === 0 && !!stdout };
    }),
  );
  // First source wins (array is in priority order)
  const winner = allResults.find(r => r.ok);
  // ...
}

// utils/secureStorage/keychainPrefetch.ts:69-89
export function startKeychainPrefetch(): void {
  if (process.platform !== 'darwin' || prefetchPromise || isBareMode()) return;

  // Fire both subprocesses immediately (non-blocking)
  const oauthSpawn = spawnSecurity(
    getMacOsKeychainStorageServiceName(CREDENTIALS_SERVICE_SUFFIX),
  );
  const legacySpawn = spawnSecurity(getMacOsKeychainStorageServiceName());

  prefetchPromise = Promise.all([oauthSpawn, legacySpawn]).then(
    ([oauth, legacy]) => {
      if (!oauth.timedOut) primeKeychainCacheFromPrefetch(oauth.stdout);
      if (!legacy.timedOut) legacyApiKeyPrefetch = { stdout: legacy.stdout };
    },
  );
}

// main.tsx:907-916
program.hook('preAction', async thisCommand => {
  profileCheckpoint('preAction_start');
  // Await async subprocess loads started at module evaluation (lines 12-20).
  // Nearly free — subprocesses complete during the ~135ms of imports above.
  await Promise.all([
    ensureMdmSettingsLoaded(),
    ensureKeychainPrefetchCompleted()
  ]);
  profileCheckpoint('preAction_after_mdm');
  await init();
  // ...
});

// utils/apiPreconnect.ts:31-71
export function preconnectAnthropicApi(): void {
  if (fired) return;
  fired = true;

  // Skip if using a cloud provider — different endpoint + auth
  if (
    isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK) ||
    isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX) ||
    isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)
  ) { return; }

  // Skip if proxy/mTLS/unix — SDK's custom dispatcher won't reuse this pool
  if (
    process.env.HTTPS_PROXY || process.env.http_proxy ||
    process.env.ANTHROPIC_UNIX_SOCKET ||
    process.env.CLAUDE_CODE_CLIENT_CERT
  ) { return; }

  const baseUrl =
    process.env.ANTHROPIC_BASE_URL || getOauthConfig().BASE_API_URL;

  // Fire and forget. HEAD = no response body, connection eligible for reuse.
  void fetch(baseUrl, {
    method: 'HEAD',
    signal: AbortSignal.timeout(10_000),
  }).catch(() => {});
}

// entrypoints/init.ts:79 / 146 / 159
applyExtraCACertsFromConfig();      // 先加载自定义 CA 证书
// ...
configureGlobalAgents();            // 再配置代理
// ...
preconnectAnthropicApi();           // 最后才预连接

// entrypoints/cli.tsx:288-291
const { startCapturingEarlyInput } = await import('../utils/earlyInput.js');
startCapturingEarlyInput();
profileCheckpoint('cli_before_main_import');
const { main: cliMain } = await import('../main.js');

// utils/earlyInput.ts:29-67
export function startCapturingEarlyInput(): void {
  // 仅在交互模式下捕获，-p (print) 模式跳过
  if (!process.stdin.isTTY || isCapturing ||
      process.argv.includes('-p') || process.argv.includes('--print')) {
    return;
  }

  isCapturing = true;
  earlyInputBuffer = '';

  // 设置 raw mode，与 Ink 的 stdin 处理方式一致
  process.stdin.setEncoding('utf8');
  process.stdin.setRawMode(true);
  process.stdin.ref();

  readableHandler = () => {
    let chunk = process.stdin.read();
    while (chunk !== null) {
      if (typeof chunk === 'string') {
        processChunk(chunk);
      }
      chunk = process.stdin.read();
    }
  };

  process.stdin.on('readable', readableHandler);
}

// utils/earlyInput.ts:164-169
export function consumeEarlyInput(): string {
  stopCapturingEarlyInput();
  const input = earlyInputBuffer.trim();
  earlyInputBuffer = '';
  return input;
}

// ink/components/App.tsx:224-228
// Stop early input capture right before we add our own readable handler.
// Both use the same stdin 'readable' + read() pattern, so they can't
// coexist -- our handler would drain stdin before Ink's can see it.
// The buffered text is preserved for REPL.tsx via consumeEarlyInput().
stopCapturingEarlyInput();

// screens/REPL.tsx:1331
const [inputValue, setInputValueRaw] = useState(() => consumeEarlyInput());

// 源码
if (feature('DAEMON') && args[0] === 'daemon') {
  const { daemonMain } = await import('../daemon/main.js');
  await daemonMain(args.slice(1));
  return;
}

// 外部版构建后 (feature('DAEMON') → false)
if (false && args[0] === 'daemon') {  // Dead code, 被 DCE 删除
  // ...
}

// tools.ts:25-53
const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null;

const cronTools = feature('AGENT_TRIGGERS')
  ? [
      require('./tools/ScheduleCronTool/CronCreateTool.js').CronCreateTool,
      require('./tools/ScheduleCronTool/CronDeleteTool.js').CronDeleteTool,
      require('./tools/ScheduleCronTool/CronListTool.js').CronListTool,
    ]
  : [];

const MonitorTool = feature('MONITOR_TOOL')
  ? require('./tools/MonitorTool/MonitorTool.js').MonitorTool
  : null;

// entrypoints/cli.tsx:21-26
if (feature('ABLATION_BASELINE') && process.env.CLAUDE_CODE_ABLATION_BASELINE) {
  for (const k of [
    'CLAUDE_CODE_SIMPLE', 'CLAUDE_CODE_DISABLE_THINKING',
    'DISABLE_INTERLEAVED_THINKING', 'DISABLE_COMPACT',
    'DISABLE_AUTO_COMPACT', 'CLAUDE_CODE_DISABLE_AUTO_MEMORY',
    'CLAUDE_CODE_DISABLE_BACKGROUND_TASKS',
  ]) {
    process.env[k] ??= '1';
  }
}

// utils/bundledMode.ts
export function isRunningWithBun(): boolean {
  // https://bun.com/guides/util/detect-bun
  return process.versions.bun !== undefined;
}

export function isInBundledMode(): boolean {
  return (
    typeof Bun !== 'undefined' &&
    Array.isArray(Bun.embeddedFiles) &&
    Bun.embeddedFiles.length > 0
  );
}

// entrypoints/init.ts:57
export const init = memoize(async (): Promise<void> => {
  const initStartTime = Date.now();
  logForDiagnosticsNoPII('info', 'init_started');
  profileCheckpoint('init_function_start');

  enableConfigs();
  applySafeConfigEnvironmentVariables();
  applyExtraCACertsFromConfig();
  setupGracefulShutdown();
  // ... 大量初始化逻辑

  preconnectAnthropicApi();
  // ...
  profileCheckpoint('init_function_end');
});

// entrypoints/init.ts:306-310
async function setMeterState(): Promise<void> {
  // Lazy-load instrumentation to defer ~400KB of OpenTelemetry + protobuf
  const { initializeTelemetry } = await import(
    '../utils/telemetry/instrumentation.js'
  );
  const meter = await initializeTelemetry();
  // ...
}

// init.ts:73-74
// Apply only safe environment variables before trust dialog
applySafeConfigEnvironmentVariables();

// utils/startupProfiler.ts:26-36
const DETAILED_PROFILING = isEnvTruthy(process.env.CLAUDE_CODE_PROFILE_STARTUP);
const STATSIG_SAMPLE_RATE = 0.005;
const STATSIG_LOGGING_SAMPLED =
  process.env.USER_TYPE === 'ant' || Math.random() < STATSIG_SAMPLE_RATE;
const SHOULD_PROFILE = DETAILED_PROFILING || STATSIG_LOGGING_SAMPLED;

// utils/startupProfiler.ts:65-68
export function profileCheckpoint(name: string): void {
  if (!SHOULD_PROFILE) return;  // 立即返回，零开销
  // ...
}

// utils/startupProfiler.ts:49-54
const PHASE_DEFINITIONS = {
  import_time: ['cli_entry', 'main_tsx_imports_loaded'],
  init_time: ['init_function_start', 'init_function_end'],
  settings_time: ['eagerLoadSettings_start', 'eagerLoadSettings_end'],
  total_time: ['cli_entry', 'main_after_run'],
} as const;

T+0ms     cli.tsx 入口（顶层副作用：env 修正，无模块加载）
          ├── 检查快速路径（--version, daemon, bridge...）
          └── 无匹配 → 进入正常启动

T+1ms     startCapturingEarlyInput()  ← 开始捕获用户输入
          import('../main.js')        ← 开始加载 main.tsx

T+2ms     main.tsx 模块求值开始
          ├── profileCheckpoint('main_tsx_entry')
          ├── startMdmRawRead()       ← MDM 子进程启动（不等待）
          ├── startKeychainPrefetch() ← Keychain 子进程启动（不等待）
          └── 开始求值上百个 import...
                                       ↕ MDM/Keychain 子进程并行运行中
T+~30ms   MDM 子进程完成              ← 但 JS 还在加载模块，结果暂存
T+~35ms   Keychain 子进程完成         ← 同上

T+~137ms  main.tsx 所有 import 求值完成
          Commander preAction hook 触发
          ├── await ensureMdmSettingsLoaded()     ← 立即返回（已完成）
          ├── await ensureKeychainPrefetchCompleted() ← 立即返回（已完成）
          ├── await init()
          │   ├── enableConfigs()
          │   ├── applySafeConfigEnvironmentVariables()
          │   ├── applyExtraCACertsFromConfig()
          │   ├── configureGlobalAgents()
          │   ├── preconnectAnthropicApi()  ← TCP+TLS 握手启动（不等待）
          │   └── ...
          └── 继续 action handler...

T+~250ms  REPL 渲染完成
          ├── Ink App 接管 stdin，停止 early capture
          ├── REPL 组件 consumeEarlyInput()  ← 取出启动期间的用户输入
          └── 用户看到交互界面                ← TCP+TLS 握手已在后台完成