cc-3-8-x-mcp/doc/prefab-direct-edit.md

Prefab 直改流程指南

目标读者：使用 Claude Code / MCP agent 操作 CC3.8.x prefab 的开发者。 本文聚焦决策和流程：什么时候用哪条路径、改完要做什么、有哪些已知坑。 prefab 文件结构细节见 prefab-schema.md，不在此重复。

---

为什么绕过 Cocos 编辑器直改 prefab 文件

Cocos Creator 编辑器将 prefab 序列化为 JSON 文件存储在磁盘上。传统工作流需要打开 GUI → 在场景树里手动操作 → 保存，这在以下场景无法工作：

• 无头环境：CI / MCP agent / 自动化脚本，没有显示器或不方便启动编辑器。
• 批量修改：几十个 prefab 同步改文字、布局参数，手动操作成本极高。
• 可重复性：工具链幂等产物（A/B 变体、多语言注入），需要确定性结果而非 GUI 点击。

直改文件可以做到零 GUI 依赖、秒级完成、可 diff 审计。代价是需要精确理解 prefab 格式，错误写入可能让编辑器报解析错误或静默破坏数据。

---

整体架构

Claude Code / MCP agent
        │
        ▼
    router.js（cc-3-8-x-mcp）
        │
        ├── offline tools（via cli 模块，纯文件 I/O）
        │       ├── prefab_query   →  cli/src/parse.js + query.js
        │       ├── prefab_edit    →  cli/src/write.js + overrides.js
        │       └── prefab_batch   →  cli/src/batch.js
        │
        └── editor tools（via HTTP → Cocos 扩展进程）
                ├── asset_reimport / asset_refresh
                ├── scene_query / scene_set_property
                ├── preview_screenshot
                └── editor_eval

offline tools：读写本地 .prefab 文件，不需要编辑器在线。适合批量、自动化场景。

editor tools：通过 HTTP 与运行中的 Cocos Creator 编辑器通信（扩展监听固定端口）。可以操作运行时场景、触发资源重新导入、截图等。需要编辑器已启动且扩展已加载。

---

决策表：用 offline 还是 editor？

操作	推荐路径	原因
改普通节点 position / active	offline（prefab_edit）	直接改文件字段，秒级完成
改普通节点 Label 文字	offline（prefab_edit）	同上
改普通节点 SpriteFrame	offline（prefab_batch，op: set-sprite-frame）	set 子命令不支持，必须走 batch
改 stub 节点普通字段（position / active）	offline（prefab_edit）	工具自动路由到 propertyOverrides
改 stub 节点组件字段（Label._string / Sprite._spriteFrame）	当前不支持	需跨 prefab 读取组件 fileId，未实现；必须在编辑器里手改
查节点树结构	offline（prefab_query）更快	纯文件解析，无需编辑器在线；但看不到运行时动态状态
查运行时节点状态（动画、数据绑定后）	editor（scene_query）	运行时才有真实数据
触发资源重新导入	editor（asset_reimport）	必须让编辑器重建 UUID 索引
预览截图	editor（preview_screenshot）	只有编辑器能渲染
在预览中执行 JS	editor（editor_eval）	需要运行时上下文
改运行时场景节点（非 prefab 文件）	editor（scene_set_property）	场景节点不存在离线文件可直改

---

offline 改完后的操作流程

直接改 .prefab 文件后，编辑器需要重新加载才能感知变化。有两种方式：

方式 A：仅重新导入资产

editor tool: asset_reimport
  参数: { "path": "assets/packages/game/home/ui/HomeUI.prefab" }

让编辑器重建该 prefab 的内部索引（UUID 映射、子资产列表）。适合只改了 prefab 内容、不涉及其他资产变动的情况。

方式 B：整链路刷新（改动较大时）

editor tool: preview_refresh_and_reload

触发编辑器重新加载所有修改过的资产并刷新预览。改动多个文件时用此方式，避免缓存不一致。

重要：offline 改完不做 reimport，编辑器下次保存 prefab 时可能用旧的序列化数据覆盖你的修改。

---

踩坑清单

坑 1：stub 节点直改字段永远无效

嵌套 prefab 的 stub 节点在父 prefab 中通常只有五个字段（__type__、_objFlags、_parent、_prefab、__editorExtras__），其余属性全在 cc.PrefabInstance.propertyOverrides 里。直接改 stub 节点的 _lpos 或 _active 字段，编辑器加载时会用 propertyOverrides 覆盖回去，修改静默丢失。

→ offline 工具已自动处理：检测到 stub 节点时自动路由到 propertyOverrides 写入。 → 手写 ops.json 绕过高层 API 时，必须自己判断 instance !== null 再决定写哪里。 → 详见 prefab-schema.md § 4。

坑 2：nestedPrefabInstanceRoots 不同步导致静默数据损坏

根节点 cc.PrefabInfo.nestedPrefabInstanceRoots 是 CC3 编辑器识别所有嵌套 prefab stub 的总索引。新增嵌套实例时如果忘记把 stub 节点引用加进这个数组，编辑器不会报错，但在下次保存 prefab 时会把嵌套引用关系覆盖掉，造成子组件引用丢失。

→ offline 工具的 editPrefab 路径已自动维护该列表。 → 手动拼 op 绕过高层 API 时必须自己维护。 → 详见 prefab-schema.md § 4 坑二 和 cli/README.md 地雷二。

坑 3：stub 节点组件字段当前不支持离线写入

覆写 stub 节点的组件字段（如 cc.Label._string、cc.Sprite._spriteFrame）需要跨 prefab 文件读取该组件的 cc.CompPrefabInfo.fileId，当前 offline 工具未实现该能力。调用时会抛 unsupported 错误并不落盘。

当前 workaround：在 Cocos 编辑器里手动改这类属性，或通过 editor tool: scene_set_property 在运行时改（重启后失效）。后续版本将在 overrides.js 中实现跨 prefab fileId 查找。

→ 详见 cli/README.md 地雷一。