From 8df6f5a415bbc0eddd611ba286b46efd689b534d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=81=AB=E7=84=B0=E5=BA=93=E6=8B=89?= <820449643@qq.com> Date: Thu, 12 Feb 2026 23:36:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=20=E5=BC=BA=E5=8C=96=20AI?= =?UTF-8?q?=20=E5=88=B7=E6=96=B0=E6=80=A7=E8=83=BD=E8=AD=A6=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在 manage_editor 描述中加入⚠️警告，强制要求使用 path 避免全量刷新 - AI 安全守则更新为 4 条，包含禁止全局刷新要求 - 注意事项文档同步强化路径要求警示 --- UPDATE_LOG.md | 6 +++--- main.js | 6 +++--- 注意事项.md | 6 +++++- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/UPDATE_LOG.md b/UPDATE_LOG.md index ba14fcd..ebac93c 100644 --- a/UPDATE_LOG.md +++ b/UPDATE_LOG.md @@ -103,10 +103,10 @@ - **问题**: 原实现使用 `forEach` 并行派发所有子操作，多个 `AssetDB` 操作同时执行引发编辑器卡死。 - **修复**: 改为串行链式执行（`next()` 递归调用），确保每个操作完成后再执行下一个。 -### 4. `refresh_editor` 路径参数优化 +### 4. `refresh_editor` 路径参数优化与警示强化 -- **问题**: 默认刷新 `db://assets/scripts`（后改为 `db://assets`），在大型生产项目中 `AssetDB.refresh()` 耗时可达 3 分钟。 -- **修复**: 工具 Schema 新增 `properties.path` 参数说明，支持指定精确刷新路径（如单个文件 `db://assets/resources/sdk_config.json` 或目录 `db://assets/resources`），大幅减少刷新耗时。 +- **工具 Schema 强化**: 在 `manage_editor` 的工具描述中加入红色警示符号 (⚠️) 和“极为重要”字样，明确要求 AI 必须指定 `path`。 +- **AI 安全守则第 4 条**: 在全局 `globalPrecautions` 中新增第四条守则，强制要求 AI 避免刷新全局资源。 - **实测效果**: 生产项目中，从默认全量刷新 **172 秒** 降至指定目录刷新 **19 秒**。 ### 5. 杂项修复 diff --git a/main.js b/main.js index 7c6d879..a227880 100644 --- a/main.js +++ b/main.js @@ -169,7 +169,7 @@ const getNewSceneTemplate = () => { */ const getToolsList = () => { 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 [ { name: "get_selected_node", @@ -299,7 +299,7 @@ const getToolsList = () => { }, { name: "manage_script", - description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本后，编辑器需要时间进行编译（通常几秒钟）。新脚本在编译完成前无法作为组件添加到节点。建议在 create 后调用 refresh_editor，或等待一段时间后再使用 manage_components。`, + description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本后，编辑器需要时间进行编译（通常几秒钟）。新脚本在编译完成前无法作为组件添加到节点。建议在 create 后调用 refresh_editor (务必指定 path 到具体文件)，或等待一段时间后再使用 manage_components。`, inputSchema: { type: "object", properties: { @@ -402,7 +402,7 @@ const getToolsList = () => { properties: { type: "object", 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"], diff --git a/注意事项.md b/注意事项.md index 6ddbcf3..357982d 100644 --- a/注意事项.md +++ b/注意事项.md @@ -119,7 +119,11 @@ 2. `batchExecute` 内部也已从并行 `forEach` 改为串行链式执行。 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 连接堆积。 - **解决方案**：所有 `callSceneScript` 调用均通过 `callSceneScriptWithTimeout` 包装，默认 15 秒超时。超时后自动返回错误，释放 HTTP 连接和队列位置。