games-development-ai/docs/agent-specs/_archive/2026-06-08-前端game-studio建设-review.md

# 前端 game-studio 脊柱建设 · Review 版计划

> 文档编号 HJ-FE-SPINE-001 · 2026-06-08 · 状态：**待创始人评审**
> 类型：review 版（结论先行 / 决策导向 / 多 Mermaid，不含代码级执行细节）
> 配套执行版：评审通过后产出 `2026-06-08-前端game-studio建设-execution.md`
> 上游依赖：Wave1 后端脊柱已建成验证（`2026-06-08-后端模块并行建设-execution.md`）

---

## 0. 一句话结论

**用已锁的 8 类契约做 mock，并行建出 `game-studio` 的"端到端可试用脊柱"——玩家侧（游戏流→试玩→互动）+ 创作者侧（创建→生成→预览→发布）一条链路本地能跑通，技术命门是自研 Canvas Runtime + WanxiangGameSDK + iframe 宿主三方链路。本次只做 `game-studio` 两端，运营后台 `game-admin` 后置。复用 Wave1 三相并行 Workflow 编排。前端不依赖后端运行、不卡外部闸门，可立即开工。**

### TL;DR 决策速览

| 维度 | 结论 | 理由 |
|---|---|---|
| **范围** | 只做 `game-studio`（创作者+玩家），`game-admin` 运营后台**后置** | 闭环优先：「做得出→有人玩」主链路在 studio；admin 是支撑、不同栈、后端已就绪可随时补 |
| **应用形态** | **单 SPA 双区**（玩家"流"为默认首页 + 创作者"创作"入口） | 「全民」用户身份流动（既玩又创），单 app 切区比双 app 跳转顺滑；省一套地基 |
| **技术核心** | 宿主容器 + WanxiangGameSDK + Canvas Runtime **本次一起出骨架** + 1 个 demo 游戏跑通三方链路 | 「试玩/预览」是闭环命门，缺它玩家侧和创作者侧都断链；契约 #3/#4 已锁，可并行 |
| **数据来源** | vite mock 据 5 个 API YAML 自动生成，前端**零后端依赖**本地预览全闭环 | 不卡 ICP/支付/广告等日历闸门，前端可独立交付到"可试用" |
| **设计** | 套 `huijing-ai-demo.html` 现成 CSS token 起骨架，ui-ux-pro-max 后续细化 | D4 已定；骨架阶段不阻塞于精细视觉 |
| **编排** | 复用 Wave1 三相并行 Workflow（前端契约→并行建模块→集成+冒烟验证门） | 已实证有效（Wave1 46 单测绿）；前端契约已锁 → 模块解耦可 N 路并行 |
| **广告/支付** | 本次只做**桩**（SDK ad/pay 插件桩），真实 SDK 切换在闸门后 | 穿山甲/微信支付需进件审核（日历闸门），与前端脊柱解耦 |

---

## 1. 背景

- **上游已就绪**：后端 Wave1 脊柱 5 模块（project/aigc/runtime/feed/telemetry）已建成并验证（46 单测绿 + 41 模块集成编译绿），13 张表 + 5 个 API 契约 + SDK/游戏包契约全锁。
- **闭环下一环 = "可试用"**：项目命题是「生成 + 流量 + 变现全闭环」。后端把"能力"建好了，但用户摸得到的是前端。脊柱闭环里「预览→发布→游戏流→试玩→互动」这几环都在前端，是把"后端能力"变成"种子用户可试用"的关键一跳。
- **前端不卡闸门**：MVP 真正关键路径是 ICP 备案 / 支付进件 / 广告审核 / LLM 实名充值等不可压缩的日历闸门（见 memory `mvp-binding-constraint-calendar-gates`）。前端用已锁契约 mock 即可独立建设+本地预览，与这些闸门**完全解耦**，是当下投入产出比最高的并行工作面。
- **现状**：`game-studio/` 与 `game-admin/` 均为**空目录**（从零建）。

---

## 2. 目标 / 非目标

### 2.1 目标（本次脊柱交付）

1. **可试用的端到端闭环**（mock 数据，本地 `vite preview` 能完整走通）：
   - **玩家闭环**：游戏流（竖屏刷）→ 点开试玩（宿主加载游戏包 + SDK 注入 + Runtime 跑）→ 互动（赞/藏/享）→ 遥测上报。
   - **创作者闭环**：创建项目 → 一句话生成（异步任务 + 进度轮询）→ 预览试玩（同宿主）→ 发布（门禁校验）。
2. **三方技术链路打通**：宿主容器 ↔ WanxiangGameSDK ↔ Canvas Runtime，用 1 个最小 demo 游戏在 iframe 沙箱里实测 postMessage 协议（生命周期 / 遥测 / 错误 / ad·pay 桩）。
3. **可验证的前端地基**：Vue3 + Vant + 路由 + 状态管理 + axios 封装 + mock 基建 + D4 设计 token + 通用组件，构建/类型检查/本地冒烟全绿。
4. **durable 化**：执行版 spec + `.agent` + 记忆 + 本地冒烟证据（截图），抗压缩续作。

### 2.2 非目标（本次明确不做）

- ❌ `game-admin` 运营后台（审核队列/精选池/数据看板）——不同栈（Element Plus），后端 admin-api 已就绪，**后置**。
- ❌ 真实后端联调——留到 staging 拉起后（与后端同一个运行时验证闸门）。
- ❌ 真实广告/支付 SDK——本次只做契约桩，真实接入在进件审核闸门后。
- ❌ Tier2/3（Cocos/3D/独立 App）——MVP 只交付 Tier1（自研 Canvas Runtime）。
- ❌ 完整玩法引擎——Runtime 本次只做"最小可跑骨架 + 1 个 demo 游戏验证链路"，不追求 3-5 模板全实现（模板引擎是后续）。
- ❌ ui-ux-pro-max 精细视觉打磨——骨架阶段套 demo CSS token 即可，精修后续单独迭代。
- ❌ 钱包/提现/收益（创作者变现侧）——属 Wave2 变现，本次脊柱聚焦"创作→流→试玩"主干。

---

## 3. 推荐方案总览

### 3.1 game-studio 分层架构

```mermaid
graph TD
    subgraph APP["game-studio 单 SPA（Vue3 + Vant，移动竖屏优先）"]
        subgraph SHELL["① 应用地基 App Shell"]
            R["路由 / 双区切换<br/>玩家区·创作区"]
            S["Pinia Store<br/>用户/项目/流/会话"]
            H["axios 封装<br/>统一拦截/错误码"]
            M["vite mock 基建<br/>据 5 个 API YAML"]
            D["D4 设计 token<br/>+ 通用组件库"]
        end
        subgraph PLAYER["② 玩家区"]
            F["游戏流 Feed<br/>竖屏刷/双专区/互动/分享"]
        end
        subgraph CREATOR["④ 创作区"]
            C["创作流<br/>创建/模板/一句话/进度轮询"]
            P["项目管理<br/>我的项目/草稿/发布门禁"]
        end
        subgraph HOST["③ 宿主×运行时（技术核心 · 玩家与创作共用）"]
            G["GamePlayer 宿主容器<br/>iframe 沙箱 + postMessage 桥<br/>+ 三容器预加载 + origin/schema 双校验"]
            SDK["WanxiangGameSDK（契约#3）<br/>注入游戏 iframe 侧"]
            RT["Canvas Runtime &lt;15KB（Tier1）<br/>+ 1 个 demo 游戏"]
            AD["ad/pay 插件桩<br/>宿主侧渲染"]
        end
    end
    MOCK["契约 mock 层<br/>project/aigc/runtime/feed/telemetry.yaml"] -.消费.-> H
    F -->|点开试玩| G
    C -->|生成后预览| G
    G <-->|postMessage| SDK
    SDK --> RT
    G --> AD
    SHELL --> PLAYER
    SHELL --> CREATOR
    SHELL --> HOST
```

**说明**：①地基被所有区依赖（先锁接口）；③宿主是玩家与创作**共用**的"试玩/预览"引擎（命门）；②④是业务页面，通过地基契约 + 宿主组件接口解耦，可并行建。

### 3.2 应用形态：单 SPA 双区

```mermaid
graph LR
    START(("进入 game-studio")) --> FEED["玩家区<br/>（默认首页 = 游戏流）"]
    FEED -->|"创作"入口| CREATE["创作区<br/>（创建/生成/项目）"]
    CREATE -->|预览/发布后| FEED
    FEED -->|点开任意游戏| PLAY["试玩（宿主容器）"]
    CREATE -->|生成完成| PREVIEW["预览（同宿主容器）"]
```

- 默认落地 = **玩家游戏流**（"像刷短视频一样发现并即点即玩"是产品第一体验）。
- "创作"是显式入口（底部 Tab 或悬浮 CTA），切到创作区。
- 试玩与预览**共用同一个宿主容器**，只是数据来源不同（已发布版本 vs 刚生成的草稿版本）。

---

## 4. 脊柱闭环定义（端到端时序）

### 4.1 玩家闭环：刷流 → 试玩 → 互动 → 遥测

```mermaid
sequenceDiagram
    participant U as 玩家
    participant FE as 游戏流页
    participant API as Mock(feed/runtime/telemetry)
    participant HOST as 宿主容器
    participant SDK as WanxiangGameSDK
    participant RT as Canvas Runtime(demo)

    U->>FE: 进入，竖屏刷
    FE->>API: GET /feed/stream（cursor分页）
    API-->>FE: 卡片流（封面/标题/作者）
    U->>FE: 点开某游戏
    FE->>API: GET /runtime/package/{versionId}
    API-->>FE: 游戏包清单（manifest+assets）
    FE->>API: POST /runtime/session/start
    API-->>FE: sessionId
    FE->>HOST: 加载游戏包到 iframe 沙箱
    HOST->>SDK: postMessage(init: gameId/versionId/traceId)
    SDK->>RT: 启动 Runtime，加载 assets
    RT-->>SDK: 生命周期 game_loaded/game_start
    SDK->>HOST: postMessage(lifecycle/telemetry)
    HOST->>API: POST /telemetry/events/batch（埋点）
    U->>FE: 点赞/收藏/分享
    FE->>API: POST /feed/interact
    U->>HOST: 退出
    HOST->>API: POST /runtime/session/end（时长）
```

### 4.2 创作者闭环：创建 → 生成 → 预览 → 发布

```mermaid
sequenceDiagram
    participant C as 创作者
    participant CR as 创作页
    participant API as Mock(project/aigc/runtime)
    participant HOST as 宿主容器

    C->>CR: 创建项目
    CR->>API: POST /project（status=0草稿）
    C->>CR: 选模板 + 一句话描述
    CR->>API: GET /aigc/template/list
    CR->>API: POST /aigc/generate（prompt+templateId）
    API-->>CR: taskId（异步）
    loop 轮询进度
        CR->>API: GET /aigc/task/{id}
        API-->>CR: 进度%（步骤+百分比）
    end
    API-->>CR: 终态：产物（versionId + 游戏包）
    C->>CR: 预览试玩
    CR->>HOST: 加载草稿版本游戏包（同宿主）
    C->>CR: 满意，发布
    CR->>API: POST /project/{id}/publish（7门禁校验）
    API-->>CR: 进入审核 / 门禁失败原因
```

---

## 5. 技术核心：宿主 × SDK × Runtime 三方契约

> 这是脊柱最有技术含量、最该用 Opus 关键 agent 建的部分。契约 #3（`sdk-interface.d.ts`）已锁，本次是**宿主侧实现 + 游戏侧 SDK 实现 + Runtime 骨架**三者对接。

```mermaid
graph TB
    subgraph OUTER["宿主侧（game-studio，iframe 外）"]
        HOST["GamePlayer 容器"]
        VALID["双校验：origin 白名单<br/>+ payload schema"]
        ADR["ad/pay 桩渲染<br/>（广告在 iframe 外宿主渲染）"]
        TEL["遥测转发 → /telemetry/events/batch"]
    end
    subgraph INNER["游戏侧（iframe 沙箱内）"]
        SDK["window.WanxiangGameSDK<br/>init/on/off/track/reportError<br/>+ ad/pay 插件"]
        RT["Canvas Runtime &lt;15KB<br/>+ demo 游戏"]
    end
    HOST -->|"postMessage(init)"| SDK
    SDK -->|"lifecycle/telemetry/error"| VALID
    SDK -->|"ad/pay 请求"| VALID
    VALID --> HOST
    HOST --> ADR
    VALID --> TEL
    SDK --> RT
```

**本次要落地的三方对接点（骨架级，可验证）：**

| 组件 | 归属 | 本次交付 | 验证方式 |
|---|---|---|---|
| **GamePlayer 宿主** | game-studio | iframe 沙箱挂载 + postMessage 信封收发 + origin/schema 双校验 + 三容器（当前/上/下）预加载占位 | demo 游戏能被加载并跑起 |
| **WanxiangGameSDK** | 独立构建产物（注入 iframe） | 契约 #3 全接口骨架：init/on/off/track/reportError + ad/pay 桩；fire-and-forget；不向游戏抛异常 | postMessage 往返 + 生命周期事件触达宿主 |
| **Canvas Runtime** | 独立产物 Tier1 | <15KB 最小渲染循环骨架 + 1 个 demo 游戏（点击类，验证链路足矣） | iframe 内能渲染、能发 game_start/game_end |
| **ad/pay 桩** | game-studio 宿主 | 契约 #3 ad.showRewarded/showInterstitial/pay.pay 的桩 UI（弹层模拟），回调 rewarded/paid | 点击触发回调，链路通 |

**安全边界（不可省，见 security-and-reliability §1.1）**：iframe 沙箱 + 宿主侧 origin 白名单 + payload schema 双校验**必须真实实现**，不能用 mock 绕过——这是 UGC 游戏跑在用户设备上的信任边界，前端是唯一执行点。

---

## 6. Mock 策略（不卡后端 / 不卡闸门）

```mermaid
graph LR
    YAML["5 个 API 契约 YAML<br/>（已锁，单一事实源）"] --> MOCK["vite-plugin-mock<br/>按 path/method 生成 handler"]
    MOCK --> AXIOS["axios 实例<br/>（拦截器统一处理）"]
    AXIOS --> PAGES["业务页面"]
    YAML -.同源.-> BE["后端真实接口<br/>（staging 联调时切换 baseURL）"]
    AXIOS -. 改 baseURL .-> BE
```

- mock handler **严格按契约 YAML 的 path/method/响应结构**生成 → 前端写的代码与真实后端零偏差（切 baseURL 即联调）。
- 异步任务（aigc 生成）mock 用"递增进度 + 定时终态"模拟轮询体验。
- 列表类（feed/project）mock 提供 cursor 分页假数据，足够验证滑动流/分页。
- **关键收益**：前端从"建"到"本地可试用"全程零后端依赖，与日历闸门解耦。

---

## 7. 并行编排设计（复用 Wave1 三相）

```mermaid
graph TD
    subgraph A["Phase A · 前端内部契约（主 agent 主导 + 评审门）"]
        A1["路由表 + 双区切换约定"]
        A2["Pinia store 切分 + 状态契约"]
        A3["mock 数据约定（据 YAML）"]
        A4["D4 设计 token + 通用组件接口"]
        A5["GamePlayer 宿主对外接口签名"]
    end
    subgraph B["Phase B · 并行建模块（N 子 agent，互斥目录）"]
        B0["① App Shell 地基<br/>（先行/被依赖，第一波）"]
        B1["② 游戏流 Feed"]
        B2["③ 宿主×SDK×Runtime<br/>★Opus 关键 agent★"]
        B3["④ 创作流 Create"]
        B4["⑤ 项目管理 Project"]
    end
    subgraph C["Phase C · 集成（主 agent 串行 + 验证门）"]
        C1["路由总装 + 区切换接线"]
        C2["vite build + vue-tsc 类型检查"]
        C3["本地 vite preview 冒烟<br/>（/browse 或 chrome-devtools 走双闭环 + 截图）"]
    end
    A --> B0
    B0 --> B1
    B0 --> B2
    B0 --> B3
    B0 --> B4
    B1 --> C1
    B2 --> C1
    B3 --> C1
    B4 --> C1
    C1 --> C2 --> C3
```

**编排要点（沿用 Wave1 实证规则）：**

1. **地基先行**：① App Shell 是被依赖项，Phase A 末锁定其对外接口（路由/store/组件/mock 约定/宿主组件签名）→ Phase B 第一波单独建地基并验证 → 其余模块基于已锁接口并行。
2. **互斥目录**：每个子 agent 只写 `game-studio/src/{区}/` 互斥子目录，**共享文件**（路由总表、`vite.config`、`package.json`、全局 store 注册）**只由主 agent 在 Phase C 串行碰** → 无冲突、免 worktree。
3. **关键 agent 跑 Opus**：③ 宿主×SDK×Runtime 是技术命门（沙箱/协议/Runtime），按 memory `opus-subagents-critical-tasks` 跑 Opus Max。
4. **主 agent 验证门**：不信子 agent 自报 build success，独立复跑 `vite build` + `vue-tsc` + 本地 preview 冒烟（浏览器实跑双闭环截图），对应后端的 `mvn test` 验证门。
5. **durable 锚点**：执行版 spec 写 workflow runId + LIVE 状态，抗压缩续作。

---

## 8. 关键权衡

| # | 抉择 | 选择 | 放弃的替代 | 理由 |
|---|---|---|---|---|
| T1 | studio 应用形态 | 单 SPA 双区 | 玩家/创作两个独立 app | 用户身份流动；省一套地基；切区比跳 app 顺滑。代价：单包略大，可路由懒加载缓解 |
| T2 | 宿主+SDK+Runtime 时机 | 本次一起出骨架 | 先做业务页面、宿主后做 | 缺宿主则"试玩/预览"断链，玩家+创作两端闭环都跑不通——脊柱不成立 |
| T3 | Runtime 深度 | 最小骨架 + 1 demo 游戏 | 完整 3-5 模板引擎 | 脊柱目标是"链路通"，模板引擎是后续；<15KB 硬约束下先验证三方协议 |
| T4 | 数据来源 | 全 mock | 等后端 staging 起来再建前端 | 解耦闸门，前端独立交付；契约已锁，切 baseURL 即联调，零返工 |
| T5 | 设计落地 | 套 demo CSS token 起骨架 | 先 ui-ux-pro-max 精修再写代码 | 不阻塞主干；视觉精修可在骨架上独立迭代 |
| T6 | 运营后台 | 后置 game-admin | 本次一并做 | 不同栈、非主闭环、后端已就绪；聚焦"做得出→有人玩" |

---

## 9. 爆炸半径 / 风险 / 兼容

- **爆炸半径**：全新目录 `game-studio/`，**不触碰**已验证的后端 5 模块与 huijing-server。零回归风险。共享文件仅 `game-studio/` 内部（路由/config/package.json），由主 agent 串行管理。
- **风险点**：
  1. **Canvas Runtime <15KB 硬约束**（中）：骨架阶段先保最小可跑，体积红线在执行版设门禁（构建产物体积断言）；超标则砍 demo 游戏复杂度，不砍协议。
  2. **iframe 沙箱跨域 postMessage 双校验**（中）：本地 mock 环境同源易"假通过"，须用真实跨 origin（不同端口/srcdoc）验证 schema 校验逻辑真生效，避免到 staging 才暴露。
  3. **异步生成轮询体验**（低）：mock 用定时终态模拟，真实 Dify 回调时延更大，进度 UI 要容忍长等待 + 超时态（契约已有 timed_out）。
  4. **D4 视觉与 Vant 主题耦合**（低）：Vant 默认主题与深色科技 demo 风格冲突，需主题化覆盖，骨架阶段先粗调，精修后置。
- **兼容**：mock 严格贴契约 → 后端联调零接口偏差；SDK 遵循 semver 只增不改 → 游戏侧向后兼容。

---

## 10. 验收标准（脊柱"可试用"的可验证门）

| # | 验收项 | 判定方式 |
|---|---|---|
| AC1 | 构建通过 | `vite build` 成功，无错误 |
| AC2 | 类型通过 | `vue-tsc --noEmit` 零类型错误 |
| AC3 | **玩家闭环本地跑通** | `vite preview` + 浏览器：刷流→点开→demo 游戏跑起→点赞→退出，遥测/互动请求在 mock 命中（截图为证） |
| AC4 | **创作者闭环本地跑通** | 创建→选模板→一句话→进度轮询到终态→预览试玩→发布门禁响应（截图为证） |
| AC5 | **三方链路实测** | 宿主 init → SDK 生命周期事件（game_loaded/start/end）→ 宿主收到 → 遥测转发；postMessage 双校验对非法 origin/schema 拒绝（控制台/截图为证） |
| AC6 | ad/pay 桩链路 | 触发激励视频桩 → 回调 rewarded=true；支付桩 → 回调 paid（截图为证） |
| AC7 | Runtime 体积 | 构建产物 Runtime 包 <15KB（体积断言） |
| AC8 | durable 化 | 执行版 spec + `.agent` + 记忆更新 + 冒烟截图归档 |

> 验证由**主 agent 独立执行**（浏览器走查经 `/browse` 技能，禁用 `mcp__claude-in-chrome__*`），不采信子 agent 自报。

---

## 11. 待确认项（请创始人拍板）

| # | 决策点 | 推荐 | 影响 |
|---|---|---|---|
| **Q1** | 本次范围是否只做 `game-studio`（创作者+玩家），`game-admin` 运营后台后置？ | **是**（聚焦主闭环） | 决定本轮工作量与并行模块数 |
| **Q2** | `game-studio` 是否采用单 SPA 双区（玩家流默认首页 + 创作入口）？ | **是** | 决定地基与路由结构 |
| **Q3** | 宿主 + WanxiangGameSDK + Canvas Runtime 是否本次一起出骨架（含 1 demo 游戏跑通三方链路）？ | **是**（否则闭环不成立） | 决定是否设 Opus 关键 agent、是否引入 Runtime 子产物 |
| **Q4** | 是否接受"全 mock 本地可试用、真实联调留 staging"作为本次验收口径？ | **是**（不卡闸门） | 决定验收边界（AC3/4 以 mock 跑通为准） |

---

## 12. 配套交付 + 闸门提醒

- **配套**：评审通过执行后，补 staging 拉起 + 脊柱运行时冒烟手册（前端 `vite build` 产物 + 后端 docker-compose 中间件 + `ruoyi-vue-pro.sql` 初始化 + Flyway 自动建 game 表 + 切 baseURL 真实联调）——本环境无 docker，须人侧或有基建环境跑。
- **闸门提醒（再次强调，MVP 真正关键路径）**：前端建设期间，人侧应**即刻并行启动**长周期日历闸门——经营主体注册 / ICP 备案 / 支付进件 / 广告联盟审核 / LLM 实名充值。这些不可压缩，是 MVP 上线的 binding constraint（见 memory `mvp-binding-constraint-calendar-gates`），越早启动越好。

---

## 评审请求

请就 **§11 的 Q1–Q4** 拍板。四项若全认可（推荐），我即产出执行版 spec 并启动并行 Workflow（复用 Wave1 三相方法）。如对范围/形态/技术核心时机有不同意见，请指出，我据此调整方案再执行。