Generator SDK

简体中文

English

简体中文

English

Appearance

AI 接入：用 Cursor 开发生成器 ​

目标：

  1. 在 Cursor 里配置 generator-sdk MCP
  2. 安装 creating-generators skill
  3. 直接用自然语言让 AI 生成一个标准生成器

这篇文档只保留最短路径：先配置 MCP，再安装 skill，然后直接让 AI 开始开发生成器。

如果你需要默认规则、旧项目改造、自检方式、发布说明和常见错误，请继续看 AI 接入补充说明。

查看完整示例

最快路径：让 AI 帮你全程完成接入 ​

如果你只想最快开始，在完成步骤 1（MCP 配置 + 重启 Cursor）之后，直接发这条消息，让 AI 一次性完成 skill 安装和接入验证：

text
请帮我完成 generator-sdk 的 AI 接入配置：
1. 如果还没添加 marketplace 源，先添加 xtool-official/xtool-skills
2. 安装 creating-generators skill
3. 完成后，调用一次 generator-sdk MCP 告诉我它的当前版本，并列出你识别到的可用工具
4. 告诉我接入是否成功

AI 会自行完成安装，不需要你守着——有需要你操作的地方，AI 会主动告诉你。 收到 AI 的"接入成功"回复之后，就可以直接提生成器需求了。

如果出现问题，或者你想了解每一步的细节，继续看下方的三步说明。

三步快速开始 ​

步骤 1：配置 MCP ​

在 Cursor 的 MCP Servers 配置中加入：

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

保存后重启 Cursor。

这一步的作用是让 AI 可以直接查询 generator-sdk 文档、runtime contract、starter 和生成器相关工具，而不是凭记忆猜 API。

步骤 2：安装 creating-generators skill ​

最简单的方式，是直接让 AI 帮你安装。发送后不需要守着——AI 会自行完成安装并告诉你结果，有需要你操作的地方会主动提示。

text
请帮我安装 creating-generators 相关 skill。
1. 如果还没添加 marketplace 源，先添加:  xtool-official/xtool-skills
2. 然后安装 creating-generators skill, 仓库: https://github.com/xtool-official/xtool-skills
3. 安装完成后告诉我结果。
点击展开查看手动安装方式

skills 的公开仓库地址是 xtool-official/xtool-skills。如果你想确认安装方式、查看 creating-generators 的内容，或手动安装 skill，可以直接参考这个仓库的 README。

如果你想手动安装，也可以执行：

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

如果你是在 Cursor 里手动安装，README 还提供了 3 种常用方式：

  1. 通过 Cursor 图形界面导入 GitHub 远程规则：
  • 打开 Settings -> Rules -> Add Rule -> Remote Rule (Github)
  • 填入仓库地址：https://github.com/xtool-official/xtool-skills.git
  1. 安装到当前项目：
bash
mkdir -p .cursor/skills/creating-generators
cp skills/creating-generators/SKILL.md .cursor/skills/creating-generators/SKILL.md
cp skills/creating-generators/reference.md .cursor/skills/creating-generators/reference.md
  1. 安装到本机所有项目：
bash
mkdir -p ~/.cursor/skills/creating-generators
cp skills/creating-generators/SKILL.md ~/.cursor/skills/creating-generators/SKILL.md
cp skills/creating-generators/reference.md ~/.cursor/skills/creating-generators/reference.md

如果你后续需要更新 skill，建议按你原来的安装方式重新执行一遍

如果 Cursor 没有立刻识别到新安装的 skill，按以下顺序排查：

现象原因操作
AI 不走标准 generator 流程skill 尚未加载到当前会话新开一个 Agent chat
新开 chat 仍无效Cursor 未重新加载 skill 文件重启 Cursor
AI 回答 MCP 相关问题时凭记忆猜测MCP 未正常运行检查 Cursor 右下角 MCP 状态，确认 generator-sdk 是绿色
MCP 显示绿色但 AI 仍答错AI 没有实际调用 MCP发"请调用 generator-sdk MCP 列出可用工具"，确认 AI 是在查文档而非凭记忆

装好以后，AI 识别到“开发生成器”意图时，会优先走标准 generator 工作流，而不是先写一个临时页面。

验证接入是否成功 ​

在正式提需求之前，建议先发这条验证消息，确认 MCP 和 skill 都已就位：

text
请帮我验证 generator-sdk 接入状态：
1. 调用一次 generator-sdk MCP，告诉我它的当前版本号
2. 告诉我你是否识别到了 creating-generators skill
3. 列出你识别到的可用 MCP 工具名称

AI 给出版本号和工具列表，说明 MCP 在真实工作；AI 提到 creating-generators skill，说明 skill 已就位。两项都确认后，就可以直接提生成器需求了。

步骤 3：直接提需求 ​

完成 MCP 和 skill 以后，新的生成器项目可以直接这样开始：

text
帮我开发一个新的挂件生成器,请按 creating-generators 的默认标准路径来做。

挂件样式：
- 极简矩形挂件
- 挂洞在矩形内部
- 内部只有单词 generator

这类场景下，文档推荐你把注意力放在“你想做什么生成器”，而不是“先把接入配置手工列全”。

已接入 generator-workbench 的旧项目，如何让 AI 帮你升级

如果你的项目已经接入了 generator-workbench，现在只是想让 AI 帮你升级到新能力，最简单的方式不是先自己判断要不要改 host/runtime，而是直接把项目背景告诉 AI，让它先做一次 upgrade audit。

你可以直接这样说：

text
这是一个已经接入 generator-workbench 的旧生成器项目，请帮我升级 generator-workbench。

要求：
1. 先按 creating-generators 的 workbench upgrade audit 流程处理
2. 先读取 CDN 上的 upgrade manifest：
   https://static-res.atomm.com/scripts/js/generator-sdk/generator-workbench/upgrade-manifest.json
3. 如果 CDN manifest 读取失败，再走 MCP 文档兜底
4. 先判断这次升级里哪些是 auto-adopted、哪些是 host-action-required、哪些是 runtime-action-required
5. 先输出这个项目自己的升级检查清单，再开始改代码

项目路径：
<你的项目路径>

当前问题或目标：
<例如：接入 cloud/history、补齐 atomm-pro 弹窗、修复 template 切换后不触发 cloud save>

如果你已经知道当前版本和目标版本，也可以把版本窗口一起告诉 AI：

text
这个项目当前使用的是 generator-workbench 0.1.5，请帮我升级到 0.1.6。
请先做 workbench upgrade audit，再实施修改。

这样对话的好处是：

  • AI 会先把“只改 CDN 就能生效”的项和“必须改生成器宿主/runtime”的项拆开
  • AI 会优先检查 workbench.config、workbench-host.js、runtime adapter、runtime-cloud-save-request 等关键接入点
  • AI 会先给出 checklist，再进入实现，避免一上来就误改壳层内部逻辑

更新与维护 ​

接入完成后，日常维护只需关注以下几种情况：

情况操作
MCP 有新版本无需手动更新，npx -y ... @latest 每次运行时自动拉取最新版
Skill 有新版本按原安装方式重新执行一遍；或让 AI 执行 claude plugin install --update creating-generators
Cursor 升级后 MCP 消失检查 .cursor/mcp.json 是否保留了配置，确认后重启 Cursor
AI 突然"忘记"标准 generator 流程新开 chat；仍不生效则重启 Cursor；最后确认 skill 文件是否还在
想确认当前 MCP 版本与工具列表发"请调用 generator-sdk MCP 列出可用工具"，AI 会实时查询并返回

继续阅读 ​

如果你已经完成这三步，或者想进一步了解：

  • 默认规则和 AI 的自动行为
  • 旧生成器如何改造
  • 如何让 AI 做自检
  • CMS / 上传等发布阶段事项
  • 更完整的提示词模板和常见错误

请查看 AI 接入补充说明。

MIT Licensed

Atomm Studio