主题
Engine 与 Tenant Runtime 组件方案
1. 方案摘要
Engine 和 Tenant Runtime 采用进程级与租户级两级生命周期。Engine 管理共享资源、租户注册和副本状态；Tenant Runtime 管理租户配置、Agent、Session、Channel、Plugin 和文件上下文。两级边界保证租户资源能够独立启动、更新、暂停和回收。
2. 设计目标与非目标
设计目标
- 明确共享进程服务与租户服务的归属。
- 支持多租户并存而不串用配置、路径和服务实例。
- 为热配置、维护状态和优雅关停提供生命周期锚点。
非目标
- 不把 Tenant Runtime 作为跨副本服务注册中心。
- 不允许租户服务直接读取其它租户的运行态。
- 不在本方案中定义具体租户计费策略。
3. 架构范围与视图
进程级 Engine 和租户级 Runtime 分别持有哪些组件，生命周期与状态边界是什么？
Engine 管理当前进程；Tenant Runtime 管理一个租户的业务上下文。它们都不是跨副本事实源。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| Engine 生命周期 | startEngine、bootstrapEngine、maintenance 和 shutdown。 |
| Tenant Runtime Registry | 按租户 code 查询、列出和关闭所有租户 Runtime。 |
| 共享进程服务 | ModelProxy、缓存、广播、Langfuse、Runtime replica heartbeat / monitor。 |
| 租户配置 | bootCfg 冷快照与 ConfigStore 当前热配置快照。 |
| 租户执行组件 | AgentRegistry、ModelGateway、Dispatcher、Ledger、EventBus 与 TaskRuns。 |
| 租户领域服务 | Session、Memory、MyFS、Channel、Schedule、Extension 和 Plugin。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- Engine 先完成共享依赖初始化，再按启用租户构造 Runtime。
- Tenant Runtime 持有租户级服务集合，业务入口通过 registry 查询。
- 冷配置决定进程和租户布局，热配置通过 ConfigStore 和 reconcile 应用。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 进程初始化 Engine
- 加载启用租户
- 逐租户构造 Tenant Runtime
- 注册到 Runtime registry
- 按运行角色启动对应能力
- 关停时先收口任务再释放共享资源
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- bootCfg 是启动快照，不能被热更新覆盖。
- ConfigStore 是当前租户配置快照，更新采用校验、shadow 构建和原子 swap。
- Runtime registry 只表示本进程已装配实例，跨副本状态仍以共享存储为准。
当前专题的关键约束
- bootCfg 不参与热更新。
- 租户服务必须从正确 Tenant Runtime 获取。
- 跨副本共享状态通过数据库、Redis 或对象存储。
8. 异常、恢复与安全边界
- 共享依赖初始化失败时 Engine 进入维护状态并拒绝接流量。
- 单租户配置或服务装配失败时隔离该租户，并记录可重试原因。
- 关停按照停止入口、暂停任务、刷新事件、释放租户资源、释放共享资源的顺序执行。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 每个副本可装配一个或多个租户 Runtime。
- 副本数量增加不会改变租户配置和 Chat 的事实源，只增加本地执行能力。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 多租户 Runtime registry
- 进程级 heartbeat、monitor、广播和维护状态
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 增加 Runtime 级别的资源配额和启动依赖图。
- 将高负载租户迁移到专属 Runtime 副本时保持同一配置和任务协议。
11. 方案验收要点
- 租户 A 的配置、Session、文件和 Channel 不会被租户 B 复用。
- 热配置更新不会改变已启动任务的冷配置语义。
- Engine 维护或关闭时所有 Tenant Runtime 都有明确终态。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。