新增 find_references 引用查找工具及 Texture2D 子资源自动解析

- 新增 find-references IPC 处理函数,递归遍历场景节点组件属性查找引用

- 新增 UUID 格式自动规范化(压缩/解压格式全量匹配)

- 新增 Texture2D -> SpriteFrame 子资源 UUID 自动解析

- 更新 UPDATE_LOG.md、注意事项.md、README.md 文档
This commit is contained in:
火焰库拉
2026-03-01 00:32:59 +08:00
parent 74d49d79c1
commit a618497028
5 changed files with 1507 additions and 1208 deletions

View File

@@ -158,3 +158,26 @@
- `scene-script.js` 内部在执行 `manage_components(get)` 序列化时,对于**长度超过 10 的 Array** 会强制截断,返回字面量字符串 `"[Array(X)]"`
- 对于**长度大于 200 的长字符串**,也会强制缩略并追加 `...[Truncated, total length: X]`
- **应对策略**:如果 AI 看到截断提示,这意味着此处为海量无语义数据,**请勿**尝试盲目通过 `update` 覆盖或还原被截断的字段,极易导致源数据被破坏。请仅修改自己能够完全看清的轻量级属性(如 `name`, `x`, `scale` 等)。
---
## 11. 引用查找 (`find_references`) 与 UUID 自动解析
### 11.1 引用查找工具用途
- **功能**: `find_references` 工具可查找当前场景中所有引用了指定节点或资源的位置,返回引用所在节点、组件类型、属性名等详细信息。
- **应用场景**:
- 删除节点或预制体前,检查是否有组件属性引用了它,防止脚本报错。
- 替换资源(如更换 SpriteFrame快速定位所有使用了旧资源的组件。
- 分析场景依赖关系,辅助重构。
### 11.2 UUID 格式差异与自动规范化
- **背景**: Cocos Creator 2.x 中 `cc.Asset._uuid` 使用 22 位压缩 UUID 格式,而 `Editor.assetdb` 返回标准 36 位带连字符 UUID同一资源的两种表示在字符串层面不相等。
- **机制**: `find-references` 处理函数通过 `Editor.Utils.UuidUtils.compressUuid/decompressUuid` 自动预计算所有格式变体,存入 `targetVariants` 数组进行全量匹配。无需人工关心 UUID 格式。
### 11.3 Texture2D 与 SpriteFrame 子资源解析
- **问题**: AI 传入图片 (Texture2D) 的 UUID 时,`cc.Sprite.spriteFrame` 实际引用的是该图片的子资源 SpriteFrame具有不同的 UUID导致直接查找返回空结果。
- **解决方案**: `main.js` 在调用 scene-script 前,自动读取目标 UUID 对应的 `.meta` 文件,提取 `subMetas` 中所有子资源 UUID作为 `additionalIds` 一并传递。scene-script 对这些额外 UUID 同样执行压缩/解压规范化后加入匹配列表。
- **效果**: 无论传入 Texture2D UUID 还是 SpriteFrame UUID`find_references` 均能正确返回所有引用位置。