主题
扩展包与 Plugin Runtime 架构方案
1. 方案摘要
本方案定义扩展包从开发、校验、导入、启用到运行挂载的完整生命周期。扩展包是交付单位，Plugin Runtime 是其中 Plugin 能力的宿主；导入默认禁用，只有通过 manifest、冲突和完整性校验后才允许进入 ready 状态。
2. 设计目标与非目标
设计目标
- 让 Agent、Skill、CLI 和 Plugin 以统一包形态交付。
- 隔离导入校验、启停管理和线上运行。
- 保证扩展冲突、权限和失败状态可解释、可恢复。
非目标
- 不把扩展包导入视为立即执行代码。
- 不允许 Plugin Runtime 扫描未完成或未启用的扩展。
- 不在宿主中复制每个扩展的业务领域逻辑。
3. 架构范围与视图
业务扩展如何被开发、校验、导入、启用并挂载为 Agent、Skill、CLI 和 Plugin？
扩展包是交付单位，Plugin Runtime 是其中 Plugin 能力的宿主；两者不是平行替代机制。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| Kit | 校验扩展结构、收集文件并打包 ZIP。 |
| 扩展来源 | 管理员本地导入，或从云端扩展包平台查询和下载。 |
| Import Service | 执行 dry-run、manifest 校验、冲突检查、落盘和 CLI 环境初始化。 |
| Extension State | 记录 disabled / ready / failed 等安装与运行状态。 |
| Agent / Skill | 启用时写入 Agent 配置、员工记录与 workspace 链接。 |
| CLI | 安装到扩展目录，并将命令链接到 engine/bin。 |
| Plugin Runtime | 只扫描 ready 扩展，暴露路由、Widget 和宿主 SDK。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- 导入采用 dry-run、manifest 校验、冲突检查、落盘和状态提交的阶段式流程。
- disabled 是导入后的默认状态，ready 才能被运行时发现。
- Plugin Runtime 通过公开 SDK 提供 Route、Widget 和宿主能力。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- Kit 开发和打包
- 本地上传或云端下载
- dry-run 与冲突检查
- 导入后默认 disabled
- 管理员启用
- 同步 Agent / Skill / CLI / Plugin
- 运行入口生效
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- 扩展状态和 manifest 是启用判断的事实源。
- 文件落盘完成后再提交 ready，避免运行时读取半包。
- Agent key、Plugin key 和 CLI command 冲突时整项能力保持不可用。
当前专题的关键约束
- 扩展导入后默认禁用。
- Plugin Runtime 只扫描 ready 扩展。
- Agent、Plugin key 与 CLI command 冲突会阻断对应流程。
8. 异常、恢复与安全边界
- 校验或冲突失败保留 failed 状态和诊断信息，不覆盖已 ready 版本。
- 启用过程任一挂载失败时回滚本轮状态，避免部分启用。
- 运行时发现扩展损坏时隔离该扩展，不影响宿主核心任务。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 扩展导入可以由管理入口执行，运行挂载发生在 Tenant Runtime 内。
- 多副本环境需要共享扩展源或在副本间完成可验证同步。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- Agent、Skill、CLI、Plugin 的扩展包 MVP
- 云端扩展查询与安装入口
规划或待完善
- 扩展包 Channel contribution
- 多个 Plugin / CLI 的完整支持与 watcher 热加载
演进方向
- 增加版本回滚、签名校验、依赖声明和扩展升级策略。
- 补齐 Channel contribution、Plugin/CLI watcher 和多扩展并发管理。
11. 方案验收要点
- 未启用扩展不会影响运行时路由和 Agent 列表。
- 同一扩展版本在不同副本得到一致的 ready 结果。
- 扩展失败可定位到阶段、冲突对象和恢复动作。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。