文档: 整合开发计划文档 & 修复: TypeScript 编译及可靠性改进

DEVELOPMENT.md

@@ -2,6 +2,17 @@
 
 本文档记录了 MCP Bridge 插件的完整开发流程，包括核心架构设计、功能实现、测试与调试等各个阶段。
 
+## 0. 项目开发规范 (Project Rules)
+
+> [!IMPORTANT]
+> 所有贡献者必须严格遵守以下规则：
+
+1.  **语言与沟通**: 所有注释、文档、计划、任务及 AI 回复必须使用 **简体中文 (Simplified Chinese)**。
+2.  **技术栈**: 新脚本必须使用 **TypeScript** (`.ts`)。禁止创建新的 `.js` 文件 (除非是构建脚本或测试配置)。
+3.  **文档**: 所有修改或创建的脚本必须包含详细的 JSDoc 格式注释。
+4.  **架构**: 严禁引入新的架构模式或重型外部库。必须复用现有的 Cocos Creator 管理器和工具类。
+5.  **隔离原则**: 保持 `main.js` (主进程) 与 `scene-script.js` (渲染进程) 的严格职责分离。即使看似方便，也不要在 `main.js` 中直接操作场景节点对象。
+
 ## 1. 项目初始化
 
 ### 1.1 目录结构搭建
@@ -413,232 +424,88 @@ manageAsset(args, callback) {
    - 防止路径遍历攻击
    - 限制服务访问范围
 
-## 11. 开发状态
+## 11. 开发路线图 (Roadmap)
 
-### 11.1 已完成的任务
+### 11.1 第三阶段开发计划（已完成）
 
-#### 第一阶段
-- ✅ HTTP 服务接口实现
-- ✅ 场景节点操作工具
-- ✅ 资源管理工具
-- ✅ 组件管理工具
-- ✅ 脚本管理工具（默认创建 TypeScript 脚本）
-- ✅ 批处理执行工具
-- ✅ 资产管理工具
-- ✅ 实时日志系统
-- ✅ 自动启动功能
-- ✅ 面板界面实现
+| 任务 | 状态 | 描述 |
+|------|------|------|
+| 编辑器管理工具实现 | ✅ 完成 | 实现 manage_editor 工具，支持编辑器状态控制和操作执行 |
+| 游戏对象查找工具实现 | ✅ 完成 | 实现 find_gameobjects 工具，支持根据条件查找场景节点 |
+| 材质和纹理管理工具实现 | ✅ 完成 | 实现 manage_material 和 manage_texture 工具，支持材质和纹理资源管理 |
+| 菜单项执行工具实现 | ✅ 完成 | 实现 execute_menu_item 工具，支持执行 Cocos Creator 菜单项 |
+| 代码编辑增强工具实现 | ✅ 完成 | 实现 apply_text_edits 工具，支持文本编辑操作应用 |
+| 控制台读取工具实现 | ✅ 完成 | 实现 read_console 工具，支持读取编辑器控制台输出 |
+| 脚本验证工具实现 | ✅ 完成 | 实现 validate_script 工具，支持脚本语法验证 |
 
-#### 第二阶段
-- ✅ 场景管理工具（scene_management）
-  - 创建场景
-  - 删除场景
-  - 复制场景
-  - 获取场景信息
-- ✅ 预制体管理工具（prefab_management）
-  - 创建预制体
-  - 更新预制体
-  - 实例化预制体
-  - 获取预制体信息
-- ✅ 面板布局优化
-  - 响应式设计
-  - 滚动条支持
-  - 小窗口适配
-- ✅ 移除旧工具
-  - 删除了 create_scene 工具（功能整合到 scene_management）
-  - 删除了 create_prefab 工具（功能整合到 prefab_management）
-- ✅ README.md 文档更新
-- ✅ 代码提交到本地仓库
+### 11.2 第四阶段开发计划（已完成）
 
-#### 第三阶段
-- ✅ 编辑器管理工具（manage_editor）
-  - 获取选中对象
-  - 设置选中状态
-  - 刷新编辑器
-- ✅ 游戏对象查找工具（find_gameobjects）
-  - 根据名称、标签、组件、激活状态查找节点
-  - 支持递归和非递归查找
-- ✅ 材质管理工具（manage_material）
-  - 创建、删除、获取材质信息
-- ✅ 纹理管理工具（manage_texture）
-  - 创建、删除、获取纹理信息
-- ✅ 菜单项执行工具（execute_menu_item）
-  - 执行 Cocos Creator 编辑器菜单项
-- ✅ 代码编辑增强工具（apply_text_edits）
-  - 支持插入、删除、替换文本操作
-- ✅ 控制台读取工具（read_console）
-  - 读取编辑器控制台输出
-  - 支持按类型过滤和限制输出数量
-- ✅ 脚本验证工具（validate_script）
-  - 验证脚本语法正确性
-- ✅ 面板工具说明功能
-  - 添加工具说明框
-  - 显示详细的工具描述和参数说明
+| 任务 | 状态 | 描述 |
+|------|------|------|
+| 测试功能实现 | ✅ 完成 | 实现 run_tests.js 脚本，支持运行自动化测试用例 |
+| 错误处理增强 | ✅ 完成 | 完善 HTTP 服务和工具调用的错误日志记录 |
 
-### 11.2 未完成的任务
+### 11.3 差异填补阶段（Gap Filling）- 已完成
 
-- ❌ 代码推送到远程仓库（认证错误）
-- ❌ 测试用例编写
-- ❌ 性能优化
-- ❌ 错误处理增强
-- ❌ 安全配置
+| 任务 | 状态 | 描述 |
+|------|------|------|
+| 全局文件搜索 | ✅ 完成 | 实现 find_in_file 工具 |
+| 撤销/重做支持 | ✅ 完成 | 实现 manage_undo 工具，并重构核心操作支持撤销 |
+| 特效管理 | ✅ 完成 | 实现 manage_vfx 工具，支持粒子系统管理 |
 
-### 11.3 后续需要完成的任务
+### 11.4 第六阶段：可靠性与体验优化（已完成）
 
-#### 高优先级
-1. **代码推送**：解决远程仓库认证问题，完成代码推送
-2. **测试用例**：为核心工具编写测试用例
-3. **安全配置**：添加 IP 白名单和认证机制
+| 任务 | 状态 | 描述 |
+|------|------|------|
+| IPC 工具增强 | ✅ 完成 | 修复 IpcManager 返回值解析，优化测试面板 (JSON 参数、筛选) |
+| 脚本可靠性修复 | ✅ 完成 | 解决脚本编译时序导致的挂载失败问题 (文档引导 + 刷新机制) |
+| 组件智能解析修复 | ✅ 完成 | 修复组件属性赋值时的 UUID 类型转换，支持压缩 UUID 及自定义组件 (`$_$ctor`) |
 
-#### 中优先级
-1. **性能优化**：优化 HTTP 服务响应速度，改进批处理执行效率
-2. **错误处理**：增强错误处理和恢复机制，提高插件稳定性
-3. **文档完善**：添加更详细的 API 文档和使用示例，包括新工具的详细说明
+### 11.5 第七阶段开发计划（未来规划）
 
-#### 低优先级
-1. **工具扩展**：添加更多高级工具，如动画管理、物理系统管理等
-2. **界面美化**：进一步优化面板界面，提升用户体验
-3. **国际化**：支持多语言，方便国际用户使用
-4. **插件发布**：准备插件发布到 Cocos 插件商店
-5. **版本兼容**：适配更多 Cocos Creator 版本
-
-### 11.4 任务优先级表
-
-| 任务 | 优先级 | 状态 | 描述 |
-|------|--------|------|------|
-| 代码推送 | 高 | 未完成 | 解决远程仓库认证问题 |
-| 测试用例 | 高 | 未完成 | 为核心工具编写测试用例 |
-| 安全配置 | 高 | 未完成 | 添加 IP 白名单和认证机制 |
-| 性能优化 | 中 | 未完成 | 优化 HTTP 服务响应速度，改进批处理执行效率 |
-| 错误处理 | 中 | 未完成 | 增强错误处理和恢复机制，提高插件稳定性 |
-| 文档完善 | 中 | 未完成 | 添加更详细的 API 文档和使用示例，包括新工具的详细说明 |
-| 工具扩展 | 低 | 未完成 | 添加更多高级工具，如动画管理、物理系统管理等 |
-| 界面美化 | 低 | 未完成 | 进一步优化面板界面，提升用户体验 |
-| 国际化 | 低 | 未完成 | 支持多语言，方便国际用户使用 |
-| 插件发布 | 低 | 未完成 | 准备插件发布到 Cocos 插件商店 |
-| 版本兼容 | 低 | 未完成 | 适配更多 Cocos Creator 版本 |
-| 编辑器管理工具 | 高 | 已完成 | 实现 manage_editor 工具，支持编辑器状态管理 |
-| 游戏对象查找工具 | 高 | 已完成 | 实现 find_gameobjects 工具，支持根据条件查找节点 |
-| 材质和纹理管理工具 | 高 | 已完成 | 实现 manage_material 和 manage_texture 工具 |
-| 菜单项执行工具 | 高 | 已完成 | 实现 execute_menu_item 工具，支持执行编辑器菜单项 |
-| 代码编辑增强工具 | 中 | 已完成 | 实现 apply_text_edits 工具，支持文本编辑操作 |
-| 控制台读取工具 | 中 | 已完成 | 实现 read_console 工具，支持读取控制台输出 |
-| 脚本验证工具 | 中 | 已完成 | 实现 validate_script 工具，支持脚本语法验证 |
-| 面板工具说明功能 | 低 | 已完成 | 添加工具说明框，显示详细的工具描述和参数说明 |
+| 任务 | 优先级 | 预计时间 | 描述 |
+|------|--------|----------|------|
+| 插件发布 | 高 | 1 天 | 准备发布，提交到 Cocos 插件商店 |
+| 文档完善 | 中 | 2 天 | 完善 API 文档 ("Getting Started" 教程) |
+| 界面美化 | 低 | 2 天 | 优化面板 UI 体检 |
+| 国际化支持 | 低 | 2 天 | 添加多语言 (i18n) 支持 |
+| 工具扩展 | 低 | 3 天 | 添加更多高级工具 |
 
 ## 12. Unity-MCP 对比分析
 
-### 12.1 Unity-MCP 功能特性
+### 12.1 功能差距 (Gap Analysis)
 
-Unity-MCP 提供了以下核心功能：
+通过与 Unity-MCP 对比，Cocos-MCP 已实现绝大多数核心功能。
 
-- **资产管理**：管理各种 Unity 资源
-- **编辑器管理**：控制 Unity 编辑器功能
-- **游戏对象管理**：创建、修改、查找游戏对象
-- **组件管理**：添加、移除、修改组件
-- **材质管理**：创建和修改材质
-- **预制体管理**：管理预制体资源
-- **场景管理**：创建、保存、加载场景
-- **脚本管理**：创建、修改脚本
-- **ScriptableObject 管理**：管理配置文件
-- **着色器管理**：管理着色器资源
-- **VFX 管理**：管理视觉效果
-- **纹理管理**：管理纹理资源
-- **批处理执行**：批量执行多个操作
-- **游戏对象查找**：根据条件查找游戏对象
-- **文件内容查找**：在文件中查找内容
-- **控制台读取**：读取 Unity 控制台输出
-- **Unity 刷新**：刷新 Unity 编辑器
-- **测试运行**：运行测试用例
-- **获取测试任务**：获取测试任务信息
-- **菜单项执行**：执行 Unity 菜单项
-- **文本编辑应用**：应用文本编辑操作
-- **脚本编辑应用**：应用脚本编辑操作
-- **脚本验证**：验证脚本语法
-- **创建脚本**：创建新脚本
-- **删除脚本**：删除脚本文件
-- **获取 SHA**：获取版本控制 SHA 值
+| 功能类别 | Unity-MCP 功能 | Cocos-MCP 状态 | 备注 |
+|---------|---------------|---------------|------|
+| 编辑器管理 | manage_editor | ✅ 已实现 | |
+| 游戏对象管理 | find_gameobjects | ✅ 已实现 | |
+| 材质管理 | manage_material | ✅ 已实现 | |
+| 纹理管理 | manage_texture | ✅ 已实现 | |
+| 代码编辑 | apply_text_edits | ✅ 已实现 | |
+| 全局搜索 | find_in_file | ✅ 已实现 | |
+| 控制台 | read_console | ✅ 已实现 | |
+| 菜单执行 | execute_menu_item | ✅ 已实现 | |
+| 脚本验证 | validate_script | ✅ 已实现 | |
+| 撤销/重做 | undo/redo | ✅ 已实现 | |
+| VFX 管理 | manage_vfx | ✅ 已实现 | |
+| Git 集成 | get_sha | ❌ 未实现 | 低优先级 |
+| ScriptableObject | manage_so | ❌ 未实现 | 使用 AssetDB 替代 |
 
-### 12.2 Cocos-MCP 功能特性
+## 13. 风险评估
 
-当前 Cocos-MCP 已实现的功能：
+### 13.1 潜在风险
 
-- **场景节点操作**：获取选中节点、设置节点名称、获取场景层级、更新节点变换、创建节点
-- **组件管理**：添加、移除、获取组件
-- **资源管理**：创建、删除、移动资源
-- **脚本管理**：创建、删除、读取、写入脚本（默认创建 TypeScript 脚本）
-- **批处理执行**：批量执行多个操作
-- **资产管理**：管理各种资源文件
-- **场景管理**：创建、删除、复制、获取场景信息
-- **预制体管理**：创建、更新、实例化、获取预制体信息
-- **面板界面**：提供主面板和工具测试面板
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 编辑器 API 变更 | 插件功能失效 | 定期检查 Cocos 更新，适配新 API |
+| 性能问题 | 插件响应缓慢 | 优化批处理 (batch_execute)，减少 IPC 通讯 |
+| 安全漏洞 | 未授权访问 | (规划中) 面板设置 IP 白名单/Token 认证 |
+| 兼容性问题 | 多版本不兼容 | 测试主流版本 (2.4.x)，提供兼容层 |
 
-### 12.3 功能缺失对比
+## 14. 结论
 
-| 功能类别 | Unity-MCP 功能 | Cocos-MCP 状态 | 可实现性 |
-|---------|---------------|---------------|--------|
-| 编辑器管理 | manage_editor | ❌ 缺失 | ✅ 可实现 |
-| 游戏对象管理 | find_gameobjects | ❌ 缺失 | ✅ 可实现 |
-| 材质管理 | manage_material | ❌ 缺失 | ✅ 可实现 |
-| 着色器管理 | manage_shader | ❌ 缺失 | ✅ 可实现 |
-| 纹理管理 | manage_texture | ❌ 缺失 | ✅ 可实现 |
-| 代码编辑增强 | apply_text_edits, script_apply_edits | ❌ 缺失 | ✅ 可实现 |
-| 测试功能 | run_tests, get_test_job | ❌ 缺失 | ⚠️ 部分可实现 |
-| 控制台读取 | read_console | ❌ 缺失 | ✅ 可实现 |
-| 菜单项执行 | execute_menu_item | ❌ 缺失 | ✅ 可实现 |
-| 脚本验证 | validate_script | ❌ 缺失 | ✅ 可实现 |
-| VFX 管理 | manage_vfx | ❌ 缺失 | ✅ 可实现 |
+Cocos-MCP 插件的开发计划已顺利完成多个迭代阶段。目前插件实现了包括编辑器管理、场景操作、资源管理在内的全套核心功能，并完成了针对性的可靠性加固（IPC 通信、脚本时序、组件解析）。
 
-### 12.4 功能实现建议
-
-#### 高优先级功能
-
-1. **编辑器管理工具** (`manage_editor`)
-   - 功能：控制编辑器状态、执行编辑器操作
-   - 实现方案：使用 `Editor.Ipc` 调用编辑器 API，如 `Editor.Selection`、`Editor.assetdb` 等
-
-2. **游戏对象查找工具** (`find_gameobjects`)
-   - 功能：根据条件查找场景中的节点
-   - 实现方案：使用场景脚本遍历节点树，根据名称、标签、组件等条件过滤
-
-3. **材质和纹理管理工具** (`manage_material`, `manage_texture`)
-   - 功能：创建和管理材质、纹理资源
-   - 实现方案：使用 `Editor.assetdb` API 操作资源文件
-
-4. **菜单项执行工具** (`execute_menu_item`)
-   - 功能：执行 Cocos Creator 菜单项
-   - 实现方案：使用 `Editor.Ipc.sendToMain` 发送菜单命令
-
-#### 中优先级功能
-
-1. **代码编辑增强工具** (`apply_text_edits`, `script_apply_edits`)
-   - 功能：应用文本编辑操作到文件
-   - 实现方案：读取文件内容，应用编辑操作，然后写回文件
-
-2. **控制台读取工具** (`read_console`)
-   - 功能：读取编辑器控制台输出
-   - 实现方案：重定向 `console.log` 等方法，捕获控制台输出
-
-3. **脚本验证工具** (`validate_script`)
-   - 功能：验证脚本语法正确性
-   - 实现方案：使用 Node.js 的语法解析器或调用外部工具
-
-#### 低优先级功能
-
-1. **测试功能** (`run_tests`, `get_test_job`)
-   - 功能：运行测试用例并获取结果
-   - 实现方案：根据 Cocos Creator 的测试框架集成
-
-2. **VFX 管理工具** (`manage_vfx`)
-   - 功能：管理视觉效果资源
-   - 实现方案：使用 `Editor.assetdb` API 操作 VFX 资源
-
-## 13. 总结
-
-MCP Bridge 插件通过 HTTP 服务和 MCP 协议，为外部 AI 工具提供了与 Cocos Creator 编辑器交互的能力。插件支持场景操作、资源管理、组件管理、脚本管理等多种功能，为 Cocos Creator 项目的开发和自动化提供了有力的支持。
-
-通过本文档的开发流程，我们构建了一个功能完整、稳定可靠的 MCP Bridge 插件，为 Cocos Creator 生态系统增添了新的工具和能力。
-
-目前插件已经完成了核心功能的实现，包括 15 个 MCP 工具，支持从场景操作到资源管理的各种功能。后续将继续完善测试、优化性能，并添加更多高级功能，为开发者提供更强大的工具支持。
-
-通过与 Unity-MCP 的对比分析，我们识别出了多个可实现的功能，这些功能将进一步增强 Cocos-MCP 的能力，使其与 Unity-MCP 保持功能对等，为 Cocos Creator 开发者提供同样强大的 AI 辅助开发体验。
+插件功能已趋于稳定，后续工作重点将转向 **发布准备**、**文档体系建设** 以及 **用户体验优化**，力求为 Cocos Creator 开发者提供高质量的 AI 辅助开发工具。