sanchong-mcp-cocos

这是一个为 Cocos Creator 3.8.x 提供的综合性 MCP (Model Context Protocol) 服务端扩展。它允许 AI 助手（如 Trae, Claude, Cursor）通过标准化协议与 Cocos 编辑器深度交互，实现对编辑器极高自由度的控制。

🚀 功能特性 (Capabilities)

本扩展提供了一整套高复用、高覆盖率的核心工具体系。作为一款全新自主研发的 Cocos MCP 解决方案，它不仅实现了编辑器底层基础操作的全量覆盖，更在自动化工程流上实现了深度突破，为 AI 提供最纯粹、最强大的编辑器控制流：

• 🗺️ 场景与节点管理 (Scene & Node)：支持获取、打开、保存、关闭场景；支持节点的精准查询、创建、销毁、重命名及 Transform 变换（位置/旋转/缩放）的动态修改。
• 🧩 组件与脚本控制 (Component & Script)：支持挂载/移除任意官方组件（cc.Label, cc.Sprite 等）和自定义脚本，自动读取和解析组件属性。提供代码自动生成、写入及触发引擎编译的全自动工作流。
• 📦 预制体高级系统 (Prefab System)：完美实现预制体的浏览、层级解析、动态创建和实例化。支持内部节点、组件及资源的复杂引用同步，完全对齐官方标准的预制体数据结构。
• 🎵 资源与依赖管理 (Asset & Dependency)：提供项目中全局资源的检索（如音频、图片等）、自动挂载、资源导入/删除，以及深度资源依赖关系分析；当前支持图片抠图（背景透明 PNG）等能力。
• ⚙️ 项目与调试辅助 (Project & Debug)：涵盖项目运行状态控制、构建流程触发、偏好设置管理、控制台日志提取以及全局消息广播。
• 🔥 独家高阶自动化 (Advanced Automation)：内置独家的场景性能大盘分析、UI自动流式排版、智能场景历史快照比对、项目僵尸资源扫描清理、组件循环依赖检测。此外，支持一键在场景中搭建节点并挂载脚本/组件、一句话创建并组装精灵节点 (Sprite)、以及一键动态绑定按钮 Click Events 事件的顶级自动化工作流。

📦 安装方法 (Installation)

本项目本质上是一个标准的 Cocos Creator 扩展，同时也内嵌了一个 MCP Node.js 服务。 你可以选择将其作为独立源码包分发，完全不需要发布到 npm！

方式一：源码直接安装（脱离 npm，推荐团队内部使用）

你可以直接将这个源码文件夹打包发给别人，或者放到公司的 Git 仓库里。

1. 将 sanchong-mcp-cocos 文件夹完整拷贝到你的 Cocos Creator 项目的 extensions 目录下（如果没有 extensions 目录，请手动新建一个）。
2. 打开终端，进入该扩展目录：

   cd extensions/sanchong-mcp-cocos

3. 安装依赖并构建：

   npm install
   npm run build

4. 启用扩展：在 Cocos Creator 顶部菜单栏打开：扩展 (Extensions) -> 扩展管理器 (Extension Manager) -> 刷新 (Refresh)，找到 sanchong-mcp-cocos 并点击启用。
5. 启用后，MCP 服务端即在后台自动启动，默认端口为 3000。

方式二：通过 npm 全局/局部安装

如果依然希望通过 npm 包管理：

cd <YOUR_COCOS_PROJECT>/extensions
npm install sanchong-mcp-cocos

# 将安装到 node_modules 里的扩展拷贝为 Creator 可识别的扩展目录
# Windows（PowerShell）
Copy-Item -Recurse -Force node_modules/sanchong-mcp-cocos ./sanchong-mcp-cocos

然后在 Cocos Creator 顶部菜单栏打开：扩展 (Extensions) -> 扩展管理器 (Extension Manager) -> 刷新 (Refresh)，找到 sanchong-mcp-cocos 并点击启用。

📦 发布到 npm (Publish)

如果你希望让别人通过 npm install 获取该扩展：

1. 确认已构建产物（发布时会自动触发构建）：

   npm run build

2. 登录 npm（或使用 npm token）：

   npm login

3. 发布：

   npm publish --access public

常见问题：

• 如果提示 403 / You do not have permission to publish：通常是包名已被占用或你不是该包的 owner。建议改成 scoped 包名，例如 @your-scope/sanchong-mcp-cocos，并同步修改 package.json.name。
• 如果你是第一次发 scoped 包，需要保持 --access public 或在 package.json.publishConfig.access 配置为 public。

使用方法 (Usage)

当扩展在 Cocos Creator 中加载并启用后，它会在本地 http://localhost:3000/sse 启动一个 SSE 服务。 你可以将支持 MCP 的 AI 助手配置为连接到此端点。

AI 文生图说明

当前版本的 ai_generate_image 功能暂未开放，因此无需在 MCP 连接配置中传入 secret，也不需要额外配置 headers。

在 Trae (或 Cursor) 的 MCP 设置中配置：

当前可直接按常规方式连接 SSE 服务：

{
  "mcpServers": {
    "sanchong-mcp-cocos": {
      "url": "http://localhost:3000/sse"
    }
  }
}

注：后续如果重新开放 AI 文生图能力，再单独补充对应的鉴权与参数配置说明。

🛠 工具列表 (Core Tools)

核心工具涵盖了编辑器日常操作的方方面面，采用全新的操作命令前缀：

• cc_scene_ops - 场景管理（获取/打开/保存/关闭场景）；open 的 payload 建议传 sceneUuid 或 scenePath，不要再传旧式对象包装
• cc_scene_typed_ops - 强类型场景操作入口：推荐优先使用；open 直接传 sceneUuid / scenePath，避免手写 payload JSON
• cc_node_ops - 节点查询、生命周期控制、属性与 Transform 变换变更
• cc_node_typed_ops - 强类型节点操作入口：避免手写 payload JSON，适合 create/delete/query/modify_transform/batch_modify/reparent/set_sibling_order
• reparent_node - 高层宏：移动节点到目标父节点下（支持 parentUuid/parentPath + siblingIndex）
• cc_component_ops - 组件增删、脚本挂载与属性数据查询；add 时支持传 scriptPath，由 MCP 自动刷新资源、解析类名并校验 UUID
• cc_component_typed_ops - 强类型组件操作入口：避免手写 payload JSON，适合 add/remove/get_list/set_property/set_properties/batch_set_properties/ensure_component/setup_widget/assign_reference，并支持 nodePath + responseMode
• cc_prefab_ops - 预制体浏览、创建、节点同步与实例化
• cc_prefab_typed_ops - 强类型预制体入口：支持 browse/parse_structure/instantiate/sync_from_node，并支持自动保存场景
• cc_asset_typed_ops - 强类型资产管理入口：支持 search/analyze_deps/mount_audio/scan_zombie_assets/save_image，无需手写 payload JSON
• cc_code_typed_ops - 强类型代码工程入口：支持 generate_script/trigger_compile，避免手写 payload JSON
• cc_project_ops - 项目管理状态与构建管线控制
• cc_debug_ops - 调试信息与日志收集
• cc_camera_typed_ops - 强类型摄像机入口：支持获取主摄像机、设置 clearColor/fov/orthoHeight
• cc_camera_ops - 摄像机专项控制：获取并动态修改 clearColor、fov 等属性
• cc_advanced_ops - 独家拓展能力：场景性能分析、UI排版、智能场景对比等
• cc_advanced_typed_ops - 强类型高级自动化入口：支持性能分析、自动布局、批量重命名，并支持自动保存场景
• create_node_with_component - 自动化进阶：一键在场景中创建节点并挂载指定组件/脚本
• mount_script_by_path - 高级脚本挂载：只传 nodeUuid + scriptPath，MCP 自动解析脚本类名与 UUID，避免错误 UUID 导致 MissingScript
• batch_mount_script_by_path - 批量脚本挂载：将同一个脚本一次性挂到多个节点，并返回逐节点结果汇总
• batch_create_nodes_with_script - 批量创建节点装配：支持统一公共脚本，或为每个节点指定专属 scriptPath，支持自动保存场景
• workflow_ui_setup - UI 工作流：一键创建 UI 页面容器。自动执行建根节点、挂 Widget 铺满、可选建半透明遮罩层并挂载页面脚本的全套动作
• generate_and_mount_script - 脚本工作流：根据文本描述自动生成 Cocos 组件脚本、触发编译，并自动挂载到现有节点或新建页面/节点
• generate_page_skeleton - 页面骨架工作流：根据文本描述自动创建标题区、内容区、按钮区，并可自动生成页面控制器脚本、输入框、列表容器与默认按钮事件
• cc_ui_typed_ops - 强类型 UI 复合节点入口：支持直接创建 Label、带文案的 Button、EditBox、协议勾选、Panel、Dropdown，以及 ScrollView+Content+Layout 列表容器与列表项模板，并支持 responseMode
• find_node_by_path - 按层级路径查找节点：适合代替先 get_hierarchy 再手动遍历
• get_hierarchy_shallow - 浅层层级查询：只看 Canvas、子节点名列表、节点存在性时优先使用
• create_button_with_label - 高层 UI 宏命令：一次创建按钮节点、背景和文案节点
• create_panel_with_title - 高层 UI 宏命令：一次创建面板背景、标题和内容容器
• create_dropdown - 高层 UI 宏命令：一次创建 Trigger、SelectedLabel、Arrow、OptionsPanel 和选项项节点
• set_label_style - 高层文字样式宏命令：一次设置 Label / Outline / Shadow
• replace_sprite_and_resize - 高层精灵宏命令：替换 SpriteFrame 后同步设置 UITransform.contentSize
• batch_transaction - 批处理事务入口：支持顺序执行 ensure_node、ensure_component、set_properties、UI 宏命令、引用绑定和保存场景
• nl_workflow_router - 自然语言自动化入口：直接输入中文需求，MCP 会返回候选意图、执行计划，并支持页面生成 + 背景图等复合工作流的分步执行
• cc_setup_sprite_node - 高级复合工具：一句话创建背景图/精灵节点并连贯赋值资源
• cc_button_ops - 按钮专项绑定：为 cc.Button 动态获取、查重、替换并注入底层 EventHandler，同时支持自动保存场景
• ai_generate_image - AI 创作中心：当前版本暂未开放
• image_cutout - 抠图：去除背景并输出透明背景 PNG（支持自动背景色采样 + 边缘泛洪、或手动指定背景色；可调 tolerance/feather/edgeProtect 等参数）
• 辅助/特化工具：fetch_audio_resources, mount_audio_clip, generate_component_script, update_node_name

脚本生成与挂载建议

为了避免 MissingScript 或脚本 UUID 不一致，推荐遵循以下流程：

1. 通过 cc_code_typed_ops 的 generate_script 写入 ts 脚本，或直接使用 generate_and_mount_script 一步完成“生成 + 编译 + 挂载”。
2. 由 MCP 自动执行 refresh-asset，随后查询脚本 UUID。
3. 优先使用 mount_script_by_path、batch_mount_script_by_path 或 cc_component_typed_ops 挂载脚本，不要手动伪造 .meta 或脚本 UUID。

generate_script 完成后会额外返回：

• componentName：解析出的脚本类名
• scriptUuid：当前引擎分配的脚本 UUID（若仍在编译中，则返回 pending_compile）

推荐调用方式

Token 节省建议：

• 优先给查询类接口传 responseMode: "minimal"，只要 uuid/status/changed 时不要请求完整节点快照
• 查节点优先用 find_node_by_path 或 get_hierarchy_shallow，不要默认跑深层 get_hierarchy
• 设组件属性优先用 set_properties / batch_set_properties，不要连续多次 set_property
• 能传 nodePath 时就不要先查 nodeUuid
• 复杂 UI 组装优先用 create_dropdown、create_button_with_label、create_panel_with_title
• 多步编辑优先用 batch_transaction，把“创建 -> 挂组件 -> 设属性 -> 绑定引用 -> 保存场景”压成一次调用

给 Agent 的推荐提示词：

如果你在 Trae、Cursor、Claude Desktop 等客户端里使用本 MCP，建议把下面这段规则加入到你的项目提示词里：

你正在操作 Cocos Creator MCP。

调用策略：
1. 默认优先使用 typed/high-level 工具，不要优先使用旧的 payload 字符串接口。
2. 默认给查询类接口传 responseMode=minimal；只有在明确需要完整 children/components/tree 时才使用 normal 或 verbose。
3. 查节点优先顺序：
   - find_node_by_path
   - get_hierarchy_shallow
   - 最后才是 get_hierarchy(depth>1)
4. 修改组件属性时：
   - 优先 set_properties / batch_set_properties
   - 不要为了拿 componentUuid 先多次 get_list；如果支持 componentName 或 nodePath，就直接用
5. 创建 UI 时优先顺序：
   - create_dropdown
   - create_button_with_label
   - create_panel_with_title
   - set_label_style
   - replace_sprite_and_resize
   - 最后才是 create node + add component + set_property 的原子链路
6. 多步 UI 搭建或引用绑定优先使用 batch_transaction，把创建节点、挂组件、设属性、绑引用、保存场景合并到一次调用。
7. 能传 nodePath 就不要先查 nodeUuid。
8. 没有明确需求时，不要返回完整 hierarchy、完整组件数组、完整 transform、长 message 或 assetCandidates 列表。

输出目标：
- 优先最少调用次数
- 优先最小返回体
- 优先高层宏命令

推荐工作流：

• 查一个节点是否存在：find_node_by_path
• 看某个容器下一级子节点：get_hierarchy_shallow
• 改一个 Label 的多项样式：set_label_style 或 set_properties
• 替图并同步改尺寸：replace_sprite_and_resize
• 创建完整下拉框：create_dropdown
• 创建面板、标题、按钮、绑定引用的一整套流程：batch_transaction

场景打开/保存：

推荐优先使用 cc_scene_typed_ops，不要再生成旧的 payload.uuid / payload.path 写法。

{
  "action": "open",
  "scenePath": "db://assets/scenes/Main.scene",
  "saveBeforeOpen": true,
  "refreshAssetDb": true
}

{
  "action": "open",
  "sceneUuid": "12345678-1234-1234-1234-123456789abc"
}

{
  "action": "save",
  "refreshAssetDb": true
}

{
  "action": "save",
  "refreshAssetDb": true,
  "allowExternalChanges": true
}

{
  "action": "close",
  "saveBeforeClose": true
}

如果必须使用 cc_scene_ops，payload 也请保持为：

{
  "action": "open",
  "payload": "{\"scenePath\":\"db://assets/scenes/Main.scene\"}"
}

自然语言自动化入口：

说明：

• nl_workflow_router 会先输出 intentCandidates 和 executionPlan，便于查看它识别到了哪些意图、准备如何执行
• 对“创建页面 + 生成脚本 + 加背景图”这类复合请求，会按计划逐步执行，而不是像早期版本那样只命中第一个分支
• 当缺少 nodeUuid、scriptPath、assetPath 等关键参数时，会在返回结果里给出 missing 和 suggestions
• save 默认会阻止“场景文件已被磁盘外部修改”后的覆盖保存；如确认要以当前编辑器内存态覆盖磁盘文件，可显式传 allowExternalChanges: true

{
  "request": "创建一个全屏 LoginView 页面，挂载 scripts/ui/LoginView.ts，并加黑色遮罩",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

自然语言场景切换：

{
  "request": "打开场景 db://assets/scenes/Main.scene",
  "autoSaveScene": false
}

{
  "request": "先保存当前场景，再打开 assets/scenes/Login.scene",
  "autoSaveScene": false
}

自然语言场景查询：

{
  "request": "当前打开的场景是什么"
}

这类查询会命中 scene_info，返回当前场景名称、UUID 等基础信息；如果编辑器环境能探测到场景未保存状态，还会额外返回 scene.isDirty 与 scene.dirtySource，否则这两个字段会是 null。

{
  "request": "查看当前场景树"
}

{
  "request": "先保存当前场景，再关闭当前场景"
}

说明：当前 nl_workflow_router 已支持自然语言识别“打开场景 / 保存场景 / 关闭当前场景 / 当前场景信息 / 场景层级树”。同场景 reopen/reload 会先触发 close-scene，再重新 open-scene，以便强制从磁盘重载。当前场景信息里的 scene.isDirty / scene.dirtySource 仅是 best-effort 探测结果，可能为 null。

自然语言挂脚本：

{
  "request": "给这个节点挂载 scripts/ui/Header.ts 脚本",
  "nodeUuid": "NODE_UUID"
}

自然语言生成脚本并挂载：

{
  "request": "生成一个登录页控制器脚本并挂到页面上，包含打开关闭和登录按钮点击处理",
  "scriptPath": "scripts/ui/LoginView.ts",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

自然语言页面骨架装配：

{
  "request": "创建一个登录弹窗，包含标题、内容区、确认按钮和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

{
  "request": "创建一个列表页，包含标题、内容区、列表区和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

{
  "request": "创建一个登录页面，包含标题、账号输入框、密码输入框、登录按钮和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

{
  "request": "创建一个注册页面，包含标题、手机号输入框、验证码输入框、协议勾选、提交按钮和返回按钮",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

{
  "request": "创建一个列表页，包含标题、列表区、列表项模板和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

自然语言高级自动化：

{
  "request": "把这个节点下的子节点竖向自动布局，间距 20",
  "nodeUuid": "ROOT_NODE_UUID",
  "autoSaveScene": true
}

自然语言 prefab 自动化：

{
  "request": "实例化一个 LoginPanel prefab 到 Canvas 下",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

{
  "request": "浏览当前场景里的 prefab 实例"
}

{
  "request": "把这个节点下的子节点批量改名，前缀 Btn_，从 1 开始，补零 3 位",
  "nodeUuid": "ROOT_NODE_UUID",
  "autoSaveScene": true
}

单节点挂载脚本：

{
  "nodeUuid": "NODE_UUID",
  "scriptPath": "scripts/player/PlayerController.ts"
}

脚本一站式工作流：

{
  "scriptPath": "scripts/ui/LoginView.ts",
  "description": "登录页控制器，包含打开关闭、登录按钮点击处理和内容根节点引用",
  "parentUuid": "CANVAS_UUID",
  "nodeName": "LoginView",
  "createAsPage": true,
  "isFullScreen": true,
  "addMask": true,
  "autoSaveScene": true
}

页面骨架工作流：

{
  "pageName": "LoginDialog",
  "description": "登录弹窗，包含标题、内容区、确认按钮和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "template": "dialog",
  "autoGenerateScript": true,
  "autoSaveScene": true
}

{
  "pageName": "LoginPage",
  "description": "登录页面，包含标题、账号输入框、密码输入框、登录按钮和关闭按钮",
  "parentUuid": "CANVAS_UUID",
  "template": "fullscreen-page",
  "autoGenerateScript": true,
  "autoSaveScene": true
}

{
  "pageName": "RegisterPage",
  "description": "注册页面，包含标题、手机号输入框、验证码输入框、协议勾选、提交按钮和返回按钮",
  "parentUuid": "CANVAS_UUID",
  "template": "fullscreen-page",
  "autoGenerateScript": true,
  "autoSaveScene": true
}

说明：

• 当描述中包含“验证码”时，页面工作流会自动生成一个 获取验证码 按钮
• 当描述中包含“列表页/列表项”时，页面工作流会自动生成 ItemTemplate 以及 3 个示例列表项
• 页面工作流会对 Content 区域自动做一次纵向布局
• 页面脚本在命中“验证码”时会自动生成 onClickCaptcha() 倒计时处理
• 列表页在生成 ItemTemplate 后，会自动额外生成并挂载 scripts/auto/<PageName>ItemRenderer.ts
• 当页面脚本存在时，列表页会自动隐藏 ItemTemplate，并由页面脚本通过 refreshView() / renderList() 克隆模板渲染列表数据
• 页面脚本在登录/注册/提交类表单里会自动带一个 validateForm() 校验模板
• 表单页脚本会自动生成 collectFormData()、requestSubmit()、submit(payload)、onSubmitSuccess()、onSubmitFailed()、resetForm()，并带 setSubmitButtonText()、setSubmitButtonEnabled()、setLoadingState()；主按钮点击默认走“校验 -> 收集数据 -> 提交”流程，提交中会自动禁用按钮并切换为“提交中...”
• 验证码按钮会自动更新倒计时文案
• ItemRenderer.setData() 默认支持 string 或 { title / label / text } 结构
• 页面工作流会自动把 titleLabel、contentRoot、btnPrimary、btnClose、btnCaptcha、captchaLabel、listView、itemTemplate、agreementToggle 以及常见输入框属性回填到生成脚本上
• 登录/注册/提交类表单脚本会按输入语义自动生成 inputAccount、inputPhone、inputPassword、inputCaptcha 等强类型字段，并带基础校验逻辑
• 列表页脚本默认内置一组预览数据，start() 会自动调用 refreshView()，生成出来即可看到列表效果

UI 复合节点：

{
  "action": "create_button",
  "parentUuid": "PARENT_UUID",
  "nodeName": "BtnLogin",
  "text": "登录",
  "fontSize": 28,
  "width": 220,
  "height": 72,
  "autoSaveScene": true
}

{
  "action": "create_dropdown",
  "parentUuid": "PARENT_UUID",
  "nodeName": "ActionDropdown",
  "defaultValue": "请选择",
  "optionsJson": "[\"攻击\",\"防御\",\"背包\"]",
  "width": 300,
  "height": 60,
  "itemHeight": 42,
  "fontSize": 22,
  "responseMode": "minimal",
  "autoSaveScene": true
}

{
  "action": "create_panel_with_title",
  "parentUuid": "PARENT_UUID",
  "nodeName": "ShopPanel",
  "title": "商店",
  "width": 640,
  "height": 860,
  "titleFontSize": 30,
  "responseMode": "minimal",
  "autoSaveScene": true
}

{
  "action": "create_edit_box",
  "parentUuid": "PARENT_UUID",
  "nodeName": "InputAccount",
  "placeholder": "请输入账号",
  "width": 520,
  "height": 64,
  "autoSaveScene": true
}

{
  "action": "create_toggle",
  "parentUuid": "PARENT_UUID",
  "nodeName": "AgreementToggle",
  "text": "我已阅读并同意用户协议",
  "isChecked": false,
  "autoSaveScene": true
}

{
  "action": "create_list_item",
  "parentUuid": "LIST_CONTENT_UUID",
  "nodeName": "ItemTemplate",
  "text": "列表项",
  "width": 680,
  "height": 72,
  "autoSaveScene": true
}

强类型组件操作：

{
  "action": "add",
  "nodeUuid": "NODE_UUID",
  "scriptPath": "scripts/ui/PageController.ts",
  "autoSaveScene": true
}

{
  "action": "ensure_component",
  "nodePath": "Canvas/LoginPanel/Title",
  "componentName": "cc.Label",
  "responseMode": "minimal"
}

{
  "action": "set_properties",
  "nodePath": "Canvas/LoginPanel/Title",
  "componentName": "cc.Label",
  "propertiesJson": "{\"string\":\"登录\",\"fontSize\":32,\"lineHeight\":36,\"color\":{\"valueKind\":\"color\",\"colorHex\":\"#FFFFFF\"}}",
  "responseMode": "minimal",
  "autoSaveScene": true
}

{
  "action": "batch_set_properties",
  "nodePath": "Canvas/LoginPanel/Icon",
  "componentName": "cc.UITransform",
  "propertiesJson": "{\"contentSize\":{\"valueKind\":\"size\",\"size\":{\"width\":128,\"height\":128}}}",
  "responseMode": "minimal"
}

{
  "action": "assign_reference",
  "nodeUuid": "PAGE_NODE_UUID",
  "componentUuid": "PAGE_COMPONENT_UUID",
  "property": "btnPrimary",
  "referenceTargetNodeUuid": "BTN_PRIMARY_NODE_UUID",
  "autoSaveScene": true
}

批量挂载同一脚本：

{
  "scriptPath": "scripts/ui/PageController.ts",
  "nodeUuids": ["NODE_A", "NODE_B", "NODE_C"],
  "autoSaveScene": true
}

强类型创建节点：

{
  "action": "create",
  "nodeName": "LoginPanel",
  "parentUuid": "PARENT_UUID",
  "position": { "x": 0, "y": 0, "z": 0 }
}

强类型批量修改节点：

{
  "action": "batch_modify",
  "nodeUuids": ["NODE_A", "NODE_B"],
  "active": true,
  "position": { "x": 100, "y": 200 }
}

强类型场景操作：

{
  "action": "get_current"
}

{
  "action": "get_hierarchy",
  "depth": 1,
  "responseMode": "minimal"
}

路径查询与浅层层级：

{
  "nodePath": "Canvas/LoginPanel/BtnLogin",
  "responseMode": "minimal"
}

{
  "path": "Canvas/LoginPanel",
  "depth": 1,
  "responseMode": "minimal"
}

高层文字与精灵宏命令：

{
  "nodePath": "Canvas/LoginPanel/Title",
  "text": "登录",
  "fontSize": 32,
  "lineHeight": 36,
  "colorHex": "#FFFFFF",
  "enableOutline": true,
  "outlineColorHex": "#000000",
  "outlineWidth": 2,
  "responseMode": "minimal",
  "autoSaveScene": true
}

{
  "nodePath": "Canvas/LoginPanel/Icon",
  "assetPath": "assets/ui/common/icon_login.png",
  "width": 128,
  "height": 128,
  "responseMode": "minimal",
  "autoSaveScene": true
}

批处理事务：

{
  "stepsJson": "[{\"id\":\"panel\",\"op\":\"ensure_node\",\"params\":{\"path\":\"Canvas/LoginPanel\"}},{\"id\":\"title\",\"op\":\"ensure_component\",\"params\":{\"nodePath\":\"Canvas/LoginPanel/Title\",\"componentName\":\"cc.Label\"}},{\"op\":\"set_properties\",\"params\":{\"nodePath\":\"Canvas/LoginPanel/Title\",\"componentName\":\"cc.Label\",\"properties\":{\"string\":\"登录\",\"fontSize\":32}}},{\"id\":\"dropdown\",\"op\":\"create_dropdown\",\"params\":{\"parentUuid\":\"$step.panel.nodeUuid\",\"nodeName\":\"ServerDropdown\",\"defaultValue\":\"一区\",\"options\":[\"一区\",\"二区\",\"三区\"]}},{\"op\":\"save_scene\",\"params\":{}}]",
  "responseMode": "minimal"
}

说明：

• batch_transaction.stepsJson 里的每一步可用 id 命名，后续步骤可通过 $step.<id>.<field> 引用前序结果
• 也支持 $last.xxx 读取上一步结果
• 默认遇错即停；如需“尽量执行完”，可传 continueOnError: true

返回的 scene 里会尽力附带 isDirty 与 dirtySource 字段，用于暴露当前编辑器内场景是否存在未保存改动的探测结果；由于 Cocos Creator 3.8 扩展侧没有确认稳定的官方查询接口，该字段是 best-effort 信息，探测不到时会返回 null，不要把它当作 save/open 的强校验依据。

示例返回：

{
  "status": "success",
  "scene": {
    "name": "Main",
    "uuid": "651a3184-e2ac-4984-9638-5ad6de0a2b91",
    "isDirty": null,
    "dirtySource": null,
    "childCount": 1,
    "children": [
      {
        "name": "Canvas",
        "uuid": "CANVAS_UUID"
      }
    ]
  }
}

强类型摄像机操作：

{
  "action": "set_property",
  "clearColor": "#000000",
  "fov": 60
}

强类型高级自动化：

{
  "action": "auto_ui_layout",
  "rootUuid": "ROOT_NODE_UUID",
  "direction": "vertical",
  "spacing": 20,
  "autoSaveScene": true
}

强类型 prefab 操作：

{
  "action": "instantiate",
  "prefabName": "LoginPanel",
  "parentUuid": "CANVAS_UUID",
  "autoSaveScene": true
}

项目与调试：

{
  "action": "get_status"
}

{
  "action": "health_check"
}

{
  "action": "browse",
  "rootUuid": "CANVAS_UUID",
  "deep": true
}

{
  "action": "smart_batch_rename",
  "rootUuid": "ROOT_NODE_UUID",
  "prefix": "Btn_",
  "pattern": "{prefix}{index}",
  "startIndex": 1,
  "padding": 3,
  "autoSaveScene": true
}

强类型生成脚本：

{
  "action": "generate_script",
  "scriptPath": "scripts/ui/LoginView.ts",
  "content": "import { _decorator, Component } from 'cc';\nconst { ccclass } = _decorator;\n\n@ccclass('LoginView')\nexport class LoginView extends Component {}\n"
}

批量创建节点装配（支持专属脚本）：

{
  "scriptPath": "scripts/ui/CommonItem.ts",
  "autoSaveScene": true,
  "nodes": [
    { "nodeName": "Header", "parentUuid": "CANVAS", "scriptPath": "scripts/ui/Header.ts" },
    { "nodeName": "Item1", "parentUuid": "CANVAS", "position": { "y": -100 } },
    { "nodeName": "Item2", "parentUuid": "CANVAS", "position": { "y": -200 } }
  ]
}

UI 页面一键生成工作流：

{
  "pageName": "LoginView",
  "scriptPath": "scripts/ui/LoginView.ts",
  "parentUuid": "CANVAS_UUID",
  "isFullScreen": true,
  "addMask": true
}

🔗 资源 (Resources)

• cocos://audio_preview_url

📄 协议 (License)

MIT License