接入调试指南

平台为 generator 接入提供了两套互补的调试工具——它们共享同一份诊断逻辑与 AI 修复提示词字典，使用场景不同，但都不需要开发者打开 DevTools 或新增任何依赖：

工具	适用场景	入口
接入诊断工具（远程，独立 Web 应用）	没有源码、不在本机，对任意线上生成器做接入审计；交付验收；用户反馈排查	https://www.atomm.com/craftlab/generator/generator-debugger/
?debug=true 调试面板（页内，内置于 workbench）	自己开发、自己调试，需要在画布交互过程中实时观察事件流和发布参数	在生成器 URL 末尾加 ?debug=true

下文先介绍接入诊断工具（远程），再介绍**?debug=true 面板**（页内）。

---

接入诊断工具

接入诊断工具是一个独立部署的 Web 应用，无需对生成器项目做任何修改、无需打开 DevTools，只要在工具页输入生成器 URL 即可获得一份「接入完成度评分 + 逐项检查 + 一键 AI 修复提示词」的完整诊断报告。

使用方式

在线模式（默认）

1. 打开 https://www.atomm.com/craftlab/generator/generator-debugger/

2. 在输入框中粘贴目标生成器的 URL（支持完整 URL、localhost、自动补全 https://）

3. 点击「开始分析」或按回车

4. 左侧面板将依次显示：

   • 「⏳ 正在分析…」（约 1 秒）
   • 「🔍 HTML 分析完成 — 等待运行时验证…」（最多 15 秒）
   • 「✅ 分析完成 — N 项错误，M 项警告」最终结果

   右侧 iframe 会同步加载目标生成器（已自动追加 ?debug=true），如果生成器接入正确，目标页面右下角的内置调试面板也会同时显示。

本地模式 + Bookmarklet

1. 在工具页面顶部切换到「本地」单选项
2. 在左侧面板下方的本地说明卡片中，把 🔧 Atomm 诊断工具 链接拖拽到浏览器书签栏
3. 打开本地生成器页面，点击书签栏中的 Atomm 诊断工具
4. 浏览器自动新开标签返回诊断工具页面，运行时检查结果直接展示

快捷链接

工具支持 ?url= 参数自动触发分析：

https://www.atomm.com/craftlab/generator/generator-debugger/?url=https://my-generator.pages.dev

适合在飞书 / Slack 群里分享给同事，对方点击即可看到结果。

生成器内置调试面板

在你的生成器页面 URL 末尾加上 ?debug=true：

https://your-generator.pages.dev/?debug=true

页面挂载完成后约 1 秒，右下角会出现一个可拖拽的调试面板（#__gw_integration_checker__）。

何时使用

接入 generator-workbench 后发现某个功能不可用（头像点击无响应、Publish as Template 无弹窗、导出无效等），第一步就是加上这个参数，面板会直接告诉你哪里出了问题并给出修复建议。

仅用于调试

生产上线前，移除 URL 中的 ?debug=true 即可关闭面板。面板使用懒加载，正常访问时完全不加载、不执行、不影响性能。

---

面板结构

面板分为三个区块：

┌─────────────────────────────────────────────────┐
│ 🔧 Workbench Integration Check            [×]  │  ← 标题栏（可拖拽）
├─────────────────────────────────────────────────┤
│  2 项错误，5 项警告               ?debug=true   │  ← 摘要栏
├─────────────────────────────────────────────────┤
│  接入检查                                        │  ← ① 静态检查（含环境/语言/上报检查）
│  ✅ workbench.sdk 已绑定到元素                   │
│  ❌ atommProEnv 未配置                           │
│     → 修复：在 workbench.config 中设置 ...      │
│     📋 复制 AI 修复提示词                        │
│  ⚠️  SDK env 与 atommProEnv 不一致              │
│  ⚠️  atommProLocale 未配置（浏览器: zh-CN）      │
│  ⚠️  analytics.reporter 未配置                  │
├─────────────────────────────────────────────────┤
│  🔗 CDN 资产                                    │  ← ② CDN 检查（新）
│  ✅ generator-sdk: index.umd.js                 │
│  ✅ generator-workbench: index.umd.js           │
│  ⚠️  atomm-ui JS: 未检测到（懒加载）            │
│     📋 复制 AI 修复提示词                        │
├─────────────────────────────────────────────────┤
│  📤 发布参数                       14:23:07.334 │  ← ③ 发布参数
│  ✅ generatorImage  ✅ appKey  ❌ template       │
│                    📋 复制 AI 修复提示词         │
│  { "generatorTag": "...", "initialData": {...} } │
│                                       [copy]    │
├─────────────────────────────────────────────────┤
│  📊 数据上报                             (2)    │  ← ④ 数据上报（新）
│  ✅ analytics.reporter.reportExport 已配置       │
│  14:23:08  [reporter] reportExport  action:...   │
│  14:23:05  [gtag]     click_export  {...}        │
├─────────────────────────────────────────────────┤
│  📡 实时事件                             (3)    │  ← ⑤ 实时事件
│  14:23:07.334  ● params_change  cover: ...      │
│  14:22:59.100  ● state-change   keys: x,y       │
└─────────────────────────────────────────────────┘

---

① 接入检查

页面加载后立即执行，检查所有必要的接入配置是否就位。

图标	含义
✅	检查通过
❌	存在错误，阻断功能
⚠️	存在警告，功能降级但不崩溃
⏭️	跳过（前置条件未满足）

完整检查项清单：

检查项	对应故障
workbench.sdk 已绑定到元素	登录、导出、积分等 sdk 无效
workbench.runtime 已绑定到元素	runtime 功能全部失效
atommProEnv 已配置	发布模板、分享列表环境不正确
atommProDomain 已配置	发布模板、分享列表环境不正确
window.__GENERATOR_RUNTIME__ 已暴露	调试异常
runtime 接口合规（mount/getState/setState/getPanelSchema/subscribe）	多种功能异常
export 通过 sdk.export.register() 注册	导出按钮无效
SDK env 与 atommProEnv 一致	登录态错误、API 与弹窗环境不一致
atommProLocale 语言配置	弹窗语言与目标用户不符
analytics.reporter 已配置	导出/发布等行为无数据上报
getCloudSaveOptions 已实现（cloud profile）	云保存参数异常
templateEnabled: true（template profile）	Publish as Template 按钮不显示
params_change.cover（template profile）	Publish as Template 弹窗 mockup 图片不正确
template_publish_media_change（template profile）	Publish as Template 预览图缺失

每个 ❌ / ⚠️ 项下方会显示两个辅助操作：

• 黄色修复建议 — 简短代码片段，直接复制到对应位置即可
• 「📋 复制 AI 修复提示词」按钮 — 点击后将一段完整的修复上下文复制到剪贴板，粘贴给任何 AI 工具（Claude、Cursor、ChatGPT 等），让 AI 自动诊断并修复该项问题

---

② CDN 资产

面板在加载时自动扫描 document.scripts 和 document.querySelectorAll('link[rel="stylesheet"]')，检查所有官方 CDN 资产是否已被加载。

检查的资产列表：

资产	官方 CDN 地址
generator-sdk (ES)	.../generator-sdk/index.es.js
generator-sdk (UMD)	.../generator-sdk/index.umd.js
generator-workbench	.../generator-sdk/generator-workbench/index.umd.js
atomm-ui JS	.../atomm-ui/dist-browser/atomm-ui.js
atomm-ui CSS	.../atomm-ui/dist-browser/atomm-ui.min.css
atomm-pro JS	.../atomm-pro/dist-browser/atomm-pro.js
atomm-pro CSS	.../atomm-pro/dist-browser/atomm-pro.css

懒加载说明

atomm-ui 和 atomm-pro 是由 workbench 按需懒加载的：

• atomm-ui 在 workbench 初始化时加载
• atomm-pro 在用户点击 "Publish as Template" 时才加载

面板首次显示时若这两项显示 ⚠️ 属于正常情况，触发对应操作后会自动变为 ✅。

若 workbench.config 中通过 atommUiScriptUrl、atommProScriptUrl 等字段使用了自定义 CDN 地址，面板同样会检测自定义地址，并在标签后标注 (自定义)。

每个 ⚠️ 项都有「📋 复制 AI 修复提示词」按钮，点击后可获得针对该 CDN 问题的完整修复提示词。

---

③ 发布参数

触发时机： 每次点击 "Publish as Template" 按钮，面板自动抓取 workbench 实际传给 atomm-pro 的完整参数并展示。

速览字段：

字段	图标含义
generatorImage	✅ 有预览图 / ❌ 为空（发布预览将空白）
generatorTag	✅ 有模板名 / ❌ 为空（模板无名称）
appKey	✅ 已读取 / ❌ 为空
template	✅ 模板数据存在 / ❌ 缺失（模板保存失败）
template.generatorId	✅ generatorId 存在 / ❌ 缺失

JSON 展示： 面板以格式化 JSON 展示完整参数，base64 图片数据自动截断为 [data-URI, 12453 chars] 以防内容过长。

Copy 按钮： 点击右上角 copy 按钮，将复制含完整 base64 数据的原始参数到剪贴板，方便对比或排查。

「📋 复制 AI 修复提示词」按钮： 当某个字段显示为 ❌（如 generatorImage、generatorTag、appKey、template 等）时，该字段旁边会出现「📋 复制 AI 修复提示词」按钮，点击后复制针对该缺失字段的完整 AI 修复上下文，粘贴给 AI 工具可自动获得修复方案。

---

④ 数据上报

这是专用于数据埋点监控的独立面板区块。它会实时拦截并记录以下来源的上报事件：

来源	标签	说明
analytics.reporter	[reporter]	workbench.config.analytics.reporter 配置的自定义上报器
window.gtag	[gtag]	Google Analytics 4 事件
window.sensors	[sa]	神策分析（Sensor Analytics）事件

面板首行状态说明：

• ✅ analytics.reporter.reportExport 已配置 — 上报器正常，事件会被记录
• ⚠️ analytics.reporter 未配置 — 未配置时导出/发布操作无数据上报

每条事件记录格式：

14:23:08  [reporter]  reportExport  {"action":"download"}

触发上报事件的操作：

• 点击 Export → 触发 reportExport
• 点击 Publish as Template → 触发 reportPublishTemplateClick（如已实现）
• 其他配置的 gtag/sa 事件

未配置 analytics.reporter

如果不需要数据上报，⚠️ 提示可忽略。若需要接入，点击「📋 复制 AI 修复提示词」获取完整配置代码。

---

⑤ 实时事件

面板订阅 runtime.subscribe()，实时展示 runtime 发出的关键事件。事件日志最新的在最上方，最多保留 30 条。

颜色	含义
绿色 ●	事件正常（如 params_change 携带了 cover 字段）
红色 ●	事件异常（如 params_change 的 cover 字段为空）

监控的关键事件：

事件	显示内容
params_change	cover 字段长度或"cover 字段为空或缺失"
template_publish_media_change	generatorImage 是否已提供
select_template	选中的模板名称
state-change	变化的字段名（最多展示 3 个）
ready	runtime 已就绪

接入检查同步更新： 当 params_change 携带 cover 字段时，"接入检查"区中该项会从 ⚠️ 自动变为 ✅，无需手动刷新页面。

---

一键复制 AI 修复提示词

这是调试面板为 AI vibe coding 场景提供的核心辅助功能。每当出现 ❌ / ⚠️ 检查项或发布参数字段缺失时，面板都会在对应位置渲染一个「📋 复制 AI 修复提示词」按钮。

使用流程

1. 打开 ?debug=true 面板，找到任意 ❌ 或 ⚠️ 项
2. 点击该项旁边的「📋 复制 AI 修复提示词」按钮
3. 切换到 AI 对话窗口（Claude、Cursor Chat、ChatGPT 等）
4. 粘贴提示词并发送
5. AI 会分析错误原因并给出可直接使用的修复代码

支持的检查项

以下错误/警告项均支持一键复制 AI 修复提示词：

接入检查类（14 项）：

检查项	触发条件
workbench.sdk 未绑定	workbench.sdk 赋值遗漏或时序错误
workbench.runtime 未绑定	workbench.runtime 赋值遗漏或时序错误
atommProEnv 未配置	config.atommProEnv 字段缺失
atommProDomain 未配置	config.atommProDomain 字段缺失
__GENERATOR_RUNTIME__ 未暴露	runtime 未挂载到 window
runtime 接口不合规	mount / getState / setState / getPanelSchema / subscribe 缺失
export 未注册	sdk.export.register() 未调用
SDK env 与 atommProEnv 不一致	GeneratorSDK.init({ env }) 与 config.atommProEnv 值不匹配
atommProLocale 未配置	config.atommProLocale 未设置
analytics.reporter 未配置	config.analytics.reporter 未实现
getCloudSaveOptions 未实现	云保存配置缺失
templateEnabled 未开启	config.templateEnabled 为 false 或未设置
params_change.cover 缺失	runtime 未在 params_change 事件中携带 cover 字段
template_publish_media_change 缺失	runtime 未发出该事件

CDN 资产类（6 项）：

检查项	触发条件
atomm-ui JS 未检测到	首次操作前属正常（懒加载），操作后仍未检测到则需排查
atomm-ui CSS 未检测到	同上
atomm-pro JS 未检测到	点击 Publish as Template 前属正常（懒加载）
atomm-pro CSS 未检测到	同上
generator-sdk 未检测到	CDN 未加载或使用 npm 包（正常）
generator-workbench 未检测到	CDN 未加载或使用 npm 包（正常）

发布参数字段类（5 项）：

字段	触发条件
generatorImage	发布预览图为空
generatorTag	模板名称为空
appKey	appKey 未正确读取
template	模板数据缺失
template.generatorId	generatorId 缺失

查看全部修复提示词原文

如需离线查阅所有修复提示词的完整内容，参见：接入自检清单 → 调试面板错误快速修复

---

拖拽面板

面板固定在右下角，如果遮挡到操作区域，可以直接拖拽标题栏将其移动到任意位置。拖拽时：

• 鼠标悬停在标题栏时光标变为 grab
• 拖拽中光标变为 grabbing
• 面板边界限制在视口内，不会拖出屏幕
• 面板刷新（事件触发重渲）后位置保留

关闭面板

移除 URL 中的 ?debug=true 即可：

https://your-generator.pages.dev/  ✅ 正常访问，面板不加载

面板代码通过动态 import() 懒加载，正常访问时不下载、不执行、不影响性能和功能。

---

相关文档

• Workbench 与 Runtime 通信 — 事件协议完整参考
• Generator Workbench — 接入配置总览
• Runtime Contract — runtime 接口规范