games-development-ai/docs/architecture/_archive/系统概要设计-技术决策版.md

🗄️ 已归档(2026-06-20 设计文档域化重构) —— 内容已重写并迁入 架构/README.md + 架构/13模块.md。本档为决策史留档,非现行 SoT;现行真相见 6 域树(总索引 docs/architecture/README.md)。

绘境AI游戏生态平台 — 系统概要设计（技术决策版）

文档编号：HJ-ARCH-001 版本：v2.1（2026-06-16 现行真相对齐：模板驱动/new-api/SAA/LittleJS/mmx-cli/命名空间） 受众：技术合伙人 / CTO / 首席架构师 生成时间：2026-06-06 关联文档：

• 业务需求：docs-design/MVP PRD.md、docs-design/Product Strategy Document.md
• 竞品分析：docs-design/竞品分析报告.md
• 产品需求/技术模块/映射 三文档：docs/architecture/产品需求清单.md、docs/architecture/技术架构与模块.md、docs/architecture/需求模块映射.md

⚠️ 回填状态（2026-06-10 起 → 2026-06-16 对齐现行真相，依据 HJ-AUDIT-001 架构三向审计 + 后续多次创始人裁定）：本档为蓝图权威，正文已逐节对齐以下裁定（以裁定为准）。本档 v2.0 成稿于 2026-06-06，下列 7 条均晚于成稿、已落入正文：

1. 生成主线已转向「模板驱动 via new-api 网关」→ 再演进为「agent 写码于插件库」（C2 裁定 2026-06-09 spike 52/52 结构层 100%；HJ-GEN-001 终审 2026-06-12 游戏模板/填参线退役）：LLM 经 new-api 网关直连便宜模型直出可玩游戏，经 harness 九门兜底；Dify / OpenGame 均从未部署、降级为远期增强，非现行生成引擎。后端实测 14 文件接 new-api（game-module-aigc-server）。
2. agentic 编排基建 = SAA(Spring AI Alibaba GA v1.1.2.2)裸 StateGraph 编排（HJ-AGI-002，2026-06-15）：short-term SAA-only，AgentScope 降 long-term premium 独立轨；后端实测 spring-ai-alibaba 已接入（SaaStudioGraph 等）。旧「自研编排/DAG 工作流引擎/Dify 可视化编排」表述全部作废。
3. Tier1 引擎 = LittleJS 增强发行版（55KB gz）+ Runner v2 装载契约 game-host.d.ts（2026-06-12 终裁，spike 85/82）：本档「自研 Canvas Runtime <15KB」相关描述全部被取代——15KB 红线废除（系 srcdoc 内联架构的衍生约束，前提已失效），改三层约束框架（SLO@千元机+4G P75 / 预算入场券 gz≤350KB·raw≤1.5MB / 工程增强层）；沙箱/SDK/三容器控制点不变。
4. 模板 = LittleJS 能力插件/二次开发件；游戏模板/填参式模板已废除（W-CLEAN，旧4模板+存量已清）：玩法/美术/关卡/UI = agent 生成域；旧 4 模板 + 存量数据已清除。Tier2/3 复杂 2D/3D/原生仍用 Cocos Creator 3.8.8 + MCP（不变）。注：「玩法模板」（品类/玩法框架·引导 AI 生成·非 pre-built 代码）未废 = 有效功能·待建，但非最高优先级（最高=Tier 0 生成可靠，玩法模板排其后；HJ-DEMO-AUDIT-001 创始人 2026-06-17，见完成度与优先级总账）。
5. AI 素材/音乐工具链 = mmx-cli（MiniMax，2026-06-12 创始人亲验拍板默认）：agent 造游戏直接 CLI 调用、免 GPU/免训练；ComfyUI 退备选，Stability Audio 等亦降级。
6. 代码命名空间整体改名为 com.wanxiang.huijing（公司 Wanxiang / 项目 Huijing，2026-06-15 合 dev/2.0.0）；对外品牌 = 绘境AI。
7. 执行排期以 mvp-execution-spec + docs/mvp/MVP作战清单.md 为准，§9 甘特仅作蓝图参考；2026-06-08 业务决策已将 MVP 验收改为「staging/内网种子灰度走通真闭环」，公网上线 = MVP 后并行长周期任务（受日历闸门约束）。
8. LLM 接入现状：D1 拍板主 DeepSeek / 备 Qwen（2026-06-08）；现行实际 = new-api 网关多模型可用（deepseek-v4-flash/pro + MiniMax-M2.7/M3 渠道全活，2026-06-14 探活实测）。网关多通道兜底曾真实失效（二厂系全废），见 §8 风险 #12。
9. RocketMQ / Nacos = 框架（yudao fork）自带依赖 + yaml 配置存在，但 MVP 运行时未部署 broker/registry → future-state（框架自带、MVP 未启用）；正文凡涉之处一律如此标注。 单一事实源（现行口径日常入口）：.agents/knowledge/tech-decisions.md（§1/§1.1/§4）+ .agents/skills/saa-graph-orchestration.md。

---

1. 背景与目标

1.1 业务背景

绘境AI 是一个 AI 驱动的全民游戏创作与变现生态平台。核心命题：让零基础创作者用一句话做出可上线、可变现的轻量小游戏，让玩家像刷短视频一样发现和试玩，让平台通过广告分成、订阅、B端定制实现商业闭环。

竞品格局（详见竞品分析报告）：

• 极逸 SOON：技术最强，无流量
• TapTap 制造：有流量，封闭且变现弱
• FunloomAI：有付费验证，品类窄

绘境的差异化 = 全闭环：生成 + 流量 + 变现三件事同时解决。

1.2 系统目标

维度	目标	量化指标
功能完整性	创作→生成→预览→发布→审核→游戏流→试玩→互动→变现 全链路闭环	端到端可走通
生成能力	自然语言输入，3-5 分钟产出可玩 Web 游戏	生成成功率 ≥85%（远期蓝图目标；MVP 验收线 ≥80%）
运行性能	游戏流首屏可交互	P75 < 3s, P95 < 6s
可用性	核心链路服务可用	≥ 99.5%（MVP）, ≥ 99.9%（正式）
扩展性	支持从单体启动平滑迁移到微服务	模块可独立部署
成本可控	MVP 阶段基础设施月成本	< 5000 元/月

1.3 非目标（明确不做）

• 不做 3D 开放世界游戏生成
• 不做专业级游戏引擎（Unity/Unreal 级别）
• 不做海外市场（MVP 阶段）
• 不做完全开放式代码生成（agent 写码于 LittleJS 插件库 + harness 九门约束保证稳定性；游戏模板/填参线已废 W-CLEAN）
• 不自研大模型（接入通用 LLM 经 new-api 网关 + 开源 Agent 框架 SAA/Spring AI Alibaba）

---

2. 业务架构

2.1 核心业务域

graph LR
  subgraph 创作域
    A0[资产管理] --> A1[游戏设计]
    A1 --> A2[AI 辅助生成]
    A2 --> A3[组装/编辑/调试]
    A3 --> A4[预览试玩]
    A4 --> A5[质量校验]
    A5 --> A6[发布申请]
  end

  subgraph 分发域
    B1[审核通过] --> B2[游戏流推荐]
    B2 --> B3[玩家试玩]
    B3 --> B4[互动反馈]
    B4 --> B5[分享传播]
  end

  subgraph 变现域
    C1[广告植入] --> C2[广告展示]
    C2 --> C3[收益归集]
    C3 --> C4[创作者结算]
    C4 --> C5[提现]
  end

  subgraph 数据域
    D1[事件采集] --> D2[质量评分]
    D2 --> D3[推荐优化]
    D3 --> D4[AI 优化建议]
    D4 --> A3
  end

  A5 --> B1
  B3 --> C2
  B4 --> D1

2.2 用户角色与权限模型

graph TB
  VISITOR[访客<br/>可浏览试玩] --> PLAYER[玩家<br/>+互动/收藏/举报]
  PLAYER --> CREATOR[创作者<br/>+创建/生成/发布]
  CREATOR --> PRO_CREATOR[专业创作者<br/>+批量/编排/B端]
  
  OPERATOR[运营<br/>审核/推荐/下架] --> ADMIN[管理员<br/>+系统配置/权限]
  
  B_CLIENT[B端客户<br/>需求/验收/报告]

角色	权限边界	对应系统入口
访客	浏览游戏流 + 试玩（无需登录）	game-studio
玩家	+点赞/收藏/分享/举报/评论	game-studio（登录后）
创作者	+创建项目/生成/编辑/发布/数据看板/收益	game-studio
专业创作者	+批量生成/工作流编排（远期）/素材市场/B端接单	game-studio（高级功能）
运营	审核/推荐/下架/精选/内容安全	game-admin
管理员	+系统配置/用户管理/权限/字典/监控	game-admin
B端客户	需求提交/进度查看/验收/报告	独立 B 端门户（P1）

2.3 核心业务流程

创作者主流程（三种模式）

模式 A：一句话生成（小白路径）

现行口径（2026-06-16）：下图为 MVP 现行主线——生成 = SAA(Spring AI Alibaba)裸 StateGraph 编排 驱动 new-api 网关 → 便宜 LLM，agent 写码于 LittleJS 插件库，经 harness 九门兜底；Dify/OpenGame 从未部署（旧蓝图原案见 §6.2 决策史）。生成任务派发走 GenerationDispatcher（http worker | 进程内 SAA 图 二选一单写），生成态 SAA 编排藏在 job/callback 契约后保持可替换。

sequenceDiagram
  participant C as 创作者
  participant S as game-studio
  participant GW as Gateway
  participant AIGC as aigc-module
  participant SAA as SAA StateGraph编排
  participant NEWAPI as new-api 网关
  participant LLM as 便宜LLM(DeepSeek/MiniMax)
  participant GATE as harness 九门(校验/构建/真玩)
  participant PRJ as project-module
  participant BPM as bpm-module

  C->>S: 输入 Prompt + 选择风格
  S->>GW: POST /api/aigc/generate
  GW->>AIGC: 转发（鉴权通过）
  AIGC->>AIGC: 创建生成任务（GenerationDispatcher 派发）
  AIGC-->>S: 202 Accepted {taskId}
  S->>S: 轮询/SSE 监听任务状态

  AIGC->>SAA: dispatch(job)：进入裸图编排
  SAA->>SAA: 节点：渲染→设计→生成代码（11 节点/4 条件边）
  SAA->>NEWAPI: 各节点经 OpenAI 兼容接口调模型
  NEWAPI->>LLM: 转发（单 key→自动入 newapi_cost 计费平面）
  LLM-->>NEWAPI: 返回 GameConfig / 游戏代码
  NEWAPI-->>SAA: 模型产物
  SAA->>GATE: 校验/构建/真玩 九门（done 由确定性门定，非 LLM 自评）
  GATE-->>SAA: 通过 → 出 GamePackage；不通过 → 修复回环
  SAA-->>AIGC: 回调 callback：packageUrl + manifest

  AIGC->>PRJ: 写入草稿版本（含生成的资产）
  AIGC-->>S: 任务完成通知

  C->>S: 预览试玩（iframe 加载）
  C->>S: 编辑标题/简介/封面/标签
  C->>S: 点击发布
  S->>GW: POST /api/project/publish
  GW->>PRJ: 提交发布审核
  PRJ->>BPM: 发起审核工作流
  BPM-->>C: 通知审核结果

模式 B：资产驱动创作（进阶路径，详见下方"创作工作台核心设计"）

创作者先在资产空间中逐步积累游戏素材（角色/关卡/音乐/机制），然后选择模板组装为完整游戏。AI 在每个环节辅助生成单项资产，但最终决策权在创作者。

模式 C：工作流编排（专业路径）

专业创作者可自定义生成流程的节点、参数和条件分支，适用于批量生产、品牌定制等场景。（2026-06-16 纠偏：原述"进入 Dify 可视化编排界面"——Dify 从未部署、已降级远期；现行/远期编排基建 = SAA(Spring AI Alibaba)裸 StateGraph 编排（HJ-AGI-002），可视化编排面属远期能力。）

玩家游戏流主流程

sequenceDiagram
  participant P as 玩家
  participant S as game-studio
  participant GW as Gateway
  participant FEED as feed-module
  participant RT as runtime-module
  participant TEL as telemetry-module

  P->>S: 进入首页/游戏流
  S->>GW: GET /api/feed/list?cursor=xxx
  GW->>FEED: 推荐列表（规则+行为信号）
  FEED-->>S: [{gameId, title, cover, manifest_url}, ...]

  S->>S: 展示封面卡片 + 预加载下一款 manifest
  P->>S: 点击"开始玩"
  S->>RT: 加载 manifest → 资源 → 启动游戏（iframe sandbox）
  S->>TEL: 上报 game_load_start
  RT-->>S: 游戏启动
  S->>TEL: 上报 game_play_start

  P->>S: 游玩 30s+
  S->>TEL: 上报 game_play_30s
  P->>S: 游戏结束
  S->>TEL: 上报 game_complete
  P->>S: 点赞/收藏/分享
  S->>GW: POST /api/feed/interaction
  GW->>FEED: 记录互动

  P->>S: 上滑切换下一款
  S->>S: 销毁当前容器 + 激活预加载容器

创作工作台核心设计

设计原则：创作者不是"Prompt 输入者"，而是"游戏设计师"。AI 是助手，不是替代品。

创作工作台提供三种创作模式，覆盖从小白到专业的全链路：

模式	目标用户	交互方式	AI 角色
一句话生成	纯小白	Prompt → 一键出成品	AI 主导，人确认
资产驱动创作	进阶创作者	先设计资产，再组装游戏	AI 辅助生成单项资产
全自定义编排（远期能力，MVP 暂不提供）	专业创作者	可视化编排面=远期（对齐 §2.3 模式C/L815；现行专业路径=按需调 SAA 裸 StateGraph）+ 手动调参	AI 按需调用

创作者资产管理体系

每个创作者拥有独立的资产空间（Asset Workspace），所有创作素材归创作者所有：

graph TB
  subgraph 创作者资产空间
    direction TB
    
    subgraph 视觉资产
      IMG[角色立绘/场景图/UI 元素]
      TEX[贴图/材质/粒子效果]
      ANIM[动画/帧序列/Spine]
      COVER[封面/宣传图/分享卡片]
    end
    
    subgraph 音频资产
      BGM[背景音乐]
      SFX[音效]
      VOICE[角色语音/音色]
      MV[过场动画/MV]
    end
    
    subgraph 设计资产
      CHAR[角色设定<br/>外观/性格/能力/台词]
      LEVEL[关卡设计<br/>地图/难度曲线/触发条件]
      MECH[游戏机制<br/>玩法规则/胜负条件/计分]
      ECON[经济系统<br/>货币/道具/产出/消耗]
      STORY[剧情/对话树/分支]
    end
    
    subgraph 商业化资产
      SHOP[付费道具设计<br/>皮肤/复活/加速/关卡包]
      AD_CFG[广告位配置<br/>时机/类型/频次]
      SOCIAL[社交接入配置<br/>好友/排行/邀请/PK]
    end
  end
  
  IMG & TEX & ANIM & COVER --> GAME[游戏项目]
  BGM & SFX & VOICE & MV --> GAME
  CHAR & LEVEL & MECH & ECON & STORY --> GAME
  SHOP & AD_CFG & SOCIAL --> GAME

资产生成方式

每种资产都支持三种产出方式：

产出方式	说明	质量控制
AI 生成	自然语言描述 → AI 产出（图片/音乐/角色/关卡等）	平台合规检测 + 风格一致性校验
手动上传	创作者上传自有素材	格式/大小/安全扫描 + 版权声明
市场获取	从素材市场购买/获取他人共享的资产	授权链验证 + 使用范围限制

资产驱动的游戏组装流程

sequenceDiagram
  participant C as 创作者
  participant WS as 工作台
  participant ASSET as 资产服务
  participant AIGC as AI 生成
  participant COMP as 合规检测
  participant RT as 运行时

  Note over C,RT: 阶段一：准备资产
  C->>WS: 创建角色设定（描述性格/外观/能力）
  WS->>AIGC: AI 生成角色立绘（基于描述）
  AIGC->>COMP: 图像合规检测
  COMP-->>AIGC: 通过
  AIGC-->>WS: 角色立绘
  C->>ASSET: 保存到我的资产空间

  C->>WS: 设计关卡（描述地图/难度/触发器）
  WS->>AIGC: AI 生成关卡配置 JSON
  AIGC-->>WS: 关卡配置
  C->>WS: 手动微调数值（速度/生成频率/奖励）
  C->>ASSET: 保存关卡到资产空间

  C->>WS: 描述背景音乐风格
  WS->>AIGC: AI 生成 BGM
  AIGC->>COMP: 音频合规检测（版权/内容）
  COMP-->>AIGC: 通过
  C->>ASSET: 保存 BGM

  Note over C,RT: 阶段二：组装游戏
  C->>WS: 选择游戏模板/机制（如"躲避类"）
  C->>WS: 从资产空间拖入：角色 + 关卡 + BGM + 音效
  C->>WS: 配置游戏机制（胜负条件/计分规则）
  C->>WS: 配置付费道具（复活 = 看广告 or ¥1）
  C->>WS: 配置广告位（过关插屏 + 结算激励视频）
  WS->>RT: 编译组装 → GamePackage

  Note over C,RT: 阶段三：预览与调试
  C->>WS: 预览试玩（iframe 沙箱）
  WS->>WS: 实时调试面板（FPS/事件流/状态变量）
  C->>WS: 发现问题 → 调整参数 → 重新编译
  C->>WS: 满意 → 提交发布

质量与合规控制点

在创作全链路设置7 道门禁，确保产出质量和平台安全：

graph LR
  G1[① Prompt/描述<br/>安全检测] --> G2[② AI 产出<br/>合规校验]
  G2 --> G3[③ 资产入库<br/>版权声明+风格校验]
  G3 --> G4[④ 组装时<br/>Schema 完整性]
  G4 --> G5[⑤ 编译后<br/>性能门禁]
  G5 --> G6[⑥ 预览时<br/>可玩性自测]
  G6 --> G7[⑦ 发布前<br/>终审+合规+适龄]

门禁	检测内容	阻断条件	责任方
① Prompt 安全	违禁词/敏感意图/注入攻击	命中 → 拒绝 + 提示修改	compliance 模块
② AI 产出合规	图片涉黄涉暴/文本违规/音频侵权	检测不通过 → 不入库	compliance 模块
③ 资产入库	版权声明完整/风格与 IP 库比对/文件安全	疑似侵权 → 冻结 + 人工复核	ip 模块
④ 组装完整性	GameConfig JSON Schema/必填字段/资源引用有效	缺失 → 编译失败 + 提示	runtime 模块
⑤ 性能门禁	包体积 ≤10MB/首屏 ≤2MB/无外部网络请求	超限 → 阻断 + 优化建议	runtime 模块
⑥ 可玩性自测	加载成功/启动成功/30s 无崩溃/结束事件触发	失败 → 阻断发布	runtime 模块
⑦ 发布终审	标题/简介/封面/标签/适龄/全链路合规汇总	人工或自动决策	bpm + compliance

创作者自由度 vs 平台控制的边界

维度	创作者可以做	平台不允许
视觉	上传任意图片/AI 生成/购买素材	涉黄涉暴涉政/侵犯已知 IP
音频	上传/AI 生成/购买	侵权音乐/违规语音
玩法	任意配置机制/关卡/难度	赌博/欺诈/诱导未成年消费
付费设计	设计道具/定价/广告位	强制付费才能通关/虚假概率/过度广告
社交接入	排行榜/好友邀请/PK	获取用户隐私/骚扰
代码	通过模板参数控制逻辑	注入任意 JS/访问外部网络/操作 DOM

底线原则：创作者通过配置（不是代码）驱动游戏行为。平台对运行时代码拥有完全控制权，创作者不直接写 JS——这是安全和合规可控的基础。

---

3. 系统架构

3.1 整体分层

graph TB
  subgraph ACCESS[接入层]
    CDN[CDN<br/>静态资源/游戏包]
    NGINX[Nginx<br/>前端托管/SSL终结]
  end

  subgraph FE[前端应用]
    STUDIO[game-studio<br/>Vue3+Vant<br/>创作者+玩家]
    ADMIN[game-admin<br/>Vue3+ElementPlus<br/>运营+管理]
  end

  subgraph GW[网关层]
    GATEWAY[Spring Cloud Gateway<br/>路由/限流/鉴权/灰度]
  end

  subgraph BIZ[业务服务层]
    STU[studio<br/>创作编排/编辑器域]
    PRJ[project<br/>项目生命周期]
    AIGC[aigc<br/>AI生成引擎]
    RT[runtime<br/>运行时/包/转换]
    FEED[feed<br/>游戏流/推荐]
    TEL[telemetry<br/>遥测/数据]
    PAY[pay<br/>支付/订阅]
    TRADE[trade<br/>结算/钱包]
    COMM[community<br/>社区/通知]
    IP[ip<br/>素材/版权]
    COMP[compliance<br/>合规/安全]
    BIZSVC[biz<br/>B端业务]
    AD[ad<br/>广告引擎]
  end

  subgraph INFRA[基础设施层_Yudao原生]
    SYS[system<br/>用户/权限/OAuth2]
    INFRASVC[infra<br/>文件/任务/日志]
    BPM[bpm<br/>工作流]
  end

  subgraph AI[AI生成层_现行]
    SAA[SAA StateGraph编排<br/>Spring AI Alibaba v1.1.2.2]
    NEWAPI[new-api 网关<br/>OpenAI兼容/多模型]
    LLM[便宜LLM<br/>DeepSeek/MiniMax]
    MMX[mmx-cli<br/>图片/音乐素材]
    LJS[LittleJS+Runner v2<br/>Tier1 引擎/插件库]
  end

  subgraph MW[中间件层]
    NACOS["Nacos<br/>(future-state·框架自带未部署)"]
    MYSQL[MySQL 8.0]
    REDIS[Redis 7]
    MQ["RocketMQ 5<br/>(future-state·框架自带未部署)"]
    MINIO[MinIO/OSS]
  end

  subgraph OBS[可观测性]
    PROM[Prometheus]
    GRAFANA[Grafana]
    SENTRY[Sentry]
    JAEGER[Jaeger<br/>链路追踪]
  end

  NGINX --> STUDIO
  NGINX --> ADMIN
  STUDIO --> GATEWAY
  ADMIN --> GATEWAY
  GATEWAY --> PRJ
  GATEWAY --> AIGC
  GATEWAY --> RT
  GATEWAY --> FEED
  GATEWAY --> TEL
  GATEWAY --> PAY
  GATEWAY --> TRADE
  GATEWAY --> COMM
  GATEWAY --> IP
  GATEWAY --> COMP
  GATEWAY --> BIZSVC
  GATEWAY --> AD
  GATEWAY --> SYS
  GATEWAY --> INFRASVC
  GATEWAY --> BPM
  AIGC --> SAA
  SAA --> NEWAPI
  NEWAPI --> LLM
  SAA --> MMX
  SAA --> LJS
  PRJ --> MYSQL
  PRJ --> REDIS
  PRJ --> MQ
  PRJ --> MINIO
  AIGC --> MYSQL
  AIGC --> REDIS
  AIGC --> MQ
  AIGC --> MINIO
  RT --> MYSQL
  RT --> REDIS
  RT --> MQ
  RT --> MINIO
  FEED --> MYSQL
  FEED --> REDIS
  FEED --> MQ
  FEED --> MINIO
  TEL --> MYSQL
  TEL --> REDIS
  TEL --> MQ
  TEL --> MINIO

3.2 部署拓扑（Docker Compose 阶段）

graph LR
  subgraph 宿主机
    subgraph 中间件容器
      nacos["Nacos:8848<br/>(future-state·MVP未部署)"]
      mysql[MySQL:3306]
      redis[Redis:6379]
      rocketmq["RocketMQ:9876<br/>(future-state·MVP未部署)"]
      minio[MinIO:9000]
    end

    subgraph 基础服务容器
      gateway[Gateway:8080]
      system[System:48081]
      infra[Infra:48082]
      bpm[BPM:48083]
    end

    subgraph 业务服务容器
      game_all["game-server:48090<br/>单体模式含全部13个业务模块<br/>(内置 SAA 裸图编排/aigc)"]
    end

    subgraph AI生成接入_现行
      newapi["new-api 网关<br/>(外部·mini-infra:3000)"]
      mmx["mmx-cli<br/>(MiniMax 素材生成)"]
    end

    subgraph 前端容器
      admin_nginx[admin-nginx:80]
      studio_nginx[studio-nginx:81]
    end

    subgraph 可观测性容器
      prometheus[Prometheus:9090]
      grafana[Grafana:3001]
      jaeger[Jaeger:16686]
    end
  end

MVP 阶段单体启动：所有 13 个业务模块编译为同一个 JAR（game-server），通过 Spring Profile 控制模块加载。需要独立扩缩时再启用 Nacos 拆为独立服务（future-state：Nacos 框架自带、MVP 未部署 registry，单体期走本地配置）。

3.3 模块间通信

通信方式	场景	协议
同步 HTTP	前端→Gateway→业务服务	REST JSON
同步 HTTP	aigc→new-api 网关→LLM；SAA 各节点经 OpenAI 兼容接口调模型	REST JSON
进程内调用	aigc 生成派发 GenerationDispatcher（http worker | 进程内 SAA 图，二选一单写）	Java 接口
同步 Feign	服务间同步调用（如 project→system 查用户）	Spring Cloud OpenFeign
异步 MQ（future-state）	生成任务派发、审核通知、事件摄取、结算触发	RocketMQ（框架自带、MVP 未部署 broker；现行走进程内/同步）
事件广播（future-state）	发布成功→feed 刷新缓存、→telemetry 记录	RocketMQ Topic（同上，MVP 未启用）

3.4 平台 Game SDK 设计

为什么需要 SDK

生成的游戏运行在 iframe 沙箱中，与平台隔离。SDK 是平台能力注入游戏的唯一通道——没有 SDK，平台就是一个静态文件托管。

设计原则

原则	含义	约束
极轻	不增加用户感知加载时间	核心模块压缩后 < 8KB
非阻塞	所有 API 调用异步，不占游戏主线程	零同步等待
优雅降级	SDK 任何功能失败，游戏照常运行	try-catch 包裹每个模块
按需加载	非核心模块（广告/社交/支付）懒加载	首屏只加载 core
沙箱安全	通过 postMessage 与宿主通信	不暴露宿主 DOM/Cookie/网络
版本化	SDK 版本与平台版本解耦，向后兼容	semver 管理

SDK 模块分层

┌─────────────────────────────────────────────────────────────┐
│  WanxiangGameSDK（注入到每个生成的游戏中）                      │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Core Layer（内联，< 8KB，游戏启动时加载）                 │ │
│  │  ├── Lifecycle   游戏生命周期管理                          │ │
│  │  ├── EventBus    SDK ↔ 宿主 postMessage 通信             │ │
│  │  ├── Telemetry   事件上报（批量/异步/sendBeacon 兜底）     │ │
│  │  └── ErrorTrack  错误捕获与上报                            │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Plugin Layer（按需懒加载，不影响首屏）                     │ │
│  │  ├── Ad          广告展示（激励视频/插屏/Banner）          │ │
│  │  ├── Pay         内购/打赏触发                             │ │
│  │  ├── Social      排行榜/好友/邀请/分享                    │ │
│  │  ├── Storage     云存档/进度保存                           │ │
│  │  └── Debug       调试面板（仅开发模式）                    │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

各模块能力清单

Core.Lifecycle（生命周期）— 必选，内联

API	说明	触发时机
sdk.ready()	通知宿主游戏初始化完成	游戏入口代码执行后
sdk.started()	通知宿主游戏开始运行	第一帧渲染后
sdk.paused()	通知宿主游戏暂停	用户切后台/广告弹出
sdk.resumed()	通知宿主游戏恢复	广告关闭/回到前台
sdk.completed(result)	通知宿主游戏结束	通关/失败/超时
sdk.error(err)	上报致命错误	游戏崩溃时
sdk.onPause(cb)	监听宿主要求暂停	切换游戏/销毁前
sdk.onResume(cb)	监听宿主要求恢复	回到当前容器

Core.Telemetry（事件上报）— 必选，内联

API	说明	约束
sdk.track(event, data)	上报自定义事件	异步，不返回 Promise
sdk.trackTiming(label, ms)	上报耗时	异步

内置自动上报（无需游戏代码调用）：

• game_load_start / game_load_success / game_load_failed
• game_play_start / game_play_30s / game_complete
• game_error（window.onerror + unhandledrejection）
• game_fps（每 10s 采样平均 FPS）

Core.ErrorTrack（错误捕获）— 必选，内联

能力	说明
全局 onerror 捕获	自动上报 JS 错误
unhandledrejection	自动上报 Promise 异常
错误去重	相同 stack 10s 内只报 1 次
错误不中断游戏	捕获后吞掉，游戏继续运行

Plugin.Ad（广告）— 按需加载

API	说明	触发方式
sdk.ad.showRewarded(opts)	展示激励视频，回调结果	创作者在游戏配置中声明广告点
sdk.ad.showInterstitial()	展示插屏广告	关卡结束/游戏结束时自动触发
sdk.ad.showBanner(position)	展示 Banner	游戏启动时按配置展示
sdk.ad.onReward(cb)	监听激励完成	玩家看完广告后回调
sdk.ad.onClose(cb)	监听广告关闭	广告关闭后恢复游戏

降级策略：广告加载失败 → 跳过广告 → 游戏继续。绝不因广告问题阻断游戏体验。

Plugin.Pay（内购）— 按需加载

API	说明
sdk.pay.purchase(itemId)	发起购买（由宿主弹出支付 UI）
sdk.pay.onSuccess(cb)	支付成功回调
sdk.pay.onCancel(cb)	支付取消回调
sdk.pay.queryOwned(itemId)	查询是否已拥有

Plugin.Social（社交）— 按需加载

API	说明
sdk.social.getLeaderboard(id)	获取排行榜数据
sdk.social.submitScore(id, score)	提交分数
sdk.social.getFriends()	获取好友列表（需授权）
sdk.social.invite(friendId)	邀请好友
sdk.social.share(data)	触发分享（由宿主处理）

Plugin.Storage（云存档）— 按需加载

API	说明
sdk.storage.save(key, data)	保存进度到云端
sdk.storage.load(key)	加载云端进度
sdk.storage.delete(key)	删除存档

Plugin.Debug（调试面板）— 仅开发模式

能力	说明
实时 FPS 曲线	性能监控
事件流日志	SDK 所有事件实时展示
状态变量查看器	GameConfig 运行时状态
trace_id 展示	从生成到运行的全链路追踪 ID
网络请求拦截	监控 SDK 与宿主通信
一键性能快照	导出性能数据

SDK 与宿主通信协议

sequenceDiagram
  participant GAME as 游戏(iframe)
  participant SDK as WanxiangGameSDK
  participant HOST as 宿主(game-studio)
  participant API as 后端 API

  Note over GAME,API: 游戏启动
  HOST->>SDK: postMessage({type:'init', config, trace_id})
  SDK->>SDK: 初始化 Core 模块
  SDK->>GAME: window.WanxiangSDK 可用
  GAME->>SDK: sdk.ready()
  SDK->>HOST: postMessage({type:'lifecycle', event:'ready'})

  Note over GAME,API: 事件上报（异步批量）
  GAME->>SDK: sdk.track('level_complete', {level:1, score:100})
  SDK->>SDK: 加入缓冲队列（每 10 条 or 5s flush）
  SDK->>HOST: postMessage({type:'telemetry', events:[...]})
  HOST->>API: POST /api/telemetry/events/batch

  Note over GAME,API: 广告展示（懒加载）
  GAME->>SDK: sdk.ad.showRewarded({placement:'revive'})
  SDK->>SDK: 首次调用 → 动态加载 Ad Plugin
  SDK->>HOST: postMessage({type:'ad', action:'show_rewarded'})
  HOST->>HOST: 弹出广告覆盖层（iframe 外部渲染）
  HOST->>SDK: postMessage({type:'ad', event:'reward_granted'})
  SDK->>GAME: onReward callback 触发
  GAME->>GAME: 玩家复活，游戏继续

  Note over GAME,API: 广告失败降级
  HOST->>SDK: postMessage({type:'ad', event:'ad_failed'})
  SDK->>GAME: onReward callback({fallback:true})
  GAME->>GAME: 免费给复活（不阻断体验）

关键设计决策

决策	选择	为什么
广告渲染位置	宿主侧（iframe 外部）	广告 SDK 需要网络权限，游戏 iframe 禁止网络
支付 UI	宿主侧弹出	支付安全不能在游戏沙箱内完成
社交数据	宿主代理请求	游戏无网络权限，通过 postMessage 由宿主代理
事件缓冲	SDK 内 10 条/5s flush	减少 postMessage 频率，不影响游戏帧率
错误上报	捕获但不中断	游戏稳定性 > 数据完整性
插件加载	首次 API 调用时懒加载	首屏只需 8KB Core，广告/社交/支付按需

合规定位与降级原则

合规模型：同意即可用，拒绝即不可用。

用户注册/首次进入
  ↓
隐私协议 + 用户服务协议（必须同意）
  ↓
同意 → 进入平台 → SDK Core 全功能默认启用
拒绝 → 不可使用平台

法律基础：《个保法》第13条第(二)款——"为订立、履行合同所必需"。用户接受平台服务即构成合同关系，SDK 采集的数据（生命周期/互动/错误/性能）是提供推荐、质量保障、变现服务的必要数据。

与抖音/微信小游戏同一合规模式：用户不同意则不可玩免费游戏。

非核心能力降级原则（铁律）：

分类	模块	失败时游戏行为	用户感知
核心（异步不阻塞）	Lifecycle / Telemetry / ErrorTrack	上报失败 → 静默丢弃，游戏不受影响	零感知
非核心（失败即跳过）	Ad	广告加载失败/超时 → 跳过广告，给玩家免费奖励	"广告不可用，已赠送奖励"
非核心（失败即跳过）	Pay	支付网络异常 → 提示稍后重试，不阻断游戏	toast 提示
非核心（失败即跳过）	Social	排行榜/好友加载失败 → 展示本地缓存或空态	功能降级但可继续玩
非核心（失败即跳过）	Storage	云存档失败 → 回退 localStorage	下次换设备可能丢失进度

编码铁律：Plugin 层的任何代码都包裹在 try-catch 中，异常不向上抛。游戏主循环（requestAnimationFrame）永远不被 SDK 阻塞。

// SDK Plugin 调用的内部实现模式（伪代码）
async function safePluginCall(fn, fallback) {
  try {
    return await Promise.race([fn(), timeout(5000)])
  } catch (e) {
    sdk._core.telemetry.track('sdk_plugin_error', { module: fn.name, error: e.message })
    return fallback  // 游戏拿到 fallback 值继续运行
  }
}

合规所需的产品侧配套

文件/机制	说明	时机
隐私政策	明确列出 SDK 采集的所有数据类型、用途、保留期限	注册前强制展示
SDK 目录页	列出 WanxiangGameSDK + 第三方 SDK（穿山甲/优量汇/微信支付等）	隐私政策附录
未成年人保护	识别未成年后：禁止广告展示 + 禁止付费 + 限制时长 + 最小采集	实名认证后触发
数据删除权	用户注销时清除关联的事件/画像数据	设置页提供入口

SDK 体积预算

模块	压缩后大小	加载时机
Core（Lifecycle + EventBus + Telemetry + ErrorTrack）	< 8KB	内联到游戏入口
Plugin.Ad	< 5KB（不含广告联盟 SDK）	首次调用 ad API 时
Plugin.Pay	< 3KB	首次调用 pay API 时
Plugin.Social	< 4KB	首次调用 social API 时
Plugin.Storage	< 2KB	首次调用 storage API 时
Plugin.Debug	< 15KB	仅开发模式加载
首屏总负担	< 8KB	—

SDK 与 runtime 模块的关系

runtime-module 编译 GamePackage 时：
1. 将 SDK Core 代码内联到游戏 entry.js 头部
2. 在 GameConfig 中声明需要的 Plugin（ad/pay/social/storage）
3. manifest.json 中记录 SDK 版本号
4. 宿主根据 manifest 决定加载哪些 Plugin chunk

游戏代码不直接引用广告联盟 SDK 或支付 SDK——这些由宿主在 iframe 外部管理。游戏只通过 sdk.ad.showRewarded() 等抽象 API 触发，具体实现对游戏透明。

---

4. 核心链路技术设计

4.1 AI 生成链路

架构决策（现行，2026-06-16）：SAA(Spring AI Alibaba)裸 StateGraph 编排 + new-api 网关 → 便宜 LLM + agent 写码于 LittleJS 插件库 + harness 九门兜底。

✅ 现行主线（C2 裁定 2026-06-09 → HJ-GEN-001 终审 2026-06-12 → HJ-AGI-002 2026-06-15）：

• 生成 = LLM 经 new-api 网关（OpenAI 兼容，多模型）直连便宜模型（DeepSeek-v4 / MiniMax-M2.7/M3）；C2 spike（4 模板 × 13 创意 = 52/52 结构层 100%）证实「LLM 直出 + 固定运行时」可达标，后续 HJ-GEN-001 进一步演进为「agent 写码于插件库」（游戏模板/填参线随 W-CLEAN 退役）。
• 编排基建 = SAA 裸 StateGraph（11 节点 / 4 条件边，SaaStudioGraph.assemble() 唯一布线源），done 由 harness 九门确定性判定、不让 LLM 自评。
• Dify / OpenGame 均从未部署、降级为远期增强；下方"为什么选 Dify + OpenGame"表保留为决策史（蓝图原案），非现行架构。

决策史（蓝图原案，为什么当初选 Dify + OpenGame，不自研）：

维度	自研	Dify + OpenGame（蓝图原案，未落地）
核心生成能力	3-6 个月	2-4 周集成验证
DAG 编排引擎	2-3 个月	Dify 开箱即用
可视化工作流 UI	1-2 个月	Dify 自带
多模型切换	2 周	Dify 原生
质量 benchmark	从零建立	OpenGame-Bench 现成
可观测性	自建	Dify 内置 trace
总周期	6-12 个月	4-6 周

当初为什么不选其他（决策史）：

• LangGraph：纯 Python 框架，无可视化 UI，运营无法参与编排
• Coze：字节闭源，不可控
• n8n：通用自动化，非 LLM 原生

后话：现行 SAA 裸图编排即"Java 进程内确定性多步编排"，避开了对 Dify 可视化 UI 的依赖（可视化编排面属远期能力）；多模型切换由 new-api 网关承担；可观测性由 SAA graph-core 的 observation 机芯（每节点发 Micrometer observation）承担。

生成任务状态机：

stateDiagram-v2
  [*] --> QUEUED: 创建任务
  QUEUED --> RUNNING: 消费消息
  RUNNING --> SUCCEEDED: 生成完成+质量通过
  RUNNING --> FAILED: 生成失败/质量不达标
  RUNNING --> TIMED_OUT: 超时(120s)
  FAILED --> QUEUED: 重试(≤2次)
  TIMED_OUT --> QUEUED: 重试(≤1次)
  SUCCEEDED --> [*]
  FAILED --> [*]: 超过重试次数
  TIMED_OUT --> [*]: 超过重试次数
  QUEUED --> CANCELED: 用户取消
  RUNNING --> CANCELED: 用户取消
  CANCELED --> [*]

性能指标：

• 生成 P50 耗时目标：< 60s
• 生成 P95 耗时目标：< 180s
• 生成成功率目标：≥ 85%（远期蓝图目标；MVP 验收线 ≥80%）
• 队列最大积压：500 任务，超过则返回 429

4.2 游戏运行时链路

三容器策略（参考抖音短视频预加载）：

[Container N-1]  [Container N]  [Container N+1]
  (销毁中)        (当前播放)      (预加载完成)

加载时序：

sequenceDiagram
  participant APP as game-studio
  participant CDN as CDN/OSS
  participant SANDBOX as iframe sandbox

  APP->>CDN: 请求 manifest.json（hash 缓存）
  CDN-->>APP: {entry, assets[], checksum}
  APP->>APP: 校验 manifest 完整性
  APP->>CDN: 并行请求 entry.js + 关键 assets
  APP->>SANDBOX: 创建 iframe（CSP + sandbox）
  APP->>SANDBOX: 注入 GameConfig + Game SDK bridge
  SANDBOX->>SANDBOX: 执行 entry.js → 初始化游戏
  SANDBOX->>APP: postMessage({type:'game_loaded'})
  APP->>APP: 隐藏 loading，展示游戏
  
  Note over APP,SANDBOX: 游玩中：SDK bridge 上报生命周期事件
  
  SANDBOX->>APP: postMessage({type:'game_complete', score})
  APP->>APP: 展示结果页 + 互动按钮

安全边界：

• iframe sandbox="allow-scripts allow-same-origin"
• 红线（2026-06-10 审计补）：allow-same-origin 仅当游戏包部署于独立源（usercontent 子域，与宿主不同源）时方可使用——同源下 iframe 可触宿主 DOM/存储、甚至自移除 sandbox，沙箱铁律失效。独立源就绪前，禁用 allow-same-origin。
• CSP: script-src 'self'; connect-src 'none'（游戏内无网络请求）；CSP 须经游戏包托管侧 HTTP 响应头下发，不以 meta 标签为唯一依赖
• postMessage 来源校验 + schema 校验
• LLM 产物消毒（模板驱动后注入面=配置字符串）：GameConfig 文案字段（title/label/theme 等）入库前做白名单字符集+长度校验，渲染侧一律转义后绘制，禁止 innerHTML/eval
• 资源总大小 ≤ 10MB，首屏 ≤ 2MB

4.3 推荐引擎链路

MVP 推荐策略（规则 + 信号，非机器学习）：

Score = w1*quality_score + w2*freshness + w3*interaction_rate 
        - w4*skip_rate - w5*error_rate - w6*report_rate
        + bonus_new_creator + bonus_featured

信号	来源	权重方向
quality_score	telemetry 模块聚合	正向
freshness	发布时间衰减	正向（24h 内 boost）
interaction_rate	点赞+收藏+分享 / 曝光	正向
skip_rate	3s 内上滑 / 曝光	负向
error_rate	加载失败 / 试玩次数	负向（硬降权）
report_rate	举报数 / 曝光	负向（阈值触发人工审核）
bonus_new_creator	新创作者前 3 个作品	保底曝光
bonus_featured	运营精选池标记	固定加分

候选集生成：Redis Sorted Set，TTL 60s，cursor 分页。

---

5. 数据架构

5.1 核心实体 ER（精简）

erDiagram
  USER ||--o{ GAME_PROJECT : owns
  GAME_PROJECT ||--o{ GAME_VERSION : has
  GAME_VERSION ||--|| GAME_PACKAGE : builds_to
  GAME_VERSION ||--o{ GENERATION_TASK : generated_by
  GAME_VERSION ||--o{ REVIEW_RECORD : reviewed_in
  
  USER ||--o{ INTERACTION : performs
  INTERACTION }o--|| GAME_PROJECT : targets
  
  USER ||--o{ WALLET : has
  WALLET ||--o{ TRANSACTION : records
  
  GAME_PROJECT ||--o{ AD_SLOT : contains
  AD_SLOT ||--o{ AD_IMPRESSION : tracks

  USER {
    string id PK
    string email
    string phone
    string display_name
    string avatar_url
    string[] roles
    datetime created_at
  }

  GAME_PROJECT {
    string id PK
    string owner_id FK
    string title
    string slug
    string status
    string[] tags
    string cover_url
    float quality_score
    datetime published_at
  }

  GAME_VERSION {
    string id PK
    string project_id FK
    int version_number
    string status
    string config_json
    string package_url
    string manifest_url
    datetime created_at
  }

  GENERATION_TASK {
    string id PK
    string version_id FK
    string status
    string prompt
    string template_id
    int retry_count
    int duration_ms
    string error_code
    datetime created_at
  }

  GAME_PACKAGE {
    string id PK
    string version_id FK
    string storage_path
    string checksum_sha256
    int size_bytes
    string manifest_json
    datetime built_at
  }

5.2 存储选型

数据类型	存储	理由
业务实体（用户/项目/版本/订单）	MySQL 8.0	Huijing 原生，事务一致性
游戏包/素材/封面	MinIO(本地) / 阿里云 OSS(生产)	对象存储，CDN 加速
推荐候选集/热数据	Redis 7	低延迟，Sorted Set 排序
事件流（埋点）	MySQL 分区表(MVP) → ClickHouse(增长期)	先简后扩
搜索（游戏/素材）	MySQL FULLTEXT(MVP) → Elasticsearch(增长期)	先简后扩
配置/注册（future-state）	Nacos	Huijing 框架自带，MVP 未部署 registry；现行单体走本地配置/Spring Profile
分布式锁/限流	Redis	高性能

5.3 数据流向总览

graph LR
  STUDIO[game-studio] -->|事件上报| TEL_API[telemetry /events/batch]
  TEL_API -->|异步·future-state| MQ["RocketMQ<br/>(框架自带·MVP未部署)"]
  MQ -->|消费入库| MYSQL[(MySQL 事件表)]
  MYSQL -->|定时聚合| AGG[GameDailyStats]
  AGG -->|写入| REDIS_FEED[Redis 候选集]
  REDIS_FEED -->|读取| FEED[feed-module]
  FEED -->|返回| STUDIO

  AIGC[aigc-module] -->|生成产物| OSS[(MinIO/OSS)]
  OSS -->|CDN分发| CDN[CDN]
  CDN -->|加载| STUDIO

---

6. 技术选型决策记录

6.1 后端框架

候选	选择	理由
Huijing Cloud (Java 17 + Spring Cloud Alibaba)	✅ 选用	60%+ 后台能力开箱即用；RBAC/OAuth2/BPM/文件/通知/审计/代码生成/多租户全覆盖；社区活跃(60k+ star)；fork 二开可控
NestJS (Node.js)	❌ 放弃	v1 已验证单体可行但缺乏企业级基础设施；微服务生态弱于 Java；后台管理/工作流需从零建
Go (Kratos/go-zero)	❌ 放弃	性能好但后台基础设施缺失；RBAC/BPM/代码生成无现成方案

6.2 AI 生成引擎

候选	选择	理由
new-api 网关 → 便宜 LLM + SAA 裸图编排（现行）	✅ 现行	LLM 经 new-api 网关（OpenAI 兼容/多模型）直出可玩游戏，SAA(Spring AI Alibaba v1.1.2.2)裸 StateGraph 编排确定性多步流程，harness 九门兜底质量；后端实测已接入（game-module-aigc-server 14 文件 + spring-ai-alibaba 1 pom），C2 spike 52/52 结构层 100%（HJ-GEN-001 / HJ-AGI-002）
Dify(编排) + OpenGame(生成)	❌ 远期增强（从未部署）	蓝图原案：Dify DAG 可视化/多模型/可观测性，OpenGame SOTA/6 阶段 pipeline；产能/复杂度上台阶时再评估启用，MVP 从不部署
纯自研	❌ 放弃	6-12 个月，时间不允许
LangGraph	❌ 放弃	无可视化 UI，运营无法参与编排
Coze	❌ 放弃	闭源不可控，依赖字节

现行口径（2026-06-16）：MVP 不部署 Dify/OpenGame，生成主线 = new-api 网关 + SAA 裸图编排（详见 §4.1）。Dify+OpenGame 整体降级为远期增强路径，本表保留其行作决策史。AgentScope（agent-native 探索）= long-term premium 独立轨，亦不在 MVP 运行时。

6.3 前端

候选	选择	理由
Vue3 + Element Plus (admin)	✅ 选用	Huijing 官方主推，文档最全，二开友好
Vue3 + Vant (studio)	✅ 选用	移动优先组件库，适配游戏流滑动体验
React + Next.js	❌ 放弃	与 Huijing 前端生态不一致，二开成本高

6.4 数据库

候选	选择	理由
MySQL 8.0	✅ 选用	Huijing 默认，社区方案最多，迁移成本最低
PostgreSQL	❌ 放弃	虽然 JSONB/全文检索更强，但 Huijing 适配成本高

6.5 消息队列

候选	选择	理由
RocketMQ 5	✅ 选用（future-state：框架自带、MVP 未部署 broker）	Huijing 默认集成，延迟消息/事务消息/死信队列完整，适合生成任务调度；MVP 运行时未部署 broker，现行生成派发走进程内 GenerationDispatcher/同步，待产能/异步化需求上台阶时启用
Kafka	❌ 放弃	偏大数据流，运维重，MVP 阶段过度
Redis Stream	❌ 放弃	可靠性不如 RocketMQ，无死信/事务消息

6.6 游戏运行时与多渠道导出

运行时按产物复杂度分层（Tier1/2/3），不同层选不同引擎。

候选	选择	理由
LittleJS 增强发行版 + Runner v2（Tier1：Web 预览/游戏流，现行）	✅ 现行	引擎 55KB gz，URL 化交付享 HTTP+编译双缓存，冷开 0.54s vs 自研壳 2.86s（4.8~5.3×）；agent 写码于插件库直接可运行，装载契约 game-host.d.ts；平台完全控制沙箱/SDK 注入；MVP 唯一交付层（2026-06-12 终裁，spike 85/82）
自研轻量 Canvas Runtime < 15KB（Tier1）	❌ 已废除（2026-06-11/12）	自研壳实为机制演示（资产载而不绘/零 juice/只胜不败），手搓引擎=critical risk；15KB 红线废除（系 srcdoc 内联架构衍生约束，前提失效），改三层约束框架（SLO@千元机+4G P75 / 预算入场券 gz≤350KB·raw≤1.5MB / 工程增强层）
Cocos Creator 3.8.8 + MCP（Tier2/3：复杂 2D+3D / 独立 App）	✅ 选用	一栈覆盖复杂 2D+3D+原生与小游戏导出；MCP（158 工具）可 AI 驱动、出功能快；MVP 仅至多 1 个探针 demo
Three.js	❌ 放弃	仅 web3D，与 Cocos 能力重复（已移除）
Phaser 3 全栈	❌ 放弃（spike 竞标落选）	纯 2D 游戏引擎；经 T1 eval-spike 与 LittleJS 对比，败于冷开/交付形态（工程质量合格，证据留 spike 目录）
LayaAir 全栈（运行时+编辑器+导出）	❌ 放弃	引擎过重影响游戏流加载；无 AI/MCP 生态；官方导出平台清单不含快手（旧"一键导出快手"为事实错误）
Unity	❌ 放弃	AI 适配差、启动重（7-10s），与 P75 < 3s 冲突

分层架构（Tier1 LittleJS 增强发行版 + Runner v2 / Tier2/3 Cocos-MCP）：

AI 生成 → agent 写码于 LittleJS 插件库（Tier1，玩法/美术/关卡/UI=生成域）
  ↓ Web 预览/游戏流
LittleJS 增强发行版（55KB gz）+ Runner v2（iframe sandbox + SDK Core + 装载契约 game-host.d.ts）→ URL 化交付享双缓存
  ↓ 复杂 2D/3D/独立 App（Tier2/3，远期）
Cocos Creator 3.8.8 + MCP → 官方一键导出小游戏包
  ↓ 多渠道导出枢纽 = 微信小游戏格式包
微信=引擎官方格式；抖音=自有导出接口；快手=经"微信格式兼容转换"（快手开发者工具，无专用接口）；Tier1（LittleJS）渠道 adapter 走 W-CH-α 竞标

模板哲学（2026-06-12 W-CLEAN）：游戏模板/填参式模板已废除（W-CLEAN，旧4模板+存量已清）——模板 = LittleJS 能力插件/二次开发件，玩法/美术/关卡/UI 全是 agent 生成域；旧 4 模板（clicker/dodge/runner/match）+ 存量数据已清除。好玩基线 v2 改挂评估门。注：「玩法模板」（品类/玩法框架·引导 AI 生成·非 pre-built 代码）未废 = 有效功能·待建，但非最高优先级（最高=Tier 0 生成可靠，玩法模板排其后；HJ-DEMO-AUDIT-001 创始人 2026-06-17，见完成度与优先级总账）。

为什么分层：

• Web 预览和游戏流需要极快加载（P75 < 3s），Tier1 LittleJS 增强发行版 + Runner v2 满足，MVP 仅交付此层
• 复杂 2D/3D/原生产物（Tier2/3）需成熟引擎，复用 Cocos 而非自研（自研 3D/原生引擎工期数十人月不可行），且 MCP 使 AI 驱动可行
• 导出以微信小游戏格式包为统一中转，可异步离线进行，不影响实时预览体验

6.7 AI 素材生成工具链

环节	工具（现行）	类型	选用理由
图片/贴图/角色/场景	✅ mmx-cli（MiniMax）	商用 CLI	2026-06-12 创始人亲验拍板默认；agent 造游戏直接 CLI 调用，免 GPU/免训练；成本走 new-api 单 key 自动入计费台账
背景音乐/音效	✅ mmx-cli（MiniMax）	商用 CLI	同一套 CLI 出图与出乐，免基础设施；Stability Audio API 降级远期
角色语音/音色克隆	Fish Audio / 阿里 CosyVoice	API+开源	中文效果最佳；Fish Audio 支持 few-shot 音色克隆；CosyVoice 开源可自部署
封面/宣传图	✅ mmx-cli（复用同一 CLI）	商用 CLI	同一套工具，不同 prompt
图片/角色/场景/封面	❌ ComfyUI（退备选）	开源	节点化 workflow、可训 IP 风格 LoRA、自部署无审查；但需 GPU（无 GPU 走 CPU 慢 10x）；mmx-cli 拍板后退为备选

现行口径（2026-06-16）：素材/音乐工具链 = mmx-cli（2026-06-12 创始人亲验拍板）。ComfyUI 退备选、Stability Audio 降级远期。下方"为什么选 ComfyUI"留作备选时的决策史。

为什么 ComfyUI 留作备选（决策史，非现行）：

• ComfyUI 可训练 IP 风格 LoRA，生成风格一致的系列素材（角色/场景/UI）
• 自部署无 API 限制/审查，游戏场景（武器/战斗）不被拒绝
• 长期成本远低于商用 API（GPU 固定成本 vs 按次付费）——但需 GPU 基建，mmx-cli 免 GPU 即用故拍为默认

6.8 内容安全

环节	工具	类型	选用理由
图片 NSFW/涉政/涉暴	safe-content-ai（自部署）+ 阿里云内容安全（兜底）	开源+商用	自部署做首道快检（免费/低延迟），高风险样本二次送阿里云确认
文本违禁/语义	阿里云文本审核	商用 API	违禁词库持续更新，语义理解强于规则匹配
音频内容	阿里云音频审核	商用 API	涉黄涉政语音识别
AI 输出风控	生成链路内置 Guardrails（SAA 节点/Java 壳）	自研规则	Prompt 注入检测 + LLM 输出 schema 校验（原述 Dify 节点，Dify 未部署，现行落在 SAA 编排节点/Java 校验层）

6.9 工具层全景图

graph TB
  subgraph AI生成工具层_现行
    SAA[SAA StateGraph编排<br/>Spring AI Alibaba v1.1.2.2]
    NEWAPI[new-api 网关<br/>OpenAI兼容/多模型]
    LLM[便宜LLM<br/>DeepSeek/MiniMax]
    MMX[mmx-cli<br/>图片/音乐素材·MiniMax]
    VOICE[Fish Audio/CosyVoice<br/>语音/音色]
  end

  subgraph 运行时工具层
    LJS[LittleJS 增强发行版<br/>55KB gz·Tier1 引擎]
    RUNNER[Runner v2<br/>装载契约 game-host.d.ts]
    COCOS["Cocos+MCP<br/>(Tier2/3 渠道导出)"]
    SDK[WanxiangGameSDK<br/>平台能力注入]
  end

  subgraph 安全工具层
    SAFE_IMG[safe-content-ai<br/>图片快检]
    ALI_SEC[阿里云内容安全<br/>兜底确认]
    GUARD[Guardrails<br/>Prompt注入+输出Schema校验]
  end

  subgraph 商业化工具层
    CSJ[穿山甲SDK<br/>字节广告]
    GDT[优量汇SDK<br/>腾讯广告]
    WXPAY[微信支付<br/>Huijing集成]
    ALIPAY[支付宝<br/>Huijing集成]
  end

  subgraph 基础设施工具层
    YUDAO[Huijing Cloud<br/>RBAC/BPM/文件/通知]
    NACOS["Nacos<br/>(future-state·框架自带未部署)"]
    MINIO[MinIO<br/>对象存储]
    JPUSH[极光推送<br/>通知]
  end

  SAA --> NEWAPI
  NEWAPI --> LLM
  SAA --> MMX & VOICE
  SAA --> LJS
  LJS --> RUNNER
  RUNNER --> SDK
  SAFE_IMG --> ALI_SEC

现行口径（2026-06-16）：本图已对齐现行工具链——生成 = SAA 裸图编排 → new-api 网关 → 便宜 LLM，素材 = mmx-cli（ComfyUI/Stability Audio 退备选、降级远期），Tier1 引擎 = LittleJS 增强发行版 + Runner v2（自研 Canvas Runtime/LayaAir CLI 已退役）。详见 §6.2/§6.6/§6.7 决策史。

---

7. 非功能性设计与工程治理

7.1 性能

指标	MVP 目标	正式目标	应对策略
游戏流首屏	P75 < 3s	P75 < 1.5s	CDN + 预加载 + 资源压缩 + HTTP/2
API 平均延迟	P95 < 500ms	P95 < 200ms	Redis 缓存 + 连接池 + 读写分离
生成任务耗时	P50 < 60s	P50 < 30s	SAA 图并行/条件节点 + 模型优化（new-api 多通道）+ 产物缓存（Prompt hash 命中跳 LLM）
并发玩家	1,000 DAU	100,000 DAU	水平扩缩 + 推荐缓存 + CDN 卸载
数据库容量（行数）	单表 < 5000 万行	同左	超过则分区/归档，事件表 → ClickHouse；QPS 目标随首次压测基线另定

性能测试节奏：Phase 3 结束后跑首次压测（wrk/k6），上线前必须通过目标值。

7.2 可靠性与高可用

策略	实现	落地阶段
服务注册/发现	Nacos 集群（3 节点，生产）— future-state，框架自带、MVP 未部署	Phase 4
熔断降级	Sentinel（Huijing 集成），per-API 规则	Phase 1 配置
数据库高可用	MySQL 主从（生产）；MVP 单节点 + 每日备份	上线前
消息可靠	RocketMQ 同步刷盘 + 死信队列 + 延迟消息 — future-state，框架自带、MVP 未部署 broker	Phase 2
生成降级	LLM 不可用 → new-api 多通道切换 + harness 门兜底 + 确定性 Fallback 生成器	Phase 2
游戏加载降级	加载超时 5s → 自动跳过 + 错误记录 + 降权	Phase 3
备份恢复	MySQL: 每日全量 + binlog；OSS: 跨区域复制	Phase 1
回滚	每次部署保留前 3 个版本镜像，5 分钟内可回退	CI/CD 内置

SLO 定义：

服务	SLO	Error Budget（月）
游戏流 API	99.5% 可用	3.6 小时不可用
AI 生成	99%（允许更高失败率）	7.2 小时
支付	99.9%	43 分钟

7.3 幂等性与分布式一致性

幂等性设计

场景	问题	方案
用户重复点击"生成"	重复创建生成任务	前端防抖 + 后端 idempotency_key（Redis 5min 去重）
MQ 重复消费	同一消息处理多次	每条消息携带 message_id，消费前查 Redis 已处理集合
支付回调重复	重复入账	订单状态机 + 乐观锁（version 字段），已完成的订单不可重入
发布重复提交	重复创建审核流程	project_version 唯一约束 + 状态前置校验

分布式事务

原则：尽量避免分布式事务，用最终一致性 + 补偿替代。

场景	涉及模块	方案
生成成功 → 写版本 + 扣积分	aigc → project + pay	本地事务写版本 + MQ 通知扣积分；扣积分失败 → 补偿（标记版本为待支付）
发布审核通过 → 上架 + 刷新 feed	bpm → project + feed	审核通过本地事务写状态 + MQ 广播 feed 刷新缓存
支付成功 → 发货 + 通知	pay → project/ad + community	支付本地事务 + MQ 事件扇出（各模块独立消费）

兜底机制：定时任务扫描"中间态"超 5 分钟的记录 → 重试或告警。

7.4 安全

层面	措施	落地阶段
接入防护	WAF（阿里云/Cloudflare）+ DDoS 高防	上线前
传输	全站 HTTPS + HSTS + TLS 1.3	Phase 1
鉴权	OAuth2 + JWT + Refresh Token 轮换（7天/30天）	Phase 1
权限	RBAC + DataPermission（创作者只看自己的项目/资产）	Phase 1
游戏沙箱	iframe sandbox + CSP + postMessage 来源+Schema 校验	Phase 2
内容安全	Prompt 检测 + 图片检测 + AI 输出校验 + 音频检测	Phase 2
注入防护	Prompt 注入 + SQL 参数化 + XSS 过滤 + SSRF 白名单	Phase 1
密钥管理	Nacos 加密 / K8s Secret（生产）；密钥 90 天轮换	Phase 1
审计	全操作日志 + 180 天保留 + 关键操作实时告警	Phase 1
渗透测试	上线前一次 + 每季度一次	上线前/季度

7.5 可观测性

graph LR
  APP[业务服务] -->|Metrics| PROM[Prometheus]
  APP -->|Traces| JAEGER[Jaeger]
  APP -->|Logs| LOKI[Loki/ELK]
  APP -->|Errors| SENTRY[Sentry]
  PROM --> GRAFANA[Grafana Dashboard]
  JAEGER --> GRAFANA
  LOKI --> GRAFANA
  GRAFANA --> ALERT[告警通道<br/>飞书/钉钉/短信]

日志规范：

规则	说明
格式	JSON 结构化（timestamp / level / trace_id / span_id / module / message / context）
级别	ERROR（需人处理）/ WARN（可能需关注）/ INFO（关键链路）/ DEBUG（开发用）
脱敏	Token/密码/手机号/身份证 → 脱敏后输出（138****1234）
trace_id	Gateway 入口注入，全链路透传（含 SAA 编排节点 observation + new-api 调用）
保留	ERROR/WARN: 90 天；INFO: 30 天；DEBUG: 仅 dev 环境

告警升级链：

级别	条件	通知方式	响应时间
P0 Critical	服务不可用 / 数据丢失 / 安全事件	电话 + 短信 + 群	5 分钟
P1 High	5xx > 2% / 生成成功率 < 70% / 支付异常	短信 + 群	15 分钟
P2 Medium	P95 > 800ms / MQ 积压 > 500 / 错误率上升	群通知	1 小时
P3 Low	非核心模块降级 / 日志异常增长	群通知	工作时间处理

7.6 工程协作与 DevOps

CI/CD Pipeline

graph LR
  DEV[开发推送] --> LINT[代码检查<br/>Checkstyle/ESLint]
  LINT --> TEST[自动化测试<br/>单元+集成]
  TEST --> BUILD[构建镜像<br/>Docker Build]
  BUILD --> SCAN[安全扫描<br/>依赖漏洞/镜像扫描]
  SCAN --> DEPLOY_STG[部署 Staging]
  DEPLOY_STG --> SMOKE[冒烟测试]
  SMOKE --> APPROVE[人工审批<br/>（prod 才需要）]
  APPROVE --> DEPLOY_PROD[滚动部署 Prod]
  DEPLOY_PROD --> VERIFY[健康检查+流量验证]
  VERIFY --> DONE[完成]
  VERIFY -->|失败| ROLLBACK[自动回滚]

工具选型：

• CI：GitHub Actions（或 GitLab CI，根据代码托管平台）
• 镜像仓库：阿里云 ACR / Harbor（自建）
• 部署：Docker Compose（MVP）→ K8s ArgoCD（正式）
• 安全扫描：Trivy（镜像）+ Snyk（依赖）

分支策略

main          ← 始终可部署，保护分支
  └── develop ← 集成分支，CI 通过才能合入
       ├── feature/xxx  ← 功能开发
       ├── fix/xxx      ← Bug 修复
       └── release/x.y  ← 发版分支（冻结后只修 bug）

规则	说明
main 保护	禁止直推，必须 PR + 至少 1 人 review + CI 通过
feature 命名	feature/{module}-{brief}，如 feature/aigc-dify-integration
commit 规范	Conventional Commits（feat:/fix:/chore:/docs:）
PR 大小	单次 < 500 行变更，超过必须拆分

环境管理

环境	用途	数据	部署方式
local	开发者本机	Docker Compose + seed 数据	手动
dev	联调/集成	共享数据库（可随时重置）	push develop 自动部署
staging	预发布验证	生产数据脱敏子集	merge to release 自动部署
prod	线上	真实数据	审批后滚动部署

数据库迁移

工具	Flyway（Java 标准，Huijing 已集成）
文件命名	V{版本号}__{描述}.sql，如 V1.0.0__create_game_project.sql
规则	只新增、不回滚（需回滚则写新迁移补偿）；DDL 和 DML 分开
检查	CI 阶段自动执行 flyway validate，不通过则阻断
大表变更	pt-online-schema-change 或 gh-ost，不锁表

7.7 API 契约与版本管理

API 版本策略

方式	说明
URL Path 版本	/api/v1/feed/list，大版本不兼容时升 v2
向后兼容	新增字段不算 breaking；删除/重命名字段 = 新版本
并行期	新版本上线后，旧版本保留至少 3 个月
废弃通知	Response Header Deprecation: true + Sunset: date

服务间契约

机制	说明
Feign 接口定义	每个模块的 -api 包声明 Feign 接口 + DTO，消费方引用此包
契约测试	Provider 端 Pact 验证 + Consumer 端 Stub 测试（P2，正式阶段引入）
变更通知	API 变更必须在 PR 描述中标注影响的消费方

事件 Schema 演进

规则	说明
版本号	每个事件类型带 schema_version 字段（如 game_play_start.v2）
向后兼容	新增字段给默认值；老版本消费者忽略未知字段
不兼容变更	新事件名（如 game_play_start_v3），老版本并行消费直到下线
Schema Registry	MVP 用文档管理；正式阶段引入 Schema Registry（如 Confluent 兼容方案）

7.8 测试策略

                    ┌─────────────────┐
                    │   E2E 测试       │  少（核心链路 5-10 条）
                    │   Playwright     │
                ┌───┴─────────────────┴───┐
                │      集成测试            │  中（模块间 + 外部依赖）
                │   Testcontainers        │
            ┌───┴─────────────────────────┴───┐
            │          单元测试                 │  多（业务逻辑/工具类）
            │       JUnit 5 + Mockito          │
            └─────────────────────────────────┘

层级	覆盖范围	工具	运行时机	目标覆盖率
单元测试	Service/Util/Validator	JUnit 5 + Mockito	每次 push	核心逻辑 > 80%
集成测试	Controller + DB + MQ + 外部 API	Testcontainers（MySQL/Redis/RocketMQ）	PR merge	核心链路 100%
E2E 测试	前端 → 后端 → DB 全链路	Playwright（前端）+ RestAssured（API）	部署 staging 后	核心 happy path
性能测试	API 吞吐/延迟/并发	k6 / wrk	Phase 3 结束 + 上线前	满足 §7.1 指标
安全测试	OWASP Top 10 / 渗透	ZAP + 人工渗透	上线前 + 季度	无 Critical/High

7.9 灰度发布与 Feature Flag

灰度发布

策略	实现	适用场景
按百分比	Gateway 路由权重（5% → 20% → 50% → 100%）	新版本服务全量前验证
按用户标签	Gateway Header 匹配（内部用户/种子用户/创作者等级）	新功能定向开放
按地域	Gateway IP/地域规则	区域性功能或合规要求
回滚	路由权重调回 0% + 旧版本容器不销毁	发现异常 5 分钟内回退

Feature Flag

工具	本地配置/数据库开关（MVP，Nacos 框架自带未部署，future-state）→ Nacos 配置中心 / Unleash/LaunchDarkly（正式）
用法	代码中 if (featureFlag.isEnabled("new-recommend-algo")) { ... }
管理	admin 后台可开关，无需重新部署
清理	Feature Flag 上线稳定 2 周后必须删除，不留死代码

7.10 扩展性设计

扩展方向	预留机制
新玩法/能力插件	LittleJS 能力插件注册（游戏模板/填参线已废 W-CLEAN，玩法/美术/关卡/UI=agent 生成域）+ Prompt Registry 示例
新 LLM 供应商	new-api 网关多通道（OpenAI 兼容）+ 同模型降级抽检
新广告联盟	AdProvider SPI 接口
新支付渠道	PayChannel SPI 接口（Huijing 原生支持）
新分发渠道	ConversionAdapter SPI 接口；Tier1（LittleJS）渠道 adapter 走 W-CH-α 竞标
单体→微服务（future-state）	Spring Profile 控制模块加载 + Nacos 路由（Nacos 框架自带、MVP 未部署）
MySQL→ClickHouse	事件表 DAO 抽象 + 双写期
SDK 版本升级	manifest 中声明 SDK 版本 + 向后兼容 + 运行时按版本加载
多端适配（小程序壳/APP壳）	SDK + 宿主分离；宿主可替换为微信/抖音小程序容器
Prompt 版本管理	Prompt 即第 8 契约（Git Registry）+ 环境隔离（draft/published）+ 轻量门禁
生成产物缓存	相同 Prompt hash → 缓存命中 → 跳过 LLM 调用（节省成本/加速）

---

8. 关键技术风险与应对

#	风险	概率	影响	应对策略	降级方案
1	LLM 调用不稳定（超时/限流/幻觉）	高	高	new-api 网关多通道切换 + 同模型降级抽检 + SAA 节点重试 + harness 九门兜底	确定性 Fallback 生成器
2	生成游戏质量不可控	高	高	JSON Schema 强校验 + 可玩性自动测试（harness 九门）+ 插件库约束	质量不达标不入库（门未过不出包）
3	游戏沙箱逃逸	低	极高	CSP + sandbox + 无网络 + postMessage 校验	检测到异常立即销毁 iframe
4	OpenGame 社区停更（已 moot：OpenGame 从未部署，降级远期）	—	—	现行生成 = new-api + SAA 裸图编排，无 OpenGame 依赖；本行留作历史	—
5	LLM 网关/编排框架升级不兼容（new-api / SAA）	中	中	锁定 SAA v1.1.2.2（同 minor 补丁前向兼容）+ new-api 自部署可控 + 编排藏在 job/callback 契约后可替换	单写切回 http worker dispatcher
6	广告联盟审核不通过	中	高	提前申请资质 + 内容合规前置	延迟广告上线，先做订阅/B端
7	多模块单体启动内存不足	低	中	8GB+ JVM + 模块懒加载	拆分 2-3 个 JVM
8	MQ 重复消费导致数据不一致	中	高	消息幂等消费（§7.3）	定时任务修复 + 告警
9	分布式事务部分失败	中	高	最终一致性 + 补偿机制（§7.3）	中间态扫描 + 人工介入
10	CI/CD 流水线瘫痪	低	中	多 runner + 镜像缓存	手动部署备案流程
11	第三方 SDK 数据泄露	低	极高	广告/支付 SDK 宿主侧隔离 + 最小权限	紧急下线第三方 SDK
12	LLM 网关单点（new-api）通道批量失效（2026-06 已真实发生：二厂系全废）	中	高	多通道健康巡检 + key 激活状态监控 + 同模型降级抽检（R8）	单通道降级运行 + 批跑冻结阀
13	LLM 成本失控（免费生成被滥刷 / 推理输出吃光配额）	中	高	生成限频限额 + 日预算熔断告警 + 显式 max_tokens	超额暂停生成入口，仅确定性模板兜底
14	监管与上游平台风险（无版号 UGC 定性 / AIGC 标识义务 / 微信抖音下场）	中	极高	非纯技术风险，由合规专项与对外材料承载（HJ-AUDIT-001 R2），本表登记防失踪	自有端收敛邀请制灰度 + 变现走渠道备案通道

---

9. 演进路线

⚠️ 2026-06-10 回填：本章甘特为 2026-06-06 蓝图原案，执行排期以 mvp-execution-spec + MVP作战清单 为准；「Dify + OpenGame Docker 部署」一项已随 C2 裁定取消（模板驱动主线）；验收口径已改内网种子灰度（2026-06-08 业务决策）。

gantt
  title v2.0 实施路线
  dateFormat YYYY-MM-DD
  axisFormat %m/%d

  section Phase 1：基座（2周）
  Fork huijing-cloud + 本地跑通全栈    :p1a, 2026-06-09, 3d
  创建 13 个 game-module 骨架         :p1b, after p1a, 3d
  Dify + OpenGame Docker 部署         :p1c, after p1a, 3d
  game-admin fork + game views 骨架   :p1d, after p1a, 4d
  game-studio 项目初始化              :p1e, after p1a, 3d
  Docker Compose 全栈可启动           :p1f, after p1c, 3d

  section Phase 2：创作链路（3周）
  project 模块 CRUD + 状态机          :p2a, after p1f, 4d
  aigc→Dify→OpenGame 集成验证         :p2b, after p1f, 5d
  runtime 编译+打包+预览交付          :p2c, after p2b, 4d
  studio 创作工作台 UI                :p2d, after p2a, 7d
  生成质量门禁（Schema+可玩性）       :p2e, after p2c, 3d

  section Phase 3：分发链路（3周）
  feed 推荐引擎 + API                 :p3a, after p2e, 5d
  studio 游戏流 UI + 三容器预加载     :p3b, after p3a, 5d
  compliance 内容安全 + 审核(BPM)     :p3c, after p2e, 5d
  telemetry 事件摄取 + 看板           :p3d, after p3a, 5d
  互动（点赞/收藏/分享/举报）         :p3e, after p3b, 3d

  section Phase 4：变现+部署（2周）
  ad 广告位定义 + 联盟 SDK 集成       :p4a, after p3e, 5d
  trade 创作者钱包 + 分成结算         :p4b, after p4a, 4d
  pay 积分充值（微信/支付宝）         :p4c, after p4a, 3d
  deploy 文档 + healthcheck + seed    :p4d, after p4b, 3d
  全链路冒烟测试                      :p4e, after p4d, 2d

  section Phase 5：打磨+上线（1周）
  性能优化（CDN/缓存/预加载）         :p5a, after p4e, 3d
  安全加固 + 渗透测试                 :p5b, after p4e, 3d
  灰度发布 + 种子用户内测             :p5c, after p5a, 4d

总周期：约 11 周（2.5 个月），产出完整 MVP 闭环。

---

10. 成本估算

10.1 基础设施成本（MVP 阶段，月度）

资源	规格	月费估算
云服务器（业务）	4C16G × 2	¥1,200
生成接入服务器（new-api 网关自部署 + 调度）	4C16G × 1（原 Dify+OpenGame，现行 = new-api 网关 + SAA 进程内编排）	¥600
MySQL RDS	2C8G	¥400
Redis	2G	¥200
OSS + CDN	100GB 存储 + 500GB 流量	¥300
LLM API 调用	~10,000 次/月 × ¥0.1	¥1,000
域名 + SSL	—	¥100
监控/备份/冗余	Prometheus/Grafana/Sentry + 备份	¥500
合计		~¥4,300/月（上限 < 5000 元/月，与投资人版核算口径一致）

10.2 团队配置（建议最小）

角色	人数	职责
后端工程师	2	huijing 二开 + 业务模块 + API
前端工程师	1	game-studio + game-admin 二开
AI/生成工程师	1	SAA 裸图编排 + new-api 接入 + 便宜模型/harness 门 + 生成质量
产品/运营	1	PRD + 种子用户 + 审核
合计	5 人

---

11. 附录

11.1 术语表

术语	含义
GameConfig	游戏配置 JSON，描述玩法/关卡/角色/规则
GamePackage	可运行的游戏包（代码 + 资源 + manifest）
DAG / StateGraph	有向无环图/状态图，描述生成工作流节点编排；现行由 SAA(Spring AI Alibaba)裸 StateGraph 承担（11 节点/4 条件边），非 Dify 可视化编排（Dify 未部署）
Game Skill（已退役）	OpenGame 的经验积累机制，类似 few-shot 模板——OpenGame 从未部署、降级远期，本术语仅留作历史，勿作现行依赖
quality_score	基于玩家行为信号聚合的游戏质量评分
Feed	游戏流推荐列表
Manifest	游戏包描述文件（入口/资源列表/hash/大小）

11.2 决策记录索引

决策	文档位置
模块划分（13 个业务模块）	技术架构与模块.md
AI 引擎选型（Dify + OpenGame，已降级远期增强、从未部署）	本文 §6.2
生成主线 = 模板驱动 via new-api 网关 → agent 写码于插件库（MVP 现行）	C2 裁定：docs/agent-specs/2026-06-09-generation-spike/spike-summary.md；HJ-GEN-001 + .agents/skills/cheap-model-game-generation.md
agentic 编排基建 = SAA(Spring AI Alibaba GA v1.1.2.2)裸 StateGraph 编排（HJ-AGI-002，现行；AgentScope 降 long-term premium）	docs/agent-specs/2026-06-15-SAA-* + .agents/skills/saa-graph-orchestration.md + .agents/knowledge/tech-decisions.md §1/§4
Tier1 引擎 = LittleJS 增强发行版（55KB gz）+ Runner v2 装载契约 game-host.d.ts（2026-06-12 终裁，自研 Canvas<15KB 已废除、15KB 红线废除）	docs/agent-specs/_archive/2026-06-11-T1引擎终裁包.md + .agents/knowledge/tech-decisions.md §1.1
模板 = LittleJS 能力插件；游戏模板/填参式模板已废除（W-CLEAN），玩法/美术/关卡/UI=agent 生成域；「玩法模板」（品类/玩法框架·引导 AI 生成·非 pre-built 代码）未废=有效功能·待建，但非最高优先级（最高=Tier 0 生成可靠，玩法模板排其后；HJ-DEMO-AUDIT-001 创始人 2026-06-17，见完成度与优先级总账）	HJ-GEN-001 + .agents/knowledge/tech-decisions.md §1.1
AI 素材/音乐工具链 = mmx-cli（MiniMax，2026-06-12 创始人亲验拍板默认）；ComfyUI 退备选	.agents/knowledge/tech-decisions.md §1（AI 素材工具链行）
代码命名空间 = com.wanxiang.huijing（公司 Wanxiang/项目 Huijing，2026-06-15 合 dev/2.0.0）；对外品牌 = 绘境AI	docs/memorys brand-rename + .agents/knowledge/product-and-architecture.md
RocketMQ / Nacos = future-state（yudao 框架自带依赖+yaml 配置存在，MVP 未部署 broker/registry）	本文 §3.1/§3.3/§5.2/§7.2；.agents/knowledge/tech-decisions.md
LLM 接入（D1：主 DeepSeek/备 Qwen；现行 = new-api 网关多模型，deepseek-v4-flash/pro + MiniMax-M2.7/M3 渠道全活）	docs/agent-specs/_archive/2026-06-08-mvp业务决策.md + .agents/knowledge/tech-decisions.md §3
MVP 模板集（D2：idle/tycoon/merge/clicker —— ⚠️ 游戏模板/填参线(旧4模板)已随 W-CLEAN 废除、存量已清；玩法模板(品类框架)未废待建；模板=LittleJS 插件）	同上 + HJ-AUDIT-001 R4 + W-CLEAN

11.3 后续文档规划

文档	受众	状态
系统概要设计-技术决策版（本文）	CTO/技术合伙人	✅ 完成
系统概要设计-投资人版	投资人/融资	✅ 完成
系统概要设计-开发团队版	工程师	✅ 完成
接口契约文档	前后端工程师	Phase 2 产出
数据库设计文档	后端工程师	Phase 1 产出