通病

真实表现

本项目

工具注册成功但一调用就报错

harady 的 10 个 reference-image 消息名在 3.8.8 根本不存在

114 条消息白名单，全部经 3.8.8 包体二进制扫描验证；模型照旧教程调用时会收到「正确名是 X」而不是 not found

多步写操作中途失败留下半改场景

listar 虽有 scene:snapshot 却没编排成事务；且实测 Cocos 3.8.8 的 snapshot-abort / cancel-recording 根本不会回滚

scene.transaction：自带 undo 日志 —— 执行前捕获逆操作，失败时逆序撤销（真机验证：失败事务后节点数 3 → 3）

任意网页能驱动你的编辑器

DaxianLee 绑 127.0.0.1 + CORS * + 无鉴权

Bearer token + Host/Origin 校验 + 4MiB 限额；不提供任意 eval

工具

说明

cocos_message

直接调用一条已验证存在的 Cocos 编辑器消息（白名单外一律拒绝并给出正确名）。

cocos_knowledge

查询 Cocos Creator 3.8.x 的实操知识，避免反复试错。topic 取值：

cocos_prefab_query

直接读 .prefab 文件（不需要编辑器运行）。

cocos_prefab_edit

声明式批量修改 .prefab 文件。所有 op 全部成功才会落盘，任一失败磁盘零写入（事务语义）。

cocos_prefab_batch

从 JSON 文件读取 ops 后批量编辑。opsJsonPath 是 JSON 文件的绝对路径（单文件或 {"files":[...]} 多文件形态）。

cocos_prefab_ops

列出 cocos_prefab_edit / cocos_prefab_batch 支持的全部 prefab op、必填参数与可选参数。不确定某个操作叫什么名字时先查这里。动画相关 op 见 cocos_anim_ops。不需要参数。

cocos_anim_ops

列出 cocos_anim_batch 支持的全部 动画 op、必填参数与可选参数。prefab 相关 op 见 cocos_prefab_ops。不需要参数。

cocos_anim_query

读 .anim 文件（不需要编辑器运行）。selector 取值：tree（轨道树）/ node（某节点的轨道）/ find（按名字找）/ field（查属性）。

cocos_anim_batch

批量修改 .anim 文件的轨道与关键帧。op 支持 offset-curve（整体平移曲线）与 set-keyframe-value（改关键帧值）。

域

工具

asset

asset.copy asset.create asset.delete asset.dependencies asset.info asset.isImported asset.move asset.path asset.query asset.refresh asset.reimport asset.save asset.url asset.users asset.uuid

build

build.platforms build.start build.status

component

component.add component.call component.list component.remove component.set

editor

editor.console.clear editor.info editor.logs

node

node.active node.clipboard node.create node.delete node.duplicate node.move node.transform

preferences

preferences.get preferences.set

preview

preview.url

project

project.config

reference

reference.add reference.config reference.current reference.remove reference.set

scene

scene.bounds scene.classes scene.close scene.components scene.create scene.find scene.node scene.open scene.reload scene.save scene.script scene.snapshot scene.snapshot.abort scene.status scene.transaction scene.tree

view

view.align view.focus view.options

等级

工具

行为

read

全部只读工具

直接执行

write

改场景/资源

直接执行，可撤销

danger

node.delete component.remove asset.delete

必须同一次调用传 confirm: true；confirm 被写进 inputSchema 的 required，模型绕不过，执行期再校验一次

层

脚本

覆盖

最近一次实测

单测

hub/test/ + hub/src/offline/test/ + test/*.test.js（真机脚本不叫 .test.js，不会被 node --test 自动发现）

离线 prefab/anim 读写、事务 undo 日志、文档/清单一致性、逐个调用全部 Bridge op、场景频道健康闸门、原型链守卫、批量两阶段提交、护栏接线、退出码语义、真机前置守卫

236/236

端到端

test/e2e.js

MCP 握手 → 工具面 → 真实读取 → 真实写入闭环 → 事务失败真回滚 → 安全护栏 → Resources → 离线能力 → 路径护栏 → 多编辑器前缀隔离

60/60（编辑器频道中毒时退出 2 = 环境不可用，不是回归）

全工具冒烟

test/tool-smoke.js

每一个工具都真跑一遍 + 工具面静态自检

覆盖全部 70 个工具；退出码语义见下方表格 —— 引擎缺陷导致的跳过与残留都单独列出，不冒充通过

真机行为

test/real-behavior.js

把「代码看不出对错、必须真机才能定论」的条目逐条跑清楚：剪切→粘贴闭环、组件真被摘掉、越界写被拦、20 并发、事务回滚、未导入场景前置拦截、离线写盘事务

53/53

码

含义

CI 该怎么处理

0

全部通过

通过

1

有真失败（真回归）

必须红 —— 这是要查的

2

有跳过：本轮没跑完（引擎侧 scene 频道中毒/正忙）

黄色/待重试 —— 不是回归，重启编辑器重跑

3

有残留：文件留在用户工程里，需要人工清理

黄色 + 要有人看一眼（通常也是引擎缺陷的连带）

4

测试自身中断（崩溃）

脚本坏了 —— 看日志

缺陷

影响

修法

editor.logs 调了不存在的 console:query 消息

工具注册成功但一调用就报错

改用官方 Editor.Logger.query()（同步 API，字段 {process,type,message,stack,time}）

8 个已实现的 Bridge 操作没暴露成 MCP 工具

有能不用

补 scene.classes / scene.components / scene.snapshot / scene.snapshot.abort / scene.bounds / build.platforms / reference.current / reference.config / editor.console.clear

scene:query-classes 参数用错（{name} 而非 {extends}）

查组件类返回空数组

改为 {extends:'cc.Component', excludeSelf:true}

声称「scene.snapshot 可编排事务回滚」

回滚是假的

实测 snapshot-abort / cancel-recording 都不回滚 → 改为自带 undo 日志（hub/src/tools/transaction.js）

路径护栏无法放宽

改不了项目外的美术资源库

新增 COCOS_MCP_EXTRA_ROOTS 环境变量，错误信息里给出用法

COCOS_MCP_EDITOR_FILTER 只在扩展端写、hub 端没实现

复制出来的配置无效

hub 端实现过滤

scene:open-scene 失败时不 reject 消息

调用方干等到客户端超时

Bridge 侧自己兜超时（单次 90s，不重试），并把「资源可能还没导入完」写进错误信息

一次 open-scene 挂死会让整个 scene 频道从此中毒（query-node-tree 永远不返回，但 bridge/ping 正常）

后面所有场景操作全部挂住，错误信息只是一堆没信息量的「超时」

加频道健康闸门：每次场景操作前用 query-dirty 探活（不能用 query-is-ready —— 它中毒后仍 3ms 正常返回，探不出病灶），连续两个独立轮次失败才判死，判死后立刻失败并提示「请重启 Cocos Creator」，每 30 秒给一次自愈机会

scene.close 引擎其实关不掉（general edit mode 下返回 false）

报 closed:true 是假成功，模型以为场景已关

引擎拒绝时明确报错，并说明「切换场景直接用 scene.open，不需要先关」

删掉当前打开的场景资源

编辑器留下指向已删除资源的引用，之后打开任何场景都挂死

Bridge 守卫拦下，提示先 scene.close

打开一个还没导入完的场景

发出 open-scene → 失败 → 频道中毒

打开前先查本地库产物文件（library/<xx>/<uuid>.json）是否存在，不导入完直接拒绝，不碰引擎

删根节点 / 删不存在的组件 / 删不存在的资源返回"成功"

假成功比报错更危险

三处都改成明确拦截或明确报错

缺少必填参数时编辑器只回一句 parameter error

模型不知道是自己少传了东西

Bridge 层前置参数校验，回中文明确错误