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

文档: 强化 AI 刷新性能警示

Browse Source 
- 在 manage_editor 描述中加入⚠️警告，强制要求使用 path 避免全量刷新
- AI 安全守则更新为 4 条，包含禁止全局刷新要求
- 注意事项文档同步强化路径要求警示
This commit is contained in:
火焰库拉
2026-02-12 23:36:21 +08:00
parent 5989a388f8
commit 8df6f5a415
3 changed files with 11 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
UPDATE_LOG.md
View File

@@ -103,10 +103,10 @@
- **问题**: 原实现使用 `forEach` 并行派发所有子操作，多个 `AssetDB` 操作同时执行引发编辑器卡死。 - **问题**: 原实现使用 `forEach` 并行派发所有子操作，多个 `AssetDB` 操作同时执行引发编辑器卡死。
- **修复**: 改为串行链式执行（`next()` 递归调用），确保每个操作完成后再执行下一个。 - **修复**: 改为串行链式执行（`next()` 递归调用），确保每个操作完成后再执行下一个。
### 4. `refresh_editor` 路径参数优化 ### 4. `refresh_editor` 路径参数优化与警示强化
- **问题**: 默认刷新 `db://assets/scripts`（后改为 `db://assets`），在大型生产项目中 `AssetDB.refresh()` 耗时可达 3 分钟。 - **工具 Schema 强化**: 在 `manage_editor` 的工具描述中加入红色警示符号 (⚠️) 和“极为重要”字样，明确要求 AI 必须指定 `path`。
- **修复**: 工具 Schema 新增 `properties.path` 参数说明，支持指定精确刷新路径（如单个文件 `db://assets/resources/sdk_config.json` 或目录 `db://assets/resources`），大幅减少刷新耗时。 - **AI 安全守则第 4 条**: 在全局 `globalPrecautions` 中新增第四条守则，强制要求 AI 避免刷新全局资源。
- **实测效果**: 生产项目中，从默认全量刷新 **172 秒** 降至指定目录刷新 **19 秒**。 - **实测效果**: 生产项目中，从默认全量刷新 **172 秒** 降至指定目录刷新 **19 秒**。
### 5. 杂项修复 ### 5. 杂项修复

6
main.js
View File

@@ -169,7 +169,7 @@ const getNewSceneTemplate = () => {
*/ */
const getToolsList = () => { const getToolsList = () => {
const globalPrecautions = const globalPrecautions =
"【AI 安全守则】: 1. 执行任何写操作前必须先通过 get_scene_hierarchy 或 manage_components(get) 验证主体存在。 2. 严禁基于假设盲目猜测属性名。 3. 资源属性（如 cc.Prefab）必须通过 UUID 进行赋值。"; "【AI 安全守则】: 1. 执行任何写操作前必须先通过 get_scene_hierarchy 或 manage_components(get) 验证主体存在。 2. 严禁基于假设盲目猜测属性名。 3. 资源属性（如 cc.Prefab）必须通过 UUID 进行赋值。 4. 严禁频繁刷新全局资源 (refresh_editor)，必须通过 properties.path 指定具体修改的文件或目录以防止编辑器长期卡死。";
return [ return [
{ {
name: "get_selected_node", name: "get_selected_node",
@@ -299,7 +299,7 @@ const getToolsList = () => {
}, },
{ {
name: "manage_script", name: "manage_script",
description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本后，编辑器需要时间进行编译（通常几秒钟）。新脚本在编译完成前无法作为组件添加到节点。建议在 create 后调用 refresh_editor，或等待一段时间后再使用 manage_components。`, description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本后，编辑器需要时间进行编译（通常几秒钟）。新脚本在编译完成前无法作为组件添加到节点。建议在 create 后调用 refresh_editor (务必指定 path 到具体文件)，或等待一段时间后再使用 manage_components。`,
inputSchema: { inputSchema: {
type: "object", type: "object",
properties: { properties: {
@@ -402,7 +402,7 @@ const getToolsList = () => {
properties: { properties: {
type: "object", type: "object",
description: description:
"操作属性。refresh_editor 支持 properties.path 指定刷新路径（如 'db://assets/scripts/MyScript.ts' 或 'db://assets/resources'）。不传则默认刷新 'db://assets'（全量刷新，大型项目可能耗时数分钟，建议尽量指定具体路径）。", "操作属性。⚠️极为重要：refresh_editor 必须通过 properties.path 指定精确的刷新路径（如 'db://assets/scripts/MyScript.ts'）。严禁不带 path 参数进行全局刷新 (db://assets)，这在大型项目中会导致编辑器卡死数分钟，严重阻塞工作流。",
}, },
}, },
required: ["action"], required: ["action"],

6
注意事项.md
View File

@@ -119,7 +119,11 @@
2. `batchExecute` 内部也已从并行 `forEach` 改为串行链式执行。 2. `batchExecute` 内部也已从并行 `forEach` 改为串行链式执行。
3. 队列长度会在日志中显示（`REQ -> [toolName] (队列长度: N)`），可用于排查积压问题。 3. 队列长度会在日志中显示（`REQ -> [toolName] (队列长度: N)`），可用于排查积压问题。
### 9.2 IPC 超时保护 (callSceneScriptWithTimeout) ### 9.2 `refresh_editor` 路径要求
- **⚠️ 必须带路径**：在调用 `manage_editor` 的 `refresh_editor` 时，务必通过 `properties.path` 指定精确的文件或目录（如 `db://assets/scripts/Test.ts`）。严禁空参数进行全局刷新，在生产项目中会导致数分钟的编辑器卡死。
### 9.3 IPC 超时保护 (callSceneScriptWithTimeout)
- **背景**：`Editor.Scene.callSceneScript` 的回调依赖 Scene 面板响应 IPC 消息。如果主线程阻塞，Scene 面板无法处理消息，导致 callback 永远不返回，HTTP 连接堆积。 - **背景**：`Editor.Scene.callSceneScript` 的回调依赖 Scene 面板响应 IPC 消息。如果主线程阻塞，Scene 面板无法处理消息，导致 callback 永远不返回，HTTP 连接堆积。
- **解决方案**：所有 `callSceneScript` 调用均通过 `callSceneScriptWithTimeout` 包装，默认 15 秒超时。超时后自动返回错误，释放 HTTP 连接和队列位置。 - **解决方案**：所有 `callSceneScript` 调用均通过 `callSceneScriptWithTimeout` 包装，默认 15 秒超时。超时后自动返回错误，释放 HTTP 连接和队列位置。