【Scratch×AI 系列 05】工程化实战：先统一目录（init），再拆分流水线（plan / exec-plan / build）

摘要Scratch 项目最容易“做着做着就乱”素材散落、版本混杂、产物找不到AI 更是无从下手xw-scratch-init 不是“创建文件夹”而是把协作与自动化的前提一次性铺好把流程拆成 plan → exec-plan → build是为了把 AI 从“胡写 JSON”变成“稳定流水线”只要把“验收标准”写对AI 就能被约束在正确的轨道上系列导航01先搞懂 SB3为什么 AI 生成的 project.json 常常“导不进 Scratch”02Target 与素材引用舞台/精灵为什么会消失03Blocks 结构与 inputs/fieldsAI 最容易写错的地方04进阶与踩坑清单05工程化实战先统一目录init再拆分流水线plan / exec-plan / build06流程使用上从想法到 planX.md验收标准怎么写才有用)07流程使用下从 planX 到可导入的 .sb3打包与自检SKILL已上传到gitee仓库位置点我跳转1. 背景Scratch×AI 的第一道坎不是积木是“工程混乱”一开始做 Scratch 游戏很轻松拉几个积木、拖几张图就能跑。但当你把 AI 引入流程你会发现真正的阻力常常不是“不会做”而是“没法协同、没法复现、没法迭代”。典型问题包括素材到处都是微信发来的图、下载的音效、临时截图……放哪叫什么哪个版本需求靠聊天记录改了一个规则没人知道影响哪些脚本导出的 .sb3 放得到处都是哪个是能交付的版本哪个是中途试验品最要命的是AI 需要“确定的路径和约定”否则它只能凭空猜测所以在 Scratch×AI 的工作流里第一件事往往不是“让 AI 写 project.json”而是先让工程变成“可被工具理解的工程”。2. 我对 Scratch×AI 工程的最低要求为了让后续自动化稳定我给自己定了 4 条硬要求素材必须集中管理并且路径稳定需求必须能落成文档并且可拆成可验收的计划每一步的产物必须可追踪从 plan 到 project.json 到 sb3任何脚本/工具重复执行都不能破坏已有内容幂等这 4 条要求本质上指向一个答案先统一目录结构再谈自动化。3. xw-scratch-init流水线的地基目录规范就是生产力xw-scratch-init 的职责很单一初始化一套标准化 Scratch 游戏工作区结构并且保证幂等已存在不覆盖只补齐缺失项。目录结构示例assets资源目录 backdrops舞台背景图片文件夹 sprite精灵图片文件夹 sprite1精灵1图片文件夹 sounds音频文件存放文件夹 scripts需求文件夹 goal需求目标文件夹 总体需求.md游戏整体创意说明文档占位填充 plan需求分析计划文件夹将来会存放需求拆解 md 文件3.1 为什么要把 assets 和 scripts 分开这是为了把“可读可维护”和“可执行可追溯”分层assets纯素材面向“人类维护”和“版本控制”scripts纯文档与产物面向“流程执行”和“自动化生成”直接收益plan 文档可以用稳定路径引用素材例如assets/sprite/sprite1/plane.svgexec-plan 阶段可以扫描这些路径生成 project.jsonbuild 阶段可以根据 project.json 的引用把真正用到的素材打进 sb33.2 为什么幂等很重要因为你会反复跑今天加了一个新精灵明天又开了一个新项目需求变了让 AI 重新生成计划/执行计划如果 init 每次都覆盖内容你会丢素材、丢需求文档、丢执行产物。所以原则是只补齐缺失项不碰已有内容。4. 为什么“让 AI 直接生成 SB3”会翻车最开始很容易想走捷径让 AI 直接输出.sb3或者至少输出“能导入的 project.json”。但失败率极高而且失败形式五花八门JSON 看似完整但 Scratch 导入后白屏target 没加载、资源对不上blocks 写得像对但 next/parent 关系断裂脚本不执行或执行一半inputs/fields 编码细节错下拉枚举、shadow 输入最容易翻车素材引用写成路径assets/...打包后 Scratch 找不到造型/背景不显示你改一句需求AI 再生成一次整个工程结构都变了不可复现、不可对比、不可回滚本质问题AI 生成的最大风险不是“不会生成”而是“不可控”。5. 三段式拆分plan / exec-plan / build把风险关进笼子里把流程拆成 plan → exec-plan → build本质是在解决三组矛盾人类表达 vs 机器结构人类想讲“玩法”机器需要的是 project.json 的精确结构可读资产 vs 可打包资产仓库里希望assets/sprite/plane.svg可读可维护sb3 里必须md5.ext平铺在根目录快速迭代 vs 可追溯需求改动频繁产物必须能对比、能回滚、能定位“从哪一步开始不对”拆分后每一步的输入输出都变得清晰且可验收。6. 每个 Skill 的职责边界非常重要6.1 plan把想法变成“可验收的计划”planSKILL通过多轮对话采用“每轮只问 1~2 个关键问题 回放已确认点 标记待定项”的节奏把“脑内想法”变成“可执行需求同时为了把“需求”和“实现”彻底解耦减少错误传播此SKILL不写实现细节不写 opcode、不写 project.json把“脑内想法”变成“可执行需求” 很多 Scratch 项目卡在“说得很嗨但落不下来”。xw-scratch-plan 通过多轮对话把目标、胜负条件、玩家操作、玩法闭环、数值规则、资源清单这些关键点逐步收敛成明确条目避免后续反复返工。降低沟通成本与遗漏风险 它采用“每轮只问 1~2 个关键问题 回放已确认点 标记待定项”的节奏能避免一次性把问题抛光导致用户疲劳也能防止关键需求比如失败条件、UI反馈、声音需求漏掉。建立可迭代的拆分粒度plan1/plan2/… 把大需求拆成多个“可交付功能包”每个 plan 聚焦一个阶段素材/移动/规则/UI/关卡等让开发节奏可控任何改动也能定位影响范围改的是哪一包。分包交付、改动可追溯方便后续 exec-plan/build 接上流水线。用“验收标准”约束 AI 与开发过程 它强制每个 plan 文件都包含可在 Scratch 里手动验证的验收标准比如“按空格跳跃落地后可再次跳跃”这会显著减少“做完才发现理解错”的情况也让后续 exec-plan 有清晰的对照实现目标。输出落地位置固定便于流水线接续 最终产物会稳定写入 /project_name/scripts/goal/总体需求.md 并在 /project_name/scripts/plan/ 下生成 planX.md。这样 exec-plan、build 都可以把这些路径当作确定输入形成稳定流水线。不写实现细节不写 opcode、不写 project.json产物示例scripts/goal/总体需求.md覆盖写入scripts/plan/plan1.md、plan2.md…按需创建这一层的价值是让 AI 有一个稳定的“需求约束”并让你用验收标准控制质量。6.2 exec-plan把 planX.md 落成“可运行的 project.json”它解决“结构正确性”并严格依赖权威规范Scratch 3.0 SB3 结构、opcode、inputs/fields 细节。把 planX.md 里的功能性需求按 Scratch 3.0 规范“落地”为可运行的 project.json 并同步产出 exec_log.md 做过程追溯。把最容易“翻车”的环节——从自然语言需求到 SB3 精确结构——变成可重复、可验收、可追踪的一步让整个 plan→exec→build 流水线稳定运转。结构正确性更高 用权威 SB3 规范约束 targets/blocks/inputs/fields 等细节减少“能导入但不跑/白屏/脚本断链”的问题。需求到实现可对照 按 plan 的验收标准去实现避免实现偏离需求。可追溯可回滚 exec_log 记录实现要点、资源引用、关键决策与变更后续改动能快速定位影响范围。工程化衔接顺畅 输出的 project.json 用可读的 assets/… 路径引用素材方便 build 阶段稳定扫描并打包成 sb3。产物示例scripts/plan/planX/project.jsonscripts/plan/planX/exec_log.mdexec_log 的意义不是“写作文”而是可追溯这次执行实现了哪些验收点引用了哪些 assets 路径做了哪些关键决策与变更6.3 build把 project.json 资源打成标准 .sb3它专门解决“可导入性”和“资源规范”把 planX/project.json 其引用的素材转换成 Scratch 3.0 可导入的标准 .sb3 资源改成 md5 命名并打包。build 流水线读取输入 读取 /project_name/scripts/plan/planX/project.json 扫描出所有被引用的资源 targets[].costumes[].md5ext 、 targets[].sounds[].md5ext 。只收集“真正在用”的资源 只处理 project.json 里实际引用到的素材没被引用的不会被打进包里。创建 build 目录 在 /project_name/scripts/plan/planX/build/ 准备打包工作区。复制并规范化资源命名 对每个被引用的资源文件计算内容 MD5生成 . 例如 xxxx.svg / xxxx.wav 并把文件复制到 build 根目录和 project.json 同级符合 sb3 结构。回写 project.json 引用 把 project.json 里的 assetId / md5ext 改成新的 md5 命名保证 Scratch 导入时能找到资源。打包生成 sb3 把 build 目录内的 project.json 所有 md5 资源文件压成 zip再改名为 planX.sb3 。自检 确保 build/project.json 是合法 JSON且里面所有 md5ext 都能在 build 目录找到对应文件同时检查 sb3 包内是“平铺结构”不额外套一层文件夹。优点保证可导入性 sb3 资源命名和目录结构是 Scratch 编辑器最敏感的点build 把这些坑一次性兜住。开发与交付分离 开发阶段用可读路径 assets/… 管素材交付阶段自动变成标准 md5 资源包两边都舒服。产物一致、可复现 同一份素材和 project.json 重复打包结果稳定便于版本管理与回归。产物示例scripts/plan/planX/build/planX.sb3scripts/plan/planX/build/project.json已转换为 SB3 规范命名已重新更名后的素材文件7. 这套设计的关键原则7.1 可控每一步都有确定输入与确定输出plan输入是对话输出是 markdown 文档exec-plan输入是 planX.md输出是 project.json exec_logbuild输入是 project.json assets输出是 sb3 build/project.json你永远知道“下一步拿什么做输入”也能对每一步做局部验收。7.2 可复现产物按 plan 归档天然可对比每个 plan 都有自己的产物目录scripts/plan/plan1/scripts/plan/plan2/…你可以轻松对比两次生成的差异定位回归问题。7.3 可维护开发用可读路径交付用 SB3 规范Scratch×AI 最实用的工程策略开发阶段用assets/...管理素材便于协作与版本控制交付阶段用md5.ext打包保证 Scratch 官方编辑器导入成功8. 小结init 是地基plan/exec/build 是“稳定流水线”当你让 AI 直接写 SB3你是在赌它“刚好写对所有细节”。但现实是SB3 细节太多且有大量跨字段约束失败是常态。当你先用 init 统一目录再用 plan/exec-plan/build 三段式拆分你得到的是可控的输入输出可追溯的日志与产物可维护的素材管理可重复执行的工程化流程接下来真正决定质量的关键点只有一个把 plan 文档里的“验收标准”写对让 AI 在可验收的边界内输出。下一篇我会进入实操细节如何把一个创意写成 planX.md尤其是“验收标准”怎么写才真正能约束住 AI。