arcade-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guolin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# arcade-ai
+
+AI-driven scaffold and live studio for Microsoft MakeCode Arcade games.
+
+## 安装与集成方式 (Installation & Integration)
+
+### 1. Claude Code 插件市场 (Claude Code plugin marketplace)
+你可以在 Claude Code plugin marketplace 中搜索并安装 `arcade-ai`。安装后即可在与 AI 对话时使用对应的技能，帮助生成和实时验证 MakeCode Arcade 游戏代码。
+
+### 2. Trae 智能辅助工具 (.trae)
+如果你使用 Trae，请将技能配置添加到 `.trae` 相关的规则路径中。初始化脚手架时通过指定 `--tool trae` 会在项目根目录下自动创建 `.trae/project_rules.md`。
+
+### 3. AI 代理常规配置 (AGENTS.md)
+对于通用的 AI 代理（如 Cline 或 Cursor 等），会在初始化时生成 `AGENTS.md` 文件。该文件定义了只修改 `game/main.ts`、严守 MakeCode Arcade 的 4 个约束、不可臆造 API 等核心规则，请确保将此规则导入你的 AI Agent 配置中。
+
+## 使用方法 (Usage)
+
+1. **项目初始化**：
+   ```bash
+   npx aca init <your-game-dir> [--tool claude|trae|agents]
+   ```
+2. **启动本地 Studio 双向实时预览服务**：
+   ```bash
+   cd <your-game-dir>
+   npx aca dev
+   ```
+3. **自检 postMessage 协议状态**：
+   ```bash
+   npx aca check
+   ```

package/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: arcade-ai
+description: Use when building or modifying a Microsoft MakeCode Arcade game — scaffolds a project, runs a live studio embedding the official editor, and provides an offline API/limits/pitfalls reference.
+---
+
+# MakeCode Arcade AI Studio
+
+帮助用 AI 开发 Microsoft MakeCode Arcade 游戏：脚手架 + 嵌入官方编辑器的实时双向同步 studio
++ 离线参考手册。
+
+## 何时用
+- 用户想做 / 改 arcade 游戏、像素小游戏、makecode 游戏时。
+
+## 怎么用（三个命令）
+1. 起项目：`npx arcade-ai init <dir> [--tool claude|trae|agents]`
+   —— 生成纯 TS 脚手架，并把规则文件与 `reference/` 一并拷进项目。
+2. 起 studio：在项目目录 `npx aca dev` —— 浏览器实时预览，AI 改 `game/main.ts` 自动刷新；
+   在编辑器里改代码/画精灵也会回写磁盘（双向）。
+3. 协议自检：`npx aca check` —— 验证官方编辑器握手 + 代码真渲染（联网，需 puppeteer）。
+
+## 写代码硬约束（违反会翻车）
+- 代码只写 `game/main.ts`；资源（精灵/地图，4-bit 16 色）走 `game/assets.json`，不内联大图到 JS。
+- **纯 TS 项目**：`game/` 里不要 `main.blocks`，`pxt.json` 的 `files` 也不列它，
+  `preferredEditor` 用 `tsprj`。否则编辑器会开在空白积木视图、看不到代码。
+- `assets.json` 必须是合法 JSON（空资源写 `{}`），不要清空成空文件。
+- **地图**：用命名地图 `tiles.setTilemap(tilemap`level`)`（编辑器自动建、人可画、自动同步回磁盘），
+  或 `createTilemap` 配**内置图块**（`sprites.castle.*`）。❌ 别把内联 `img` 当图块塞进 `createTilemap`，会崩。
+- 不臆造 arcade 不存在的 API。
+
+## 查文档（按需读，不要全量背）
+本 skill 同级、以及 `aca init` 生成的用户项目内，都有一份 `reference/`：
+- `reference/arcade-api.md` —— sprites / controller / game / tilemap / music / info API 速查
+- `reference/limits.md` —— 屏幕、调色板、内存、不支持的 JS 特性等硬限制
+- `reference/pitfalls.md` —— 已知坑 + postMessage 协议字段（动手前务必扫一遍）
+- `reference/project-format.md` —— pxt.json / assets.json / 文件格式约定
+
+写代码前，遇到不确定的 API 或限制就读对应文件，不要凭记忆。

package/bin/aca.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run(process.argv.slice(2)).then((code) => process.exit(code));

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "arcade-ai",
+  "version": "0.1.0",
+  "description": "AI-driven scaffold and live studio for Microsoft MakeCode Arcade games",
+  "keywords": [
+    "makecode",
+    "arcade",
+    "ai",
+    "game",
+    "pixel",
+    "education"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "aca": "bin/aca.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "reference",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "chokidar": "^3.6.0"
+  },
+  "optionalDependencies": {
+    "puppeteer": "^22.0.0"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 tests/*.test.js"
+  }
+}

package/reference/arcade-api.md

@@ -0,0 +1,158 @@
+# MakeCode Arcade API Quick Reference
+
+本文档收集了 Microsoft MakeCode Arcade 中的常用高频 APIs，包含精灵、控制器、游戏循环、瓦片图、音乐和游戏信息等模块。
+
+## 1. 精灵 (Sprites)
+精灵是游戏中的主体元素（角色、敌人、道具、特效等）。
+
+- **创建精灵**：
+  `let player = sprites.create(img`...`, SpriteKind.Player)`
+- **控制精灵在屏幕内**：
+  `player.setStayInScreen(true)`
+- **设置精灵位置**：
+  `player.setPosition(x: number, y: number)`
+- **精灵速度**：
+  `player.vx = 50` (X轴速度)
+  `player.vy = -20` (Y轴速度)
+- **销毁精灵**：
+  `player.destroy(effects.disintegrate, 500)` (支持特效与延迟时间)
+- **碰撞重叠事件**：
+  ```typescript
+  sprites.onOverlap(SpriteKind.Player, SpriteKind.Enemy, function(player, enemy) {
+      enemy.destroy();
+      info.changeLifeBy(-1);
+  });
+  ```
+
+## 2. 控制器 (Controller)
+控制玩家输入。
+
+- **用摇杆移动精灵**：
+  `controller.moveSprite(player, vx?, vy?)` (默认速度为 100)
+- **按键事件**：
+  ```typescript
+  controller.A.onEvent(ControllerButtonEvent.Pressed, function() {
+      // 射击子弹
+      let projectile = sprites.createProjectileFromSprite(img`...`, player, 200, 0);
+  });
+  ```
+- **获取当前摇杆倾斜度**：
+  `controller.dx()`, `controller.dy()`
+
+## 3. 游戏控制与循环 (Game)
+控制游戏全局流和定时执行。
+
+- **游戏更新循环**（每帧执行）：
+  ```typescript
+  game.onUpdate(function() {
+      // 每帧执行的物理逻辑或状态检查
+  });
+  ```
+- **定时更新循环**（指定毫秒数执行一次）：
+  ```typescript
+  game.onUpdateInterval(1000, function() {
+      // 每秒生成一个敌人
+      let enemy = sprites.create(img`...`, SpriteKind.Enemy);
+  });
+  ```
+- **游戏结束**：
+  `game.over(win: boolean, effect?: effect)`
+- **显示长文本对话框**：
+  `game.showLongText("Hello World!", DialogLayout.Bottom)`
+
+## 4. 瓦片地图 (Tilemap)
+用于绘制游戏背景和关卡障碍。
+
+- **设置当前瓦片地图**：
+  `tiles.setCurrentTilemap(tilemap`level1`)`
+- **将精灵移入特定瓦片**：
+  `tiles.placeOnRandomTile(sprite, assets.tile`transparency1`)`
+- **碰撞瓦片判定**：
+  ```typescript
+  scene.onOverlapTile(SpriteKind.Player, assets.tile`lava`, function(sprite, location) {
+      info.changeLifeBy(-1);
+  });
+  ```
+
+## 5. 音乐与音效 (Music)
+- **播放内置音效**：
+  `music.play(music.melodyPlayable(music.baDing), music.PlaybackMode.UntilDone)`
+- **播放乐谱简谱**：
+  `music.playMelody("C5 B A G F E D C ", 120)`
+- **常用预设音效**：
+  `music.pewPew`, `music.jumpUp`, `music.powerUp`, `music.powerDown`
+
+## 6. 游戏信息 (Info)
+处理分数、生命值和计时器。
+
+- **设置/修改分数**：
+  `info.setScore(0)`
+  `info.changeScoreBy(10)`
+- **设置/修改生命值**：
+  `info.setLife(3)`
+  `info.changeLifeBy(-1)`
+- **倒计时**：
+  `info.startCountdown(30)` (30秒)
+  `info.onCountdownEnd(function() { game.over(false) })`
+
+## 7. 地图 Tilemap（两条可靠路线，外加一个会崩的禁区）
+
+> ⚠️ **禁区**：`tiles.createTilemap(hex`...`, img`...`, [内联 img tile], ...)` —— **把内联 `img` 当图块会让官方编辑器崩溃**（Oops 重载循环）。编辑器的 tilemap 解析器只接受“命名图块资源”，不接受随手写的内联 img。已实测确认。详见 pitfalls 坑5。
+
+### 路线 A（推荐，AI + 人协作）：命名地图 `tilemap`level``
+AI 在代码里引用一个命名地图；编辑器首次打开会**自动创建一张可编辑的空地图**，人在网页地图编辑器里画好后，自动同步回磁盘（`tilemap.g.ts` / `tilemap.g.jres`）并随游戏运行、可反复改。
+```typescript
+tiles.setTilemap(tilemap`level`)     // level 不存在时编辑器会自动创建
+scene.cameraFollowSprite(mySprite)
+```
+
+### 路线 B（纯代码，用内置图块）：`createTilemap` + **内置 tile**
+图块用 MakeCode 自带的图库（真资源，不会崩），而不是内联 img：
+```typescript
+const data = Buffer.create(4 + cols * rows);
+data.setNumber(NumberFormat.Int16LE, 0, cols);   // 宽
+data.setNumber(NumberFormat.Int16LE, 2, rows);   // 高
+data.setUint8(4 + row * cols + col, tileIndex);  // 每格图块索引（0 起，指向下面数组）
+const walls = image.create(cols, rows);          // 墙体层：非透明像素=墙
+const tm = tiles.createTilemap(
+    data, walls,
+    [sprites.castle.tileGrass1, sprites.castle.tilePath5],  // 内置图块，非内联 img
+    TileScale.Sixteen);
+tiles.setCurrentTilemap(tm);
+```
+
+### 内置图库（直接按名引用，无需手画/手写 jres）
+- `sprites.castle.*` —— 草地/路/石头/房子等：`tileGrass1`、`tileGrass2`、`tileDarkGrass2`、`tilePath5`、`rock0`、`houseBlue` …
+- 还有 `sprites.dungeon.*`、`sprites.builtin.*`、`sprites.food.*`、`sprites.vehicle.*` 等多个图库。
+- **确切名字以编辑器里的图库(image gallery)为准**——打开精灵/地图编辑器点“Gallery”即可浏览全部，别凭记忆臆造名字。
+
+## 8. Looping Background Music & Custom Melodies
+- **Play Custom Notes Looping**: Use `music.stringPlayable` and `music.PlaybackMode.LoopingInBackground`.
+  ```typescript
+  music.play(
+      music.stringPlayable("E G A G C5 B A G ", 120),
+      music.PlaybackMode.LoopingInBackground
+  );
+  ```
+- **Stop All Sounds**: `music.stopAllSounds()`
+
+## 9. Collisions & Overlap Events
+- **Scene Wall Collision Event**: Triggered when a sprite hits a tilemap wall:
+  ```typescript
+  scene.onHitWall(SpriteKind.Enemy, function(enemy: Sprite, location: tiles.Location) {
+      enemy.vx = -enemy.vx; // Bounce back
+  });
+  ```
+- **Sprite Overlap Event**:
+  ```typescript
+  sprites.onOverlap(SpriteKind.Player, SpriteKind.Enemy, function(player: Sprite, enemy: Sprite) {
+      // Logic here
+  });
+  ```
+- **Tile Overlap Event**:
+  ```typescript
+  scene.onOverlapTile(SpriteKind.Player, tileSpike, function(player: Sprite, location: tiles.Location) {
+      // Logic here (e.g. respawn player)
+  });
+  ```
+

package/reference/limits.md

@@ -0,0 +1,36 @@
+# MakeCode Arcade Limits & Unsupported JS Features
+
+Microsoft MakeCode Arcade 专为复古的 8-bit 和 16-bit 掌机设计。虽然它支持使用 TypeScript (JavaScript) 编写游戏，但其底层的物理硬件运行环境、编译器和渲染器都引入了许多限制。
+
+## 1. 硬件与显示限制
+
+- **屏幕分辨率 (Screen Resolution)**：
+  固定为 **160 x 120 像素**。所有精灵坐标、屏幕尺寸和瓦片大小都是基于该分辨率进行布局。
+- **16 色调色板 (16-Color Palette)**：
+  底层是 4-bit 颜色深度（Color Depth）。仅支持固定包含 16 种颜色的经典 MS MakeCode Arcade 调色板。
+  * 颜色 `0`（在 img 中通常写作 `.`）代表透明色。
+  * 精灵图象（Image 字面量）中只能使用这 16 种字符代码（如 `.`, `1`-`9`, `a`-`f`）来代表不同的颜色。
+
+## 2. 内存与精灵数量限制
+
+在运行模拟器或部署在实体 Arcade 硬件（如 PyGamer、PyBadge、Meowbit 等）上时，面临着极度受限的运行资源：
+- **精灵数量上限 (Sprite Count)**：
+  通常在硬件上不建议同时存在超过 **30-50 个活动的精灵**，否则垃圾回收（Garbage Collection）和每帧碰撞检测会导致帧率骤降。
+- **内存限制 (Memory Limit)**：
+  微控制器通常仅有 96KB - 512KB 的 RAM。在 TypeScript 中创建大量的动态数组或嵌套深层对象，或者在循环中频繁实例化临时对象，很容易导致内存溢出崩溃。
+
+## 3. 不支持的 JavaScript (TypeScript) 语言特性
+
+MakeCode 拥有自定义的 TypeScript-to-C++ (Static TypeScript) 编译器。它**不包含完整的 JS 运行时环境**（如 V8 或 QuickJS），所以以下特性是不支持或受到极大限制的：
+
+- **Async / Await 和 Promise**：
+  MakeCode 底层采用轻量级的绿色线程（Fiber）协同运行。原生的 `async/await` 语法和 `Promise` 对象是**不支持**的。
+  * *替代方案*：如果需要延迟，请使用 MakeCode 内置的 `pause(ms)` API 挂起当前协程。
+- **内置数据结构限制**：
+  不支持 `Map`、`Set` 以及 `WeakMap` / `WeakSet`。
+  * *替代方案*：使用普通的对象 `{ [key: string]: val }` 或数组进行简单的 key-value 映射。
+- **未实现的 JS API**：
+  由于本地无标准的 Web 浏览器环境，任何浏览器和 Node.js 原生的 API（如 `window`, `document`, `fetch`, `console.log` 的完整版，以及任何 DOM 或 Node 内置库）在 Arcade 运行时内均不可用。
+- **动态特性限制**：
+  - 不支持 `eval()`、`new Function()` 等动态代码执行。
+  - 不支持 `Object.defineProperty` 或 `Proxy` 拦截。

package/reference/pitfalls.md

@@ -0,0 +1,72 @@
+# MakeCode Arcade Pitfalls & postMessage Protocol Reference
+
+本文档总结了在使用和集成 Microsoft MakeCode Arcade 官方编辑器时常见的四个关键坑点及对应的解决方案，并对双向同步时所使用的 `postMessage` 协议字段进行了详细说明。
+
+## 常见坑点 (Common Pitfalls)
+
+### 1. 资源配置文件 `assets.json` 不得为空
+* **现象**：当宿主将本地文件推送到 MakeCode 编辑器后，编辑器可能崩溃，显示 "Oops We detected a problem..." 并不断自动刷新。
+* **原因**：因为 `assets.json` 作为美术资源（如瓦片图、贴图、精灵）配置文件，如果是一个空文件（0 字节或 1 字节），编辑器内部的 `JSON.parse` 无法解析空字符串，从而抛出未捕获异常导致崩溃。
+* **解决**：在初始化和保存时，`assets.json` 的内容必须是合法的 JSON 对象 `"{}"`，不得为空文件。
+
+### 2. `pxt.json` 中的 `files` 数组必须与实际文件一致
+* **现象**：修改或同步代码后，编辑器解析警告、代码丢失或无法渲染。
+* **原因**：MakeCode 的同步逻辑严格依赖 `files` 声明。`files` 数组里列出的文件必须都真实存在，反之磁盘上要被编辑器读取的文件也必须在 `files` 里声明，否则关联错乱。
+* **解决**：纯 TypeScript 工作流（本项目默认）声明 `["main.ts", "README.md", "assets.json"]` 即可，**不要列入 `main.blocks`**（见坑 3）。
+
+### 3. ⚠️ 不要推送空的 `main.blocks` / 不要用 `blocksprj`（真机验证纠正）
+* **现象**：编辑器加载成功、文件也同步进去了（README 能显示），**但代码区一片空白，看似一个全新空项目**。
+* **原因**：只要项目里存在 `main.blocks` 文件，编辑器就默认打开**积木（Blocks）视图**；而 AI 生成的代码在 `main.ts` 里、`main.blocks` 是空的，于是积木画布空白、`main.ts` 不显示，且 MakeCode **不会**在加载时自动把 TS 反编译成积木。仅改 header 的 `editor` 字段无法纠正——`main.blocks` 的存在会压倒它。
+* **解决**：做**纯 TypeScript 项目**——磁盘上**不要 `main.blocks`**、`files` 里也不列它，header 用 `editor: "tsprj"`、`pxt.json` 的 `preferredEditor: "tsprj"`。编辑器即会开在 JavaScript 视图并显示 `main.ts`。
+* **教训**：握手成功（编辑器请求 `/api/project`）发生在加载早期，**不等于代码渲染成功**。验证一定要确认编辑器里**真的出现了代码**，否则空白项目会假阳性蒙混过关。`aca check` 已据此加强为两关：握手 + 渲染。
+
+### 4. iframe 加载官方地址时遭遇 404
+* **现象**：使用 `https://arcade.makecode.com/index.html?controller=1` 时页面直接返回 404 导致 iframe 挂起白屏。
+* **原因**：微软官方在线版会安全过滤或缓存拦截带有 `index.html` 路径的请求。
+* **解决**：iframe.src 请求应当使用纯净的根域名路径，即 `https://arcade.makecode.com/?controller=1`（不要带 `index.html`）。
+
+### 5. ⚠️ tilemap 用内联 `img` 当图块 → 编辑器崩溃（实测确认）
+* **现象**：`tiles.createTilemap(hex`...`, img`...`, [tileA, tileB], TileScale.Sixteen)` 里把 `tileA/tileB` 写成**内联 `img` 变量**，编辑器加载后崩溃，弹 "Oops, we detected a problem..." 并不断重载。
+* **原因**：编辑器的 tilemap 字段编辑器会尝试把 `createTilemap` 反编译成可视化地图控件，它只认**命名图块资源**（`myTiles.xxx` / 内置 `sprites.castle.xxx`），遇到随手写的内联 img 图块就解析崩溃。
+* **解决**：地图走两条可靠路线之一（见 arcade-api.md 第 7 节）：
+  1. **命名地图** `tiles.setTilemap(tilemap`level`)`——编辑器自动创建空地图，人画好后同步回磁盘；
+  2. **内置图块** `createTilemap(..., [sprites.castle.tileGrass1, ...], ...)`——图块用自带图库，不要内联 img。
+* **补充**：图块/地图数据最终以 base64 的 F4 图片格式存进 `tilemap.g.jres`，由 `tilemap.g.ts` 声明命名空间——这些是编辑器生成的，AI 不要手写 jres。
+
+---
+
+## postMessage 协议字段参考
+
+在宿主与嵌入的 MakeCode iframe 通信中，所有的消息都是通过 HTML5 的 `postMessage` 协议进行的，通常使用 `type: "pxthost"` 来标识由宿主环境与编辑器之间的 workspace 级交互。
+
+### 1. `workspacesync` (同步请求)
+当编辑器 iframe 初始化加载完成后，它会向宿主发送一个 `action: "workspacesync"` 的消息，向宿主请求本地代码文件。
+- **消息发送方**：编辑器 iframe -> 宿主 window
+- **格式**：
+  ```json
+  {
+    "type": "pxthost",
+    "action": "workspacesync"
+  }
+  ```
+- **宿主响应**：宿主收到后，读取本地文件列表并回复。回复消息也需要包含相同的 `type: "pxthost"` 和 `action: "workspacesync"`，同时附带 `projects` 数组，指定 `header`（其中 `editor: "tsprj"`，见坑 3）和 `text`（包含文件名与文件内容的键值对）。
+
+### 2. `workspacesave` (保存请求)
+当用户在编辑器中拖拽积木或编辑代码发生改变时，编辑器会触发自动保存，并向宿主发送一个 `action: "workspacesave"` 的消息。
+- **消息发送方**：编辑器 iframe -> 宿主 window
+- **格式**：
+  ```json
+  {
+    "type": "pxthost",
+    "action": "workspacesave",
+    "project": {
+      "header": { ... },
+      "text": {
+        "main.ts": "...",
+        "assets.json": "...",
+        "pxt.json": "..."
+      }
+    }
+  }
+  ```
+- **宿主处理**：宿主接收到此消息后，解析出其中的 `project.text`，并将其中的文件写回本地磁盘，随后宿主通过暂停监听文件变化来避免写盘引发的回声现象（watcher echo）。

package/reference/project-format.md

@@ -0,0 +1,55 @@
+# MakeCode Arcade Project Format Reference
+
+本文档介绍了 Microsoft MakeCode Arcade (PXT) 项目的工程格式与文件结构，包括核心配置文件、资源存储模式、自动生成的 TypeScript 代码以及开发时遵守的白名单机制。
+
+## 1. 核心配置文件
+
+- **`pxt.json`**：
+  项目的包管理器和工程说明书。它声明了项目的名称、依赖的库和编译的入口文件。
+  * `name`：项目名称。
+  * `dependencies`：外部包依赖。默认包含 `"device": "*"` 代表核心 API。
+  * `files`：非常关键！列出了该项目参与编译的所有文件列表。加了 tilemap/命名资源后，
+    编辑器会自动把生成的 `*.g.ts` 加进这里——同步时要原样带回（见第 3 节）。
+  * `preferredEditor`：首选编辑器类型。本项目是纯 TS 工作流，应为 `"tsprj"`（JavaScript 视图）。
+    **不要用 `blocksprj`**，否则编辑器开在空白积木视图、看不到 `main.ts` 代码（见 pitfalls 坑3）。
+
+- **`assets.json`**：
+  在 MakeCode 项目中用来存放用户设计的所有美术资源（图像、精灵图、瓦片、瓦片图、动画等）。
+  * 必须是一个合法的 JSON 对象，内容不得为空。即使没有资源也应初始化为 `"{}"`。
+  * 其中的美术资源使用类似 F4（MakeCode 资源版本格式）的结构表示。图像在底层会被编译为 `Image` 字面量。
+
+## 2. 自动生成的 TS 文件 (`*.g.ts`)
+
+当在编辑器的 Assets 管理面板中设计或导入图片、瓦片图后，编辑器在自动保存时会在内存中或输出的工程里动态生成相关的 TypeScript 代码接口：
+
+- **`images.g.ts`**：
+  自动生成美术精灵图（Sprite Images）的声明。例如，在 assets 面板建了一个叫 `hero` 的精灵图，它会在代码中生成类似：
+  ```typescript
+  namespace myImages {
+      export const hero = img`...`;
+  }
+  ```
+  在代码中可通过 `assets.image`hero`` 直接引用。
+
+- **`tilemap.g.ts`**：
+  声明编辑的瓦片地图（Tilemap）以及关联的图块（Tiles）。它将复杂的二维图块数组序列化，并暴露常量（如 `tilemap`level1``）。
+
+*注意*：这些 `*.g.ts`（以及 tilemap 关联的 `*.g.jres`）是编辑器生成的、AI 不应手改的代码，
+但**必须参与同步**——否则在编辑器里画的地图/命名资源会丢失。`arcade-ai` 会自动往返这些文件。
+
+## 3. `arcade-ai` 工程同步规则（按扩展名，非固定名单）
+
+本地双向实时同步**不再用固定文件名白名单**（旧版只认 6 个文件，会把 tilemap 生成的
+`*.g.ts` / `*.g.jres` 丢掉，导致地图存不住）。现在 `project-io` 按**扩展名**动态同步项目根下
+所有项目文件：
+
+- **同步的扩展名**：`.ts`、`.js`、`.json`、`.md`、`.blocks`、`.jres`、`.txt`。
+  涵盖 `main.ts`、`pxt.json`、`assets.json`、`README.md`、以及 `tilemap.g.ts`、`tiles.g.jres`
+  等动态生成文件。
+- **自动排除**：
+  - 目录 `pxt_modules` / `built` / `node_modules` / `.git`（依赖与产物）。
+  - 隐藏文件（`.gitignore`、`.env` 等）。
+  - 其它扩展（`.sh`、`.png`、二进制等）。
+  - 带路径分隔或 `..` 的名字（防目录遍历，只接受项目根下的纯文件名）。
+
+这样地图、命名精灵等会生成额外文件的功能都能完整往返，同时仍挡住危险/冗余文件。

package/src/cli.js

@@ -0,0 +1,32 @@
+import { parseArgs as nodeParseArgs } from 'node:util';
+
+const COMMANDS = { init: 'init', dev: 'dev', check: 'check' };
+
+export function parseArgs(argv) {
+  const { values, positionals } = nodeParseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      tool: { type: 'string' },
+      port: { type: 'string' },
+      url: { type: 'string' },
+    },
+  });
+  const [command, ...rest] = positionals;
+  return { command, positionals: rest, options: values };
+}
+
+const HELP = `arcade-ai (aca)
+用法:
+  aca init [dir] [--tool claude|trae|agents]   起脚手架
+  aca dev  [--port 8080]                        起本地 studio
+  aca check [--url <makecode-url>]              自检 postMessage 协议`;
+
+export async function run(argv) {
+  const { command, positionals, options } = parseArgs(argv);
+  if (!command) { console.log(HELP); return 0; }
+  if (!COMMANDS[command]) { console.error(`未知命令: ${command}\n\n${HELP}`); return 1; }
+  const mod = await import(`./commands/${command}.js`);
+  return mod.default({ positionals, options });
+}

package/src/commands/check.js

@@ -0,0 +1,58 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startStudio } from '../studio/server.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const hostHtmlPath = join(here, '..', 'host', 'index.html');
+const gameDir = join(here, '..', 'template', 'game');   // 用内置模板当样本
+
+export default async function check(ctx) {
+  let puppeteer;
+  try { puppeteer = (await import('puppeteer')).default; }
+  catch { console.error('需要 puppeteer：npm i -D puppeteer'); return 2; }
+
+  const studio = await startStudio({ gameDir, port: 0, hostHtmlPath });
+  const browser = await puppeteer.launch({ headless: 'new', args: ['--no-sandbox'] });
+  try {
+    const page = await browser.newPage();
+    await page.goto(studio.url, { waitUntil: 'networkidle2', timeout: 60000 });
+
+    // 第 1 关：握手 —— 编辑器触发 workspacesync，host 页据此请求 /api/project。
+    await page.waitForResponse((r) => r.url().endsWith('/api/project'), { timeout: 45000 });
+    console.log('  · 握手成功：编辑器已发起 workspacesync 并拉取本地项目');
+
+    // 第 2 关（关键）：渲染 —— 等编辑器把 main.ts 真正显示出来。
+    // 仅靠握手是不够的：项目可能加载成空白积木视图。必须确认代码可见。
+    const editorFrame = await waitForEditorFrame(page);
+    const SNIPPET = 'sprites.create';
+    await editorFrame.waitForFunction((kw) => {
+      const lines = [...document.querySelectorAll('.view-line')].map((l) => l.textContent).join('\n');
+      return lines.includes(kw);
+    }, { timeout: 30000 }, SNIPPET);
+    console.log('  · 渲染成功：编辑器 JS 视图已显示 main.ts 代码');
+
+    console.log('✅ 协议自检通过：握手 + 代码渲染均成立');
+    return 0;
+  } catch (e) {
+    console.error(`❌ 自检失败：${e.message}`);
+    console.error('   （若卡在"渲染"步：多半是项目以空白积木视图打开——检查 pxt.json 是否误含 main.blocks / preferredEditor 是否为 tsprj）');
+    return 1;
+  } finally {
+    await browser.close();
+    await studio.close();
+  }
+}
+
+// 官方编辑器主 frame（排除文档/模拟器子 frame）
+async function waitForEditorFrame(page) {
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    const f = page.frames().find((fr) =>
+      fr.url().includes('makecode.com') &&
+      !fr.url().includes('---docs') &&
+      !fr.url().includes('---simulator'));
+    if (f) return f;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error('未找到官方编辑器 iframe');
+}

package/src/commands/dev.js

@@ -0,0 +1,25 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { startStudio } from '../studio/server.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const hostHtmlPath = join(here, '..', 'host', 'index.html');
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try { spawn(cmd, args, { stdio: 'ignore', detached: true }).unref(); } catch {}
+}
+
+export default async function dev(ctx) {
+  const cwd = ctx.options._cwd || process.cwd();
+  const gameDir = join(cwd, 'game');
+  const port = ctx.options._noBlock ? 0 : Number(ctx.options.port || 8080);
+  const studio = await startStudio({ gameDir, port, hostHtmlPath });
+  if (ctx.options._noBlock) return studio;
+  console.log(`🎮 studio: ${studio.url}`);
+  openBrowser(studio.url);
+  return new Promise(() => {});   // 常驻
+}

package/src/commands/init.js

@@ -0,0 +1,34 @@
+import { cpSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const templateDir = join(here, '..', 'template');
+// reference 是知识层，随 skill 与 npm 包一起发布（仓库根 /reference）
+export const referenceDir = join(here, '..', '..', 'reference');
+
+const RULES = {
+  claude: { src: 'claude.md', dest: 'CLAUDE.md' },
+  trae: { src: 'project_rules.md', dest: '.trae/project_rules.md' },
+  agents: { src: 'agents.md', dest: 'AGENTS.md' },
+};
+
+function writeRules(dest, tool) {
+  const r = RULES[tool] || RULES.agents;
+  const content = readFileSync(join(here, '..', 'rules', r.src), 'utf8');
+  const target = join(dest, r.dest);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content, 'utf8');
+}
+
+export default async function init(ctx) {
+  const dest = ctx.positionals[0] || 'arcade-game';
+  mkdirSync(dest, { recursive: true });
+  cpSync(join(templateDir, 'game'), join(dest, 'game'), { recursive: true });
+  copyFileSync(join(templateDir, 'package.json'), join(dest, 'package.json'));
+  // 把知识库拷进项目，使其自包含、跨工具可查（Trae/其它 AI 裸读项目也能用）
+  cpSync(referenceDir, join(dest, 'reference'), { recursive: true });
+  writeRules(dest, ctx.options.tool);
+  console.log(`✅ 已创建 ${dest}\n  cd ${dest} && npx aca dev`);
+  return 0;
+}

package/src/host/index.html

@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><title>arcade-ai studio</title>
+<style>html,body{margin:0;height:100%}iframe{width:100%;height:100%;border:0}</style></head>
+<body>
+<iframe id="mc" src="https://arcade.makecode.com/?controller=1"
+  sandbox="allow-popups allow-forms allow-scripts allow-same-origin"
+  allow="autoplay; gamepad; midi"></iframe>
+<script>
+const iframe = document.getElementById('mc');
+
+window.addEventListener('message', async (event) => {
+  if (event.source !== iframe.contentWindow) return;
+  const msg = event.data; if (!msg) return;
+
+  if (msg.type === 'pxthost' && msg.action === 'workspacesync') {
+    const data = await (await fetch('/api/project')).json();
+    msg.projects = [{
+      header: {
+        id: 'arcade-ai-project', name: 'arcade-game',
+        modificationTime: Date.now(), recentUse: Date.now(),
+        target: 'arcade', editor: 'tsprj'        // JS 视图：AI 写的是 main.ts，须开在 TS 编辑器
+      },
+      text: data.files
+    }];
+    iframe.contentWindow.postMessage(msg, '*');
+  }
+
+  if (msg.type === 'pxthost' && msg.action === 'workspacesave') {
+    const project = msg.project;
+    if (project && project.text) {
+      await fetch('/api/save', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ files: project.text })
+      });
+    }
+  }
+});
+
+// 文件被外部（AI）改动 → 自动 reload iframe，重走 workspacesync（已验证路径）
+const es = new EventSource('/events');
+es.onmessage = (e) => { if (e.data === 'changed') iframe.src = iframe.src; };
+</script>
+</body>
+</html>

package/src/project-io.js

@@ -0,0 +1,59 @@
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+
+// MakeCode arcade 项目文件按扩展名同步（项目文件都在项目根，无子目录）。
+// 这样 tilemap/命名资源生成的 *.g.ts / *.g.jres 也能完整往返，而不是被固定白名单丢弃。
+// 纯 JS 工具：不收 .py（编辑器从 main.ts 自动转译的 Python 产物）。
+const SYNC_EXTS = new Set(['.ts', '.js', '.json', '.md', '.blocks', '.jres', '.txt']);
+
+// 目录黑名单：依赖、产物，不参与同步。
+const SKIP_DIRS = new Set(['pxt_modules', 'built', 'node_modules', '.git']);
+
+// 一个文件名是否该同步：纯文件名（防路径遍历）、非隐藏、扩展在白名单内。
+export function isSyncable(name) {
+  if (typeof name !== 'string' || name.length === 0) return false;
+  if (name !== basename(name)) return false;          // 拒绝 ../x、sub/x、/abs 等
+  if (name.startsWith('.')) return false;             // 排除 .gitignore 等隐藏文件
+  return SYNC_EXTS.has(extname(name).toLowerCase());
+}
+
+export function readProject(gameDir) {
+  const out = {};
+  for (const name of readdirSync(gameDir)) {
+    if (SKIP_DIRS.has(name)) continue;
+    if (!isSyncable(name)) continue;
+    const p = join(gameDir, name);
+    if (!statSync(p).isFile()) continue;              // 跳过同名目录
+    out[name] = readFileSync(p, 'utf8');
+  }
+  return out;
+}
+
+// 让 pxt.json 的 files 与实际同步的文件一致：剔除不同步的条目（如 main.py），
+// 否则磁盘上会出现"声明了却不存在"的悬空引用。
+function sanitizePxtJson(content) {
+  try {
+    const j = JSON.parse(content);
+    if (Array.isArray(j.files)) {
+      const cleaned = j.files.filter((f) => isSyncable(f));
+      if (cleaned.length !== j.files.length) {
+        j.files = cleaned;
+        return JSON.stringify(j, null, 4) + '\n';
+      }
+    }
+  } catch { /* 非法 JSON：原样写回，不阻断 */ }
+  return content;
+}
+
+export function writeProject(gameDir, files, opts = {}) {
+  const written = [];
+  for (const name of Object.keys(files || {})) {
+    if (!isSyncable(name)) continue;
+    let content = files[name] ?? '';
+    if (name === 'pxt.json') content = sanitizePxtJson(content);
+    opts.beforeWrite?.();
+    writeFileSync(join(gameDir, name), content, 'utf8');
+    written.push(name);
+  }
+  return written;
+}

package/src/rules/agents.md

@@ -0,0 +1,12 @@
+# 给 AI 的项目规则：MakeCode Arcade 游戏
+
+- 游戏代码只写在 `game/main.ts`；资源（精灵/地图，4-bit 16 色）走 `game/assets.json`，不要内联大图到 JS。
+- 这是**纯 TypeScript 项目**：`game/` 里**不要**有 `main.blocks`，`pxt.json` 的 `files` 也不要列它（否则官方编辑器会开在空白积木视图，看不到你的代码）。
+- 改完代码后 `aca dev` 的页面会自动刷新预览；无需手动操作。
+- **精灵**用内联 `img\`\``，AI 直接写。
+- **地图**有两条可靠路线，二选一（细节见 `reference/arcade-api.md` 第7节 / `reference/pitfalls.md` 坑5）：
+  1. 命名地图 `tiles.setTilemap(tilemap\`level\`)`——编辑器自动建空地图，人在网页里画好后同步回磁盘；
+  2. `tiles.createTilemap(...)` + **内置图块**（如 `sprites.castle.tileGrass1`），图块用自带图库。
+  - ❌ **千万别**把内联 `img` 当图块塞进 `createTilemap`——会让编辑器崩溃（已实测）。
+- 不确定图块/API 名字时查 `reference/` 或编辑器图库，不要臆造不存在的 arcade API。
+- 不要清空 `assets.json`（必须是合法 JSON，空资源写 `{}`），也不要手写 `tilemap.g.jres`（编辑器生成）。

package/src/rules/claude.md

@@ -0,0 +1,12 @@
+# 给 AI 的项目规则：MakeCode Arcade 游戏
+
+- 游戏代码只写在 `game/main.ts`；资源（精灵/地图，4-bit 16 色）走 `game/assets.json`，不要内联大图到 JS。
+- 这是**纯 TypeScript 项目**：`game/` 里**不要**有 `main.blocks`，`pxt.json` 的 `files` 也不要列它（否则官方编辑器会开在空白积木视图，看不到你的代码）。
+- 改完代码后 `aca dev` 的页面会自动刷新预览；无需手动操作。
+- **精灵**用内联 `img\`\``，AI 直接写。
+- **地图**有两条可靠路线，二选一（细节见 `reference/arcade-api.md` 第7节 / `reference/pitfalls.md` 坑5）：
+  1. 命名地图 `tiles.setTilemap(tilemap\`level\`)`——编辑器自动建空地图，人在网页里画好后同步回磁盘；
+  2. `tiles.createTilemap(...)` + **内置图块**（如 `sprites.castle.tileGrass1`），图块用自带图库。
+  - ❌ **千万别**把内联 `img` 当图块塞进 `createTilemap`——会让编辑器崩溃（已实测）。
+- 不确定图块/API 名字时查 `reference/` 或编辑器图库，不要臆造不存在的 arcade API。
+- 不要清空 `assets.json`（必须是合法 JSON，空资源写 `{}`），也不要手写 `tilemap.g.jres`（编辑器生成）。

package/src/rules/project_rules.md

@@ -0,0 +1,12 @@
+# 给 AI 的项目规则：MakeCode Arcade 游戏
+
+- 游戏代码只写在 `game/main.ts`；资源（精灵/地图，4-bit 16 色）走 `game/assets.json`，不要内联大图到 JS。
+- 这是**纯 TypeScript 项目**：`game/` 里**不要**有 `main.blocks`，`pxt.json` 的 `files` 也不要列它（否则官方编辑器会开在空白积木视图，看不到你的代码）。
+- 改完代码后 `aca dev` 的页面会自动刷新预览；无需手动操作。
+- **精灵**用内联 `img\`\``，AI 直接写。
+- **地图**有两条可靠路线，二选一（细节见 `reference/arcade-api.md` 第7节 / `reference/pitfalls.md` 坑5）：
+  1. 命名地图 `tiles.setTilemap(tilemap\`level\`)`——编辑器自动建空地图，人在网页里画好后同步回磁盘；
+  2. `tiles.createTilemap(...)` + **内置图块**（如 `sprites.castle.tileGrass1`），图块用自带图库。
+  - ❌ **千万别**把内联 `img` 当图块塞进 `createTilemap`——会让编辑器崩溃（已实测）。
+- 不确定图块/API 名字时查 `reference/` 或编辑器图库，不要臆造不存在的 arcade API。
+- 不要清空 `assets.json`（必须是合法 JSON，空资源写 `{}`），也不要手写 `tilemap.g.jres`（编辑器生成）。

package/src/studio/server.js

@@ -0,0 +1,67 @@
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { readProject, writeProject } from '../project-io.js';
+import { createWatcher } from './watcher.js';
+
+export function startStudio({ gameDir, port = 0, hostHtmlPath }) {
+  const clients = new Set();
+  const watcher = createWatcher(gameDir, () => {
+    for (const res of clients) res.write('data: changed\n\n');
+  });
+
+  const server = createServer((req, res) => {
+    const url = req.url.split('?')[0];
+    if (req.method === 'GET' && url === '/') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(readFileSync(hostHtmlPath));
+    } else if (req.method === 'GET' && url === '/api/project') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ files: readProject(gameDir) }));
+    } else if (req.method === 'POST' && url === '/api/save') {
+      let body = '';
+      req.on('data', (c) => (body += c));
+      req.on('end', () => {
+        try {
+          const { files } = JSON.parse(body || '{}');
+          watcher.pause(600);
+          const written = writeProject(gameDir, files);
+          const incoming = Object.keys(files || {});
+          const dropped = incoming.filter((f) => !written.includes(f));
+          console.log(`[save] 收到 ${incoming.length} 文件，落盘 ${written.length}`);
+          if (dropped.length) console.warn(`[save] ⚠️ 未同步（扩展不支持/不安全）: ${dropped.join(', ')}`);
+          res.writeHead(200, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ success: true }));
+        } catch (e) {
+          res.writeHead(500); res.end(String(e));
+        }
+      });
+    } else if (req.method === 'GET' && url === '/events') {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+      });
+      res.write('retry: 1000\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+    } else {
+      res.writeHead(404); res.end('Not Found');
+    }
+  });
+
+  return new Promise((resolve) => {
+    server.listen(port, '127.0.0.1', () => {
+      const { port: p } = server.address();
+      resolve({
+        url: `http://127.0.0.1:${p}`,
+        port: p,
+        async close() {
+          for (const r of clients) r.end();
+          await watcher.close();
+          server.closeAllConnections?.();
+          server.close();
+        },
+      });
+    });
+  });
+}

package/src/studio/watcher.js

@@ -0,0 +1,17 @@
+import chokidar from 'chokidar';
+
+export function createWatcher(gameDir, onChange) {
+  let pausedUntil = 0;
+  let timer = null;
+  const watcher = chokidar.watch(gameDir, { ignoreInitial: true });
+  const fire = () => {
+    if (Date.now() < pausedUntil) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => { if (Date.now() >= pausedUntil) onChange(); }, 200);
+  };
+  watcher.on('add', fire).on('change', fire);
+  return {
+    pause(ms) { pausedUntil = Date.now() + ms; },
+    async close() { clearTimeout(timer); await watcher.close(); },
+  };
+}

package/src/template/game/README.md

@@ -0,0 +1,2 @@
+# Arcade Game
+由 arcade-ai 脚手架生成。用 AI 修改 `main.ts`，`aca dev` 实时预览。

package/src/template/game/assets.json

@@ -0,0 +1 @@
+{}

package/src/template/game/main.ts

@@ -0,0 +1,24 @@
+// 玩家精灵：内联 img（AI 直接写，编辑器里可点开可视化微调）
+let player = sprites.create(img`
+. . . . . . f f f f . . . . . .
+. . . . . f f f f f f . . . . .
+. . . . f f e e e e f f . . . .
+. . . . f e f e e f e f . . . .
+. . . . f e e e e e e f . . . .
+. . . . f e f e e f e f . . . .
+. . . . f e f f f f e f . . . .
+. . . . f e e e e e e f . . . .
+. . . . . f f f f f f . . . . .
+. . . . . . f f f f . . . . . .
+. . . . . f f . . f f . . . . .
+. . . . . . . . . . . . . . . .
+`, SpriteKind.Player)
+controller.moveSprite(player)
+player.setStayInScreen(true)
+
+// 地图：引用命名地图 `level`。
+// 编辑器首次打开会自动创建一张空地图——你在网页里点开地图编辑器画好后，
+// 会自动同步回本地磁盘（tilemap.g.ts / tilemap.g.jres），并随游戏运行。
+// 画格子时可直接用内置图块库（如 sprites.castle.tileGrass1），无需手画。
+tiles.setTilemap(tilemap`level`)
+scene.cameraFollowSprite(player)

package/src/template/game/pxt.json

@@ -0,0 +1,18 @@
+{
+    "name": "arcade-game",
+    "version": "0.0.1",
+    "description": "",
+    "dependencies": {
+        "device": "*"
+    },
+    "files": [
+        "main.ts",
+        "README.md",
+        "assets.json"
+    ],
+    "supportedTargets": [
+        "arcade"
+    ],
+    "preferredEditor": "tsprj",
+    "languageRestriction": "javascript-only"
+}

package/src/template/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "arcade-game-project",
+  "private": true,
+  "type": "module",
+  "scripts": { "dev": "aca dev" },
+  "devDependencies": { "arcade-ai": "^0.1.0" }
+}