Workbench Integration Checklist

Integrated generator-workbench but something is not working and you don't know where to start?

This page organizes the most common problems by feature. Each problem comes with a ready-to-use prompt — copy it, fill in your project path, and send it to AI. The AI will inspect your code and fix what is missing.

Feature 1: Publish as Template

Problem 1: Clicking "Publish as Template" does nothing

Send the following to AI:

Please inspect my generator project and find out why clicking the "Publish as Template" button has no effect.

Project path: <your project path>

Check in this order:
1. Check whether publishAsTemplate is disabled in the generator-workbench config (enablePublishAsTemplate is false or missing)
2. Check whether getPublishAsTemplateOptions is missing from workbench.config
3. Check whether the atomm-pro modal component is imported and registered correctly
4. Open the browser console and check whether clicking the button throws any JS errors

For each item: report the current status, and if there is a problem, fix it directly.

Send the following to AI:

Please inspect my generator project for a blank template preview image in the Publish as Template modal.
The modal opens normally but the preview image is blank or black.

Project path: <your project path>

Check the following:
1. Find the getPublishAsTemplateOptions implementation and check whether the generatorImage field has a value
2. If generatorImage is empty or undefined, locate the canvas or preview DOM element in the generator (usually a canvas tag or a container with a specific aria-label)
3. Check whether there is any logic that takes a screenshot of this element and converts it to a base64 PNG
4. If not, implement it: capture the canvas element as a screenshot, convert to base64 PNG, and pass it as generatorImage when Publish as Template is triggered

Tell me where you made changes after fixing.

Problem 3: The published template has no name, or the name is wrong

Send the following to AI:

Please inspect my generator project for a template name issue in Publish as Template.

Project path: <your project path>

Check the following:
1. Check whether workbench.config.title has a value — this field is used as the default template name
2. Check whether initialData.generatorInfo.generatorName has a value in getPublishAsTemplateOptions
3. If title is empty or unset, set a reasonable default name in the workbench initialization config

Tell me where you made changes after fixing.

Applies when: the generator has a left-side template presets panel, the user selects a preset, but the generatorTag field in the modal is empty.

Send the following to AI:

Please inspect my generator project for a missing generatorTag in the Publish as Template modal.
The generator has template presets, but the modal does not show the name of the currently selected preset.

Project path: <your project path>

Check the following:
1. Find the logic that switches template presets in the generator (usually a click handler on the left template list)
2. Check whether it dispatches a runtime select_template event with { name: '<template name>' }
3. If not, add runtime.notify('select_template', { name: template.name }) to the template switching logic
4. Confirm that generator-workbench picks up this name and passes it as generatorTag in the publish payload

Tell me where you made changes after fixing.

Problem 5: After Customize, the canvas state does not match what was published

The template was published and then opened with Customize, but the canvas looks different from what was published, or unexpected UI state appears.

Send the following to AI:

Please inspect my generator project for a template data mismatch in Publish as Template.
After publishing a template and using Customize to re-open it, the canvas state does not match what was published.

Project path: <your project path>

Check the following:
1. Find the logic that builds the template field inside getPublishAsTemplateOptions
2. Check whether the template data contains any UI state (for example: whether a panel is open, the active tab, scroll position, sidebar visibility)
3. Template data must only contain design parameters (params) and metadata (meta), not UI display state
4. If UI state is mixed in, refactor the template data builder to include only design-related fields

Tell me which fields were removed after fixing.

Feature 2: Cloud Save

Problem 6: Cloud save records have no thumbnail

Send the following to AI:

Please inspect my generator project for a missing cloud save cover image.
Saved cloud records in the history list have no thumbnail (cover is blank).

Project path: <your project path>

Check the following:
1. Check whether workbench.config has a getCloudSaveOptions method
2. If it does, check whether the returned cover field has a value (must be a base64 data URL)
3. If cover is empty, check whether there is logic that listens to runtime state-change events and captures a canvas screenshot on each state change
4. If not, implement it:
   - On runtime state-change, capture the current canvas state as a 400x225 base64 PNG
   - Cache the result
   - Return the cached value from getCloudSaveOptions

Tell me where you made changes after fixing.

Problem 7: Editing the canvas does not trigger auto-save

Send the following to AI:

Please inspect my generator project for a missing auto-save trigger.
After the user edits the canvas, auto-save is not triggered.

Project path: <your project path>

Check the following:
1. Check whether autoSave or enableAutoSave is enabled in workbench.config
2. Check whether the generator runtime dispatches a state-change event when canvas state changes (runtime.notify('state-change', ...))
3. If state-change is not being dispatched, locate where canvas state is updated and confirm that runtime.notify is called there
4. For each item: report the current status and fix if there is a problem

Feature 3: Template Page Adaptation (Embed Mode)

Problem 8: The template presets panel is visible on the template page

After publishing, the generator is embedded on the template page, but the left-side template presets list is still visible.

Send the following to AI:

Please inspect my generator project for an embed mode adaptation issue.
When the generator is embedded via ?mode=embed on the template page, the left template presets sidebar is still visible.

Project path: <your project path>

Check the following:
1. Check whether there is logic in the generator that detects embed mode (via URL parameter ?mode=embed or the workbench embed-mode-start command)
2. Check whether the template presets list has a conditional render in embed mode (for example: v-if="!isEmbedMode" or display: none)
3. If not, implement it:
   - Detect embed mode (read mode=embed from the URL)
   - Hide the template presets sidebar when embed mode is active

Tell me where you made changes after fixing.

Problem 9: The template page is broken on mobile — more than just the canvas is visible

Send the following to AI:

Please inspect my generator project for a mobile adaptation issue on the template page.
On a mobile device, the template page shows more than just the canvas — the toolbar, parameter panel, and other elements are also visible.

Project path: <your project path>

Check the following:
1. Check whether the generator has embed mode detection logic
2. Check whether there is logic to hide the parameter panel, toolbar, and other secondary UI on mobile viewports (≤768px) in embed mode
3. If not, implement it:
   - Detect embed mode
   - Add mobile responsive adaptation: hide the parameter panel and toolbar, make the canvas fill the screen
   - CSS media query or runtime detection both work

Tell me where you made changes after fixing.

Problem 10: The template page shows the default canvas state instead of the template content

The template page should show the state from when it was published, but it shows the generator's default initial state instead.

Send the following to AI:

Please inspect my generator project for a template data loading issue in embed mode.
After opening the template page, the canvas shows the generator default state, not the published template content.

Project path: <your project path>

Check the following:
1. Check whether generator-workbench forwards template data to the runtime in embed mode (via dispatchWorkbenchCommand with template data)
2. Check whether the runtime's dispatchWorkbenchCommand implements logic to receive template data and apply it to the canvas
3. If dispatchWorkbenchCommand is not implemented or does not handle template commands, implement it:
   - Listen for the workbench command that contains template data
   - Apply the template data (defaults.params and defaults.meta) to the canvas

Tell me where you made changes after fixing.

Feature 4: Customize Flow

Problem 11: After clicking Customize, the canvas shows the default state

The user clicks Customize on the template page and is redirected to the generator with a templateId in the URL, but the canvas shows the default initial state instead of the template content.

Send the following to AI:

Please inspect my generator project for a Customize flow issue.
The user arrives from the template page with a templateId in the URL, but the canvas shows the default state instead of the template content.

Project path: <your project path>

Check the following:
1. Check whether the generator initialization code reads the URL parameter templateId
2. If it does, check whether it calls sdk.template.get(templateId) to fetch the template data
3. If data is fetched, check whether defaults.params and defaults.meta are applied to the canvas
4. If any step is missing, implement the complete template restore flow in the correct order:
   read templateId → fetch template data → apply to canvas

Tell me where you made changes after fixing.

Problem 12: After Customize and re-publishing, the template data is different from expected

The user Customizes the template, makes edits, and publishes again — but the published data does not match what was expected.

Send the following to AI:

Please inspect my generator project for a re-publish issue after Customize.
After the user Customizes a template and makes changes, publishing again produces incorrect template data.

Project path: <your project path>

Check the following:
1. Check whether the template field in getPublishAsTemplateOptions is built from the current runtime state in real time, rather than from stale data cached at Customize time
2. Check whether the runtime state is correctly updated after template restore (getState() returns the latest state after Customize)
3. For each item: report the current status and fix if there is a problem

Full Scan

If you are not sure which feature is causing the problem, ask AI to run a full scan:

Please run a full integration audit on this generator project that uses generator-workbench.

Project path: <your project path>

Check each of the four feature areas below and output a status table:

**Publish as Template**
- Can the Publish as Template button be triggered
- generatorImage (canvas screenshot) is implemented
- generatorTag (template name label) is forwarded via select_template event
- workbench.config.title is set
- template data excludes UI state

**Cloud Save**
- getCloudSaveOptions cover image is implemented
- state-change event correctly triggers auto-save

**Embed Mode Adaptation**
- Embed mode detection is implemented
- Template presets sidebar is hidden in embed mode
- Mobile adaptation is applied in embed mode

**Customize Flow**
- templateId URL parameter is read on init
- sdk.template.get is called to fetch template data
- Template data is applied to canvas

Output format:
| Feature | Check Item | Status | Notes |
|---------|------------|--------|-------|

Status key: ✅ implemented · ❌ missing · ⚠️ partial

For every ❌ and ⚠️ item, fix it and then output the status table again.

Feature 5: Project Config (config.json and appKey)

Problem 13: After uploading to CMS, the code is not recognized or not backfilled

After uploading the generator to CMS, the platform cannot identify or backfill the generator code (which is the appKey). The most common cause is that appKey is scattered as hardcoded strings across multiple files instead of being read from a single config.json at the project root.

Send the following to AI:

Please inspect my generator project for appKey configuration issues and verify it follows the config.json standard.
After uploading to CMS, the code is not recognized or cannot be backfilled.

Project path: <your project path>

Check the following:
1. Check whether a config.json file exists at the project root and contains an appKey field, for example:
   {
     "appKey": "your-generator-key"
   }
2. Search the project for all places where an appKey string value appears (not a variable reference) — check whether any appKey is hardcoded directly in business modules, JS files, or HTML files instead of being read from config.json
3. Check the GeneratorSDK.init() call — confirm that the appKey value comes from config.json and is not a hardcoded string
4. Check workbench.config, getPublishAsTemplateOptions, and other workbench configuration that uses appKey — confirm they all read the value from config.json

If any of the following problems are found, fix them:
- No config.json at the project root — create one and put appKey in it
- config.json exists but is missing the appKey field — add it
- Business code contains hardcoded appKey strings — change them to read from config.json
- SDK initialization appKey is not coming from config.json — update the read path

Tell me which files were changed and what the final config.json contains.

Feature 6: Environment Configuration

After publishing the generator, API requests go to the test server instead of production, or the atomm-pro modal shows unexpected behavior such as an invite entry appearing in the CN version.

Send the following to AI:

Please inspect my generator project's environment configuration and confirm the SDK env and workbench environment are correct.

Project path: <your project path>

Environment configuration reference:
- Generator Workbench has two environment layers:
  1. SDK layer: GeneratorSDK.init({ env }) — controls the base URL for all platform APIs and the Passport login region
  2. Shell layer: workbench.config.atommProEnv — controls workbench shell behavior, community template routing, and atomm-pro modal context
- Correct approach: set env only in the SDK; after workbench.sdk = sdk is executed, the shell automatically derives atommProEnv from sdk.getEnv() — no need to set it again
- Supported env values:
  · prod: production (US), API: https://api.xtool.com
  · prod_cn: production (China), API: https://api.makeblock.com
  · pre: pre-release environment
  · test: test environment
  · dev: development environment

- prod_cn special behaviors (applied automatically, no manual config needed):
  · Invite / Earn Credits entry is hidden
  · Publish as Template entry is hidden
  · When no ?lang= URL parameter is present, default language is zh instead of en

Check the following:
1. Find the GeneratorSDK.init() call and check what the current env parameter value is
2. Check whether env switches dynamically based on the actual runtime environment (for example: dev/test locally, prod or prod_cn in production)
3. Check whether workbench.config has a manually set atommProEnv — if it does and it conflicts with the SDK env, workbench will log a warning and use the SDK env; the recommended fix is to remove the manual setting and rely on automatic sync
4. If the generator needs to support both international and CN regions, check whether env correctly distinguishes prod (US) from prod_cn (China)

If problems are found, fix them:
- If env is hardcoded, change it to read dynamically from an environment variable
- If atommProEnv is manually set and matches the SDK env, remove the redundant setting; if it conflicts, determine which is correct and unify

Tell me where you made changes and what the final env configuration logic looks like.

Feature 7: Language and i18n Configuration

Problem 15: The workbench top bar is in English but the generator should display another language

The workbench top bar buttons and modal text always show in English and do not switch based on the user's language, or the language selection in the workbench and inside the runtime are out of sync.

Send the following to AI:

Please inspect my generator project's workbench language configuration and confirm whether the language detection and display are correct.

Project path: <your project path>

Language configuration reference:
- The workbench shell reads the language from the ?lang= URL parameter, for example ?lang=zh or ?lang=en
- When no ?lang= parameter is present, the default language is English (en)
- Exception: when SDK env is prod_cn and no ?lang= parameter is present, the default language is zh instead of en
- Language can be manually set via workbench.config.atommProLocale, which overrides the automatic URL detection
- Supported language codes:
  zh, en, zh-hant, de, es, fr, it, ja, ko, ru, uk, th, cs, vi, id, sl, pl

Check the following:
1. Check whether the generator URL passes the language via a ?lang= parameter, or whether it uses another mechanism such as localStorage or a route parameter
2. Check whether workbench.config has an atommProLocale field and what its value is
3. If the runtime has its own i18n system (for example Vue i18n), check whether it reads the language from the same source as the workbench — both should prefer the ?lang= URL parameter to avoid the workbench showing Chinese while the runtime shows English (or vice versa)
4. If the generator needs to support prod_cn (China production), check whether the runtime's language logic also implements the following: when env is prod_cn and no ?lang= URL parameter is present, fall back to zh

If problems are found, fix them:
- If the workbench language and the runtime language are out of sync, unify both to read from the same source
- If the prod_cn language fallback is missing, add that logic
- If a fixed language is needed regardless of URL, set atommProLocale in workbench.config

Tell me where you made changes and what the final language detection logic looks like.

Full Scan

If you are not sure which feature is causing the problem, ask AI to run a full scan:

Please run a full integration audit on this generator project that uses generator-workbench.

Project path: <your project path>

Check each of the seven feature areas below and output a status table:

**Publish as Template**
- Can the Publish as Template button be triggered
- generatorImage (canvas screenshot) is implemented
- generatorTag (template name label) is forwarded via select_template event
- workbench.config.title is set
- template data excludes UI state

**Cloud Save**
- getCloudSaveOptions cover image is implemented
- state-change event correctly triggers auto-save

**Embed Mode Adaptation**
- Embed mode detection is implemented
- Template presets sidebar is hidden in embed mode
- Mobile adaptation is applied in embed mode

**Customize Flow**
- templateId URL parameter is read on init
- sdk.template.get is called to fetch template data
- Template data is applied to canvas

**Project Config (config.json and appKey)**
- config.json exists at the project root and contains the appKey field
- All uses of appKey in the project read from config.json — no hardcoded strings

**Environment Configuration**
- SDK env parameter matches the actual runtime environment
- workbench derives atommProEnv automatically from SDK; no conflicting manual atommProEnv setting

**Language and i18n**
- workbench language source is correct (?lang= URL parameter takes priority)
- Runtime language is in sync with workbench
- prod_cn environment has a Chinese language fallback

Output format:
| Feature | Check Item | Status | Notes |
|---------|------------|--------|-------|

Status key: ✅ implemented · ❌ missing · ⚠️ partial

For every ❌ and ⚠️ item, fix it and then output the status table again.

Generator Workbench — shell overview, configuration, and mount options
Workbench Runtime Communication — select_template, state-change, dispatchWorkbenchCommand reference
Runtime Contract — full runtime interface reference
Debugging Guide — how to inspect workbench events and payloads in the browser

Workbench Integration Checklist ​

Feature 1: Publish as Template ​

Problem 1: Clicking "Publish as Template" does nothing ​

Problem 2: The publish modal opens, but the template preview image is blank or black ​

Problem 3: The published template has no name, or the name is wrong ​

Problem 4: The "current template" field in the publish modal is empty ​

Problem 5: After Customize, the canvas state does not match what was published ​

Feature 2: Cloud Save ​

Problem 6: Cloud save records have no thumbnail ​

Problem 7: Editing the canvas does not trigger auto-save ​

Feature 3: Template Page Adaptation (Embed Mode) ​

Problem 8: The template presets panel is visible on the template page ​

Problem 9: The template page is broken on mobile — more than just the canvas is visible ​

Problem 10: The template page shows the default canvas state instead of the template content ​

Feature 4: Customize Flow ​

Problem 11: After clicking Customize, the canvas shows the default state ​

Problem 12: After Customize and re-publishing, the template data is different from expected ​

Full Scan ​

Feature 5: Project Config (config.json and appKey) ​

Problem 13: After uploading to CMS, the code is not recognized or not backfilled ​

Feature 6: Environment Configuration ​

Problem 14: After publishing, API requests hit the wrong environment, or the atomm-pro modal behaves unexpectedly ​

Feature 7: Language and i18n Configuration ​

Problem 15: The workbench top bar is in English but the generator should display another language ​

Full Scan ​

Related Pages ​

Workbench Integration Checklist

Feature 1: Publish as Template

Problem 1: Clicking "Publish as Template" does nothing

Problem 2: The publish modal opens, but the template preview image is blank or black

Problem 3: The published template has no name, or the name is wrong

Problem 4: The "current template" field in the publish modal is empty

Problem 5: After Customize, the canvas state does not match what was published

Feature 2: Cloud Save

Problem 6: Cloud save records have no thumbnail

Problem 7: Editing the canvas does not trigger auto-save

Feature 3: Template Page Adaptation (Embed Mode)

Problem 8: The template presets panel is visible on the template page

Problem 9: The template page is broken on mobile — more than just the canvas is visible

Problem 10: The template page shows the default canvas state instead of the template content

Feature 4: Customize Flow

Problem 11: After clicking Customize, the canvas shows the default state

Problem 12: After Customize and re-publishing, the template data is different from expected

Full Scan

Feature 5: Project Config (config.json and appKey)

Problem 13: After uploading to CMS, the code is not recognized or not backfilled

Feature 6: Environment Configuration

Problem 14: After publishing, API requests hit the wrong environment, or the atomm-pro modal behaves unexpectedly

Feature 7: Language and i18n Configuration

Problem 15: The workbench top bar is in English but the generator should display another language

Full Scan

Related Pages