games-development-ai/docs/agent-specs/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 分层架构

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 双区

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

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

---

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

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

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 创作者闭环：创建 → 生成 → 预览 → 发布

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 骨架三者对接。

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 策略（不卡后端 / 不卡闸门）

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 三相）

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 模块与 yudao-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 三相方法）。如对范围/形态/技术核心时机有不同意见，请指出，我据此调整方案再执行。