| name | gui-prefab |
| user-invocable | false |
| description | Atom Game GUI pipeline 第 3 阶段。把 View.cs 挂到 Prefab 并绑定 [SerializeField] 引用。 自包含的 Prefab 编辑指引，不依赖外部 edit-prefab skill。在 gui-draft 生成 View.cs 后使用。 控制 Prefab 绑定漂移。 |
Phase 3: gui-prefab — Prefab 编辑
职责：自包含的 Prefab 编辑。控制：Prefab 绑定漂移。
输入：gui-draft 输出的 View.cs + ui_data.lua 的 prefab 路径。
执行位置与并行：本阶段跑在主 agent。gui-config（Phase 4）与本阶段并行——
若本需求涉及配置数据，由 orchestrator 把 gui-config spawn 到 subagent 与本阶段同时跑；
不涉及配置则直接 skipped。两阶段都落定后才进入 gui-review（编排细节见 commands/run.md）。
动手前先读 ${CLAUDE_PLUGIN_ROOT}/shared-references/prefab-binding-contract.md。
编辑内容
- 把
<PanelName>View.cs 挂到 Prefab 根节点。
- 绑定每个
[SerializeField] 引用（按钮、文本、图片、列表节点）。
StylesModule<TEnum>：分组节点齐全 + 设默认 m_SelectedIndex。ListModule：Template 节点保持 inactive。- 静态格式文本保留在 Prefab 文本节点。
工具使用（主动加载）
进入本阶段时，主动通过 ToolSearch 搜索并加载 Prefab 相关能力（详见流程步骤 0），而非被动等待已加载：
- 优先使用搜到的 Prefab 专用 skill/tool：用它读写 Prefab、读 hierarchy、校验绑定。
- 搜不到 Prefab 专用工具时，退而用 Unity Editor 交互能力（编译、挂脚本、绑定
[SerializeField]）作为 fallback。
- 两者都没有 → 不臆造绑定；在
HUMAN_REVIEW.md 标注「需在 Unity 中人工挂脚本/绑定」，本阶段判降级，管线继续。
流程
-
前置：主动加载 Prefab 相关 skill/tool（改 prefab 之前必做）：
- 优先：使用
ToolSearch 搜索 Prefab 编辑相关能力（查询 "prefab" / "prefab edit" / "prefab bind" 等），
获取 deferred tool schema——搜到则优先使用，用于读写 Prefab、读 hierarchy、校验绑定。
- fallback：使用
ToolSearch 搜索 Unity Editor 交互能力（查询 "unity editor" / "unity compile" 等），
获取编译/Editor 交互 tool schema——Prefab 专用工具搜不到时，退而用 Editor 交互能力编辑 Prefab
（挂脚本、绑定 [SerializeField]）作为补充。
- 搜索到的工具 schema 会展开在上下文中，后续步骤直接调用。
- 两者都没有 → Prefab 编辑能力不可用，步骤 2–4 跳过，步骤 5 记
BLOCKED 入 HUMAN_REVIEW.md，不阻塞管线。
-
前置：判断 Unity Editor 运行状态 + C# 编译（硬门，改 prefab 之前必做）：
- 先通过 unity-cli 判断 Unity Editor 是否正在运行。
- Editor 运行中（unity-cli 可用）：
- 先查 PlayMode 状态；若处于 PlayMode 且需退出，先征求用户确认。
- 通过 unity-cli 触发 C# 编译，让 gui-draft 产出的
<PanelName>View.cs（及本次新增/改动的 ViewModel）
进程序集——只有编译通过、MonoScript 生成稳定 GUID 后，才能把 View 脚本挂到 Prefab 根节点、
并让 [SerializeField] 字段在 Inspector 可见可绑。
- 编译通过后可以继续编辑 Prefab（挂脚本、绑定
[SerializeField]）。
- Editor 未运行（unity-cli 不可用）：
- 可通过 Batch Mode 编译（
./unity/WindowsEditor/Unity.exe -projectPath ./client/ -batchmode -quit ...），
让 View/ViewModel 进程序集（.meta 文件由 csharp-tool 生成，不依赖 Unity 编译）。
- 但 Batch Mode 无法编辑 Prefab（不能挂脚本、不能绑定
[SerializeField]）→ Prefab 编辑本身判
BLOCKED，记入 HUMAN_REVIEW.md「需在 Unity Editor 中人工挂脚本/绑定」。
- 两路径均不可用（Editor 未开且无 Unity.exe） → 编译门 + Prefab 编辑均判
BLOCKED 记入清单，不阻塞。
- 编译报错 → 先按报错修 draft 产物再重编。编译通过后才进入第 2 步。
-
列出 View.cs 中所有 [SerializeField] 字段（名称 + 类型）。
-
对照 Prefab hierarchy 逐一绑定（或记录待人工绑定项）。
-
校验 prefab-binding-contract 的清单（悬空字段 / 孤儿绑定 / 类型匹配 / 数量一致）。
-
记录状态（由 orchestrator 在主 agent 侧执行）：
python3 "${CLAUDE_PLUGIN_ROOT}/tools/gui_run_state.py" set "${CLAUDE_PROJECT_DIR}" <panelId> gui-prefab done
Gate
- 前置工具加载门：改 prefab 前已通过
ToolSearch 主动搜索 Prefab 专用工具（优先）及 Unity Editor
交互能力（fallback）。Prefab 专用工具搜到 → 优先用于读写/校验 Prefab；搜不到 → 退而通过 unity-cli
与 Editor 通讯完成 Prefab 编辑；unity-cli 也不可用（Editor 未运行）→ 步骤 1 仅剩 Batch Mode 编译，
Prefab 编辑本身 BLOCKED；连 Unity.exe 都没有 → 编译门 + Prefab 编辑均 BLOCKED。
- 前置编译门：改 prefab 前 C# 已编译通过（View/ViewModel 进程序集）。按两路径规则：Editor 运行中
→ unity-cli 编译后继续编辑 prefab；Editor 未运行 → Batch Mode 编译可过但 Prefab 编辑本身 BLOCKED
（Batch Mode 无法操作 Prefab），记入
HUMAN_REVIEW.md；两路径均不可用 → BLOCKED。
- View.cs 中每个
[SerializeField] 在 Prefab 中都有对应绑定节点（数量一致）。
缺 Prefab 能力时该 Gate → BLOCKED，记入清单，不阻塞。
→ gui-config（Phase 4）由 orchestrator 并行 spawn 于 subagent（本需求不涉及配置则 skipped）。
prefab 与 config 两阶段均落定后 → 进入 gui-review。
