# PlayCraft Skills 总览

本目录统一管理 PlayCraft 的两类 skill：

| 目录 | 类型 | 说明 |
|-----|-----|-----|
| `skills/` | **Atom Skills** | Remix 组装单元（代码/资源/配置）。每个 skill 有 `manifest.json` + `SKILL.md` + `ref/`，命名规范 `<name>.<bundleType>`，如 `phaser.aicomponent`、`win_result_panel.aiimage` |
| `platform-skills/` | **Platform Skills** | AI Agent 使用 PlayCraft 平台的操作指南（生图、生音频、发布等）。symlink → `packages/backend/src/features/agent/skills/`，修改统一在 backend 进行 |

> **图谱关系**（节点边、权重、组装引擎）后续在 `docs/recommend/` 中单独定义。

---

## 命名规范（必须遵守）

### Atom Skills — `<name>.<bundleType>`

**特征：**
- 目录名格式：`<snake_case_name>.<bundleType>`（如 `grid_board_layout.aicomponent`、`bg_music.aiaudio`）
- 必须有 `manifest.json`（声明 atomId、category、tags、bindingRoles、scaffold 等）
- 必须有 `SKILL.md`（使用说明）
- 通常有 `ref/` 目录（蒸馏自真实项目的参考代码/资源文件）
- **代表"是什么"**：一个可组装进 Remix 的具体素材或代码单元

```
grid_board_layout.aicomponent/   ← Atom Skill
  ├── manifest.json
  ├── SKILL.md
  └── ref/
      ├── BoardLayout.ts
      └── BoardLayout3D.ts
```

### Platform Tools — `playcraft-<name>`

**特征：**
- 目录名格式：`playcraft-<kebab-case-name>`（如 `playcraft-image-generation`、`playcraft-skill-recommender`）
- **只有 `SKILL.md`，没有 `manifest.json`**（不参与 Atom Graph，不被 recommend API 索引）
- **代表"怎么做"**：描述 Agent 如何使用 PlayCraft CLI / API 完成某项操作
- 被 Agent Skills Loader 发现，在 Agent Session 初始化时加载

```
playcraft-image-generation/      ← Platform Tool
  └── SKILL.md                   ← 仅此一个文件
```

### 判断规则

| 问题 | 是 → | 否 → |
|------|------|------|
| 它是一个可以被 scaffold 进项目的代码/资源单元吗？ | Atom Skill（`<name>.<bundleType>`） | → 下一条 |
| 它描述的是 Agent 如何使用平台工具/CLI 的操作流程吗？ | Platform Tool（`playcraft-<name>`） | 不属于 skills 目录 |

**常见错误：**
- ❌ 把平台操作指南做成 `manifest.json` + `SKILL.md`（混淆 Atom 和 Platform Tool）
- ❌ 用 `<name>.aicomponent` 命名平台工具（如 `skill_recommender.aicomponent`）
- ❌ 给 Platform Tool 创建 `manifest.json`（会被错误地当作 Atom 索引）

---

## Platform Skills 列表

| Skill | 说明 |
|-------|-----|
| `playcraft-image-generation` | AI 生图（Google Gemini / IEGG LiteLLM），直接写入文件 |
| `playcraft-audio-generation` | AI 生音频（BGM + SFX），体积预算管理 |
| `playcraft-image-processing` | 图片后处理（缩放/裁剪/格式转换/合成）|
| `playcraft-sprite-sheet` | 多图合并精灵图，输出 PNG + JSON 帧坐标 |
| `playcraft-sprite-remix` | 精灵图拆解 + 逐帧 AI 重绘 + 重组装 |
| `sound-effects` | 通过 playcraft CLI 生成音效（SFX）|
| `playcraft-asset-management` | 查看/替换项目素材 |
| `playcraft-code-editor` | 读取/修改项目脚本和配置 |
| `playcraft-remix-workflow` | Remix 工程流程（主题/metadata/schema）|
| `playcraft-create-remix` | 创建新 Remix 变体 |
| `playcraft-build` | 在 sandbox 执行 `npm run build` |
| `playcraft-save` | 将 sandbox 代码 sync → commit → push |
| `playcraft-deploy` | 组合操作：build → save → publish |
| `playcraft-project-management` | 查看变体、浏览推荐 Remix |
| `playcraft-platform-intro` | PlayCraft 平台介绍 |
| `playcraft-prefab` | playcraft prefab CLI 用法 |
| `playcraft-skill-recommender` | 构建项目前的 Skill 推荐与脚手架（`playcraft skills match/list/scaffold`） |

---

## bundleType 说明

| bundleType | 含义 | category 可选值 |
|-----------|-----|--------------|
| `aicomponent` | 通用代码 skill（引擎/布局/场景/UI/状态/构建/工具） | engine / layout / scene / state / component / build / util |
| `aigameplay` | 玩法逻辑（PGS schema + 相关代码模块） | gameplay |
| `aivalidator` | 校验/测试/质量门禁（测试脚本 + 校验报告） | validator |
| `aiimage` | 图片资源 | visual |
| `aiaudio` | 音频资源 | audio |
| `aiconfig` | 配置封包 | config |

---

## Skills 分层清单

### 1. 引擎层（category: engine）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `phaser.aicomponent` | Phaser 3 引擎 + **完整空项目骨架**（7 个文件：HTML/CSS/TS 入口/tsconfig/globals/StartGame/GameConfig），安装后即可 `pnpm dev` 运行 | `gameEngine` |

### 2. 构建层（category: build）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `playable_scripts_build.aicomponent` | 试玩广告多渠道构建管线（@tencent/playable-scripts） | `buildPipeline` |
| `theme_switcher_build.aicomponent` | 主题入口 `src/theme/index.ts`，构建时切换主题 | — |

### 3. 布局层（category: layout）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `responsive_2d_layout.aicomponent` | **框架无关布局规范**（uiScale/vScale/不变量）+ 默认 Phaser 参考实现 `ref/UiLayout.ts` | `responsiveLayout` |
| `playable_hud_layout.aicomponent` | **HUD 屏幕分区**（顶/底/棋盘可用高度、z-order 合同），无代码 scaffold | `playableHudLayout` |
| `playable_end_screen_layout.aicomponent` | **结算全屏布局**（遮罩、安全区、CTA 锚点），无代码 scaffold | `playableEndScreenLayout` |
| `playable_guidance_layer.aicomponent` | **指引层布局**（挖洞、手指、与 HUD/结算 depth），无代码 scaffold | `playableGuidanceLayout` |
| `grid_board_layout.aicomponent` | 可变尺寸格子棋盘布局（格子大小/偏移/缩放边界） | `gridBoardLayout` |

### 4. 场景层（category: scene）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `phaser_scene_lifecycle.aicomponent` | Phaser 双场景架构骨架（Preloader → Game） | `sceneLifecycle` |
| `preloader_scene.aicomponent` | 预加载场景（加载资产 + Loading UI + sdk.start） | `preloaderScene` |
| `game_scene.aicomponent` | 主游戏场景（协调所有子系统） | `gameMainScene` |

### 5. 状态层（category: state）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `settings_state.aicomponent` | 用户设置（音乐/音效开关/拖拽速度） | `userSettings` |
| `theme_state.aicomponent` | 主题配置（路径颜色/箭头风格/UI 颜色） | `themeManager` |
| `level_state.aicomponent` | 关卡进度（当前索引/关卡数据加载） | `levelProgress` |
| `run_context_state.aicomponent` | 运行上下文（normal/test 模式区分） | `runContext` |

### 6. 玩法层（bundleType: aigameplay / category: gameplay + component）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `path_elimination_rules.aigameplay` | 路径消除玩法 PGS（核心规则 + testCases）；**Remix 的 entry 节点** | `gameplayRule` |
| `pick_and_match_rules.aigameplay` | 拾取三消玩法 PGS（棋盘拾取→篮子→三同消除）；支持多层堆叠、同类聚合、篮子溢出 | `gameplayRule` |
| `arrow_path_data_format.aicomponent` | RawLevelJson ↔ ParsedLevel 类型定义和解析器 | `levelDataFormat` |
| `path_renderer.aicomponent` | 棋盘路径批量渲染器（折线 + 箭头头部） | `pathBatchRenderer` |
| `path_animation.aicomponent` | 路径动画（消除滑出/阻挡震动/胜利钻石） | `pathAnimationDirector` |
| `path_input_handler.aicomponent` | 棋盘输入（命中检测/拖拽棋盘/双指缩放） | `boardInputHandler` |
| `level_lifecycle.aicomponent` | 关卡生命周期（扣命/超时/胜利/进关） | `levelLifecycleController` |

> 旧的 `arrow_escape_core.aigameplay`（描述"放箭头引导角色"玩法）已被 `path_elimination_rules.aigameplay`（路径消除）替代并删除。

### 7. UI 组件层（category: component）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `loading_screen.aicomponent` | Loading 页面 UI（logo/标题/星评/进度 dots） | `loadingScreen` |
| `top_ui_bar.aicomponent` | 顶部 UI 条容器 + `GAME_TOP_UI_BAR_HEIGHT` 常量 | `topUiBar` |
| `bottom_ui_bar.aicomponent` | 底部 UI 条占位 + `GAME_BOTTOM_UI_BAR_HEIGHT`（与 `GameConfig` 同源） | `bottomUiBar` |
| `countdown_timer.aicomponent` | 倒计时显示器（七段数码管风格） | `countdownTimer` |
| `heart_lives.aicomponent` | 心形生命值指示器 | `livesIndicator` |
| `combo_display.aicomponent` | 连击计数 UI + 倒计时进度环 | `comboDisplay` |
| `combo_praise_text.aicomponent` | 连击表扬文案弹出动画（GOOD → LEGENDARY） | `comboPraiseText` |
| `progress_bar.aicomponent` | 关卡进度条（已消除/总路径） | `progressBar` |
| `download_button.aicomponent` | 下载 CTA 按钮（呼吸动画 + sdk.install） | `downloadCta` |
| `game_over_panel.aicomponent` | 胜利/失败结果面板（半透明遮罩 + 结果图 + CTA） | `gameOverDialog` |
| `tutorial_overlay.aicomponent` | 新手引导浮层（前两关步进式操作指导） | `tutorialOverlay` |
| `digit_renderer.aicomponent` | 七段数码管数字渲染器（基础组件） | `digitGlyphRenderer` |

### 8. 工具层（category: util）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `sound_utils.aicomponent` | `safePlaySound()` 音频安全播放工具函数 | `audioPlayHelper` |

### 8.5 校验层（bundleType: aivalidator，category: validator）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `gameplay_unit_test.aivalidator` | 玩法逻辑单元测试（Vitest） | `testFramework` |
| `level_solvability_validator.aivalidator` | 关卡可解性验证器 | `levelValidator` |
| `level_data_validator.aivalidator` | 关卡数据格式校验器 | `dataValidator` |

> `aivalidator` 与 `aicomponent` 的区别：aivalidator 的核心目的是**检查/验证**已有代码或数据的质量，不产出可部署的功能代码。

### 9. 图片资源层（bundleType: aiimage，category: visual）

| atomId | 对应文件 | bindingRoles |
|--------|---------|-------------|
| `direction_arrow_sprite.aiimage`（已有） | `arrows.png` | `directionalIndicator` |
| `playable_app_logo.aiimage` | `logo.webp` | `appLogo` |
| `win_result_panel.aiimage` | `win.webp` | `successFeedbackPanel` |
| `lose_result_panel.aiimage` | `lose.webp` | `failFeedbackPanel` |
| `nomove_hint_overlay.aiimage` | `nomove_hint.webp` | `dangerFlashOverlay` |
| `figer_icon.aiimage` | `figer.webp` | `tutorialPointer` |
| `time_icon.aiimage` | `time.webp` | `clockIcon` |
| `win_dot.aiimage` | `win_dot.webp` | `winParticleAsset` |
| `normal_dot.aiimage` | `normal_dot.webp` | `normalParticleAsset` |

> `directionalIndicator` 同类替代簇：`direction_arrow_sprite.aiimage`（箭头）可替换为车、手指、赛博风等变体。

### 10. 音频资源层（bundleType: aiaudio，category: audio）

| atomId | 对应文件 | bindingRoles |
|--------|---------|-------------|
| `cheerful_ukulele.aiaudio`（已有） | — | `bgMusic` |
| `calm_piano.aiaudio`（已有） | — | `bgMusic` |
| `energetic_electronic.aiaudio`（已有） | — | `bgMusic` |
| `bg_music.aiaudio` | `bg.mp3` | `bgMusic` |
| `click_sfx.aiaudio` | `click.mp3` | `sfxClick` |
| `appear_sfx.aiaudio` | `appear.mp3` | `sfxAppear` |
| `success_sfx.aiaudio` | `success.mp3` | `sfxSuccess` |
| `fail_sfx.aiaudio` | `fail.mp3` | `sfxFail` |
| `lose_sfx.aiaudio` | `lose.mp3` | `sfxLose` |
| `mistake_sfx.aiaudio` | `mistake.mp3` | `sfxMistake` |
| `win_anim_sfx.aiaudio` | `win_anim.mp3` | `sfxWinAnim` |
| `arrow_move_error_sfx.aiaudio` | `arrow_move_error.mp3` | `sfxArrowMoveError` |
| `button_click_sfx.aiaudio` | `button_click.mp3` | `sfxButtonClick` |

> `bgMusic` 同类替代簇：`bg_music` / `cheerful_ukulele` / `calm_piano` / `energetic_electronic`

### 11. 配置层（bundleType: aiconfig，category: config）

| atomId | 描述 | bindingRoles |
|--------|-----|-------------|
| `level_data_pack.aiconfig` | `RawLevelJson[]` 关卡数据集 | `levelDataPack` |
| `theme_variant.aiconfig` | 主题变体配置（ThemeVariantConfig 实例） | `themeVariantConfig` |
| `app_metadata.aiconfig` | Loading 页面文案（标题/描述/评分） | `appMetadata` |
| `easy_to_hard.aiconfig`（已有） | 先易后难难度曲线 | `gameConfig` |
| `wave_difficulty.aiconfig`（已有） | 波浪难度曲线 | `gameConfig` |
| `score_goal.aiconfig`（已有） | 分数目标配置 | `gameConfig` |
| `time_clear_goal.aiconfig`（已有） | 限时通关目标配置 | `gameConfig` |

---

## 继承自 match3 的通用素材

| atomId | 说明 |
|--------|-----|
| `match3_core.aigameplay` | match3 玩法规则，暂未改动 |
| `forest/ocean/castle/desert.aiimage` | 背景图，可作 `boardBackgroundTexture` 候选 |
| `fruit_tile/jewel_tile/candy_tile.aiimage` | match3 / pick_and_match 可用的瓦片贴图集 |

---

## bindingRoles 语义标签完整列表

语义标签用于：
1. 声明该 skill 的类别（写在 `bindingRoles` 字段）
2. 软槽位候选召回（其他 skill 的 `imports[].matchBindingRoles` 引用）

完整枚举见 [`packages/common/src/recommend/atom-graph/types.ts`](../common/src/recommend/atom-graph/types.ts) 中的 `AtomBindingRole` 类型。

---

## 文件结构

```
packages/skills/
├── skills/
│   ├── phaser.aicomponent/
│   │   ├── manifest.json     # 类型、标签、bindingRoles、scaffold、imports、exports
│   │   ├── SKILL.md          # 使用说明、Scaffold/Imports/Skill Definition
│   │   └── ref/              # 蒸馏自真实 remix 的源文件
│   ├── path_elimination_rules.aigameplay/
│   │   ├── manifest.json
│   │   ├── SKILL.md
│   │   └── ref/
│   │       └── pgs-schema.json   # 完整 PGS 规则描述
│   └── ...（共 ~68 个 skill）
└── test/
    └── atom-skills.test.ts   # 完整性校验
```

---

## 双 Skill 系统共存设计

PlayCraft 同时支持两套互补的 Skill 系统，两者职责不同、互不干扰。

```
.claude/skills/                        ← Claude Code 原生发现路径
  ├── playcraft-workflow/               ← 静态桥接 skill（随项目模板分发）
  │   └── SKILL.md                      工作流入口，引导 agent 使用 playcraft skills match
  ├── playcraft-skill-recommender → …   ← 软连接（playcraft create 自动创建）
  ├── playcraft-image-generation  → …   ← 软连接（指向 node_modules/@playcraft/skills）
  ├── playcraft-audio-generation  → …
  └── …（其余 Platform Tool 软连接）

node_modules/@playcraft/skills/skills/ ← DAG 推荐引擎的 Atom 索引源
  ├── phaser.aicomponent/
  ├── match3_core.aigameplay/
  ├── gameplay_balance_check.aivalidator/
  └── …（134+ Atom Skills）
```

### 分层策略

| 层 | 内容 | 发现方式 | 职责 |
|---|---|---|---|
| **Claude Code Skills** | 静态桥接 skill + Platform Tool 软连接 | IDE 自动扫描 `.claude/skills/` | HOW：平台工具用法 |
| **DAG Atom Skills** | 134+ `.aiimage/.aiaudio/.aicomponent/.aigameplay/.aiconfig/.aivalidator` | `playcraft skills match` CLI 推荐 | WHAT：游戏积木 |

### 为什么不把 Atom Skills 放进 `.claude/skills/`

1. **数量问题**：134+ Atom Skills 会淹没 Claude Code 的 description 匹配机制
2. **格式差异**：Atom Skills 的 SKILL.md 包含 DAG 元数据（`triggers`、`prompt_extension`、`tools`），Claude Code 不解析这些字段
3. **职责分离**：Atom Skills 通过 `playcraft skills match` 按引擎+意图精准推荐，比 IDE 文本匹配更准确
4. **发现机制**：DAG 推荐系统可做依赖图遍历、打分排序，远优于 IDE 的关键词匹配

### 桥接 skill（`playcraft-workflow`）的作用

`packages/cli/project-template/.claude/skills/playcraft-workflow/SKILL.md` 是静态提交到模板的唯一 Atom 入口：
- Claude Code 自动注入（description 含构建相关关键词）
- 告知 agent "开始任何游戏项目前先运行 `playcraft skills match`"
- 解释如何阅读 Atom Skill 的 `SKILL.md`（`prompt_extension` / `tools` 字段）

### 软连接生命周期

```
playcraft create my-game
  → 复制 project-template（含静态 playcraft-workflow）
  → 在 .claude/skills/ 创建 playcraft-* 软连接
    ├── 若 monorepo dev 路径可解析 → 绝对路径软连接（当下即用）
    └── 否则 → 相对路径软连接（指向 node_modules，npm install 后激活）

npm install
  → @playcraft/skills 安装到 node_modules
  → 相对路径软连接自动解析生效
```

软连接由 `playcraft create` 生成，在 `.gitignore` 中排除，不提交到项目 Git 仓库。