games-development-ai/docs/architecture/系统概要设计-开发团队版.md

造梦AI游戏生态平台 — 系统概要设计（开发团队版）

文档编号：HJ-ARCH-003 版本：v2.0 受众：全栈工程师 / 前端工程师 / AI 工程师 / QA 定位：开发者日常参考手册——环境搭建、模块职责、编码规范、联调协议、提交流程 生成时间：2026-06-07 前置阅读：

• 技术决策版（架构全貌）：系统概要设计-技术决策版.md
• 技术架构与模块（Doc B，13 模块）：技术架构与模块.md

---

⚠️ 状态横幅（2026-06-10 审计加注，先读 · HJ-AUDIT-001）

本档为 2026-06-07 的「10 人团队 + 微服务三仓」目标态设计，与执行现实已系统性脱节——照本档环境/命令操作会失败。日常开发权威 = .agents/rules/ + .agents/knowledge/；实操与踩坑 = docs/mvp/MVP进度总账.md + docs/memorys/。 与现实的 6 条关键差异：

1. monorepo：三仓未拆，代码在当前仓（分支 dev/x.y.z，无 main/develop，远程=阿里云 Gitea）；
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. 废弃选型（本档正文多处仍当现行栈描述，阅读时一律按现行口径折算）：
   • 生成主线 = 模板驱动 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 工具层为蓝图态——其中 Dify/OpenGame/ComfyUI/Stability Audio 已按上条折算为远期/退备选，现行生成主线见 .agents/skills/saa-graph-orchestration.md + .agents/skills/cheap-model-game-generation.md。其余章节阅读时按上述差异折算。

---

1. 快速上手

1.1 仓库结构

造梦AI 项目由 3 个独立 Git 仓库组成：

game-cloud/        后端（Huijing Cloud fork + 游戏业务模块）
game-admin/        管理后台前端（huijing-ui-admin-vue3 fork）
game-studio/       产品端前端（Vue3 + Vant，创作者+玩家）

1.2 本地环境要求

工具	版本	用途
JDK	17+	后端编译运行
Maven	3.9+	后端依赖管理
Node.js	20+	前端构建
pnpm	9+	前端包管理
Docker & Docker Compose	24+	中间件 + AI 引擎
Git	2.40+	版本控制
IDE	IntelliJ IDEA（后端）/ VS Code（前端）	开发

1.3 一键启动（本地开发）

# 1. 启动中间件（MySQL/Redis/Nacos/RocketMQ/MinIO）
cd game-cloud/deploy
docker compose -f docker-compose.middleware.yml up -d

# 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
mvn flyway:migrate -pl game-module-system-biz  # 基础表
mvn flyway:migrate -pl game-module-project-biz # 业务表
# ... 各模块依次执行

# 4. 导入 seed 数据（开发用测试账号/模板/示例游戏）
mysql -u root -p wanxiang_dev < deploy/sql/seed-dev.sql

# 5. 启动后端（单体模式，所有模块一个进程）
mvn spring-boot:run -pl game-server

# 6. 启动管理后台前端
cd game-admin && pnpm install && pnpm dev

# 7. 启动产品端前端
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）（future-state，MVP 未部署 registry）
• MinIO：http://localhost:9001（minioadmin / minioadmin）
• Dify：http://localhost:3001 / ComfyUI：http://localhost:8188 / OpenGame Agent：http://localhost:8100（future-state，MVP 不部署；现行 = new-api 网关 + SAA 裸图编排，美术/音乐 = mmx-cli）

---

2. 后端模块地图

2.1 目录结构

game-cloud/
├── game-gateway/                         # 网关（路由/限流/鉴权/CORS）
├── game-server/                          # 单体启动入口（引用所有模块）
├── game-framework/                       # 通用框架扩展
│   ├── game-common/                      #   通用工具/常量/异常定义
│   ├── game-spring-boot-starter-security/#   安全扩展（匿名 token）
│   ├── game-spring-boot-starter-mq/      #   MQ 消息定义 + 幂等消费基类
│   └── game-spring-boot-starter-test/    #   测试基类 + Testcontainers 配置
│
├── game-module-system/                   # 【Huijing】用户/权限/租户/OAuth2/短信
├── game-module-infra/                    # 【Huijing】文件/任务/日志/代码生成
├── game-module-bpm/                      # 【Huijing】工作流（Flowable）
│
├── game-module-project/                  # 游戏项目生命周期
│   ├── game-module-project-api/          #   DTO + Feign 接口 + 枚举
│   └── game-module-project-biz/          #   实现
│       ├── controller/admin/             #     后台接口（运营/管理员用）
│       ├── controller/app/              #     产品端接口（创作者用）
│       ├── service/                      #     业务逻辑
│       ├── dal/mysql/                    #     Mapper + DO
│       ├── convert/                      #     DO ↔ VO 转换器
│       └── job/                          #     定时任务
│
├── game-module-aigc/                     # AI 生成引擎
│   ├── game-module-aigc-api/
│   └── game-module-aigc-biz/
│       ├── controller/app/              #     创作者发起生成
│       ├── controller/admin/            #     模板/工作流管理
│       ├── 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/             #     质量评估
│       └── 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/            #     生成产物 → 可运行 Web 包（Tier1=LittleJS 增强发行版≈55KB gz + Runner v2 装载契约 game-host.d.ts；~~自研轻量 Runtime<15KB~~ 已废除，2026-06-12 终裁）
│       ├── service/package/             #     包存储/版本化/checksum/CDN 刷新
│       └── service/conversion/          #     多渠道导出（微信格式包为枢纽）
│           ├── WechatPackager.java      #       产出微信小游戏格式包（导出枢纽）
│           ├── DouyinAdapter.java       #       抖音自有导出接口适配
│           └── KuaishouAdapter.java     #       快手：微信格式兼容转换（无专用接口）
├── game-module-feed/                     # 游戏流/推荐/互动
├── game-module-telemetry/                # 遥测/数据
├── game-module-pay/                      # 支付/订阅
├── game-module-trade/                    # 结算/钱包
├── game-module-community/                # 社区/通知
├── game-module-ip/                       # IP/素材/版权
├── game-module-compliance/               # 合规/安全
├── game-module-biz/                      # B端业务
├── game-module-ad/                       # 广告引擎
│
└── deploy/
    ├── docker-compose.middleware.yml      # 中间件
    ├── docker-compose.ai.yml             # （future-state，MVP 不部署）Dify + OpenGame——现行生成主线 = new-api 网关 + SAA 裸图，不需此栈
    ├── docker-compose.yml                # 全栈（生产/staging）
    ├── sql/                              # 初始化 + seed
    ├── nacos/                            # Nacos 配置导入
    └── Dockerfile                        # 业务服务镜像

2.2 模块职责速查

模块	一句话	对外暴露	主要依赖
project	项目/版本/草稿/发布/审核	/app/project/**, /admin/project/**	bpm, system, infra
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
pay	充值/订阅/内购订单	/app/pay/**, /admin/pay/**	微信/支付宝 SDK
trade	广告分成/创作者钱包/提现	/app/trade/**, /admin/trade/**	pay, ad, telemetry
community	评论/关注/排行/通知	/app/community/**, /admin/community/**	project, system
ip	素材市场/版权/IP	/app/ip/**, /admin/ip/**	project, trade, compliance
compliance	内容安全/审核/RBAC	内部调用为主	外部安全 API
biz	B端定制/教育/文旅	/admin/biz/**	project, aigc, trade
ad	广告位/联盟对接/上报	/app/ad/**, /admin/ad/**	runtime, trade, telemetry

2.3 API 路径规范

/app/**    → 产品端接口（game-studio 调用），需要用户 Token
/admin/**  → 管理后台接口（game-admin 调用），需要管理员权限

URL 格式：/{端}/{模块}/{资源}/{动作}

示例：

POST   /app/aigc/generate          # 创作者发起生成
GET    /app/feed/list              # 游戏流列表
POST   /app/feed/interaction       # 点赞/收藏
GET    /app/project/my             # 我的项目
POST   /admin/project/review       # 审核操作
GET    /admin/telemetry/dashboard  # 运营看板

---

3. 前端模块地图

3.1 game-admin（管理后台）

game-admin/
├── src/
│   ├── api/game/                # 游戏业务 API 定义
│   │   ├── project.ts           #   项目管理
│   │   ├── review.ts            #   审核
│   │   ├── template.ts          #   模板管理
│   │   ├── feed.ts              #   推荐管理
│   │   ├── telemetry.ts         #   数据看板
│   │   ├── creator.ts           #   创作者管理
│   │   └── content-safety.ts    #   内容安全
│   ├── views/game/              # 游戏业务页面（二开新增）
│   │   ├── project/             #   项目列表/详情
│   │   ├── review/              #   审核队列
│   │   ├── template/            #   模板 CRUD
│   │   ├── feed/                #   精选池/降权
│   │   ├── telemetry/           #   数据看板
│   │   ├── creator/             #   创作者管理
│   │   └── content-safety/      #   违规/封禁
│   └── views/system/            # Huijing 原生（尽量不改）
├── .env.development             # 本地 API 地址
└── vite.config.ts

开发规范：

• 新增页面放 views/game/ 下，不改 Huijing 原生 views
• API 定义统一放 api/game/，使用 Huijing 的 request 封装
• 使用 Huijing 的 CRUD 组件（XTable / XForm / Dialog）保持风格一致

3.2 game-studio（产品端）

game-studio/
├── src/
│   ├── views/
│   │   ├── auth/                # 登录/注册
│   │   ├── feed/                # 游戏流（首页）
│   │   ├── play/                # 试玩/分享页
│   │   ├── creator/             # 创作工作台
│   │   │   ├── ProjectList.vue
│   │   │   ├── AssetWorkspace.vue    # 资产管理
│   │   │   ├── GameDesigner.vue      # 游戏设计/组装
│   │   │   ├── GenerationStatus.vue
│   │   │   ├── PreviewPlay.vue
│   │   │   └── PublishFlow.vue
│   │   └── profile/             # 创作者中心/数据
│   ├── components/
│   │   ├── game-runtime/        # 游戏运行时容器
│   │   │   ├── GameContainer.vue
│   │   │   ├── GameLoader.vue
│   │   │   └── DebugPanel.vue   # 调试面板（开发模式）
│   │   └── shared/
│   ├── api/                     # 后端 API 对接
│   ├── stores/                  # Pinia 状态
│   ├── sdk/                     # WanxiangGameSDK 源码
│   │   ├── core/
│   │   │   ├── lifecycle.ts
│   │   │   ├── event-bus.ts
│   │   │   ├── telemetry.ts
│   │   │   └── error-track.ts
│   │   └── plugins/
│   │       ├── ad.ts
│   │       ├── pay.ts
│   │       ├── social.ts
│   │       └── storage.ts
│   └── router/
├── public/
└── vite.config.ts

---

4. 编码规范

4.1 后端（Java）

规则	说明
包命名	com.wanxiang.huijing.game.module.{模块名}.{层}
类命名	Controller/Service/Mapper/DO/VO/DTO 后缀一致
DO	数据库映射对象，字段与数据库一一对应
VO	视图对象，面向前端，字段可裁剪/组合
DTO	模块间传输对象，定义在 -api 包中
异常处理	使用 Huijing 的 ServiceException + 错误码枚举
日志	@Slf4j，关键链路 INFO，错误 ERROR（含 trace_id）
注释	类注释 + 复杂方法注释（中文），字段注释
SQL	禁止 select *，必须指定字段；大表查询必须有索引
事务	@Transactional 只加在 Service 层，范围尽量小

错误码分配：

1-001-000-000 ~ 1-001-999-999  → system 模块
1-002-000-000 ~ 1-002-999-999  → infra 模块
1-100-000-000 ~ 1-100-999-999  → project 模块
1-101-000-000 ~ 1-101-999-999  → aigc 模块
1-102-000-000 ~ 1-102-999-999  → runtime 模块
1-103-000-000 ~ 1-103-999-999  → feed 模块
... 每个模块一个段，避免冲突

4.2 前端（TypeScript/Vue）

规则	说明
组件命名	PascalCase 单文件组件，如 GameContainer.vue
API 文件	按模块一个文件，函数名 = {HTTP方法}{资源}{动作}
状态管理	Pinia，按功能域拆 store
样式	game-admin 用 Element Plus 变量；game-studio 用 Vant + CSS Variables
类型	严格 TypeScript，禁止 any（除非有充分理由）
请求	统一使用封装的 request 实例，自动处理 Token/刷新/错误

4.3 SDK（TypeScript）

规则	说明
零依赖	SDK 不引入任何第三方库
体积预算	Core < 8KB（压缩后），每个 Plugin < 5KB
异步安全	所有对外 API 不返回 Promise（fire-and-forget）
错误隔离	每个 Plugin 内部 try-catch，不向游戏抛异常
版本兼容	新版本只增字段/方法，不删不改已有签名

---

5. Git 协作流程

5.1 分支策略

main          ← 始终可部署，保护分支
  └── develop ← 集成分支
       ├── feature/{module}-{brief}  ← 功能开发
       ├── fix/{module}-{brief}      ← Bug 修复
       └── release/x.y.z            ← 发版

5.2 日常开发流程

# 1. 从 develop 创建分支
git checkout develop && git pull
git checkout -b feature/aigc-saa-graph

# 2. 开发 + 本地测试
# ...编码...
mvn test -pl game-module-aigc-biz   # 跑单元测试

# 3. 提交（Conventional Commits）
git add .
git commit -m "feat(aigc): wire SAA StateGraph generation via new-api gateway"

# 4. 推送 + 创建 PR
git push -u origin feature/aigc-saa-graph
# 在 GitHub/Gitea 创建 PR → develop

# 5. Review + CI 通过 → Merge

5.3 Commit 规范

<type>(<scope>): <subject>

type:   feat / fix / refactor / docs / test / chore / perf
scope:  模块名（aigc / project / feed / studio / admin / sdk ...）
subject: 动词开头，简明描述（中英文均可）

示例：

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

5.4 PR 规范

## 变更内容
- [ ] 新功能 / Bug 修复 / 重构

## 影响范围
- 影响的模块：
- 影响的 API（如有变更）：
- 数据库迁移（如有）：

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过（如涉及 DB/MQ）
- [ ] 本地手工验证

## 截图/录屏（如有 UI 变更）

---

6. 联调协议

6.1 前后端联调

规则	说明
接口文档	后端 Swagger（Knife4j），地址 http://localhost:48080/doc.html
Mock	接口未就绪时，前端使用 vite-plugin-mock 本地 mock
联调环境	dev 环境共用一套后端，前端各自本地连 dev
问题跟踪	联调 bug 提 Issue，标签 联调 + 模块名
契约对齐	后端先写 -api 包的 VO/DTO，前端据此定义 TypeScript 类型

6.2 后端与 AI 引擎联调（现行 = new-api 网关 + SAA 裸图，进程内编排）

⚠️ 现行无独立 AI 引擎进程：生成全在 game-server 进程内由 SAA 裸 StateGraph 编排，仅出网调 new-api 网关。Dify/OpenGame 联调 系蓝图态、MVP 不部署。

组件	地址	联调方式
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 与宿主联调

game-studio（宿主）启动开发模式：
  → iframe 加载本地游戏包（dev server）
  → SDK postMessage 通信可在 DevTools Console 观察
  → DebugPanel 组件展示实时事件流

---

7. 测试指南

7.1 后端测试

# 单元测试（快，无外部依赖）
mvn test -pl game-module-aigc-biz

# 集成测试（需要 Docker，Testcontainers 自动启动 MySQL/Redis）
mvn verify -pl game-module-project-biz -Pintegration

# 全模块测试
mvn test

测试文件规范：

• 单元测试：src/test/java/.../XxxServiceTest.java
• 集成测试：src/test/java/.../XxxServiceIntegrationTest.java
• 测试基类：继承 game-spring-boot-starter-test 提供的 BaseDbUnitTest / BaseDbAndRedisUnitTest

7.2 前端测试

# game-studio 单元测试
cd game-studio && pnpm test

# game-studio E2E（需要后端运行）
pnpm test:e2e

7.3 SDK 测试

cd game-studio/src/sdk
pnpm test          # 单元测试（模拟 postMessage）
pnpm test:size     # 体积检查（Core < 8KB）

---

8. 部署流程

8.1 本地 → dev 环境

# push 到 develop 分支后自动触发 CI：
# 1. lint + test
# 2. build Docker image
# 3. push to registry
# 4. deploy to dev（docker compose pull + up）

8.2 dev → staging → prod

develop ──merge──→ release/x.y.z
                      │
                      ├── CI: build + test + image
                      ├── auto deploy → staging
                      ├── smoke test（自动）
                      ├── 人工验证
                      └── 审批 → deploy → prod（滚动更新）

8.3 回滚

# 方式一：镜像回退（推荐，< 5min）
docker compose pull  # 拉取指定 tag
docker compose up -d

# 方式二：Gateway 流量切回（灰度场景）
# Nacos 配置修改路由权重 → 旧版本 100%

---

9. 常见问题

问题	解决
本地启动报 Nacos 连接失败	先 docker compose -f docker-compose.middleware.yml up -d，等 Nacos 就绪
Flyway 迁移冲突	不要修改已存在的迁移文件；新建迁移解决
前端 API 401	Token 过期，重新登录；检查 .env 中后端地址
生成任务一直 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）/ 测试未更新

---

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 工具全景

工具	本地地址	对接模块	开发者需要了解的
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（音乐）	退备选（现行音乐=mmx-cli）
Fish Audio / 阿里 CosyVoice	远程 API	aigc（语音生成，备选）	音色克隆/TTS（现行语音优先 mmx-cli，本项备选）

10.2 生成编排开发流程（现行 = new-api 网关 + SAA 裸图）

⚠️ 原「Dify 开发流程」已废除——Dify 降级远期、MVP 从不部署。现行生成编排在 game-server 进程内用 SAA 裸 StateGraph，仅出网调 new-api 网关。

# 现行：改图 = 改 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 开发流程（已退备选；现行美术/音乐 = mmx-cli）

⚠️ ComfyUI 已退备选（2026-06-12 创始人亲验拍板）。现行美术/音乐 = mmx-cli（MiniMax CLI）：agent 造游戏时直接 CLI 调用，免 GPU、免训练 LoRA。以下 ComfyUI 节点流程仅留作历史/远期训风格 LoRA 时参考。

# 现行：mmx-cli 生成图片/音乐（agent 直接调用，用法见全局 skill `mmx-cli`）
#   mmx image ...   # 文生图（角色/场景/封面）
#   mmx music ...   # 音乐生成
# 用量 = quota 对账入成本台账（盯用量，创始人拍板默认走 mmx-cli）

# ── 以下为 ComfyUI（退备选，仅历史/训 LoRA 时参考）──
# open http://localhost:8188 → 拖拽节点设计 workflow → 导出 API Format JSON → POST /prompt → 轮询 /history/{prompt_id}

10.4 多渠道导出

导出枢纽 = 微信小游戏格式包。Tier1（LittleJS 增强发行版）渠道 adapter 走 W-CH-α 对比竞标（LittleJS+adapter vs Cocos 导出，HJ-CH-001；原「自研 Canvas 自做 adapter」随自研壳退役），Tier2/3（远期）用 Cocos Creator 官方一键导出。各渠道路径：

• 微信：引擎导出官方格式，直接上架。
• 抖音：抖音有自有导出接口，单独适配。
• 快手：无专用导出接口，标准路径 = 导出微信包 → 快手开发者工具「微信格式兼容转换」。 （注：LayaAir 官方导出平台清单不含快手，旧文档「一键导出快手」为事实错误。）

# Tier2/3（远期，Cocos Creator）官方一键导出微信小游戏包
# Cocos Creator → 构建发布 → 微信小游戏平台 → 构建

# Tier1（MVP，LittleJS）产出微信格式包：渠道 adapter 走 W-CH-α 竞标（~~自研 Canvas 转换器~~ 已退役）
# runtime 模块 service/conversion 承载导出枢纽（微信格式包），具体 adapter 实现待 HJ-CH-001 竞标定

# 快手：将微信格式包导入快手开发者工具做兼容转换，无一键 CLI
# 在 Java 中调用（runtime 模块）：
# ProcessBuilder/转换服务 → 异步等待 → 上传产物到 OSS

10.5 内容安全对接

# safe-content-ai 本地部署
# docker-compose.ai.yml 已包含

# 调用方式：
# POST http://localhost:8200/api/v1/detect
# Body: { "image_url": "..." } 或 multipart file
# Response: { "nsfw_score": 0.02, "label": "safe" }

# 阈值配置（Nacos）：
# safe-content.threshold.block = 0.7    # 直接拦截
# safe-content.threshold.review = 0.4   # 送人工审核
# safe-content.threshold.pass = 0.4     # 自动通过

---

11. 速查链接

资源	地址
后端 API 文档（Swagger）	http://localhost:48080/doc.html
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

---

11. 模块开发 Checklist

新增一个业务模块时，按以下清单逐项完成：

• 创建 game-module-{name}-api 和 game-module-{name}-biz 两个 Maven 模块
• 在 -api 中定义 VO / DTO / 枚举 / Feign 接口 / 错误码
• 在 -biz 中创建 controller/admin/ + controller/app/ + service/ + dal/ + convert/
• 编写 Flyway 迁移脚本 V{x.y.z}__{desc}.sql
• 在 game-server 的 pom.xml 中引入新模块依赖
• 在 Nacos 中添加模块配置（如有模块级配置）
• 编写单元测试（Service 层）
• 编写集成测试（Controller 层，含 DB）
• 在 Swagger 中验证 API 文档自动生成
• 更新本文档的模块速查表
• 通知前端同学新接口已就绪（附 Swagger 地址 + 示例 curl）