Generator SDK

简体中文

English

简体中文

English

Appearance

Generator Workbench 升级指南 ​

generator-workbench 可以通过 CDN 分发，但这不意味着所有已接入的生成器只要刷新页面，就一定已经正确接入了新能力。

这篇文档定义 generator-workbench 的升级模型，说明如何优先读取 CDN 上发布的 upgrade-manifest.json，并给使用 CDN 接入的生成器提供一套可重复执行的升级检查清单。

为什么需要这篇文档 ​

很多生成器会通过 CDN 加载：

  • generator-sdk
  • generator-workbench

这样做的好处是壳层脚本可以随发布自动更新。

但问题在于，新增能力不一定都属于“壳内闭环能力”。有些能力还会要求生成器同步补齐：

  • 新的宿主配置
  • 新的 runtime 事件
  • 新的 CDN 资源
  • 新的路由行为
  • 新的生成器侧回归测试

所以会出现一种常见现象：

  • 生成器页面里看到的 generator-workbench 已经是新版本
  • 但新能力并没有真正接通

三类升级项 ​

每次 generator-workbench 发布新能力时，都应该把变化明确分成三类。

1. 自动获得型 ​

这类能力完全在 generator-workbench 内部闭环。

例如：

  • 壳层 UI 修复
  • 壳层内部 billing 流程优化
  • 不改变宿主 / runtime 契约的壳层渲染改进

对于这类能力，通常更新 CDN 脚本就够了。

2. 宿主补接入型 ​

这类能力需要生成器的 host page 或 workbench-host.js 一起修改。

例如：

  • 开启 cloudEnabled / historyEnabled
  • 增加 atommProEnv / atommProDomain
  • 通过 CDN 接入时补 atommProScriptUrl / atommProCssUrl
  • 暴露 saveToCloud() 等宿主方法

对于这类能力，只更新 CDN 不够，必须同步改生成器宿主接入代码。

3. Runtime 补接入型 ​

这类能力要求生成器 runtime contract 或 runtime 事件流发生变化。

例如：

  • 让 runtime.getState() 在挂载前的 cloud bootstrap 阶段也可安全调用
  • 正确实现 subscribe(listener)
  • 在模板切换时发出 runtime 可感知的状态变化
  • 在需要自定义保存 payload 时派发 runtime-cloud-save-request

对于这类能力，必须显式升级生成器 runtime 或 runtime adapter。

升级清单的来源：upgrade-manifest.json ​

升级元数据会发布到：

https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json

如果 CDN manifest 暂时不可读，再回退到 MCP 文档查询路径，而不是假设“只更新 CDN 壳就够了”。

这个文件的目标是机器可读，方便被以下角色复用：

  • 文档页面
  • MCP 工具
  • 现有 creating-generators skill
  • 生成器仓库自己的升级检查脚本

Manifest 结构 ​

Manifest 负责记录：

  • 当前最新 generator-workbench 版本
  • 对应的升级文档入口
  • 每个版本的升级说明
  • 每个版本里哪些能力是自动获得型 / 宿主补接入型 / runtime 补接入型
  • 所需 CDN 资源
  • 生成器升级检查清单

结构示意：

json
{
  "schemaVersion": "1.0.0",
  "packageName": "@atomm-developer/generator-workbench",
  "latestVersion": "0.1.21",
  "releases": [
    {
      "version": "0.1.21",
      "previousVersion": "0.1.20",
      "autoAdoptedCapabilities": [],
      "adoptionRequirements": [],
      "cdnAssets": [],
      "generatorChecklist": []
    }
  ]
}

推荐升级流程 ​

当一个生成器已经通过 CDN 接入 generator-workbench 时，推荐按以下顺序升级：

  1. 识别该生成器当前使用的 workbench 版本。
  2. 优先读取 CDN 上的 upgrade-manifest.json，定位目标版本条目。
  3. 把新能力拆成：
    • 自动获得型
    • 宿主补接入型
    • runtime 补接入型
  4. 在理解是否需要宿主/runtime 适配之前，不要只改 CDN 地址就结束。
  5. 更新生成器的宿主 glue code。
  6. 必要时更新生成器 runtime 或 runtime adapter。
  7. 运行与本次能力相关的 smoke test / 回归测试。

CDN 能做什么，不能做什么 ​

CDN 能自动更新 ​

  • workbench 主包本身
  • 壳层内部 bug fix
  • 纯壳层 UI 优化
  • 不改变宿主/runtime 契约的内部壳层编排

CDN 不能自动更新 ​

  • 生成器本地的 workbench-host.js
  • runtime adapter
  • runtime 事件派发
  • 宿主路由策略
  • 生成器自己的回归测试

这一点非常关键。像 flag 这种问题，本质上就是：

  • 壳更新了
  • 但生成器本地宿主接入层没有同步升级

例子：0.1.20 升级到 0.1.21 ​

0.1.21 的 manifest 条目可以作为“模板发布重开行为收敛”的标准例子：壳层现在会缓存第一次打开时解析出的 generatorImage 和 generatorTag，如果第一次 generatorImage 需要上传 OSS，则后续重开会直接复用第一次上传得到的 URL；同时，用户关闭再打开共享的 PublishTemplateModal 时，壳层默认不再自动 resetForm()。

0.1.21 中的自动获得型能力 ​

  • 第一次打开 Publish as Template 时，壳层会把当前解析出的 generatorImage 和 generatorTag 缓存在当前 workbench 实例内存里
  • 如果第一次 generatorImage 是本地图片数据，壳层会完成一次 OSS 上传，并把返回的 URL 也缓存起来；后续再次打开时会直接复用这个 OSS URL，而不是重复上传原始 base64
  • 共享的 atomm-pro 发布弹窗在关闭再打开时，壳层默认不再自动调用 resetForm()，所以草稿表单输入会被保留

0.1.21 中的宿主补接入型能力 ​

  • 对标准生成器接入来说，没有必改项；大多数场景只需要升级 workbench 包或 CDN 脚本即可获得新的重开行为
  • 如果宿主 glue、浏览器测试或自定义包装层以前假设“关闭再打开发布弹窗一定会自动清空表单”，需要同步更新这些断言或包装逻辑
  • 如果自定义集成以前假设“第一次打开后，后续 runtime 再发 select_template / template_publish_media_change 仍会继续替换 generatorTag / generatorImage”，现在也需要调整认知：当前 workbench 实例会继续复用第一次打开时缓存下来的发布身份

0.1.21 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 事件契约

这也说明为什么 0.1.21 基本仍可视为一次 CDN-only 升级，但有一个重要行为差异需要注意：

  • 缓存逻辑和默认不 reset 都完全收敛在 generator-workbench 内部
  • 大多数生成器只要升级包或脚本，就能直接得到“少一次重复上传”和“重开保留草稿”的收益
  • 但如果你们有自定义包装层、浏览器测试或人工流程依赖旧的自动清空行为，或者依赖第一次打开后继续跟随新的 runtime 模板身份，这些外围断言需要显式刷新

例子：0.1.18 升级到 0.1.20 ​

0.1.20 的 manifest 条目可以作为“几乎纯壳层的首屏性能优化版”的标准例子：壳层现在拆分了 shell-ready 与 runtime-ready 时序，把 billing 同步和 Atomm Pro 资源从首屏关键路径移开，并把样式加载改成非阻塞，因此已接入生成器在升级后通常可以直接缩短空白首屏时间。

0.1.20 中的自动获得型能力 ​

  • 壳层现在会提供分阶段的 shell-ready / runtime-ready 时序，同时继续兼容旧的 ready 链路，已有生成器不会因为升级而失去原有 ready 语义
  • syncBillingState、atomm-pro 运行时加载和非关键 CSS 工作都会被后置，不再阻塞首屏壳层渲染
  • atomm-ui 样式现在改为单通道后台拉取，并通过可复用的全局样式注册表去重，多个 workbench 实例不会重复做同样的全局样式注入
  • 当启用 invitation、Publish as Template 或 credits purchase 时，atomm-pro.css 会在后台异步预加载，真正打开共享弹窗前再等待样式就绪，从而修复第一次打开时的样式缺失回归

0.1.20 中的宿主补接入型能力 ​

  • 对标准生成器接入来说，没有必改项；大多数场景只需要升级 workbench 包或 CDN 脚本即可获得这次白屏优化
  • 只有那些直接读取 PublishTemplateModal.open(...) 参数的宿主 glue、浏览器测试或自定义包装层，才需要把 params.style 改成 params.initialData.style
  • 如果生成器本来就依赖 workbench.config.style 传递固定或 runtime 推导出的发布样式，继续按原方式传值即可；变化只在弹窗打开参数里的落点，不在宿主配置字段

0.1.20 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 事件契约

这也说明为什么 0.1.20 对大多数已有生成器来说已经接近一次 CDN-only 升级：

  • 白屏优化本身都收敛在 generator-workbench 内部
  • 大多数生成器只要升级包或脚本，就能得到更早的 shell 渲染和非阻塞资源加载
  • 真正需要注意的兼容点只有一种：如果你们有自定义代码直接读取模板发布弹窗打开参数里的顶层 style，现在要改读 initialData.style

例子：0.1.17 升级到 0.1.18 ​

0.1.18 的 manifest 条目可以作为“壳层补齐模板发布 style 透传”的标准例子：壳层现在会把 workbench.config.style 持续保留到完整的 Publish as Template 链路里，包括最终发给 /community/v2/web/making/template 的 submit 请求；同时，顶栏 logo 现在会跳转到 Atomm 官网。

0.1.18 中的自动获得型能力 ​

  • 如果宿主已经传了 workbench.config.style，壳层现在会把这个值同时带到 PublishTemplateModal.open(...) 和最终的 submit 请求里；即使共享的 atomm-pro 弹窗在 submit 时默认没有带出 style，workbench 也会补回去
  • 点击壳层顶栏 logo 现在会在当前页跳转到 Atomm 官网
  • 这些变化都在 generator-workbench 内部完成，不要求修改 @atomm/atomm-pro

0.1.18 中的宿主补接入型能力 ​

  • 如果生成器希望模板发布弹窗和最终 submit 请求都带上固定或 runtime 推导出的 style，需要在 workbench.mount() 之前显式传入 workbench.config.style
  • 如果 style 模式由 runtime 状态持有，需要由宿主 glue code 显式桥接，例如先读取 runtime.getState().style，再写入 workbench.config.style
  • 不要假设 generator-workbench 会在初始化阶段自动扫描 runtime 任意字段；这一版只是保证 config.style 在 submit 阶段不丢失，初始化桥接仍然由宿主负责

0.1.18 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 事件契约

这也说明为什么 0.1.18 不是“所有生成器都只改 CDN 就能自动获得”的升级：

  • submit 阶段的 style 保留逻辑虽然在 generator-workbench 内部
  • 但只有宿主实际传了 workbench.config.style，生成器才会真正得到这个能力
  • 如果生成器依赖发布态 style 字段，仍建议同时回归“弹窗打开参数”和“最终模板发布请求”两段链路

更早的例子：0.1.16 升级到 0.1.17 ​

0.1.17 的 manifest 条目可以作为“路由模板引导恢复”的标准例子：当 workbench 页面没有 gid、但路由中带有 templateId 时，壳层现在会读取社区 making 详情接口，把完整响应和 data.generatorInfo.info 打印到控制台，再把这个 info 对象恢复到 runtime，然后才会考虑回退到首次 cloud save。

0.1.17 中的自动获得型能力 ​

  • 如果当前路由带有 templateId 且没有 gid，壳层现在会自动请求 /community/v1/web/making/:id
  • 壳层会打印完整 making 响应和 data.generatorInfo.info，再用与 gid restore 相同的 cloud-history source 将这个 info 恢复到 runtime
  • 如果当前路由已经带有 gid，gid restore 仍然优先，模板引导请求不会触发

0.1.17 中的宿主补接入型能力 ​

  • 如果生成器希望从社区模板入口引导恢复，需要由宿主路由构造逻辑显式追加 templateId=<making id>
  • 如果宿主需要显式指定 making 接口环境，需要继续在路由上追加 env=dev|test|prod；否则壳层会回退到 config.atommProEnv
  • 如果某条路由应该恢复已有云草稿，而不是重放模板引导数据，就应继续保留 gid

0.1.17 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 事件契约

这也说明为什么 0.1.17 不是“所有生成器都只改 CDN 就能自动获得”的升级：

  • 真正的 runtime 恢复逻辑虽然在 generator-workbench 内部
  • 但只有宿主实际构造了 templateId 路由，生成器才会走到这条新引导链路
  • 因为路由身份现在会决定恢复来源，所以仍建议同时回归 templateId 路由和 gid 路由

更早的例子：0.1.15 升级到 0.1.16 ​

0.1.16 的 manifest 条目可以作为“模板发布前统一补传 OSS”的标准例子：在共享的 atomm-pro 发布弹窗真正发出创建或更新请求之前，generator-workbench 会把顶层 cover 或 generatorInfo.cover 中仍然是本地图片数据的值先上传到 OSS，再把字段替换成远程 URL。

0.1.16 中的自动获得型能力 ​

  • 如果发布 payload 里的 cover 或 generatorInfo.cover 还是本地图片数据，壳层现在会在最终模板请求发出前自动上传到 OSS
  • 如果这两个字段指向同一份本地图源，壳层会复用同一次上传结果
  • 下游模板发布接口在 submit 时拿到的将是远程 OSS URL，而不是原始本地图片数据

0.1.16 中的宿主补接入型能力 ​

  • 没有；这一版不要求宿主新增配置

0.1.16 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 事件契约

这也说明为什么 0.1.16 可以视为一次典型的 CDN-only 升级：

  • 上传补强逻辑完全在 workbench 的模板发布 bridge 内部
  • 现有生成器仍然复用同一个共享 atomm-pro 发布弹窗
  • 但如果生成器依赖壳层封面或 runtime 覆盖封面参与发布，仍建议补做一次 publish smoke test，确认 submit 时的 cover 已经被规范化成 OSS URL

更早的例子：0.1.14 升级到 0.1.15 ​

0.1.15 的 manifest 条目可以作为“模板发布 payload 契约更新”的标准例子：壳层现在会把 generatorInfo 规范为 { appKey, generatorCode, generatorName, info, template, cover, originImageUrl }，并支持 runtime 用 template_publish_media_change 主动覆盖 generatorImage 与 initialData.cover。

0.1.15 中的自动获得型能力 ​

  • generatorInfo.generatorCode 现在与 appKey 对齐
  • generatorInfo.generatorName 现在优先取模板元信息里的标题，没有时回退到 config.title
  • generatorInfo.info 现在使用最新 runtime state，按 sdk.cloud.save(...) 的 info 结构实时组装
  • 旧的 generatorId、panelSchema、selectedFieldPaths、state、templateMeta 不再出现在发布 payload 的 generatorInfo 中

0.1.15 中的宿主补接入型能力 ​

  • 没有；这一版不要求宿主新增配置

0.1.15 中的 runtime 补接入型能力 ​

  • 如果生成器希望 runtime 自己覆盖模板发布图，需要继续实现 runtime.subscribe(listener)，并发出：
  • template_publish_media_change
  • 事件 payload 形状为 { data: { generatorImage?: string, cover?: string } }

这也说明为什么 0.1.15 不是“所有生成器都完全无感”的升级：

  • 如果生成器只依赖标准的壳层模板发布入口，那么新的 generatorInfo 契约会自动生效
  • 如果生成器 runtime 需要自己传发布封面或预览图，仍然需要补发新的 runtime 事件
  • 如果有下游系统依赖旧的 generatorInfo 字段结构，也需要跟着升级消费逻辑

更早的例子：0.1.13 升级到 0.1.14 ​

0.1.14 的 manifest 条目可以作为“runtime 先渲染、cloud bootstrap 后置”的标准例子：壳层现在会先挂载 runtime，再在后台执行路由级的 gid restore / 首次 cloud save，所以登录流程慢、用户关闭登录弹窗，或者 cloud bootstrap 本身较慢时，都不会再把 runtime 首屏卡成空白。

当前版本在“未登录 + gid 路由”上又进一步收紧了这条行为：

  • mount 仍然保持 runtime 先渲染
  • 如果当前路由已经带有 gid，但本地还没有 token，壳层不会再自动 restore 这条云草稿
  • 当用户后续显式登录后，壳层只会把这条 gid 绑定到当前会话，供后续保存继续写回
  • 对于未登录的新路由，首次 cloud record 创建也会延后到用户显式保存时再发生

0.1.14 中的自动获得型能力 ​

  • runtime 的 canvas/panel 或 workspace 现在会先完成挂载，再等待 gid restore 或首次 cloud save
  • 如果 cloud bootstrap 过程中登录被取消或失败，runtime 也不会因此一直保持空白
  • 对于没有 gid 的新路由，壳层现在会把首次后台建单和后续保存协调起来，减少重复创建首个草稿的风险

0.1.14 中的宿主补接入型能力 ​

  • 没有；这一版只调整壳层内部的挂载与 bootstrap 时序

0.1.14 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变公开的 runtime 契约

这也说明为什么 0.1.14 可以视为一次典型的 CDN-only 升级：

  • 修复点完全在 generator-workbench 的挂载编排内部
  • 现有生成器不需要新增宿主配置，也不需要补新的 runtime 事件
  • 但因为首屏渲染与 cloud bootstrap 的先后关系发生了变化，仍建议回归验证 fresh route、gid restore 路由和未登录入口流程

更早的例子：0.1.11 升级到 0.1.12 ​

0.1.12 的 manifest 条目可以作为“宿主补齐 atomm-pro 多语言接入”的标准例子：壳层现在公开导出了 createAtommProHostI18nConfig()，但旧生成器如果开启了邀请、赚积分、充值或模板发布弹窗，仍然需要在宿主侧显式接入这份 helper，或者手动传入等价的 atommProLocale / atommProMessages。

0.1.12 中的自动获得型能力 ​

  • 没有；这一版提供的是可复用的宿主接入模板，不是单纯替换 CDN 后就会自动生效的壳层内部能力

0.1.12 中的宿主补接入型能力 ​

  • 从 @atomm-developer/generator-workbench 导入 createAtommProHostI18nConfig()，并把它 spread 到 workbench.config；或者手动提供等价的 atommProLocale 与 atommProMessages
  • 确保宿主传入的 message 集合覆盖共享 atomm-pro 流程实际使用到的命名空间，包括：
    • 邀请 / 分享裂变
    • 充值 / 积分购买
    • 模板发布
  • 如果生成器已经有自定义的 atomm-pro 文案覆盖，应在新的 starter config 之上继续 merge，而不是删掉新增需要的 key

0.1.12 中的 runtime 补接入型能力 ​

  • 没有；这一版不改变 runtime 契约

这也说明为什么 0.1.12 不是“所有生成器都只改 CDN 就能完全接通”的升级：

  • shell 主包现在公开了标准的 atomm-pro 宿主多语言模板
  • 但如果宿主没有实际传入 locale/messages，邀请弹窗和充值弹窗仍然可能直接显示原始 i18n key
  • 如果某个生成器根本没有启用任何 atomm-pro 邀请 / 充值 / 发布 UI，这个版本通常可以视为非阻塞升级

更早的例子：0.1.10 升级到 0.1.11 ​

0.1.11 的 manifest 条目可以作为“模板发布链路升级”的标准例子：壳层现在会直接打开共享的 @atomm/atomm-pro 发布弹窗，而生成器如果希望 generatorTag 跟随 runtime 当前模板选择，则需要继续补齐 select_template 事件。

0.1.11 中的自动获得型能力 ​

  • 点击模板发布入口时，壳层现在会直接打开 @atomm/atomm-pro 的 PublishTemplateModal，而不是停留在原来的壳层字段勾选弹窗
  • 壳层会自动把 runtime state、标准模板 JSON、cover/origin image 和模板元信息映射到发布弹窗 payload
  • 只要生成器已经使用标准 workbench 模板入口，升级 shell 后就立即能获得这套发布弹窗集成

0.1.11 中的宿主补接入型能力 ​

  • 如果发布弹窗需要预填 summary、contentTags，或者需要稳定的 generatorInfo.generatorName 与兜底 generatorTag，建议通过 workbench.config.getTemplateMeta() 传入
  • getTemplateMeta().generatorTag 现在只作为兜底值；如果 runtime 已发出 select_template.data.name，壳层会优先使用 runtime 的值

0.1.11 中的 runtime 补接入型能力 ​

  • runtime.subscribe(listener) 继续作为标准的 runtime -> workbench 事件通道
  • 如果希望发布弹窗里的 generatorTag 跟随 runtime 模板选择，应在选择变化时发出 select_template，载荷为 { data: { name, category? } }
  • data.name 应该就是最终希望传给发布弹窗的标签文本，因为壳层现在会把最新一次事件里的 name 直接复用为 publishParams.generatorTag
  • 其他壳层能力如果仍依赖 params_change 或 state-change，则继续分别保留，不要混用替代

这也说明为什么 0.1.11 不是“所有生成器都只改 CDN 就能完全接通”的升级：

  • shell 主包已经带上了 atomm-pro 发布弹窗接入
  • 但如果希望 generatorTag 动态跟随 runtime 模板选择，仍然需要生成器自己正确发出 select_template.data.name
  • 如果某个生成器暂时不需要 runtime 驱动标签，也可以先升级 shell，并继续使用 getTemplateMeta().generatorTag 作为兜底值

生成器侧升级检查清单 ​

当 manifest 显示某个版本包含宿主补接入型或 runtime 补接入型能力时，至少检查以下内容：

  • 这次能力是自动获得型，还是需要宿主/runtime 改造？
  • 生成器是否显式传入了新的 workbench.config 字段？
  • 如果 runtime 行为依赖 embed/full 路由能力，是否已经读取 routeMode？
  • runtime 是否实现了 subscribe(listener)？
  • 如果宿主或壳层需要观察业务事件，runtime 是否发出了 select_template 或 params_change？
  • 如果宿主需要反向命令，workbench.dispatchRuntimeCommand(...) 和 runtime.dispatchWorkbenchCommand(...) 是否已成对接通？
  • runtime 是否会在 runtime 自有编辑行为后发出可观察的状态变化？
  • 如果保存需要自定义 payload，runtime 是否派发了 runtime-cloud-save-request？
  • 如果开启了 cloud route bootstrap，runtime.getState() 在真实子 runtime mount 前是否可安全调用？
  • 如果启用了邀请或充值弹窗，相关 atomm-pro CDN 资源是否可访问？
  • 生成器是否补了覆盖新能力的 smoke test？

这套东西如何接到 MCP 和 Skill ​

这篇文档和 upgrade-manifest.json 的设计目标，是为了让现有的 generator-sdk-mcp/skills/creating-generators 后续可以直接复用，而不是再新增一个 skill。

预期流程是：

  1. creating-generators 识别当前任务是旧生成器升级或 workbench 兼容升级
  2. 优先读取 https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json
  3. 如果 CDN manifest 读取失败，再走 MCP 文档兜底
  4. 扫描目标生成器仓库中的 host/runtime 接入点
  5. 输出该生成器自己的升级检查清单

也就是说，升级知识应该集中在：

  • 这篇升级文档
  • upgrade-manifest.json
  • 现有 creating-generators skill 的流程补充

而不是靠不断增加新的 skill。

发布要求 ​

当 generator-workbench 增加、删除或更新能力时，应在同一个发布任务里同时更新：

  • https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json
  • 这篇文档
  • docs/guide/generator-workbench-upgrade.md
  • 如果壳层行为发生变化，也要同步更新：
    • docs/guide/generator-workbench.md
    • docs/zh/guide/generator-workbench.md
  • 如果通信契约发生变化，也要同步更新：
    • docs/guide/generator-workbench-runtime-communication.md
    • docs/zh/guide/generator-workbench-runtime-communication.md
  • 以及任何描述接入路径的 MCP / skill 参考文档

相关文档 ​

MIT Licensed

Atomm Studio