游戏 UI 总控工作流

把对话需求转换成可复现的 UI 项目。项目事实必须写入 specs/<project-id>/；不要仅保留在对话中。

快速路由

根据请求选择最小充分路径：

• 游戏策划、PRD、交互逻辑、生图前需求 → game-ui-product-design
• 规范、设计系统、统一风格 → game-ui-specification
• 页面清单、功能扩展、玩家旅程 → game-ui-extension
• 完整单页、原型视觉、页面生图 → game-ui-page-generator
• 透明组件、切图、素材拆解 → game-ui-component-breakdown
• 雪碧图、单元素 PNG、切片打包 → game-ui-sprite-sheet-splitter
• Atlas、9-slice、Godot / Unity / Cocos JSON → game-ui-asset-pipeline
• 完整项目或多阶段交付 → 按本工作流依次编排

用户明确要求单阶段时，不强迫执行完整流程；但要读取已有契约。 生图前若 gdd.md / prd.md / interaction.md 缺失或仍为 draft，必须先执行生成第一步：game-ui-product-design。

分步操作指引

当用户按完整生成链路工作时，第一步必须是策划与 PRD，使用以下检查点：

1. 策划与 PRD（生成第一步）：调用 game-ui-product-design，完成并批准 gdd.md、prd.md、interaction.md；未批准前不得进入后续生图步骤。
2. 原型生成视觉：用一个基准页面验证构图和信息层级，保存为未批准版本。
3. UI 风格切换：保持页面结构不变生成风格候选；用户选定后再批准样式契约和基准页。
4. UI 延展：先输出屏幕地图并等待范围确认，再按批次逐页生成。
5. UI 组件拆解：只拆已批准页面，每个组件和状态单独交付。
6. 雪碧图拆分打包：把组件合图切成单元素透明 PNG，生成 manifest 和 ZIP。
7. Atlas 与引擎交付：语义命名、确认 9-slice、打包 Atlas 并生成引擎 JSON。

每一步开始时简要说明：

• 当前步骤和目标
• 将读取的输入
• 将产生或修改的文件
• 本步停止条件

每一步结束时固定输出：

当前步骤：
完成状态：
本步产物：
需要你检查：
可选操作：
进入下一步的条件：
可直接复制的下一步调用文本：

存在人工门禁时必须停止，不能把“给出下一步指引”理解为自动执行下一步：

• gdd.md / prd.md / interaction.md 未批准时，不开始页面生图（用户明确要求“跳过策划门禁”除外，并写入 quickstart.md）。
• 原型结构未确认时，不开始风格定稿。
• 风格契约和基准页未批准时，不批量延展页面视觉。
• 页面范围未确认时，只完成屏幕地图。
• 源页面未批准时，不拆组件。
• 组件雪碧图不存在时，不伪造单元素 PNG 或 ZIP。
• 语义 mapping 和 9-slice 未审核时，不批准 Atlas 或引擎清单。

初始化

1. 生成稳定的 project-id，使用小写字母、数字和连字符。

2. 若项目目录不存在，执行：

   python3 scripts/init_project.py <project-id>
   

3. 读取 spec.md、research.md、plan.md、gdd.md、prd.md、interaction.md 和 contracts/ 中全部文件。

4. 将用户提供的参考图路径记入 spec.md，分析结论写入 research.md。

5. 只询问会改变题材、平台、比例或交付范围的阻断问题；其他信息使用明确标注的默认值。

阶段顺序

完整项目启动时，生成链路从 Product Design 开始（第一步）。spec.md / research.md 可在同一步由产品设计回填最小集，或紧随其后补全。

1. Product Design（生成第一步）

调用 game-ui-product-design：

1. 写入 gdd.md：游戏定位、核心循环、系统清单、经济与养成（策划层，不含服务端公式）
2. 写入 prd.md：P0/P1 需求、信息架构、页面交付范围、验收标准
3. 写入 interaction.md：全局导航、分页面主流程、控件行为、状态机、跨页链路
4. 若 spec.md 仍空，同步写入项目定位、平台、比例与范围摘要

三份文档的 文档状态.status 均为 approved 后，才允许进入原型生图与后续步骤。用户明确跳过时，在 quickstart.md 记录跳过原因。

门禁：不得用空模板或仅改标题冒充已批准策划文档；本阶段结束后必须停止等待批准。

2. Specify

补全 spec.md（若第一步未写全）：

• 项目定位、核心玩法、目标平台、画面比例和语言
• 用户故事、范围、首个页面和交付物
• 可验证的视觉、功能和版权验收标准

门禁：存在阻断性未决事项时不得冻结契约。

3. Research

把参考图抽象成可复用语言，不复制受保护角色、商标或完整构图：

• 色彩、材质、光源、圆角、描边、密度
• 导航、卡片、按钮、图标和反馈模式
• 玩家旅程、核心循环、平台限制与风险

4. Specification

调用 game-ui-specification，写入 contracts/style-contract.yaml。将状态从 draft 改为 approved 前，确认色彩、文字、几何、效果和一致性规则均可执行。

门禁：页面技能不得静默引入契约外的主色、材质、光向或圆角体系。

5. Extension

调用 game-ui-extension：

• 以 gdd.md / prd.md / interaction.md 为输入
• 在 plan.md 建立按玩家旅程排序的屏幕路线
• 在 contracts/screen-contract.yaml 记录页面目的、入口、主操作、组件、状态、边界和数据
• 只选择服务玩法与商业模式的页面，标注 must-have、genre-specific 或 optional

6. Page generation

调用 game-ui-page-generator，一次处理一个页面：

1. 确认生成第一步（策划三文档）已批准（或已记录跳过）。
2. 读取样式、页面契约与 interaction.md 中该页主流程/状态。
3. 保存页面说明与最终提示词到 prompts/pages/<screen-id>.md。
4. 图片工具可用时实际生成图片，保存到 assets/pages/<screen-id>.<ext>。
5. 更新 asset-manifest.yaml；等待用户或明确验收规则批准。

不要因为工具不可用而虚构图片。此时资源状态使用 pending-generation，并保留可直接执行的提示词。

7. Component breakdown

仅对 approved: true 的页面调用 game-ui-component-breakdown：

• 先更新 component-contract.yaml
• 每个组件单独提示、单独文件、单独 manifest 条目
• 除背景外默认透明；默认不生成文字
• 组件状态、尺寸、命名和源页面可追踪

8. Sprite-sheet splitting

组件拆解输出为整张雪碧图时，调用 game-ui-sprite-sheet-splitter：

1. 读取实际雪碧图和组件契约。
2. 检查并去掉标题、按钮文案、数字标签、水印和文字残影。
3. 使用 Alpha 或纯色背景检测独立元素。
4. 导出单元素透明 PNG。
5. 生成坐标、尺寸和路径 manifest。
6. 将 PNG 与 manifest 打包成 ZIP。
7. 人工检查文字、裁断、粘连、阴影和透明边缘。

自动检测不可靠时调整阈值或重新生成留有间距的雪碧图，不得把错误切片标记为批准。

9. Atlas and engine handoff

需要开发交付时调用 game-ui-asset-pipeline：

1. 将检测序号映射为稳定语义名称。
2. 为组件登记 full、1:1、tile 或人工审核的 9-slice。
3. 生成不旋转的 Atlas PNG 与 JSON。
4. 生成 Godot、Unity、Cocos 或通用 JSON 清单。
5. 明确区分 JSON handoff 与原生引擎工程文件。

10. Validate

执行：

python3 scripts/validate_project.py specs/<project-id>

修复全部错误。警告必须在 quickstart.md 解释或解决。

视觉生成规则

图片生成工具可用时：

1. 页面图使用契约的画面比例。
2. 工具不支持精确尺寸时选择最接近比例，并在 manifest 记录实际尺寸。
3. 对中文文字生成不可靠时，优先生成无文字底板并注明后期排版区域；不得声称乱码可直接交付。
4. 组件生图逐个执行，不把多个组件粘在同一张图中。
5. 工具返回的文件移动或复制到项目资源目录，再更新真实路径。

变更控制

• 用户修改视觉方向时，先更新 spec.md 和 style-contract.yaml，再标记受影响页面与组件为 stale。
• 页面结构变化时，更新 screen-contract.yaml 后再生图。
• 页面未批准时，不得开始组件拆解。
• 不覆盖已批准资源；生成新版本并在 manifest 中保留来源关系。

完成定义

• 六类 Spec-Kit 产物完整，并含已批准（或已记录跳过）的 gdd.md / prd.md / interaction.md
• 四类核心契约之间的 ID 和路径一致；使用雪碧图时附加拆分契约
• 页面及组件图片存在，或明确标记待生成
• 视觉稿与组件均有提示词可复现
• 使用雪碧图时，单元素 PNG、拆分 manifest 和 ZIP 包可追踪
• 使用开发交付时，Atlas regions、9-slice 与引擎 JSON 一致
• tasks.md 反映真实状态
• 校验脚本无错误