Vue 脚手架结构说明

这篇文档介绍 create-workbench-vue 生成项目的目录、文件作用、配置项和扩展方式。只想创建并启动项目时，先看 Vue 脚手架启动开发。

生成后的目录结构

my-generator/
├── config.json
├── index.html
├── package.json
├── tsconfig.json
├── src/
│   ├── env.d.ts
│   ├── main.ts
│   ├── platform/
│   │   └── config.ts
│   ├── runtime/
│   │   ├── export.ts
│   │   ├── index.ts
│   │   ├── panel-schema.ts
│   │   ├── state.ts
│   │   ├── styles.css
│   │   └── types.ts
│   └── components/
│       └── RuntimeView.vue
├── README.md
└── vite.config.ts

目录与文件作用

脚手架把「平台接入」和「生成器业务」分开。开发者日常主要改 src/runtime/ 和 src/components/RuntimeView.vue，通常不需要改应用壳挂载逻辑。

文件	职责
config.json	部署时可替换配置，保存 appKey、env、标题、atomm-pro 域名和语言。入口代码会运行时通过 ./config.json 读取它，避免把正式 appKey 写死在源码里。构建时会复制到 dist/config.json。
index.html	Vite 页面入口，只放置 <generator-workbench id="workbench"> 和 src/main.ts。不要在这里重写顶部栏、登录按钮或导出按钮。
package.json	生成项目依赖和脚本，默认包含 @atomm-developer/generator-sdk、@atomm-developer/generator-workbench、vue、vite、vue-tsc，并通过 pnpm.onlyBuiltDependencies 允许 esbuild 执行安装构建脚本。
tsconfig.json	TypeScript 严格模式配置，开启 resolveJsonModule、DOM 类型和 Vue 文件类型检查。
vite.config.ts	Vite 配置，默认启用 Vue 插件，设置 base: './'，并在构建结束后把根目录 config.json 复制到 dist/config.json，避免构建产物部署到子目录时资源和配置路径 404。
src/env.d.ts	Vue 单文件组件和 <generator-workbench> 标签的类型声明。
src/main.ts	平台接入入口：读取 config.json、初始化 GeneratorSDK、注册导出 provider、定义 Web Component、绑定 workbench.sdk/runtime/config，最后调用 workbench.mount()。
src/platform/config.ts	config.json 的读取和基础校验逻辑。缺少 appKey 时会直接抛错，便于尽早发现部署配置问题。
src/runtime/types.ts	生成器状态、runtime 事件、mount 参数、导出动作等类型定义。开发业务状态时应先更新这里。
src/runtime/state.ts	生成器业务状态的单一事实源，默认包含 meta、document、params。
src/runtime/panel-schema.ts	参数面板 PanelSchema 和 panelFilter 裁剪逻辑。workbench 和 embed 场景会通过它决定哪些参数可见、只读或隐藏。
src/runtime/export.ts	导出数据生成逻辑，供 Download 和 Open in Studio 复用。默认示例生成 SVG data URL。
src/runtime/index.ts	Runtime Contract 实现：mount、getState、setState、patchState、getPanelSchema、export、subscribe。同时会把 runtime 样式注入实际挂载根节点，避免 Shadow DOM 下样式丢失。
src/runtime/styles.css	默认画布、参数面板和响应式样式。可以按业务替换，但不要依赖页面级全局样式能穿透 workbench。
src/components/RuntimeView.vue	默认业务 UI：左侧/中间画布和参数面板示例。开发者通常从这里开始替换成真实生成器渲染。
README.md	生成项目的本地说明，包含启动、构建和主要开发入口。

生成配置项

config.json

脚手架默认生成：

{
  "appKey": "your_app_key",
  "env": "test",
  "title": "My Generator",
  "atommProDomain": "atomm",
  "atommProLocale": "en-US"
}

字段说明：

字段	说明
appKey	生成器在开发者控制台注册的唯一标识。开发阶段可用临时值，发布前必须替换为真实值。
env	SDK 环境。支持 dev、test、pre、prod、prod_cn。它会传给 GeneratorSDK.init()。
title	应用壳标题，也会作为默认生成器名称展示。
atommProDomain	atomm-pro 使用的业务域，默认 atomm。只有明确接入 Studio 域时才改为 studio。
atommProLocale	atomm-pro 弹窗语言，默认 en-US。中文可设置为 zh-CN。脚手架会通过 createAtommProHostI18nConfig() 注入默认多语言文案。

workbench.config

src/main.ts 中的默认配置是 workbench-basic 档位：

workbench.config = {
  ...createAtommProHostI18nConfig(config.atommProLocale ?? 'en-US'),
  title: config.title,
  mode: 'shell',
  logoText: 'Atomm',
  atommProEnv: config.env,
  atommProDomain: config.atommProDomain ?? 'atomm',
  exportEnabled: true,
  studioEnabled: true,
  templateEnabled: false,
  cloudEnabled: false,
  historyEnabled: false,
  autoSaveEnabled: false,
}

关键配置说明：

字段	默认值	说明
mode	shell	推荐模式。workbench 负责顶部栏和导出入口，runtime 自己控制业务布局。
exportEnabled	true	显示导出入口，点击后走 sdk.export.register() 注册的 provider。
studioEnabled	true	允许 Open in Studio，默认复用 src/runtime/export.ts 的导出 helper。
templateEnabled	false	默认不显示 Publish as Template，不接入模板协议，避免无需求时改造 runtime。
cloudEnabled	false	默认不启用云保存。需要草稿保存时再升级为 workbench-cloud。
historyEnabled	false	默认不显示历史记录。通常和 cloudEnabled 一起开启。
autoSaveEnabled	false	默认不自动保存。开启前需要提供可序列化 snapshot 和必要的保存策略。
atommProEnv	跟随 config.env	让自检面板和 atomm-pro 弹窗上下文与 SDK 环境一致。
atommProDomain	atomm	atomm-pro 登录、积分、邀请等平台弹窗使用的业务域。
atommProLocale / atommProMessages	由 createAtommProHostI18nConfig() 生成	保障 atomm-pro 弹窗文案正常显示，避免出现多语言 key。
onError	控制台输出	workbench 内部能力出错时回调，开发期用于定位接入问题。

atommProEnv 与 GeneratorSDK.init({ env }) 保持同一个来源。脚手架显式写入 config.env，便于 ?debug=true 自检面板直接检查环境一致性。

开发生成器业务

通常只需要改三处：

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

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

状态与参数面板

默认状态位于 src/runtime/state.ts：

export const generatorState = reactive<GeneratorState>({
  meta: {
    schemaVersion: '1.0.0',
    generatorId: 'my-generator',
    title: 'My Generator',
  },
  document: {
    width: 520,
    height: 360,
    unit: 'px',
  },
  params: {
    text: 'My Generator',
    accentColor: '#2563eb',
    scale: 1,
    shape: 'rounded',
  },
})

新增业务参数时，建议按这个顺序修改：

1. 在 src/runtime/types.ts 的 GeneratorState 中增加类型。
2. 在 src/runtime/state.ts 中增加默认值。
3. 在 src/runtime/panel-schema.ts 中增加可编辑字段，并用 bind.path 指向状态路径，例如 params.text。
4. 在 src/components/RuntimeView.vue 中使用参数渲染画布。

Runtime Contract

src/runtime/index.ts 是 workbench 调用 runtime 的入口。默认实现已包含：

方法	作用
mount(options)	把 RuntimeView.vue 挂载到 workbench 提供的容器中，支持 target、routeMode、panelFilter。
getState()	返回当前业务状态快照。
setState(nextState)	用完整状态替换当前状态，常用于宿主恢复草稿或模板。
patchState(patch)	按路径局部更新状态，并发出 state-change / params_change 事件。
getPanelSchema(options)	返回参数面板 schema，并按 panelFilter 裁剪。
export(action, options)	生成导出数据，供 SDK export provider 调用。
subscribe(listener)	让 workbench 监听 runtime 事件。

不要在 runtime 中重新实现顶部栏、登录入口、积分入口或导出浮层。这些属于 generator-workbench 的职责。

导出逻辑

src/main.ts 会注册：

sdk.export.register({
  getExportData: async (purpose, format) => {
    const result = await exportRuntime(
      purpose === 'studio' ? 'open-in-studio' : 'download-svg',
      { format },
    )
    return result ? { type: 'dataUrl', dataUrl: result.dataUrl } : null
  },
  getFileName: () => `${runtime.generatorId}-export.svg`,
})

如果真实生成器导出 PNG、SVG 或 Studio 文件，需要改 src/runtime/export.ts，保持 sdk.export.register() 这一层不变即可。不要把 export() 方法挂到 runtime 对象上，runtime 只保留 Runtime Contract 约定的方法。

样式策略

src/runtime/styles.css 会被两处使用：

• src/main.ts 正常引入，让页面级预览和开发体验有基础样式。
• src/runtime/index.ts 通过 styles.css?raw 在 mount() 时注入实际 runtime 挂载根节点。

第二点是为了兼容 workbench 可能把 runtime 挂进 Shadow DOM 或其他隔离根节点的场景。开发者替换样式时，应继续保留这条注入链路。

能力升级方式

脚手架默认不启用云保存、历史记录和模板发布。需要升级时按能力分层处理。

升级到 workbench-cloud

适用于需要云保存、历史记录、恢复草稿的生成器。需要做三件事：

1. 在 workbench.config 中设置 cloudEnabled: true、historyEnabled: true。
2. 提供 getCloudSaveOptions()，返回至少 { title, snapshot }。
3. 确认 snapshot 可以 JSON 序列化，不包含 DOM、函数、循环引用。

如果需要封面图，可继续补充 cover，或实现 getCloudCover()。

升级到 workbench-template

只有需要 Publish as Template、模板页嵌入、customize 流程、模板导入导出时才启用。需要做这些事：

1. 设置 templateEnabled: true。
2. 确认 runtime 的 getState()、setState()、getPanelSchema() 可表达模板默认参数。
3. 提供模板发布需要的媒体字段，例如 generatorImage、cover、generatorTag，优先通过 getTemplatePublishPayload() 聚合。
4. 验证 ?mode=embed 下 runtime 不显示不该出现在模板页里的业务 UI。

如果暂时没有模板业务，不要开启 templateEnabled，也不要引入 Template Definition Protocol 改造。

发布脚手架命令

脚手架命令随 @atomm-developer/generator-sdk-mcp 发布。当前仓库在 GitLab：

https://git.makeblock.com/makeblock-internet/generator-sdk

发布流程：

cd generator-workbench
pnpm install
pnpm build
npm publish

cd generator-sdk-mcp
pnpm install
pnpm build
npm publish

如果脚手架模板升级了 @atomm-developer/generator-workbench 依赖版本，必须先发布对应的 workbench 包，再发布 generator-sdk-mcp，否则开发者执行 pnpm install 时会因为找不到 workbench 版本而失败。

发布后，开发者使用：

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

如果只想从 GitLab 当前分支测试未发布版本，可以先在本仓库执行：

cd generator-sdk-mcp
pnpm build
node dist/index.js create-workbench-vue my-generator

相关文档

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