Bootstrap 序列模式

问题

如果没有有纪律的 bootstrap 序列，安全关键的初始化步骤会乱序执行：TLS 证书在第一个网络连接已完成握手之后才加载，代理 Agent 在第一个出站 TCP 连接之前未配置，信任门控的子系统——遥测、完整环境变量集——在用户授予权限之前就激活。同时触发初始化的并发调用者导致昂贵的子系统双重初始化，浪费数百 KB 的模块加载并造成微妙的状态损坏。同时，完全不需要任何子系统的琐碎命令仍然要支付加载整个模块图的代价。

这些问题出现在任何在配置、网络、信任和可观测性之间具有有序依赖的 Agent 运行时中——并非特定于某个具体实现。

黄金法则

按依赖顺序初始化，信任是关键转折点

初始化必须遵循依赖图：任何子系统都不应在其依赖的子系统之前激活。两个通用的排序约束是：(1) 配置解析必须在任何子系统读取配置值之前完成，(2) 信任建立——用户授予或拒绝同意的时刻——必须在激活依赖于同意的子系统（遥测、秘密环境变量、分析）之前完成。在配置和信任之间，排序取决于你的运行时的具体依赖图。传输设置（TLS、代理、证书）通常靠前，因为大多数子系统依赖正确的网络状态。可观测性通常靠后，因为它依赖于配置、传输和信任。确切的层数和序列因运行时而异——原则是你必须识别和尊重依赖边，而非每个运行时都有完全相同的层。

将顶层 init 备忘化以合并并发调用者

将整个初始化函数包装在备忘化边界中，使所有并发调用者共享单个进行中的 promise。没有这个，两个同时调用 init 的调用者会各自执行完整序列，可能双重配置全局 HTTP Agent、双重加载遥测模块，或在第一个调用者尚未完成写入的状态上竞争。备忘化边界在最外层异步函数上，而非在各个子步骤上。

在信任边界两侧拆分环境变量

环境变量分为两类：没有安全影响的（编辑器偏好、语言区域、显示设置）和携带密钥或改变信任姿态的（API key、代理凭据、认证 token）。在信任对话之前应用安全集，以便早期子系统可以读取无害的配置。仅在用户授予信任之后才应用完整集。颠倒此顺序意味着环境注入的凭据在获得同意之前就已激活。

在加载任何内容之前分发琐碎命令

需要零子系统状态的命令——版本查询、schema 导出、诊断标志——应从入口点在任何动态导入或初始化运行之前分发。这使它们的延迟保持在进程启动的底线，并防止加载数百 KB 永远不会执行的代码的模块图。

在 init 期间注册清理，而非在使用处

每个清理处理器——优雅关闭、传输拆卸、子进程回收、会话清理——都必须在初始化期间注册，而非分散在使用处。在 init 时注册保证清理在退出时无条件运行，无论走了哪条代码路径。在使用处注册的清理处理器在意外退出路径绕过该处时会被静默跳过。

适用场景

• 你的 Agent 运行时在 TLS、代理和网络子系统之间有安全关键的排序。
• 你支持多种入口模式（CLI、服务器、SDK、无头），它们必须共享同一初始化路径。
• 你需要一个信任边界来分隔同意前和同意后的配置。
• 昂贵的子系统（遥测、追踪、可观测性）应仅在被许可和需要时加载。
• 琐碎命令应即时响应，而不支付完全初始化的代价。
• 多个调用者或代码路径可能同时触发初始化。

权衡

决策	收益	代价
依赖有序的串行初始化	安全关键步骤不可能乱序执行	冷启动比并行初始化慢；每层阻塞于其依赖
备忘化的顶层 init	并发调用者共享一个 promise；无双重初始化	某些备忘化库中缓存的拒绝会阻止瞬态错误的重试
信任拆分的环境变量	密钥在用户同意前永不激活	需要维护两次单独的应用过程；容易把变量放错集合
琐碎命令的快速路径分发	版本/帮助/诊断的亚毫秒级响应	每条快速路径是必须在正常 init 流程之外维护的特殊情况
重模块的懒动态导入	数百 KB 推迟到实际需要时	导入延迟转移到首次使用；更难推理加载顺序
非关键工作的并行即弃	后台缓存在不阻塞关键路径的情况下填充	失败是静默的；调用者必须优雅地容忍缓存未命中
构建时功能标志门控	禁用模式的死代码从发布产物中消除	功能检查必须在调用处内联出现；包装到辅助函数会让打包器失效
传输作为窄接口	线协议版本可互换而不触及调用者	协议版本间的行为差异可能隐藏在同一接口后面

实现模式

• 作为第一步解析和验证所有配置文件。在任何网络联系之前将解析错误呈现为用户可见的诊断。
• 在配置验证之后、实例化任何 HTTP 客户端或 Agent 之前立即应用 TLS 证书配置。许多运行时在进程启动时缓存 TLS 证书存储；在第一次握手之后应用的证书可能对复用缓存池的连接无效。
• 在代理 Agent 之前配置双向 TLS，在任何出站连接（包括预连接或预热调用）之前配置代理 Agent。依赖链是：证书，然后双向 TLS，然后 Agent，然后连接。
• 在信任对话之前应用安全的环境变量子集（无密钥、无认证 token）。在信任建立之后推迟完整集。
• 将整个顶层异步初始化函数包装在备忘化边界中。并发调用者必须接收同一 promise，而非触发同一序列的并行执行。
• 在传输层配置之后但在信任阻塞之前触发非关键的后台工作（仓库检测、IDE 检测、缓存填充、分析前导）。这些任务不应在关键路径上被等待。
• 将遥测初始化门控在信任建立之后。使用与 init 备忘化不同的独立布尔守卫，以便遥测在首次尝试失败时可以独立重试。
• 当运行时支持受管远程设置时，在最终确定遥测配置之前等待这些设置加载完毕，以便组织配置的端点得到尊重。
• 对重依赖树（遥测、追踪、protocol buffers、gRPC）使用动态导入，使其模块重量推迟到子系统实际初始化时。
• 在入口点检查琐碎命令（版本、帮助、schema 导出）并以零动态导入立即分发——不要为永远不会使用的命令加载完整模块图。
• 通过同一初始化路径支持多种入口模式（交互式 CLI、服务器/守护进程、SDK 嵌入、无头），仅在 init 之上的模式分发层分支。对于无头模式，跳过交互式对话框并以非零退出码写入 stderr。
• 对模式特定分支使用构建时功能标志。标志检查必须在调用处内联出现，以便打包器可以执行死代码消除；将其包装在辅助函数中会失效此优化。
• 将传输定义为窄接口——写入、批量写入、连接、关闭、状态报告——使不同的线协议版本可以在单一面上互换。
• 在初始化期间注册所有清理处理器（优雅关闭、传输拆卸、子进程清理、会话终结），而非在个别使用处。

踩坑指南

备忘化隐藏了重试失败。 某些备忘化实现缓存首次返回的 promise，包括被拒绝的。如果瞬态配置错误导致 init 拒绝，每个后续调用者永远收到缓存的拒绝。要么使用拒绝时清除的备忘化变体，要么实现一个出错时重置标志的手动一次性守卫。

信任边界通过环境变量泄漏。 在信任对话之前应用完整的环境变量集意味着环境注入的 API key 或代理凭据在用户同意前就已激活。这是安全违规，而非仅仅是排序偏好。始终先应用安全过程，仅在明确信任授予后才应用完整过程。

TLS 证书存储缓存使延迟应用失效。 在许多运行时中，TLS 证书存储在进程启动时只读取一次。即使只完成一次 TLS 握手后再应用自定义 CA 证书，可能对复用缓存证书池的连接无效。CA 证书配置必须是网络相关步骤中最先执行的——在任何连接之前，包括预连接预热。

遥测跨异步边界的双重初始化。 当多条代码路径可以触发遥测初始化（非交互式会话的急切同步初始化、远程设置加载后的延迟异步初始化）时，守卫标志必须在异步初始化器解析之前设置，而非之后。解析之后设置会留下一个窗口，让第二个调用者滑入并双重初始化。

功能标志必须内联以实现死代码消除。 构建时功能标志只有在标志检查直接出现在调用处时才能实现死代码消除。将检查提取到辅助函数中，即使是平凡可内联的，也会使打包器的静态分析失效并在所有构建中发布门控代码。

传输协议版本差异隐藏在接口后面。 当传输接口抽象多个线协议版本时，行为差异（如一个版本支持丢弃批次计数而另一个始终返回零）对调用者不可见。依赖版本特定行为的调用者不能依赖抽象接口进行这些检查。

全局状态模块必须是导入图中的叶子。 任何持有全局单例状态的模块必须只导入纯叶子模块——没有对系统其余部分的传递依赖。向全局状态模块添加非叶子导入会创建在整个 bootstrap 图中级联的循环依赖风险。

无头模式不能阻塞在交互式对话框上。 当运行时检测到非交互式会话（无 TTY、管道输入、CI 环境）时，初始化必须跳过任何交互式信任对话框或提示。在无头上下文中阻塞用户输入会无限期挂起进程。

Claude Code 实证

Claude Code 的 bootstrap 序列是这些原则的生产实现，通过单一有序的初始化路径支持七种不同的入口模式。

带显式依赖注释的四层排序。 初始化函数强制严格排序：首先配置解析，然后安全环境变量应用，然后 TLS CA 证书配置，然后优雅关闭注册，然后双向 TLS 配置，然后全局 HTTP Agent 设置，然后 API 预连接。每一步都包含注释说明为什么它必须在下一步之前。TLS 步骤携带关于运行时在启动时缓存证书存储使延迟应用失效的特别说明。

备忘化的 init 合并并发调用者。 顶层初始化函数包装在单一备忘化边界中，确保无论多少代码路径同时触发 init，序列恰好执行一次，所有调用者共享同一 promise。

信任拆分的环境变量。 环境变量应用被拆分为两个不同的过程。"安全"过程在任何信任检查之前运行，只应用没有安全影响的变量。"完整"过程仅在信任对话完成后运行，应用可能携带 API key、代理凭据或其他敏感配置的变量。

琐碎命令的快速路径分发。 CLI 入口点在加载任何模块之前检查版本标志、schema 导出和诊断命令。这些路径以零动态导入响应并立即退出，使其延迟保持在进程启动的底线。

重子系统的懒加载。 遥测初始化使用动态导入推迟约 400KB 的可观测性和 protocol buffer 模块，直到实际需要遥测。进一步的懒加载层推迟约 700KB 的 gRPC 传输模块，直到追踪仪表被激活。这种两级懒加载为从不激活追踪的会话保持关键路径快速。

非关键后台缓存的并行即弃。 在传输层配置之后但在信任阻塞之前，bootstrap 触发非关键后台任务——IDE 检测、仓库检测、OAuth 缓存填充、分析前导——作为不等待的 promise。这些填充后续同步调用者读取的共享缓存，而不阻塞关键初始化路径。

多模式入口通过单一 init 路径。 七种入口模式——交互式 REPL、服务器/守护进程、SDK 嵌入、桥接/远程控制、后台会话、模板运行器和自托管运行器——都流经同一备忘化初始化函数。模式特定行为在 init 调用之上而非之内分支。功能门控模式使用带内联检查的构建时标志，使未使用的模式从发布产物中消除。

可互换线协议的传输抽象。 桥接传输定义为窄接口，具有写入、批量写入、连接、关闭和状态报告方法。两个协议版本——一个使用 WebSocket 加 POST，另一个使用 server-sent events 进行读取和单独的写入通道——在此面后可互换。接口文档记录了版本间存在行为差异的位置。