SDK 接入自检清单
接入 generator-sdk 后遇到问题，不知道从哪里查？
本文档按 SDK 的功能模块分类，列出每个模块接入时最常见的问题现象。每个问题都配有一段可以直接复制给 AI 的检查指令——你只需把项目路径填进去，发给 AI，它会自己检查并修复。
SDK 初始化
问题 1：SDK 没有任何反应，所有功能都不工作
把以下内容发给 AI：
请检查我的生成器项目中 SDK 初始化的问题。
SDK 接入后所有功能都没有反应。
项目路径：<你的项目路径>
请排查：
1. 检查是否调用了 GeneratorSDK.init({ appKey: '...' }) 来初始化 SDK
2. 检查 appKey 是否有值（不能为空字符串或 undefined）
3. 检查 SDK 初始化是否在其他功能调用之前执行（需要最先初始化）
4. 检查浏览器控制台是否有 "[GeneratorSDK] initialized" 的日志，若没有说明初始化未执行
对每一项：告诉我当前状态，如果有问题直接修复。问题 2：同一个页面初始化了多个 SDK 实例，功能表现不一致
把以下内容发给 AI：
请检查我的生成器项目中 SDK 实例重复初始化的问题。
不同地方的 SDK 功能（比如登录状态和积分余额）表现不一致，可能是多实例问题。
项目路径：<你的项目路径>
请排查：
1. 搜索项目中所有 GeneratorSDK.init 调用的位置
2. 检查是否在不同地方使用了不同的 appKey 或 env 参数——同一 appKey+env 组合才会复用单例
3. 如果存在多个不同参数的初始化，找出哪一个是正确的，统一所有地方使用同一份初始化配置
4. 确保初始化只在顶层执行一次，并把实例传递给需要它的地方
修复后告诉我在哪里做了修改。问题 3：接入后发现登录态在 dev/test 环境和 prod 环境行为不同
把以下内容发给 AI：
请检查我的生成器项目中 SDK 环境配置的问题。
dev/test 环境下登录态正常，但 prod 环境下不正常（或反过来）。
项目路径：<你的项目路径>
请排查：
1. 检查 GeneratorSDK.init 时 env 参数是什么——可选值有 prod、prod_cn、pre、test、dev
2. 检查当前运行环境和 env 参数是否匹配（比如本地开发是否使用了 prod，导致请求打到了线上服务）
3. 检查项目是否有根据运行环境动态切换 env 参数的逻辑
4. 如果没有，帮我根据环境变量（如 import.meta.env.MODE 或 process.env.NODE_ENV）动态设置 env 参数
修复后告诉我在哪里做了修改。Auth 模块（登录/用户）
问题 4：页面加载后登录状态不对，已登录用户显示为未登录
把以下内容发给 AI：
请检查我的生成器项目中 Auth 模块登录状态恢复的问题。
页面刷新后，已登录的用户显示为未登录状态。
项目路径：<你的项目路径>
请排查：
1. 检查 SDK 初始化后是否调用了 sdk.auth.ready() 等待登录态恢复
2. 检查渲染登录状态的逻辑是否在 ready() resolve 之后才执行
3. 如果没有等待 ready()，帮我在初始化流程中加入：await sdk.auth.ready() 后再渲染用户状态
修复后告诉我在哪里做了修改。问题 5：登录弹窗无法弹出，或弹出后关闭没有更新登录状态
把以下内容发给 AI：
请检查我的生成器项目中 Auth 模块登录弹窗的问题。
项目路径：<你的项目路径>
请排查：
1. 检查是否调用了 sdk.auth.login() 来触发登录弹窗
2. 检查登录成功后是否监听了 sdk.auth.onChange(callback) 来更新 UI 中的用户状态
3. 如果没有 onChange 监听，帮我加上：在用户登录/登出时自动刷新 UI 状态
4. 检查浏览器控制台是否有 @makeblock/passport-client 相关的报错
对每一项：告诉我当前状态，如果有问题直接修复。问题 6：需要在登录后执行某个操作，但不知道在哪里接
把以下内容发给 AI：
请检查我的生成器项目中 Auth 模块登录回调的接入方式。
我希望用户登录后自动执行某个操作（比如加载云保存数据），但不确定在哪里接。
项目路径：<你的项目路径>
请排查：
1. 找到项目中处理登录状态的地方
2. 检查是否使用了 sdk.auth.onChange(callback)——这是在登录/登出状态变化时触发回调的正确方式
3. 如果没有，帮我在合适的位置加上 onChange 监听，在用户登录时执行需要的操作
4. 注意：onChange 会在登录和登出时都触发，需要在回调中判断当前是登录还是登出状态
修复后告诉我在哪里做了修改。Cloud 模块（云保存）
问题 7：调用 sdk.cloud.save() 后控制台报错或保存失败
把以下内容发给 AI：
请检查我的生成器项目中 Cloud 模块保存功能的问题。
调用 sdk.cloud.save() 后报错或保存失败。
项目路径：<你的项目路径>
请排查：
1. 检查 save() 调用时传入的参数——snapshot 字段必须是可以 JSON.stringify 的纯数据对象，不能包含函数、DOM 元素、循环引用等
2. 检查 cover 字段——如果有传，必须是 base64 格式的图片 data URL，不能是 File 对象或 Blob
3. 检查用户是否已登录（Cloud 模块需要登录态），未登录时保存会失败
4. 检查浏览器控制台的具体错误信息，并告诉我是什么错误
对每一项：告诉我当前状态，如果有问题直接修复。问题 8：保存成功但封面图（cover）是空白的
把以下内容发给 AI：
请检查我的生成器项目中 Cloud 模块封面图的问题。
云保存成功，但保存记录的封面图是空白的。
项目路径：<你的项目路径>
请排查：
1. 找到调用 sdk.cloud.save() 的地方，检查 cover 字段是否有值
2. 如果 cover 为空，检查生成器中是否有从画布截图并生成 base64 图片的逻辑
3. 如果画布截图使用了 canvas.toDataURL()，检查画布是否有跨域资源（图片/字体）——跨域资源会导致 canvas 被污染，toDataURL 会抛错
4. 如果有跨域问题，检查跨域资源加载时是否设置了 crossOrigin="anonymous" 属性，且服务器是否返回了正确的 CORS 头
告诉我排查结果，如果有问题直接修复。问题 9：调用 sdk.cloud.restore(id) 后画布没有恢复数据
把以下内容发给 AI：
请检查我的生成器项目中 Cloud 模块恢复功能的问题。
调用 sdk.cloud.restore(id) 成功返回了数据，但画布没有更新。
项目路径：<你的项目路径>
请排查：
1. 找到调用 sdk.cloud.restore() 的地方，检查返回的数据结构——返回对象的 data.snapshot 字段是保存时传入的原始数据
2. 检查拿到 snapshot 后，是否有把数据应用到画布的逻辑（比如调用 setState、applyState 等方法）
3. 如果没有，帮我在 restore 成功后，把 snapshot 数据应用到画布状态
修复后告诉我在哪里做了修改。History 模块（历史记录）
问题 10：历史记录列表为空，但实际上有保存过数据
把以下内容发给 AI：
请检查我的生成器项目中 History 模块获取列表的问题。
调用 sdk.history.getList() 返回空数组，但实际上有保存过数据。
项目路径：<你的项目路径>
请排查：
1. 检查 SDK 初始化时的 appKey 是否和保存数据时使用的 appKey 一致——历史记录按 appKey 隔离
2. 检查用户是否已登录——历史记录是按用户维度存储的，未登录获取不到数据
3. 检查 sdk.history.getList() 是否在 sdk.auth.ready() 之后调用
4. 在浏览器网络面板中检查历史记录接口的实际请求和响应，告诉我接口返回了什么
告诉我排查结果，如果有问题直接修复。问题 11：历史记录列表显示的条数和实际条数不对
把以下内容发给 AI：
请检查我的生成器项目中 History 模块分页的问题。
历史记录列表显示的总数（total）和实际看到的条数不一致。
项目路径：<你的项目路径>
请排查：
1. 找到使用 sdk.history.getList() 返回值中 total 字段的地方
2. 注意：SDK 当前版本中，getList 返回的 total 值等于当前返回的数组长度，不是数据库中的真实总数
3. 如果 UI 用 total 来判断"是否还有更多数据"或"总页数"，这个逻辑会不准确
4. 帮我调整分页逻辑：改为通过"返回数量是否少于 pageSize"来判断是否还有更多数据
修复后告诉我在哪里做了修改。Credits 模块（积分）
问题 12：调用 sdk.credits.getBalance() 后余额显示不更新
把以下内容发给 AI：
请检查我的生成器项目中 Credits 模块余额显示的问题。
积分余额没有实时更新，或者消费后余额没有刷新。
项目路径：<你的项目路径>
请排查：
1. 检查是否使用了 sdk.credits.onChange(callback) 监听余额变化——消费积分后，SDK 会自动更新余额并通过 onChange 通知
2. 如果没有监听 onChange，帮我加上：在余额变化时自动刷新 UI 中的积分显示
3. 检查是否在需要显示最新余额的时机（比如页面初始化）调用了 sdk.credits.getBalance()
4. 如果有手动刷新余额的需求，可以调用 sdk.credits.getBalance() 重新拉取
修复后告诉我在哪里做了修改。问题 13：调用 sdk.credits.consume() 报权限错误
把以下内容发给 AI：
请检查我的生成器项目中 Credits 模块消费积分的问题。
调用 sdk.credits.consume() 时报权限错误或失败。
项目路径：<你的项目路径>
请排查：
1. 检查传入的 action 参数——Credits 的 consume 接口需要后端预先注册 action，不能随意传入字符串
2. 检查这个 action 是否已在平台控制台申请和注册
3. 如果不需要直接消费积分，检查是否应该改用 sdk.billing 模块（它统一管理免费次数和积分消费，更适合大多数场景）
4. 在浏览器网络面板中查看 consume 接口的具体错误响应，告诉我错误码是什么
告诉我排查结果和建议的修改方式。Billing 模块（统一计费）
问题 14：sdk.billing.check() 一直返回余额不足，但实际有余额
把以下内容发给 AI：
请检查我的生成器项目中 Billing 模块 check() 返回不正确的问题。
sdk.billing.check() 返回余额不足，但实际上用户有积分余额。
项目路径：<你的项目路径>
请排查：
1. 检查在调用 check() 之前是否先调用了 sdk.billing.getUsage()——check() 依赖已缓存的数据，首次必须先调用 getUsage() 获取数据
2. 检查 getUsage() 是否在用户登录后才调用（未登录时无法获取正确的计费状态）
3. 如果缺少 getUsage() 的调用，帮我在合适的位置（登录后/初始化时）加上 await sdk.billing.getUsage()
4. 确认修复后 check() 是否返回正确结果
修复后告诉我在哪里做了修改。问题 15：用 withBilling 包装后，用户有余额但功能无法执行
把以下内容发给 AI：
请检查我的生成器项目中 withBilling 包装函数的问题。
使用 withBilling(sdk.billing, action) 后，用户有余额但功能仍然无法执行或报错。
项目路径：<你的项目路径>
请排查：
1. 找到 withBilling 的调用方式，检查传入的参数是否正确：
第一个参数是 sdk.billing 实例，第二个参数是实际要执行的 async 函数
2. 检查在调用 withBilling 之前是否已经调用了 sdk.billing.getUsage()
3. 检查 withBilling 的 try/catch 处理——当余额不足时，它会抛出 SdkError(40301)，需要在 catch 中单独处理这个错误码，提示用户充值
4. 检查浏览器控制台的具体错误信息，告诉我是什么错误
对每一项：告诉我当前状态，如果有问题直接修复。问题 16：计费消费后，积分余额 UI 没有更新
把以下内容发给 AI：
请检查我的生成器项目中 Billing 消费后积分刷新的问题。
用户触发计费消费后，页面上的积分余额显示没有更新。
项目路径：<你的项目路径>
请排查：
1. 检查是否通过 sdk.credits.onChange(callback) 监听了积分余额变化
2. Billing 模块在 consume 成功后会自动调用 credits 刷新，并通过 credits.onChange 通知
3. 如果没有 credits.onChange 监听，帮我加上：在积分变化时自动更新 UI 中的余额显示
修复后告诉我在哪里做了修改。Export 模块（导出）
问题 17：点击导出/下载按钮没有反应
把以下内容发给 AI：
请检查我的生成器项目中 Export 模块导出功能的问题。
点击导出或下载按钮没有任何反应。
项目路径：<你的项目路径>
请排查：
1. 检查在调用 sdk.export.download() 之前是否调用了 sdk.export.register(provider) 注册导出提供者
2. 检查 register 传入的 provider 对象是否实现了 getExportData 或 getExportCanvas 方法（二选一）
3. 如果两个方法都没实现，帮我实现一个最简单的 getExportCanvas：从画布元素获取 HTMLCanvasElement 并返回
4. 检查浏览器控制台是否有相关报错
对每一项：告诉我当前状态，如果有问题直接修复。问题 18：导出 SVG 格式时报错
把以下内容发给 AI：
请检查我的生成器项目中 Export 模块 SVG 导出的问题。
当用户选择导出 SVG 格式时报错，PNG 格式正常。
项目路径：<你的项目路径>
请排查：
1. 检查 export provider 中是否实现了 getExportData 方法（SVG 导出必须用 getExportData，不能用 getExportCanvas）
2. 如果只实现了 getExportCanvas，SVG 从 canvas 转换会失败——需要实现 getExportData 并在 type 为 svg 时返回 { type: 'svg', svgString: '<svg>...</svg>' }
3. 如果生成器的渲染引擎支持输出 SVG 字符串，帮我实现 getExportData 方法来支持 SVG 导出
修复后告诉我在哪里做了修改。问题 19：导出功能没有计费控制，任何用户都可以免费导出
把以下内容发给 AI：
请检查我的生成器项目中 Export 模块计费控制的问题。
当前所有用户都可以无限制导出，没有积分/次数限制。
项目路径：<你的项目路径>
请排查：
1. 检查调用 sdk.export.download() 或 sdk.export.openInStudio() 之前是否有计费检查
2. Export 模块本身不包含计费逻辑，需要配合 withBilling 使用：
在执行导出前，先通过 withBilling(sdk.billing, async () => { sdk.export.download() }) 包装
3. 如果没有接入计费，帮我用 withBilling 包装导出操作，实现"有余额才能导出"的逻辑
修复后告诉我在哪里做了修改。Template 模块
问题 20：调用 sdk.template.applyToRuntime() 后画布状态没有变化
把以下内容发给 AI：
请检查我的生成器项目中 Template 模块应用模板的问题。
调用 sdk.template.applyToRuntime(templateData, runtime) 后画布没有更新。
项目路径：<你的项目路径>
请排查：
1. 检查传入 applyToRuntime 的 runtime 对象是否实现了 setState 方法
2. applyToRuntime 内部会调用 runtime.setState(snapshot)，如果 runtime 对象没有这个方法，模板无法应用
3. 检查 setState 的实现——它应该接收模板数据并更新画布状态
4. 如果 runtime 对象缺少 setState，帮我给 runtime 添加该方法的实现
修复后告诉我在哪里做了修改。问题 21：构建模板数据时，不知道 PanelSchema 里哪些字段应该放进模板
把以下内容发给 AI：
请帮助我确认生成器项目中 Template 模块应该包含哪些字段。
我不确定 PanelSchema 中哪些字段应该作为模板的可调整参数。
项目路径：<你的项目路径>
请排查：
1. 找到生成器中的 PanelSchema 定义（通常在 getPanelSchema() 或类似方法中）
2. 调用 sdk.template.getFieldOptions(panelSchema) 可以从 PanelSchema 中提取可选字段列表
3. 检查当前 template 数据构建逻辑中的 adjustableFields 和 panelFilter——这两个字段控制用户在 Customize 时可以调整哪些参数
4. 告诉我当前 PanelSchema 中有哪些字段，并帮我确认哪些应该是可调整的模板字段
输出建议的 adjustableFields 和 panelFilter 配置。综合检查
如果你不确定哪个模块有问题，可以让 AI 做一次全面扫描：
请对这个已接入 generator-sdk 的生成器项目做一次全面的 SDK 接入自检。
项目路径：<你的项目路径>
请按以下模块逐一检查，并输出状态表：
**初始化**
- GeneratorSDK.init 是否被调用，appKey 是否有值
- env 参数是否与运行环境匹配
- 是否在所有其他 SDK 调用之前初始化
**Auth 模块**
- sdk.auth.ready() 是否在页面初始化时等待
- 是否通过 sdk.auth.onChange 监听登录状态变化
**Cloud 模块**
- sdk.cloud.save() 的 snapshot 是否可序列化
- cover 封面图是否有实现
- sdk.cloud.restore() 返回的数据是否被应用到画布
**History 模块**
- 是否在登录后才调用 getList
- 是否依赖了 total 字段做分页（此字段值等于当前页数组长度）
**Credits 模块**
- 是否通过 sdk.credits.onChange 监听余额变化
**Billing 模块**
- 是否在 check() 之前调用了 getUsage()
- withBilling 是否正确处理了余额不足（SdkError 40301）的情况
**Export 模块**
- 是否调用了 sdk.export.register(provider) 注册导出提供者
- SVG 导出是否通过 getExportData 实现
- 导出是否接入了计费控制
**Template 模块**
- applyToRuntime 的 runtime 对象是否实现了 setState
输出格式：
| 模块 | 检查项 | 状态 | 备注 |
|------|--------|------|------|
状态：✅ 已实现 · ❌ 缺失 · ⚠️ 部分实现
对于所有 ❌ 和 ⚠️ 的项，逐一修复后重新输出状态表。