主题
系统模块与依赖边界方案
1. 方案摘要
本方案通过公开契约划分业务应用、核心运行时、扩展工具和聊天交互模块。依赖方向从上层业务能力指向稳定协议，下层模块不反向依赖业务应用，从而让扩展、SDK 和 UI 适配可以独立演进。
2. 设计目标与非目标
设计目标
- 稳定模块职责和依赖方向。
- 让业务扩展只依赖公开 SDK、Schema 和宿主协议。
- 避免把逻辑模块边界误解成部署边界。
非目标
- 不规定模块必须拆成独立进程。
- 不描述具体构建工具或目录组织。
- 不允许通过内部实现细节形成新的公共依赖。
3. 架构范围与视图
业务应用、运行时能力、扩展工具与聊天交互模块如何分工和依赖？
本图表达逻辑模块与依赖方向，不代表生产部署拓扑。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| 业务应用 | 承载用户界面、API、智能体引擎、Channel、管理能力和插件宿主。 |
| 扩展开发工具 | 提供扩展、插件与业务 CLI 的开发、校验和打包能力。 |
| 核心运行时 | 提供配置、路径、扩展加载、插件宿主和兼容入口。 |
| 嵌入与接入 SDK | 提供嵌入式 WebChat 加载和业务系统接入能力。 |
| 聊天交互模块 | 提供聊天协议、客户端、服务端、UI 框架适配和 Widget。 |
| 内置业务插件 | 通过公开插件协议接入宿主运行时。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- 业务应用是能力编排者，核心运行时提供通用底座，聊天模块提供交互协议和 UI 适配。
- 扩展工具只负责开发、校验和打包，不参与线上任务执行。
- 插件通过公开协议接入宿主，宿主负责生命周期、路由和 Widget 挂载。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 业务应用依赖核心运行时和聊天交互模块。
- 扩展开发工具依赖扩展规范与插件公开协议。
- 插件宿主依赖插件公开协议并加载内置或业务插件。
- 嵌入与接入 SDK 复用聊天协议和公开接入契约。
- 基础模块不反向依赖业务应用。
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- 公开协议版本是模块间兼容性的判断依据。
- 模块升级先保持向后兼容，再逐步引入新能力。
- 跨模块状态通过明确的输入输出传递，不共享隐式全局状态。
当前专题的关键约束
- 包依赖图不应被解读为微服务图。
- 业务扩展只能依赖公开 SDK，不依赖应用内部路由或渲染协议。
- 基础模块只通过公开契约向上层提供能力。
8. 异常、恢复与安全边界
- manifest、Schema 或协议不兼容时在装载边界失败，不进入运行态。
- 宿主拒绝未知能力和非法扩展，不通过降级绕过协议校验。
- 聊天 UI 适配失败不应改变服务端任务和会话事实。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 逻辑模块可在同一进程运行，也可由宿主在不同服务中复用。
- SDK、协议和资源文件应能被独立发布或嵌入使用。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 业务应用、扩展工具、核心运行时与聊天交互模块边界
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 为插件协议、Widget 和 Channel 贡献点建立版本化兼容策略。
- 把高频变化的业务能力继续下沉到公开扩展协议，而不是扩大宿主内部 API。
11. 方案验收要点
- 任意扩展只使用公开契约即可完成校验、导入和运行。
- 下层模块不需要引入上层业务语义。
- 模块边界变更能够通过协议版本和兼容测试被发现。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。