games-development-ai/docs/architecture/架构/README.md

topic, canonical, date

topic	canonical	date
架构域总览	true	2026-06-25

架构域 · 设计主文档

这是什么：绘境AI 架构域的设计主文档,回答"这套系统用什么技术、怎么搭起来"(HOW),不重复"产品对用户提供什么"(WHAT——那部分在产品域)。 给谁看:CTO、技术合伙人、首席架构师、新加入的工程师、外部技术尽调。 怎么读:先读本页建立全局的技术认知——分层怎么分、关键选型为什么这么选、13 个后端模块各管什么、它们之间怎么依赖;需要某个子系统的更深细节时,再深入文末的子文档(如生成引擎)。 读这一页 = 当前架构真相。源头有三份很长的设计文档(技术决策版 1500+ 行、技术架构与模块、开发团队版),本页只取它们的架构骨架与关键决策的"为什么";实现级细节、环境搭建、部署命令不在这里(分别交给各子文档与运维域)。

---

1. 一张图看懂整体分层

绘境AI 的后端基于 Huijing Cloud(一套开源的 Java 企业级后台框架,基于 Spring Cloud Alibaba;我们 fork 它做二次开发,下文简称 Huijing)搭建,在它提供的基座能力(用户/权限/工作流/文件等)之上,叠加 13 个游戏业务模块。整套系统自上而下分为六层:用户从浏览器进来,经接入层和网关层,落到业务服务层;业务服务依赖 Huijing 原生的基础设施层,并向上调用一个独立的 AI 生成层来产出游戏;所有这些都坐在中间件层(数据库/缓存/对象存储)之上,由可观测性层旁路监控。

flowchart 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 + Element Plus<br/>运营 + 管理员"]
  end
  subgraph GW["网关层 — 统一入口"]
    GATEWAY["Spring Cloud Gateway<br/>路由 / 限流 / 鉴权 / 灰度"]
  end
  subgraph BIZ["业务服务层 — 13 个游戏业务模块"]
    M["studio · project · aigc · runtime · feed<br/>telemetry · pay · trade · community<br/>ip · compliance · biz · ad"]
  end
  subgraph INFRA["基础设施层 — Huijing 原生开箱即用"]
    SYS["system 用户/权限/OAuth2"]
    INFRASVC["infra 文件/任务/日志"]
    BPM["bpm 工作流"]
  end
  subgraph AI["AI 生成层 — 现行生成主线"]
    SAA["编排框架 → AgentScope(现行收敛)<br/>现存实现 SAA 裸图 · Spring AI Alibaba v1.1.2.2 · 降远期"]
    NEWAPI["new-api 网关<br/>OpenAI 兼容 / 多模型"]
    LLM["便宜 LLM<br/>DeepSeek / MiniMax"]
    LJS["LittleJS + Runner v2<br/>Tier1 引擎 / 插件库"]
  end
  subgraph MW["中间件层 — 数据与存储"]
    MYSQL["MySQL 8.0"]
    REDIS["Redis 7"]
    MINIO["MinIO / 阿里云 OSS"]
    FUTURE["Nacos · RocketMQ · Sentinel<br/>(2026-07-01 反转为 MVP 生产基建 · 接入中)"]
  end
  subgraph OBS["可观测性层 — 旁路监控"]
    OBSV["Prometheus · Grafana<br/>Sentry · Jaeger"]
  end

  NGINX --> STUDIO & ADMIN
  STUDIO & ADMIN --> GATEWAY
  GATEWAY --> BIZ
  BIZ --> INFRA
  BIZ --> AI
  AI --> NEWAPI
  NEWAPI --> LLM
  BIZ --> MW

这套分层有一条贯穿始终的设计取向:先简后扩,能复用就不自研。后端复用 Huijing 现成的 60% 后台能力;生成不自研大模型而是接通用模型;引擎不自研而是用成熟的 LittleJS。系统因此能用很小的团队(建议 5 人)和很低的成本(MVP 基础设施约 ¥4,300/月,上限 < ¥5,000/月)跑起来,同时为后续从单体平滑长成微服务预留好了路径。

---

2. 关键技术决策:每一项的"为什么"

架构里真正值钱的不是组件清单,而是为什么选 A 不选 B。下面把对整体形态影响最大的几项决策讲清楚,每项都给出它击败的候选与理由。这些是经过多轮验证(spike,即小规模技术验证实验)和创始人裁定后落定的现行真相;被推翻的旧方案保留为"决策史",帮助理解演进,但不再是现行架构。

2.1 后端框架 = Huijing Cloud(Java 17 + Spring Cloud Alibaba)

候选	结论	理由
Huijing Cloud	✅ 选用	60%+ 后台能力开箱即用——RBAC(基于角色的访问控制)、OAuth2、BPM(业务流程/工作流引擎)、文件、通知、审计、代码生成、多租户全覆盖;社区活跃(60k+ star);fork 二开可控
NestJS (Node.js)	❌ 放弃	早期原型已验证单体可行,但缺企业级基础设施,后台管理/工作流要从零建
Go (Kratos / go-zero)	❌ 放弃	性能好但后台基础设施缺失,RBAC/BPM/代码生成无现成方案

选 Huijing 的核心算盘:把"做后台基础设施"这件耗时但不差异化的事直接买现成的,把团队的力气全押在生成、流量、变现这三件真正的护城河上。

2.2 生成主线 = AgentScope 三档统一框架(按 AI 参与深度)→ new-api → 便宜 LLM → A-model 写真 src/

这是整个平台演进最剧烈、也最关键的一处决策,值得展开。现行口径(2026-06-25 reframe)是:生成框架收敛到 AgentScope 一套,按 AI 参与深度分 Tier0/1/2 三档(三档全高度模板化:玩法模板 + 工程骨架,不是从零生成),引擎按复杂度选(轻-中 LittleJS、最高 Phaser、非分档轴),生成产物的终态统一是 src/ 多文件源工程(A-model 写真 src/);SAA / Dify / Coze 降到最低优先级、留作「远期适配验证可插拔」目标。下面先把它怎么从蓝图原案一路走过来的决策史讲清。

最初的蓝图原案是 Dify + OpenGame(Dify 是一个带可视化工作流编排界面的 LLM 应用平台;OpenGame 是一套游戏生成 agent),理由是开箱即用、省自研时间。但随后的技术验证推翻了它:

• C2 裁定(2026-06-09):一次 spike 用 4 个模板 × 13 个创意 = 52/52 结构层 100% 通过,证实了"LLM 直连便宜模型直出可玩游戏 + 固定运行时"这条更轻的路就能达标。
• HJ-GEN-001 终审(2026-06-12):进一步把方向定为"agent 写码于插件库"(让模型直接写游戏代码,落在 LittleJS 能力插件库里),把更早的"游戏模板/填参式模板"路线退役(代号 W-CLEAN,即清理旧模板的收口工作:旧 4 模板 clicker/dodge/runner/match + 存量数据已清除)。
• HJ-AGI-002(2026-06-15):把编排基建定为 SAA 裸 StateGraph 编排。SAA = Spring AI Alibaba(阿里巴巴出的 Spring AI 框架,GA 版 v1.1.2.2);StateGraph 是它的状态图编排原语;"裸图"指我们直接用它的状态图节点布线,而不是用它更上层的 ReactAgent 封装。

结果:Dify / OpenGame 均从未部署、降级为远期增强。这套 SAA 裸图编排此后又被一个更大的 reframe 收口:生成框架统一收敛到 AgentScope 三档,SAA / Dify / Coze 一并降到最低优先级、留作「远期适配验证可插拔」目标,不再是现行主轴。后端侧的 SAA 实测痕迹仍在(game-module-aigc-server 有 14 个文件接通 new-api、spring-ai-alibaba 已进 pom 跑起 SaaStudioGraph),作为可插拔编排基建的一个验证实现保留。

flowchart LR
  subgraph 现行["✅ 现行主线(AgentScope 三档统一框架)"]
    A1["创作者 Prompt"] --> A2["AgentScope 框架<br/>按 AI 深度 Tier0/1/2 · 全模板化"]
    A2 --> A3["new-api 网关<br/>OpenAI 兼容 · 多模型"]
    A3 --> A4["便宜 LLM<br/>DeepSeek-v4 / MiniMax-M2.7·M3"]
    A4 --> A5["harness 九门兜底<br/>校验 / 构建 / 真玩"]
    A5 --> A6["A-model 写真 src/<br/>多文件源工程出包"]
  end
  subgraph 低优["⤵ 降最低优先级(远期适配验证可插拔)"]
    C1["SAA 裸 StateGraph"]
    C2["Dify / Coze 编排"]
  end
  subgraph 决策史["❌ 蓝图原案(从未部署 · 已废)"]
    B1["Dify 可视化编排"]
    B2["OpenGame 生成 agent"]
  end

几个术语一句话解释:

• new-api 网关:一个自部署的 LLM 网关,对外提供 OpenAI 兼容接口,对内可挂多个模型通道。它让"换模型/多通道兜底"变成网关层的配置事,业务代码无感;且单 key 自动入 newapi_cost 计费平面,成本可对账。接入时有个工程坑:baseUrl 要剥掉末尾的 /v1。
• harness 九门:生成产物要真正"能玩"才算数,所以在生成链路后端串了九道确定性门(校验 → 构建 → 真玩),done 由这些确定性门判定,不让 LLM 给自己打分。门不过就不出包。
• SAA 图的形状(作为可插拔编排基建的一个验证实现保留):16 个节点 + 7 处条件边,主链是 START → render → classify → design → generate → validate → scaffold → asset → build → play → player/nreview → emit → END,validate / build / play / player 任一不通过则走 repair → generate 回环修复;连续失败到升档窗则 escalate 升 stage2 强档,救场轮耗尽才 giveup(这条 repair → escalate → giveup 就是救场阶梯)。唯一布线源是 SaaStudioGraph.assemble(),生产派发与回归测试共用,避免布线漂移。

这套框架按 AI 参与深度分三档,而不是按基建或品类切成几条互斥的线。Tier0/1 浅-中介入档面向合成 / 挂机 / 答题这类可发行轻游戏,照玩法模板 + 工程骨架生成、用便宜模型把可靠性和可验收性拉满,引擎用 LittleJS;**Tier2 深介入档(富游戏)**让一个自治 ReAct agent 去造多系统富交互(经营 / 合成 / 多系统富游戏),引擎用 Phaser 全无头、靠三层校验当确定性地板加人工终审兜底,产物是真 Phaser src/ 源工程。三档同在 AgentScope 一套框架下、只经公共件交汇,区别只在 AI 介入多深。tier2 的现状要说准:0 号 spike 已过 accept、核心代码已落(验证走 n=5 收敛环:并发跑 5、有错追加 5、收敛即 go),产品化排期待定——不是「待 0 号 spike、尚未落代码」。还有一处终态口径要说准:生成游戏的终态统一是一个 src/ 多文件源工程(结构化、可导航、agent 能定位,创始人 2026-06-20 定调),gameDefinition 已废(判错误路线),现行直接由 A-model 写真 src/,既无 factory/gamedef 双轨、也无 cutover 切换。per-gen 预算硬闸:便宜档每次生成 < ¥10、复杂档 < ¥50(图、音另算)。

演进的更深细节(三档运行时架构、加节点方法、checkpoint 框架坑、观测、dispatcher 契约、tier2 富游戏档详设、A-model 写真 src/)在子文档生成引擎,运行时单一真相 SoT = 生成引擎/agentic运行时架构图说.md。

2.3 游戏运行时引擎按复杂度选(非分档轴)= LittleJS(轻-中)+ Phaser/Pixi(最高复杂度富游戏)+ Cocos(3D / 渠道导出轴)

⚠️ 引擎是按复杂度的实现变体、不是 AI 深度分档轴——三档(Tier0/1/2)是 AI 参与深度,引擎随产物复杂度独立选;详见运行时 SoT 自治富游戏引擎(引擎选型:为什么 Phaser/Pixi、为什么排除 Cocos)。 本节早期按"产物复杂度分层"选引擎(Tier1 = LittleJS / Tier2-3 = Cocos),现已收口为一个正交两轴框架。起因是 tier2 富游戏档要做"AI agent 自治生成富游戏",而自治要求引擎全无头、纯代码 / CLI 可构建、loop 里不挂 GUI 编辑器。据此核实(取证级):Cocos Creator 必须开编辑器才能构建,其"MCP(158 工具)"是连到运行中编辑器的扩展插件、驱动的是 GUI 编辑器而非 headless——所以下表与本节"MCP 可被 / 让 AI 驱动"那几句的 headless 含义是事实错,Cocos 进不了自治 loop。 正确两轴是:① 自治生成引擎(全无头:富 2D = Phaser / Pixi,轻-中复杂度 = LittleJS);② 3D / 渠道导出引擎(Cocos,编辑器 + 人在环,服务复杂 3D / 原生 / 一键渠道导出)。 Phaser 当初"放弃"属轻量轻游戏流的冷启动之败(渠道 / 交付维度),与 tier2 富游戏档的 headless 自治维度正交、不是一把尺;tier2 富 2D 自治据 headless 筛子选 Phaser / Pixi。

运行时按产物复杂度分层,不同层用不同引擎。LittleJS 是一个极小的开源 2D 游戏引擎;"增强发行版"指我们在它基础上叠了能力插件库与装载契约。

候选	结论	理由
LittleJS 增强发行版 + Runner v2(Tier1)	✅ 现行	引擎仅 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	❌ 已废除	自研壳实测只是机制演示(资产载而不绘、零打磨、只能赢不能输),手搓引擎属 critical risk;15KB 红线一并废除——它本是"srcdoc 内联"那套老架构衍生出的约束,前提失效就该废,改为三层约束框架(见下)
Cocos Creator 3.8.8(3D / 渠道导出轴)	✅ 选用,但不进 tier2 自治 loop	一栈覆盖复杂 2D+3D+原生与一键渠道导出;其 MCP 是编辑器扩展、需编辑器在跑、非 headless(见上 supersession 纠错),只服务"编辑器 + 人在环"的 3D / 渠道;MVP 阶段至多 1 个探针 demo
Phaser / Pixi(tier2 富游戏档)✅ · LayaAir / Unity / Three.js ❌	见理由	Phaser、Pixi 纯代码全无头可构建(Phaser 官方 HEADLESS + node),过"全 AI 可做"筛子、生态厚=LLM 好生成 → tier2 富 2D 自治选用;Phaser 的"T1 eval-spike 冷启动落选"只在轻量轻游戏维度、与 tier2 自治维度正交(见上 supersession)。LayaAir 引擎过重且官方导出不含快手;Unity 启动重(7-10s)与 P75<3s 目标冲突;Three.js 仅 web3D 与 Cocos 重复

废掉 15KB 红线后,质量改由三层约束框架守:① 性能 SLO(在千元机 + 4G 网络下的首屏 P75 达标);② 预算入场券(压缩后 gz≤350KB、原始 raw≤1.5MB);③ 工程增强层(juice/手感等)。沙箱、SDK、三容器控制点保持不变。

模板哲学(W-CLEAN):"游戏模板/填参式模板"已废除——模板 = LittleJS 能力插件/二次开发件,玩法/美术/关卡/UI 全是 agent 生成域。需要区分的是,"玩法模板"(指品类/玩法框架,用来引导 AI 生成,而非预制代码)并未废除,它是有效功能、待建,但优先级排在"生成可靠"(Tier 0)之后(HJ-DEMO-AUDIT-001,创始人 2026-06-17)。

为什么按复杂度选:Web 预览和游戏流要求极快加载(P75<3s),轻-中复杂度的 LittleJS 正好满足,所以 MVP 的轻量轻游戏交付这一层;复杂 3D/原生需要成熟引擎,复用 Cocos 而非自研(自研 3D/原生引擎工期数十人月不可行),但其 MCP 经编辑器驱动、非 headless,故 Cocos 走"编辑器 + 人在环"模式、不进 tier2 自治 loop;tier2 富游戏档的富 2D 自治生成用 Phaser/Pixi 全无头引擎(见本节 supersession 横幅);多渠道导出以微信小游戏格式包为统一中转,可异步离线进行,不影响实时预览。

2.4 AI 素材工具链 = mmx-cli(MiniMax)

游戏要图、要音乐、要封面。这一链路现行统一走 mmx-cli(MiniMax 的命令行工具,2026-06-12 创始人亲验拍板默认):agent 造游戏时直接 CLI 调用,免 GPU、免训练,成本随 new-api 单 key 自动入计费台账。原候选 ComfyUI(开源、可训 IP 风格 LoRA、自部署无审查,但需 GPU,无 GPU 走 CPU 慢 10 倍)退为备选;Stability Audio 等降级远期。语音/音色克隆备选 Fish Audio / 阿里 CosyVoice(中文效果好)。

2.5 其余基线选型(简表)

维度	选型	一句话理由
前端 admin	Vue3 + Element Plus	Huijing 官方主推,二开友好
前端 studio	Vue3 + Vant	移动优先组件库,适配游戏流滑动
数据库	MySQL 8.0	Huijing 默认,社区方案最多,迁移成本最低
对象存储	MinIO(本地)/ 阿里云 OSS(生产)	对象存储 + CDN 加速,放游戏包/素材/封面
缓存/热数据	Redis 7	低延迟,Sorted Set 适合推荐候选集排序
消息队列	RocketMQ 5(MVP 生产基建)	Huijing 默认集成,延迟/事务消息完整;2026-07-01 反转为异步 gen 队列(自托管 mini-infra,生产者 + 有界消费 ≤15 + CAS 幂等已落,见 git)
配置/注册	Nacos(MVP 生产基建)	Huijing 框架自带;2026-07-01 反转为配置中心 + 服务发现(gen-worker 已接热参 watcher、AgentScope Service 已注册进 discovery,见 git)

关于 Nacos / RocketMQ / Sentinel(2026-07-01 反转为 MVP 生产基建):这三件原是 Huijing(yudao fork)框架自带依赖,一度按 future-state 搁置;2026-07-01 build-vs-buy 现货尽调后反转为 MVP 生产 runtime,自托管在 mini-infra——Nacos 配置中心 + 服务发现、RocketMQ 异步 gen 队列、Sentinel 准入侧流控。接入实现进行中(gen-worker 已接 Nacos 热参 watcher 与服务注册、game-cloud 已上 RocketMQ 有界消费队列,见 git 与配置控制面设计)。读设计时凡涉"异步 MQ""服务注册发现""准入流控",按已采纳的这三件理解,不再按 MVP 阶段"进程内调用 / 本地配置"折算。

---

3. 13 个后端业务模块总览

业务能力按领域边界切成 13 个模块,高内聚、低耦合。它们物理上以 jar 聚合进 Huijing 单体一起运行(MVP 单体启动:所有模块编译进同一个 JAR game-server,用 Spring Profile 控制加载),逻辑上各自独立、可被未来拆分。每个模块有一个三字母前缀,技术功能用 T-{模块}-{nn} 编号(共 204 项技术功能,作为结构权威的注册表)。

flowchart TB
  subgraph 创作["创作链路"]
    STU["studio · 创作编排/编辑器域"]
    AGC["aigc · 无状态生成原子"]
    RT["runtime · 编译/沙箱/多渠道发布"]
    PRJ["project · 项目生命周期 + 专区 Zone"]
  end
  subgraph 分发["分发与数据"]
    FED["feed · 游戏流推荐/互动/分享"]
    TEL["telemetry · 事件摄取/聚合/质量评分"]
  end
  subgraph 变现["变现链路"]
    PAY["pay · 支付收单/订单/退款对账"]
    TRD["trade · 分账/结算/钱包/财税"]
    AD["ad · 广告联盟/植入/曝光计费/归因"]
  end
  subgraph 生态["平台与合规"]
    CMU["community · 社交/互动/排行/通知"]
    IP["ip · 素材安全/授权链/IP 风格原子"]
    CMP["compliance · 内容安全/审核/锁风门/RBAC"]
    BIZ["biz · B/G 端定制工程底座"]
  end

模块	前缀	一句话职责	建设形态(2026-06-10 审计)
studio	STU	把"创作会话"编排成可试玩草稿:调度 aigc 原子、装配多资产、管理角色 rig / 对白树 / 任务链	★新增
aigc	AGC	单 Prompt → 单确定性产物(GameConfig/图/音/剧情/封面/校验/风格指纹),无状态、幂等、可重放	收敛
runtime	RT	GameConfig → 版本化可运行包,沙箱预览,多渠道转换与发布状态机	扩
project	PRJ	项目/版本/草稿全生命周期与状态流转,编排发布,承载专区 Zone 实体	扩
feed	FED	已发布游戏按规则推荐成竖屏游戏流,回收互动信号,分享外链,按 Zone 分区	扩
telemetry	TEL	统一摄取全链路事件,治理 Schema、增量聚合、算 quality_score、产出监控告警	—
pay	PAY	把各类付费统一收单为可追溯、可对账、可幂等的支付订单	huijing 原生(未接入单体)
trade	TRD	把多源收入按规则分账、归集、结算、对账并出财税报表	—
community	CMU	社交关系、互动计数、排行/成就、全渠道通知投递	未建(Wave4)
ip	IP	为素材/IP 资产提供安全可信、授权可溯、风格可校的底座原子,按 Zone 双轨归类	seam 寄宿 compliance
compliance	CMP	内容安全与审核中枢 + 锁风门裁决,并承载 RBAC/审计/加密/安全基线/防沉迷	扩
biz	BIZ	为 B/G 端定制提供报价、BPM 编排、签章、CRM、交付验收状态机	未建(Wave4)
ad	AD	把联盟接入、广告位 AI 植入、曝光计费、eCPM 优化与归因做成游戏内广告后端	—

几个跨模块的关键概念:

• 专区 Zone:运营用的双轨分区(授权 IP 区 / UGC 用户原创区),owner 是 project;feed 据它分区推荐,ip 据它双轨归类。UGC = User Generated Content,用户生成内容。
• 锁风门 Gate(T-CMP-12):一道"风格-版权一致性"门,owner 是 compliance。它聚合 aigc 的风格检测原子(T-AGC-19)和 ip 的 IP 风格校验原子(T-IP-04),裁决 pass / review / block,挂在 project 的发布前检查(T-PRJ-05)上。"锁风"= 锁定风格、防侵权。

各模块卡片(职责 IN/OUT 边界、技术功能 T-id 清单)与重划状态详见 docs/architecture/架构/13模块.md;真/桩/未建的实时状态以 docs/mvp/MVP进度总账.md 为准。冲突时口径:状态 > 实现 > 结构。

---

4. 模块依赖:为什么是这个方向

模块间是单向、低耦合的依赖,只经各模块的 -api 包(声明 DTO + Feign 接口)交互。下图是依赖方向(箭头 A→B 表示 A 依赖 B):

graph LR
  STU[studio] --> AGC[aigc]
  STU --> RT[runtime]
  STU --> IP[ip]
  STU --> PRJ[project]
  STU --> CMP[compliance]
  AGC --> CMP
  AGC --> PRJ
  RT --> PRJ
  RT --> TEL[telemetry]
  FED[feed] --> PRJ
  FED --> TEL
  TEL --> FED
  IP --> CMP
  IP --> TRD[trade]
  CMP --> AGC
  CMP --> IP
  PRJ --> CMP
  TRD --> PAY[pay]
  TRD --> AD[ad]
  AD --> RT
  BIZ[biz] --> PRJ
  BIZ --> AGC
  BIZ --> TRD
  CMU[community] --> PRJ

读这张图有几条主线:创作侧 studio 站在最上游,把活分派给 aigc(生成)、runtime(编译)、ip(素材)、project(落库)、compliance(安全);生成原子 aigc 只向下依赖 compliance(Prompt 安全)和 project(写结果),自己保持无状态;数据回路 telemetry 与 feed 互相依赖(feed 消费质量信号、telemetry 回收互动),形成"越用越聪明"的闭环;资金侧 trade 向下依赖 pay(收单)和 ad(广告收入),自己只管分账结算。这种单向切分让任何一个模块都能独立演进、独立测试,也是未来从单体拆成微服务时的天然切割线。

---

5. 一条生成请求是怎么跑通的

把上面的分层、生成主线、模块依赖串起来,看一次"一句话生成游戏"的完整时序——这是创作链路的核心路径。注意生成任务的派发走 GenerationDispatcher(http worker 与进程内 SAA 图二选一、单写),生成态 SAA 编排藏在 job/callback 契约后,保持可替换。

sequenceDiagram
  participant C as 创作者
  participant S as game-studio
  participant GW as Gateway
  participant AIGC as aigc 模块
  participant SAA as SAA StateGraph 编排
  participant NEWAPI as new-api 网关
  participant LLM as 便宜 LLM
  participant GATE as harness 九门
  participant PRJ as project 模块

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

  AIGC->>SAA: dispatch(job) 进入裸图编排
  SAA->>SAA: 节点:render→classify→design→generate(16 节点/7 条件边)
  SAA->>NEWAPI: 各节点经 OpenAI 兼容接口调模型
  NEWAPI->>LLM: 转发(单 key → 自动入 newapi_cost 计费)
  LLM-->>NEWAPI: 返回 GameConfig / 游戏代码
  NEWAPI-->>SAA: 模型产物
  SAA->>GATE: 校验/构建/真玩九门(done 由确定性门定)
  GATE-->>SAA: 通过 → 出 GamePackage;不通过 → 修复回环
  SAA-->>AIGC: 回调 callback:packageUrl + manifest
  AIGC->>PRJ: 写入草稿版本
  AIGC-->>S: 任务完成通知

生成任务本身是一个有明确状态机的对象,它给"超时/失败/重试/取消"都定义了清楚的边——这是任何涉及外部模型调用的链路都必须考虑的可靠性设计:

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

生成性能与质量的硬指标:生成 P50 < 60s、P95 < 180s,生成成功率 ≥ 80%(MVP 验收线;远期蓝图目标 ≥85%),队列最大积压 500 任务、超过返回 429。

---

6. 游戏怎么安全地跑在玩家面前

生成出来的游戏运行在 iframe 沙箱(浏览器内嵌的隔离框架)里,与平台彻底隔离。平台能力靠 WanxiangGameSDK 注入进去——这是平台向游戏注入能力的唯一通道,没有它平台就只是个静态文件托管。SDK 分两层:Core 层(生命周期/事件总线/遥测/错误捕获)内联进游戏入口、压缩后 < 8KB;Plugin 层(广告/支付/社交/云存档/调试)按需懒加载,首屏不付出代价。

加载用三容器策略(参考抖音短视频预加载):当前播放的容器之外,前一个在销毁、后一个已预加载完成,上滑切换时无缝衔接。

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'})
  Note over APP,SANDBOX: 游玩中:SDK bridge 上报生命周期事件
  SANDBOX->>APP: postMessage({type:'game_complete', score})

安全边界是几条不能破的红线:

• 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 标签。
• LLM 产物消毒:GameConfig 的文案字段(title/label/theme 等)入库前做白名单字符集 + 长度校验,渲染侧一律转义后绘制,禁止 innerHTML/eval。
• 资源总大小 ≤ 10MB、首屏 ≤ 2MB;postMessage 必须校验来源 + schema。

底线原则:创作者通过配置(不是写代码)驱动游戏行为,平台对运行时代码拥有完全控制权——这是安全与合规可控的根。

运行时打包、沙箱、SDK 分层、多渠道导出的完整手册见运维域与 .agents/skills/runtime-and-multichannel.md;广告/支付/社交各 Plugin 的降级铁律("失败即跳过、绝不阻断游戏")见技术决策版 §3.4。

---

7. 推荐引擎:让好游戏被刷到

MVP 阶段的推荐是规则 + 信号,不上机器学习(那是增长期的事)。每款游戏的曝光排序由一个打分公式决定,正向信号(质量分/新鲜度/互动率)加分,负向信号(跳过率/错误率/举报率)减分,再叠加新创作者保底与运营精选加分:

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

其中 error_rate(加载失败/试玩次数)是硬降权——技术上跑不动的游戏直接沉底;report_rate 超阈值会触发人工审核。候选集存在 Redis Sorted Set,TTL 60s,用 cursor 分页(MVP 也可直查 MySQL,Redis 缓存是增长期形态)。这条设计让"质量好 + 玩家爱玩"的游戏自然浮上来,数据回流又持续校准推荐——这正是平台"越用越聪明"的来源。

---

8. 数据怎么存、怎么流

核心实体围绕"用户拥有项目、项目有版本、版本编译成包、版本由生成任务产出"这条主线展开:

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

存储选型遵循"先简后扩":业务实体进 MySQL(事务一致性),游戏包/素材/封面进 MinIO/OSS(对象存储 + CDN),推荐热数据进 Redis;事件流 MVP 用 MySQL 分区表、增长期迁 ClickHouse,搜索 MVP 用 MySQL FULLTEXT、增长期迁 Elasticsearch。数据流向上,埋点事件经 telemetry 入库、定时聚合成 GameDailyStats、写入 Redis 候选集供 feed 读取;生成产物落 OSS 经 CDN 分发给前端。

---

9. 工程治理:把可靠性和质量钉死

这套系统涉及外部模型、异步任务、支付,所以可靠性不是事后补的,而是设计进去的。下面是几条贯穿的硬约束。

幂等性:用户重复点"生成"用 idempotency_key(Redis 5 分钟去重);支付回调重复靠订单状态机 + 乐观锁;发布重复提交靠 project_version 唯一约束。分布式一致性:原则是尽量避免分布式事务,改用最终一致性 + 补偿,并用定时任务扫描"中间态超 5 分钟"的记录来兜底。

SLO(服务等级目标)与可用性:

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

整体可用性目标 ≥99.5%(MVP)/ ≥99.9%(正式)。性能目标:游戏流首屏 P75<3s(正式 P75<1.5s)、API P95<500ms、并发从 1,000 DAU 起步水平扩到 100,000 DAU。可观测性:业务服务把 Metrics/Traces/Logs/Errors 分别送 Prometheus/Jaeger/Loki/Sentry,汇到 Grafana 看板与告警;日志 JSON 结构化、Token/手机号脱敏、trace_id 从 Gateway 入口全链路透传(含 SAA 编排节点 observation + new-api 调用)。

关键技术风险里有几条已经真实发生或影响重大,值得单列:

• LLM 网关单点通道批量失效(2026-06 已真实发生:二厂系全废)——应对是多通道健康巡检 + key 激活状态监控 + 同模型降级抽检 + 批跑冻结阀。
• LLM 成本失控(免费生成被滥刷 / 推理输出吃光配额)——应对是生成限频限额 + 日预算熔断告警 + 显式 max_tokens,超额则暂停生成入口、仅确定性模板兜底。
• 监管与上游平台风险(无版号 UGC 定性 / AIGC 标识义务 / 微信抖音下场)——这是非纯技术风险,由合规专项与对外材料承载,登记在此防失踪。

完整的幂等矩阵、分布式事务补偿表、安全分层、CI/CD、测试金字塔、灰度与 Feature Flag、扩展性 SPI 接口见技术决策版 §7;安全与可靠性的硬约束基线见 .agents/rules/security-and-reliability.md。

---

10. 子文档导航

本页是架构域的入口与骨架。更深的子系统现行架构在下列子文档,需要细节时再深入:

文档	回答什么
生成引擎 🚧	架构演进中 —— 生成收敛 AgentScope 三档(按 AI 深度·全模板化),gameDefinition 已废(错误路线),现行 = A-model 写真 src/;tier2 富游戏档 0 号 spike 已 accept、核心已落(产品化排期待定)。生成主线的深层架构:三档运行时拓扑、加节点方法、new-api 接入、checkpoint 框架坑、dispatcher 契约、九门 harness。运行时架构单一真相 SoT 见 生成引擎/agentic运行时架构图说.md
产物执行沙箱	生成出来的游戏(不可信代码)怎么在浏览器里被隔离着安全跑:取包 / sha256 校验 / iframe+CSP 隔离 / postMessage 双校验 / SDK 受控面;沙箱与"插件↔引擎"受控面是两条正交边界
契约总览	全部契约族的导航与口径收口:有哪几类、各落哪、各算第几、怎么镜像同步到代码、防漂移门有没有
前端域	game-studio / game-admin 的前端设计体系、组件分层、SDK 源码组织、运行时容器
后端域	后端模块的实现级设计、API 路径规范、错误码分配、Flyway 迁移、契约对齐
运维域	环境/部署/staging 运维、构建门、smoke 门、运行时打包与多渠道导出手册

控制面 / 管理面:把三档生成(统一在 AgentScope 框架下,tier2 富游戏档 0 号 spike 已 accept、核心已落)配置、观测、审计、管起来的治理层(配置注册表 + 观测审计仓 + D12 治理门 + 管理面 UI),设计见运行时 SoT 生成引擎/agentic运行时架构图说.md(§5.2 控制面与配置热取 / §一 反锁死五件)。

纪律:架构域只讲"系统怎么搭、关键决策为什么";产品对用户提供什么在产品域,哪条产品需求由哪些技术模块实现在需求模块映射。各域各司其职、互不重复。

源头长文档(需要逐条考据时回溯):系统概要设计-技术决策版.md(HJ-ARCH-001,架构全貌与决策记录)、技术架构与模块.md(HJ-TECH-002,13 模块 T-id 注册表)、系统概要设计-开发团队版.md(HJ-ARCH-003,日常参考手册,注意其环境/命令段为 target-state、与现实有出入,以 .agents/rules + docs/mvp/MVP进度总账.md 为准)。现行口径的日常入口 = .agents/knowledge/tech-decisions.md + .agents/skills/saa-graph-orchestration.md。