chore(spec): 综合清理 + legacy-layer 迁移 spec/plan/data

主要改动: - 切到 funplay-cocos-mcp v0.5.1 (用户级配置, 项目级 .mcp.json 删除) - 仓库文档/CLAUDE.md/.gitignore 等清理过时 cocos-mcp-server 引用 - memory 文件同步: cocos-mcp-setup/path/blocker/spriteframe-uuid/prefab-persist 等加 funplay 实测警告 - memory 新建 funplay-cocos-mcp-pending-verification.md (后已被实测覆盖) - spec/plan/data: - docs/superpowers/specs/2026-09-02-legacy-layer-migration-design.md - docs/superpowers/plans/2026-09-02-legacy-layer-migration.md - docs/superpowers/data/layer-spirit-summary.json - YouleNexus: profiles.ts / defaults.ts / PlayerInfoView.prefab / scene 改动 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-02 07:36:54 +08:00
parent fea85c6644
commit 02dc5d51ca
100 changed files with 3480 additions and 6961 deletions
@@ -1465,7 +1465,7 @@ Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
 1. `client.setIdentity(<真实身份>)`；监听 `open`/`login`/`message`/`slow`/`reconnecting`。
 2. `client.start()`，连真实服务器。
 3. 断言/观察：收到 `@toconcon` 不报错；发出 `player_login`；收到 `player_login` 响应且 `parseLoginResponse(...).ok === true`；console 打印 playerid/资产。
-4. 用 cocos-creator-mcp 的 `debug_get_console_logs` / `debug_screenshot` 留存联调证据。
+4. 用 funplay-cocos-mcp 的 `search_project_logs` / `capture_preview_screenshot` 留存联调证据。

 验收标准：真实服务器返回的 `player_login` 被正确解析、`isSendLoginState` 门控正确放行、心跳不被误当业务包、断网后能重连重登。

@@ -252,7 +252,7 @@ Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"

 > **非 TDD 的验证任务，但必须排在工具开发之前。** spec §6 的三条待实测项是整个构建期合成方案的承重点；若 Auto Atlas 不在构建期打包，Task 3–6 的设计需推倒重来。先验证，再建在上面。
 >
-> **前置条件**：需要 Cocos Creator 3.8.8 打开 `YouleNexus` 且 cocos-creator-mcp 服务可用。所有编辑器操作**必须**走 `mcp__cocos-creator-mcp__cocos_*` 工具，**绝不允许手改** `.meta`/`.pac`（CLAUDE.md）。MCP 连不上时提示用户去编辑器启动服务，不得退而求其次手改文件。
+> **前置条件**：需要 Cocos Creator 3.8.8 打开 `YouleNexus` 且 funplay-cocos-mcp 服务可用（`curl http://127.0.0.1:8765/health`）。所有编辑器操作**必须**走 `mcp__funplay_cocos__*` 工具，**绝不允许手改** `.meta`/`.pac`（CLAUDE.md）。MCP 连不上时提示用户去编辑器启用扩展，不得退而求其次手改文件。

 **Files:**
 - Create: `cocoscreator_projects/YouleNexus/assets/framework/ui/atlas-hall/probe_a.png`（验证素材，程序生成）
@@ -290,7 +290,7 @@ Expected: 打印 `生成完成`，`atlas-hall/` 下出现两个 64×64 PNG。
 用 MCP 刷新资源，然后确认两张图各自生成了 `.meta`：

 ```
-mcp__cocos-creator-mcp__cocos_project  →  action: refresh_assets
+mcp__funplay_cocos__refresh_assets
 ```

 Run: `ls YouleNexus/assets/framework/ui/atlas-hall/`
@@ -303,8 +303,8 @@ Expected: 出现 `probe_a.png.meta` 与 `probe_b.png.meta`。
 用 MCP 在 `atlas-hall/` 下创建自动图集资源（`.pac`），然后构建一次 web-mobile：

 ```
-mcp__cocos-creator-mcp__cocos_asset    →  创建 atlas-hall/atlas-hall.pac（自动图集）
-mcp__cocos-creator-mcp__cocos_builder  →  构建 platform=web-mobile
+mcp__funplay_cocos__write_file       →  创建 atlas-hall/atlas-hall.pac（自动图集）
+mcp__funplay_cocos__run_project_preview  →  构建 platform=web-mobile
 ```

 Expected（判定标准）：构建产物中 `probe_a` 与 `probe_b` **被合并进同一张图集贴图**，而非各自独立的 64×64 PNG。
@@ -1664,9 +1664,9 @@ Expected: 框架测试全部通过（原 84 个 + 本任务新增 6 个 = 90 个
 用 MCP 刷新并等待编译：

 ```
-mcp__cocos-creator-mcp__cocos_project  →  action: refresh_assets
-mcp__cocos-creator-mcp__cocos_debug    →  action: wait_compile
-mcp__cocos-creator-mcp__cocos_debug    →  action: get_console_logs, level: error
+mcp__funplay_cocos__refresh_assets
+mcp__funplay_cocos__run_script_diagnostics  →  等待编译
+mcp__funplay_cocos__search_project_logs     →  query=error, regex=true
 ```

 Expected: 编译完成且无 error 级日志；`ui/theme/` 下四个 `.ts` 各生成 `.meta`。
@@ -6,7 +6,7 @@

 **Architecture:** 分两段。**Node 侧**是纯函数转换器：读 `gameabc_*.json` → 坐标换算 / 锚点推断 / 分组 / bucket 归属 / 帧切分 → 产出 55 份中间描述 JSON + 散图。**编辑器侧**读中间描述建节点存 prefab；本计划只用 MCP 跑通一个界面验证链路，不写编辑器扩展。转换器绝不直接生成 `.prefab`/`.meta`（红线）。

-**Tech Stack:** Node.js 20.13.1（ESM `.mjs`）、`node:test` + `node:assert`、`pngjs`（PNG 编解码，见 Global Constraints 的例外说明）；编辑器侧走 `mcp__cocos-creator-mcp__cocos_*`。
+**Tech Stack:** Node.js 20.13.1（ESM `.mjs`）、`node:test` + `node:assert`、`pngjs`（PNG 编解码，见 Global Constraints 的例外说明）；编辑器侧走 `mcp__funplay_cocos__*`。

 **Spec:** `docs/superpowers/specs/2026-08-28-legacy-ui-migration-design.md`

@@ -1456,7 +1456,7 @@ Expected: 中间描述 56 个、散图 1306 张、ObjectID 索引 991 条。

 - [ ] **Step 5: 让编辑器导入散图并确认无错**

-用 MCP 刷新资源（工具名用 `ToolSearch` 自行发现，当前扩展为 `cocos-mcp-server` 的 16 个聚合工具；刷新资源大概率是 `cocos_asset` 的某个 action，可用 `cocos_knowledge {topic:"tool_guide", query:"asset.refresh"}` 查用法）。
+用 MCP 刷新资源（直接调 `mcp__funplay_cocos__refresh_assets`；工具列表可查 `get_tool_catalog`，按返回值核对）。

 Expected: 1306 张图被导入并各自生成 `.meta`；无 error 级日志。

@@ -1484,7 +1484,7 @@ Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"

 > **非 TDD 的验证任务。** 目的是证明「中间描述 → Cocos prefab」这条链路成立，并量出落地一个界面的实际耗时，据此判断是否值得写编辑器扩展批量跑完其余 54 个。
 >
-> **前置条件**：Cocos Creator 打开 `YouleNexus` 且 cocos-mcp-server 服务可用。所有编辑器操作**必须**走 `mcp__cocos-creator-mcp__cocos_*`；**绝不允许手写** `.prefab`/`.meta`。MCP 不可用时提示用户启动服务，不得退而求其次手改文件。
+> **前置条件**：Cocos Creator 打开 `YouleNexus` 且 funplay-cocos-mcp 服务可用（`curl http://127.0.0.1:8765/health`）。所有编辑器操作**必须**走 `mcp__funplay_cocos__*`；**绝不允许手写** `.prefab`/`.meta`。MCP 不可用时提示用户去编辑器启用扩展，不得退而求其次手改文件。

 **Files:**
 - Create: `cocoscreator_projects/YouleNexus/assets/framework/ui/prefabs/Login_Layer.prefab`（由编辑器生成）
@@ -0,0 +1,142 @@
+# 平台逻辑移植（子系统 C）开发计划 —— 从当前进度到「逻辑流程一致」验收
+
+> **For agentic workers:** 执行时使用 `superpowers:subagent-driven-development`（推荐）或 `superpowers:executing-plans`，任务用 `- [ ]` checkbox 跟踪。
+> 顶层路线图：本计划定义阶段边界、依赖、验收；阶段 1 直接续用 `2026-06-28-platform-store.md`，阶段 4/5 复用 `2026-08-27-ui-asset-and-skin.md`、`2026-08-28-legacy-ui-migration.md`，阶段 2/3 为新增（执行时各自展开为 TDD 任务）。
+
+**Goal:** 把子系统 C 规范（`docs/superpowers/specs/2026-08-30-legacy-platform-logic-migration.md`）的 §3 落点全部落地，使 §8 的 10 条「逻辑流程一致性检查点」全部通过。
+
+**策略假设（可纠正点）**：**端到端逻辑主线优先，UI 大面积落地收尾**——先打通「启动 → 建连 → 登录 → 进房/大厅 → 对局分发」这条纯逻辑主线（Store/session/protocol/sdk），UI 用最小占位（已有 `Login_Layer.prefab`）；最后再批量落地 55 界面。理由：C 规范的目标是「逻辑流程一致」而非「像素一致」，逻辑主线是协议契约与业务正确性的承重墙，UI 是响应式 Store 的下游视图、可后置。
+
+**基线（已完成，勿重复）**：`core`（含 `reactive.ts`）、`net`（transport/net-client/envelope-codec/heartbeat/reconnect）、`protocol`（login + 4 rpc）、`config`（完整）、`platform`（player-store + types + readonly）、`ui/theme`。真机联调 `player_login` 往返已通过。
+
+---
+
+## 阶段总览（依赖图）
+
+```
+阶段1 三态机+session ──┐
+                      ├─► 阶段2 协议+收包路由 ──► 阶段3 sdk+重连 ──► 阶段5 真机联调
+阶段4 UI落地(并行) ────┘          (可与4并行)       (依赖2)
+阶段5 原生桥(并行) ───────────────────────────────────────────────┘
+```
+
+| 阶段 | 内容 | 依赖 | 产出 | 复用现有 plan |
+|---|---|---|---|---|
+| **1** | platform 三态机 + session | 无（reactive/types/player 已就绪） | AppStore/RoomStore/PlatformSession | ✅ `2026-06-28-platform-store.md` Task 4/5/6 |
+| **2** | 启动接线 + protocol 补全 + 收包路由 + 房间事件 | 阶段 1 | rpc 常量、Router、房间 handler、PlayerStore 补全 | 新写 |
+| **3** | sdk（IGameModule/GameContext）+ 断线重连 | 阶段 2 | GameContext、IGameModule、deskinfo 透传 | 新写（= 原「Plan 5」主体） |
+| **4** | UI 界面落地（55 界面 + FrameSet） | 阶段 1（响应式 Store） | FrameSet 组件、界面控制器、批量 prefab | ✅ `2026-08-28-legacy-ui-migration.md` + 新写控制器 |
+| **5** | 原生桥（WVJB）+ 真机端到端联调 | 阶段 3/4 | 完整 WVJB 桥、端到端验收 | 新写（= 原「Plan 5」收尾） |
+
+---
+
+## 阶段 1：platform 三态机 + session（续现有 plan）
+
+**目标**：`AppStore`(=GameData) / `RoomStore`(=Desk) / `PlatformSession`(=12_Logic 登录接入)，使 login 事件 → 三 Store 正确填充 + 相位流转。
+
+**直接续用** `docs/superpowers/plans/2026-06-28-platform-store.md` 的 **Task 4（AppStore）、Task 5（RoomStore）、Task 6（PlatformSession）**——该 plan 已含完整代码与测试，此处不重写，按原 TDD 流程执行。
+
+- [ ] Task 4：`platform/stores/app-store.ts`（AppStore：setIdentity/setServers/setPhase/applyLogin）
+- [ ] Task 5：`platform/stores/room-store.ts`（RoomStore：applyRecovery/clear，`players` 座位数组 + `deskinfo` opaque 透传）
+- [ ] Task 6：`platform/session.ts`（PlatformSession 订阅 NetClient 事件总线 → 填充三 Store，相位流转）
+
+**验收**：`npm run test:framework` 全绿（含 app-store 3 + room-store 3 + session 4 用例）；`typecheck:framework` exit 0；login 含 `roomcode` 时 `RoomStore.inRoom=true` + `deskinfo` 原样透传。
+
+---
+
+## 阶段 2：启动接线 + protocol 补全 + 收包路由 + 房间事件
+
+**目标**：把「收包 → 路由分界 → Store 更新」这条主线打通，覆盖 C 规范 §4.1（路由分界）与 §6.2（登录分支）。
+
+### Task 2.1 — protocol 补全 rpc 常量（对应 C §3 `02_Const` 落点）
+
+- [ ] 从旧 `02_Const.js` 的 `RpcList`（:13–109，~100 个）提取平台层 rpc，落 `protocol/routes.ts`（扩展 `Rpc`，保持函数名==rpc 字符串的同构映射）。
+- [ ] 至少覆盖房间类 rpc（`create_room`/`self_join_room`/`self_exit_room`/`other_exit_room`/`self_makewar`/`player_prepare`/`self_apply_free_room`/`change_seat`/`update_bean`/`connect_roomserver`…）与玩家类（`update_bean`/`set_sign`/`set_tel`…）。
+- **验收**：`Rpc` 常量与 `docs/protocol/` 的 rpc 字符串逐字节一致；typecheck 通过。
+
+### Task 2.2 — 收包路由分界（C §4.1 的红线）
+
+- [ ] 在 `net-client.ts`（或新建 `protocol/router.ts`）实现 Router：`route ∈ {platform,agent,room}` → 平台 handler；`route = <game route>` → sdk 钩子（阶段 3 接上，本阶段先留 `onGameRoute` 空钩子 + 未注册时显式报错，不静默吞包）。
+- [ ] `connect_roomserver`/`connect_agentserver` 换服逻辑已存在（`net-client.ts:129-133`），补「换服后重发登录」的触发。
+- **验收**：单测：platform 包 → 平台 handler 被调；对局 route 未注册 → 显式报错（第二准则：不兜底）。
+
+### Task 2.3 — 房间事件 handler → RoomStore/PlayerStore 更新（C §6.4）
+
+- [ ] 新建 `protocol/room.ts`（或 `platform/room-handlers.ts`）：`self_join_room`/`other_join_room`/`self_exit_room`/`other_exit_room`/`self_makewar`/`player_prepare`/`self/other_apply/agree/refuse_free_room`/`other_offline/online`/`change_seat` → 更新 `RoomStore`（座位、`stage`、`state`、`AgreeList`）。
+- [ ] `PlayerStore` 补全 `update_bean`/`update_roomcard`/`setCharm`/`setSign`/`setTel`（对应 C §3.1 消除双镜像：bean/roomcard 只写 `PlayerStore`，`RoomStore.players[seat]` 是同一响应式来源的投影）。
+- **验收**：单测：每个房间 rpc 收包 → RoomStore/PlayerStore 字段正确变化；解散投票 `AgreeList` 累积正确。
+
+### Task 2.4 — 启动接线（C §6.1 启动流程）
+
+- [ ] 把 `config/bootstrap` 的 `resolveBootstrap` 结果接 `AppStore.setIdentity/setServers`；`new PlatformSession(net.bus)` + `net.start()`。
+- [ ] 首屏门控四条件（资源/WS onopen/配置/加载计时器）合成一个「就绪信号」→ 登录页（UI 阶段 4 接，本阶段先暴露 `AppStore.phase` 状态）。
+- **验收**：启动编排单测：bootstrap → AppStore 身份/服务器就绪 → net.start 建连。
+
+---
+
+## 阶段 3：sdk（IGameModule/GameContext）+ 断线重连
+
+**目标**：建立子游戏对接边界，收包路由对局分支接上 sdk，`deskinfo` 透传 + 断线重连恢复（C §4.1/§5 边界判据、§6.3）。
+
+### Task 3.1 — `sdk/GameContext` facade（C §3 `08_Utl_Output` 落点）
+
+- [ ] 只读暴露：`room`/`player`（只读 Store）、`net.send(route,rpc,data)`、`seat.toView(mySeat,target)`（替代旧 `ChangeToStatus`）、`ui` 占位（toast/dialog）。
+- [ ] 旧 `08_Utl_Output.js` 的只读 getter（`getMyInfo`/`getRoomcode`/`getPlayerList`/`getMySeat`…）→ facade 方法或直接只读 Store。
+- **验收**：单测：facade 只读、不可逆改 Store；`seat.toView` 与旧 `ChangeToStatus` 同结果。
+
+### Task 3.2 — `IGameModule` 接口 + 注册（框架 spec §4）
+
+- [ ] 定义 `IGameModule`（`route`/`onEnter`/`onExit`/`onReceive`/`onReconnect`/`serialize`/平台钩子默认空实现）。
+- [ ] 注册机制：子游戏注册自己，Router 据 `route` 分发对局包 → `activeGame.onReceive`。
+- **验收**：单测：注册 mock 子游戏 → 对局 route 包 → `onReceive` 被调；未注册 → 显式报错。
+
+### Task 3.3 — `deskinfo` 透传 + 断线重连（C §6.3）
+
+- [ ] login 回包含 `deskinfo`（`isbattle==1`）→ `RoomStore` 只透传不解析 → `activeGame.onReconnect(deskinfo)`。
+- [ ] 断线重连完整链路：`net/reconnect` 重连 → 重发登录 → `deskinfo` 恢复对局。
+- **验收**：集成测试：login(deskinfo) → `onReconnect` 收到原样快照；断线 → 重连 → 重发登录。
+
+---
+
+## 阶段 4（并行）：UI 界面落地
+
+**目标**：从 55 界面中间描述批量落地 Cocos 界面，响应式订阅 Store，界面切换走 `node.active` + `AppStore.currentScene`（C §6.5）。
+
+- [ ] **Task 4.1 FrameSet 组件**（B §3.4）：多帧图切帧的运行时载体（`setFrame(n)`，1 基帧号）。
+- [ ] **Task 4.2 界面控制器**：登录/大厅/房间 + 各弹窗，`subscribe` 三 Store 自动刷新；`Login_Layer.prefab` 接入真实登录数据。
+- [ ] **Task 4.3 批量落地**：复用 `2026-08-28-legacy-ui-migration.md` 的 convert 管线，把 55 个 layer JSON → prefab（当前仅 Login_Layer 已落）。
+- [ ] **Task 4.4 界面切换**：`AppStore.currentScene` 状态替代 `get_self(149,37)` 哨兵。
+
+**验收**：登录→大厅→房间 界面切换正确；帧动画走 FrameSet；UI 由 Store 响应式驱动（无手工刷新）。
+
+---
+
+## 阶段 5（并行收尾）：原生桥 + 真机端到端联调
+
+- [ ] **Task 5.1 WVJB 完整异步桥**（原「Plan 5」）：`window.settings` 同步取值 + `setupWebViewJavascriptBridge` 异步注册，接口名/数据格式/URL 构造与旧逐字一致（`native-bridge-contract` 技能）。
+- [ ] **Task 5.2 真机端到端**：登录 → 大厅 → 进房 → 对局（mock/seed 子游戏）→ 结算，联调本地服。
+- [ ] **Task 5.3 断线重连真机验证**：`isbattle==1` 时 `deskinfo` 恢复对局。
+
+---
+
+## 验收标准（映射 C 规范 §8 检查点）
+
+- [ ] 信封 `{app,route,rpc,data}` 逐字节对齐（✅ 已有，回归不破坏）
+- [ ] 收包分界：`platform/agent/room` → 平台 handler；对局 route → `onReceive`；未注册显式报错（阶段 2/3）
+- [ ] 发包 HTTP 兜底（`netType==1`）+ `player_login` 的 `putMsg="playerLogin"`（阶段 2）
+- [ ] 启动门控四条件合成就绪信号（阶段 2）
+- [ ] 登录分支：`roomcode`/`deskinfo` 有无 → 大厅 or 房间 or `onReconnect`（阶段 1/3）
+- [ ] 断线重连 + `deskinfo` 恢复（阶段 3/5）
+- [ ] 三态机单一来源，无双镜像（阶段 1/2）
+- [ ] 对局态 `deskinfo` 平台层不解析、原样透传（阶段 3）
+- [ ] 界面切换 `node.active` + `currentScene`，不搬 `set_level`（阶段 4）
+- [ ] 原生接口逐字一致（阶段 5）
+
+---
+
+## 风险与依赖
+
+1. **UI 落地量大**（55 界面、旧 9862 行）——通过「逻辑主线先行 + 响应式 Store 后置 UI」隔离，UI 延迟不阻塞阶段 2/3 的协议正确性验证。
+2. **对局 route 的 sdk 分界是红线**——阶段 2.2 先留「未注册显式报错」，避免静默吞包（第二准则）。
+3. **`set_windows`/`players` 完整建模**等次要项——按 C §9.3 待验证清单在对应阶段落地时回填，不阻塞主线。
+4. **换肤/打包（ui-asset-skin plan）**——独立于本计划，需在阶段 4 UI 落地时同步执行（散图 → Auto Atlas 打包），避免 UI 落地后返工。