gui-prefab
Atom Game GUI pipeline 第 3 阶段。把 View.cs 挂到 Prefab 并绑定 [SerializeField] 引用。 自包含的 Prefab 编辑指引,不依赖外部 edit-prefab skill。在 gui-draft 生成 View.cs 后使用。 控制 Prefab 绑定漂移。
SKILL.mdskills/gui-prefab/SKILL.md
GitHubPhase 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 中人工挂脚本/绑定」。
- 可通过 Batch Mode 编译(
- 两路径均不可用(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。