chore: track Cocos Creator project for future migration

2026-09-08 21:54:30 +08:00
parent feb2ec5de1
commit 9f8990b579
23 changed files with 37475 additions and 5 deletions
@@ -0,0 +1,64 @@
+# Cocos MCP Pro Troubleshooting
+
+Version: 0.2.0
+
+## 先运行“一键检测”
+
+面板会分别检查Node、Bridge、WebSocket、Creator Scene和客户端配置。先处理第一个失败项，不要连续重装或盲目重试写操作。
+
+## 面板打不开或提示`methods`不存在
+
+确认正式ZIP的根目录直接包含`package.json`、`dist/main.js`、`dist/scene.js`和`dist/panels/default/index.js`，没有多嵌一层扩展目录。移除不完整或旧版扩展后重新导入正式ZIP，并重启Creator。不要把未构建源码目录当作商店扩展安装。
+
+Creator 3.8.8在Windows上若提示`unzip: No zipfiles found`后又报`ENOENT scandir`，先把ZIP复制到只含英文和数字的本地路径（例如`C:\CocosMCP\cocos-mcp.zip`）再导入。这个报错可能来自Creator内置解压器无法读取ZIP来源路径中的中文；项目目录本身仍可保留中文、空格和`&`。
+
+## 客户端提示`Connection closed`
+
+1. 保持Creator和当前工程打开，确认面板服务正在运行。
+2. 在面板里重新配置对应客户端。v0.2.0会迁移旧的`.cocos-mcp-launcher.cmd`或`.sh`配置。
+3. 完全退出并重启AI客户端，然后调用`cocos_ping`。
+4. 若仍失败，运行“一键检测”并查看客户端MCP日志。
+
+正确配置应直接执行Node，参数依次包含`bridge-cli.js`、`--project`和工程目录。不要手抄他人的绝对路径。
+
+## 提示`bridge cli missing`或路径乱码
+
+这通常是旧版启动器或扩展目录不完整。卸载旧扩展，重新导入完整v0.2.0目录，再执行一键配置。路径中包含中文、空格或`&`时，不需要额外加转义字符；让面板生成配置即可。
+
+## 提示`node not found`
+
+安装Node.js 18至24，再回到面板重新运行一键配置。v0.2.0会把实际Node可执行文件的绝对路径写入客户端配置，不依赖GUI应用的`PATH`。
+
+## 配置文件原有内容丢失了吗
+
+不会直接覆盖。插件会解析现有JSON/TOML，更新`cocos-creator`条目，写入临时文件并校验后原子替换。原文件存在时会保留同目录`.cocos-mcp.bak`备份；格式损坏时会停止并明确报错。
+
+## MCP连上了，但简单UI任务仍要求手动挂脚本
+
+先调用`cocos_get_capabilities`，确认版本为0.2.0。圆形、矩形、文本、图片和按钮应使用`cocos_create_ui_*`或`cocos_apply_ui_spec`，不应临时生成组件脚本让用户手动挂载。若客户端仍这样规划，把这句话补给它：
+
+```text
+使用Cocos MCP Pro任务级UI工具直接完成；失败时返回诊断并回滚，不生成临时脚本，不要求我手动操作Creator。
+```
+
+## UI任务失败后留下半成品
+
+停止继续写入，立即保存`diagnostics`并提交问题。`cocos_apply_ui_spec`设计为事务操作，任一步失败都应自动移除本次创建的节点。不要在残留状态上继续让AI“补救”。
+
+## 图片或字体资源写入失败
+
+`set_component_property`可接受资源UUID，也可直接接受`assets/...`路径。路径必须存在且资源类型与目标属性匹配；插件会在写入前解析并校验，不匹配时拒绝修改。
+
+## 网页报错怎么读
+
+使用`cocos_preview_debug_start`打开托管Chrome/Edge预览，不要把普通浏览器页面来回复制给AI。复现后调用`cocos_preview_debug_read`；可读取JavaScript异常、未处理Promise、控制台错误和失败网络请求。结束时调用`cocos_preview_debug_stop`。
+
+## Android或iOS构建是否一定不受影响
+
+不能只凭编辑器或网页错误下结论。`cocos_get_build_diagnostics`只整理Creator已有构建日志；仍需实际完成目标平台构建和设备测试。
+
+## 反馈问题
+
+邮箱：jimmymjing@gmail.com
+
+请附Creator版本、插件版本、系统、AI客户端、一键检测结果、复现步骤和脱敏诊断。不要发送项目密钥、API Key或完整商业项目。