主题
单进程运行时分层方案
1. 方案摘要
本方案定义单个进程内的五层运行时结构。接入层只负责协议适配，Engine 负责装配和生命周期，Tenant Runtime 负责租户上下文，执行层负责 Agent 任务，数据层负责事件、回复和持久化。分层的目的不是增加抽象，而是防止请求处理过程绕过统一生命周期和租户边界。
2. 设计目标与非目标
设计目标
- 让所有入口通过统一 Engine 和 Tenant Runtime 获取能力。
- 限制层间调用方向，避免接入层直接创建领域服务。
- 在单进程模式下保留未来拆分 Gateway / Runtime 的边界。
非目标
- 不把每一层都定义成独立服务。
- 不在进程内存中实现跨副本一致性。
- 不把事件流当作数据库事务的替代品。
3. 架构范围与视图
单进程组合部署时，访问、运行时、执行、领域服务和数据层如何协作？
本图描述单个副本的逻辑分层。生产多副本角色拆分在图 10 中展开。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| 接入层 | 页面、HTTP API、SSE、Web / IM Channel、OpenAPI 和 Scheduler。 |
| Engine | 负责单副本内的服务装配、生命周期和统一能力入口。 |
| Tenant Runtime | 承载每个租户独立的配置、Agent、Session、Memory、Channel 与文件上下文。 |
| 调度与执行 | Dispatcher、Ledger、Trigger、任务队列、Agent Runner 与 Claude Agent SDK。 |
| 领域服务 | 模型、技能、工具、插件、扩展、授权、用量和可观测能力。 |
| 持久化与出站 | EventBus、SSE、Channel reply、数据库、Redis 和 MyFS。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- Engine 是进程级唯一装配入口，Tenant Runtime 是租户级上下文入口。
- 任务执行与事件发布分离，事件用于过程反馈，数据库用于状态事实。
- 接入层只传递身份、租户、Agent、Chat 和请求上下文。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 入口解析请求
- 通过 Engine 获取服务
- 解析租户并进入 Tenant Runtime
- 调度并执行 Agent
- 发布事件与回复
- 持久化状态和文件
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- Engine registry 和本地 EventBus 只表示当前副本运行态。
- Chat、Task、Session、文件和 ownership 需要落到共享事实源。
- 进行中的任务使用入口时固化的配置快照，避免热更新改变任务语义。
当前专题的关键约束
- 接入层不直接创建业务服务。
- Engine 单例只在单个进程内复用。
- 跨副本状态以共享基础设施为准。
8. 异常、恢复与安全边界
- Engine 启动失败时副本不可服务，不能以半初始化 Runtime 接收请求。
- Tenant Runtime 初始化失败只影响对应租户，并应阻止该租户流量进入。
- 关停先停止接入和新任务，再收口运行任务，最后释放共享资源。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 组合部署将五层放在同一进程，适合本地和低规模场景。
- 多副本模式通过内部派发把接入和执行分开，但保持层间契约。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 单进程组合部署
- Engine 单例与 Tenant Runtime registry
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 增加运行时健康状态、启动依赖和优雅关停的可观测指标。
- 将需要独立扩缩容的入口能力迁移到 Gateway，同时保持 Tenant Runtime 接口稳定。
11. 方案验收要点
- Route 请求只能通过 Engine / Tenant Runtime 获得服务。
- 同一请求在单进程和拆分部署中的任务语义一致。
- 关停期间不会产生新的孤儿任务或未保护写入。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。