DiAL/openspec/specs/server-bootstrap/spec.md

Purpose

TBD - 统一服务启动引导函数，封装开发和生产模式的完整启动序列。

Requirements

Requirement: 统一启动引导函数

系统 SHALL 提供 src/server/bootstrap.ts 导出 bootstrap(options: BootstrapOptions) 函数，封装完整的服务启动序列：加载配置、初始化正式 logger、创建 store、同步 targets、创建并启动 engine、启动 HTTP server、注册 shutdown handler。配置加载失败发生在正式 logger 初始化之前，系统 SHALL 使用 console fallback 输出启动失败信息。配置加载成功后的启动失败 SHALL 使用正式 logger 输出 fatal 后退出。

Scenario: 开发模式启动

• WHEN dev.ts 调用 bootstrap({ configPath, mode: "development" })
• THEN 系统 SHALL 完成完整启动序列，不传入 staticAssets，并初始化运行时 logger

Scenario: 生产模式启动（带静态资源）

• WHEN code-generated entry 调用 bootstrap({ configPath, mode: "production", staticAssets })
• THEN 系统 SHALL 完成完整启动序列，将 staticAssets 传递给 startServer，并初始化运行时 logger

Scenario: 配置加载失败处理

• WHEN 配置文件读取、YAML 解析或配置校验失败
• THEN 系统 SHALL 通过 console fallback 输出错误信息并以非零退出码退出进程

Scenario: 配置加载后的启动失败处理

• WHEN logger、store、engine 或 HTTP server 初始化失败
• THEN 系统 SHALL 通过正式 logger 输出 fatal 日志并以非零退出码退出进程

Scenario: 优雅关机

• WHEN 进程收到 SIGINT 或 SIGTERM 信号
• THEN bootstrap 注册的 shutdown handler SHALL 调用 engine.stop()、store.close() 和 logger.flush() 后退出

Requirement: BootstrapOptions 接口

bootstrap 函数 SHALL 接受 BootstrapOptions 参数，包含 configPath: string、mode: RuntimeMode 和可选的 staticAssets?: StaticAssets。

Scenario: 最小配置（开发模式）

• WHEN 仅传入 configPath 和 mode
• THEN 系统 SHALL 正常启动，startServer 不接收 staticAssets 参数

Scenario: 生产模式配置

• WHEN 传入 configPath、mode 和 staticAssets
• THEN 系统 SHALL 将 staticAssets 传递给 startServer

Requirement: dev.ts 和生产入口使用 bootstrap

dev.ts 和 src/server/main.ts SHALL 调用 bootstrap() 而非各自维护启动序列。

Scenario: dev.ts 调用 bootstrap

• WHEN 开发者运行 bun run dev
• THEN dev.ts SHALL 调用 bootstrap 完成启动

Scenario: main.ts 调用 bootstrap

• WHEN 生产可执行文件启动
• THEN main.ts SHALL 调用 bootstrap 完成启动