第3章 启动算法与生命周期管理

// main.tsx 顶部（伪代码）
import { profileCheckpoint } from './utils/startupProfiler.js'

profileCheckpoint('main_tsx_entry')                    // 标记：入口

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

import { startKeychainPrefetch } from './secureStorage/keychainPrefetch.js'
startKeychainPrefetch()                                 // 立即启动钥匙串读取

// 接下来是约 135ms 的 import 链...
import { Command } from '@commander-js/extra-typings'
import chalk from 'chalk'
import React from 'react'
// ... 总计约 180+ 个 import 语句 ...

profileCheckpoint('main_tsx_imports_loaded')            // 标记：import 完成

时间轴 ─────────────────────────────────────────────────>

主线程:  [import profileCheckpoint] [startMdmRawRead()] [import ...剩余180个模块... ~135ms]
MDM进程:                            [plutil 子进程执行 ~~~~~~ ~5-40ms]
钥匙串:                              [security 子进程1 ~32ms] [security 子进程2 ~33ms]
                                      ↑ 两个钥匙串读取也是并行的

结果:    子进程在 import 求值期间就已完成, 后续 await 几乎零成本

// rawRead.ts 核心算法（伪代码）
let rawReadPromise = null

function startMdmRawRead():
    if rawReadPromise: return          // 幂等：只启动一次
    rawReadPromise = fireRawRead()

function fireRawRead() -> Promise<RawReadResult>:
    if platform == 'darwin':
        plistPaths = getMacOSPlistPaths()    // 多个可能的 plist 路径
        results = await Promise.all(
            plistPaths.map(path =>
                if not existsSync(path):     // 快速路径：文件不存在则跳过
                    return { stdout: '', ok: false }
                return execFilePromise('plutil', [...args, path])
            )
        )
        return first(results, r => r.ok)     // 优先级序列，取第一个成功的

    if platform == 'win32':
        [hklm, hkcu] = await Promise.all([   // HKLM 和 HKCU 并行读取
            execFilePromise('reg', ['query', HKLM_PATH, ...]),
            execFilePromise('reg', ['query', HKCU_PATH, ...])
        ])
        return { hklmStdout, hkcuStdout }

    return empty                              // Linux 无 MDM 等价物

// keychainPrefetch.ts 核心算法（伪代码）
function startKeychainPrefetch():
    if platform != 'darwin': return
    if prefetchPromise: return        // 幂等
    if isBareMode(): return           // --bare 模式跳过

    // 两个 security 子进程同时 spawn
    oauthSpawn  = spawnSecurity(CREDENTIALS_SERVICE)
    legacySpawn = spawnSecurity(LEGACY_SERVICE)

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

// 在 preAction 钩子中等待结果
async function ensureKeychainPrefetchCompleted():
    if prefetchPromise: await prefetchPromise

// 通用模式：Spawn-During-Import
阶段 1 — 模块求值期（同步，不可打断）:
    import 最小依赖
    启动异步操作（子进程 / 网络 / 文件 I/O）
    继续 import 其余模块                    // 异步操作在后台运行

阶段 2 — 命令解析期:
    commander.hook('preAction', async () =>
        await Promise.all([                 // 此时异步操作大概率已完成
            ensureMdmSettingsLoaded(),
            ensureKeychainPrefetchCompleted()
        ])
        await init()                        // init() 中的同步读取命中预取缓存
    )

阶段 3 — setup() + 首次渲染:
    // setup() 与 getCommands() 并行
    setupPromise = setup(cwd, ...)          // ~28ms，主要是 UDS socket bind
    commandsPromise = getCommands(cwd)      // 文件系统读取，与 setup 不竞争 I/O
    await setupPromise
    commands = await commandsPromise        // 大概率已完成

T_total ≈ T_import + max(T_mdm, T_keychain) + T_init + max(T_setup, T_commands)
        ≈ 135ms   + ~0ms（已在import中完成）+ 50ms  + max(28ms, 15ms)
        ≈ 213ms

                    ┌─────────────────┐
                    │  main_tsx_entry  │
                    └────────┬────────┘
                  ┌──────────┼──────────┐
                  ▼          ▼          ▼
           ┌──────────┐ ┌────────┐ ┌──────────────┐
           │ MDM Read │ │Keychain│ │ Module Import │
           └────┬─────┘ └───┬────┘ └──────┬───────┘
                │            │             │
                └──────┬─────┘             │
                       ▼                   ▼
              ┌──────────────┐   ┌──────────────────┐
              │ensureMdm/KC  │   │ eagerLoadSettings │
              └──────┬───────┘   └────────┬─────────┘
                     │                    │
                     └────────┬───────────┘
                              ▼
                     ┌──────────────┐
                     │    init()    │─────────────────────────┐
                     └──────┬──────┘                         │
                            │                                ▼
               ┌────────────┼────────────┐        ┌──────────────────┐
               ▼            ▼            ▼        │ setupGraceful    │
        ┌───────────┐ ┌──────────┐ ┌─────────┐   │ Shutdown()       │
        │ mTLS/Proxy│ │ 1P Event │ │ OAuth   │   └──────────────────┘
        │ Configure │ │ Logging  │ │ Populate│
        └─────┬─────┘ └──────────┘ └─────────┘
              │
              ▼
       ┌──────────────┐
       │ preconnect   │   ← TCP+TLS 预握手，与后续工作重叠
       │ AnthropicApi │
       └──────────────┘
              │
              ▼
     ┌────────────────┐     ┌───────────────┐
     │    setup()     │────▶│  getCommands() │  ← 并行执行
     └────────┬───────┘     └───────┬───────┘
              │                     │
              ▼                     ▼
     ┌────────────────┐    ┌───────────────┐
     │   MCP Connect  │    │ SessionStart  │  ← 并行执行
     │   (prefetch)   │    │ Hooks         │
     └────────┬───────┘    └───────┬───────┘
              │                    │
              └────────┬───────────┘
                       ▼
              ┌────────────────┐
              │  launchRepl()  │
              │  首次渲染       │
              └────────┬───────┘
                       ▼
              ┌────────────────┐
              │ startDeferred  │  ← 首次渲染后才执行
              │ Prefetches()   │
              └────────────────┘

program.hook('preAction', async () =>
    // 汇合点 1：等待模块求值期启动的子进程
    await Promise.all([
        ensureMdmSettingsLoaded(),
        ensureKeychainPrefetchCompleted()
    ])

    // 汇合点 2：执行 init()（内部有自己的并行操作）
    await init()

    // 汇合点 3：附加日志 sink、运行迁移
    initSinks()
    runMigrations()

    // 启动非阻塞远程设置加载
    void loadRemoteManagedSettings()
    void loadPolicyLimits()
)

// 通过 feature flag 实现编译期消除
const coordinatorModule = feature('COORDINATOR_MODE')
    ? require('./coordinator/coordinatorMode.js')
    : null

// 如果 COORDINATOR_MODE 为 false，打包工具可以 tree-shake 整个模块

// 仅在特定条件下加载重型模块
if (feature('COMMIT_ATTRIBUTION')):
    setImmediate(() =>                        // 推迟到下一个 tick
        void import('./utils/attributionHooks.js')
            .then(m => m.registerAttributionHooks())
    )

function startDeferredPrefetches():
    if isBareMode(): return        // --bare 模式：一切从简

    // 这些在用户打字期间预热，首次 API 调用时命中缓存
    void initUser()
    void getUserContext()
    void prefetchSystemContextIfSafe()
    void getRelevantTips()
    void countFilesRoundedRg(cwd, timeout=3000)

    // 功能标志和分析初始化
    void initializeAnalyticsGates()
    void prefetchOfficialMcpUrls()
    void refreshModelCapabilities()

    // 变更检测器
    void settingsChangeDetector.initialize()
    void skillChangeDetector.initialize()

--bare 跳过的组件:
  ✗ CLAUDE.md 自动发现
  ✗ 钥匙串读取（仅用环境变量 API Key）
  ✗ Hooks 系统（SessionStart、FileChanged 等）
  ✗ LSP 服务器管理
  ✗ 插件同步
  ✗ 提交归因
  ✗ 自动记忆（Auto-memory）
  ✗ 后台预取（initUser、getUserContext 等）
  ✗ 团队记忆观察者
  ✗ 会话文件访问分析

--bare 保留的组件:
  ✓ 权限安全门控
  ✓ tengu_started 启动信标（发版健康监控）
  ✓ API Key 预取（如果已建立信任）
  ✓ 核心工具加载

teammate.ts → AppState.tsx → ... → main.tsx → teammate.ts

// main.tsx 第 68-77 行
// Lazy require to avoid circular dependency:
//   teammate.ts -> AppState.tsx -> ... -> main.tsx
const getTeammateUtils = () =>
    require('./utils/teammate.js') as typeof import('./utils/teammate.js')

const getTeammatePromptAddendum = () =>
    require('./utils/swarm/teammatePromptAddendum.js')
        as typeof import('./utils/swarm/teammatePromptAddendum.js')

const getTeammateModeSnapshot = () =>
    require('./utils/swarm/backends/teammateModeSnapshot.js')
        as typeof import('./utils/swarm/backends/teammateModeSnapshot.js')

// cleanupRegistry.ts — 极简设计
const cleanupFunctions = new Set<() => Promise<void>>()

function registerCleanup(cleanupFn): () => void {
    cleanupFunctions.add(cleanupFn)
    return () => cleanupFunctions.delete(cleanupFn)  // 返回注销函数
}

async function runCleanupFunctions(): void {
    await Promise.all(
        Array.from(cleanupFunctions).map(fn => fn())
    )
}

// init.ts 中的注册示例
registerCleanup(shutdownLspServerManager)         // LSP 服务器关闭
registerCleanup(async () => {
    const { cleanupSessionTeams } = await import('./swarm/teamHelpers.js')
    await cleanupSessionTeams()                    // 清理团队工作区
})

async function gracefulShutdown(exitCode, reason, options):
    if shutdownInProgress: return      // 幂等保护：只执行一次
    shutdownInProgress = true

    // ① 计算故障保护预算
    sessionEndTimeoutMs = getSessionEndHookTimeoutMs()
    failsafeTimer = setTimeout(
        () => { cleanupTerminalModes(); printResumeHint(); forceExit(code) },
        max(5000, sessionEndTimeoutMs + 3500)    // 至少 5 秒，留足 hook 预算
    )
    failsafeTimer.unref()              // 不阻止进程退出

    // ② 立即恢复终端状态（最高优先级）
    cleanupTerminalModes()             // 同步、writeSync，不会被打断
    printResumeHint()                  // 打印 resume 提示

    // ③ 执行注册的清理函数（限时 2 秒）
    try:
        await Promise.race([
            runCleanupFunctions(),
            timeout(2000)              // 超时即放弃
        ])

    // ④ 执行 SessionEnd 生命周期钩子（限时可配置）
    try:
        await executeSessionEndHooks(reason, {
            signal: AbortSignal.timeout(sessionEndTimeoutMs)
        })

    // ⑤ 记录启动性能报告
    profileReport()

    // ⑥ 发送缓存驱逐提示
    logEvent('tengu_cache_eviction_hint', { last_request_id })

    // ⑦ 刷新分析管道（限时 500ms）
    await Promise.race([
        Promise.all([shutdown1PEventLogging(), shutdownDatadog()]),
        sleep(500)
    ])

    // ⑧ 强制退出
    forceExit(exitCode)

function cleanupTerminalModes():
    if not process.stdout.isTTY: return

    writeSync(1, DISABLE_MOUSE_TRACKING)       // 最先发送：需要终端往返时间
    // Ink 实例卸载（退出替代屏幕）
    inst = instances.get(process.stdout)
    if inst?.isAltScreenActive:
        inst.unmount()                          // 在替代屏幕上完成最终渲染
    inst?.drainStdin()                          // 排空卸载期间到达的输入
    inst?.detachForShutdown()                   // 标记已卸载，防止重复清理
    writeSync(1, DISABLE_MODIFY_OTHER_KEYS)     // 禁用扩展按键协议
    writeSync(1, DISABLE_KITTY_KEYBOARD)        // 禁用 Kitty 键盘协议
    writeSync(1, DFE)                           // 禁用焦点事件
    writeSync(1, DBP)                           // 禁用方括号粘贴模式
    writeSync(1, SHOW_CURSOR)                   // 显示光标
    writeSync(1, CLEAR_ITERM2_PROGRESS)         // 清除进度条
    writeSync(1, CLEAR_TAB_STATUS)              // 清除标签状态
    writeSync(1, CLEAR_TERMINAL_TITLE)          // 清除终端标题

process.on('SIGINT',  () => gracefulShutdown(0))      // Ctrl+C
process.on('SIGTERM', () => gracefulShutdown(143))     // kill 命令 (128+15)
process.on('SIGHUP',  () => gracefulShutdown(129))     // 终端关闭 (128+1)

if process.stdin.isTTY:
    orphanCheckInterval = setInterval(() =>
        if isScrollDraining: return    // 滚动排空期间跳过（节省事件循环时间）
        if not process.stdout.writable or not process.stdin.readable:
            clearInterval(orphanCheckInterval)
            gracefulShutdown(129)       // 作为 SIGHUP 处理
    , 30_000)                          // 每 30 秒检查
    orphanCheckInterval.unref()        // 不阻止自然退出

onExit(() => {})  // 永远不注销，防止 Bun 的 signal-exit 注销 bug

┌─────────────┐
│  模块求值    │  startMdmRawRead(), startKeychainPrefetch()
│  (Evaluating)│  并行预取启动
└──────┬──────┘
       │ import 完成
       ▼
┌─────────────┐
│  解析命令    │  commander 解析 argv
│  (Parsing)   │
└──────┬──────┘
       │ preAction 触发
       ▼
┌─────────────┐
│  初始化      │  await ensureMdm + ensureKeychain
│  (Initing)   │  await init()  (mTLS, proxy, preconnect, ...)
│              │  runMigrations()
└──────┬──────┘
       │ action handler 开始
       ▼
┌─────────────┐
│  配置        │  setup(), getCommands(), loadPlugins()
│  (Setting Up)│  MCP 连接, Hook 执行 (并行)
└──────┬──────┘
       │ launchRepl() / runHeadless()
       ▼
┌─────────────┐
│  运行中      │  REPL 交互 / 查询处理
│  (Running)   │  startDeferredPrefetches() (后台预热)
│              │
└──────┬──────┘
       │ SIGINT / SIGTERM / SIGHUP / 用户退出
       ▼
┌─────────────┐
│  关闭中      │  cleanupTerminalModes()
│  (Shutting   │  printResumeHint()
│   Down)      │  runCleanupFunctions() (限时 2s)
│              │  executeSessionEndHooks() (限时可配置)
│              │  flush analytics (限时 500ms)
└──────┬──────┘
       │ forceExit() 或故障保护定时器
       ▼
┌─────────────┐
│  已终止      │  process.exit(code)
│  (Terminated)│  或 SIGKILL（终端已断开时）
└─────────────┘

function profileCheckpoint(name):
    if not SHOULD_PROFILE: return       // 非采样用户：零成本
    performance.mark(name)
    if DETAILED_PROFILING:
        memorySnapshots.push(process.memoryUsage())

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']
}