mirror of
https://github.com/HappyLifeOk/cc-3-8-x-mcp.git
synced 2026-06-10 17:56:47 +00:00
furao
14c5b00f14
Cocos Creator 3.8.x MCP bridge extension with a built-in offline CLI. Components: - Editor extension: in-process MCP server exposing scene / asset-db / preview / local / editor-process-control tools - stdio router: aggregates multiple editor instances on one machine, with shortName dedup - offline CLI (cocos-mcp-cli): headless prefab read/write + a wrapper around the Cocos CLI build Pure Node.js, zero third-party dependencies. Licensed under Apache-2.0.
115 lines
6.0 KiB
Markdown
115 lines
6.0 KiB
Markdown
# Prefab 直改流程指南
|
||
|
||
> 目标读者：使用 Claude Code / MCP agent 操作 CC3.8.x prefab 的开发者。
|
||
> 本文聚焦**决策和流程**：什么时候用哪条路径、改完要做什么、有哪些已知坑。
|
||
> prefab 文件结构细节见 [prefab-schema.md](./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](./prefab-schema.md)。
|
||
|
||
### 坑 2：nestedPrefabInstanceRoots 不同步导致静默数据损坏
|
||
|
||
根节点 `cc.PrefabInfo.nestedPrefabInstanceRoots` 是 CC3 编辑器识别所有嵌套 prefab stub 的总索引。新增嵌套实例时如果忘记把 stub 节点引用加进这个数组，编辑器不会报错，但在下次保存 prefab 时会把嵌套引用关系覆盖掉，造成子组件引用丢失。
|
||
|
||
→ offline 工具的 `editPrefab` 路径已自动维护该列表。
|
||
→ 手动拼 op 绕过高层 API 时必须自己维护。
|
||
→ 详见 [prefab-schema.md § 4 坑二](./prefab-schema.md) 和 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 地雷一。
|