界面迁移更新
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: cocos-mcp
|
||||
description: Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 mcp__funplay_cocos__* 工具没出现、调用报连接失败、curl 127.0.0.1:8765/health 不通时。
|
||||
---
|
||||
|
||||
# funplay-cocos-mcp 接入与排障
|
||||
|
||||
工程 `cocoscreator_projects/YouleNexus`。编辑器操作走 `mcp__funplay_cocos__*` 工具（**105 个独立工具**，不是聚合派发）。
|
||||
|
||||
「禁止手改 `.scene`/`.prefab`/`.anim`/`.meta`」这条规则的唯一来源是 AGENTS.md，本文件不复述——按仓库第二准则，同一条规则不在两处定义。
|
||||
|
||||
## 工具怎么用：不在本文件
|
||||
|
||||
MCP server 连上后会自注入完整说明（每个工具 description 带用法/枚举/示例）。**照它的说明用，不要在本文件重复维护一份工具清单**——扩展换版本时那份副本必然过期误导。需要查工具清单时调 `get_tool_catalog`。
|
||||
|
||||
当前扩展 `funplay-cocos-mcp` v0.5.1（`extensions/funplay-cocos-mcp/`），工具名形如 `mcp__funplay_cocos__<verb>_<noun>`（如 `create_node` / `inspect_component` / `run_project_preview` / `capture_preview_screenshot`）。**不是** `action:` 参数派发模式——没有 `cocos_scene` / `cocos_node` 这种聚合入口，每个操作就是一把独立工具。
|
||||
|
||||
## 前置条件（缺一不可）
|
||||
|
||||
1. Cocos Creator 3.8.8 已打开 `YouleNexus` 工程；
|
||||
2. 扩展 **Funplay Cocos MCP** 已启用（`extensions/funplay-cocos-mcp/funplay-cocos-mcp.config.json` 里 `autostart: true` 默认会自动起 sidecar，监听 `http://127.0.0.1:8765/mcp`）；
|
||||
3. Codex 侧**不需要** `.mcp.json` —— `funplay_cocos` 配置在用户级 `~/.Codex.json`，项目级刻意不维护 MCP 配置（schema 校验也不允许空对象，见 memory `cocos-creator-mcp-setup`）。
|
||||
|
||||
## 探活
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8765/health
|
||||
# 期望：{"ok":true,"name":"Funplay Cocos MCP - YouleNexus","version":"0.5.1","projectName":"YouleNexus",...}
|
||||
```
|
||||
|
||||
或在会话内直接调 `mcp__funplay_cocos__get_project_info`，期望 `{ok:true, ...}` 包含 `projectName: YouleNexus`、`cocosVersion: 3.8.8`。
|
||||
|
||||
## 连不上时
|
||||
|
||||
**提示用户去编辑器里启用扩展 / 等待 autostart 起服务**，不要盲目重试，更不要绕开 MCP 去手改序列化文件。服务只在编辑器进程内，外部无法代为启动。
|
||||
|
||||
按此顺序排查：编辑器是否开着 → 扩展管理器里 `Funplay Cocos MCP` 是否启用 → `~/.Codex.json` 里 `mcpServers.funplay_cocos` 条目是否还在（type=http、url=http://127.0.0.1:8765/mcp）→ `/health` 是否通 → 工具列表里是否出现 `mcp__funplay_cocos__*`（用 `get_tool_catalog` 列出来核对）。`~/.Codex.json` 改动后**需重启 Codex 会话**才生效。
|
||||
|
||||
## 已知坑
|
||||
|
||||
funplay 扩展踩过的坑（每条都有对应 memory 详解，结论先列这里）：
|
||||
|
||||
- **SpriteFrame UUID**：设组件 `spriteFrame` 属性时 value 必须用 **SpriteFrame 真 UUID**（含 `@sub-asset` 后缀），不是 ImageAsset 路径，也不是裸 UUID——否则 Sprite 不会显示（见 memory `cocos-mcp-spriteframe-uuid`）。
|
||||
- **挂脚本路径判断**：`framework/` 路径下挂脚本能正常识别；老版本曾误判 `framework/` 为非脚本路径，已修正（见 memory `cocos-mcp-mount-script-path`）。
|
||||
- **mount_script 持久化限制**：MCP 的 mount 系列工具不写 prefab JSON 的 `__type__` / `__scriptAsset`，需要用户在编辑器里手动挂一次；不要绕过去 Edit prefab JSON（UUID 引用会被破坏，见 memory `prefab-persist-mount-script`）。
|
||||
- **library 缓存**：不要 `rm -rf YouleNexus/library`；用 Cocos 编辑器的 reload 重建（见 memory `cocos-mcp-library-cache`）。
|
||||
- **工具前缀迁移**：仓库里若还有 `mcp__cocos-creator-mcp__*` 写法（旧 16 聚合工具版），需要改成 `mcp__funplay_cocos__*` 对应动作；AGENTS.md 的允许规则已迁好。
|
||||
|
||||
## 安装方式与历史沿革
|
||||
|
||||
项目记忆 `cocos-creator-mcp-setup` —— 历次换装（164 工具 stdio 桥 → 16 聚合 HTTP :3000 → 105 独立 HTTP :8765）与配置位置演进全在那里。
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
name: native-bridge-contract
|
||||
description: Use when 要实现/修改 Cocos 前端与原生侧、配置服务的对接——远程配置文件读取（gameserver / urlserver）、window.settings 同步取值、WebViewJavascriptBridge (WVJB) handler 注册与互调（分享/视频/语音/电话/通讯录/电量/网络/摇一摇），或需要核对这些接口名、数据格式、回调约定、URL 构造。
|
||||
---
|
||||
|
||||
# 客户端侧适配约束：远程配置 / 原生数据接口 / 原生↔H5 桥接（须与原项目逐字一致）
|
||||
|
||||
继「服务器零改动」之后的**第二类不可妥协约束**：除 WebSocket 协议外，前端还通过「远程配置文件」与「原生接口」获取大量数据。新 Cocos 前端必须与原项目**逐字一致**地复刻这些读取/互调/注册方式（接口名、数据格式、回调约定、URL 构造），让原生侧与配置服务**零改动**即可对接。三类机制：
|
||||
|
||||
1. **远程配置文件读取**：入口 `Game_Config.Debugger.gameserver`（`projects/Game_Surface_3/js/01_SubGame/00_SubGame_Config.js:11`，远程 `.txt` URL + `ifast_random()` 防缓存 + `serverType` 切正式/本地）。读取链：`Logic.setGameServer()`（解析 URL 参数 `gameconfig` 或 `Func.getothername("gameserver")` 覆盖，`12_Logic.js:1259-1281`）→ `get_config(gameserver)`（**引擎层函数**，GET 远程 txt，`12_Logic.js:521`）→ `ServerUrl_Succ(_msg)` 回调（`12_Logic.js:533`）→ `GameData.Server = _msg.data.urlserver`（`12_Logic.js:549`）。**URL 构造、请求方式、回包字段解析须一致。**
|
||||
|
||||
2. **原生同步数据接口（注入对象）**：`Func.getothername(name)` → `window.settings.getothername(name)`（`js/00_Surface/05_Func.js:2467-2471`）。`window.settings` 是**原生注入的全局对象**，用于同步取配置（如渠道/包信息/gameserver 覆盖）。
|
||||
|
||||
3. **原生↔H5 异步桥 = WebViewJavascriptBridge (WVJB)**（`05_Func.js:2627` 起）：
|
||||
- 初始化 `setupWebViewJavascriptBridge(callback)`（经 `window.WVJBCallbacks` / `WebViewJavascriptBridgeReady` 事件 / `wvjbscheme://__BRIDGE_LOADED__` iframe）。
|
||||
- **H5 注册供原生调用**：`bridge.registerHandler("<name>", (data, responseCallback) => {…})`。已注册 handler（名称/数据结构须一致）：`getVideoinfo`、`sharelogin`、`sharesuccess`、`gameui_play_voice`、`gameui_stop_voice`、`getphoneinfo`、`getAddressBook`、`phonestate`、`appservice`、`getaudiourl`、`getBattery`、`getwifiLevel`、`getnetwork`、`shakeEnd` 等（`05_Func.js:2651+`）。
|
||||
- **H5 调用原生**：`bridge.callHandler("<name>", data, responseCallback)`（WVJB 约定）。
|
||||
- 覆盖能力：分享、视频、语音录制/播放、电话状态、通讯录、电量/wifi/网络、摇一摇等。
|
||||
|
||||
> **Cocos 适配注意**：原项目是 H5（WebView + WVJB + `window.settings` + 引擎 `get_config`）。新 Cocos 前端无论走 WebView 还是原生（jsb），都必须对接**同名 handler、同样的数据结构与回调约定**，并保持远程配置读取流程一致，使**原生侧与配置服务无需改动**即可互通。这套桥接的落地属 sdk/平台层范畴（后续 Plan）。改这部分前先核对上述源码位置，不要臆测接口名或数据格式。
|
||||
Reference in New Issue
Block a user