CocosPlugin/mcp-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ca9fcabefd88b3e5937c50fb2fd40fccf8a03218
mcp-bridge/DEVELOPMENT_PLAN.md

630 lines
21 KiB
Markdown
Raw Normal View History

feat: Implement VFX management, Undo/Redo, Find in File; docs: Update README and plans
2026-02-01 13:30:11 +08:00
# Cocos-MCP 开发计划文档
## 1. 项目概述
### 1.1 项目背景
Cocos-MCP (Model Context Protocol) 插件是一个为 Cocos Creator 编辑器提供外部 AI 工具交互能力的桥梁。通过 HTTP 服务和 MCP 协议，插件允许外部 AI 工具（如 Cursor、VS Code 等）直接与 Cocos Creator 编辑器进行交互，实现场景操作、资源管理、脚本编辑等功能。
### 1.2 项目目标
- 提供与 Unity-MCP 对等的功能集，使 Cocos Creator 开发者获得同样强大的 AI 辅助开发体验
- 实现编辑器管理、游戏对象查找、材质/纹理管理等高级功能
- 优化现有功能，提高插件稳定性和性能
- 建立完善的测试和部署流程
### 1.3 技术栈
- **开发语言**：JavaScript/TypeScript
- **运行环境**：Node.js (Cocos Creator 内置)
- **通信协议**：HTTP + JSON (MCP 协议)
- **编辑器 API**：Cocos Creator 2.4.x Editor API
- **界面技术**：HTML/CSS + Cocos Creator 面板 API
## 2. 功能分析
### 2.1 Unity-MCP 功能参考
Unity-MCP 提供了以下核心功能：
| 功能类别 | 具体功能 | 描述 |
|---------|---------|------|
| 编辑器管理 | manage_editor | 控制 Unity 编辑器状态和操作 |
| 游戏对象管理 | find_gameobjects | 根据条件查找游戏对象 |
| 材质管理 | manage_material | 创建和管理材质资源 |
| 着色器管理 | manage_shader | 管理着色器资源 |
| 纹理管理 | manage_texture | 管理纹理资源 |
| 代码编辑增强 | apply_text_edits | 应用文本编辑操作到文件 |
| 测试功能 | run_tests | 运行测试用例 |
| 控制台读取 | read_console | 读取编辑器控制台输出 |
| 菜单项执行 | execute_menu_item | 执行编辑器菜单项 |
| 脚本验证 | validate_script | 验证脚本语法 |
| VFX 管理 | manage_vfx | 管理视觉效果资源 |
### 2.2 Cocos-MCP 现状分析
#### 已实现功能
- **场景节点操作**：获取选中节点、设置节点名称、获取场景层级、更新节点变换、创建节点
- **组件管理**：添加、移除、获取组件
- **资源管理**：创建、删除、移动资源
- **脚本管理**：创建、删除、读取、写入脚本（默认创建 TypeScript 脚本）
- **批处理执行**：批量执行多个操作
- **资产管理**：管理各种资源文件
- **场景管理**：创建、删除、复制、获取场景信息
- **预制体管理**：创建、更新、实例化、获取预制体信息
- **面板界面**：提供主面板和工具测试面板
- **编辑器管理**：控制编辑器状态、执行编辑器操作
- **游戏对象查找**：根据条件查找场景中的节点
- **材质管理**：创建和管理材质资源
- **着色器管理**：管理着色器资源
- **纹理管理**：管理纹理资源
- **代码编辑增强**：应用文本编辑操作到文件
- **测试功能**：运行自动化测试用例 (`run_tests.js`)
- **控制台读取**：读取编辑器控制台输出
- **菜单项执行**：执行编辑器菜单项
- **脚本验证**：验证脚本语法
#### 缺失功能
- **VFX 管理**：管理视觉效果资源（暂未排期）
### 2.3 功能优先级排序
所有高/中优先级功能均已完成。
### 2.4 Unity-MCP 差异分析 (Gap Analysis)
通过对比 [Unity-MCP](https://github.com/CoplayDev/unity-mcp)，发现以下缺失或可增强的功能：
1. **全局搜索 (`find_in_file`)**: ✅ 已实现。支持在整个项目中搜索文本内容。
2. **ScriptableObject 管理 (`manage_scriptable_object`)**: 虽然 AssetDB 可以创建资源，但缺乏专门针对 ScriptableObject (cc.Asset) 的简便创建工具。
3. **Undo/Redo 支持**: ✅ 已实现。通过 `manage_undo` 提供了 `undo/redo` 及事务组支持。
4. **VFX 管理 (`manage_vfx`)**: ✅ 已实现。支持粒子系统的创建、修改和信息获取。
5. **Git 集成 (`get_sha`)**: 获取当前版本库信息。
`find_in_file`、`Undo/Redo` 和 `manage_vfx` 已在最新迭代中完成。
## 3. 开发路线图
### 3.1 第三阶段开发计划（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| 编辑器管理工具实现 | ✅ 完成 | 实现 manage_editor 工具，支持编辑器状态控制和操作执行 |
| 游戏对象查找工具实现 | ✅ 完成 | 实现 find_gameobjects 工具，支持根据条件查找场景节点 |
| 材质和纹理管理工具实现 | ✅ 完成 | 实现 manage_material 和 manage_texture 工具，支持材质和纹理资源管理 |
| 菜单项执行工具实现 | ✅ 完成 | 实现 execute_menu_item 工具，支持执行 Cocos Creator 菜单项 |
| 代码编辑增强工具实现 | ✅ 完成 | 实现 apply_text_edits 工具，支持文本编辑操作应用 |
| 控制台读取工具实现 | ✅ 完成 | 实现 read_console 工具，支持读取编辑器控制台输出 |
| 脚本验证工具实现 | ✅ 完成 | 实现 validate_script 工具，支持脚本语法验证 |
### 3.2 第四阶段开发计划（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| 测试功能实现 | ✅ 完成 | 实现 run_tests.js 脚本，支持运行自动化测试用例 |
| 错误处理增强 | ✅ 完成 | 完善 HTTP 服务和工具调用的错误日志记录 |
### 3.3 差异填补阶段（Gap Filling）- 已完成
| 任务 | 状态 | 描述 |
|------|------|------|
| 全局文件搜索 | ✅ 完成 | 实现 find_in_file 工具 |
| 撤销/重做支持 | ✅ 完成 | 实现 manage_undo 工具，并重构核心操作支持撤销 |
| 特效管理 | ✅ 完成 | 实现 manage_vfx 工具，支持粒子系统管理 |
### 3.3 第五阶段开发计划（远期）
| 任务 | 优先级 | 预计时间 | 描述 |
|------|--------|----------|------|
| 工具扩展 | 低 | 3 天 | 添加更多高级工具和功能 |
| 界面美化 | 低 | 2 天 | 进一步优化面板界面，提升用户体验 |
| 国际化支持 | 低 | 2 天 | 添加多语言支持 |
| 文档完善 | 中 | 2 天 | 完善 API 文档和使用示例 |
| 插件发布 | 高 | 1 天 | 准备插件发布，提交到 Cocos 插件商店 |
## 4. 技术架构
### 4.1 系统架构
```
┌────────────────────┐ HTTP ┌────────────────────┐ IPC ┌────────────────────┐
│ 外部 AI 工具 │ ──────────> │ main.js (HTTP服务) │ ─────────> │ scene-script.js │
│ (Cursor/VS Code) │ <──────── │ (MCP 协议处理) │ <──────── │ (场景操作执行) │
└────────────────────┘ JSON └────────────────────┘ JSON └────────────────────┘
```
### 4.2 核心模块
1. **HTTP 服务模块**：处理外部请求，解析 MCP 协议，返回操作结果
2. **MCP 工具模块**：实现各种操作工具，包括新增的编辑器管理、游戏对象查找等功能
3. **场景操作模块**：执行场景相关操作，如节点查找、组件管理等
4. **资源管理模块**：处理脚本、材质、纹理等资源文件的创建和管理
5. **面板界面模块**：提供用户交互界面，包括主面板和工具测试面板
### 4.3 技术实现要点
- **编辑器 API 调用**：使用 `Editor.Ipc` 与编辑器核心进行通信
- **资源操作**：使用 `Editor.assetdb` API 进行资源文件的创建、读取、更新和删除
- **场景操作**：通过场景脚本执行节点和组件操作
- **异步处理**：使用回调函数处理异步操作，避免阻塞主线程
- **错误处理**：完善的错误捕获和处理机制，提高插件稳定性
- **性能优化**：使用批处理执行减少 HTTP 请求次数，优化资源操作效率
## 5. 功能实现方案
### 5.1 编辑器管理工具 (`manage_editor`)
#### 功能描述
提供对 Cocos Creator 编辑器状态的控制和操作执行能力。
#### 实现方案
```javascript
// 在 main.js 中添加
manageEditor(args, callback) {
const { action, target, properties } = args;
switch (action) {
case "get_selection":
// 获取当前选中的资源或节点
const nodeSelection = Editor.Selection.curSelection('node');
const assetSelection = Editor.Selection.curSelection('asset');
callback(null, {
nodes: nodeSelection,
assets: assetSelection
});
break;
case "set_selection":
// 设置选中状态
if (target === 'node' && properties.nodes) {
Editor.Selection.select('node', properties.nodes);
} else if (target === 'asset' && properties.assets) {
Editor.Selection.select('asset', properties.assets);
}
callback(null, "Selection updated");
break;
case "refresh_editor":
// 刷新编辑器
Editor.assetdb.refresh();
callback(null, "Editor refreshed");
break;
default:
callback("Unknown action");
}
}
```
### 5.2 游戏对象查找工具 (`find_gameobjects`)
#### 功能描述
根据条件查找场景中的节点对象。
#### 实现方案
```javascript
// 在 scene-script.js 中添加
findGameObjects(params, callback) {
const { conditions, recursive } = params;
const result = [];
// 遍历场景根节点
cc.director.getScene().children.forEach(child => {
searchNode(child, conditions, recursive, result);
});
callback(null, result);
}
function searchNode(node, conditions, recursive, result) {
// 检查节点是否满足条件
let match = true;
if (conditions.name && !node.name.includes(conditions.name)) {
match = false;
}
if (conditions.tag && node.tag !== conditions.tag) {
match = false;
}
if (conditions.component && !node.getComponent(conditions.component)) {
match = false;
}
if (match) {
result.push({
id: node.uuid,
name: node.name,
tag: node.tag,
position: node.position,
rotation: node.rotation,
scale: node.scale
});
}
// 递归搜索子节点
if (recursive) {
node.children.forEach(child => {
searchNode(child, conditions, recursive, result);
});
}
}
```
### 5.3 材质和纹理管理工具 (`manage_material`, `manage_texture`)
#### 功能描述
管理材质和纹理资源，支持创建、修改、删除等操作。
#### 实现方案
```javascript
// 在 main.js 中添加
manageMaterial(args, callback) {
const { action, path, properties } = args;
switch (action) {
case "create":
// 创建材质资源
const materialContent = JSON.stringify({
__type__: "cc.Material",
_name: "",
_objFlags: 0,
_native: "",
effects: [{
technique: 0,
defines: {},
uniforms: properties.uniforms || {}
}]
});
// 确保目录存在
const fs = require('fs');
const pathModule = require('path');
const absolutePath = Editor.assetdb.urlToFspath(path);
const dirPath = pathModule.dirname(absolutePath);
if (!fs.existsSync(dirPath)) {
fs.mkdirSync(dirPath, { recursive: true });
}
Editor.assetdb.create(path, materialContent, (err) => {
callback(err, err ? null : `Material created at ${path}`);
});
break;
// 其他操作...
}
}
manageTexture(args, callback) {
const { action, path, properties } = args;
switch (action) {
case "create":
// 创建纹理资源（简化版，实际需要处理纹理文件）
const textureContent = JSON.stringify({
__type__: "cc.Texture2D",
_name: "",
_objFlags: 0,
_native: properties.native || "",
width: properties.width || 128,
height: properties.height || 128
});
// 确保目录存在
const fs = require('fs');
const pathModule = require('path');
const absolutePath = Editor.assetdb.urlToFspath(path);
const dirPath = pathModule.dirname(absolutePath);
if (!fs.existsSync(dirPath)) {
fs.mkdirSync(dirPath, { recursive: true });
}
Editor.assetdb.create(path, textureContent, (err) => {
callback(err, err ? null : `Texture created at ${path}`);
});
break;
// 其他操作...
}
}
```
### 5.4 菜单项执行工具 (`execute_menu_item`)
#### 功能描述
执行 Cocos Creator 编辑器的菜单项命令。
#### 实现方案
```javascript
// 在 main.js 中添加
executeMenuItem(args, callback) {
const { menuPath } = args;
try {
// 执行菜单项
Editor.Ipc.sendToMain('menu:click', menuPath);
callback(null, `Menu item executed: ${menuPath}`);
} catch (err) {
callback(`Failed to execute menu item: ${err.message}`);
}
}
```
### 5.5 代码编辑增强工具 (`apply_text_edits`)
#### 功能描述
应用文本编辑操作到文件，支持插入、删除、替换等操作。
#### 实现方案
```javascript
// 在 main.js 中添加
applyTextEdits(args, callback) {
const { filePath, edits } = args;
// 读取文件内容
Editor.assetdb.queryInfoByUrl(filePath, (err, info) => {
if (err) {
callback(`Failed to get file info: ${err.message}`);
return;
}
Editor.assetdb.loadMeta(info.uuid, (err, content) => {
if (err) {
callback(`Failed to load file: ${err.message}`);
return;
}
// 应用编辑操作
let updatedContent = content;
edits.forEach(edit => {
switch (edit.type) {
case "insert":
updatedContent = updatedContent.slice(0, edit.position) + edit.text + updatedContent.slice(edit.position);
break;
case "delete":
updatedContent = updatedContent.slice(0, edit.start) + updatedContent.slice(edit.end);
break;
case "replace":
updatedContent = updatedContent.slice(0, edit.start) + edit.text + updatedContent.slice(edit.end);
break;
}
});
// 写回文件
Editor.assetdb.save(info.uuid, updatedContent, (err) => {
callback(err, err ? null : `Text edits applied to ${filePath}`);
});
});
});
}
```
### 5.6 控制台读取工具 (`read_console`)
#### 功能描述
读取编辑器控制台的输出信息。
#### 实现方案
```javascript
// 在 main.js 中添加
// 首先在模块顶部添加控制台输出捕获
let consoleOutput = [];
const originalLog = console.log;
const originalError = console.error;
const originalWarn = console.warn;
console.log = function(...args) {
consoleOutput.push({ type: 'log', message: args.join(' ') });
originalLog.apply(console, args);
};
console.error = function(...args) {
consoleOutput.push({ type: 'error', message: args.join(' ') });
originalError.apply(console, args);
};
console.warn = function(...args) {
consoleOutput.push({ type: 'warn', message: args.join(' ') });
originalWarn.apply(console, args);
};
// 然后添加 read_console 工具
readConsole(args, callback) {
const { limit, type } = args;
let filteredOutput = consoleOutput;
if (type) {
filteredOutput = filteredOutput.filter(item => item.type === type);
}
if (limit) {
filteredOutput = filteredOutput.slice(-limit);
}
callback(null, filteredOutput);
}
```
### 5.7 脚本验证工具 (`validate_script`)
#### 功能描述
验证脚本文件的语法正确性。
#### 实现方案
```javascript
// 在 main.js 中添加
validateScript(args, callback) {
const { filePath } = args;
// 读取脚本内容
Editor.assetdb.queryInfoByUrl(filePath, (err, info) => {
if (err) {
callback(`Failed to get file info: ${err.message}`);
return;
}
Editor.assetdb.loadMeta(info.uuid, (err, content) => {
if (err) {
callback(`Failed to load file: ${err.message}`);
return;
}
try {
// 对于 JavaScript 脚本，使用 eval 进行简单验证
if (filePath.endsWith('.js')) {
// 包装在函数中以避免变量污染
const wrapper = `(function() { ${content} })`;
eval(wrapper);
}
// 对于 TypeScript 脚本，这里可以添加更复杂的验证逻辑
callback(null, { valid: true, message: 'Script syntax is valid' });
} catch (err) {
callback(null, { valid: false, message: err.message });
}
});
});
}
});
}
```
### 5.8 常用 IPC 消息参考 (Cocos Creator 2.4.x)
基于社区资料整理，以下 IPC 消息可用于扩展功能：
#### 场景操作 (`scene:`)
- **创建/实例化**:
- `scene:create-node-by-classid` (参数: name, parentUuid)
- `scene:create-nodes-by-uuids` (实例化预制体, 参数: [prefabUuid], parentUuid)
- **修改**:
- `scene:set-property` (参数: {id, path, type, value})
- `scene:copy-nodes` / `scene:paste-nodes`
- **安全机制**:
- `scene:undo` / `scene:redo` (建议集成到 manage_editor)
#### 资源操作 (`assets:`)
- `assets:hint` (高亮资源)
- `assets:open-text-file` (打开外部编辑器)
## 6. 测试策略
### 6.1 测试目标
- 验证所有新增功能的正确性和稳定性
- 确保现有功能不受影响
- 测试插件在不同场景下的性能表现
- 验证错误处理机制的有效性
### 6.2 测试方法
#### 单元测试
- 为每个工具函数编写独立的测试用例
- 测试各种输入参数和边界情况
- 验证函数返回值的正确性
#### 集成测试
- 测试工具之间的协作能力
- 验证批处理执行的正确性
- 测试插件与编辑器的集成稳定性
#### 性能测试
- 测试工具执行速度
- 验证批处理执行的性能优势
- 测试插件在处理大量操作时的表现
#### 回归测试
- 确保新增功能不破坏现有功能
- 验证修复的 bug 不会再次出现
- 测试插件在不同版本 Cocos Creator 中的兼容性
### 6.3 测试工具
- **手动测试**：通过面板界面测试工具功能
- **脚本测试**：编写测试脚本自动执行测试用例
- **性能分析**：使用浏览器开发者工具分析性能瓶颈
## 7. 部署与维护
### 7.1 部署方案
#### 本地部署
1. 将插件复制到 Cocos Creator 项目的 `packages` 目录
2. 重启 Cocos Creator 编辑器
3. 在编辑器中打开 MCP Bridge 面板
4. 启动 HTTP 服务
#### 远程部署
1. 使用 Git 进行版本控制
2. 提供插件的 GitHub 仓库地址
3. 发布插件到 Cocos 插件商店（未来）
### 7.2 维护计划
#### 版本管理
- 遵循语义化版本规范（MAJOR.MINOR.PATCH）
- 定期发布更新版本
- 维护详细的版本变更日志
#### 错误处理
- 建立错误报告机制
- 定期分析错误日志
- 及时修复发现的问题
#### 性能优化
- 定期分析插件性能
- 优化资源操作和网络请求
- 提高插件响应速度
#### 文档维护
- 保持 README.md 和开发文档的更新
- 提供详细的 API 文档
- 编写使用教程和示例
## 8. 风险评估
### 8.1 潜在风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 编辑器 API 变更 | 插件功能失效 | 定期检查 Cocos Creator 更新，适配新 API |
| 性能问题 | 插件响应缓慢 | 优化代码结构，使用批处理执行，避免阻塞操作 |
| 安全漏洞 | 未授权访问 | 添加 IP 白名单，实现认证机制，限制服务访问范围 |
| 兼容性问题 | 不同版本 Cocos Creator 不兼容 | 测试多个版本，提供版本兼容层 |
| 错误处理不完善 | 插件崩溃 | 完善错误捕获和处理机制，提高插件稳定性 |
### 8.2 应对策略
- **持续集成**：建立自动化测试流程，及时发现问题
- **监控机制**：添加性能监控和错误监控
- **用户反馈**：建立用户反馈渠道，收集使用问题
- **文档完善**：提供详细的安装和使用文档
- **社区支持**：建立社区支持渠道，解答用户问题
## 9. 结论
Cocos-MCP 插件的开发计划基于与 Unity-MCP 的功能对比，旨在为 Cocos Creator 开发者提供同样强大的 AI 辅助开发体验。通过分阶段实现编辑器管理、游戏对象查找、材质/纹理管理等高级功能，插件将逐步完善其功能集，成为 Cocos Creator 编辑器的重要扩展工具。
本开发计划文档为后续的开发工作提供了详细的指导，包括功能实现方案、技术架构设计、测试策略和部署维护计划。通过严格按照计划执行开发工作，我们可以确保插件的质量和稳定性，为 Cocos Creator 生态系统做出贡献。
Reference in New Issue Copy Permalink