Cocos Creator 插件开发注意事项

1. 资源与预制体管理

问题：手动使用 manage_asset 创建或修改以 .meta 结尾的文件会导致编辑器报错（如 Invalid assetpath, must not use .meta as suffix）。
原因：Cocos Creator 资源数据库会自动识别新资源并生成对应的 .meta 文件。外部强行介入会破坏资源索引一致性。
最佳实践：始终使用高级资源工具（如 prefab_management）来处理资源，让编辑器自行管理 .meta 文件。

问题：在 Inspector 面板中，脚本属性（如 cc.Prefab 或 cc.Node）若通过路径关联，经常会出现 "Type Error"。
原因：编辑器 Inspector 期望获得的是引擎内部的对象引用。虽然 db:// 路径可以指向文件，但在属性赋值层面，编辑器无法自动将字符串路径转换为对应的类实例。
最佳实践：
1. 通过 manage_asset -> get_info 获取资源的 UUID。
2. 在调用 manage_components -> update 时，优先使用 UUID 进行赋值。
3. UUID 是底层唯一标识，能确保编辑器精准识别资源类型并正确完成引用链接。

注意事项：创建新脚本后，必须调用 manage_editor -> refresh_editor 或等待几秒钟以触发编译。
风险：在脚本编译完成前尝试将其作为组件添加到节点，会导致 添加组件失败: Cannot read property 'constructor' of null 或找不到脚本组件的问题。

正确协议：应使用 Editor.Ipc.sendToMain('scene:delete-nodes', uuid_or_array)。
注意：不要误用 scene:delete-selected，因为它在某些版本的编辑器底层不接受参数或行为不一致。
技巧：在 mcp-bridge 中，调用 execute_menu_item("delete-node:NODE_UUID") 会走场景脚本的直连删除，而 execute_menu_item("Delete") 则会走主进程的 scene:delete-nodes 并自动带上选中的节点。

改进点：在 scene-script.js 的 applyProperties 中通过 cc.AssetLibrary.loadAsset 解决了资源属性在 Inspector 报错 "Type Error" 的问题。
原理：
- 问题根源：在场景进程中直接将 UUID 字符串赋给资源属性（如 comp.prefab = "uuid"），会导致 .fire 文件将其保存为纯字符串而非对象格式。编辑器 Inspector 期望的是资源引用结构 { "__uuid__": "..." }，类型不匹配产生 Type Error。
- 修复逻辑：
  1. 真实加载：使用 cc.AssetLibrary.loadAsset(uuid, callback) 在场景进程中异步加载真实的资源实例。
  2. 实例赋值：在回调中将加载到的 asset 对象赋予组件（component[key] = asset），这确保了场景保存时能生成正确的序列化对象。
  3. UI 同步：同步发送 IPC scene:set-property，使用 { uuid: value } 格式通知编辑器面板更新 Inspector UI。
- Node/Component: 对于节点或组件引用，通过 findNode 查找实例并直接赋值实例对象，而非 UUID 字符串。

核心法则：任何对节点、组件、属性的操作，都必须建立在 “主体已确认存在” 的基础上。
具体流程：
1. 节点校验：在操作前必须调用 get_scene_hierarchy 确认 nodeId。
2. 组件校验：在 update 或 remove 前必须调用 manage_components(action: 'get') 确认目标组件存在。
3. 属性校验：严禁猜测属性名。在 update 前，应通过读取脚本定义或 get 返回的现有属性列表来确定准确的属性名称。
禁止行为：禁止基于假设进行盲目赋值或删除。如果发现对象不存在，应立即报错或尝试重建，而非继续尝试修改。

资产识别启发式：当通过 manage_components 赋值时，如果属性名包含以下关键字，插件会尝试将其作为 UUID 资源处理： prefab, sprite, texture, material, skeleton, spine, atlas, font, audio, data
建议：如果资源未正确加载，请检查属性名是否包含以上关键字，或手动确认该 UUID 不属于任何节点。 69: 70: --- 71: 72: ## 7. 搜索工具 (search_project) 使用建议 73: * 性能建议：尽量指定 path 参数缩小搜索范围（如 db://assets/scripts），避免全项目大面积搜索，尤其是在包含大量旧资源的 Library 目录（虽然插件已过滤）。 74: * 正则表达式：在使用 useRegex 时，确保正则模式的语法正确。如果正则匹配失败，工具会返回详细的错误提示。 75: * 模式选择： 76: * 查找具体逻辑代码：使用 matchType: "content"。 77: * 定位资源文件：使用 matchType: "file_name" 并配合 extensions 过滤。 78: * 重构目录结构前：使用 matchType: "dir_name" 检查目录名冲突。