Boot 模式

wesgine 支持三种 boot 模式，分别适用于桌面产品、云端 SaaS 和 HTTP 二进制部署。选择哪种模式取决于进程模型和租户数量。

三种 Boot 模式对比

模式	适用场景	进程关系	典型消费方
Go 嵌入 · 单 Cell	桌面 N=1	引擎在同一进程内	wesclaw desktop / wescraft 个人版
Go 嵌入 · 多 Cell	桌面 1-workspace-1-Cell	引擎在同一进程内	wescode
HTTP 二进制	服务端多租户	引擎独立进程，Java/其他语言通过 HTTP 调用	teleclaw / wesclaw-saas

模式一：桌面产品 Boot（StartEngine + GetOrCreate）

桌面产品将 wesgine 作为 Go 库嵌入，在同一进程内运行。

eng, err := engine.StartEngine(ctx, engine.Config{
    DataDir: dataDir,
    Logger:  logger,
})

// GetOrCreate 前必须绑定 ProviderLiveKeyFn（INV-CELL-08）
spec.ProviderLiveKeyFn = liveTokens.Key

cell, err := eng.Hypervisor.Cells().GetOrCreate(ctx, spec)
runtime := cell.Runtime()

关键约束：

StartEngine 只调用 hyp.Start（挂身份骨架），禁止 ActivatePersisted
GetOrCreate 前必须绑齐 json:"-" 进程 hook（OnStarted / HostEnvironment / ProviderLiveKeyFn）
落盘了 wes:/org: 却不绑 live-key getter → EnsureActive fail-loud

模式二：SaaS Boot（StartEngine + ensureEngineCell）

SaaS 使用相同的 StartEngine，但 Cell 创建逻辑由产品本地实现。

eng, err := engine.StartEngine(ctx, engine.Config{DataDir: dataDir})

// SaaS 产品本地的 ensureEngineCell
cell, err := ensureEngineCell(ctx, eng.Hypervisor, dataDir, cellID)

与桌面的差异：

治理策略通常为 RegulatedPreset（locked + internal_only）
exec 默认关闭
Cell ID 来自平台 API（如 GET /api/me/active-cell），不是硬编码 "main"

模式三：HTTP 二进制 Boot（独立进程 + Admin API）

引擎作为独立进程运行（wesgine serve），消费方通过 HTTP 调用。

wesgine serve --data-dir /var/lib/wesgine --addr :9091

消费方（如 Java）通过 Admin API 管理 Cell：

POST /admin/cells          → 创建 Cell
PUT  /admin/cells/{id}     → 幂等 upsert
GET  /admin/cells/{id}     → 获取 Cell
POST /admin/cells/{id}/run → 发起 Run

启动契约（INV-SERVE-REACHABLE-01）：绑端口 + sdnotify.Ready() 在前，ActivatePersisted 在后且在 goroutine 里。可达性不随数据量增长。

ActivatePersisted 的使用时机

场景	是否调用	说明
`wesgine serve`	✅ 在监听之后后台调用	预热已持久化的 Cell
SDK 消费方（桌面）	❌ 禁止在 GetOrCreate 前调用	会用残缺 spec 打开数据面
SDK 消费方（桌面）	❌ 禁止主动调用	GetOrCreate 自动 Bind+Activate

热身可被取消：ActivatePersisted 循环每轮查 ctx.Err()，SIGTERM 后不继续 boot。