daoqi/youle_cocos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
65f0998fbd9bb77218873dc85f53a7152cb71389
youle_cocos/CLAUDE.md
T
joywayerandClaude Opus 5 0ba37c7212 docs(mcp): CLAUDE.md 与 cocos-mcp 技能只保留 MCP 自身给不了的信息 
原文档写着"164 个工具"并复述了一份按前缀分的工具清单, 对应的是已删除的旧扩展,
照着写会调不到工具。

改为不再复述工具用法: cocos-mcp-server 连上后会自注入 5.5K 字符的完整说明
(CRITICAL RULES + intent→tool 速查表 + 批量操作), 16 个工具的 description 也
各带 action 枚举与示例, 仓库里再维护一份副本必然随扩展版本腐化。

文档只保留 MCP 给不了的部分——服务离线时它的自带说明也一并消失, 而那正是最需要
"去编辑器点 Start Server"和"不要转而手改序列化文件"的时刻:
- 前置条件、curl /health 探活、连不上时的排查顺序
- settings/mcp-server.json 的 autoStart:false, ECONNREFUSED 的常见成因
- 已知坑: cocos_asset.search 的 type 过滤失效; cocos_scene.hierarchy 的
  includeComponents 失效; 编辑器里的 scene-2d 是 Creator 内置模板而非工程资产
  (assets/ 下 0 个 .scene), 不必去仓库里找

技能里原本重复的"禁止手改 .scene/.prefab"规则改为引用 CLAUDE.md 单一来源, 依据
是仓库第二准则; 基线测试也表明未读该技能的 agent 仅凭 CLAUDE.md 即拒绝手改。

CLAUDE.md 里"动手前先读技能"改为条件式(正常操作不必读, 故障时才读), 此前该指令
与技能的排障定位冲突, 实测中不同 agent 对它的解读并不一致。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-19 08:01:23 +08:00

88 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 第一准则：服务器零改动
**任何前端开发都必须完全遵循前后端数据包的协议与数据结构，做到服务器零改动。** 这是本仓库不可逾越的最高准则，优先于一切其它考量：
- 协议信封、`route`/`rpc` 命名、字段名与类型、`roomtype` 配置数组、`deskinfo` 快照结构等，**必须与现有协议逐字节对齐**（依据 `docs/protocol/`），不得为前端方便而改变格式或新增/重命名字段。
- 遇到协议层有疑问时，**先读 `docs/protocol/` 对应章节核对，不要臆测**；宁可前端多做适配，也绝不要求服务器配合改动。
- 新的 Cocos 前端（`YouleNexus`）的目标，就是在不改服务器的前提下复刻该协议契约、实现联调兼容。
## 第二准则：数据源权威、唯一，下游不兜底
**每一类数据只能有一个权威且唯一的来源（single source of truth）；下游消费方不得猜测、修补、兜底。**
- **唯一来源**：同一份配置/数据（如服务器地址、渠道身份、协议常量）只在一个地方定义，其它地方一律引用，不得各处复制或并存第二份。
- **下游零兜底**：消费方拿到的数据缺失或非法时，**直接显式报错/抛出，把问题暴露到来源**，不得用默认值「猜一个」、不得静默 `?? 兜底值`、不得 try/catch 后塞个 fallback 蒙混。错误要早暴露、可定位，而不是被下游悄悄掩盖。
- **配置即契约**：来源（如 `profiles.ts` 的服务器地址）必须把该提供的字段显式提供齐全；缺了就是配置错误，应在来源处修正，而不是让下游补。
- 例外只有一种：来源本身明确定义了「可选 + 缺省语义」，且该缺省**写在来源处**（而非散落在各下游）。
> 这条与「服务器零改动」并列：前者保边界契约不变，后者保内部数据流可信、单源、可追溯。新增/修改任何带默认值、回退、容错分支的代码前，先问：这是不是在替上游兜底？若是，改为在来源处修正 + 在下游暴露。
## 仓库总览
这是友乐（Youle）棋牌游戏平台的前端工作区，核心是「**一套前端模板 + 多个子游戏**」的架构，并正在迁移到 Cocos Creator。三个顶层目录：
- **`projects/`** —— 旧版 HTML5 前端。`projects/Game_Surface_3` 是**前端模板（平台外壳）**，其余目录（`doudizhu` / `erqiwang` / `niuniu` / `majiang_jx` / `guanpai-jx` / `pdk_card_client-jinxian` / `sangelaok` / `zpy` / `gamehall3` …）都是**基于该模板扩展出来的子游戏**，平台层几乎不动，只改子游戏层 + 美术数据。
- **`docs/protocol/`** —— 前端模板框架与服务器收发包的**协议规范**（权威文档，8 篇）。改动任何网络层代码前**必须先读对应章节**，服务器不可改，前端必须严格对齐协议。
- **`cocoscreator_projects/YouleNexus/`** —— 新的 Cocos Creator 3.8+ 前端工程，目标是按 `docs/protocol` 复刻协议契约，做到服务器零改动即可联调。
## 前端模板 Game_Surface_3 与子游戏（`projects/`）
**四层结构（自底向上）：**
1. **引擎层** —— `js/gameabc.min.js`（gameabc 精灵引擎）+ Spine（`spine-canvas.js` / `SpineMgr.js`）+ Canvas 渲染；提供触屏/定时器/资源/WebSocket 底层回调。
2. **桥接层** —— `js/gamemain.js`：统一事件总线，把引擎回调分发到平台 UI、子游戏 `Game_Modify`、对战逻辑。
3. **平台层** —— `js/00_Surface/*`（12 个文件）：登录、大厅、房间、聊天、社交、网络、资源、排行、任务等通用能力。**子游戏间几乎不变**。
4. **子游戏层** —— `js/01_SubGame/*`（3 个文件）：只实现本游戏的对局逻辑与房间 UI。
**平台层关键文件（`js/00_Surface/`）：** `02_Const.js`（`ConstVal`/`AppList`/路由表）、`04_Data.js`（`GameData` 全局态）、`09_Net.js`（`Net._SendData()` 收发分发）、`12_Logic.js`（`Logic` 连接/重连/分发编排）、`07_Desk.js`（`Desk` 房间状态机）、`06_Player.js`（`C_Player`/`Player` 数据结构）、`11_GameUI.js`（平台 UI）、`00_minhttp.js`（WebSocket 底层封装）。
**子游戏层（`js/01_SubGame/`，开发子游戏 = 改这 3 个文件 + 美术数据）：**
- `00_SubGame_Config.js` —— `Game_Config`（房间数、气泡位置、分享、调试开关）
- `01_SubGame_modify.js` —— `Game_Modify` / `gameCombat`（对局实现 + 房间/胜负 UI）
- `02_SubGame_Input.js` —— 平台回调钩子（模板里是桩，子游戏覆写为真实逻辑）
- 另需补充：`gamemain.js`（扩展对局初始化）、专用算法模块（牌型/出牌等）、美术数据 `output/gameabc_data.min.js`。
**状态归属：** 平台层维护 `Desk`（房间/座位）、`C_Player`（自己）、`GameData`（连接/资产）；子游戏维护对局态（手牌、出牌历史、轮次、分数）于自身命名空间，并需可序列化为 `deskinfo` 以支持断线重连。
## 网络协议（`docs/protocol/`，新旧前端共同契约）
- **传输层：** 单条长连 **WebSocket，纯 JSON 文本**（无二进制/protobuf）。先 HTTP GET 配置服务拿 `urlserver`，再 `ws://<ip:port>` 连接；支持 `connect_agentserver`/`connect_roomserver` 切换服务器。
- **消息信封：**
- 客户端→服务器（单层）：`{ "app":"youle", "route":"agent|room|platform|<game_route>", "rpc":"<name>", "data":{…} }`
- 服务器→客户端（**双层包裹**）：外层 `{ "data": <inner> }`；inner 可能是字符串需 `JSON.parse`。**收包必做过滤**：`@toconcon`（前 9 字符，握手包，忽略）、`data.com === "@serverheartbeat"`（服务器心跳，~20s 一次，**不回复**）。
- **路由分发：** `route ∈ {agent, room, platform}` → 平台层处理（`Net.<rpc>` → `Desk.*` / `C_Player.*`）；`route` 为其它值 → 交子游戏 `Game_Modify._ReceiveData(msg)`，由子游戏 `switch(msg.rpc)` 派发对局包。平台请求通用身份字段：`agentid`/`gameid`/`playerid`（房间操作再加 `roomcode`）。
- **心跳/超时/重连：** 客户端 30s 收包超时（`ConstVal.Max.heartbeat = 30000`），超时报“网络慢”并重连；断线时 `Logic` 轮询候选服务器，重连后重发 `player_login`。
- **核心数据结构（详见 `04-数据结构.md`）：** `C_Player`（本地玩家）、`Player(seat)`（座位玩家）、`Desk`（房间/牌桌）、`player_login` 响应（账号资产 + 可选房间恢复段：`roomcode`/`isbattle`/`deskinfo`…）。
- **两个不可妥协的约束：** ① `roomtype` 房间配置数组结构必须与目标子游戏**逐字节一致**（服务器据此解析规则）；② `deskinfo` 对局快照须可序列化/反序列化以支持 `isbattle==1` 时 `Game_Modify.Reconnect(deskinfo)` 断线重连。
**协议文档索引：** `00-框架架构设计` · `01-传输层与架构` · `02-协议-agent路由` · `03-协议-room路由` · `04-数据结构` · `05-游戏内协议与桥接` · `06-子游戏开发模式与Cocos方案`。改协议相关代码前先读对应篇。
## 客户端侧适配约束：远程配置 / 原生数据接口 / 原生↔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）。改这部分前先核对上述源码位置，不要臆测接口名或数据格式。
## Cocos Creator 新前端：优先使用 cocos-creator-mcp
新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**（场景、节点、组件、prefab、资源、动画、预览/截图等），都必须走 `mcp__cocos-creator-mcp__cocos_*` 这组 MCP 工具驱动编辑器。
**绝不允许手改** `.scene` / `.prefab` / `.anim` / `.meta`——它们是 UUID 引用的序列化资源，任何文本编辑都会破坏引用结构，导致「资源导入失败」且只能人工恢复。**MCP 连不上时也不例外**：应提示用户去编辑器启动服务，而不是退而求其次去手改文件。
具体工具用法不写在这里——MCP server 连上后会自注入完整说明（工具清单、action 速查、批量操作），以其为准，**正常操作不需要先读任何仓库文档**。
`cocos-mcp` 技能（`.claude/skills/cocos-mcp/SKILL.md`）只记录 MCP 自己给不了的部分：前置条件、探活、排障、已知坑。**工具正常时不必读它；一旦 `cocos_*` 工具没出现、调用报连接失败、或行为与预期不符，就去读。**
Reference in New Issue View Git Blame Copy Permalink