feat: 修复节点变换属性竞态问题，扩展完整属性支持，增强获取数据工具

- fix: 将 update-node-transform 中 scaleX/scaleY 从异步 IPC 改为直接赋值，修复设置不生效 - fix: 将 color 从异步 IPC 改为直接赋值 (node.color = new cc.Color().fromHEX(color)) - feat: update_node_transform 新增 rotation/anchorX/anchorY/opacity/skewX/skewY 参数 - feat: get_scene_hierarchy includeDetails 新增 rotation/anchor/color/opacity/skew/group 返回 - feat: callSceneScriptWithTimeout 对 panel not found 错误返回友好中文提示 - docs: 更新 UPDATE_LOG.md/注意事项.md/project-rules.md 反映所有修改
2026-03-01 12:18:02 +08:00
parent a618497028
commit 77aba8e7f3
5 changed files with 153 additions and 108 deletions
--- a/.gemini/rules/project-rules.md
+++ b/.gemini/rules/project-rules.md
@@ -7,18 +7,20 @@ description: "MCP Bridge 插件开发规则和编码规范"

 ## 1. 语言规范 (Language)

-*   **强制中文**: 所有的对话回复、代码注释、以及生成的文档都必须使用**中文**。
-*   **日志消息**: `addLog()` 的消息内容可以使用中英文混合，确保关键术语清晰。
+- **强制中文**: 所有的对话回复、代码注释、以及生成的文档都必须使用**中文**。
+- **日志消息**: `addLog()` 的消息内容可以使用中英文混合，确保关键术语清晰。

 ---

 ## 2. 关键工作流程 (Critical Workflow)

 ### 2.1 插件重载
+
 - **必须重载**: 修改 `main.js`, `package.json`, `scene-script.js`, 或 `panel/` 后，**必须**在编辑器中执行「扩展 → 刷新」或重启编辑器。
 - **热更新不适用**: Cocos Creator 2.x 的插件主进程脚本不支持热更新。

 ### 2.2 测试驱动
+
 - **测试脚本**: 每个新功能必须在 `test/` 目录下创建独立测试脚本 (如 `test/test_feature.js`)。
 - **HTTP 验证**: 测试脚本通过 HTTP 请求直接调用插件 API，验证功能正确性。
 - **运行前提**: 确保 Cocos Creator 编辑器已打开且 MCP Bridge 服务已启动。
@@ -29,10 +31,10 @@ description: "MCP Bridge 插件开发规则和编码规范"

 ### 3.1 进程职责划分

-| 文件 | 进程 | 可访问 | 不可访问 |
-|------|------|--------|----------|
-| `main.js` | 主进程 (Main) | `Editor.assetdb`, `Editor.Ipc`, `require()` | `cc.*` (Cocos 引擎) |
-| `scene-script.js` | 渲染进程 (Renderer) | `cc.*`, `cc.engine`, `cc.director` | `Editor.assetdb`, `Editor.FileSystem` |
+| 文件              | 进程                | 可访问                                      | 不可访问                              |
+| ----------------- | ------------------- | ------------------------------------------- | ------------------------------------- |
+| `main.js`         | 主进程 (Main)       | `Editor.assetdb`, `Editor.Ipc`, `require()` | `cc.*` (Cocos 引擎)                   |
+| `scene-script.js` | 渲染进程 (Renderer) | `cc.*`, `cc.engine`, `cc.director`          | `Editor.assetdb`, `Editor.FileSystem` |

 ### 3.2 跨进程通信规则

@@ -59,14 +61,14 @@ description: "MCP Bridge 插件开发规则和编码规范"

 ### 4.1 命名规范

-| 类型 | 规范 | 示例 |
-|------|------|------|
-| 函数名 | camelCase | `handleMcpCall`, `manageScript` |
-| 常量 | SCREAMING_SNAKE_CASE | `MAX_RESULTS`, `DEFAULT_PORT` |
-| 私有变量 | _camelCase | `_isMoving`, `_timer` |
-| 布尔变量 | is/has/can 前缀 | `isSceneBusy`, `hasComponent` |
-| MCP 工具名 | snake_case | `get_selected_node`, `manage_vfx` |
-| IPC 消息名 | kebab-case | `get-hierarchy`, `create-node` |
+| 类型       | 规范                 | 示例                              |
+| ---------- | -------------------- | --------------------------------- |
+| 函数名     | camelCase            | `handleMcpCall`, `manageScript`   |
+| 常量       | SCREAMING_SNAKE_CASE | `MAX_RESULTS`, `DEFAULT_PORT`     |
+| 私有变量   | \_camelCase          | `_isMoving`, `_timer`             |
+| 布尔变量   | is/has/can 前缀      | `isSceneBusy`, `hasComponent`     |
+| MCP 工具名 | snake_case           | `get_selected_node`, `manage_vfx` |
+| IPC 消息名 | kebab-case           | `get-hierarchy`, `create-node`    |

 ### 4.2 函数组织顺序

@@ -76,28 +78,28 @@ description: "MCP Bridge 插件开发规则和编码规范"
 module.exports = {
    // 1. 配置属性
    "scene-script": "scene-script.js",
-    
+
    // 2. 生命周期函数
-    load() { },
-    unload() { },
-    
+    load() {},
+    unload() {},
+
    // 3. 服务器管理
-    startServer(port) { },
-    stopServer() { },
-    
+    startServer(port) {},
+    stopServer() {},
+
    // 4. 核心处理逻辑
-    handleMcpCall(name, args, callback) { },
-    
+    handleMcpCall(name, args, callback) {},
+
    // 5. 工具函数 (按字母顺序)
-    applyTextEdits(args, callback) { },
-    batchExecute(args, callback) { },
+    applyTextEdits(args, callback) {},
+    batchExecute(args, callback) {},
    // ...
-    
+
    // 6. IPC 消息处理
    messages: {
-        "open-test-panel"() { },
+        "open-test-panel"() {},
        // ...
-    }
+    },
 };
 ```

@@ -106,6 +108,7 @@ module.exports = {
 > ⚠️ **重要**: `main.js` 已存在重复函数问题，编辑前务必使用 `view_file` 确认上下文，避免创建重复定义。

 **检查清单**:
+
 - [ ] 新增函数前，搜索是否已存在同名函数
 - [ ] 修改函数时，确认只有一个定义
 - [ ] `messages` 对象中避免重复的消息处理器
@@ -122,16 +125,16 @@ addLog("mcp", `REQ -> [${toolName}]`);
 addLog("success", `RES <- [${toolName}] 成功`);

 // ❌ 错误
-console.log("服务启动成功");  // 不会被 read_console 捕获
+console.log("服务启动成功"); // 不会被 read_console 捕获
 ```

-| type | 用途 | 颜色 |
-|------|------|------|
-| `info` | 一般信息 | 蓝色 |
-| `success` | 操作成功 | 绿色 |
-| `warn` | 警告信息 | 黄色 |
-| `error` | 错误信息 | 红色 |
-| `mcp` | MCP 请求/响应 | 紫色 |
+| type      | 用途          | 颜色 |
+| --------- | ------------- | ---- |
+| `info`    | 一般信息      | 蓝色 |
+| `success` | 操作成功      | 绿色 |
+| `warn`    | 警告信息      | 黄色 |
+| `error`   | 错误信息      | 红色 |
+| `mcp`     | MCP 请求/响应 | 紫色 |

 ---

@@ -148,13 +151,15 @@ Editor.Ipc.sendToPanel("scene", "scene:set-property", {
    path: "x",
    type: "Float",
    value: 100,
-    isSubProp: false
+    isSubProp: false,
 });

-// ❌ 不支持 Undo (直接修改)
+// ⚠️ 不支持 Undo，但同步生效（update-node-transform 使用此方式）
 node.x = 100;
 ```

+> **注意**: `update-node-transform` 中所有 13 个属性均使用直接赋值方式，这是为了解决异步 IPC 竞态条件导致属性不生效的问题。此为设计性 trade-off：牺牲 Undo 支持以保证属性即时可靠生效。
+
 ### 5.2 使用 Undo 组

 对于复合操作，使用 Undo 组包装：
@@ -193,7 +198,7 @@ const defaultPaths = [
    "db://internal/image/default_sprite_splash",
    "db://internal/image/default_sprite_splash.png",
    "db://internal/image/default_particle",
-    "db://internal/image/default_particle.png"
+    "db://internal/image/default_particle.png",
 ];

 for (const path of defaultPaths) {
@@ -226,12 +231,12 @@ setTimeout(() => {

 ```javascript
 // ✅ 标准风格
-callback(null, result);           // 成功
-callback("Error message");        // 失败 (字符串)
-callback(new Error("message"));   // 失败 (Error 对象)
+callback(null, result); // 成功
+callback("Error message"); // 失败 (字符串)
+callback(new Error("message")); // 失败 (Error 对象)

 // 避免混用
-callback(err, null);              // 不推荐，保持一致性
+callback(err, null); // 不推荐，保持一致性
 ```

 ### 7.2 异步操作错误处理
@@ -252,22 +257,22 @@ Editor.assetdb.queryInfoByUrl(path, (err, info) => {

 使用 [Conventional Commits](https://conventionalcommits.org/) 格式：

-| 类型 | 用途 | 示例 |
-|------|------|------|
-| `feat` | 新功能 | `feat: add manage_vfx tool` |
-| `fix` | 修复 bug | `fix: resolve duplicate function in main.js` |
-| `docs` | 文档更新 | `docs: add code review report` |
-| `refactor` | 重构 | `refactor: split main.js into modules` |
-| `test` | 测试 | `test: add material management tests` |
-| `chore` | 杂项 | `chore: update dependencies` |
+| 类型       | 用途     | 示例                                         |
+| ---------- | -------- | -------------------------------------------- |
+| `feat`     | 新功能   | `feat: add manage_vfx tool`                  |
+| `fix`      | 修复 bug | `fix: resolve duplicate function in main.js` |
+| `docs`     | 文档更新 | `docs: add code review report`               |
+| `refactor` | 重构     | `refactor: split main.js into modules`       |
+| `test`     | 测试     | `test: add material management tests`        |
+| `chore`    | 杂项     | `chore: update dependencies`                 |

 ---

 ## 9. 已知问题 (Known Issues)

-| 问题 | 原因 | 解决方案 |
-|------|------|----------|
-| "Unknown object to record" 错误 | Cocos 2.4.x Undo 系统与 MCP 交互问题 | 可忽略，不影响功能 |
-| "sendToMain scene:stash-and-save failed" | 时序问题 | 手动 Ctrl+S 保存 |
-| 颜色修改不支持 Undo | 使用 scene-script 直接修改 | 待优化 |
-| execute_menu_item 仅支持部分菜单 | 缺乏通用菜单 IPC | 添加菜单映射表 |
+| 问题                                     | 原因                                  | 解决方案                           |
+| ---------------------------------------- | ------------------------------------- | ---------------------------------- |
+| "Unknown object to record" 错误          | Cocos 2.4.x Undo 系统与 MCP 交互问题  | 可忽略，不影响功能                 |
+| "sendToMain scene:stash-and-save failed" | 时序问题                              | 手动 Ctrl+S 保存                   |
+| `update-node-transform` 不支持 Undo      | 为解决异步 IPC 竞态问题，改用直接赋值 | 设计性 trade-off，保证属性即时生效 |
+| execute_menu_item 仅支持部分菜单         | 缺乏通用菜单 IPC                      | 添加菜单映射表                     |