【Scratch×AI 系列 04】进阶与踩坑清单：从“能导入”到“能稳定跑”

摘要能导入不代表能跑control_stop、克隆常量、监视器与编码问题会让项目“看起来正常但行为异常”一份好用的 SB3 规范文件必须把“结构”与“坑位规则”写成可执行的清单我最常踩的 6 个坑cap 积木 next、shadow 输入、克隆myself、资源 md5ext、PowerShell JSON 深度、UTF-8 编码本文给你一份“发布前自检表”按表走导入成功率会直接上一个档次系列导航01先搞懂 SB3为什么 AI 生成的 project.json 常常“导不进 Scratch”02Target 与素材引用舞台/精灵为什么会消失03Blocks 结构与 inputs/fieldsAI 最容易写错的地方04进阶与踩坑清单本文05工程化实战先统一目录init再拆分流水线plan / exec-plan / build06流程使用上从想法到 planX.md验收标准怎么写才有用)07流程使用下从 planX 到可导入的 .sb3打包与自检规范参考Scratch3_SB3_配置文件规范.mdSKILL已上传到gitee仓库位置点我跳转1. 为什么“写规范文件”必须包含踩坑规则如果你只写字段表有哪些字段、类型是什么你会得到一个“看起来完整但不实用”的文档。真正折磨人的是这些现象项目能导入但某段脚本不执行变量监视器不显示或乱码克隆能创建但行为不对素材导入后空白尤其是 AI 生成的路径引用这些问题往往不是“字段缺失”而是字段之间的约束关系。所以我在规范里专门把“坑位规则”写成强约束条目并在自动化生成与打包时强制遵守。下面就是我最常踩的坑也是最值得写进规范/工具的坑。2. 坑 1control_stop 是 cap 积木后面不能接 nextcontrol_stop属于“终止类cap积木”它会终止脚本在 blocks 结构上它必须是链路末端因此必须满足next: null如果你把它接上 next可能导入不报错但运行时会出现“后面的积木永远执行不到”或者结构被 Scratch 自动修复导致脚本乱套这条规则在 exec-plan 的强制约束里也写了skills/xw-scratch-exec-plan/SKILL.md3. 坑 2inputs 的 shadow 规则写错最常见是“看起来能跑但输入不对”当一个输入槽需要放入 reporter同时又要保留默认数字输入框shadow典型写法是[3,reporterBlockId,[4,0]]如果你写成[2, reporterBlockId]逻辑可能还能跑但 Scratch 编辑器里会丢失默认 shadow导出再导入后可能出现不一致如果你写错 shadowState 或第三段结构轻则输入框显示异常重则 block 结构解析失败4. 坑 3克隆“自己”的常量必须是 “myself”控制类积木control_create_clone_of的下拉字段克隆自己时必须写_myself_AI 很爱写myself自己self这些都不行。结果通常表现为积木在编辑器里显示成空白选项克隆行为不生效或被 Scratch 自动改写5. 坑 4素材引用必须走 md5ext路径引用只适合“生成阶段”标准 SB3 的素材规则素材文件名是md5.ext且与project.json同级压缩包根目录所以打包出来的build/project.json必须满足costumes[].md5ext/sounds[].md5ext不出现assets/...所有 md5ext 指向的文件在 build 根目录真实存在这也是为什么我把流程分成exec-plan允许暂时用可读路径引用 assetsbuild扫描引用 → 复制素材 → 计算 MD5 → 回写 md5ext → 打包 sb3相关说明在skills/xw-scratch-build/SKILL.md6. 坑 5Windows 专属PowerShell 的 ConvertTo-Json 深度限制如果你用 PowerShell 读写 project.json迟早会遇到这个错误ConvertTo-Json : 序列化允许的最大深度为 100。原因是 PowerShell 5.1 的深度上限就是 100哪怕你写 -Depth 200 也可能报错。对 Scratch 的 project.json 来说经验上ConvertTo-Json -Depth 100足够但一定要显式写-Depth 100别用默认值我把这条也固化进了打包脚本skills/xw-scratch-build/build_plan.ps17. 坑 6中文字段与 UTF-8 编码变量名、监视器最容易乱码很多时候你以为是 Scratch 不支持中文其实是编码问题读取 JSON 时没有指定 UTF-8写回时带了 BOM 或编码被工具改写经验做法读取Get-Content -Raw -Encoding UTF8 ... | ConvertFrom-Json写入用 UTF8 无 BOM避免某些工具链兼容性问题这同样在 build 的脚本里做了兜底处理。8. 监视器monitors可选但很影响“作品完成度”monitors是顶层数组用来控制变量/列表的显示位置显示模式大字、正常、滑条图层顺序等它通常不会导致“导不进”但很容易导致UI 看起来乱导出再导入后监视器位置漂移建议策略开发早期可以为空数组一旦进入“交付/展示”阶段最好把核心变量监视器写进 monitors尤其是分数、生命、倒计时9. 发布前自检表强烈建议照着走9.1 容器与素材build 根目录存在project.jsonbuild 根目录所有素材文件名为md5.extproject.json中所有md5ext引用的文件在 build 根目录真实存在sb3 压缩包根目录直接包含project.json与素材文件不多嵌套一层目录9.2 targets至少 1 个舞台 targetisStage: truename: Stage所有 sprite target 都有name且不重复costumes强烈建议至少 1 个否则“能导入但白屏”的概率会增加9.3 blocks每个 block 都有opcode/next/parent/inputs/fields/shadow/topLeveltopLevel: true的 block 建议带x/ynext/parent引用的 blockId 都真实存在不悬挂9.4 坑位强约束control_stop的next必须为 null克隆“自己”的常量必须是_myself_inputs 需要保留默认 shadow 时使用三段式[3, reporter, shadow]结语把“坑位”写进规范AI 才能真正变成生产力写 SB3 规范文件的目的不是“写得像百科”而是让它可以被工具执行、被流程复用、被踩坑经验不断强化。到这里4 篇“规范文件编写”部分就完结了。接下来我会进入“skill 为什么这么设计、怎么落地成一条流水线”的两篇文章把经历沉淀成可复用的工具链才是 Scratch×AI 真正能跑起来的关键。