# 前端 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["路由 / 双区切换
玩家区·创作区"] S["Pinia Store
用户/项目/流/会话"] H["axios 封装
统一拦截/错误码"] M["vite mock 基建
据 5 个 API YAML"] D["D4 设计 token
+ 通用组件库"] end subgraph PLAYER["② 玩家区"] F["游戏流 Feed
竖屏刷/双专区/互动/分享"] end subgraph CREATOR["④ 创作区"] C["创作流
创建/模板/一句话/进度轮询"] P["项目管理
我的项目/草稿/发布门禁"] end subgraph HOST["③ 宿主×运行时（技术核心 · 玩家与创作共用）"] G["GamePlayer 宿主容器
iframe 沙箱 + postMessage 桥
+ 三容器预加载 + origin/schema 双校验"] SDK["WanxiangGameSDK（契约#3）
注入游戏 iframe 侧"] RT["Canvas Runtime <15KB（Tier1）
+ 1 个 demo 游戏"] AD["ad/pay 插件桩
宿主侧渲染"] end end MOCK["契约 mock 层
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["玩家区
（默认首页 = 游戏流）"] FEED -->|"创作"入口| CREATE["创作区
（创建/生成/项目）"] 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 白名单
+ payload schema"] ADR["ad/pay 桩渲染
（广告在 iframe 外宿主渲染）"] TEL["遥测转发 → /telemetry/events/batch"] end subgraph INNER["游戏侧（iframe 沙箱内）"] SDK["window.WanxiangGameSDK
init/on/off/track/reportError
+ ad/pay 插件"] RT["Canvas Runtime <15KB
+ 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
（已锁，单一事实源）"] --> MOCK["vite-plugin-mock
按 path/method 生成 handler"] MOCK --> AXIOS["axios 实例
（拦截器统一处理）"] AXIOS --> PAGES["业务页面"] YAML -.同源.-> BE["后端真实接口
（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 地基
（先行/被依赖，第一波）"] B1["② 游戏流 Feed"] B2["③ 宿主×SDK×Runtime
★Opus 关键 agent★"] B3["④ 创作流 Create"] B4["⑤ 项目管理 Project"] end subgraph C["Phase C · 集成（主 agent 串行 + 验证门）"] C1["路由总装 + 区切换接线"] C2["vite build + vue-tsc 类型检查"] C3["本地 vite preview 冒烟
（/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 三相方法）。如对范围/形态/技术核心时机有不同意见，请指出，我据此调整方案再执行。