From 8e7ace3ec36bcf8f7db1f8f54d43a9534a516c40 Mon Sep 17 00:00:00 2001 From: zizi Date: Tue, 16 Jun 2026 12:24:46 +0000 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E6=A0=B8=E5=BF=83?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=A1=A3=E5=85=A8=E7=BA=BF=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=E7=8E=B0=E8=A1=8C=E7=9C=9F=E7=9B=B8=EF=BC=88=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E5=86=B3=E7=AD=96=E7=89=88/=E5=BC=80=E5=8F=91=E5=9B=A2?= =?UTF-8?q?=E9=98=9F=E7=89=88/=E6=8A=95=E8=B5=84=E4=BA=BA=E7=89=88/?= =?UTF-8?q?=E6=8A=A4=E5=9F=8E=E6=B2=B3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 承接核心设计文档真相对齐，创始人批『全部核心档一起对齐』。废弃选型(Dify/OpenGame/自研Canvas/ComfyUI/AgentScope)曾被当现行架构详述，新接手照信即落废栈。 技术决策版(架构基线 1528→1562)：4 张 Mermaid 重画(DIFY/OG/COMFY/CANVAS_RT→new-api/SAA/mmx/LittleJS)+3 选型表翻面+删虚构字段 dify_workflow_id+MQ/Nacos 标 future-state(框架自带·MVP未部署)+顶部横幅升 v2.1+决策索引补 6 行。 开发团队版(13处)/投资人版(8处)/护城河(5处)：事实性技术栈改现行，工程目标态细节+护城河论述/愿景保留；Doc B 那处 AgentScope 已是『作废→SAA』现行标注。事实核查据 contracts/+game-cloud 实测。Mermaid 结构校验通过未真渲染→建议 mini-desktop 终确认。待定夺=成本或高估(¥4,300按纪律未改)。 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-06-16-技术决策版重写-review.md | 21 +- docs/architecture/护城河对外话术-双版本.md | 10 +- docs/architecture/系统概要设计-开发团队版.md | 151 +++++------ docs/architecture/系统概要设计-技术决策版.md | 243 ++++++++++-------- docs/architecture/系统概要设计-投资人版.md | 25 +- 5 files changed, 252 insertions(+), 198 deletions(-) diff --git a/docs/agent-specs/2026-06-16-技术决策版重写-review.md b/docs/agent-specs/2026-06-16-技术决策版重写-review.md index b8bd6f96..84aebd1f 100644 --- a/docs/agent-specs/2026-06-16-技术决策版重写-review.md +++ b/docs/agent-specs/2026-06-16-技术决策版重写-review.md @@ -1,6 +1,6 @@ # 技术决策版重写 — 计划（评审版） -> 状态: PLAN（待创始人批准后执行；**未动正文**） · 更新: 2026-06-16 +> 状态: **已执行**（2026-06-16，创始人批"全部核心档对齐"：技术决策版/开发团队版/投资人版/护城河话术 4 档已对齐；Doc B 那处 AgentScope 已是"作废→SAA"现行标注无需改） · 更新: 2026-06-16 > 目标档：`docs/architecture/系统概要设计-技术决策版.md`（AGENTS §4 必读·**架构基线**，1527 行） > 由来：2026-06-16 目录治理追问"哪些核心设计档需重写"——审计实测此档 96 处废弃选型词 vs 11 处现行词，是唯一真·过期权威基线（详见 [`2026-06-16-agent-specs目录治理-review.md`](2026-06-16-agent-specs目录治理-review.md)）。 @@ -47,8 +47,19 @@ 2. 主代理负责：事实核查（MQ/Nacos/字段名据 contracts 核实）+ Mermaid 渲染校验 + 终审。 3. 同步评估其它核心档：**开发团队版（48 处废弃词）**——是逐节改写还是强化其"别信、看 .agents"降级横幅；Doc B（1 处 AgentScope）顺手改。 -## 待你确认 +## 待你确认（已答复：全部核心档一起对齐 ✓ 已执行） -1. 批准"**逐节改写、不降级**"方向？ -2. 重写范围：**只技术决策版**，还是**连带开发团队版**（48 处）一起做？ -3. 投资人版/护城河话术的旧选型表述：保留为愿景 / 一并对齐？ +1. ~~批准"逐节改写、不降级"方向？~~ → 已批准并执行。 +2. ~~范围~~ → 全部核心档（技术决策版/开发团队版/投资人版/护城河话术）已对齐。 +3. ~~投资人版/护城河~~ → 已对齐：事实性技术栈改现行，护城河论述/愿景保留。 + +## 执行后 · 待创始人定夺（R3 投资人向 flag，均不影响已对齐的技术口径，纯商业指标） + +1. **月成本可能高估**：现行**无独立自建 AI 推理/GPU 机**（生成走 new-api 外部 API、SAA 进程内跑后端 JVM、美术走 mmx-cli 外部）——投资人版 §7.1 服务器档位/月成本实际可能 **< ¥4,300**。按纪律**未改总额**，是否下修？ +2. **LLM 单次成本**：W-G1 实测便宜模型 **¥0.01–0.03/款**（经 new-api）< BP 假设的 ¥0.05–0.1，是否下修以强化资本效率叙事？ +3. **mmx-cli quota**：已替代 ComfyUI 进入美术/音乐线，是否在对外成本表单列一行 mmx API 费（创始人已要求"盯用量=quota 对账入成本台账"）？ + +## 验证留痕（2026-06-16） + +- 技术决策版：54 围栏(偶)、18 Mermaid、旧节点 ID(OPENGAME/CANVAS_RT/COMFY) 残留 **0**、`dify_workflow_id` **0**、`participant DIFY` **0**；MQ/Nacos 25 处保留并标 future-state。 +- 4 张 Mermaid 经**结构校验**（围栏平衡+标签引号+零旧节点 ID）通过；**未在本机真渲染**（chrome/mmdc 受限）→ 建议 mini-desktop 或浏览器扫一眼 4 图终确认。 diff --git a/docs/architecture/护城河对外话术-双版本.md b/docs/architecture/护城河对外话术-双版本.md index d9fe993c..20681726 100644 --- a/docs/architecture/护城河对外话术-双版本.md +++ b/docs/architecture/护城河对外话术-双版本.md @@ -65,11 +65,11 @@ | BP 术语 | DD 桌上的诚实口径 | |---|---| -| IP 专属定向微调垂类模型 | "通用 LLM 做底座，为每个 IP 训练**画风 LoRA**（ComfyUI/Flux/SDXL）保证系列一致。**没有自训垂类大模型。**" | +| IP 专属定向微调垂类模型 | "通用 LLM 做底座，美术现行经 **mmx-cli（MiniMax）** 出系列一致素材（按需可叠 IP 画风 LoRA，ComfyUI/Flux/SDXL 为备选路径）。**没有自训垂类大模型。**" | | 四层画风锁风校验算法 | "风格指纹嵌入比对 + 阈值门 + 三档人审（标准/严格/人工）。**不是高深算法**，是让非独家 IP 能安全规模化使用的工程 + 合规流程。" | | 轻量化 H5 游戏引擎 | "轻量 H5 运行时——自研的是**宿主控制层**（Runner + iframe 沙箱 + SDK 注入），渲染引擎层用成熟开源轻引擎（可替换），保 P75<3s 首屏与平台控制点；复杂 2D/3D 用 Cocos。**不自研引擎。**" | | 全域一键分发调度系统 | "以微信小游戏格式包为枢纽的多渠道转换 + 渠道适配规则库 + 发布状态机。**快手经格式转换 + 真机验证，不是全自动。**" | -| AI + 人工双层风控 | "机审（自部署快检 + 阿里云内容安全 + Dify Guardrails）+ 人审队列（BPM）。行业合规标配，我们做扎实了。" | +| AI + 人工双层风控 | "机审（自部署快检 + 阿里云内容安全 + Prompt 注入检测/输出 schema 校验）+ 人审队列（BPM）。行业合规标配，我们做扎实了。" | | 流量双轨推荐算法 | "MVP 是**规则线性加权打分** + 授权IP/UGC 双区分区运营；千人千面 ML 是数据积累后的增长期演进。" | ### B2. 四条红线措辞（尽调前全网改口） @@ -83,13 +83,13 @@ ### B3. 自研边界（清楚地讲"自研什么、不自研什么"） - **自研（必须自掌——控制点 + 数据入口）**：运行时宿主层（Runner + iframe 沙箱 + SDK 注入；渲染引擎为可替换的开源轻引擎，不自研）、feed 推荐、telemetry 数据底座、变现链路（钱包/分账/广告位）。 -- **不自研（省 6-12 月 + 千万级，且可替换无锁定）**：大模型、生成 Agent（OpenGame）、编排（Dify）、后台（Huijing）、素材生成（ComfyUI）、内容安全（阿里云）、复杂引擎（Cocos，远期）。 +- **不自研（省 6-12 月 + 千万级，且可替换无锁定）**：大模型、多模型网关（new-api，接通用 LLM）、后台（Huijing）、素材生成（mmx-cli；ComfyUI 备选）、内容安全（阿里云）、复杂引擎（Cocos，远期）；编排用 SAA（Spring AI Alibaba）裸图、轻引擎用 LittleJS（均开源、可替换）。生成 Agent（OpenGame）/可视化编排（Dify）列为远期增强、当前不部署。 ### B4. CTO 会戳的三个点 + 怎么答 | CTO 戳 | 怎么答 | |---|---| -| "这六项不就是 Dify+ComfyUI+Huijing+阿里云拼的吗？" | "对，而且是刻意的。自研这些要 6-12 月烧千万，我们 4-6 周集成，省下的全投在竞品没有的 feed/变现/SDK 上。自研边界很清楚（见 B3）。" | +| "这六项不就是网关+开源框架+阿里云拼的吗？" | "对，而且是刻意的。生成走 new-api 网关接通用 LLM、编排用 SAA 裸图、美术用 mmx-cli、后台 Huijing、安全阿里云——自研这些要 6-12 月烧千万，我们数周集成，省下的全投在竞品没有的 feed/变现/SDK 上。自研边界很清楚（见 B3）。" | | "锁风是什么高深算法？" | "不是。嵌入比对 + 阈值 + 人审。我们不声称算法领先——它解决的是工程和合规问题：让非独家 IP 安全规模化。价值在流程，不在算法。" | | "轻量 runtime 有什么了不起？" | "运行时本身不了不起——渲染引擎我们直接用成熟开源轻引擎。了不起的是控制点：广告/支付在宿主侧注入、游戏沙箱零网络权限——决定了变现能否被平台掌控、合规边界划在哪。是工程选择，不是炫技。" | @@ -97,7 +97,7 @@ - **13 模块高内聚低耦合 + 契约先行**（Feign `-api` 包声明）+ 单 JAR 起步可平滑拆微服务。 - **沙箱安全铁律**：iframe `sandbox` + CSP `connect-src 'none'` + postMessage 来源/schema 双校验 + 10MB/2MB 体积预算。 - **降级铁律**：SDK 非核心模块全 try-catch 包裹，广告/支付失败不阻断游戏主循环（requestAnimationFrame 永不被 SDK 卡住）。 -- **可观测全套**（Prometheus/Jaeger/Sentry，trace_id 透传含 Dify/OpenGame）+ **幂等四场景** + 最终一致性补偿。 +- **可观测全套**（Prometheus/Jaeger/Sentry，trace_id 透传含 new-api 网关/SAA 编排）+ **幂等四场景** + 最终一致性补偿。 - **一句话收**："这不是有护城河的架构，是'懂工程的团队用最少的钱把闭环跑通'的架构——而这正是种子轮最该考察的团队能力。" --- diff --git a/docs/architecture/系统概要设计-开发团队版.md b/docs/architecture/系统概要设计-开发团队版.md index 9721a501..b4a803ef 100644 --- a/docs/architecture/系统概要设计-开发团队版.md +++ b/docs/architecture/系统概要设计-开发团队版.md @@ -19,10 +19,14 @@ 2. **huijing 单体**运行，无 Nacos / RocketMQ / 独立 Gateway——§1.3 中间件启动、§9 按 MQ/Nacos 排错的路径全部失效； 3. 后端业务模块后缀为 **`-server`**（非 `-biz`），API 前缀为 **`/app-api`、`/admin-api`**（非 `/app`、`/admin`）——照本档命令/路径必失败； 4. **无 docker-compose / 自有 CI**：构建部署 = mini-desktop 手动（git push→pull），见进度总账与 `docs/memorys/`； -5. **Dify 暂不部署**：生成链 = 模板驱动 + new-api 直连（C2 裁定 2026-06-09）； +5. **废弃选型（本档正文多处仍当现行栈描述，阅读时一律按现行口径折算）**： + - **生成主线** = 模板驱动 via **new-api 网关**（OpenAI 兼容 baseUrl，剥末尾 `/v1`）+ **SAA（Spring AI Alibaba v1.1.2.2）裸 `StateGraph` 编排**（HJ-AGI-002）；**Dify / OpenGame 降级远期、MVP 从不部署**（C2 裁定 2026-06-09 / HJ-GEN-001 终审 2026-06-12）。本档 §1.3 启动 AI 引擎、§2 `service/dify/`、§6.2、§9 QUEUED 排错、§10.1/10.2/10.3、§11 速查链接中把 Dify/OpenGame 当现行依赖之处，均为蓝图态，照做必失败； + - **Tier1 引擎** = **LittleJS 增强发行版（约 55KB gz）+ Runner v2（装载契约 game-host.d.ts）**；本档「自研轻量 Runtime <15KB / 自研 Canvas adapter」（§2 compiler 注、§10.4）已废除（2026-06-12 终裁），模板 = LittleJS 能力插件（玩法模板层随 W-CLEAN 废除），Tier2/3 = Cocos Creator 3.8.8 + MCP； + - **美术 / 音乐** = **mmx-cli（MiniMax，agent 直接 CLI 调用）**；本档 §10.1「ComfyUI / Stability Audio」已退备选； + - **RocketMQ / Nacos** = 框架自带依赖与配置在仓，但 **MVP 未部署 broker / registry**（future-state，勿当现行中间件启动/排错）；命名空间 = `com.wanxiang.huijing`，对外品牌 = 绘境AI。 6. 前端 mock = 自写 vite 中间件（非 vite-plugin-mock）；前端验证门 = `npm run build`（`vue-tsc --noEmit` 是假门禁）；admin 二开目录 = `views/wanxiang/`（非 `views/game/`）。 -> §4 编码规范、§5.3 commit 规范、§10 工具层蓝图段仍有效；其余章节阅读时按上述差异折算。 +> §4 编码规范、§5.3 commit 规范仍有效；§10 工具层为蓝图态——其中 Dify/OpenGame/ComfyUI/Stability Audio 已按上条折算为远期/退备选，现行生成主线见 [`.agents/skills/saa-graph-orchestration.md`](../../.agents/skills/saa-graph-orchestration.md) + [`.agents/skills/cheap-model-game-generation.md`](../../.agents/skills/cheap-model-game-generation.md)。其余章节阅读时按上述差异折算。 --- @@ -57,10 +61,11 @@ game-studio/ 产品端前端（Vue3 + Vant，创作者+玩家） cd game-cloud/deploy docker compose -f docker-compose.middleware.yml up -d -# 2. 启动 AI 引擎（Dify + OpenGame + ComfyUI） -docker compose -f docker-compose.ai.yml up -d -# 注意：ComfyUI 需要 GPU（或 CPU 模式启动，速度慢 10x） -# 无 GPU 时可跳过 ComfyUI，图片生成走 mock 或外部 API +# 2.（future-state，MVP 不执行）启动 AI 引擎（Dify + OpenGame + ComfyUI） +# ⚠️ 现行生成主线 = new-api 网关直连便宜模型 + SAA 裸图编排（在 game-server 进程内），不部署 Dify/OpenGame/ComfyUI。 +# 本步为 1.x 蓝图态，MVP 跳过；new-api 网关地址/密钥经环境变量注入（见 aigc 模块 AigcExecutorProperties）。 +# docker compose -f docker-compose.ai.yml up -d +# 注意（仅蓝图态）：ComfyUI 需要 GPU；现行美术/音乐已改用 mmx-cli（MiniMax CLI），ComfyUI 退备选。 # 3. 初始化数据库 cd game-cloud @@ -85,11 +90,9 @@ cd game-studio && pnpm install && pnpm dev - 管理后台：http://localhost:1024（admin / admin123） - 产品端：http://localhost:3000 - 后端 API：http://localhost:48080 -- Nacos 控制台：http://localhost:8848/nacos（nacos / nacos） -- Dify：http://localhost:3001 -- ComfyUI：http://localhost:8188 +- Nacos 控制台：http://localhost:8848/nacos（nacos / nacos）（future-state，MVP 未部署 registry） - MinIO：http://localhost:9001（minioadmin / minioadmin） -- OpenGame Agent：http://localhost:8100 +- ~~Dify：http://localhost:3001 / ComfyUI：http://localhost:8188 / OpenGame Agent：http://localhost:8100~~（future-state，MVP 不部署；现行 = new-api 网关 + SAA 裸图编排，美术/音乐 = mmx-cli） --- @@ -126,18 +129,20 @@ game-cloud/ │ └── game-module-aigc-biz/ │ ├── controller/app/ # 创作者发起生成 │ ├── controller/admin/ # 模板/工作流管理 -│ ├── service/task/ # 生成任务调度（MQ） -│ ├── service/dify/ # Dify HTTP Client -│ ├── service/template/ # 模板引擎 +│ ├── service/task/ # 生成任务调度 +│ ├── service/executor/ # 生成执行器 + new-api 网关 LLM Client（现行主线；剥末尾 /v1，OpenAI 兼容） +│ ├── saa/ # SAA(Spring AI Alibaba)裸 StateGraph 编排（HJ-AGI-002：render→design→generate→…→emit） +│ ├── service/template/ # 模板装载（LittleJS 插件 / Prompt Registry per templateId） │ ├── service/quality/ # 质量评估 -│ └── mq/consumer/ # MQ 消费者（任务执行） +│ └── service/callback/ # 生成回调写链（DifyCallbackService 系历史命名，现行复用其三表同事务写链，非真 Dify 依赖） +│ # 注：~~service/dify/ Dify HTTP Client~~ 已废除——Dify 降级远期、从未部署 │ ├── game-module-runtime/ # 运行时/包构建/转换 │ ├── game-module-runtime-api/ │ └── game-module-runtime-biz/ │ ├── controller/app/ # 预览包交付端点（按版本） │ ├── controller/admin/ # 包管理/转换管理 -│ ├── service/compiler/ # GameConfig → 可运行 Web 包（自研轻量 Runtime, <15KB） +│ ├── service/compiler/ # 生成产物 → 可运行 Web 包（Tier1=LittleJS 增强发行版≈55KB gz + Runner v2 装载契约 game-host.d.ts；~~自研轻量 Runtime<15KB~~ 已废除，2026-06-12 终裁） │ ├── service/package/ # 包存储/版本化/checksum/CDN 刷新 │ └── service/conversion/ # 多渠道导出（微信格式包为枢纽） │ ├── WechatPackager.java # 产出微信小游戏格式包（导出枢纽） @@ -155,7 +160,7 @@ game-cloud/ │ └── deploy/ ├── docker-compose.middleware.yml # 中间件 - ├── docker-compose.ai.yml # Dify + OpenGame + ├── docker-compose.ai.yml # （future-state，MVP 不部署）Dify + OpenGame——现行生成主线 = new-api 网关 + SAA 裸图，不需此栈 ├── docker-compose.yml # 全栈（生产/staging） ├── sql/ # 初始化 + seed ├── nacos/ # Nacos 配置导入 @@ -167,7 +172,7 @@ game-cloud/ | 模块 | 一句话 | 对外暴露 | 主要依赖 | |---|---|---|---| | project | 项目/版本/草稿/发布/审核 | `/app/project/**`, `/admin/project/**` | bpm, system, infra | -| aigc | AI 生成任务调度 + Dify 调用 | `/app/aigc/**`, `/admin/aigc/**` | project, compliance, Dify, OpenGame | +| aigc | AI 生成任务调度 + new-api 网关 LLM 调用 + SAA 裸图编排 | `/app/aigc/**`, `/admin/aigc/**` | project, compliance, new-api 网关；~~Dify/OpenGame~~ 降级远期未部署 | | runtime | 编译打包 + 资源交付 + 小游戏转换 | `/app/runtime/**`, `/admin/runtime/**` | project, OSS, CDN | | feed | 推荐列表 + 互动 + 分享 | `/app/feed/**`, `/admin/feed/**` | project, telemetry, Redis | | telemetry | 事件摄取 + 聚合 + 看板 | `/app/telemetry/**`, `/admin/telemetry/**` | MQ, MySQL | @@ -345,7 +350,7 @@ main ← 始终可部署，保护分支 ```bash # 1. 从 develop 创建分支 git checkout develop && git pull -git checkout -b feature/aigc-dify-integration +git checkout -b feature/aigc-saa-graph # 2. 开发 + 本地测试 # ...编码... @@ -353,10 +358,10 @@ mvn test -pl game-module-aigc-biz # 跑单元测试 # 3. 提交（Conventional Commits） git add . -git commit -m "feat(aigc): integrate Dify workflow API for game generation" +git commit -m "feat(aigc): wire SAA StateGraph generation via new-api gateway" # 4. 推送 + 创建 PR -git push -u origin feature/aigc-dify-integration +git push -u origin feature/aigc-saa-graph # 在 GitHub/Gitea 创建 PR → develop # 5. Review + CI 通过 → Merge @@ -374,7 +379,7 @@ subject: 动词开头，简明描述（中英文均可） 示例： ``` -feat(aigc): integrate Dify workflow API for game generation +feat(aigc): wire SAA StateGraph generation via new-api gateway fix(feed): cursor pagination returns duplicate games refactor(sdk): extract telemetry buffer into standalone module test(project): add integration test for publish flow @@ -413,12 +418,15 @@ test(project): add integration test for publish flow | 问题跟踪 | 联调 bug 提 Issue，标签 `联调` + 模块名 | | 契约对齐 | 后端先写 `-api` 包的 VO/DTO，前端据此定义 TypeScript 类型 | -### 6.2 后端与 AI 引擎联调 +### 6.2 后端与 AI 引擎联调（现行 = new-api 网关 + SAA 裸图，进程内编排） + +> ⚠️ 现行无独立 AI 引擎进程：生成全在 game-server 进程内由 SAA 裸 `StateGraph` 编排，仅出网调 new-api 网关。~~Dify/OpenGame 联调~~ 系蓝图态、MVP 不部署。 | 组件 | 地址 | 联调方式 | |---|---|---| -| Dify | `http://localhost:3001` | 后端 `DifyClient` 调用 Workflow API，Dify UI 可查看执行日志 | -| OpenGame | `http://localhost:8100` | Dify 节点调用，或直接 HTTP 测试 `/generate` 端点 | +| **new-api 网关** | 经环境变量注入（`AigcExecutorProperties` 的 llm-base/api-key；OpenAI 兼容，baseUrl 自动剥末尾 `/v1`） | 图内五角色模型全经此网关；与 W-G1 http worker 同一计费平面，对账看 new-api `logs.quota` | +| **SAA 裸图** | game-server 进程内（`saa/SaaStudioGraph.java` 唯一布线源 + `SaaGraphDispatcher.java` 生产派发） | 单测 `SaaStudioGraphTest` / 冒烟 `SaaNewApiGenerateSmokeTest`；门禁 = 九门真玩 harness | +| ~~Dify / OpenGame~~ | ~~localhost:3001 / 8100~~ | future-state，降级远期未部署 | ### 6.3 SDK 与宿主联调 @@ -515,7 +523,7 @@ docker compose up -d | 本地启动报 Nacos 连接失败 | 先 `docker compose -f docker-compose.middleware.yml up -d`，等 Nacos 就绪 | | Flyway 迁移冲突 | 不要修改已存在的迁移文件；新建迁移解决 | | 前端 API 401 | Token 过期，重新登录；检查 `.env` 中后端地址 | -| 生成任务一直 QUEUED | 检查 Dify 是否启动 + RocketMQ Consumer 是否注册 | +| 生成任务一直 QUEUED | 现行：检查 new-api 网关可达（llm-base/api-key 注入正确、渠道活）+ SAA 图派发器是否构造成功（看 `SaaGraphDispatcher` 日志）。~~Dify 启动 / RocketMQ Consumer~~ 系蓝图态排错路径，MVP 不适用 | | SDK postMessage 收不到 | 检查 iframe origin 是否在白名单；查看 Console 错误 | | 单元测试依赖 DB | 应该用 Mock；如果需要真 DB，用集成测试 + Testcontainers | | PR CI 失败 | 看 CI 日志；最常见：代码格式（Checkstyle）/ 测试未更新 | @@ -524,61 +532,60 @@ docker compose up -d ## 10. 外部工具层开发指南 +> ⚠️ **本章为 1.x 蓝图态（2026-06-07），其中部分工具已废弃/降级，下表已按现行口径标注**： +> - **生成主线现行 = new-api 网关（OpenAI 兼容）+ SAA(Spring AI Alibaba)裸 `StateGraph` 进程内编排**（HJ-AGI-002）；**Dify/OpenGame 降级远期、MVP 从不部署**，§10.2 Dify 开发流程仅留作历史。 +> - **美术/音乐现行 = mmx-cli（MiniMax CLI，agent 直接调用，免 GPU/免训练）**；**ComfyUI 退备选**（§10.3 仅历史），~~Stability Audio~~ 同退。 +> - **Tier1 渠道导出现行 = LittleJS + W-CH-α 竞标 adapter**；§10.4「自研 Canvas adapter」随自研壳退役。 + ### 10.1 工具全景 | 工具 | 本地地址 | 对接模块 | 开发者需要了解的 | |---|---|---|---| -| **Dify** | http://localhost:3001 | aigc | 编排 workflow、调试节点、查看执行日志 | -| **OpenGame** | http://localhost:8100 | aigc（通过 Dify 节点调用） | 测试 `/generate` 端点、查看 6 阶段日志 | -| **ComfyUI** | http://localhost:8188 | aigc（图片/素材生成） | 设计 workflow、导出 API JSON、对接 Dify | -| **多渠道导出** | 自研转换器 / Cocos 官方导出 | runtime（多渠道导出） | 以微信小游戏格式包为枢纽，抖音单独适配，快手经微信格式兼容转换 | -| **safe-content-ai** | http://localhost:8200 | compliance | 图片 NSFW 快检 API | +| **new-api 网关**（现行生成主线） | 环境变量注入（llm-base/api-key，OpenAI 兼容，剥末尾 `/v1`） | aigc | 多模型经此网关直连；`logs.quota` 权威对账成本 | +| **SAA 裸图编排**（现行生成主线） | game-server 进程内（`saa/SaaStudioGraph.java`） | aigc | 11 节点确定性多步图，门禁=九门真玩 harness；不用 ReactAgent/asNode | +| **mmx-cli（MiniMax）**（现行美术/音乐） | CLI（远程 API） | aigc（图片/音乐/语音） | agent 直接 CLI 生成，免 GPU/免训练；用量=quota 入成本台账 | +| ~~Dify~~ | ~~localhost:3001~~ | ~~aigc~~ | **future-state，降级远期未部署**（编排能力现由 SAA 裸图承担） | +| ~~OpenGame~~ | ~~localhost:8100~~ | ~~aigc~~ | **future-state，降级远期未部署**（代码生成现由 agent 写码于插件库） | +| ~~ComfyUI~~ | ~~localhost:8188~~ | ~~aigc（图片/素材）~~ | **退备选**（现行美术=mmx-cli；如需训风格 LoRA 再议） | +| **多渠道导出** | LittleJS adapter（W-CH-α 竞标）/ Cocos 官方导出 | runtime（多渠道导出） | 以微信小游戏格式包为枢纽，抖音单独适配，快手经微信格式兼容转换（~~自研 Canvas adapter~~ 已退役） | +| **safe-content-ai** | http://localhost:8200 | compliance | 图片 NSFW 快检 API（future-state，随 docker-compose.ai.yml 蓝图态） | | **穿山甲/优量汇 SDK** | 宿主侧加载 | ad + SDK Plugin.Ad | 广告 SDK 集成、广告位 ID 配置 | -| **Stability Audio API** | 远程 API | aigc（音乐生成） | API Key 配置、调用封装 | -| **Fish Audio** | 远程 API | aigc（语音生成） | 音色克隆训练、TTS 调用 | +| ~~Stability Audio API~~ | ~~远程 API~~ | ~~aigc（音乐）~~ | **退备选**（现行音乐=mmx-cli） | +| **Fish Audio / 阿里 CosyVoice** | 远程 API | aigc（语音生成，备选） | 音色克隆/TTS（现行语音优先 mmx-cli，本项备选） | -### 10.2 Dify 开发流程 +### 10.2 生成编排开发流程（现行 = new-api 网关 + SAA 裸图） + +> ⚠️ ~~原「Dify 开发流程」已废除~~——Dify 降级远期、MVP 从不部署。现行生成编排在 game-server 进程内用 SAA 裸 `StateGraph`，仅出网调 new-api 网关。 ```bash -# 本地访问 Dify -open http://localhost:3001 - -# 创建/编辑游戏生成 Workflow： -# 1. Dify UI → Studio → 创建 Workflow -# 2. 添加节点：LLM / HTTP(OpenGame) / HTTP(ComfyUI) / 条件分支 / 变量赋值 -# 3. 测试运行 → 查看每节点输入输出 -# 4. 发布为 API → 获取 workflow_id - -# 后端调用方式： -# DifyClient.java 调用 POST /v1/workflows/run -# Body: { "inputs": {"prompt": "...", "template_id": "..."}, "response_mode": "blocking" } +# 现行：改图 = 改 saa/SaaStudioGraph.assemble()（唯一布线源，生产派发器 + 回归测试共用） +# 节点 11 个 + 条件边 4 处：START→render→design→generate→validate ─┬(ok)→scaffold→build→play→player→emit→END +# ├(repair)→repair→generate（回环） +# └(giveup)→giveup→END +# 后端调用方式（现行）： +# SaaGraphDispatcher 懒构造并缓存已编译图；图内五角色模型全经 new-api 网关： +# OpenAiApi.builder().baseUrl(stripV1Suffix(llm-base)).apiKey(api-key).build() # baseUrl 取 host 根，剥末尾 /v1 +# 验证：mvn test -pl game-module-aigc-server -Dtest=SaaStudioGraphTest # 拓扑回归 +# 冒烟见 SaaNewApiGenerateSmokeTest；详见 .agents/skills/saa-graph-orchestration.md ``` -### 10.3 ComfyUI 开发流程 +### 10.3 ~~ComfyUI 开发流程~~（已退备选；现行美术/音乐 = mmx-cli） + +> ⚠️ **ComfyUI 已退备选**（2026-06-12 创始人亲验拍板）。现行美术/音乐 = **mmx-cli（MiniMax CLI）**：agent 造游戏时直接 CLI 调用，免 GPU、免训练 LoRA。以下 ComfyUI 节点流程仅留作历史/远期训风格 LoRA 时参考。 ```bash -# 本地访问 ComfyUI -open http://localhost:8188 +# 现行：mmx-cli 生成图片/音乐（agent 直接调用，用法见全局 skill `mmx-cli`） +# mmx image ... # 文生图（角色/场景/封面） +# mmx music ... # 音乐生成 +# 用量 = quota 对账入成本台账（盯用量，创始人拍板默认走 mmx-cli） -# 设计图片生成 workflow（节点拖拽）： -# 1. 加载模型节点（Flux/SDXL/自训练 LoRA） -# 2. 配置 prompt/negative_prompt/尺寸/步数 -# 3. 运行验证效果 -# 4. 导出 workflow 为 JSON（Save → API Format） - -# 通过 API 调用： -# POST http://localhost:8188/prompt -# Body: { "prompt": , "client_id": "..." } -# 轮询 /history/{prompt_id} 获取结果图片 URL - -# 在 Dify 中集成： -# Dify HTTP Request 节点 → ComfyUI /prompt 端点 -# 输入：风格描述 + 角色描述 → 填入 workflow JSON 的 prompt 字段 +# ── 以下为 ComfyUI（退备选，仅历史/训 LoRA 时参考）── +# open http://localhost:8188 → 拖拽节点设计 workflow → 导出 API Format JSON → POST /prompt → 轮询 /history/{prompt_id} ``` ### 10.4 多渠道导出 -**导出枢纽 = 微信小游戏格式包**。Tier1 自研 Canvas 自做 adapter，Tier2/3（远期）用 Cocos Creator 官方一键导出。各渠道路径： +**导出枢纽 = 微信小游戏格式包**。Tier1（LittleJS 增强发行版）渠道 adapter 走 **W-CH-α 对比竞标**（LittleJS+adapter vs Cocos 导出，HJ-CH-001；~~原「自研 Canvas 自做 adapter」随自研壳退役~~），Tier2/3（远期）用 Cocos Creator 官方一键导出。各渠道路径： - **微信**：引擎导出官方格式，直接上架。 - **抖音**：抖音有自有导出接口，单独适配。 @@ -589,8 +596,8 @@ open http://localhost:8188 # Tier2/3（远期，Cocos Creator）官方一键导出微信小游戏包 # Cocos Creator → 构建发布 → 微信小游戏平台 → 构建 -# Tier1（MVP）自研 Canvas adapter 产出微信格式包： -# runtime 模块 service/conversion 调用自研转换器 → 产出微信小游戏包 +# Tier1（MVP，LittleJS）产出微信格式包：渠道 adapter 走 W-CH-α 竞标（~~自研 Canvas 转换器~~ 已退役） +# runtime 模块 service/conversion 承载导出枢纽（微信格式包），具体 adapter 实现待 HJ-CH-001 竞标定 # 快手：将微信格式包导入快手开发者工具做兼容转换，无一键 CLI # 在 Java 中调用（runtime 模块）： @@ -621,19 +628,19 @@ open http://localhost:8188 | 资源 | 地址 | |---|---| | 后端 API 文档（Swagger） | http://localhost:48080/doc.html | -| Nacos 控制台 | http://localhost:8848/nacos | -| Dify 编排界面 | http://localhost:3001 | -| ComfyUI 图片生成 | http://localhost:8188 | -| OpenGame Agent | http://localhost:8100 | -| safe-content-ai | http://localhost:8200 | +| Nacos 控制台（future-state，MVP 未部署） | http://localhost:8848/nacos | +| ~~Dify 编排界面 / ComfyUI / OpenGame Agent~~ | ~~localhost:3001 / 8188 / 8100~~（future-state，MVP 不部署；现行=new-api 网关 + SAA 裸图 + mmx-cli） | +| safe-content-ai（future-state，随 AI 栈蓝图态） | http://localhost:8200 | | MinIO 文件管理 | http://localhost:9001 | | Grafana 监控 | http://localhost:3002 | | 设计文档目录 | `docs/architecture/` | | 技术架构与模块（Doc B） | `docs/architecture/技术架构与模块.md` | +| SAA 图编排 playbook（现行生成主线） | `.agents/skills/saa-graph-orchestration.md` | +| 便宜模型生成 playbook（W-G1） | `.agents/skills/cheap-model-game-generation.md` | | Huijing 官方文档 | https://cloud.iocoder.cn | | Cocos Creator 文档（Tier2/3 远期） | https://docs.cocos.com/creator/3.8/manual/ | -| ComfyUI 文档 | https://docs.comfy.org | -| Dify 文档 | https://docs.dify.ai | +| ~~ComfyUI 文档（退备选）~~ | https://docs.comfy.org | +| ~~Dify 文档（降级远期）~~ | https://docs.dify.ai | --- diff --git a/docs/architecture/系统概要设计-技术决策版.md b/docs/architecture/系统概要设计-技术决策版.md index 1726a807..c5e431df 100644 --- a/docs/architecture/系统概要设计-技术决策版.md +++ b/docs/architecture/系统概要设计-技术决策版.md @@ -1,7 +1,7 @@ # 造梦AI游戏生态平台 — 系统概要设计（技术决策版） > **文档编号**：HJ-ARCH-001 -> **版本**：v2.0 +> **版本**：v2.1（2026-06-16 现行真相对齐：模板驱动/new-api/SAA/LittleJS/mmx-cli/命名空间） > **受众**：技术合伙人 / CTO / 首席架构师 > **生成时间**：2026-06-06 > **关联文档**： @@ -9,11 +9,17 @@ > - 竞品分析：`docs-design/竞品分析报告.md` > - 产品需求/技术模块/映射 三文档：`docs/architecture/产品需求清单.md`、`docs/architecture/技术架构与模块.md`、`docs/architecture/需求模块映射.md` -> **⚠️ 回填状态（2026-06-10，依据 HJ-AUDIT-001 架构三向审计）**：本档为蓝图权威，但以下裁定晚于本档成稿，**以裁定为准**： -> 1. **生成主线已转向「模板驱动」**（C2 裁定 2026-06-09，spike 52/52 结构层 100%）：LLM 直出 GameConfig 参数 + 固定模板 runtime，经 new-api 网关直连 LLM；**Dify / OpenGame 均未部署**，OpenGame 代码生成降级为远期增强。本档 §2.3 模式A 时序图、§4.1、§6.2 的 Dify+OpenGame 描述保留为蓝图原案。 -> 2. **执行排期以 `mvp-execution-spec` + `docs/mvp/MVP作战清单.md` 为准**，§9 甘特仅作蓝图参考；2026-06-08 业务决策已将 MVP 验收改为「staging/内网种子灰度走通真闭环」，公网上线=MVP 后并行长周期任务（受日历闸门约束）。 -> 3. **LLM 接入现状**：D1 拍板主 DeepSeek / 备 Qwen（2026-06-08）；当前实际 = MiniMax-M2.7 经 new-api 网关（DeepSeek key 未激活）。网关多通道兜底曾真实失效（二厂系全废），见 §8 风险 #12。 -> 4. **Tier1 运行时已立项重设计**（2026-06-11 创始人专门会话）：本档「自研 Canvas Runtime <15KB」相关描述（§4.2/§6.6 等）被裁定取代——**15KB 红线废除**（srcdoc 内联架构的衍生约束，前提失效），改三层约束框架（SLO@千元机+4G P75 / 预算入场券 gz≤350KB·raw≤1.5MB / 工程增强层），渲染层换成品轻引擎+Runner v2（终裁待 LittleJS vs Phaser spike）；沙箱/SDK/三容器控制点不变。单一事实源：`docs/brainstorms/2026-06-11-tier1-runtime-constraints-requirements.md` + `.agents/knowledge/tech-decisions.md` §1.1。 +> **⚠️ 回填状态（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）**：玩法/美术/关卡/UI = agent 生成域；旧 4 模板 + 存量数据已清除。Tier2/3 复杂 2D/3D/原生仍用 Cocos Creator 3.8.8 + MCP（不变）。 +> 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`。 --- @@ -46,8 +52,8 @@ - 不做 3D 开放世界游戏生成 - 不做专业级游戏引擎（Unity/Unreal 级别） - 不做海外市场（MVP 阶段） -- 不做完全开放式代码生成（用模板约束保证稳定性） -- 不自研大模型（接入通用 LLM + 开源 Agent 框架） +- 不做完全开放式代码生成（agent 写码于 LittleJS 插件库 + harness 九门约束保证稳定性；玩法模板层已废除 W-CLEAN） +- 不自研大模型（接入通用 LLM 经 new-api 网关 + 开源 Agent 框架 SAA/Spring AI Alibaba） --- @@ -121,37 +127,38 @@ graph TB **模式 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 契约后保持可替换。 + ```mermaid sequenceDiagram participant C as 创作者 participant S as game-studio participant GW as Gateway participant AIGC as aigc-module - participant DIFY as Dify(编排) - participant OG as OpenGame(生成) - participant RT as runtime-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 + 选择风格/模板 + C->>S: 输入 Prompt + 选择风格 S->>GW: POST /api/aigc/generate GW->>AIGC: 转发（鉴权通过） - AIGC->>AIGC: 创建生成任务（MQ） + AIGC->>AIGC: 创建生成任务（GenerationDispatcher 派发） AIGC-->>S: 202 Accepted {taskId} S->>S: 轮询/SSE 监听任务状态 - AIGC->>DIFY: HTTP 调用 Workflow API - DIFY->>DIFY: 节点1: Prompt 安全检测 - DIFY->>DIFY: 节点2: 意图解析 + 模板匹配 - DIFY->>DIFY: 节点3: GameConfig 生成 + Schema 校验 - DIFY->>OG: 节点4: HTTP 调用 OpenGame Agent - OG->>OG: 6阶段 Pipeline（脚手架→设计→素材→代码→验证→修正） - OG-->>DIFY: 返回游戏代码包 - DIFY->>DIFY: 节点5: 质量评估 - DIFY-->>AIGC: 返回完整 GamePackage + 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->>RT: 编译 + 打包 + 上传 OSS - RT-->>AIGC: packageUrl + manifest AIGC->>PRJ: 写入草稿版本（含生成的资产） AIGC-->>S: 任务完成通知 @@ -170,7 +177,7 @@ sequenceDiagram **模式 C：工作流编排（专业路径）** -专业创作者可进入 Dify 暴露的可视化编排界面，自定义生成流程的节点、参数和条件分支。适用于批量生产、品牌定制等场景。 +专业创作者可自定义生成流程的节点、参数和条件分支，适用于批量生产、品牌定制等场景。（**2026-06-16 纠偏**：原述"进入 Dify 可视化编排界面"——Dify 从未部署、已降级远期；现行/远期编排基建 = SAA(Spring AI Alibaba)裸 `StateGraph` 编排（HJ-AGI-002），可视化编排面属远期能力。） #### 玩家游戏流主流程 @@ -400,16 +407,19 @@ graph TB BPM[bpm
工作流] end - subgraph AI[AI引擎层] - DIFY[Dify
DAG编排/多模型] - OPENGAME[OpenGame Agent
Python/代码生成] + subgraph AI[AI生成层_现行] + SAA[SAA StateGraph编排
Spring AI Alibaba v1.1.2.2] + NEWAPI[new-api 网关
OpenAI兼容/多模型] + LLM[便宜LLM
DeepSeek/MiniMax] + MMX[mmx-cli
图片/音乐素材] + LJS[LittleJS+Runner v2
Tier1 引擎/插件库] end subgraph MW[中间件层] - NACOS[Nacos] + NACOS["Nacos
(future-state·框架自带未部署)"] MYSQL[MySQL 8.0] REDIS[Redis 7] - MQ[RocketMQ 5] + MQ["RocketMQ 5
(future-state·框架自带未部署)"] MINIO[MinIO/OSS] end @@ -439,8 +449,11 @@ graph TB GATEWAY --> SYS GATEWAY --> INFRASVC GATEWAY --> BPM - AIGC --> DIFY - DIFY --> OPENGAME + AIGC --> SAA + SAA --> NEWAPI + NEWAPI --> LLM + SAA --> MMX + SAA --> LJS PRJ --> MYSQL PRJ --> REDIS PRJ --> MQ @@ -469,10 +482,10 @@ graph TB graph LR subgraph 宿主机 subgraph 中间件容器 - nacos[Nacos:8848] + nacos["Nacos:8848
(future-state·MVP未部署)"] mysql[MySQL:3306] redis[Redis:6379] - rocketmq[RocketMQ:9876] + rocketmq["RocketMQ:9876
(future-state·MVP未部署)"] minio[MinIO:9000] end @@ -484,12 +497,12 @@ graph LR end subgraph 业务服务容器 - game_all[game-server:48090
单体模式含全部13个业务模块] + game_all["game-server:48090
单体模式含全部13个业务模块
(内置 SAA 裸图编排/aigc)"] end - subgraph AI引擎容器 - dify[Dify:3000+80] - opengame[OpenGame:8100] + subgraph AI生成接入_现行 + newapi["new-api 网关
(外部·mini-infra:3000)"] + mmx["mmx-cli
(MiniMax 素材生成)"] end subgraph 前端容器 @@ -505,17 +518,18 @@ graph LR end ``` -**MVP 阶段单体启动**：所有 13 个业务模块编译为同一个 JAR（`game-server`），通过 Spring Profile 控制模块加载。需要独立扩缩时，Nacos 配置一改即拆为独立服务。 +**MVP 阶段单体启动**：所有 13 个业务模块编译为同一个 JAR（`game-server`），通过 Spring Profile 控制模块加载。需要独立扩缩时再启用 Nacos 拆为独立服务（**future-state**：Nacos 框架自带、MVP 未部署 registry，单体期走本地配置）。 ### 3.3 模块间通信 | 通信方式 | 场景 | 协议 | |---|---|---| | 同步 HTTP | 前端→Gateway→业务服务 | REST JSON | -| 同步 HTTP | aigc→Dify, Dify→OpenGame | REST JSON | +| 同步 HTTP | aigc→new-api 网关→LLM；SAA 各节点经 OpenAI 兼容接口调模型 | REST JSON | +| 进程内调用 | aigc 生成派发 `GenerationDispatcher`（http worker \| 进程内 SAA 图，二选一单写） | Java 接口 | | 同步 Feign | 服务间同步调用（如 project→system 查用户） | Spring Cloud OpenFeign | -| 异步 MQ | 生成任务派发、审核通知、事件摄取、结算触发 | RocketMQ | -| 事件广播 | 发布成功→feed 刷新缓存、→telemetry 记录 | RocketMQ Topic | +| 异步 MQ（future-state） | 生成任务派发、审核通知、事件摄取、结算触发 | RocketMQ（框架自带、MVP 未部署 broker；现行走进程内/同步） | +| 事件广播（future-state） | 发布成功→feed 刷新缓存、→telemetry 记录 | RocketMQ Topic（同上，MVP 未启用） | ### 3.4 平台 Game SDK 设计 @@ -774,13 +788,16 @@ runtime-module 编译 GamePackage 时： ### 4.1 AI 生成链路 -**架构决策**：Dify（DAG 编排）+ OpenGame（代码生成）+ Java 壳（任务调度） +**架构决策（现行，2026-06-16）**：**SAA(Spring AI Alibaba)裸 `StateGraph` 编排** + **new-api 网关 → 便宜 LLM** + agent 写码于 LittleJS 插件库 + harness 九门兜底。 -> ⚠️ **2026-06-10 回填**：MVP 现行主线已按 C2 裁定改为**模板驱动**（LLM 直出 GameConfig + 固定模板 runtime，见文档头部回填状态）；本节 Dify+OpenGame 组合保留为远期增强蓝图。 +> ✅ **现行主线（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，不自研）**： -| 维度 | 自研 | Dify + OpenGame | +| 维度 | 自研 | Dify + OpenGame（蓝图原案，未落地） | |---|---|---| | 核心生成能力 | 3-6 个月 | 2-4 周集成验证 | | DAG 编排引擎 | 2-3 个月 | Dify 开箱即用 | @@ -790,11 +807,13 @@ runtime-module 编译 GamePackage 时： | 可观测性 | 自建 | Dify 内置 trace | | **总周期** | **6-12 个月** | **4-6 周** | -**为什么不选其他**： +**当初为什么不选其他（决策史）**： - LangGraph：纯 Python 框架，无可视化 UI，运营无法参与编排 - Coze：字节闭源，不可控 - n8n：通用自动化，非 LLM 原生 +> **后话**：现行 SAA 裸图编排即"Java 进程内确定性多步编排"，避开了对 Dify 可视化 UI 的依赖（可视化编排面属远期能力）；多模型切换由 new-api 网关承担；可观测性由 SAA graph-core 的 observation 机芯（每节点发 Micrometer observation）承担。 + **生成任务状态机**： ```mermaid @@ -946,7 +965,6 @@ erDiagram string status string prompt string template_id - string dify_workflow_id int retry_count int duration_ms string error_code @@ -973,7 +991,7 @@ erDiagram | 推荐候选集/热数据 | Redis 7 | 低延迟，Sorted Set 排序 | | 事件流（埋点） | MySQL 分区表(MVP) → ClickHouse(增长期) | 先简后扩 | | 搜索（游戏/素材） | MySQL FULLTEXT(MVP) → Elasticsearch(增长期) | 先简后扩 | -| 配置/注册 | Nacos | Huijing 原生 | +| 配置/注册（future-state） | Nacos | Huijing 框架自带，**MVP 未部署 registry**；现行单体走本地配置/Spring Profile | | 分布式锁/限流 | Redis | 高性能 | ### 5.3 数据流向总览 @@ -981,7 +999,7 @@ erDiagram ```mermaid graph LR STUDIO[game-studio] -->|事件上报| TEL_API[telemetry /events/batch] - TEL_API -->|异步| MQ[RocketMQ] + TEL_API -->|异步·future-state| MQ["RocketMQ
(框架自带·MVP未部署)"] MQ -->|消费入库| MYSQL[(MySQL 事件表)] MYSQL -->|定时聚合| AGG[GameDailyStats] AGG -->|写入| REDIS_FEED[Redis 候选集] @@ -1009,12 +1027,13 @@ graph LR | 候选 | 选择 | 理由 | |---|---|---| -| **Dify(编排) + OpenGame(生成)** | ✅ 选用 | Dify: DAG 可视化/多模型/可观测性开箱即用；OpenGame: SOTA 效果/6 阶段 pipeline/论文验证；组合 4-6 周跑通 | +| **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-10 回填**：C2 spike（4 模板 × 13 创意 = 52/52 结构层 100%）证实「LLM 填参数 + 固定模板 runtime」即可达标——**MVP 不部署 Dify/OpenGame，直连 new-api 网关**；本表选型整体降级为远期增强路径（产能/复杂度上台阶时再启用）。 +> **现行口径（2026-06-16）**：MVP **不部署 Dify/OpenGame**，生成主线 = new-api 网关 + SAA 裸图编排（详见 §4.1）。Dify+OpenGame 整体降级为远期增强路径，本表保留其行作决策史。AgentScope（agent-native 探索）= long-term premium 独立轨，亦不在 MVP 运行时。 ### 6.3 前端 @@ -1035,7 +1054,7 @@ graph LR | 候选 | 选择 | 理由 | |---|---|---| -| **RocketMQ 5** | ✅ 选用 | Huijing 默认集成，延迟消息/事务消息/死信队列完整，适合生成任务调度 | +| **RocketMQ 5** | ✅ 选用（**future-state**：框架自带、MVP 未部署 broker） | Huijing 默认集成，延迟消息/事务消息/死信队列完整，适合生成任务调度；**MVP 运行时未部署 broker**，现行生成派发走进程内 `GenerationDispatcher`/同步，待产能/异步化需求上台阶时启用 | | Kafka | ❌ 放弃 | 偏大数据流，运维重，MVP 阶段过度 | | Redis Stream | ❌ 放弃 | 可靠性不如 RocketMQ，无死信/事务消息 | @@ -1045,44 +1064,49 @@ graph LR | 候选 | 选择 | 理由 | |---|---|---| -| **自研轻量 Canvas Runtime（Tier1：Web 预览/游戏流）** | ✅ 选用 | < 15KB，首屏极快（P75 < 3s），AI 生成纯 JS 直接可运行，平台完全控制沙箱/SDK 注入，是护城河；MVP 唯一交付层 | +| **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 全栈 | ❌ 放弃 | 纯 2D 游戏引擎，多渠道导出能力弱，小游戏适配需自研 | +| Phaser 3 全栈 | ❌ 放弃（spike 竞标落选） | 纯 2D 游戏引擎；经 T1 eval-spike 与 LittleJS 对比，败于冷开/交付形态（工程质量合格，证据留 spike 目录） | | LayaAir 全栈（运行时+编辑器+导出） | ❌ 放弃 | 引擎过重影响游戏流加载；无 AI/MCP 生态；官方导出平台清单**不含快手**（旧"一键导出快手"为事实错误） | | Unity | ❌ 放弃 | AI 适配差、启动重（7-10s），与 P75 < 3s 冲突 | -**分层架构（Tier1 自研 Canvas + Tier2/3 Cocos-MCP）**： +**分层架构（Tier1 LittleJS 增强发行版 + Runner v2 / Tier2/3 Cocos-MCP）**： ``` -AI 生成 → 纯 JS/Canvas 游戏代码（Tier1，OpenGame 文生代码） +AI 生成 → agent 写码于 LittleJS 插件库（Tier1，玩法/美术/关卡/UI=生成域） ↓ Web 预览/游戏流 -自研轻量 Runtime（iframe sandbox + SDK Core）→ 即时加载，< 15KB +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）**：**玩法模板层已废除**——模板 = LittleJS 能力插件/二次开发件，玩法/美术/关卡/UI 全是 agent 生成域；旧 4 模板（clicker/dodge/runner/match）+ 存量数据已清除。好玩基线 v2 改挂评估门。 + 为什么分层： -- Web 预览和游戏流需要**极快加载**（P75 < 3s），Tier1 轻量 Runtime 满足，MVP 仅交付此层 +- Web 预览和游戏流需要**极快加载**（P75 < 3s），Tier1 LittleJS 增强发行版 + Runner v2 满足，MVP 仅交付此层 - 复杂 2D/3D/原生产物（Tier2/3）需成熟引擎，复用 Cocos 而非自研（自研 3D/原生引擎工期数十人月不可行），且 MCP 使 AI 驱动可行 - 导出以微信小游戏格式包为统一中转，可异步离线进行，不影响实时预览体验 ### 6.7 AI 素材生成工具链 -| 环节 | 工具 | 类型 | 选用理由 | +| 环节 | 工具（现行） | 类型 | 选用理由 | |---|---|---|---| -| **图片/贴图/角色/场景** | ComfyUI（自部署） | 开源 | 节点化 workflow，支持 Flux/SDXL/ControlNet/LoRA；可训练 IP 风格模型；有 HTTP API 直接对接 Dify 节点 | -| **背景音乐/音效** | Stability Audio API | 商用 API | 6 分钟商用级音乐生成，版权清晰（全授权训练数据），API 调用即用 | +| **图片/贴图/角色/场景** | ✅ **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 开源可自部署 | -| **封面/宣传图** | ComfyUI（复用上面实例） | 开源 | 同一套基础设施，不同 workflow | +| **封面/宣传图** | ✅ **mmx-cli（复用同一 CLI）** | 商用 CLI | 同一套工具，不同 prompt | +| ~~图片/角色/场景/封面~~ | ❌ **ComfyUI（退备选）** | 开源 | 节点化 workflow、可训 IP 风格 LoRA、自部署无审查；但需 GPU（无 GPU 走 CPU 慢 10x）；mmx-cli 拍板后退为备选 | -为什么选 ComfyUI 而不是直接调 Midjourney/DALL-E API： +> **现行口径（2026-06-16）**：素材/音乐工具链 = **mmx-cli**（2026-06-12 创始人亲验拍板）。**ComfyUI 退备选**、Stability Audio 降级远期。下方"为什么选 ComfyUI"留作备选时的决策史。 + +为什么 ComfyUI 留作备选（决策史，非现行）： - ComfyUI 可**训练 IP 风格 LoRA**，生成风格一致的系列素材（角色/场景/UI） -- 节点化 workflow 可被 Dify 编排调用，形成端到端自动化 - 自部署无 API 限制/审查，游戏场景（武器/战斗）不被拒绝 -- 长期成本远低于商用 API（GPU 固定成本 vs 按次付费） +- 长期成本远低于商用 API（GPU 固定成本 vs 按次付费）——但需 GPU 基建，mmx-cli 免 GPU 即用故拍为默认 ### 6.8 内容安全 @@ -1091,30 +1115,31 @@ Cocos Creator 3.8.8 + MCP → 官方一键导出小游戏包 | **图片 NSFW/涉政/涉暴** | safe-content-ai（自部署）+ 阿里云内容安全（兜底） | 开源+商用 | 自部署做首道快检（免费/低延迟），高风险样本二次送阿里云确认 | | **文本违禁/语义** | 阿里云文本审核 | 商用 API | 违禁词库持续更新，语义理解强于规则匹配 | | **音频内容** | 阿里云音频审核 | 商用 API | 涉黄涉政语音识别 | -| **AI 输出风控** | Dify 节点内置 Guardrails | 自研规则 | Prompt 注入检测 + LLM 输出 schema 校验 | +| **AI 输出风控** | 生成链路内置 Guardrails（SAA 节点/Java 壳） | 自研规则 | Prompt 注入检测 + LLM 输出 schema 校验（~~原述 Dify 节点~~，Dify 未部署，现行落在 SAA 编排节点/Java 校验层） | ### 6.9 工具层全景图 ```mermaid graph TB - subgraph AI生成工具层 - DIFY[Dify
编排引擎] - OG[OpenGame
代码生成] - COMFY[ComfyUI
图片/素材生成] - AUDIO[Stability Audio
音乐生成] + subgraph AI生成工具层_现行 + SAA[SAA StateGraph编排
Spring AI Alibaba v1.1.2.2] + NEWAPI[new-api 网关
OpenAI兼容/多模型] + LLM[便宜LLM
DeepSeek/MiniMax] + MMX[mmx-cli
图片/音乐素材·MiniMax] VOICE[Fish Audio/CosyVoice
语音/音色] end subgraph 运行时工具层 - CANVAS_RT[自研轻量 Runtime
<15KB Canvas] - LAYA_CLI[LayaAir CLI
多渠道导出] + LJS[LittleJS 增强发行版
55KB gz·Tier1 引擎] + RUNNER[Runner v2
装载契约 game-host.d.ts] + COCOS["Cocos+MCP
(Tier2/3 渠道导出)"] SDK[WanxiangGameSDK
平台能力注入] end subgraph 安全工具层 SAFE_IMG[safe-content-ai
图片快检] ALI_SEC[阿里云内容安全
兜底确认] - GUARD[Dify Guardrails
AI输出风控] + GUARD[Guardrails
Prompt注入+输出Schema校验] end subgraph 商业化工具层 @@ -1126,18 +1151,22 @@ graph TB subgraph 基础设施工具层 YUDAO[Huijing Cloud
RBAC/BPM/文件/通知] - NACOS[Nacos
注册/配置] + NACOS["Nacos
(future-state·框架自带未部署)"] MINIO[MinIO
对象存储] JPUSH[极光推送
通知] end - DIFY --> OG & COMFY & AUDIO & VOICE - OG --> CANVAS_RT - CANVAS_RT --> SDK - CANVAS_RT --> LAYA_CLI + 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. 非功能性设计与工程治理 @@ -1148,7 +1177,7 @@ graph TB |---|---|---|---| | 游戏流首屏 | P75 < 3s | P75 < 1.5s | CDN + 预加载 + 资源压缩 + HTTP/2 | | API 平均延迟 | P95 < 500ms | P95 < 200ms | Redis 缓存 + 连接池 + 读写分离 | -| 生成任务耗时 | P50 < 60s | P50 < 30s | Dify 并行节点 + 模型优化 + 产物缓存 | +| 生成任务耗时 | P50 < 60s | P50 < 30s | SAA 图并行/条件节点 + 模型优化（new-api 多通道）+ 产物缓存（Prompt hash 命中跳 LLM） | | 并发玩家 | 1,000 DAU | 100,000 DAU | 水平扩缩 + 推荐缓存 + CDN 卸载 | | 数据库容量（行数） | 单表 < 5000 万行 | 同左 | 超过则分区/归档，事件表 → ClickHouse；QPS 目标随首次压测基线另定 | @@ -1158,11 +1187,11 @@ graph TB | 策略 | 实现 | 落地阶段 | |---|---|---| -| 服务注册/发现 | Nacos 集群（3 节点，生产） | Phase 4 | +| 服务注册/发现 | Nacos 集群（3 节点，生产）— **future-state，框架自带、MVP 未部署** | Phase 4 | | 熔断降级 | Sentinel（Huijing 集成），per-API 规则 | Phase 1 配置 | | 数据库高可用 | MySQL 主从（生产）；MVP 单节点 + 每日备份 | 上线前 | -| 消息可靠 | RocketMQ 同步刷盘 + 死信队列 + 延迟消息 | Phase 2 | -| 生成降级 | LLM 不可用 → 确定性 Fallback 生成器 | Phase 2 | +| 消息可靠 | 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 内置 | @@ -1234,7 +1263,7 @@ graph LR | 格式 | JSON 结构化（timestamp / level / trace_id / span_id / module / message / context） | | 级别 | ERROR（需人处理）/ WARN（可能需关注）/ INFO（关键链路）/ DEBUG（开发用） | | 脱敏 | Token/密码/手机号/身份证 → 脱敏后输出（`138****1234`） | -| trace_id | Gateway 入口注入，全链路透传（含 Dify/OpenGame 调用） | +| trace_id | Gateway 入口注入，全链路透传（含 SAA 编排节点 observation + new-api 调用） | | 保留 | ERROR/WARN: 90 天；INFO: 30 天；DEBUG: 仅 dev 环境 | **告警升级链**： @@ -1370,7 +1399,7 @@ main ← 始终可部署，保护分支 #### Feature Flag -| 工具 | Nacos 配置中心（MVP）→ Unleash/LaunchDarkly（正式） | +| 工具 | 本地配置/数据库开关（MVP，Nacos 框架自带未部署，future-state）→ Nacos 配置中心 / Unleash/LaunchDarkly（正式） | |---|---| | 用法 | 代码中 `if (featureFlag.isEnabled("new-recommend-algo")) { ... }` | | 管理 | admin 后台可开关，无需重新部署 | @@ -1380,16 +1409,16 @@ main ← 始终可部署，保护分支 | 扩展方向 | 预留机制 | |---|---| -| 新玩法模板 | 模板注册（Dify Workflow + 模板 JSON Schema + 示例 Prompt） | -| 新 LLM 供应商 | Dify 原生多模型管理 + 模型 A/B 测试 | +| 新玩法/能力插件 | LittleJS 能力插件注册（玩法模板层已废除 W-CLEAN，玩法/美术/关卡/UI=agent 生成域）+ Prompt Registry 示例 | +| 新 LLM 供应商 | new-api 网关多通道（OpenAI 兼容）+ 同模型降级抽检 | | 新广告联盟 | AdProvider SPI 接口 | | 新支付渠道 | PayChannel SPI 接口（Huijing 原生支持） | -| 新分发渠道 | ConversionAdapter SPI 接口 | -| 单体→微服务 | Spring Profile 控制模块加载 + Nacos 路由 | +| 新分发渠道 | ConversionAdapter SPI 接口；Tier1（LittleJS）渠道 adapter 走 W-CH-α 竞标 | +| 单体→微服务（future-state） | Spring Profile 控制模块加载 + Nacos 路由（Nacos 框架自带、MVP 未部署） | | MySQL→ClickHouse | 事件表 DAO 抽象 + 双写期 | | SDK 版本升级 | manifest 中声明 SDK 版本 + 向后兼容 + 运行时按版本加载 | | 多端适配（小程序壳/APP壳） | SDK + 宿主分离；宿主可替换为微信/抖音小程序容器 | -| Prompt 版本管理 | Dify 内置工作流版本 + 环境隔离（draft/published） | +| Prompt 版本管理 | Prompt 即第 8 契约（Git Registry）+ 环境隔离（draft/published）+ 轻量门禁 | | 生成产物缓存 | 相同 Prompt hash → 缓存命中 → 跳过 LLM 调用（节省成本/加速） | --- @@ -1398,11 +1427,11 @@ main ← 始终可部署，保护分支 | # | 风险 | 概率 | 影响 | 应对策略 | 降级方案 | |---|---|---|---|---|---| -| 1 | LLM 调用不稳定（超时/限流/幻觉） | 高 | 高 | Dify 内置重试+熔断；多供应商切换 | 确定性 Fallback 生成器 | -| 2 | 生成游戏质量不可控 | 高 | 高 | JSON Schema 强校验 + 可玩性自动测试 + 模板约束 | 质量不达标不入库 | +| 1 | LLM 调用不稳定（超时/限流/幻觉） | 高 | 高 | new-api 网关多通道切换 + 同模型降级抽检 + SAA 节点重试 + harness 九门兜底 | 确定性 Fallback 生成器 | +| 2 | 生成游戏质量不可控 | 高 | 高 | JSON Schema 强校验 + 可玩性自动测试（harness 九门）+ 插件库约束 | 质量不达标不入库（门未过不出包） | | 3 | 游戏沙箱逃逸 | 低 | 极高 | CSP + sandbox + 无网络 + postMessage 校验 | 检测到异常立即销毁 iframe | -| 4 | OpenGame 社区停更 | 中 | 中 | fork 维护 + 核心 pipeline 逻辑简单可自维护 | 退化为纯 Dify + 模板生成 | -| 5 | Dify 版本升级不兼容 | 中 | 中 | 锁定版本 + 壳层隔离 | 自部署可控 | +| 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） | 定时任务修复 + 告警 | @@ -1471,7 +1500,7 @@ gantt | 资源 | 规格 | 月费估算 | |---|---|---| | 云服务器（业务） | 4C16G × 2 | ¥1,200 | -| 云服务器（AI引擎） | 4C16G × 1（Dify + OpenGame） | ¥600 | +| 生成接入服务器（new-api 网关自部署 + 调度） | 4C16G × 1（~~原 Dify+OpenGame，现行 = new-api 网关 + SAA 进程内编排~~） | ¥600 | | MySQL RDS | 2C8G | ¥400 | | Redis | 2G | ¥200 | | OSS + CDN | 100GB 存储 + 500GB 流量 | ¥300 | @@ -1486,7 +1515,7 @@ gantt |---|---|---| | 后端工程师 | 2 | huijing 二开 + 业务模块 + API | | 前端工程师 | 1 | game-studio + game-admin 二开 | -| AI/生成工程师 | 1 | Dify 编排 + OpenGame 集成 + 质量 | +| AI/生成工程师 | 1 | SAA 裸图编排 + new-api 接入 + 便宜模型/harness 门 + 生成质量 | | 产品/运营 | 1 | PRD + 种子用户 + 审核 | | **合计** | **5 人** | | @@ -1500,8 +1529,8 @@ gantt |---|---| | GameConfig | 游戏配置 JSON，描述玩法/关卡/角色/规则 | | GamePackage | 可运行的游戏包（代码 + 资源 + manifest） | -| DAG | 有向无环图，用于描述生成工作流节点编排 | -| Game Skill | OpenGame 的经验积累机制，类似 few-shot 模板 | +| DAG / StateGraph | 有向无环图/状态图，描述生成工作流节点编排；现行由 **SAA(Spring AI Alibaba)裸 `StateGraph`** 承担（11 节点/4 条件边），~~非 Dify 可视化编排~~（Dify 未部署） | +| ~~Game Skill~~（已退役） | ~~OpenGame 的经验积累机制，类似 few-shot 模板~~——OpenGame 从未部署、降级远期，本术语仅留作历史，勿作现行依赖 | | quality_score | 基于玩家行为信号聚合的游戏质量评分 | | Feed | 游戏流推荐列表 | | Manifest | 游戏包描述文件（入口/资源列表/hash/大小） | @@ -1511,10 +1540,16 @@ gantt | 决策 | 文档位置 | |---|---| | 模块划分（13 个业务模块） | `技术架构与模块.md` | -| AI 引擎选型（Dify + OpenGame，**已降级远期增强**） | 本文 §6.2 | -| **生成主线 = 模板驱动（MVP 现行）** | C2 裁定：`docs/agent-specs/2026-06-09-generation-spike/spike-summary.md` | -| LLM 接入（D1：主 DeepSeek/备 Qwen；现行 MiniMax-M2.7 经 new-api） | `docs/agent-specs/2026-06-08-mvp业务决策.md` | -| MVP 模板集（D2：idle/tycoon/merge/clicker —— ⚠️ 与 `contracts/templates/` 现存 clicker/dodge/runner/match 不一致，**下一模板/渲染面波开工前必拍**） | 同上 + HJ-AUDIT-001 R4 | +| 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/2026-06-11-T1引擎终裁包.md` + `.agents/knowledge/tech-decisions.md` §1.1 | +| **模板 = LittleJS 能力插件；玩法模板层已废除（W-CLEAN），玩法/美术/关卡/UI=agent 生成域** | 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/2026-06-08-mvp业务决策.md` + `.agents/knowledge/tech-decisions.md` §3 | +| MVP 模板集（D2：idle/tycoon/merge/clicker —— ⚠️ 玩法模板层已随 W-CLEAN 废除、存量数据已清除；模板=LittleJS 插件） | 同上 + HJ-AUDIT-001 R4 + W-CLEAN | ### 11.3 后续文档规划 diff --git a/docs/architecture/系统概要设计-投资人版.md b/docs/architecture/系统概要设计-投资人版.md index 2f45d500..b4057f31 100644 --- a/docs/architecture/系统概要设计-投资人版.md +++ b/docs/architecture/系统概要设计-投资人版.md @@ -28,11 +28,11 @@ | 能力 | 竞品做法 | 造梦做法 | 成本对比 | |---|---|---|---| -| AI 生成引擎 | 自研（6-12 月，投入千万） | Dify 开源编排 + OpenGame 开源生成，4-6 周集成 | **节省 80% 时间和成本** | +| AI 生成引擎 | 自研（6-12 月，投入千万） | new-api 网关直连通用 LLM + 模板/插件库驱动生成，数周集成（Dify/OpenGame 列为远期增强） | **节省 80% 时间和成本** | | 后台管理系统 | 自建（3-6 月） | Huijing Cloud 开源二开，60%+ 能力开箱即用 | **节省 3 个月** | | 工作流/审核 | 自建 | Flowable 工作流引擎（Huijing 内置） | **零开发成本** | -| 多模型切换 | 绑定单一供应商 | Dify 原生支持多 LLM 热切换 | **零锁定风险** | -| 游戏运行时 | 自研重型引擎 | 自研轻量 Canvas Runtime（Tier1）+ Cocos Creator + MCP（Tier2/3，远期） | **轻量自研+成熟引擎复用，零许可费** | +| 多模型切换 | 绑定单一供应商 | new-api 网关原生支持多 LLM 热切换 | **零锁定风险** | +| 游戏运行时 | 自研重型引擎 | LittleJS 增强发行版 + Runner v2（Tier1）+ Cocos Creator + MCP（Tier2/3，远期） | **开源轻引擎+成熟引擎复用，零许可费** | **结论：同等功能，造梦的技术投入约为极逸 SOON 的 1/5，时间约为 1/3。** @@ -79,23 +79,24 @@ ### 4.1 架构策略 -**不自研大模型，不自研引擎。用开源框架组合 + 通用 LLM API 实现 SOTA 效果。** +**不自研大模型，不自研引擎。用 new-api 网关直连通用 LLM + 开源轻引擎/能力插件库组合实现 SOTA 效果。** | 组件 | 来源 | 作用 | 成本 | |---|---|---|---| -| Dify | 开源（MIT/Apache），自部署 | AI 工作流可视化编排、多模型切换、可观测 | 免费 | -| OpenGame | 开源（CUHK MMLab, 2025） | 游戏代码生成 Agent，论文验证 SOTA | 免费 | -| 通用 LLM | DeepSeek / 通义千问 / OpenAI API | 底层语言理解和代码生成 | ¥0.05-0.1/次 | -| 自研轻量 Canvas Runtime / Cocos Creator + MCP | 自研 + 开源（MIT） | 游戏运行时（Tier1 轻量自研，Tier2/3 用 Cocos，远期） | 零许可费 | +| new-api 网关 | 开源，进程外网关 | 多 LLM 统一接入、热切换、计费/配额、可观测 | 免费（仅 LLM 按次计费） | +| SAA（Spring AI Alibaba）裸图编排 | 开源，后端进程内 | AI 生成流程编排（StateGraph），无需自部署编排服务 | 免费 | +| 通用 LLM | DeepSeek / 通义千问 / MiniMax（经 new-api 网关） | 底层语言理解和代码生成 | ¥0.05-0.1/次 | +| LittleJS 增强发行版 + Runner v2 / Cocos Creator + MCP | 开源（MIT） | 游戏运行时（Tier1 开源轻引擎+宿主层，Tier2/3 用 Cocos，远期） | 零许可费 | +| Dify / OpenGame | 开源 | 可视化编排 / 代码生成 Agent（**远期增强方向，MVP 不部署**） | 远期 | ### 4.2 为什么不自研模型 | 自研模型 | 用开源组合 | |---|---| -| 需要 1000 万+ 数据标注 | OpenGame 已有训练数据和 benchmark | +| 需要 1000 万+ 数据标注 | 直接调用已训练好的通用 LLM，无需自建训练数据 | | 需要 GPU 集群（月烧百万） | 调用 API，按次计费（月几千元） | | 需要 6-12 个月出第一版 | 4-6 周核心链路跑通 | -| 模型能力绑定单一供应商 | Dify 随时切换最新最强模型 | +| 模型能力绑定单一供应商 | new-api 网关随时切换最新最强模型 | **极逸 SOON 花了 1 亿做自研模型，我们用 1/20 的成本达到同等可用性，剩下的钱花在他们没有的能力上——流量和变现。** @@ -160,7 +161,7 @@ T+1 自动入账创作者钱包（80% 分成） | 项目 | 月费 | 说明 | |---|---|---| -| 云服务器 | ¥2,400 | 3 台 4C16G（业务+AI+中间件） | +| 云服务器 | ¥2,400 | 3 台 4C16G（业务[含 SAA 进程内编排]+网关[new-api]+中间件；图片/音乐及生成 LLM 走外部 API 不占自建算力） | | 数据库 | ¥400 | MySQL RDS | | 对象存储 + CDN | ¥300 | 游戏包/素材/封面 | | LLM API | ¥1,000 | ~10,000 次生成/月 | @@ -226,7 +227,7 @@ T+1 自动入账创作者钱包（80% 分成） | 验证项 | 方法 | 预期里程碑 | |---|---|---| -| AI 生成可行性 | Dify + OpenGame 集成 demo | 第 4 周：Prompt→可玩游戏 端到端跑通 | +| AI 生成可行性 | new-api 网关直连 LLM + 模板/插件库生成 demo | 第 4 周：Prompt→可玩游戏 端到端跑通 | | 游戏流体验 | 游戏流 prototype + 10 款种子内容 | 第 8 周：滑动即玩体验可用 | | 变现链路 | 广告 SDK 集成 + 结算流程 | 第 10 周：创作者看到收益 | | 多渠道分发 | 微信小游戏导出验证 | 第 12 周：至少 1 个渠道通过审核 |