Vue 脚手架启动开发

这篇文档面向还没有开始开发生成器的开发者。它只讲如何用一条命令创建、启动、构建 Vue 3 + Vite + generator-workbench 项目。

如果你想了解脚手架目录、文件职责、配置项、Runtime Contract 和能力升级方式，请看 Vue 脚手架结构说明。

适用场景

使用脚手架适合这些情况：

• 你要从零开始开发一个新的生成器
• 你希望默认复用官方应用壳，而不是自己写顶部栏、登录入口、导出按钮
• 你希望先接入 basic 档位：登录、积分、计费、下载、Open in Studio
• 你暂时不需要云保存、历史记录或 Publish as Template

如果你已经有一个生成器，需要保留现有代码并接入应用壳，请看 手把手接入应用壳。

一条命令创建项目

pnpm dlx @atomm-developer/generator-sdk-mcp@latest create-workbench-vue my-generator --app-key your_app_key

也可以先用开发态 appKey 生成项目，之后再修改 config.json：

pnpm dlx @atomm-developer/generator-sdk-mcp@latest create-workbench-vue my-generator

常用参数：

参数	说明
<project-name>	要创建的项目目录名，同时作为默认 package name 和 generatorId 来源
--app-key <appKey>	开发者控制台中注册的生成器 appKey；不传时生成 dev_<project_name>
--env <env>	SDK 环境，默认 test，可改为 dev / pre / prod / prod_cn
--title <title>	应用壳顶栏标题，不传时从项目名自动生成
--force	允许写入非空目录

启动开发服务器

cd my-generator
pnpm install
pnpm dev

脚手架生成的 package.json 已默认包含 pnpm.onlyBuiltDependencies: ["esbuild"]，用于兼容 pnpm 10/11 的依赖构建脚本审批机制，避免 Vite 依赖的 esbuild 被标记为 ignored build。

开发时建议直接打开自检模式：

http://localhost:5173/?debug=true

自检面板会检查 workbench.sdk、workbench.runtime、config 和 mount() 顺序是否正确。

默认能力档位

脚手架默认使用 workbench-basic：

workbench.config = {
  mode: 'shell',
  atommProEnv: config.env,
  exportEnabled: true,
  studioEnabled: true,
  templateEnabled: false,
  cloudEnabled: false,
  historyEnabled: false,
  autoSaveEnabled: false,
}

这意味着：

• 应用壳负责顶部栏、登录、积分、计费、导出按钮
• runtime 只负责画布、参数面板、状态和导出数据
• 默认不显示 Publish as Template
• 默认不改造 Template Definition Protocol
• 默认不启用云保存和历史记录

后续如果需要云保存 / 历史记录，再显式升级为 workbench-cloud；如果需要发布模板、模板页嵌入或 customize 流程，再显式升级为 workbench-template。

从哪里开始改业务

通常只需要改三处：

1. 在 src/runtime/state.ts 定义你的业务状态。
2. 在 src/runtime/panel-schema.ts 用 PanelSchema 暴露可编辑参数。
3. 在 src/components/RuntimeView.vue 实现画布和参数面板交互。

修改参数时请通过 runtime.patchState() 更新状态。这样应用壳才能收到 state-change / params_change 事件，后续升级云保存、历史记录或模板发布时不需要重写状态链路。

用 AI 开始开发自己的生成器

脚手架生成后，可以在 Cursor、Claude Code 等 AI IDE 中打开项目目录，让 AI 直接基于脚手架实现你的生成器业务。

建议先把需求说清楚，再要求 AI 只改业务文件：

我已经通过 create-workbench-vue 创建了一个 generator-workbench Vue 脚手架项目。

请基于当前脚手架开发一个「你的生成器名称」生成器，需求如下：
1. 画布中需要展示：……
2. 用户可以调整的参数包括：……
3. 导出格式需要支持：SVG / PNG / Studio（按实际填写）

请遵守这些约束：
- 保持 generator-workbench 作为官方应用壳，不要重写顶部栏、登录、积分、导出按钮。
- 默认使用 workbench-basic 能力，不要开启 cloudEnabled、historyEnabled、templateEnabled。
- 主要修改 src/runtime/state.ts、src/runtime/panel-schema.ts、src/runtime/export.ts、src/components/RuntimeView.vue。
- 修改参数时通过 runtime.patchState() 更新状态。
- 完成后运行 pnpm build，并说明改了哪些文件。

如果你确实需要云保存、历史记录或 Publish as Template，不要在第一轮提示词里含糊地说“接入所有能力”。建议明确说明要升级到哪个档位：

请在当前脚手架基础上升级到 workbench-cloud：
- 开启 cloudEnabled 和 historyEnabled
- 提供可 JSON 序列化的 snapshot
- 如能从画布生成封面图，请把 cover 接入云保存
- 不要开启 templateEnabled

只有需要发布模板、模板页嵌入或 customize 流程时，才让 AI 升级到 workbench-template。

构建与部署

本地构建：

pnpm build

产物在 dist/。部署到静态站点时，把 dist/ 整个目录上传到你的静态托管服务即可。

脚手架的 vite.config.ts 默认设置了 base: './'，构建后的资源会以 ./assets/... 相对路径加载。因此无论部署在站点根路径，还是像 /my-generator/dist/index.html 这样的子目录路径，都不会因为 /assets/... 绝对路径导致资源 404。

构建时脚手架还会把项目根目录的 config.json 复制到 dist/config.json，入口代码会通过 ./config.json 加载运行时配置。部署时请确保 dist/config.json 与 dist/index.html 一起上传；如果上线后修改 appKey 或 env，只需要替换 dist/config.json。

部署前检查：

• config.json 中的 appKey 已替换为开发者控制台注册值
• env 与目标环境一致，例如中国正式环境使用 prod_cn
• atommProLocale 已按目标用户设置，例如英文 en-US、中文 zh-CN
• 生产访问一次 /?debug=true，确认自检面板核心项通过
• 如果走 Makeblock 内部静态部署，确保服务支持 SPA fallback 到 index.html

继续阅读

• Vue 脚手架结构说明：目录、文件作用、配置项、Runtime Contract、样式策略和能力升级。
• 应用壳功能与配置参考：查看 generator-workbench 的完整能力和配置。
• 应用壳接入自检：排查 SDK、runtime、config 和 mount 顺序问题。

相关文档

• 核心概念
• Vue 脚手架结构说明
• 应用壳功能与配置参考
• 应用壳与生成器通信
• 发布模板协议
• 应用壳接入自检