---
name: playcraft-prefab
description: playcraft prefab CLI 全量用法（须带 playcraft 前缀）。与 playcraft-remix-workflow 共用同一 CLI；该技能的「CLI 与 Remix 步骤对照表」与本技能 S1–S4 一致。选主题/schema/metadata 见 remix技能。
compatibility: agent
---

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你在项目根（或 `--project-dir`）执行命令时**必须写全**：**`playcraft prefab …`**（不要省略 `playcraft`）。

  **与 playcraft-remix-workflow**：Remix 流程里「何时跑 CLI」见该技能中的 **CLI 与 Remix 步骤对照表**；**子命令、分页、过滤、JSON 字段** 以本技能为准。对方负责 **index.ts / theme.schema.json5 / theme.metadata.md / 源码**；你负责 **协议已有后的 list/describe/set/switch/…**。

  **修改原则**：**优先 CLI**（校验、路径、`--json` 的 `summary`/`page`/`guide`）；环境不便或批量编辑更合适时，**允许直接编辑** 当前主题的 `theme.data.json5`（须 JSON5 合法且符合 schema）。PlayCanvas 项目同理：优先 CLI，必要时手改 GameConfig。

  **变体一行话**：External 里 variant = 主题目录名，数据在 `src/theme/<id>/theme.data.json5`；PlayCanvas 里 variant = 场景 id，见 `prefab scenes`。存在 `theme.schema.json5` 即按 External 检测；存在 `assets/DefaultGame.json` 即 PlayCanvas。

  ---

  ### S1：首次摸清「能改什么」（控制上下文）

  1. `playcraft prefab variants`（或 `themes` / `scenes`）确认变体。
  2. `playcraft prefab list --json` → 读 **`summary`**（`total` / `enabled` / `disabled` / `changed`）和 **`page`**；有 **`page.hasMore`** 就继续 `--offset` 翻页，**不要假定一页即全集**。
  3. 缩小范围：`--match <regex>`（默认忽略大小写；`--match-case` 区分）、`--used-only` / `--unused-only` / `--changed-only`。
  4. 找字段名或说明：`playcraft prefab search <regex> --json`。
  5. 看约束与示例：`playcraft prefab describe <key> --json`（含 **`guide`**）；多 key 时用 `describe --all --json --limit N --offset M`（可加 `--match`）。

  ### S2：只改已有字段（数值 / 开关 / dotpath）

  1. `playcraft prefab describe <key> --json` 确认类型与范围。
  2. 可选：`playcraft prefab diff --json` 看当前与默认值差异。
  3. 单字段：`playcraft prefab set <key> <field> <value>`；多字段：`set-batch`（`--file` 或 stdin，JSON：`{ "prefabKey": { "field": value } }`）。
  4. 验证：`get` 或再跑 `diff`。

  ### S3：启用/禁用整块 prefab

  1. `playcraft prefab list --json` 确认 key。
  2. `playcraft prefab enable <key>` 或 `disable <key>`。
  3. 再 `describe` / `set` 填子字段（若需要）。

  ### S4：操作非当前活跃主题

  - 要么：`playcraft prefab switch <themeId>`（External 会写 `src/theme/index.ts`）；
  - 要么：命令统一加 `--variant <themeId>`（或 PlayCanvas 的 scene id）。

  ---

  ### 命令速查（项目根执行）

  ```bash
  playcraft prefab variants | themes | scenes
  playcraft prefab list [--json] [--variant <id>] [--limit N] [--offset M] \
    [--match <regex>] [--match-case] [--used-only] [--unused-only] [--changed-only] [--with-values]
  playcraft prefab diff [--json] [同上过滤分页]
  playcraft prefab describe [key] [--all] [--json] [同上]
  playcraft prefab search <regex> [--json] [--limit N] [--offset M] [--match-case]
  playcraft prefab get <key> [field] [--variant <id>]
  playcraft prefab set <key> <field> <value> [--variant <id>]
  playcraft prefab set-batch [--file path] [--variant <id>]
  playcraft prefab enable|disable <key> [--variant <id>]
  playcraft prefab switch <variant>
  ```

  ```bash
  playcraft prefab list --json | jq '.summary'
  ```

  | 常用选项 | 说明 |
  |----------|------|
  | `--variant <id>` | 不指定时：External 用 index.ts 活跃主题；PlayCanvas 用默认 GameConfig |
  | `--project-dir <path>` | 项目根，默认 cwd |

  ### 失败时

  - 无法识别项目类型：确认 cwd 是否为工程根。
  - key 不存在：`list --json`。
  - 校验失败：`describe <key> --json`。
  - 无效正则：检查 pattern。
  - 变体不存在：`prefab variants`。

## 我做什么

- 用 CLI（优先）读写已有 prefab 配置；必要时允许手改 data 文件（自担 schema 与语法）
- 分页检索、diff、批量 `set-batch`

## 何时用我

- 「当前主题改了哪些配置项」「把 layout.baseWidth 改成 800」
- 「有哪些 prefab key」「启用某块玩法」「切到另一个主题做配置」
- Agent 已处于 **Remix 工程根**且协议已在 schema 中

## 工作流

1. **bash** — 按 **S1→S2/S3/S4** 选用命令序列（尽量带 `--json` 便于解析）
2. **read** — 仅当 CLI 无法覆盖时读/写 `theme.data.json5`（须符合 playcraft-remix-workflow 目录约定）
3. **terminate** — `{ summary: "已修改：…" }`