mcp-bridge/CODE_REVIEW.md

MCP Bridge 插件代码审查报告

审查日期: 2026-02-02
审查人: AI Assistant

📋 审查概要

项目	状态
代码行数	main.js (1560行), scene-script.js (560行)
测试脚本	4个 (run_tests.js, test_find_file.js, test_undo.js, test_vfx.js)
功能完成度	高 - 大部分核心功能已实现
代码质量	中等 - 存在重复代码和结构问题

---

🔴 高优先级问题 (需要立即修复)

1. 重复函数定义 (严重)

在 main.js 中发现以下重复定义的函数：

函数名	第一次出现	第二次出现
validateScript	行 1337-1369	行 1424-1456
get-server-state (message)	行 1375-1377	行 1408-1415
executeMenuItem	行 1243-1254	行 1317-1335 (同名但实现不同)

⚠️ 警告: 重复函数会导致后定义的覆盖先定义的，可能造成意外行为。第二个 validateScript (行 1424-1456) 使用了 loadMeta 而不是 loadAny，可能无法正确读取脚本内容。

建议修复:

• 删除重复的 validateScript 函数 (保留行 1337-1369 的版本，它使用 loadAny)
• 合并两个 get-server-state 消息处理器 (第二个更完整，包含 autoStart)
• 审查并合并两个 executeMenuItem 的实现

---

2. TypeScript 脚本验证缺失

// 对于 TypeScript 脚本，这里可以添加更复杂的验证逻辑
callback(null, { valid: true, message: 'Script syntax is valid' });

validate_script 工具对 TypeScript .ts 文件没有实际验证逻辑，直接返回 valid: true。

建议修复:

• 集成 TypeScript 编译器进行语法检查
• 或者使用 require('typescript').transpileModule() 进行基本验证

---

🟡 中优先级问题 (建议修复)

3. 菜单项执行功能受限

// 通用尝试 (可能不工作，取决于编辑器版本)
// Editor.Ipc.sendToMain('ui:menu-click', menuPath); 
// 兜底：仅记录日志，暂不支持通用菜单点击
addLog("warn", "Generic menu execution partial support.");

execute_menu_item 工具只对 File/Save Scene 有实际作用，其他菜单项仅记录日志。

建议修复:

• 调研 Cocos Creator 2.4.x 的菜单执行 IPC 接口
• 或者添加常用菜单项的映射表

---

4. 颜色属性 Undo 不支持

// 暂且忽略颜色的 Undo，先保证 Transform 的 Undo。
Editor.Scene.callSceneScript("mcp-bridge", "update-node-transform", { id, color }, (err) => {
    if (err) addLog("warn", "Color update failed or partial");
});

update_node_transform 中位置和缩放使用 scene:set-property 支持 Undo，但颜色通过 scene-script 修改，不支持 Undo。

建议修复:

• 研究如何通过 scene:set-property 设置颜色属性

---

5. 材质/纹理创建功能不完整

manage_material 和 manage_texture 的 create 操作创建的是 JSON 元数据文件，而不是真正的材质或纹理资源。

// 创建材质资源
const materialContent = JSON.stringify({
    __type__: "cc.Material",
    // ...
});

建议修复:

• 文档中说明此工具的限制
• 或者使用 Cocos Creator 的资源创建 API

---

🟢 低优先级问题 (可优化)

6. 缺失的功能模块

根据 DEVELOPMENT_PLAN.md，以下功能未完全实现或可扩展：

功能	状态	说明
Git 集成 (get_sha)	❌ 未实现	获取当前版本库信息
ScriptableObject 管理	❌ 未实现	类似 Unity 的 ScriptableObject
国际化支持	❌ 未实现	多语言界面
插件商店发布	❌ 未完成	打包和发布流程

---

7. 代码结构优化建议

1. 拆分 main.js: 1560 行代码过于庞大，建议拆分为：

   • tools/scene-tools.js - 场景相关工具
   • tools/asset-tools.js - 资源管理工具
   • tools/editor-tools.js - 编辑器控制工具

2. 统一错误处理: 部分函数直接 return callback(error)，部分使用 callback(err, null)，建议统一风格。

3. 添加 JSDoc 注释: 核心函数缺少文档注释。

---

8. 测试覆盖不完整

目前测试脚本仅覆盖：

• ✅ 基础连接和节点操作 (run_tests.js)
• ✅ 文件搜索 (test_find_file.js)
• ✅ 撤销/重做 (test_undo.js)
• ✅ 粒子系统 (test_vfx.js)

未覆盖的功能：

• ❌ manage_material / manage_texture
• ❌ scene_management / prefab_management
• ❌ apply_text_edits
• ❌ batch_execute

---

📌 修复优先级排序

序号	问题	优先级	预计工时
1	删除重复函数	🔴 高	0.5h
2	合并 get-server-state	🔴 高	0.5h
3	TypeScript 验证	🟡 中	2h
4	菜单执行增强	🟡 中	1h
5	颜色 Undo 支持	🟡 中	1h
6	测试覆盖扩展	🟢 低	4h
7	代码拆分重构	🟢 低	8h

---

🚀 下一步行动建议

1. 立即修复: 删除 main.js 中的重复函数定义
2. 短期: 完善 TypeScript 验证和测试覆盖
3. 中期: 优化代码结构，拆分大文件
4. 长期: 实现 Git 集成，准备插件商店发布

---

📝 附录：已实现功能清单

工具名称	状态	说明
get_selected_node	✅	获取选中节点
set_node_name	✅	修改节点名称
save_scene	✅	保存场景
get_scene_hierarchy	✅	获取场景层级
update_node_transform	✅	修改节点变换
create_scene	✅	创建场景
create_prefab	✅	创建预制体
open_scene	✅	打开场景
create_node	✅	创建节点
manage_components	✅	管理组件
manage_script	✅	管理脚本
batch_execute	✅	批量执行
manage_asset	✅	管理资源
scene_management	✅	场景管理
prefab_management	✅	预制体管理
manage_editor	✅	编辑器管理
find_gameobjects	✅	查找节点
manage_material	⚠️	部分实现
manage_texture	⚠️	部分实现
execute_menu_item	⚠️	部分实现
apply_text_edits	✅	文本编辑
read_console	✅	读取控制台
validate_script	⚠️	仅支持 JS
find_in_file	✅	文件搜索
manage_undo	✅	撤销/重做
manage_vfx	✅	粒子系统