---
name: playcraft-remix-workflow
description: Remix 工程流程（主题/metadata/schema/新功能）。配置读写须落实在可执行命令：在项目根运行 playcraft prefab（list/describe/set/switch/…）；详见文内「CLI 对照表」。可手改 theme.data.json5 作备选。与 playcraft-prefab 同一套 CLI。
disable: false
compatibility: agent
---

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你指导在 **Remix 工程**里做玩法变体：主题与协议在仓库中的位置、如何向用户提问、何时扩展 schema、何时改源码。

  **与 playcraft-prefab**：二者共用同一套 **`playcraft prefab` CLI**（命令清单以 **playcraft-prefab** 技能为准）。本技能补充 **何时、为何** 在 Remix 里执行这些命令；**不要**只写「用 list」而不写 **`playcraft prefab list`**。

  - **本技能负责**：选/复制主题、改 `src/theme/index.ts`、读/写 `theme.metadata.md`、**编辑 `theme.schema.json5`**、新功能设计协议、改游戏源码。
  - **配置值读写（已有协议）**：在项目根执行 **`playcraft prefab …`**（优先）；CLI 不便时可手改 `src/theme/<主题>/theme.data.json5`（须符合 schema）。PlayCanvas 工程用 `playcraft prefab scenes` 与 `--variant <sceneId>`。

  ### CLI 与 Remix 步骤对照（均在仓库根目录执行）

  | Remix 步骤 | 建议命令（External 主题工程） |
  |------------|-------------------------------|
  | 确认有哪些主题 / 当前活跃 | `playcraft prefab themes --json` |
  | 用户选定主题后对齐 CLI 上下文 | `playcraft prefab switch <themeId>` **或** 所有后续命令加 `--variant <themeId>` |
  | 全局摸清 prefab 与启用情况 | `playcraft prefab list --json`（读 `.summary`、`.page`，注意 `.page.hasMore`） |
  | 按关键词找字段 | `playcraft prefab search '<regex>' --json` |
  | 看某 key 约束与 `guide` | `playcraft prefab describe <key> --json` |
  | 看相对默认值改动了什么 | `playcraft prefab diff --json` |
  | 改一个字段 | `playcraft prefab set <key> <field> <value>` |
  | 一次改多字段 | `playcraft prefab set-batch --file batch.json`（或 stdin） |
  | 整块启用/关闭 | `playcraft prefab enable <key>` / `disable <key>` |
  | PlayCanvas：有哪些场景 | `playcraft prefab scenes --json` |

  `theme.data.json5` 即 CLI 对当前主题写入的配置落盘文件；手改该文件与 CLI 写入应二选一或谨慎合并，避免冲突。

  ## 介绍

  指导修改当前可玩广告工程；产物是基于某一 **theme** 配置呈现的游戏。

  ## 变体原则

  玩法由配置项组合而成，尽量配置化以实现复用与组装。目录见下；**所有 prefab 子命令的完整列表、分页与过滤选项以 playcraft-prefab 技能为准**，本处只固定 **Remix 与 CLI 的衔接**。

  ## 目录结构

  ```
  ├── assets ← 公共资源
  ├── SKILL
  │   ├── SKILL.md                    ← 若存在则读取，了解当前游戏专用技能
  ├── src
  │   ├── theme
  │   │   ├── theme.schema.json5      ← 全局唯一协议：所有 prefab 键与字段定义
  │   │   ├── theme.metadata.md       ← 各主题玩法摘要（# 主题名 / 玩法要点）
  │   │   ├── index.ts                ← 仅引用一个主题目录，如 export { default } from "./draft"
  │   │   ├── draft/
  │   │   │   ├── theme.data.json5    ← 当前主题最终配置（CLI 优先写入；亦可手改）
  │   │   │   ├── assets/
  │   │   └── <其他主题目录>/
  │   │       └── theme.data.json5
  ...
  ```

  ## 初始化流程

  ### 问题 1：选择主题

  - 读取 `src/theme/theme.metadata.md`，向用户展示可选主题与玩法描述。
  - 选项：① 使用 draft；② 切换到已有主题名；③ 复制某主题为新目录并命名。
  - 用户确认后：修改 `src/theme/index.ts` 指向选定主题。
  - **之后改配置值（必绑 CLI）**：先执行 `playcraft prefab switch <themeId>`（会改 `index.ts` 与 CLI 默认主题一致），**或** 不改 index、仅对每条命令加 `--variant <themeId>`。再跑 `playcraft prefab list --json` 确认上下文。

  ### 问题 2：修改需求

  - **摸清能力（先 CLI）**：`playcraft prefab list --json` → `jq '.summary'`；按需 `playcraft prefab search '<关键词>' --json`、`playcraft prefab describe <key> --json`。仍可读 `theme.schema.json5` 补细节，但**不要**只靠通读大文件代替上述命令。
  - 询问用户今日目标：已有协议内变体 → **场景 1**；新协议 → **场景 2**。

  ## 变体流程（用户提出具体需求后）

  下文以 `src/theme/draft` 为例说明路径；其他主题将 `draft` 换成对应目录名，或对每条命令使用 `playcraft prefab … --variant <themeId>`。

  ### 已有配置项：优先 CLI，可选手改

  - **首选**：上表所列 **`playcraft prefab …`** 全名；机器解析时**加 `--json`**。
  - **亦可**：直接编辑 `theme.data.json5`（须符合 `theme.schema.json5`、JSON5 合法）。
  - 协议要求其他工具/技能（生图、路径资源等）时，按协议执行。

  ### 场景 1：需求落在已有协议内

  **默认命令序列**：`playcraft prefab describe <key> --json` → `playcraft prefab set <key> <field> <value>`（或多字段 `set-batch`）→ `playcraft prefab get <key> --json` 或 `diff --json` 复核。CLI 不便时再手改 `theme.data.json5`。

  ### 场景 2：新增功能（协议中尚不存在）

  先结合源码与 schema 注释判断是否允许实现（部分能力可能以库形式封闭并在 schema 中注明）。

  若可实现，以配置优先，典型步骤：

  1. **设计协议项**：与用户澄清细节；将新块写入 **唯一** 的 `src/theme/theme.schema.json5`（JSON Schema + 必要时 `xplatform`，参考 `references/xplatform.schema.json5`）。新 object 建议含 **`enable`，且默认 `false`**，避免旧主题被默认打开。
  2. **写入配置值**：协议落地后执行 **`playcraft prefab enable <key>`**，再 **`playcraft prefab describe <key> --json`**，然后 **`playcraft prefab set …`** / **`playcraft prefab set-batch …`** 填默认值；亦可手改 `theme.data.json5`。更新 `theme.metadata.md`，未实现前可标【实现中】。
  3. **实现源码**：按新协议接入游戏逻辑；验收通过后更新 `theme.metadata.md`，去掉【实现中】。

## 我做什么

- Remix 流程：主题选择、metadata、目录与 schema 扩展、新功能实现节奏
- 在流程中嵌入 **完整 `playcraft prefab …` 命令**；细节与选项见 **playcraft-prefab** 技能

## 何时用我

- 用户要「换主题 / 复制主题 / 理解这个游戏能改什么」
- 需要改 **theme.schema.json5** 或更新 **theme.metadata.md**
- 新玩法从零设计协议并实现代码

## 工作流

1. **read** — `theme.metadata.md`；必要时 `theme.schema.json5`
2. **bash / 用户** — 确认主题；**bash** — `playcraft prefab switch …` 或统一 `--variant`
3. **bash** — `playcraft prefab list|search|describe|set|…`（完整命令见上表与 playcraft-prefab）
4. **read / bash** — 场景 2：改 `theme.schema.json5`、`theme.metadata.md`、源码
5. **terminate** — 简要汇报变更与待验收点