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 脚本验证缺失

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

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

**建议修复**:
- 集成 TypeScript 编译器进行语法检查
- 或者使用 `require('typescript').transpileModule()` 进行基本验证

---

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

### 3. 菜单项执行功能受限

```javascript
// 通用尝试 (可能不工作，取决于编辑器版本)
// 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 不支持

```javascript
// 暂且忽略颜色的 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 元数据文件，而不是真正的材质或纹理资源。

```javascript
// 创建材质资源
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` | ✅ | 粒子系统 |