Generator SDK

简体中文

English

简体中文

English

Appearance

AI 接入补充说明 ​

这篇文档承接 AI 接入：用 Cursor 开发生成器 的快速开始内容，补充默认规则、旧生成器改造、自检方式、发布事项和常见错误。

最短提示词 ​

如果你只是想先把第一版骨架跑起来，可以直接这样问：

text
帮我开发一个新的挂件生成器，按 creating-generators 的默认标准路径来做，先完成一个最小可运行 demo。

skill 会把默认路径补出来，包括：

  • generator-workbench
  • starter-html-runtime
  • full / embed
  • 标准 runtime 暴露
  • auth、credits、billing、export、template
  • 在默认 html 路径接入 generator-workbench 后，业务 UI 默认优先使用 atomm-ui，并保持 CDN 引入
  • 当 runtime 业务 UI 使用 atomm-ui 时，AI 还应确保样式被注入到 runtime 的实际挂载根节点，而不是只把 CSS 放在页面 <head>

如果你想收紧范围 ​

如果这次只是先做标准骨架，不扩展额外平台能力，可以继续补一句：

text
这次先保持默认标准路径，不额外扩展 `cloud` / `history`。
请先完成最小可运行骨架，方便后面继续迭代业务逻辑。

这样 AI 会收紧范围，但仍保留标准 generator 的默认结构，而不是退化成一个普通页面。

先记住这条默认规则 ​

如果你是在做一个新的标准生成器，通常不需要先手动告诉 AI：

  • appKey 是什么
  • 技术栈选什么
  • 要不要 generator-workbench
  • 要不要 full / embed
  • 要不要 auth、billing、export、template

安装好 MCP 和 skill 后，AI 默认应按下面这条路径执行：

  1. 识别这是 generator 任务
  2. 默认使用 html + starter-html-runtime
  3. 默认让 generator-workbench 使用 shell 模式挂载，让 runtime 接管完整 workspace 布局
  4. 默认生成 full / embed 双入口
  5. 默认补齐 window.__GENERATOR_RUNTIME__、getPanelSchema() 和标准 runtime 接口
  6. 默认启用 auth、credits、billing、export、template
  7. 在默认 html + generator-workbench 路径下，默认让业务 UI 使用 atomm-ui + CDN
  8. 如果 runtime 业务 UI 用了 atomm-ui，默认补上面向实际样式宿主的注入逻辑，兼容 Shadow Root / 普通 DOM
  9. 默认生成开发态 appKey，而不是先卡在配置提问

只有在你显式偏离默认路径时，AI 才应该继续追问，例如：

  • 明确要求 vue
  • 明确要求 reduced-scope
  • 明确要求 custom shell
  • 明确要求 runtime-only
  • 明确要求 cloud 或 history
  • 明确说明这是“旧生成器改造”

已有生成器怎么问 ​

如果你已经有一个生成器项目，不要让 AI “重新创建项目”，而是要先说清楚这是增量改造。

当前 skill 对旧生成器最重要的不是先问 appKey，而是先明确任务口径：

  • compatibility refactor
  • standardization refactor

你可以直接这样问：

text
这是一个已有的生成器项目，请不要重建项目，而是在现有代码上改造。

任务口径：standardization refactor

已知信息：
1. 当前已有挂件预览和参数面板
2. 请先分析当前项目结构，再决定在哪里接入 generator-sdk
3. 我希望它收敛到标准 generator 结构

请先完成：
1. 判断当前项目适合用兼容改造还是标准化改造
2. 接入 generator-sdk
3. 补齐 runtime、`full` / `embed`、`PanelSchema`
4. 说明你准备修改哪些文件，以及还缺什么信息

只有当这是旧项目，并且确实需要复用线上配置时，appKey 才需要成为后续问题；它不应该再作为新项目默认起步时的前置门槛。

AI 实际会做什么 ​

接入 MCP 和 skill 后，AI 通常会按这个顺序工作：

  1. 判断这是不是 generator 任务
  2. 判断是新建项目还是已有项目改造
  3. 新建场景默认走 generator-workbench + runtime starter
  4. 优先生成标准 runtime，而不是手写 custom full shell
  5. 补齐 full / embed、window.__GENERATOR_RUNTIME__、getPanelSchema()
  6. 只在你显式偏离默认路径时继续追问配置
  7. 最后汇报当前阶段、已完成项、未完成项和风险

让 AI 自检 ​

代码生成完以后，建议你马上让 AI 做一轮自检：

text
请检查这个生成器是否已经满足 creating-generators 的默认标准路径，并按下面字段汇报：
1. 任务口径
2. 当前阶段
3. 已完成项
4. 未完成项
5. 是否达到标准化完成状态
6. 风险和阻塞点
7. MCP 使用路径
8. 是否使用了官方 `generator-workbench`

如果你只想检查最小 demo 是否跑通，也可以这样问：

text
请确认当前是否已经具备：
1. `generator-workbench`
2. `full` / `embed`
3. `window.__GENERATOR_RUNTIME__`
4. `getPanelSchema()`
5. 最小挂件 demo 可运行

发布前再处理 CMS 和上传 ​

如果你当前只是想让 AI 帮你搭第一版工程，这一步可以先放后面。

真正准备发布或接平台时，再去处理 CMS 和资源上传：

常见发布动作包括：

  1. 在 CMS 中补全生成器名称、正式配置和平台侧信息
  2. 构建项目并打包 zip
  3. 上传构建产物

这属于“发布阶段”，不应该再占据 AI 快速起步文档的主要篇幅。

推荐提示词模板 ​

如果你想复用这套方式，可以直接把下面这段作为模板：

text
帮我开发一个新的挂件生成器。

请按 creating-generators 的默认标准路径来做，不要先卡在 `appKey`、壳层或 feature 选择上。

目标：
1. 默认使用 `generator-workbench`
2. 默认生成标准 runtime，支持 `full` / `embed`
3. 保留 `PanelSchema` 和标准 runtime 接口
4. 接入 `generator-workbench` 后，业务 UI 默认使用 `atomm-ui`，并通过 CDN 引入
5. 不要只停留在页面 `<head>` 引 CSS；如果 runtime 业务 UI 用了 `atomm-ui`，要兼容实际挂载根节点的样式注入
6. 先完成一个最小可运行 demo

挂件要求：
- 左侧预览
- 右侧参数面板
- 极简矩形挂件
- 内部只有 generator

完成后请汇报：
1. 当前阶段
2. 已完成项
3. 未完成项
4. 风险和后续建议

常见错误 ​

没装 MCP，就直接让 AI 写接入代码 ​

这样 AI 很容易凭记忆猜 API，把 generator-sdk 用法写偏。

没装 skill，就只让 AI “随便做个生成器” ​

这样 AI 很容易只生成一个页面，缺少 full / embed、runtime 和 PanelSchema。

新生成器一上来就追问 appKey ​

当前 skill 的默认路径已经允许 AI 先生成开发态 appKey，不需要把它当成起步阻塞项。

把 generator-workbench 当成后续增强项 ​

对于新的标准生成器，generator-workbench 应该是默认宿主壳层，并优先选择 shell 模式，而不是“先随便写一个壳，后面再换”。

从 generate_code 或手写 demo 开始，而不是从 starter 开始 ​

这样 AI 很容易回到局部示例页或 custom shell，而不是标准 generator 的默认接入路径。

以为把 atomm-ui CSS 放进 index.html 的 <head> 就已经完成了 ​

在 generator-workbench 挂载 runtime 时，runtime 的业务 UI 可能被挂进 Shadow Root 或其他隔离根节点。此时只靠页面级 CSS 不能保证业务组件样式生效，AI 需要额外确认 runtime 侧的样式宿主处理。

一句话原则 ​

不是“让 AI 随便生成一个页面”，而是“先配置 MCP 和 skill，然后让 AI 按 creating-generators 的默认标准路径，直接生成一个接入 generator-workbench 的标准生成器骨架”。

MIT Licensed

Atomm Studio