cocos-dna — Cocos Creator UI 设计规范技能

版本兼容性

引擎	支持版本	说明
Cocos Creator	3.7+（推荐 3.8 / 4.x）	依赖 cc.tween 新 API、Widget.AlignMode、Sprite.SizeMode.CUSTOM、Prefab 嵌套序列化等 3.7+ 特性
Node.js（工具脚本）	16+	sync-runtime.js、resolve-asset-uuids.js 等使用 ES2020+ 语法

低版本注意：Cocos Creator 3.6 及以下版本的 resources.load 回调签名和 Prefab 序列化格式可能与本 skill 模板不兼容。如需支持更早版本，请在 templates/runtime/ 中做适配。

来源与架构

基于 design-dna 扩展。Phase 1（结构）和 Phase 2（分析）完全复用 design-dna skill 原始实现，Phase 3 重写为 DNA 数据驱动转换方案 — 将 DNA JSON 映射为 Cocos Creator 原生组件，通过 MCP 工具自动生成 Prefab。

为什么不能直接用 design-dna 的 Phase 3：design-dna 的 Phase 3 产出是自包含 HTML/CSS/JS（Web 前端），而 Cocos Creator 使用自有渲染管线（WebGL/Metal/Vulkan）、ECS-like 组件模型（Node + Component）、Asset Manager 资源系统，三者完全不同。因此 cocos-dna 替换 Phase 3 为 Cocos 原生组件映射 + MCP 驱动 Prefab 创建。

依赖

cocos-dna 依赖 design-dna skill。如未安装，引导用户安装：https://github.com/zanwei/design-dna

跨 Skill 协作

cocos-dna 通过稳定的数据契约为其他 skill 提供服务，不直接调用其他 skill 的脚本。

消费者	契约文件	提供脚本	协作模式
cocos-test	verify-spec.json	extract-verify-spec.js	cocos-dna 导出"该验什么"，cocos-test 决定"怎么验"
cocos-test	Prefab .prefab	check-prefab-dupes.js	通用 Prefab 重名检测，cocos-test 可在测试流程中调用

职责边界：

• cocos-dna 负责：UI 结构定义、数据提取、verify-spec.json schema 维护
• cocos-test 负责：测试模板、断言逻辑、Playwright/Jest 集成
• 中间契约（verify-spec.json）的 schema 变更由 cocos-dna 维护，向后兼容

项目隔离原则：本技能是通用规范，不包含任何特定项目的设计内容。所有项目特定的设计系统来自各项目自己的 cocos-dna/design-dna.json。

---

三阶段工作流

Phase 1: 结构          Phase 2: 分析          Phase 3: 生成（Cocos 转换）
 [design-dna]           [design-dna]            [cocos-dna 自有]
┌─────────────┐     ┌─────────────────┐     ┌──────────────────────────┐
│ 展示 Schema │ ──→ │ 从参考图提取    │ ──→ │ DNA → Cocos 组件映射     │
│ 三维度字段   │     │ Design DNA JSON │     │ → MCP 创建节点/Prefab    │
│ 问用户定制   │     │ 问用户调整      │     │ → 生成 View.generated.ts │
└─────────────┘     └─────────────────┘     └──────────────────────────┘

根据上下文判断从哪个阶段开始：

• 全新项目：Phase 1 → 2 → 3（完整流程）
• 已有 DNA，新界面：Phase 3（直接转换）
• 用户只想看 Schema：仅 Phase 1

---

Phase 1: 结构 — 展示 Schema 📦 由 design-dna skill 执行

1. 读取 references/design-dna-schema.md
2. 向用户展示三维度结构：design_system（tokens）、design_style（定性感知）、visual_effects（特效层）
3. 询问用户是否需要定制或扩展维度

Phase 2: 分析 — 从参考图提取 DNA 📦 由 design-dna skill 执行

1. 从用户提供的参考图/截图/URL 中逐字段提取或推断值
2. 输出完整 DNA JSON — 每字段必须填充
3. 必须询问："需要在进入生成阶段前调整任何值吗？"
4. 用户确认后保存为 cocos-dna/design-dna.json

Phase 3: 生成 — DNA 数据驱动转换 🎮 cocos-dna 核心

本阶段是 cocos-dna 的核心价值。 详细映射规则和代码模板见 → references/dna-cocos-mapping.md

执行步骤

1. 读取设计约束 — 读取 cocos-dna/design-dna.json（SSOT）+ 已有 components/ 文档作为风格基线
2. 确认输入 — 页面名称（英文+中文）、设计分辨率、适配策略、UI 参考图
   • ⚠️ 适配策略确认（不可跳过）：从 design-dna.json → design_system.layout 读取 design_resolution + fit_strategy + safe_area。如缺失，必须先询问用户目标平台和适配策略后补充到 design-dna.json
3. ⚠️ 初始化页面目录结构（不可跳过） — 见下方「页面目录初始化」
4. 分析图片 → 匹配 DNA — 将图片元素匹配到 DNA 的颜色、字体、间距等
5. ⚠️ 参考图坐标换算（不可跳过） — 见下方「参考图坐标换算规则」
6. ⚠️ 询问动态效果（不可跳过） — 见下方「动态效果确认」
7. DNA → Cocos 组件映射 — 按映射表确定层级结构和组件分配。必须按三层分类规则决定定位方式（Layer 1 交互UI→Widget / Layer 2 容器→Widget+Layout / Layer 3 装饰→Position）
8. 输出文档 + 代码（Phase 3a） — 见下方「产出物清单」。此步输出 design.md + asset-manifest(UUID=null) + art-prompts.md + View.generated.ts + PageView.ts。不依赖美术资源和 MCP
9. 资源绑定 + MCP 创建 Prefab（Phase 3b） — 美术资源到位后执行。按场景 H 流程：resolve-asset-uuids → generate-view → design2prefab（MCP-Only，不降级）
10. 验证 — 按验证清单自检，见 → references/output-spec.md

⚠️ 页面目录初始化（必须在输出任何文件前执行）

关键规则：进入 Phase 3 后，Agent 必须首先创建完整的页面目录结构，再开始编写文档和代码。
不完整的目录结构会导致后续 resolve-asset-uuids.js、AI 绘图、验证等环节断裂。

必须创建的目录和文件：

cocos-dna/components/<page>/
├── design.md                  ← 步骤 7 输出
├── asset-manifest.json        ← 步骤 7 输出
├── view-manifest.json         ← 步骤 7 输出（从 design.md 第6.2章 @property 映射表提取）
├── assets/
│   ├── art-prompts.md         ← 步骤 7 输出（AI 绘图 Prompt，基于 design.md 第6章资源清单）
│   └── raw/
│       └── .gitkeep           ← 占位，后续 AI 生成的原始资产放在此目录
└── references/
    └── README.md              ← 参考图索引（可从 examples/_example-page/references/README.md 复制模板）

Agent 检查清单（步骤 3）：

• cocos-dna/components/<page>/ 目录已创建
• cocos-dna/components/<page>/assets/ 目录已创建
• cocos-dna/components/<page>/assets/raw/.gitkeep 已创建
• cocos-dna/components/<page>/references/ 目录已创建
• design-dna.json 的 pages 索引中已添加新页面条目

💡 提示：可参考 examples/_example-page/ 的目录结构。assets/art-prompts.md 在步骤 7 输出文档时与 design.md、asset-manifest.json 一起编写。

⚠️ 参考图坐标换算规则（必须在输出 design.md 前执行）

背景：用户提供的 UI 参考图分辨率（如 2712×1220）通常与项目设计分辨率（如 1280×720）不同。
如果直接使用参考图上的像素坐标写入 design.md 第4章，会导致节点偏移出屏、UI 布局崩溃。
这是 pig-rabbit 等项目 UI 全乱的根本原因。

换算公式：

scaleX = design_resolution.width / 参考图宽度
scaleY = design_resolution.height / 参考图高度

新坐标 x = 参考图 x × scaleX
新坐标 y = 参考图 y × scaleY
新尺寸 w = 参考图 w × scaleX  (或 scaleY，取决于保持比例的需求)
新尺寸 h = 参考图 h × scaleY

换算后按「三层分类」决定定位方式（见 node-spec.md 的「UI 布局三层分类规则」）：

核心原则（来自 Cocos 官方多分辨率适配文档）：
Canvas 负责整体缩放（所有渲染元素统一缩放），Widget 负责 UI 对齐（确保元素在不同分辨率保持正确位置）。
Widget 只用于「需要在不同分辨率保持语义位置」的 UI 元素，不是所有节点都用 Widget。

层级	元素类型	定位方式	说明
Layer 1: 交互 UI	按钮、标题、文本、HUD、输入框、提示	必须 Widget（禁止用 Position 定位到屏幕边缘）	不同分辨率/宽高比必须保持语义位置
Layer 2: 结构容器	Panel、Group、Container、List	Widget + Layout	容器决定内部元素位置，自身用 Widget 锚定
Layer 3: 装饰/视觉元素	背景纹理、齿轮装饰、光效、粒子	可以用 Position（Canvas 已统一缩放），不强制 Widget	装饰不需精确对齐；有动画的装饰用 Position 更灵活

Widget 具体策略表（仅 Layer 1 + Layer 2）：

换算后的节点位置	Widget 策略	说明
顶部 UI（标题、返回按钮）	[Widget: Top=边距, HCenter=0]	不同设备顶部高度不同（刘海/平板）
底部 UI（按钮、提示文字）	[Widget: Bottom=边距, HCenter=0]	底部 UI 最典型需要适配的区域
全屏背景/遮罩	[Widget: LRTB=0]	自动撑满，不用固定尺寸
水平居中内容组	[Widget: HCenter=0] + Position y	居中不依赖绝对 x
底部多个按钮/提示	用 Layout 包一层 + [Widget: Bottom=N, HCenter=0]	避免按钮与提示文字重叠

装饰元素（Layer 3）策略：

装饰类型	推荐定位	说明
纯视觉装饰（齿轮、飘带、纹理）	Position（Canvas 缩放即可）	不同宽高比下允许被裁切
需要在宽窄屏都可见的角落装饰	[Widget: 方向=边距, AlignMode=ONCE]	ONCE = 仅初始化对齐一次，之后不干涉动画
有持续动画的装饰（旋转齿轮等）	Position 或 [Widget: AlignMode=ONCE]	⚠️ AlignMode=ALWAYS 会每帧重置 Position，覆盖 tween 动画

换算示例（参考图 2712×1220 → 设计分辨率 1280×720）：

scaleX = 1280/2712 ≈ 0.472
scaleY = 720/1220  ≈ 0.590

TitleGroup(交互UI):  y=440  → y≈260 → Widget: Top=100, HCenter=0
CardGroup(结构容器):  y=80   → y≈47  → Widget: HCenter=0, VCenter=25
DifficultyGroup(UI): y=-380 → y≈-224 → Widget: Bottom=136, HCenter=0
StartBtn(交互UI):    y=-500 → y≈-295 → Widget: Bottom=65, HCenter=0
DecoGear(装饰):      (-560, 300) → (-264, 177) → Position: (-264, 177)（Canvas 缩放即可）
Card 500×600 → 236×354（按 scaleX 等比缩放）

Agent 检查清单（步骤 5）：

• 已识别参考图分辨率与设计分辨率的差异
• 已计算 scaleX 和 scaleY
• 所有坐标和尺寸已按比例换算到设计分辨率
• 交互 UI（Layer 1） 使用 Widget 定位，禁止 Position 定位到屏幕边缘
• 结构容器（Layer 2） 使用 Widget + Layout
• 装饰元素（Layer 3） 使用 Position（有动画的节点不用 Widget ALWAYS）
• 关键 UI 元素在安全区域内
• 有持续动画的 Widget 节点设置 AlignMode=ONCE

⚠️ MCP 策略：MCP-Only（无降级）

核心原则：Cocos Creator 是引擎项目，Prefab 必须通过 MCP 在编辑器中创建才能保证组件初始化、UUID 分配、序列化格式正确。
不存在"优雅降级" — Offline 生成的 Prefab JSON 在编辑器中经常组件丢失、打不开，最终还是要用 MCP 重做。

MCP 不可用时的 Agent 行为：

1. 不降级、不绕过 — 明确告知用户 MCP 不可用，Prefab 步骤暂停
2. 输出 MCP 启动指引：

   ⛔ MCP Server 未连通，Prefab 创建步骤暂停。
   请启动 Cocos MCP Server：
   node <cocos-cli-path>/dist/cli.js start-mcp-server
   启动后执行「场景 H：资源到位 + Prefab 创建」继续。

3. Phase 3a 的产出物正常输出（design.md + View.generated.ts + PageView.ts），这些不依赖 MCP
4. 禁止使用 --offline 作为正式产出路径。--offline 和 --dry-run 仅用于调试/预览节点树结构

💡 design2prefab.js 的 --offline 模式保留但重新定位：它是开发者调试工具（预览 Prefab JSON 结构），不是产出物生成路径。正式 Prefab 必须走 MCP。

⚠️ 美术资源异步工作流（渐进式完成）

现实场景：Phase 3 设计阶段先输出 art-prompts.md（AI 绘图 Prompt），美术资源异步、逐步生成。
代码不应等美术资源就位才开始写 — 应该先写代码，资源到位后再绑定。

Phase 3 拆分为两个可独立执行的子阶段：

子阶段	时机	产出物	依赖 MCP
Phase 3a: 设计 + 代码	立即执行	design.md + asset-manifest(UUID=null) + art-prompts.md + View.generated.ts + PageView.ts	❌ 不依赖
Phase 3b: 资源绑定 + Prefab	美术资源到位后	asset-manifest(UUID已填充) + View.generated.ts(刷新) + Prefab	✅ 需要 MCP

Phase 3a 详细步骤（美术资源到位前）：

A1  sync-runtime.js (如需)     → 同步 runtime 模板
A2  AI 手写 design.md          → 9章完整，第6章资源清单包含预设路径
A3  AI 手写 asset-manifest.json → uuid/spriteFrameUuid 填 null，status 填 "pending"
A3b AI 手写 view-manifest.json → 从 design.md 第4章 @property 映射表提取 UI 节点绑定（结构化 JSON）
A4  AI 手写 art-prompts.md     → 每资源独立 Prompt
A5  generate-view.js <page>    → Layer 2 .generated.ts（读取 view-manifest.json + asset-manifest.json 两个数据源）
A6  AI 手写 PageView.ts        → Layer 3 业务逻辑（引用节点名，不依赖具体资源 UUID）
A7  AI 手写 ThemeConfig 等     → 主题配置

generate-view.js 数据源：view-manifest.json（UI 节点绑定 → @autoNode/@autoLabel/@autoSprite）+ asset-manifest.json（资源清单 → assetManifest getter + @property(SpriteFrame)）

Phase 3a 的代码是可编译可运行的 — Sprite 节点暂时无纹理（白色占位），但逻辑、布局、动画、交互都已就位。

Phase 3b 详细步骤（美术资源到位后 = 场景 H）：→ 见下方场景 H

---

输入要求

必填项	说明
UI 图片	至少 1 张截图/设计稿
页面名称	英文标识符，如 main-menu、char-select
中文名称	如 "主菜单"、"角色选择界面"

选填项	默认值
设计分辨率	从项目 cocos-dna/design-dna.json → layout.design_resolution 读取，或默认 1280×720
适配策略	从项目 cocos-dna/design-dna.json → layout.fit_strategy 读取，或默认 "fitHeight"（横屏）/ "fitWidth"（竖屏）
安全区域	从项目 cocos-dna/design-dna.json → layout.safe_area 读取。如未定义，默认等于设计分辨率
额外交互说明	从图片推断

⚡ 动态效果确认（重要）

静态截图无法完整表达动态效果。Agent 分析完图片后 必须主动询问用户：

💡 我注意到这个界面可能包含以下动态效果。请确认哪些需要支持：

1. 粒子效果 — 烟雾、飘雪、火花、光点等
2. 持续旋转/摆动 — 齿轮旋转、时钟指针、钟摆等
3. 背景动效 — 缓慢平移、亮度呼吸、云层流动等
4. 入场/过渡动画 — 渐显、滑入、缩放出场等
5. 交互反馈 — 按钮悬停发光、按下缩放、点击波纹等
6. 其他 — 请补充

---

产出物清单

#	产物	路径	说明
1	Design DNA JSON	cocos-dna/design-dna.json	全局设计 token SSOT（色彩/字体/间距/动效/风格）+ 页面轻量索引。禁止在此存储页面级设计详情
2	UI 结构协议文档	cocos-dna/components/<page>/design.md	9章 Markdown（含第1.5章），页面设计数据的唯一存储位置
3	资产绑定清单	cocos-dna/components/<page>/asset-manifest.json	Sprite UUID 映射。运行 resolve-asset-uuids.js Smart Discovery 自动同步
3b	UI 节点绑定清单	cocos-dna/components/<page>/view-manifest.json	从 design.md 第6.2章 @property 映射表提取的结构化 JSON。generate-view.js 读取此文件生成 @autoNode/@autoLabel/@autoSprite 声明
3c	验证规格	cocos-dna/components/<page>/verify-spec.json	标准化验证契约（节点/Label/Sprite/资源清单），由 extract-verify-spec.js 生成，供 cocos-test 的 generate-verify.js 消费。详见「跨 Skill 协作」章节
4	AI 绘图 Prompt	cocos-dna/components/<page>/assets/art-prompts.md	美术资源生成指引，每个资源独立一节（## 资源 #N: 描述 — filename.png），严禁合并。格式规范见 → references/output-spec.md
5a	三层架构 — AI 生成层	assets/scripts/views/<Page>View.generated.ts	Layer 2：@property 声明 + assetManifest（AI 可安全覆盖）
5b	三层架构 — 业务逻辑层	assets/scripts/views/<Page>PageView.ts	Layer 3：业务逻辑（人写，AI 永不覆盖）
5c	Prefab 组件脚本（可选）	assets/scripts/prefab-components/<Page>PageComp.ts	@property 声明（辅助 Prefab 编辑器序列化）
6	Prefab 文件	assets/resources/prefabs/pages/<Page>Page.prefab	MCP 自动创建
7	ThemeConfig 更新	assets/scripts/ui/themed-components/ThemeConfig.ts	全局 tokens 同步（SteamColors SSOT）

Scene vs Prefab 架构决策

⚠️ 关键规则：新 UI 页面默认创建为 .prefab，不新建 .scene。详细约束见 → cocos-constraints.md「Scene 架构约束」章节。

决策	条件	产物
创建 Prefab（默认）	所有普通 UI 页面（菜单/战斗/地图/设置等）	assets/resources/prefabs/pages/<Page>Page.prefab
创建 Scene（例外）	渲染管线/光照/天空盒与主场景根本不同（需设计文档论证 + 用户确认）	assets/scenes/<name>.scene + 更新 build-config.json

design2prefab.js 的 MCP 模式使用 scene 仅作为临时工作区（打开 → 创建节点 → 导出为 Prefab → 清理），scene 本身不是产出物。Offline 模式不涉及 scene。

三层架构

所有页面统一使用 BaseView 三层架构：

层级	文件	职责	维护者
Layer 1	BaseView.ts	通用基类（状态机 + 资源管理 + Widget 工具）	skill 维护
Layer 2	XxxView.generated.ts	@property + assetManifest（可安全覆盖）	Codegen / AI
Layer 3	XxxPageView.ts	业务逻辑（永不覆盖）	人工

design.md 章节结构（9章，含第1.5章）

章节	内容	何时读取详细规范
第1章 设计概述	页面功能、视觉目标、设计分辨率、适配策略（fit_strategy + safe_area）、设计原则	—
第1.5章 参考图溯源	参考图列表、设计决策追踪表	—
第2章 整体布局	ASCII 线框图 + 布局要点表	—
第3章 视觉规范	色彩/字体/尺寸/动效 4 个子表	—
第4章 节点树	Cocos Prefab 结构（核心）	→ node-spec.md
第5章 元素详述	每个元素的设计参数（Cocos API 格式）	—
第6章 资源切图清单	资源文件名/尺寸表 + @property 映射表（路径以 asset-manifest.json 为权威，不重复）	→ node-spec.md
第6.5章 资产绑定	asset-manifest.json	→ asset-binding.md
第7章 交互逻辑	点击、入场动画、页面跳转	—
第8章 动态效果	粒子/动画/背景动效规范	→ output-spec.md

---

项目设计系统

每个项目在 cocos-dna/ 目录下维护自己的设计系统：

<project-root>/cocos-dna/
├── design-dna.json          ← 全局 SSOT（仅含 design_system / design_style / visual_effects / cocos_dna_extensions + 页面索引）
├── design-tokens.css        ← CSS 变量辅助预览
├── asset-manifest.schema.json
├── components/              ← 各 UI 页面的设计数据
│   ├── <page-name>/
│   │   ├── design.md        ← 页面级设计数据的唯一存储位置（9 章）
│   │   ├── asset-manifest.json  ← 资源清单（路径 + UUID + 加载方式）
│   │   ├── view-manifest.json   ← UI 节点绑定（property 名 + cc 类型 + Prefab 节点名）
│   │   ├── assets/
│   │   │   ├── art-prompts.md    ← AI 绘图 Prompt
│   │   │   └── raw/              ← AI 生成的原始资产（不参与 Cocos 构建）
│   │   └── references/
│   └── ...
└── README.md

# examples 目录位于 skill 本身（不在项目产物 cocos-dna/ 下）：
.codebuddy/skills/cocos-dna/examples/
├── README.md                ← 索引说明 + 数据边界 + 新建流程
└── _example-page/           ← 模拟完整页面目录
    ├── design.md            ← design.md 9 章完整格式模板
    ├── asset-manifest.json  ← 资源清单格式示例
    ├── view-manifest.json   ← UI 节点绑定格式示例
    ├── references/README.md
    └── assets/art-prompts.md

design-dna.json 数据边界

⚠️ 关键规则：design-dna.json 只保存全局设计 token（design_system、design_style、visual_effects、cocos_dna_extensions）和一个 pages 轻量索引（仅含 page_name_cn、status、design_doc 路径）。

禁止在 design-dna.json 的 pages 中写入页面的 layout、components、animations、particles 等详细设计数据。这些数据必须且只能写在对应的 cocos-dna/components/<page>/design.md 中。

新增 UI 页面时：

1. 在 pages 索引中添加一行轻量条目
2. 在 cocos-dna/components/<page>/design.md 中编写完整的 9 章设计文档

• 无 cocos-dna/design-dna.json：先从参考图提取设计系统（Phase 1→2），生成后再进入 UI 分析
• 已有 cocos-dna/design-dna.json：读取全局 token 作为设计约束，新界面必须与已有系统保持一致

---

参考资料索引

文件	用途	何时读取
design-dna-schema.md	三维度 JSON Schema	Phase 1 展示结构、Phase 2 首次生成 DNA
dna-cocos-mapping.md	DNA→Cocos 映射表 + MCP 流程 + 代码模板 + 路径渲染指南	Phase 3 执行映射与代码生成
output-spec.md	design.md 9章详细定义（含第1.5章）+ 动效接口 + 验证清单	Phase 3 编写 design.md、最终验证
node-spec.md	节点命名规范、节点信息格式	Phase 3 构建第4/6章节点树
asset-binding.md	资产绑定协议、Schema、状态机、静态 vs 动态资源目录决策、Smart Discovery 规范	Phase 3 生成第6.5章、资产同步
examples/_example-page/（skill 目录下）	完整页面目录结构示例（design.md 9章 + asset-manifest + view-manifest + references + art-prompts）	理解输出格式、新页面目录结构
cocos-constraints.md	Cocos 技术栈禁止清单与约束	代码生成/任务规划时自检
validate-workflow.md	V1-V4 验证规范（设计文档/Prefab/代码/测试）	Phase 3 完成后自动验证
runtime-integration.md	Runtime 集成规范（ResourceManager/LayerManager 同步与改造指南）	Phase 3 代码生成、runtime 集成

Runtime 模板

cocos-dna 提供通用运行时基础设施模板，由 skill 统一维护，通过 sync-runtime.js 同步到项目。

模板文件	版本	职责
`templates/runtime/core/ResourceManager.ts`	1.0.0	统一资源加载/缓存/分组释放（解决 resources.load 散落 + 零 release 问题）
`templates/runtime/core/LayerManager.ts`	1.0.0	UI 层级隔离：page / popup / effect / guide
`templates/runtime/core/EventBus.ts`	1.1.0	全局事件总线（on/off/emit/once + 单例 + context 绑定）+ 使用范围规约 + 清理规则
`templates/runtime/core/DebugLogger.ts`	1.0.0	结构化调试日志（module/tag/level + window.__DEBUG_LOG__ 供 E2E）
`templates/runtime/core/UIBinder.ts`	1.0.0	运行时节点绑定工具（auto/map/component 三种模式，@property 的动态 fallback）
`templates/runtime/views/BaseView.ts`	1.1.0	视图 Component 基类（三层架构：runtime → generated → business），支持 @property + 状态机 + 资源管理 + asset-manifest 绑定

Agent 自动集成时机

• Phase 3 首次执行：检查项目 assets/scripts/runtime/ 是否缺少 runtime 文件，缺少则自动同步
• 新项目初始化：完整流程（Phase 1 → 2 → 3）时自动同步
• 用户显式请求："同步 runtime"、"更新 runtime 模板"

什么放 skill，什么放项目

判断标准	归属
能直接在另一个 Cocos DNA 项目里用	→ skill templates/
绑定项目视觉风格/游戏流/业务逻辑	→ 项目 assets/scripts/

Skill v1.6 覆盖层（6 模板 + 1 codegen 脚本）：视图基类（BaseView）+ 绑定工具（UIBinder）+ 资源（ResourceManager）+ 层级（LayerManager）+ 通信（EventBus）+ 调试（DebugLogger）+ Codegen（generate-view.js）

留在项目侧：GameEvents（事件常量）、GameFlowFSM、UIManager、I18n、DataProvider、ThemeConfig、RendererConfig

详细集成步骤见 → runtime-integration.md

资产同步与 Prefab 生成工作流

资产时序问题与解决方案

Phase 3 设计阶段先生成 asset-manifest.json（预设路径），美术资源后续异步、逐步生成。两者之间存在时序断裂：

问题	表现	解决
路径猜错	manifest 预设 resources/textures/main-menu/，实际放在 textures/common/buttons/	Smart Discovery 自动纠正
资源重命名	manifest 记录 4.1 主菜单背景.png，实际规范名 main_menu_bg.png	按 id 关键词模糊匹配
UUID 缺失	文件已存在但 manifest 中 uuid 为 null	resolve-asset-uuids 从 .meta 提取
低优先级目录	NanoBanana/raw/ 等原始目录被误选	优先级排序 + 自动切换到正式目录

完整流水线

Phase 3 设计       美术资源生成         资产同步              Prefab 生成
┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  ┌──────────────────┐
│ design.md    │  │ AI 绘图/手工 │  │ resolve-asset-   │  │ design2prefab.js │
│ + asset-     │→ │ 放入 assets/ │→ │ uuids.js v2.0    │→ │ 读 design.md #4  │
│   manifest   │  │ 任意合理目录 │  │ Smart Discovery  │  │ + asset-manifest │
│ (预设路径)   │  │ .meta 自动生 │  │ 自动修正+填UUID  │  │ → MCP/Offline    │
└──────────────┘  └──────────────┘  └──────────────────┘  └──────────────────┘

resolve-asset-uuids.js v2.0 — Smart Discovery

资产同步的核心工具。详细算法见 → asset-binding.md

查找策略（按优先级）：

1. 精确路径 — 按 assetPath 查找，非低优先级目录则直接使用
2. 精确 filename — 按 filename 在 assets/ 全局索引中查找
3. id 模糊匹配 — 从 id 提取关键词（去掉 bg_/icon_/btn_/fx_ 前缀），匹配文件名包含所有关键词的文件

loadType 路径偏好：

• static → 优先 assets/textures/（非 resources）
• dynamic → 优先 assets/resources/textures/

Agent 执行时机：

• 每次美术资源有更新（新增/移动/重命名）后运行
• Phase 3 生成 Prefab 前必须先运行
• 运行命令：node .codebuddy/skills/cocos-dna/scripts/resolve-asset-uuids.js --project <path> [--page <id>] --verbose

design2prefab.js — 设计文档到 Prefab

从 design.md 第4章自动解析节点树 → 生成 NodeSpec[] 中间表示 → MCP 或 Offline 创建 Prefab。

数据源：

1. design.md 第4章代码块 → 节点树结构（NodeSpec）
2. asset-manifest.json → SpriteFrame UUID 绑定

三种模式：

模式	命令	说明
dry-run	--dry-run	仅解析 + 打印 NodeSpec 树（调试用）
MCP	（默认）	正式产出路径 — 需 Cocos 编辑器运行，实时创建节点 + 保存 Prefab
Offline	--offline	仅调试/预览 — 不需编辑器，生成 .prefab JSON 供检查结构，不作为正式产出物

SpriteFrame 绑定流程（双策略）：

1. 显式绑定 — design.md 节点中 SpriteFrame: xxx.png → 从 asset-manifest 查找 filename === xxx.png && (status === 'ready' || status === 'size_mismatch') → 获取 spriteFrameUuid → MCP setSpriteFrame() / Offline __uuid__ 绑定
2. 自动绑定（推荐） — 节点为 [Sprite] 类型但无显式 SpriteFrame: 属性时 → 从 asset-manifest 的 boundToNodes 数组匹配当前节点路径 → 获取 spriteFrameUuid → 自动绑定

注意：size_mismatch 状态的资源也有有效 UUID，不会跳过绑定。MCP 和 Offline 模式均支持上述双策略。

可执行脚本

脚本总览

脚本	角色层	用途	调用方式
mcp-client.js	🔧 底层库	MCP 通信层 — 场景/节点/组件/Prefab 操作 API	require() 内部调用；或 node scripts/mcp-client.js [port] 测试连通性
prefab-builder.js	🔧 底层库	离线 Prefab JSON 构建器（不需编辑器）	require() 内部调用；node scripts/prefab-builder.js 自测
resolve-asset-uuids.js	⚙️ 数据同步	v2.0 Smart Discovery 资产 UUID 解析	node scripts/resolve-asset-uuids.js --project <P> [--page <id>] [--check] [--verbose]
design2prefab.js	⚙️ 生成	design.md #4 → NodeSpec → MCP/Offline Prefab	node scripts/design2prefab.js --project <P> <page> [--dry-run|--offline]
generate-view.js	⚙️ 生成	view-manifest + asset-manifest → Layer 2 XxxView.generated.ts	node scripts/generate-view.js [--project <P>] <page|all> [--dry-run] [--out <dir>]
sync-runtime.js	🏗️ 基建	Runtime 模板同步（templates/ → 项目 scripts/runtime/）	node scripts/sync-runtime.js --project <P> --apply
ui-dev-workflow.js	✅ 验证	V1-V4 验证引擎（设计文档/Prefab/代码/测试）	node scripts/ui-dev-workflow.js --project <P> <ui-name>
extract-verify-spec.js	📤 数据导出	从 view-manifest + asset-manifest 提取标准化 verify-spec.json，供 cocos-test 消费	node scripts/extract-verify-spec.js --project <P> <page|--all>
check-prefab-dupes.js	✅ 验证	Prefab 节点重名检测（通用版，支持任意页面）	node scripts/check-prefab-dupes.js --project <P> <page|--all> [--verbose]

⭐ 脚本编排地图（Orchestration Map）

Coding Agent 必读：下面按场景列出脚本的组合顺序与依赖关系。底层库脚本（mcp-client / prefab-builder）不需要手动调用，它们被 design2prefab 内部 require()。

场景 A：新建 UI 页面（完整 Phase 3 流程）

Phase 3 拆分为 3a（设计+代码） 和 3b（资源绑定+Prefab），支持美术资源异步到位。

步骤  脚本                    输入 → 输出                                前置条件
─────────────────────────────────────────────────────────────────────────────
 === Phase 3a: 设计 + 代码（无需美术资源，无需 MCP） ===
 A1   sync-runtime.js         skill templates/ → 项目 runtime/           首次执行或 runtime 版本落后时
 A2   — (AI 手写) —           Phase 3 输出 design.md + asset-manifest    无（AI 核心工作）
 A3   — (AI 手写) —           Phase 3 输出 art-prompts.md               A2 完成
 A4   — (AI 手写) —           Phase 3 输出 ThemeConfig + PageView.ts     A2 完成
 A5   generate-view.js        asset-manifest → XxxView.generated.ts     A2（manifest 已创建，UUID 可为 null）
 --- 此时代码可编译运行，Sprite 节点暂无纹理（白色占位）---
 --- 美术资源异步生成中... ---

 === Phase 3b: 资源绑定 + Prefab（需美术资源 + MCP） = 场景 H ===
 A6   resolve-asset-uuids.js  .meta 文件 → asset-manifest UUID 填充     美术资源已放入 assets/
 A7   generate-view.js        刷新 Layer 2（UUID 已填充）               A6 完成
 A8   design2prefab.js        design.md #4 + manifest → MCP Prefab      A7 + MCP Server 已启动
 A9   ui-dev-workflow.js      全部产出物 → V1-V4 验证报告               A8 完成

流程图：

=== Phase 3a（立即执行）===
sync-runtime ─→ AI 写 design.md + manifest + art-prompts + 代码
                        ↓
              generate-view（manifest UUID=null 也能生成骨架）
                        ↓
              代码可编译运行（白色占位 Sprite）

=== Phase 3b（美术到位后）=== 同场景 H
              美术资源放入 assets/
                        ↓
              resolve-asset-uuids ─→ generate-view（刷新）─→ design2prefab（MCP）
                                                                    ↓
                                                            ui-dev-workflow

场景 B：美术资源更新后刷新

步骤  脚本                    说明
─────────────────────────────────────────────────────────────
 B1   resolve-asset-uuids.js  重新扫描 → 更新路径 + 填充新 UUID
 B2   generate-view.js        重新生成 .generated.ts（manifest 变化了）
 B3   design2prefab.js        可选 — 如需重建 Prefab

场景 C：设计迭代（用户反馈修正后）

典型触发：Phase 3 首次输出 design.md 后，用户审阅并提出修改意见（如调整布局、增删节点、修改配色等），Agent 需要同步更新所有受影响的产出物。

步骤  操作                      说明                                     必须/可选
────────────────────────────────────────────────────────────────────────────────────
 C1   — (AI 手写) —             更新 design.md（按用户反馈修改受影响章节）    必须
 C2   — (AI 手写) —             同步更新 asset-manifest.json               必须（如资源清单有变化）
 C3   — (AI 手写) —             同步更新 assets/art-prompts.md             必须（如资源清单有变化）
 C4   resolve-asset-uuids.js    重新扫描 → 更新 UUID 映射                  必须（manifest 变化时）
 C5   generate-view.js          重新生成 .generated.ts                     必须（manifest 变化时）
 C6   design2prefab.js --dry-run 预览节点树变化                            推荐
 C7   design2prefab.js          正式重建 Prefab                            必须（节点树有变化时）
 C8   ui-dev-workflow.js        重新验证 V1-V4                             推荐

⚠️ 同步更新规则（不可违反）：

design.md 变化类型	asset-manifest.json	art-prompts.md	View.generated.ts	Prefab
仅文案/字号调整	—	—	—	重建
增删/重命名节点	同步增删条目	同步增删 Prompt	重新生成	重建
增删/替换图片资源	同步增删条目	同步增删 Prompt	重新生成	重建
布局/位置调整	—	—	—	重建
配色/风格调整	—	更新 Prompt 中的风格描述	—	重建

💡 简记：design.md 是 SSOT。凡 design.md 第6章（资源清单）有变化，asset-manifest.json 和 art-prompts.md 必须联动更新。Agent 禁止只改 design.md 而忘记同步其他文件。

场景 D：仅重建 Prefab（小幅调整后）

步骤  脚本                    说明
─────────────────────────────────────────────────────────────
 D1   design2prefab.js --dry-run   先预览节点树变化
 D2   design2prefab.js             确认无误后正式构建

场景 E：仅验证产出物完整性

步骤  脚本                    说明
─────────────────────────────────────────────────────────────
 E1   ui-dev-workflow.js      运行 V1-V4 验证，查看哪些产出物缺失或不一致

场景 F：新项目初始化

步骤  脚本                    说明
─────────────────────────────────────────────────────────────
 F1   sync-runtime.js --apply      同步全部 runtime 模板到项目
 F2   进入场景 A（A2 开始）

场景 G：框架/模板升级后批量刷新（Refresh）

典型触发：BaseView 升级（如 v1.0→v1.1 auto-bind）、generate-view.js 模板修改、runtime 模板 bug 修复等。
此场景仅刷新可安全重复生成的产物，设计阶段产物保持不变。

步骤  操作                                   说明                             条件
──────────────────────────────────────────────────────────────────────────────────────
 G1   sync-runtime.js --apply                同步 runtime 模板到项目           runtime 版本有更新时
 G2   resolve-asset-uuids.js --project <P>   刷新所有页面 manifest 的 UUID     UUID 有缺失/路径变更时
 G3   generate-view.js all                   批量重新生成所有 Layer 2          核心目的
 G4   构建 (node scripts/build.js)           编译验证                          —
 G5   E2E 测试                               验证不黑屏、UI 正常              —

场景 H：美术资源到位 + Prefab 创建（Phase 3b）

典型触发：Phase 3a 完成后，美术资源（部分或全部）已放入 assets/ 目录。
也用于「美术资源分批到位」的增量更新场景。

步骤  操作                                    说明                              前置条件
──────────────────────────────────────────────────────────────────────────────────────
 H1   resolve-asset-uuids.js --project <P>    Smart Discovery 填充 UUID         美术资源已放入 assets/
 H2   generate-view.js <page|all>             刷新 Layer 2（manifest 变化了）   H1 完成
 H3   design2prefab.js --project <P> <page>   MCP 创建 Prefab                   H2 + MCP Server 已启动
 H4   ui-dev-workflow.js --project <P> <page> V1-V4 验证                        H3 完成

增量模式：如果只有部分资源到位，可以仅执行 H1+H2 刷新绑定。等全部资源就位后再执行 H3+H4。
generate-view.js 只输出 status=ready|size_mismatch 的条目，pending 资源会被自动跳过。

⚠️ 术语规范："重新生成" vs "重新设计"

Agent 必须严格区分这两个指令，它们触发的场景和影响范围完全不同：

指令	含义	触发场景	涉及产物
"重新生成"	仅重新执行机械生成步骤，设计决策类产物保持不变	场景 G（批量刷新）/ B（资源更新）/ H（资源到位）	✅ 标记的产物：View.generated.ts、Runtime 模板、manifest UUID、Prefab
"重新设计"	完全重新开始 Phase 3，包括重写 design.md、重新规划节点树和资源清单	场景 C（设计迭代）/ A（新建）	全部产物，包括 ❌ 标记的：design.md、asset-manifest 条目、art-prompts.md、ThemeConfig

💡 简记："重新生成" = generate-view.js all（场景 G）。"重新设计" = AI 重写 design.md（场景 C/A）。

⚠️ 产物可重复性规范

关键问题：哪些产物可以安全重复生成？

类别	产物	可安全重复？	原因	触发条件
设计阶段（与 UI 设计绑定）
	design-dna.json	❌	全局 token SSOT，人工确认过	仅 UI 重新设计时
	design.md	❌	9章设计文档，与参考图/人工审阅绑定	仅 UI 重新设计时
	asset-manifest.json 条目结构	❌	条目与 design.md 第6章绑定	仅 design.md 变更时
	asset-manifest.json UUID 字段	✅	resolve-asset-uuids.js 自动扫描	资源变更/路径变更时
	art-prompts.md	❌	美术 Prompt 与 design.md 第6章对应	仅 UI 重新设计时
代码生成（可安全重复）
	XxxView.generated.ts (Layer 2)	✅	"generated" 就是设计来被覆盖的	场景 G/H/B
	XxxPageView.ts (Layer 3)	❌	人工业务逻辑，永不覆盖	仅新建时生成骨架
基建（可安全同步）
	Runtime 模板 (runtime/)	✅	skill 模板 → 项目，有版本控制	场景 G/F
Prefab（可重建）
	.prefab 文件	✅	从 design.md + manifest 重建	场景 D/H
主题/配置
	ThemeConfig.ts	⚠️	可能有手动调整	仅设计变更时

简记：❌ 的产物 = 设计决策类（需人工确认或 UI 重新设计才能改）。✅ 的产物 = 机械生成类（随时可从上游数据重新生成）。

脚本依赖关系图

                     ┌─────────────────────┐
                     │   sync-runtime.js   │ ← 首次/版本更新时执行
                     │ 🏗️ 基建（独立）      │
                     └─────────────────────┘

                     ┌─────────────────────┐
                     │ resolve-asset-uuids │ ← 美术资源变化后执行
                     │ ⚙️ 数据同步          │
                     └────────┬────────────┘
                              │ manifest UUID 已填充
                    ┌─────────┼─────────┐
                    ▼                   ▼
         ┌──────────────────┐  ┌─────────────────┐
         │ generate-view.js │  │ design2prefab.js │ ← 内部 require:
         │ ⚙️ Layer 2 代码   │  │ ⚙️ Prefab 生成   │    mcp-client.js (MCP 模式 = 正式)
         └──────────────────┘  │                  │    prefab-builder.js (Offline = 仅调试)
                               └────────┬─────────┘
                                        │ 所有产出物就绪
                                        ▼
                             ┌──────────────────────┐
                             │ ui-dev-workflow.js    │
                             │ ✅ V1-V4 验证         │
                             └──────────────────────┘

关键规则

1. 底层库不手动调用 — mcp-client.js 和 prefab-builder.js 由 design2prefab.js 内部 require()，Agent 无需直接运行
2. resolve 必须先于 generate/design2prefab — UUID 未填充就生成代码 = 资源绑定失败
3. generate-view 和 design2prefab 可并行 — 两者都只读 manifest，互不依赖（但习惯上先 generate-view 再 design2prefab）
4. ui-dev-workflow 放最后 — 它是验证全部产出物的最终关卡
5. sync-runtime 按需执行 — 非每次都跑，仅首次或 runtime 模板版本更新时

重要：Agent 在 Cocos Creator 项目中工作时，必须遵守 cocos-constraints.md 中的全部约束。核心规则：运行时代码中禁止使用 HTML/CSS/DOM/Web 框架，必须使用 Cocos 原生 API 和组件。