应用壳核心概念

在接入应用壳（@atomm-developer/generator-workbench）之前，建立正确的心智模型非常重要。本页介绍你在接入过程中会反复遇到的术语和分层关系。读完这篇文档之后，再去阅读 功能与配置参考，或者直接按 快速接入教程 上手操作。

三层角色

整个生成器接入体系由三个角色共同构成：

角色	包	负责什么
生成器	你自己编写	画布渲染、业务状态管理、参数面板 UI、导出数据生产
SDK	@atomm-developer/generator-sdk	登录鉴权、计费积分、云保存、历史记录、导出到 Studio
应用壳	@atomm-developer/generator-workbench	把生成器和 SDK 能力拼合进统一的平台壳层 UI

一句话：你写生成器，SDK 连平台，应用壳包外壳。

这三个角色各自独立：你不需要在生成器里重新实现登录、积分、计费或导出按钮，这些都由应用壳 + SDK 统一负责。

应用壳的职责边界

弄清楚应用壳负责什么、不负责什么，有助于避免把不该放进生成器的逻辑放错地方。

应用壳负责：

• 顶栏 UI：标题与品牌位 · 登录 / 头像 / 退出 · Credits 积分徽章 · 邀请入口
• 导出入口：Download · Open in Studio · Billing 计费闸门
• 模板发布弹窗（templateEnabled: true 时）
• 云保存 / 历史记录控件（cloudEnabled: true 时）
• 把生成器挂载到 workspace 或 canvas / panel 宿主
• 模板模式下的 iframe bridge 通信

下图中红色标注位置为应用壳部分:

应用壳不负责：

• 生成器的业务状态本身
• 画布的渲染和绘制逻辑
• 生成器的参数 schema 设计
• 平台 API 的底层实现
• 完整的作品中心或路由化项目管理页面

SDK 提供的平台能力

能力档位本质上是对 SDK 模块的分层开启策略。在选择档位之前，先了解 SDK 提供了哪些能力模块：

SDK 模块	提供的能力	对应的应用壳开关
sdk.auth	登录鉴权 · 用户信息获取 · Token 管理	始终集成，无需配置
sdk.credits	积分余额查询与顶栏展示	始终集成，无需配置
sdk.billing	导出计费 · 积分扣减 · 黑名单校验	始终集成，无需配置
sdk.export	文件下载（SVG / PNG / JPEG / WebP）· 发送到 Studio	exportEnabled / studioEnabled
sdk.cloud	云端草稿保存 · 草稿恢复 · gid 路由管理	cloudEnabled
sdk.history	历史版本列表 · 历史版本恢复	historyEnabled
sdk.template	模板 JSON 序列化 · 模板应用到生成器 · embed bridge 模板初始化	templateEnabled

auth、credits、billing 三个模块是基础平台能力，应用壳始终集成，不需要单独开启。其余模块按实际需求逐步开启即可，这正是能力档位划分的依据。

能力档位

在规划接入方案时，先确认自己需要哪个档位。这是文档概念，不是配置字段。

• basic：登录 · 导出 · Credits 积分 · Billing 计费壳层体验
• cloud：在 basic 基础上 + 云保存 / 历史记录
• template：在 cloud 基础上 + 模板发布 / Embed 接入 / customize 回流

重要提示：

• 接入应用壳不等于必须开启所有档位
• templateEnabled: false（默认值）时，不会出现任何模板相关 UI 或逻辑
• cloudEnabled: false（默认值）时，不会出现任何云保存 / 历史记录相关 UI

---

阅读路径

根据你的目标，选择下一步阅读的文档：

我想做什么	下一步读
我已有生成器，想快速接入登录 / 导出	手把手接入教程（basic 档位）
我想了解应用壳布局模式（shell / full / template）如何选择	功能与配置参考 → 宿主壳模式
我想了解 模板模式(?mode=embed) 和 iframe bridge	主站 Embed 宿主接入
我想了解应用壳每个功能怎么工作	功能与配置参考
我想了解应用壳和生成器如何通信	应用壳与生成器通信
我想了解整体分层架构	整体架构
我想了解生成器和应用壳之间的协议细节	生成器接入协议