CocosPlugin/mcp-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现 open_prefab 工具，优化预制体创建稳定性，并完成全量源码 (JS/TS)、文档与配置的汉化合规审计

Browse Source
This commit is contained in:
火焰库拉
2026-02-13 13:52:27 +08:00
parent 8df6f5a415
commit 24bc7b7b1f
11 changed files with 2024 additions and 1547 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
DEVELOPMENT.md
View File

@@ -104,11 +104,18 @@ startServer(port) {
## 4. 开发历程与里程碑
### 2026-02-10: Undo 系统深度修复与规范化
- **问题分析**: 修复了 `TypeError: Cannot read property '_name' of null`。该错误是由于直接修改节点属性（绕过 Undo 系统）与分组事务混用导致的。
- **重构要点**: 将 `update-node-transform` 中所有的直接赋值替换为 `scene:set-property` IPC 调用，确保所有变换修改均受撤销系统监控。
- **缺陷修正**: 修复了 `manage_undo` 在 `begin_group` 时传递错误参数导致 "Unknown object to record" 的问题。
- **全量汉化与文档同步**: 完成了 `main.js` 和 `scene-script.js` 的 100% 简体中文翻译。同步更新了 `README.md`、`DEVELOPMENT.md` 及 `注意事项.md`。
### 2026-02-13: 新增 `open_prefab` 功能与消息协议修正
- **需求实现**: 新增 `open_prefab` 工具，允许 AI 直接打开预制体进入编辑模式。
- **协议修正**: 经过测试对比，最终确认使用 `scene:enter-prefab-edit-mode` 消息并配合 `Editor.Ipc.sendToAll` 是进入预制体编辑模式的最佳方案，解决了 `scene:open-by-uuid` 无法触发编辑状态的问题。
- **文档深度补全**: 遵循全局开发规范，同步更新了所有技术文档，确保 100% 简体中文覆盖及详尽的 JSDoc 注释。
### 3.2 MCP 工具注册
在 `/list-tools` 接口中注册工具：
@@ -118,7 +125,7 @@ const tools = [
{
name: "get_selected_node",
description: "获取当前选中的节点",
parameters: []
parameters: [],
},
// 其他工具...
];
@@ -130,10 +137,10 @@ const tools = [
```javascript
const sceneScript = {
'create-node'(params, callback) {
"create-node"(params, callback) {
// 创建节点逻辑...
},
'set-property'(params, callback) {
"set-property"(params, callback) {
// 设置属性逻辑...
},
// 其他操作...
@@ -283,6 +290,7 @@ manageAsset(args, callback) {
**错误信息**：`Panel info not found for panel mcp-bridge`
**解决方案**：
- 检查 `package.json` 中的面板配置
- 确保 `panel` 字段配置正确，移除冲突的 `panels` 字段
@@ -291,6 +299,7 @@ manageAsset(args, callback) {
**错误信息**：`Parent path ... is not exists`
**解决方案**：
- 在创建资源前添加目录检查和创建逻辑
- 使用 `fs.mkdirSync(dirPath, { recursive: true })` 递归创建目录
@@ -299,6 +308,7 @@ manageAsset(args, callback) {
**错误信息**：`SyntaxError: Invalid or unexpected token`
**解决方案**：
- 使用模板字符串（反引号）处理多行字符串
- 避免变量名冲突
@@ -321,6 +331,7 @@ manageAsset(args, callback) {
### 5.2 API 文档
为每个 MCP 工具编写详细的 API 文档，包括：
- 工具名称
- 功能描述
- 参数说明
@@ -438,7 +449,7 @@ manageAsset(args, callback) {
### 11.1 第三阶段开发计划（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| ---------------------- | ------- | ------------------------------------------------------------------- |
| 编辑器管理工具实现 | ✅ 完成 | 实现 manage_editor 工具，支持编辑器状态控制和操作执行 |
| 游戏对象查找工具实现 | ✅ 完成 | 实现 find_gameobjects 工具，支持根据条件查找场景节点 |
| 材质和纹理管理工具实现 | ✅ 完成 | 实现 manage_material 和 manage_texture 工具，支持材质和纹理资源管理 |
@@ -450,14 +461,14 @@ manageAsset(args, callback) {
### 11.2 第四阶段开发计划（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| ------------ | ------- | ---------------------------------------------- |
| 测试功能实现 | ✅ 完成 | 实现 run_tests.js 脚本，支持运行自动化测试用例 |
| 错误处理增强 | ✅ 完成 | 完善 HTTP 服务和工具调用的错误日志记录 |
### 11.3 差异填补阶段（Gap Filling）- 已完成
| 任务 | 状态 | 描述 |
|------|------|------|
| -------- | ------- | ---------------------------------------------- |
| 特效管理 | ✅ 完成 | 实现 manage_vfx 工具，支持粒子系统管理 |
| 文件哈希 | ✅ 完成 | 实现 get_sha 工具，支持文件 SHA-256 计算 |
| 动画管理 | ✅ 完成 | 实现 manage_animation 工具，支持动画播放与控制 |
@@ -465,7 +476,7 @@ manageAsset(args, callback) {
### 11.4 第六阶段：可靠性与体验优化（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| ---------------- | ------- | -------------------------------------------------------------------------- |
| IPC 工具增强 | ✅ 完成 | 修复 IpcManager 返回值解析，优化测试面板 (JSON 参数、筛选) |
| 脚本可靠性修复 | ✅ 完成 | 解决脚本编译时序导致的挂载失败问题 (文档引导 + 刷新机制) |
| 组件智能解析修复 | ✅ 完成 | 修复组件属性赋值时的 UUID 类型转换，支持压缩 UUID 及自定义组件 (`$_$ctor`) |
@@ -473,7 +484,7 @@ manageAsset(args, callback) {
### 11.5 第七阶段开发计划（已完成）
| 任务 | 状态 | 描述 |
|------|------|------|
| ---------- | ------- | ----------------------------------------- |
| 插件发布 | ✅ 完成 | 准备发布，提交到 Cocos 插件商店 |
| 文档完善 | ✅ 完成 | 完善 API 文档 ("Getting Started" 教程) |
| 界面美化 | ✅ 完成 | 优化面板 UI 体验 |
@@ -487,7 +498,7 @@ manageAsset(args, callback) {
通过与 Unity-MCP 对比，Cocos-MCP 已实现绝大多数核心功能。
| 功能类别 | Unity-MCP 功能 | Cocos-MCP 状态 | 备注 |
|---------|---------------|---------------|------|
| ---------------- | ----------------- | -------------- | ------------------------------------- |
| 编辑器管理 | manage_editor | ✅ 已实现 | |
| 游戏对象管理 | find_gameobjects | ✅ 已实现 | |
| 材质管理 | manage_material | ✅ 已实现 | |
@@ -508,7 +519,7 @@ manageAsset(args, callback) {
### 13.1 潜在风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| --------------- | ------------ | ----------------------------------------- |
| 编辑器 API 变更 | 插件功能失效 | 定期检查 Cocos 更新，适配新 API |
| 性能问题 | 插件响应缓慢 | 优化批处理 (batch_execute)，减少 IPC 通讯 |
| 安全漏洞 | 未授权访问 | (规划中) 面板设置 IP 白名单/Token 认证 |

182
IPC_MESSAGES.md
View File

File diff suppressed because it is too large Load Diff

19
README.md
View File

@@ -10,7 +10,7 @@
- **HTTP 服务接口**: 提供标准 HTTP 接口，外部工具可以通过 MCP 协议调用 Cocos Creator 编辑器功能
- **场景节点操作**: 获取、创建、修改场景中的节点
- **资源管理**: 创建场景、预制体，打开指定资源
- **资源管理**: 创建场景、预制体，打开场景或预制体进入编辑模式
- **组件管理**: 添加、删除、获取节点组件
- **脚本管理**: 创建、删除、读取、写入脚本文件
- **批处理执行**: 批量执行多个 MCP 工具操作，提高效率
@@ -123,7 +123,13 @@ Args: [你的项目所在盘符]:/[项目路径]/packages/mcp-bridge/mcp-proxy.j
- **参数**:
- `url`: 场景资源路径，如 `db://assets/NewScene.fire`
### 7. create_node
### 7. open_prefab
- **描述**: 在编辑器中打开指定的预制体文件进入编辑模式。这是一个异步操作，打开后请等待几秒。
- **参数**:
- `url`: 预制体资源路径，如 `db://assets/prefabs/Test.prefab`
### 8. create_node
- **描述**: 在当前场景中创建一个新节点。
- **重要提示**:
@@ -303,6 +309,7 @@ Args: [你的项目所在盘符]:/[项目路径]/packages/mcp-bridge/mcp-proxy.j
- `includeSubpackages`: 是否搜索子包 (Boolean, 默认 true)
**示例**:
```json
// 正则搜索
{
@@ -349,7 +356,6 @@ Args: [你的项目所在盘符]:/[项目路径]/packages/mcp-bridge/mcp-proxy.j
- **参数**:
- `path`: 文件路径，如 `db://assets/scripts/Test.ts`
## 技术实现
### 架构设计
@@ -413,12 +419,11 @@ Args: [你的项目所在盘符]:/[项目路径]/packages/mcp-bridge/mcp-proxy.j
1. **确定性优先**：任何对节点、组件、属性的操作，都必须建立在“主体已确认存在”的基础上。
2. **校验流程**：
* **节点校验**：操作前必须使用 `get_scene_hierarchy` 确认节点。
* **组件校验**：操作组件前必须使用 `get`（通过 `manage_components`）确认组件存在。
* **属性校验**：更新属性前必须确认属性名准确无误。
- **节点校验**：操作前必须使用 `get_scene_hierarchy` 确认节点。
- **组件校验**：操作组件前必须使用 `get`（通过 `manage_components`）确认组件存在。
- **属性校验**：更新属性前必须确认属性名准确无误。
3. **禁止假设**：禁止盲目尝试对不存在的对象或属性进行修改。
## 贡献
欢迎提交 Issue 和 Pull Request 来改进这个插件！

7
UPDATE_LOG.md
View File

@@ -113,3 +113,10 @@
- **清理死代码**: 删除 `/list-tools` 路由中重复的 `res.writeHead / res.end` 调用。
- **文档更新**: `注意事项.md` 新增第 9 章「并发安全与防卡死机制」，记录 CommandQueue 和 IPC 超时两个防护机制。
### 6. 场景与预制体工具增强
- **新增 `open_prefab` 工具**: 解决了直接打开预制体进入编辑模式的问题。通过使用正确的 IPC 消息 `scene:enter-prefab-edit-mode` (并结合 `Editor.Ipc.sendToAll`)，使得 AI 可以精准操控预制体的编辑流程，而不再局限于场景跳转。
- **优化预制体创建稳定性 (`create_node` + `prefab_management`)**:
- 在创建物理目录后强制执行 `Editor.assetdb.refresh`，确保 AssetDB 即时同步。
- 将节点重命名与预制体创建指令之间的安全延迟从 100ms 增加至 300ms，消除了重命名未完成导致创建失败的竞态条件。

120
main.js
View File

@@ -253,6 +253,20 @@ const getToolsList = () => {
required: ["url"],
},
},
{
name: "open_prefab",
description: `${globalPrecautions} 在编辑器中打开预制体文件进入编辑模式。注意：这是一个异步操作，打开后请等待几秒。`,
inputSchema: {
type: "object",
properties: {
url: {
type: "string",
description: "预制体资源路径，如 db://assets/prefabs/Test.prefab",
},
},
required: ["url"],
},
},
{
name: "create_node",
description: `${globalPrecautions} 在当前场景中创建一个新节点。重要提示：1. 如果指定 parentId，必须先通过 get_scene_hierarchy 确保该父节点真实存在且未被删除。2. 类型说明：'sprite' (100x100 尺寸 + 默认贴图), 'button' (150x50 尺寸 + 深色底图 + Button组件), 'label' (120x40 尺寸 + Label组件), 'empty' (纯空节点)。`,
@@ -842,6 +856,9 @@ module.exports = {
}
},
/**
* 关闭 HTTP 服务器
*/
stopServer() {
if (mcpServer) {
mcpServer.close();
@@ -852,6 +869,10 @@ module.exports = {
}
},
/**
* 获取 MCP 资源列表
* @returns {Array<Object>} 资源列表数组
*/
getResourcesList() {
return [
{
@@ -875,6 +896,11 @@ module.exports = {
];
},
/**
* 读取指定的 MCP 资源内容
* @param {string} uri 资源统一资源标识符 (URI)
* @param {Function} callback 完成回调 (err, content)
*/
handleReadResource(uri, callback) {
let parsed;
try {
@@ -997,6 +1023,22 @@ module.exports = {
}
break;
case "open_prefab":
isSceneBusy = true; // 锁定
const prefabUuid = Editor.assetdb.urlToUuid(args.url);
if (prefabUuid) {
// 【核心修复】使用正确的 IPC 消息进入预制体编辑模式
Editor.Ipc.sendToAll("scene:enter-prefab-edit-mode", prefabUuid);
setTimeout(() => {
isSceneBusy = false;
callback(null, `成功：正在打开预制体 ${args.url}`);
}, 2000);
} else {
isSceneBusy = false;
callback(`找不到路径为 ${args.url} 的资源`);
}
break;
case "create_node":
if (args.type === "sprite" || args.type === "button") {
const splashUuid = Editor.assetdb.urlToUuid(
@@ -1432,11 +1474,11 @@ export default class NewScript extends cc.Component {
const dirPath = pathModule.dirname(absolutePath);
if (!fs.existsSync(dirPath)) {
fs.mkdirSync(dirPath, { recursive: true });
// 【增强】确保 AssetDB 刷新文件夹，防止场景脚本找不到目标目录
Editor.assetdb.refresh(targetDir);
}
// 解析目标目录和文件名
// db://assets/folder/PrefabName.prefab -> db://assets/folder, PrefabName
const targetDir = prefabPath.substring(0, prefabPath.lastIndexOf("/"));
const fileName = prefabPath.substring(prefabPath.lastIndexOf("/") + 1);
const prefabName = fileName.replace(".prefab", "");
@@ -1451,9 +1493,10 @@ export default class NewScript extends cc.Component {
// 2. 发送创建命令 (参数: [uuids], dirPath)
// 注意: scene:create-prefab 第三个参数必须是 db:// 目录路径
// 【增强】增加延迟到 300ms，确保 IPC 消息处理并同步到底层引擎
setTimeout(() => {
Editor.Ipc.sendToPanel("scene", "scene:create-prefab", [nodeId], targetDir);
}, 100); // 稍微延迟以确保重命名生效
}, 300);
callback(null, `指令已发送: 从节点 ${nodeId} 在目录 ${targetDir} 创建名为 ${prefabName} 的预制体`);
break;
@@ -1472,7 +1515,7 @@ export default class NewScript extends cc.Component {
case "instantiate":
if (!Editor.assetdb.exists(prefabPath)) {
return callback(`Prefab not found at ${prefabPath}`);
return callback(`路径为 ${prefabPath} 的预制体不存在`);
}
// 实例化预制体
const prefabUuid = Editor.assetdb.urlToUuid(prefabPath);
@@ -2066,6 +2109,11 @@ CCProgram fs %{
callback(null, filteredOutput);
},
/**
* 执行编辑器菜单项
* @param {Object} args 参数 (menuPath)
* @param {Function} callback 完成回调
*/
executeMenuItem(args, callback) {
const { menuPath } = args;
if (!menuPath) {
@@ -2092,7 +2140,7 @@ CCProgram fs %{
if (uuid) {
callSceneScriptWithTimeout("mcp-bridge", "delete-node", { uuid }, (err, result) => {
if (err) callback(err);
else callback(null, result || `Node ${uuid} deleted via scene script`);
else callback(null, result || `节点 ${uuid} 已通过场景脚本删除`);
});
return;
}
@@ -2120,7 +2168,7 @@ CCProgram fs %{
} else {
// 对于未在映射表中的菜单，尝试通用的 menu:click (虽然不一定有效)
// 或者直接返回不支持的警告
addLog("warn", `支持映射表中找不到菜单项 '${menuPath}'。尝试通过 legacy 模式执行。`);
addLog("warn", `支持映射表中找不到菜单项 '${menuPath}'。尝试通过旧版模式执行。`);
// 尝试通用调用
try {
@@ -2134,7 +2182,11 @@ CCProgram fs %{
}
},
// 验证脚本
/**
* 验证脚本文件的语法或基础结构
* @param {Object} args 参数 (filePath)
* @param {Function} callback 完成回调
*/
validateScript(args, callback) {
const { filePath } = args;
@@ -2265,7 +2317,7 @@ CCProgram fs %{
},
"inspect-apis"() {
addLog("info", "[API Inspector] Starting DEEP inspection...");
addLog("info", "[API 检查器] 开始深度分析...");
// 获取函数参数的辅助函数
const getArgs = (func) => {
@@ -2365,8 +2417,8 @@ CCProgram fs %{
: "Missing";
});
addLog("info", `[API Inspector] Standard Objects:\n${JSON.stringify(report, null, 2)}`);
addLog("info", `[API Inspector] Forum Checklist:\n${JSON.stringify(checklistResults, null, 2)}`);
addLog("info", `[API 检查器] 标准对象:\n${JSON.stringify(report, null, 2)}`);
addLog("info", `[API 检查器] 论坛核查清单:\n${JSON.stringify(checklistResults, null, 2)}`);
// 3. 检查内置包 IPC 消息
const ipcReport = {};
@@ -2391,12 +2443,15 @@ CCProgram fs %{
}
});
addLog("info", `[API Inspector] Built-in IPC Messages:\n${JSON.stringify(ipcReport, null, 2)}`);
addLog("info", `[API 检查器] 内置包 IPC 消息:\n${JSON.stringify(ipcReport, null, 2)}`);
},
},
// 全局文件搜索
// 项目搜索 (升级版 find_in_file)
/**
* 全局项目文件搜索 (支持正则表达式、文件名、目录名搜索)
* @param {Object} args 参数
* @param {Function} callback 完成回调
*/
searchProject(args, callback) {
const { query, useRegex, path: searchPath, matchType, extensions } = args;
@@ -2405,7 +2460,7 @@ CCProgram fs %{
const rootPath = Editor.assetdb.urlToFspath(rootPathUrl);
if (!rootPath || !fs.existsSync(rootPath)) {
return callback(`Invalid search path: ${rootPathUrl}`);
return callback(`无效的搜索路径: ${rootPathUrl}`);
}
const mode = matchType || "content"; // content, file_name, dir_name
@@ -2534,11 +2589,15 @@ CCProgram fs %{
walk(rootPath);
callback(null, results);
} catch (err) {
callback(`Search project failed: ${err.message}`);
callback(`项目搜索失败: ${err.message}`);
}
},
// 管理撤销/重做
/**
* 管理撤销/重做操作及事务分组
* @param {Object} args 参数 (action, description, id)
* @param {Function} callback 完成回调
*/
manageUndo(args, callback) {
const { action, description } = args;
@@ -2546,16 +2605,13 @@ CCProgram fs %{
switch (action) {
case "undo":
Editor.Ipc.sendToPanel("scene", "scene:undo");
callback(null, "Undo command executed");
callback(null, "撤销指令已执行");
break;
case "redo":
Editor.Ipc.sendToPanel("scene", "scene:redo");
callback(null, "Redo command executed");
callback(null, "重做指令已执行");
break;
case "begin_group":
// scene:undo-record [id]
// 注意：在 2.4.x 中，undo-record 通常需要一个有效的 uuid
// 如果没有提供 uuid，不应将 description 作为 ID 发送，否则会报 Unknown object to record
addLog("info", `开始撤销组: ${description || "MCP 动作"}`);
// 如果有参数包含 id，则记录该节点
if (args.id) {
@@ -2565,27 +2621,31 @@ CCProgram fs %{
break;
case "end_group":
Editor.Ipc.sendToPanel("scene", "scene:undo-commit");
callback(null, "Undo group committed");
callback(null, "撤销组已提交");
break;
case "cancel_group":
Editor.Ipc.sendToPanel("scene", "scene:undo-cancel");
callback(null, "Undo group cancelled");
callback(null, "撤销组已取消");
break;
default:
callback(`Unknown undo action: ${action}`);
callback(`未知的撤销操作: ${action}`);
}
} catch (err) {
callback(`Undo operation failed: ${err.message}`);
callback(`撤销操作失败: ${err.message}`);
}
},
// 获取文件 SHA-256
/**
* 计算资源的 SHA-256 哈希值
* @param {Object} args 参数 (path)
* @param {Function} callback 完成回调
*/
getSha(args, callback) {
const { path: url } = args;
const fspath = Editor.assetdb.urlToFspath(url);
if (!fspath || !fs.existsSync(fspath)) {
return callback(`File not found: ${url}`);
return callback(`找不到文件: ${url}`);
}
try {
@@ -2599,7 +2659,11 @@ CCProgram fs %{
}
},
// 管理动画
/**
* 管理节点动画 (播放、停止、获取信息等)
* @param {Object} args 参数
* @param {Function} callback 完成回调
*/
manageAnimation(args, callback) {
// 转发给场景脚本处理
callSceneScriptWithTimeout("mcp-bridge", "manage-animation", args, callback);

122
mcp-proxy.js
View File

@@ -1,101 +1,149 @@
const http = require('http');
/**
* MCP 桥接代理脚本
* 负责在标准 MCP 客户端 (stdin/stdout) 与 Cocos Creator 插件 (HTTP) 之间转发请求。
*/
const http = require("http");
/**
* 当前 Cocos Creator 插件监听的端口
* @type {number}
*/
const COCOS_PORT = 3456;
/**
* 发送调试日志到标准的错误输出流水
* @param {string} msg 日志消息
*/
function debugLog(msg) {
process.stderr.write(`[Proxy Debug] ${msg}\n`);
process.stderr.write(`[代理调试] ${msg}\n`);
}
process.stdin.on('data', (data) => {
const lines = data.toString().split('\n');
lines.forEach(line => {
// 监听标准输入以获取 MCP 请求
process.stdin.on("data", (data) => {
const lines = data.toString().split("\n");
lines.forEach((line) => {
if (!line.trim()) return;
try {
const request = JSON.parse(line);
handleRequest(request);
} catch (e) {}
} catch (e) {
// 忽略非 JSON 输入
}
});
});
/**
* 处理 JSON-RPC 请求
* @param {Object} req RPC 请求对象
*/
function handleRequest(req) {
const { method, id, params } = req;
if (method === 'initialize') {
// 处理握手初始化
if (method === "initialize") {
sendToAI({
jsonrpc: "2.0", id: id,
jsonrpc: "2.0",
id: id,
result: {
protocolVersion: "2024-11-05",
capabilities: { tools: {} },
serverInfo: { name: "cocos-bridge", version: "1.0.0" }
}
serverInfo: { name: "cocos-bridge", version: "1.0.0" },
},
});
return;
}
if (method === 'tools/list') {
// 使用 GET 获取列表
forwardToCocos('/list-tools', null, id, 'GET');
// 获取工具列表
if (method === "tools/list") {
forwardToCocos("/list-tools", null, id, "GET");
return;
}
if (method === 'tools/call') {
// 使用 POST 执行工具
forwardToCocos('/call-tool', {
// 执行具体工具
if (method === "tools/call") {
forwardToCocos(
"/call-tool",
{
name: params.name,
arguments: params.arguments
}, id, 'POST');
arguments: params.arguments,
},
id,
"POST",
);
return;
}
// 默认空响应
if (id !== undefined) sendToAI({ jsonrpc: "2.0", id: id, result: {} });
}
function forwardToCocos(path, payload, id, method = 'POST') {
const postData = payload ? JSON.stringify(payload) : '';
/**
* 将请求通过 HTTP 转发给 Cocos Creator 插件
* @param {string} path API 路径
* @param {Object|null} payload 发送的数据体
* @param {string|number} id RPC 请求标识符
* @param {string} method HTTP 方法 (默认 POST)
*/
function forwardToCocos(path, payload, id, method = "POST") {
const postData = payload ? JSON.stringify(payload) : "";
const options = {
hostname: '127.0.0.1',
hostname: "127.0.0.1",
port: COCOS_PORT,
path: path,
method: method,
headers: { 'Content-Type': 'application/json' }
headers: { "Content-Type": "application/json" },
};
if (postData) {
options.headers['Content-Length'] = Buffer.byteLength(postData);
options.headers["Content-Length"] = Buffer.byteLength(postData);
}
const request = http.request(options, (res) => {
let resData = '';
res.on('data', d => resData += d);
res.on('end', () => {
let resData = "";
res.on("data", (d) => (resData += d));
res.on("end", () => {
try {
const cocosRes = JSON.parse(resData);
// 检查关键字段
if (path === '/list-tools' && !cocosRes.tools) {
// 如果报错，把 Cocos 返回的所有内容打印到 Trae 的 stderr 日志里
debugLog(`CRITICAL: Cocos returned no tools. Received: ${resData}`);
sendError(id, -32603, "Invalid Cocos response: missing tools array");
// 检查关键字段，确保 Cocos 插件返回了期望的数据格式
if (path === "/list-tools" && !cocosRes.tools) {
debugLog(`致命错误: Cocos 未返回工具列表。接收内容: ${resData}`);
sendError(id, -32603, "Cocos 响应无效：缺少 tools 数组");
} else {
sendToAI({ jsonrpc: "2.0", id: id, result: cocosRes });
}
} catch (e) {
debugLog(`JSON Parse Error. Cocos Sent: ${resData}`);
sendError(id, -32603, "Cocos returned non-JSON data");
debugLog(`JSON 解析错误。Cocos 发送内容: ${resData}`);
sendError(id, -32603, "Cocos 返回了非 JSON 数据");
}
});
});
request.on('error', (e) => {
debugLog(`Cocos is offline: ${e.message}`);
sendError(id, -32000, "Cocos Plugin Offline");
request.on("error", (e) => {
debugLog(`Cocos 插件已离线: ${e.message}`);
sendError(id, -32000, "Cocos 插件离线");
});
if (postData) request.write(postData);
request.end();
}
function sendToAI(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
/**
* 将结果发送给 AI (通过标准输出)
* @param {Object} obj 结果对象
*/
function sendToAI(obj) {
process.stdout.write(JSON.stringify(obj) + "\n");
}
/**
* 发送 RPC 错误响应
* @param {string|number} id RPC 请求标识符
* @param {number} code 错误码
* @param {string} message 错误消息
*/
function sendError(id, code, message) {
sendToAI({ jsonrpc: "2.0", id: id, error: { code, message } });
}

4
package.json
View File

@@ -6,14 +6,14 @@
"main": "main.js",
"scene-script": "scene-script.js",
"main-menu": {
"MCP Bridge/Open Panel": {
"MCP 桥接器/开启测试面板": {
"message": "mcp-bridge:open-test-panel"
}
},
"panel": {
"main": "panel/index.js",
"type": "dockable",
"title": "MCP Test Panel",
"title": "MCP 测试面板",
"width": 400,
"height": 300
},

128
panel/index.js
View File

@@ -1,23 +1,53 @@
"use strict";
/**
* MCP Bridge 插件面板脚本
* 负责处理面板 UI 交互、与主进程通信以及提供测试工具界面。
*/
const fs = require("fs");
const { IpcUi } = require("../dist/IpcUi");
Editor.Panel.extend({
/**
* 面板 CSS 样式
*/
style: fs.readFileSync(Editor.url("packages://mcp-bridge/panel/index.html"), "utf-8"),
/**
* 面板 HTML 模板
*/
template: fs.readFileSync(Editor.url("packages://mcp-bridge/panel/index.html"), "utf-8"),
/**
* 监听来自主进程的消息
*/
messages: {
/**
* 接收并渲染日志
* @param {Object} event IPC 事件对象
* @param {Object} log 日志数据
*/
"mcp-bridge:on-log"(event, log) {
this.renderLog(log);
},
/**
* 服务器状态变更通知
* @param {Object} event IPC 事件对象
* @param {Object} config 服务器配置
*/
"mcp-bridge:state-changed"(event, config) {
this.updateUI(config.active);
},
},
/**
* 面板就绪回调，进行 DOM 绑定与事件初始化
*/
ready() {
const root = this.shadowRoot;
// 获取 DOM 元素
// 获取 DOM 元素映射
const els = {
port: root.querySelector("#portInput"),
btnToggle: root.querySelector("#btnToggle"),
@@ -41,7 +71,7 @@ Editor.Panel.extend({
resizer: root.querySelector("#testResizer"),
};
// 1. 初始化状态
// 1. 初始化服务器状态与配置
Editor.Ipc.sendToMain("mcp-bridge:get-server-state", (err, data) => {
if (data) {
els.port.value = data.config.port;
@@ -52,10 +82,10 @@ Editor.Panel.extend({
}
});
// 初始化 IPC UI
// 初始化 IPC 调试专用 UI (由 TypeScript 编写并编译到 dist)
new IpcUi(root);
// 2. 标签切换
// 2. 标签页切换逻辑
els.tabMain.addEventListener("confirm", () => {
els.tabMain.classList.add("active");
els.tabTest.classList.remove("active");
@@ -64,6 +94,7 @@ Editor.Panel.extend({
els.panelTest.classList.remove("active");
els.panelIpc.classList.remove("active");
});
els.tabTest.addEventListener("confirm", () => {
els.tabTest.classList.add("active");
els.tabMain.classList.remove("active");
@@ -71,8 +102,9 @@ Editor.Panel.extend({
els.panelTest.classList.add("active");
els.panelMain.classList.remove("active");
els.panelIpc.classList.remove("active");
this.fetchTools(els);
this.fetchTools(els); // 切换到测试页时自动拉取工具列表
});
els.tabIpc.addEventListener("confirm", () => {
els.tabIpc.classList.add("active");
els.tabMain.classList.remove("active");
@@ -82,39 +114,42 @@ Editor.Panel.extend({
els.panelTest.classList.remove("active");
});
// 3. 基础功能
// 3. 基础控制按钮逻辑
els.btnToggle.addEventListener("confirm", () => {
Editor.Ipc.sendToMain("mcp-bridge:toggle-server", parseInt(els.port.value));
});
root.querySelector("#btnClear").addEventListener("confirm", () => {
els.logView.innerHTML = "";
Editor.Ipc.sendToMain("mcp-bridge:clear-logs");
});
root.querySelector("#btnCopy").addEventListener("confirm", () => {
require("electron").clipboard.writeText(els.logView.innerText);
Editor.success("日志已复制");
Editor.success("日志已复制到剪贴板");
});
els.autoStart.addEventListener("change", (e) => {
Editor.Ipc.sendToMain("mcp-bridge:set-auto-start", e.target.value);
});
// 4. 测试页功能
// 4. API 测试页交互逻辑
els.listBtn.addEventListener("confirm", () => this.fetchTools(els));
els.clearBtn.addEventListener("confirm", () => {
els.result.value = "";
});
els.testBtn.addEventListener("confirm", () => this.runTest(els));
els.testBtn.addEventListener("confirm", () => this.runTest(els));
// 添加 API 探查功能
// API 探查功能 (辅助开发者发现可用内部 IPC)
const probeBtn = root.querySelector("#probeApisBtn");
if (probeBtn) {
probeBtn.addEventListener("confirm", () => {
Editor.Ipc.sendToMain("mcp-bridge:inspect-apis");
els.result.value = "探查指令已发送。请查看编辑器控制台日志。";
els.result.value = "API 探查指令已发送。请查看编辑器控制台 (Console) 获取详细报告。";
});
}
// 5. 【修复】拖拽逻辑
// 5. 测试页分栏拖拽缩放逻辑
if (els.resizer && els.left) {
els.resizer.addEventListener("mousedown", (e) => {
e.preventDefault();
@@ -135,8 +170,13 @@ Editor.Panel.extend({
}
},
/**
* 从本地服务器获取 MCP 工具列表并渲染
* @param {Object} els DOM 元素映射
*/
fetchTools(els) {
const url = `http://localhost:${els.port.value}/list-tools`;
els.result.value = "正在获取工具列表...";
fetch(url)
.then((r) => r.json())
.then((data) => {
@@ -154,64 +194,86 @@ Editor.Panel.extend({
};
els.toolsList.appendChild(item);
});
// 保存工具映射表，以便后续检索
this.toolsMap = toolsMap;
els.result.value = `成功加载 ${data.tools.length} 个工具。`;
els.result.value = `成功：加载了 ${data.tools.length} 个工具。`;
})
.catch((e) => {
els.result.value = "Error: " + e.message;
els.result.value = "获取失败: " + e.message;
});
},
/**
* 在面板中展示工具的详细描述与参数定义
* @param {Object} els DOM 元素映射
* @param {Object} tool 工具定义对象
*/
showToolDescription(els, tool) {
if (!tool) {
els.toolDescription.textContent = "选择工具查看说明";
els.toolDescription.textContent = "选择工具以查看说明";
return;
}
let description = tool.description || "无描述";
let description = tool.description || "暂无描述";
let inputSchema = tool.inputSchema;
let details = [];
if (inputSchema && inputSchema.properties) {
details.push("参数说明:");
details.push("<b>参数说明:</b>");
for (const [key, prop] of Object.entries(inputSchema.properties)) {
let propDesc = `- ${key}`;
let propDesc = `- <code>${key}</code>`;
if (prop.description) {
propDesc += `: ${prop.description}`;
}
if (prop.required || (inputSchema.required && inputSchema.required.includes(key))) {
propDesc += " (必填)";
propDesc += " <span style='color:#f44'>(必填)</span>";
}
details.push(propDesc);
}
}
els.toolDescription.innerHTML = `${description}<br><br>${details.join('<br>')}`;
els.toolDescription.innerHTML = `${description}<br><br>${details.join("<br>")}`;
},
/**
* 执行工具测试请求
* @param {Object} els DOM 元素映射
*/
runTest(els) {
const url = `http://localhost:${els.port.value}/call-tool`;
const body = { name: els.toolName.value, arguments: JSON.parse(els.toolParams.value || "{}") };
els.result.value = "正在测试...";
let args;
try {
args = JSON.parse(els.toolParams.value || "{}");
} catch (e) {
els.result.value = "JSON 格式错误: " + e.message;
return;
}
const body = { name: els.toolName.value, arguments: args };
els.result.value = "正在发送请求...";
fetch(url, { method: "POST", body: JSON.stringify(body) })
.then((r) => r.json())
.then((d) => {
els.result.value = JSON.stringify(d, null, 2);
})
.catch((e) => {
els.result.value = "Error: " + e.message;
els.result.value = "测试异常: " + e.message;
});
},
/**
* 获取指定工具的示例参数
* @param {string} name 工具名称
* @returns {Object} 示例参数对象
*/
getExample(name) {
const examples = {
set_node_name: { id: "UUID", newName: "Hello" },
update_node_transform: { id: "UUID", x: 0, y: 0, color: "#FF0000" },
create_node: { name: "Node", type: "sprite", parentId: "" },
set_node_name: { id: "节点-UUID", newName: "新名称" },
update_node_transform: { id: "节点-UUID", x: 0, y: 0, color: "#FF0000" },
create_node: { name: "新节点", type: "sprite", parentId: "" },
open_scene: { url: "db://assets/Scene.fire" },
open_prefab: { url: "db://assets/MyPrefab.prefab" },
manage_editor: { action: "get_selection" },
find_gameobjects: { conditions: { name: "Node", active: true }, recursive: true },
find_gameobjects: { conditions: { name: "MyNode", active: true }, recursive: true },
manage_material: {
action: "create",
path: "db://assets/materials/NewMaterial.mat",
@@ -225,7 +287,7 @@ Editor.Panel.extend({
execute_menu_item: { menuPath: "Assets/Create/Folder" },
apply_text_edits: {
filePath: "db://assets/scripts/TestScript.ts",
edits: [{ type: "insert", position: 0, text: "// Test comment\n" }],
edits: [{ type: "insert", position: 0, text: "// 测试注释\n" }],
},
read_console: { limit: 10, type: "log" },
validate_script: { filePath: "db://assets/scripts/TestScript.ts" },
@@ -233,6 +295,10 @@ Editor.Panel.extend({
return examples[name] || {};
},
/**
* 将日志条目渲染至面板控制台
* @param {Object} log 日志对象
*/
renderLog(log) {
const view = this.shadowRoot.querySelector("#logConsole");
if (!view) return;
@@ -244,6 +310,10 @@ Editor.Panel.extend({
if (atBottom) view.scrollTop = view.scrollHeight;
},
/**
* 根据服务器运行状态更新 UI 按钮文字与样式
* @param {boolean} active 服务器是否处于激活状态
*/
updateUI(active) {
const btn = this.shadowRoot.querySelector("#btnToggle");
if (!btn) return;

149
scene-script.js
View File

@@ -8,7 +8,7 @@
const findNode = (id) => {
if (!id) return null;
let node = cc.engine.getInstanceById(id);
if (!node && typeof Editor !== 'undefined' && Editor.Utils && Editor.Utils.UuidUtils) {
if (!node && typeof Editor !== "undefined" && Editor.Utils && Editor.Utils.UuidUtils) {
// 如果直接查不到，尝试对可能是压缩格式的 ID 进行解压后再次查找
try {
const decompressed = Editor.Utils.UuidUtils.decompressUuid(id);
@@ -68,6 +68,11 @@ module.exports = {
"get-hierarchy": function (event) {
const scene = cc.director.getScene();
/**
* 递归遍历并序列化节点树
* @param {cc.Node} node 目标节点
* @returns {Object|null} 序列化后的节点数据
*/
function dumpNodes(node) {
// 【优化】跳过编辑器内部的私有节点，减少数据量
if (node.name.startsWith("Editor Scene") || node.name === "gizmoRoot") {
@@ -114,22 +119,52 @@ module.exports = {
// 使用 scene:set-property 实现支持 Undo 的属性修改
// 注意：IPC 消息需要发送到 'scene' 面板
if (x !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "x", type: "Number", value: Number(x) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "x",
type: "Number",
value: Number(x),
});
}
if (y !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "y", type: "Number", value: Number(y) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "y",
type: "Number",
value: Number(y),
});
}
if (args.width !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "width", type: "Number", value: Number(args.width) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "width",
type: "Number",
value: Number(args.width),
});
}
if (args.height !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "height", type: "Number", value: Number(args.height) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "height",
type: "Number",
value: Number(args.height),
});
}
if (scaleX !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "scaleX", type: "Number", value: Number(scaleX) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "scaleX",
type: "Number",
value: Number(scaleX),
});
}
if (scaleY !== undefined) {
Editor.Ipc.sendToPanel("scene", "scene:set-property", { id, path: "scaleY", type: "Number", value: Number(scaleY) });
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id,
path: "scaleY",
type: "Number",
value: Number(scaleY),
});
}
if (color) {
const c = new cc.Color().fromHEX(color);
@@ -137,7 +172,7 @@ module.exports = {
id: id,
path: "color",
type: "Color",
value: { r: c.r, g: c.g, b: c.b, a: c.a }
value: { r: c.r, g: c.g, b: c.b, a: c.a },
});
}
@@ -258,7 +293,11 @@ module.exports = {
const { nodeId, action, componentType, componentId, properties } = args;
let node = findNode(nodeId);
// 辅助函数：应用属性并智能解析
/**
* 辅助函数：应用属性并智能解析 (支持 UUID 资源与节点引用)
* @param {cc.Component} component 目标组件实例
* @param {Object} props 待更新的属性键值对
*/
const applyProperties = (component, props) => {
if (!props) return;
// 尝试获取组件类的属性定义
@@ -266,12 +305,13 @@ module.exports = {
for (const [key, value] of Object.entries(props)) {
// 【核心修复】专门处理各类事件属性 (ClickEvents, ScrollEvents 等)
const isEventProp = Array.isArray(value) && (key.toLowerCase().endsWith('events') || key === 'clickEvents');
const isEventProp =
Array.isArray(value) && (key.toLowerCase().endsWith("events") || key === "clickEvents");
if (isEventProp) {
const eventHandlers = [];
for (const item of value) {
if (typeof item === 'object' && (item.target || item.component || item.handler)) {
if (typeof item === "object" && (item.target || item.component || item.handler)) {
const handler = new cc.Component.EventHandler();
// 解析 Target Node
@@ -289,7 +329,8 @@ module.exports = {
if (item.component) handler.component = item.component;
if (item.handler) handler.handler = item.handler;
if (item.customEventData !== undefined) handler.customEventData = String(item.customEventData);
if (item.customEventData !== undefined)
handler.customEventData = String(item.customEventData);
eventHandlers.push(handler);
} else {
@@ -309,18 +350,35 @@ module.exports = {
try {
const attrs = (cc.Class.Attr.getClassAttrs && cc.Class.Attr.getClassAttrs(compClass)) || {};
let propertyType = attrs[key] ? attrs[key].type : null;
if (!propertyType && attrs[key + '$_$ctor']) {
propertyType = attrs[key + '$_$ctor'];
if (!propertyType && attrs[key + "$_$ctor"]) {
propertyType = attrs[key + "$_$ctor"];
}
let isAsset = propertyType && (propertyType.prototype instanceof cc.Asset || propertyType === cc.Asset || propertyType === cc.Prefab || propertyType === cc.SpriteFrame);
let isAssetArray = Array.isArray(value) && (key === 'materials' || key.toLowerCase().includes('assets'));
let isAsset =
propertyType &&
(propertyType.prototype instanceof cc.Asset ||
propertyType === cc.Asset ||
propertyType === cc.Prefab ||
propertyType === cc.SpriteFrame);
let isAssetArray =
Array.isArray(value) && (key === "materials" || key.toLowerCase().includes("assets"));
// 启发式：如果属性名包含 prefab/sprite/texture 等，且值为 UUID 且不是节点
if (!isAsset && !isAssetArray && typeof value === 'string' && value.length > 20) {
if (!isAsset && !isAssetArray && typeof value === "string" && value.length > 20) {
const lowerKey = key.toLowerCase();
const assetKeywords = ['prefab', 'sprite', 'texture', 'material', 'skeleton', 'spine', 'atlas', 'font', 'audio', 'data'];
if (assetKeywords.some(k => lowerKey.includes(k))) {
const assetKeywords = [
"prefab",
"sprite",
"texture",
"material",
"skeleton",
"spine",
"atlas",
"font",
"audio",
"data",
];
if (assetKeywords.some((k) => lowerKey.includes(k))) {
if (!findNode(value)) {
isAsset = true;
}
@@ -339,7 +397,7 @@ module.exports = {
}
uuids.forEach((uuid, idx) => {
if (typeof uuid !== 'string' || uuid.length < 10) {
if (typeof uuid !== "string" || uuid.length < 10) {
loadedCount++;
return;
}
@@ -355,7 +413,7 @@ module.exports = {
if (loadedCount === uuids.length) {
if (isAssetArray) {
// 过滤掉加载失败的
component[key] = loadedAssets.filter(a => !!a);
component[key] = loadedAssets.filter((a) => !!a);
} else {
if (loadedAssets[0]) component[key] = loadedAssets[0];
}
@@ -363,12 +421,12 @@ module.exports = {
// 通知编辑器 UI 更新
const compIndex = node._components.indexOf(component);
if (compIndex !== -1) {
Editor.Ipc.sendToPanel('scene', 'scene:set-property', {
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id: node.uuid,
path: `_components.${compIndex}.${key}`,
type: isAssetArray ? 'Array' : 'Object',
value: isAssetArray ? uuids.map(u => ({ uuid: u })) : { uuid: value },
isSubProp: false
type: isAssetArray ? "Array" : "Object",
value: isAssetArray ? uuids.map((u) => ({ uuid: u })) : { uuid: value },
isSubProp: false,
});
}
Editor.Ipc.sendToMain("scene:dirty");
@@ -378,7 +436,12 @@ module.exports = {
// 【重要修复】使用 continue 而不是 return，确保处理完 Asset 属性后
// 还能继续处理后续的普通属性 (如 type, sizeMode 等)
continue;
} else if (propertyType && (propertyType.prototype instanceof cc.Component || propertyType === cc.Component || propertyType === cc.Node)) {
} else if (
propertyType &&
(propertyType.prototype instanceof cc.Component ||
propertyType === cc.Component ||
propertyType === cc.Node)
) {
// 2. 处理节点或组件引用
const targetNode = findNode(value);
if (targetNode) {
@@ -389,7 +452,9 @@ module.exports = {
if (targetComp) {
finalValue = targetComp;
} else {
Editor.warn(`[scene-script] 在节点 ${targetNode.name} 上找不到组件 ${propertyType.name}`);
Editor.warn(
`[scene-script] 在节点 ${targetNode.name} 上找不到组件 ${propertyType.name}`,
);
}
}
Editor.log(`[scene-script] 已应用 ${key} 的引用: ${targetNode.name}`);
@@ -399,7 +464,7 @@ module.exports = {
}
} else {
// 3. 通用启发式 (找不到类型时的 fallback)
if (typeof value === 'string' && value.length > 20) {
if (typeof value === "string" && value.length > 20) {
const targetNode = findNode(value);
if (targetNode) {
finalValue = targetNode;
@@ -408,12 +473,12 @@ module.exports = {
// 找不到节点且是 UUID -> 视为资源
const compIndex = node._components.indexOf(component);
if (compIndex !== -1) {
Editor.Ipc.sendToPanel('scene', 'scene:set-property', {
Editor.Ipc.sendToPanel("scene", "scene:set-property", {
id: node.uuid,
path: `_components.${compIndex}.${key}`,
type: 'Object',
type: "Object",
value: { uuid: value },
isSubProp: false
isSubProp: false,
});
Editor.log(`[scene-script] 通过 IPC 启发式解析 ${key} 的资源: ${value}`);
}
@@ -553,7 +618,8 @@ module.exports = {
if (event.reply) event.reply(null, "没有需要更新的属性");
}
} else {
if (event.reply) event.reply(new Error(`找不到组件 (类型: ${componentType}, ID: ${componentId})`));
if (event.reply)
event.reply(new Error(`找不到组件 (类型: ${componentType}, ID: ${componentId})`));
}
} catch (err) {
if (event.reply) event.reply(new Error(`更新组件失败: ${err.message}`));
@@ -576,7 +642,7 @@ module.exports = {
}
// 基础类型是安全的
if (typeof val !== 'object') {
if (typeof val !== "object") {
properties[key] = val;
continue;
}
@@ -599,7 +665,8 @@ module.exports = {
properties[key] = JSON.parse(jsonStr);
} catch (e) {
// 如果 JSON 失败（例如循环引用），格式化为字符串
properties[key] = `[复杂对象: ${val.constructor ? val.constructor.name : typeof val}]`;
properties[key] =
`[复杂对象: ${val.constructor ? val.constructor.name : typeof val}]`;
}
}
} catch (e) {
@@ -647,7 +714,7 @@ module.exports = {
const scene = cc.director.getScene();
if (!scene) {
if (event.reply) event.reply(new Error("Scene not ready or loading."));
if (event.reply) event.reply(new Error("场景尚未准备好或正在加载。"));
return;
}
@@ -885,7 +952,6 @@ module.exports = {
} else {
if (event.reply) event.reply(new Error("找不到父节点"));
}
} else if (action === "update") {
let node = findNode(nodeId);
if (node) {
@@ -903,7 +969,6 @@ module.exports = {
} else {
if (event.reply) event.reply(new Error("找不到节点"));
}
} else if (action === "get_info") {
let node = findNode(nodeId);
if (node) {
@@ -921,7 +986,7 @@ module.exports = {
speed: ps.speed,
angle: ps.angle,
gravity: { x: ps.gravity.x, y: ps.gravity.y },
file: ps.file ? ps.file.name : null
file: ps.file ? ps.file.name : null,
};
if (event.reply) event.reply(null, info);
} else {
@@ -958,12 +1023,12 @@ module.exports = {
switch (action) {
case "get_list":
const clips = anim.getClips();
const clipList = clips.map(c => ({
const clipList = clips.map((c) => ({
name: c.name,
duration: c.duration,
sample: c.sample,
speed: c.speed,
wrapMode: c.wrapMode
wrapMode: c.wrapMode,
}));
if (event.reply) event.reply(null, clipList);
break;
@@ -980,9 +1045,9 @@ module.exports = {
}
const info = {
currentClip: currentClip ? currentClip.name : null,
clips: anim.getClips().map(c => c.name),
clips: anim.getClips().map((c) => c.name),
playOnLoad: anim.playOnLoad,
isPlaying: isPlaying
isPlaying: isPlaying,
};
if (event.reply) event.reply(null, info);
break;

19
src/IpcManager.ts
View File

@@ -1,8 +1,7 @@
// @ts-ignore
const fs = require('fs');
const fs = require("fs");
// @ts-ignore
const path = require('path');
const path = require("path");
/**
* IPC 消息管理器
@@ -16,14 +15,14 @@ export class IpcManager {
public static getIpcMessages(): any[] {
// 获取文档路径
// @ts-ignore
const docPath = Editor.url('packages://mcp-bridge/IPC_MESSAGES.md');
const docPath = Editor.url("packages://mcp-bridge/IPC_MESSAGES.md");
if (!fs.existsSync(docPath)) {
// @ts-ignore
Editor.error(`[IPC Manager] Document not found: ${docPath}`);
Editor.error(`[IPC 管理器] 找不到文档文件: ${docPath}`);
return [];
}
const content = fs.readFileSync(docPath, 'utf-8');
const content = fs.readFileSync(docPath, "utf-8");
const messages: any[] = [];
// 正则匹配 ### `message-name`
@@ -65,7 +64,7 @@ export class IpcManager {
params,
returns,
type,
status
status,
});
}
@@ -95,12 +94,12 @@ export class IpcManager {
if (Editor.Ipc.sendToMain) {
// @ts-ignore
Editor.Ipc.sendToMain(name, args);
resolve({ success: true, message: "Message sent (sendToMain)" });
resolve({ success: true, message: "消息已发送 (sendToMain)" });
} else {
resolve({ success: false, message: "Editor.Ipc.sendToMain not available" });
resolve({ success: false, message: "Editor.Ipc.sendToMain 不可用" });
}
} catch (e: any) {
resolve({ success: false, message: `Error: ${e.message}` });
resolve({ success: false, message: `错误: ${e.message}` });
}
});
}

88
src/IpcUi.ts
View File

@@ -1,4 +1,3 @@
// @ts-ignore
const Editor = window.Editor;
@@ -10,11 +9,18 @@ export class IpcUi {
private filterSelect: HTMLSelectElement | null = null;
private paramInput: HTMLTextAreaElement | null = null;
/**
* 构造函数
* @param root Shadow UI 根节点
*/
constructor(root: ShadowRoot) {
this.root = root;
this.bindEvents();
}
/**
* 绑定 UI 事件
*/
private bindEvents() {
const btnScan = this.root.querySelector("#btnScanIpc");
const btnTest = this.root.querySelector("#btnTestIpc");
@@ -31,52 +37,64 @@ export class IpcUi {
btnTest.addEventListener("confirm", () => this.testSelected());
}
if (cbSelectAll) {
cbSelectAll.addEventListener("change", (e: any) => this.toggleAll(e.detail ? e.detail.value : (e.target.value === 'true' || e.target.checked)));
cbSelectAll.addEventListener("change", (e: any) =>
this.toggleAll(e.detail ? e.detail.value : e.target.value === "true" || e.target.checked),
);
}
if (this.filterSelect) {
this.filterSelect.addEventListener("change", () => this.filterMessages());
}
}
/**
* 扫描 IPC 消息
*/
private scanMessages() {
this.log("Scanning IPC messages...");
this.log("正在扫描 IPC 消息...");
// @ts-ignore
Editor.Ipc.sendToMain("mcp-bridge:scan-ipc-messages", (err: any, msgs: any[]) => {
if (err) {
this.log(`Scan Error: ${err}`);
this.log(`扫描错误: ${err}`);
return;
}
if (msgs) {
this.allMessages = msgs;
this.filterMessages();
this.log(`Found ${msgs.length} messages.`);
this.log(`找到 ${msgs.length} 条消息。`);
} else {
this.log("No messages found.");
this.log("未找到任何消息。");
}
});
}
/**
* 根据当前选择器过滤消息列表
*/
private filterMessages() {
if (!this.allMessages) return;
const filter = this.filterSelect ? this.filterSelect.value : "all";
let filtered = this.allMessages;
if (filter === "available") {
filtered = this.allMessages.filter(m => m.status === "可用");
filtered = this.allMessages.filter((m) => m.status === "可用");
} else if (filter === "unavailable") {
filtered = this.allMessages.filter(m => m.status && m.status.includes("不可用"));
filtered = this.allMessages.filter((m) => m.status && m.status.includes("不可用"));
} else if (filter === "untested") {
filtered = this.allMessages.filter(m => !m.status || m.status === "未测试");
filtered = this.allMessages.filter((m) => !m.status || m.status === "未测试");
}
this.renderList(filtered);
}
/**
* 渲染消息列表 UI
* @param msgs 消息对象数组
*/
private renderList(msgs: any[]) {
if (!this.ipcList) return;
this.ipcList.innerHTML = "";
msgs.forEach(msg => {
msgs.forEach((msg) => {
const item = document.createElement("div");
item.className = "ipc-item";
item.style.padding = "4px";
@@ -84,34 +102,35 @@ export class IpcUi {
item.style.display = "flex";
item.style.alignItems = "center";
// Checkbox
// 复选框
const checkbox = document.createElement("ui-checkbox");
// @ts-ignore
checkbox.value = false;
checkbox.setAttribute("data-name", msg.name);
checkbox.style.marginRight = "8px";
// Content
// 内容区域
const content = document.createElement("div");
content.style.flex = "1";
content.style.fontSize = "11px";
let statusColor = "#888"; // Untested
if (msg.status === "可用") statusColor = "#4CAF50"; // Green
else if (msg.status && msg.status.includes("不可用")) statusColor = "#F44336"; // Red
let statusColor = "#888"; // 未测试
if (msg.status === "可用")
statusColor = "#4CAF50"; // 绿色
else if (msg.status && msg.status.includes("不可用")) statusColor = "#F44336"; // 红色
content.innerHTML = `
<div style="display:flex; justify-content:space-between;">
<span style="color: #4CAF50; font-weight: bold;">${msg.name}</span>
<span style="color: ${statusColor}; font-size: 10px; border: 1px solid ${statusColor}; padding: 0 4px; border-radius: 4px;">${msg.status || "未测试"}</span>
</div>
<div style="color: #888;">${msg.description || "No desc"}</div>
<div style="color: #666; font-size: 10px;">Params: ${msg.params || "None"}</div>
<div style="color: #888;">${msg.description || "无描述"}</div>
<div style="color: #666; font-size: 10px;">参数: ${msg.params || "无"}</div>
`;
// Action Button
// 执行按钮
const btnRun = document.createElement("ui-button");
btnRun.innerText = "Run";
btnRun.innerText = "执行";
btnRun.className = "tiny";
btnRun.style.height = "20px";
btnRun.style.lineHeight = "20px";
@@ -126,28 +145,35 @@ export class IpcUi {
});
}
/**
* 测试所有选中的 IPC 消息
*/
private async testSelected() {
const checkboxes = this.root.querySelectorAll("#ipcList ui-checkbox");
const toTest: string[] = [];
checkboxes.forEach((cb: any) => {
// In Cocos 2.x, ui-checkbox value is boolean
// 在 Cocos 2.x 中, ui-checkbox 的值是布尔型
if (cb.checked || cb.value === true) {
toTest.push(cb.getAttribute("data-name"));
}
});
if (toTest.length === 0) {
this.log("No messages selected.");
this.log("未选择任何消息。");
return;
}
this.log(`Starting batch test for ${toTest.length} messages...`);
this.log(`开始批量测试 ${toTest.length} 条消息...`);
for (const name of toTest) {
await this.runTest(name);
}
this.log("Batch test completed.");
this.log("批量测试完成。");
}
/**
* 运行单个测试请求
* @param name 消息名称
*/
private runTest(name: string): Promise<void> {
return new Promise((resolve) => {
let params = null;
@@ -155,25 +181,29 @@ export class IpcUi {
try {
params = JSON.parse(this.paramInput.value.trim());
} catch (e) {
this.log(`[Error] Invalid JSON Params: ${e}`);
this.log(`[错误] 无效的 JSON 参数: ${e}`);
resolve();
return;
}
}
this.log(`Testing: ${name} with params: ${JSON.stringify(params)}...`);
this.log(`正在测试: ${name}，参数: ${JSON.stringify(params)}...`);
// @ts-ignore
Editor.Ipc.sendToMain("mcp-bridge:test-ipc-message", { name, params }, (err: any, result: any) => {
if (err) {
this.log(`[${name}] Failed: ${err}`);
this.log(`[${name}] 失败: ${err}`);
} else {
this.log(`[${name}] Success: ${JSON.stringify(result)}`);
this.log(`[${name}] 成功: ${JSON.stringify(result)}`);
}
resolve();
});
});
}
/**
* 全选/取消全选
* @param checked 是否选中
*/
private toggleAll(checked: boolean) {
const checkboxes = this.root.querySelectorAll("#ipcList ui-checkbox");
checkboxes.forEach((cb: any) => {
@@ -181,6 +211,10 @@ export class IpcUi {
});
}
/**
* 输出日志到界面
* @param msg 日志消息
*/
private log(msg: string) {
if (this.logArea) {
// @ts-ignore