# Scratch规范与AI编码SKILL

**Repository Path**: shine_well/scratch_ai_skill

## Basic Information

- **Project Name**: Scratch规范与AI编码SKILL
- **Description**: 从“灵感”到“可导入 Scratch 的 .sb3”一条龙：初始化 → 需求梳理 → 自动生成 project.json → 规范打包
全程对齐 Scratch 3.0（SB3）规范，解决 AI 生成不合规、导入失败、舞台/精灵不显示等顽固问题
面向“信息技术课/亲子共创/STEAM 教育”：少走坑，更多时间打磨玩法
支持先用“人类语言”描述玩法，再由工具把它变成可运行的工程配置
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-04-03
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用 AI 做 Scratch 游戏？这套技能链让想法稳定落地为可导入 .sb3

> 摘要
>
> - 从“灵感”到“可导入 Scratch 的 .sb3”一条龙：初始化 → 需求梳理 → 自动生成 project.json → 规范打包
> - 全程对齐 Scratch 3.0（SB3）规范，解决 AI 生成不合规、导入失败、舞台/精灵不显示等顽固问题
> - 面向“信息技术课/亲子共创/STEAM 教育”：少走坑，更多时间打磨玩法
> - 支持先用“人类语言”描述玩法，再由工具把它变成可运行的工程配置

---

## 背景：为什么要做这套 skill

家里老大在信息技术课上要做一个小型游戏，我们希望借助 AI 一起把创意快速实现。最开始的想法很美：用自然语言描述玩法，让 AI 直接生成 Scratch 工程文件。可实际动手后，问题接二连三：

- AI 生成的 project.json 不符合 Scratch 3 规范；
- 素材引用方式不对，导入后背景或精灵不显示；
- 某些积木用法细节被 AI“自创”，在编辑器中直接报错；
- 即便能打开，变量监视器、克隆、控制流等也经常错位或失效。

为了解决这些痛点，我们把“AI 参与设计”的流程规范化，拆解为清晰的 4 个阶段，并固化成可复用的 skill 工具链：从目录初始化、需求梳理、自动生成符合规范的 project.json，到最终打包为标准 .sb3。目标只有一个——让创意稳定落地，且在 Scratch 官方编辑器中“开箱即用”。

---

## 这套 skill 到底做什么

- xw-scratch-init：创建标准化工程目录  
  在项目根目录生成 assets（背景、精灵、声音）与 scripts（需求与计划）骨架，避免素材与产物“散落一地”，为后续协作与打包做准备。

- xw-scratch-plan：把创意变成清晰的需求与计划  
  通过多轮要点式问答，把“人类语言的玩法”沉淀为两类文档：总体需求（覆盖写入 scripts/goal/总体需求.md）与分步计划（scripts/plan/plan1.md、plan2.md…）。聚焦功能与验收，不引入实现细节。

- xw-scratch-exec-plan：把计划落实为可运行的 project.json  
  读取某个 planX.md，根据 SB3 规范生成对应的 project.json，并产出执行日志 exec_log.md；确保 targets、blocks、inputs/fields、monitors、meta 等结构完全合规，常见坑位有明确校验与修正。

- xw-scratch-build：把计划产出打成符合标准的 .sb3  
  扫描 project.json 中引用的素材，生成 SB3 规范要求的 md5.ext 命名，写回 assetId/md5ext，并在 planX/build/ 目录中打包出 planX.sb3，确保能被官方编辑器正确导入与运行。

参考规范：SB3 配置文件规范与坑位清单已包含在项目中，可直接查阅  
- [Scratch3_SB3_配置文件规范.md](https://gitee.com/shine_well/scratch_ai_skill/blob/main/.trae/skills/xw-scratch-exec-plan/Scratch3_SB3_%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E8%A7%84%E8%8C%83.md)  
- 打包脚本参考：[build_plan.ps1](https://gitee.com/shine_well/scratch_ai_skill/blob/main/.trae/skills/xw-scratch-build/build_plan.ps1)

---

## 使用流程（从 0 到 .sb3）

### 1. 初始化目录（一次性）
创建统一的目录结构，方便后续把素材与计划“各就各位”。

```
assets/
  backdrops/
  sprite/
    sprite1/
  sounds/
scripts/
  goal/
    总体需求.md
  plan/
```

### 2. 梳理需求 → 产出计划
围绕“游戏类型与目标 → 操作与交互 → 玩法闭环 → 角色与资源 → 规则与数值 → 关卡/流程 → 约束与边界”的顺序，收敛为两类文档：

- scripts/goal/总体需求.md（覆盖写入）
- scripts/plan/plan1.md、plan2.md…（每个 plan 是一份可验收的功能包）

推荐的 plan 模板示例：

```markdown
# 本计划目标
- 让主角可以通过键盘方向键移动，并在舞台边缘反弹

# 功能需求清单
- 方向键上下左右控制位移；速度为 5
- 碰到舞台边缘自动反弹
- 在舞台左上角以监视器显示“步数”变量（每移动一次 +1）

# 资源需求
- 主角造型：assets/sprite/sprite1/hero.svg
- 舞台背景：assets/backdrops/bg1.svg

# 交互与规则
- 用户按键触发移动；松开停止
- 触边时反向；持续播放行走动画

# 验收标准
- 在 Scratch 编辑器中，按方向键主角移动，松开停止
- 碰边反弹；步数监视器随移动递增
```

### 3. 执行计划 → 自动生成 project.json
选择 planX（例如 plan1），工具会：
- 生成 scripts/plan/plan1/project.json
- 生成 scripts/plan/plan1/exec_log.md（记录实现要点与变更）

生成的 project.json 满足以下关键约束：
- 控制类 cap 积木（如 control_stop）不会错误串接 next
- 克隆目标“自己”字段使用 "_myself_"
- 复杂输入位（inputs）符合 Scratch 导出风格（如保留默认 shadow）
- 仅使用基础（非扩展）opcode，避免兼容性问题
- 中文字段正确读写，避免乱码

### 4. 规范打包 → 输出 planX.sb3
在 scripts/plan/planX/build/ 目录中，打包得到 planX.sb3，且：
- build/project.json 内所有 md5ext 都对应 build 根目录下真实存在的 <md5>.<ext>
- 压缩包根目录直接包含 project.json 与资源文件（无多余文件夹）
- 可直接在 Scratch 官方编辑器中导入并运行

如需在 PowerShell 环境手动打包，可复用项目已提供的脚本（示例命令见脚本注释），其内部已处理 Windows + PowerShell 5.1 的常见坑（如 UTF8、最大 JSON 深度、zip 改名为 .sb3）。

---

## 它解决了哪些硬伤

- SB3 结构不合规  
  严格对齐 targets/blocks/monitors/meta 等字段结构，减少“能打开但不能跑”的玄学问题。

- 素材引用与命名混乱  
  先以可读路径组织 assets，执行阶段按需引用；打包阶段统一计算 md5，回写 assetId/md5ext 并生成 .sb3。

- 常见细节坑位兜底  
  - inputs 的 shadow 处理、三段式输入保持与替换
  - control_stop 终止类积木 next: null
  - 克隆目标 "_myself_" 常量使用
  - 中文字段读写用 UTF8 无 BOM，避免监视器/变量名乱码

- 需求与实现长期同步  
  每个 plan 对应一套 project.json + exec_log.md，便于回归验证与后续迭代。

---

## 快速上手清单

- 场景：课堂作业/亲子共创/AI+教育/课后社团
- 角色：不要求会写 SB3，只要能清楚表达玩法与验收点
- 产物：最终获得可导入 Scratch 编辑器的 .sb3 与完整工程目录
- 建议：先做“最小可玩”回路（移动/得分/失败），再逐步加难度与表现

---

## 常见问题（FAQ）

- 计划里写了资源路径，但打包说“资源不存在”？  
  请检查 assets 下的实际文件是否存在、路径大小写是否一致；仅被 project.json 引用到的资源才会被复制与改名。

- 导入后变量监视器显示乱码？  
  生成与写入 project.json 使用 UTF8 无 BOM；若你手动编辑，请确保保持相同编码。

- 能不能直接把 AI 生成的 project.json 拿来打包？  
  不建议。建议通过“计划执行 → 生成合法 project.json → 规范打包”的链路，确保结构合规后再打包。

---

## 结语

AI 擅长帮助我们“描述与探索”玩法，但把创意稳稳落地到 Scratch，需要一条可靠的工程化链路。这套 skill 把流程拆清楚、把坑位兜住、把产物做标准，让课堂作业与亲子共创更聚焦在“玩法有趣、表达清晰”。

如果你也正在做 Scratch 小游戏，欢迎按“初始化 → 需求梳理 → 执行计划 → 规范打包”的步骤走一遍，让第一个可玩的 .sb3 尽快跑起来。