Generator SDK

简体中文

English

简体中文

English

Appearance

生成器开发者上手 ​

这篇文档面向希望通过 Cursor + AI 开发新生成器，或重构已有旧生成器的开发者。目标不是只生成一个完整页面，而是让生成器收敛为默认具备 generator-sdk 平台能力和 full / embed 双模式的标准接入形态。

你会得到什么 ​

使用这套链路后，AI 在新建或重构场景下默认会朝以下目标收敛：

  • 通过 generator-sdk 接入登录、导出、Open in Studio、积分、计费等平台能力
  • 暴露 window.__GENERATOR_RUNTIME__
  • 同时支持完整页面和模板页中的 embed mode
  • 支持 PanelSchema 和 PanelFilter
  • 后续可以在模板页中实现左侧 canvas、右侧部分参数面板
  • 如果明确需要模板作者能力，可自动启用 template feature，生成模板发布 / 导入骨架

对于旧生成器，AI 还应先区分两种任务口径：

  • 兼容性重构：以不回归和最小改动为优先，允许阶段性交付
  • 标准化重构：最终收敛到标准 generator 结构，不能只停在“SDK + 轻量 bridge”

前置准备 ​

在开始前，请先准备：

  • 一个可用的 Cursor 环境
  • Node.js 18 或更高版本
  • CMS 登录权限

其中 appKey 本质上是生成器的 id，会直接写入 GeneratorSDK.init({ appKey })。开发者可以自己定义一个稳定的 id，只要同一个生成器始终使用同一个值即可。

第一步：安装 Agent Skills 和 MCP ​

在 Cursor 的 MCP Servers 配置中加入：

json
{
  "mcpServers": {
    "generator-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "@atomm-developer/generator-sdk-mcp@latest"
      ]
    }
  }
}

保存后重启 Cursor。

第二步：把 skill 放到项目里 ​

skills 的公开仓库地址是 xtool-official/xtool-skills。如果你想查看 creating-generators 的来源、可安装内容，或确认 marketplace 对应仓库，可以直接打开这个仓库。

1.1 方式一：手动安装 Agent Skills

claude plugin marketplace add xtool-official/xtool-skills
claude plugin install creating-generators@xtool-skills

1.2 方式二：让AI自己安装

请帮我安装 creating-generators 接入相关的 skills。
1. 先添加 marketplace 源（如果还没添加的话）：
   xtool-official/xtool-skills
2. 然后安装以下 plugin：
   - creating-generators
安装完成后，告诉我安装结果。

1.3 方式三: 在你的生成器项目根目录创建：

txt
.cursor/
  skills/
    creating-generators/
      SKILL.md
      reference.md

如果开发者无法直接从发布包中找到 skill 文件，也可以直接从文档页复制：

第三步：第一次怎么问 AI ​

装好 MCP 和 skill 后，不需要先粘贴一大段固定规范。通常只需要表达“我要开发一个生成器”的意图。

例如：

text
帮我做一个新的相框生成器

或：

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

正常情况下，skill 会自动继续追问：

  1. 生成器名称
  2. 生成器 appKey
  3. 技术栈：html 或 vue
  4. 需要接入哪些 SDK 功能
  5. 是否需要模板作者能力

问完后，AI 会默认补上这些约束：

  • 使用 runtime starter，而不是只生成一个完整页面
  • 默认启用 full / embed
  • 默认暴露 window.__GENERATOR_RUNTIME__
  • 默认实现 getState、setState、patchState、getPanelSchema、export、subscribe
  • 参数面板支持 PanelFilter
  • 如果用户提到模板、模板页、子生成器、预设参数或只允许部分参数可调，默认启用 template feature

如果你给的是旧生成器重构任务，新的默认追问顺序应先问清：

  1. 这是 兼容性重构，还是 标准化重构
  2. 旧代码目录或仓库在哪里
  3. 现有生成器 appKey 是否沿用
  4. 当前技术形态是 html / vue / bridge / 部分 runtime
  5. 是否允许分阶段交付

旧生成器推荐提示词 ​

如果你想要的是兼容性重构，建议直接这样说：

text
这是一个旧生成器源码 @index.html。
请在 @refactor 目录中做兼容性重构：
1. 所有功能、交互、样式、导出行为不能改变
2. 接入 generator-sdk
3. 允许分阶段交付，但不要把阶段性交付说成标准化完成

如果你想要的是标准化重构，建议直接这样说：

text
这是一个旧生成器源码 @index.html。
请在 @refactor 目录中做标准化重构，而不是只做最小兼容改造：
1. 所有功能、交互、样式、导出行为不能改变
2. 接入 generator-sdk
3. 补齐完整 Generator Runtime Contract
4. 提供 full / embed 双入口
5. 支持 PanelSchema + PanelFilter
6. 如果涉及模板场景，使用统一模板协议
7. 未达到标准化完成态前，不要宣称已完成标准 generator 改造

一段真实对话示例 ​

text
开发者：帮我做一个新的相框生成器

AI：先确认生成器名称。你希望这个生成器最终展示的名称是什么？

开发者：春日相框生成器

AI：我会先为这个新生成器自动生成一个开发态 appKey，并直接写入 GeneratorSDK.init({ appKey })。如果你后续需要复用线上已有 appKey，再告诉我即可。

AI：你希望使用哪种技术栈？可选：html / vue。默认建议：快速 vibe coding 用 html，工程化项目用 vue。

开发者：vue

AI：需要接入哪些 SDK 能力？可多选：登录、导出 SVG、Open in Studio、积分、统一计费、云保存、历史记录。

开发者：登录、导出 SVG、Open in Studio、积分

AI：是否需要模板作者能力？如果涉及模板、模板页、子生成器、预设参数或只允许部分参数可调，我会自动启用 template feature。

开发者：需要，要支持发布模板和导入模板。

AI：收到。我会基于 starter-vue-runtime 生成项目骨架，默认启用 full / embed 双模式，并自动补齐 __GENERATOR_RUNTIME__、getState、setState、patchState、getPanelSchema、export、subscribe，以及模板页所需的 PanelFilter 能力。同时启用 template feature，生成统一模板 JSON 协议和“发布模板 / 导入模板”骨架。接下来开始生成代码。

AI 实际会做什么 ​

正常情况下，AI 会通过 MCP 完成这些工作：

  1. 识别“开发生成器”意图
  2. 判断是新建、兼容性重构，还是标准化重构
  3. 询问生成器名称 / 旧代码位置 / 开发态或已有生产 appKey / 技术栈 / SDK 功能
  4. 查询 generator-sdk 和 Runtime Contract 文档
  5. 新建场景调用 generate_runtime_starter
  6. 重构场景先做差距分析，再决定是 adapter、runtime 包装还是参考 starter 重构
  7. 如果用户明确需要模板作者能力，启用 template feature
  8. 输出阶段、未完成项和 CMS / 迁移说明，而不是只说“已完成”

生成完成后要检查什么 ​

你可以让 AI 自检以下项目：

text
请确认这个生成器是否已经支持：
1. full / embed 双模式
2. window.__GENERATOR_RUNTIME__
3. getPanelSchema + PanelFilter
4. 模板页只挂载 canvas 和部分参数面板

如果是旧生成器重构，还建议增加一轮“完成口径”自检：

text
请按以下字段汇报当前状态：
1. 任务口径：兼容性重构 / 标准化重构
2. 当前阶段
3. 已完成项
4. 未完成项
5. 是否可宣称标准化完成
6. 兼容性与迁移说明

只有当 generator-sdk、完整 runtime、full/embed、window.__GENERATOR_RUNTIME__、getPanelSchema + PanelFilter，以及按需模板协议都补齐后，才应宣称“标准化重构完成”。

如果你的目标是让生成器接入模板页，也建议继续阅读：

最后一步：去 CMS 配置 ​

代码完成后，还需要去 CMS 完成平台侧配置：

至少需要配置：

  • appKey
  • 生成器名称
  • 分享裂变相关配置
  • 积分 / 免费次数相关配置

常见错误 ​

只让 AI 生成完整页面 ​

这会导致后续没有 embed mode，模板页也无法稳定接入。

把登录、导出、积分写死在页面里 ​

正确做法是通过 generator-sdk 接入，而不是自己再造一套协议。

模板页重写一套参数逻辑 ​

正确做法是让生成器返回 PanelSchema，再由模板页通过 PanelFilter 只渲染部分参数。

把阶段性交付说成“已按 skill 完成” ​

如果只是完成了 SDK 接入、兼容层或部分 runtime，只能表述为“阶段性交付”或“兼容性重构完成”，不能说“已经完成标准化重构”。

一句话原则 ​

不是“先做页面，再补 embed”，而是“先从 runtime starter 开始，再继续做页面”。

MIT Licensed

Atomm Studio