# AGENTS.md

This file provides guidance to Codex (Codex.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` 是**前端模板（平台外壳）**，也是新前端 UI 迁移的**原工程（迁移源）**；其余目录都是**基于该模板扩展出来的子游戏**，平台层几乎不动，只改子游戏层 + 美术数据。分层结构与关键文件见 `projects/AGENTS.md`。
- **`docs/protocol/`** —— 前端模板框架与服务器收发包的**协议规范**（权威文档，8 篇）。改动任何网络层代码前**必须先读对应章节**，服务器不可改，前端必须严格对齐协议。
- **`cocoscreator_projects/YouleNexus/`** —— 新的 Cocos Creator 3.8+ 前端工程，目标是按 `docs/protocol` 复刻协议契约，做到服务器零改动即可联调。

### 服务器文档与二七王服务端

- **`server/development-guide/`**：服务器通用开发文档。查服务端框架、子游戏接入、通信协议和开发约束时，从 [README](server/development-guide/README.md) 开始，按任务阅读对应章节。
- **`server/games/erqiwang/`**：二七王当前改动后的服务器代码。核对实际行为时读取这里的实现，不以 `projects/erqiwang` 的旧前端推断当前服务器规则。
- 二七王规则设计位于 [design.md](server/games/erqiwang/docs/design/design.md)，玩法协议位于 [packet_protocol.md](server/games/erqiwang/docs/protocol/packet_protocol.md)。前端接入时同时核对设计、协议与服务端实现；发现差异应明确记录，不把设计要求冒充已实现行为。
- `roomtype` 由目标子游戏定义，可能是数组或字符串；平台通用流程不可擅自转换类型。二七王实际解析以 `class.config.js` 为入口，局数与扣卡检查 `class.export.js`；位索引只在协议文档中维护，不在本文件重复定义。
- 查阅服务器源码用于前端适配，不代表授权修改服务器代码；前端开发继续遵守“服务器零改动”。

### 原工程 `Game_Surface_3` → `YouleNexus` 的 UI 迁移

`YouleNexus` 的 UI 资源（`assets/framework/ui/prefabs/`）从**原工程 `projects/Game_Surface_3`** 逐层复刻。数据契约与流程规范：

- 数据模型（权威）：`docs/superpowers/specs/原工程数据模型.md`；迁移流程：`docs/superpowers/specs/UI-手工迁移规范.md`（9 步 funplay MCP + 8 项验证清单）。
- 已完成的参照真相源：`assets/framework/ui/prefabs/Login_Layer.prefab`（Layer 2）。

> ⚠️ **索引与类型（易踩坑，实测修正）**：源数据索引**直接按 ID**——`gameabc_Object.json` 的 `ObjectList[ObjectID]`、`gameabc_Image.json` 的 `ImageFileList[ImageFileID]`（**不是** `ID - 1`，旧文档的 off-by-one 是错的）；组件类型看 `ObjectType`（`2`=Sprite、`4`=Text），**不是** XML 的 `SpiritType`（那是另一套枚举）。

## 网络协议（`docs/protocol/`，新旧前端共同契约）

`docs/protocol/` 是权威文档，改任何网络层代码前先读对应章节，**不要凭本文件的转述臆测**。

**两个不可妥协的约束：** ① `roomtype` 房间配置编码的类型与结构必须与目标子游戏**逐字节一致**（服务器据此解析规则）；② `deskinfo` 对局快照须可序列化/反序列化以支持 `isbattle==1` 时 `Game_Modify.Reconnect(deskinfo)` 断线重连。

## 客户端侧适配约束：远程配置 / 原生数据接口 / 原生↔H5 桥接

继「服务器零改动」之后的**第二类不可妥协约束**：除 WebSocket 协议外，前端还通过「远程配置文件」（`gameserver` → `urlserver`）与「原生接口」（`window.settings` 同步取值、WVJB 异步桥）获取大量数据。新 Cocos 前端必须与原项目**逐字一致**地复刻这些读取/互调/注册方式（接口名、数据格式、回调约定、URL 构造），让原生侧与配置服务**零改动**即可对接。

具体机制、handler 清单与源码位置见 `native-bridge-contract` 技能（`.Codex/skills/native-bridge-contract/SKILL.md`）——改这部分前先读它核对，不要臆测接口名或数据格式。

## Cocos Creator 新前端：优先使用 funplay-cocos-mcp

新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**（场景、节点、组件、prefab、资源、动画、预览/截图等），都必须走 `mcp__funplay_cocos__*` 这组 MCP 工具驱动编辑器。

**绝不允许手改** `.scene` / `.prefab` / `.anim` / `.meta`——它们是 UUID 引用的序列化资源，任何文本编辑都会破坏引用结构，导致「资源导入失败」且只能人工恢复。**MCP 连不上时也不例外**：应提示用户去编辑器启动服务，而不是退而求其次去手改文件。

具体工具用法不写在这里——MCP server 连上后会自注入完整说明（工具清单、action 速查、批量操作），以其为准，**正常操作不需要先读任何仓库文档**。

`cocos-mcp` 技能（`.Codex/skills/cocos-mcp/SKILL.md`）只记录 MCP 自己给不了的部分：前置条件、探活、排障、已知坑。**工具正常时不必读它；一旦 `cocos_*` 工具没出现、调用报连接失败、或行为与预期不符，就去读。**