修复: manage_script 取值丢失错误，强化 prompt 加载和生成 meta，全量更新相关文档
This commit is contained in:
火焰库拉
@@ -116,6 +116,11 @@ startServer(port) {
|
||||
- **协议修正**: 经过测试对比，最终确认使用 `scene:enter-prefab-edit-mode` 消息并配合 `Editor.Ipc.sendToAll` 是进入预制体编辑模式的最佳方案，解决了 `scene:open-by-uuid` 无法触发编辑状态的问题。
|
||||
- **文档深度补全**: 遵循全局开发规范，同步更新了所有技术文档，确保 100% 简体中文覆盖及详尽的 JSDoc 注释。
|
||||
|
||||
### 2026-02-25: 修复 manage_script 路径引用错误与强制生成 Meta
|
||||
|
||||
- **缺陷修正**: 修复了 `main.js` 中 `manageScript` 处理 `create` 动作时由于变量名解构导致 `path.dirname` 找不到 `path` 引用的问题。现已改为使用预设的 `pathModule` 模块。
|
||||
- **规范强化**: 将 `manage_script` 的工具提示（Prompt）更新为强制要求调用 `refresh_editor` 生成脚本的 `.meta` 文件，以确保新创建的脚本能够被正确挂载为组件，同时不增加整体 Token 消耗。
|
||||
|
||||
### 3.2 MCP 工具注册
|
||||
|
||||
在 `/list-tools` 接口中注册工具：
|
||||
|
||||
@@ -171,7 +171,7 @@ Args: [你的项目所在盘符]:/[项目路径]/packages/mcp-bridge/mcp-proxy.j
|
||||
|
||||
### 9. manage_script
|
||||
|
||||
- **描述**: 管理脚本文件，默认创建 TypeScript 脚本
|
||||
- **描述**: 管理脚本文件，默认创建 TypeScript 脚本。**注意**：创建或修改脚本后，此工具没有主动刷新资源库。如果将要作为组件挂载到节点，创建后**必须**接着显式调用 `refresh_editor` 工具（传递精准路径参数）以便编辑器生成 `.meta` 文件并分配 UUID，否则无法作为组件添加。
|
||||
- **参数**:
|
||||
- `action`: 操作类型（`create`, `delete`, `read`, `write`）
|
||||
- `path`: 脚本路径，如 `db://assets/scripts/NewScript.ts`
|
||||
|
||||
@@ -126,17 +126,20 @@
|
||||
## 八、 Token 消耗深度优化 (2026-02-24)
|
||||
|
||||
### 1. 工具描述精简 (`main.js`)
|
||||
|
||||
- **问题**: `globalPrecautions` (AI 安全守则) 被硬编码到所有工具的 `description` 中，导致每次环境初始化或查阅工具列表时浪费约 2200 个 CJK Token。
|
||||
- **优化**: 收束安全守则的广播范围。目前仅针对高风险的**写操作**（如 `manage_components`, `update_node_transform`, `manage_material`, `create_node` 等）保留警告，低风险或只读分析类工具（如 `get_scene_hierarchy`, `get_selected_node`）已悉数移除该文本。
|
||||
- **效果**: `/list-tools` 整体负载字符数缩减近 40%。
|
||||
|
||||
### 2. 长数据截断保护 (`scene-script.js`)
|
||||
|
||||
- **问题**: `manage_components(get)` 会完整序列化多边形坐标集、曲线数据数组以及 Base64 图片，产生极其庞大且对 AI 无用的 JSON 负载。
|
||||
- **优化**:
|
||||
- **数组截断**: 长度超过 10 的数组直接返回 `[Array(length)]`，彻底杜绝数据雪崩。
|
||||
- **字符串截断**: 长度超过 200 的字符串限制为截断显示并附带 `...[Truncated, total length: X]` 提示。
|
||||
|
||||
### 3. 层级树获取瘦身与分页 (`get_scene_hierarchy`)
|
||||
|
||||
- **问题**: 请求场景层级时会一次性返回完整 1000+ 节点的深层结构，包括所有变换矩阵。
|
||||
- **优化**:
|
||||
- 支持 `depth` 深度限制（默认 2 层）。
|
||||
@@ -144,8 +147,26 @@
|
||||
- 添加 `includeDetails` 参数。默认关闭，此时剥离坐标、缩放与尺寸指标，且将冗长的组件详细结构浓缩成简化的名称数组（如 `["Sprite", "Button"]`）。
|
||||
|
||||
### 4. 查找结果精简 (`find_gameobjects`)
|
||||
|
||||
- **优化**: 将原本包含 Transform（位移/缩放/尺寸）全量数据的匹配回传，精简为仅包含核心识别特征的基础集 (`uuid`, `name`, `active`, `components`, `childrenCount`)，极大释放了同名大批量查找时的 Token 压力。
|
||||
|
||||
### 5. 底层鲁棒性大修
|
||||
|
||||
- **问题**: 上述优化在应用过程中暴露出遍历未命名根节点（如 `cc.Scene`）时遭遇 `undefined.startsWith` 报错并引发 IPC 悬挂的致命隐患。
|
||||
- **修复**: 在 `dumpNodes` 与 `searchNode` 中增设前置安全屏障，并修复 `cc.js.getClassName(c)` 替代底层的 `__typename` 来兼容 2.4 获取有效类名。修复了 `main.js` 中关于 `get_scene_hierarchy` 的参数传递脱节问题。
|
||||
|
||||
---
|
||||
|
||||
## 九、 脚本管理修复与强化 (2026-02-25)
|
||||
|
||||
### 1. `manage_script` 路径引用错误修复
|
||||
|
||||
- **问题**: AI 在调用 `manage_script` 工具执行 `create` 创建脚本时，出现 `path is not defined` 报错。
|
||||
- **原因**: 传入的变量 `path` 已经被解构重命名为 `scriptPath`，而在后续获取物理路径时，错误地调用了 `path.dirname()`，导致引用错误。
|
||||
- **修复**: 将 `path.dirname` 修正为全局正确引入的 `pathModule.dirname`，彻底解决了使用此工具生成自定义脚本库时的崩溃问题。
|
||||
|
||||
### 2. 强制生成 Script Meta 文件的提示词 (Prompt) 优化
|
||||
|
||||
- **问题**: AI 助手创建或修改脚本后，若不主动触发系统刷新，后续试图通过 `manage_components` 将该新脚本挂载为组件时，会由于缺乏有效的 `.meta` 扫描和 UUID 索引而失败。
|
||||
- **优化**: 在 `main.js` 中的 `manage_script` 工具 `description` 提示词中，将原本建议性质的刷新语气，修改为严格指令：“**创建后必须调用 refresh_editor (务必指定 path) 生成 meta 文件，否则无法作为组件添加**”。
|
||||
- **效益**: 在不增加 Token 开销的前提下，强制规范了大语言模型的行为，保障了脚本创建到组件挂载工作流的健壮性。
|
||||
|
||||
16
main.js
16
main.js
@@ -200,9 +200,12 @@ const getToolsList = () => {
|
||||
type: "object",
|
||||
properties: {
|
||||
nodeId: { type: "string", description: "指定的根节点 UUID。如果不传则获取整个场景的根。" },
|
||||
depth: { type: "number", description: "遍历的深度限制，默认为 2。用来防止过大场景导致返回数据超长。" },
|
||||
includeDetails: { type: "boolean", description: "是否包含坐标、缩放等杂项详情，默认为 false。" }
|
||||
}
|
||||
depth: {
|
||||
type: "number",
|
||||
description: "遍历的深度限制，默认为 2。用来防止过大场景导致返回数据超长。",
|
||||
},
|
||||
includeDetails: { type: "boolean", description: "是否包含坐标、缩放等杂项详情，默认为 false。" },
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
@@ -320,7 +323,7 @@ const getToolsList = () => {
|
||||
},
|
||||
{
|
||||
name: "manage_script",
|
||||
description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本后，编辑器需要时间进行编译（通常几秒钟）。新脚本在编译完成前无法作为组件添加到节点。建议在 create 后调用 refresh_editor (务必指定 path 到具体文件)，或等待一段时间后再使用 manage_components。`,
|
||||
description: `${globalPrecautions} 管理脚本文件。注意：创建或修改脚本需时间编译。创建后必须调用 refresh_editor (务必指定 path) 生成 meta 文件，否则无法作为组件添加。`,
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
@@ -437,7 +440,8 @@ const getToolsList = () => {
|
||||
properties: {
|
||||
conditions: {
|
||||
type: "object",
|
||||
description: "查找条件。支持的属性：name (节点名称，支持模糊匹配), component (包含的组件类名，如 'cc.Sprite'), active (布尔值，节点的激活状态)。"
|
||||
description:
|
||||
"查找条件。支持的属性：name (节点名称，支持模糊匹配), component (包含的组件类名，如 'cc.Sprite'), active (布尔值，节点的激活状态)。",
|
||||
},
|
||||
recursive: { type: "boolean", default: true, description: "是否递归查找所有子节点" },
|
||||
},
|
||||
@@ -1212,7 +1216,7 @@ module.exports = {
|
||||
}
|
||||
// 确保父目录存在
|
||||
const absolutePath = Editor.assetdb.urlToFspath(scriptPath);
|
||||
const dirPath = path.dirname(absolutePath);
|
||||
const dirPath = pathModule.dirname(absolutePath);
|
||||
if (!fs.existsSync(dirPath)) {
|
||||
fs.mkdirSync(dirPath, { recursive: true });
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user