zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/.agents/knowledge/product-and-architecture.md
zizi d97e194383 docs(治理): SoT注册表+docs-gate六检门,清缩历史档126→69 
- 注册表:docs/architecture/README.md §2,37 份 canonical(frontmatter topic+canonical:true)与表双向机器对账
- 门:.agents/tools/docs-gate.py 六检(品牌根/canonical唯一/死链/入口卫生/留痕隔离/设计档申报),挂 .githooks/pre-commit(本仓已激活)+ .gitea/workflows/docs-gate.yml(待runner)+ wave-close 第8步;旧 check-deadlinks.sh 退役并入 G3
- 清缩:删 54 项历史档(plans 16/agent-specs 设计与spike 20/brainstorms 5/memorys 3/goals+作战清单完成史归档/王蓝莓design/SAA现状html/add-game-template);channel-spike 564K 代码资产迁仓级 spikes/;六件删前蒸馏已迁(代码评审16条open项→进度总账§5、prefix-cache字段表→cheap-model skill、意图基线29条→需求清单附录、九门降级rationale→验收门、A11 TODO→tech-decisions、3layer边界→littlejs-game-dev 指针)
- 修口径约90处:六处SAA『现行主线』旧标、Nacos/RocketMQ『未部署』旧述(07-01反转)、gameDefinition残留、全部死链改 git show 定位;AGENTS.md 249→136行(决策史归tech-decisions);_index 改纯在飞板;对外演示版 md→html
- 依据:docs/agent-specs/2026-07-02-文档治理-{全量普查与裁决-report,SoT注册表与治理门-设计}.md(四路普查191份md+Codex/Opus双评审必修项已折入);恢复基线 8ea97234(单档 git checkout 8ea97234 -- <路径>)
2026-07-02 14:24:12 +08:00

17 KiB
Raw Permalink Blame History

产品与架构事实蒸馏

蒸馏来源：docs/architecture/产品/商业定位.md、docs/architecture/产品/需求清单.md、docs/architecture/架构/13模块.md、docs/architecture/产品/需求模块映射.md、docs/architecture/架构/README.md、docs/architecture/架构/README.md 目的：让后续 Agent 读本篇即掌握产品定位、用户角色、分层架构、三仓库、13 模块与依赖、Huijing 复用边界、SDK 定位，不必重读原始长文档。 相关：决策见 tech-decisions.md；MVP 范围见 mvp-scope-and-milestones.md。 子系统现行设计+现状（深一层 SoT）：见 docs/agent-specs/ 子系统 canonical 活档——引擎与运行时 / agentic编排-SAA / 开闸验收门-W-G1 / 渠道发行 / studio前端设计体系 / 变现与单位经济 / 战略与合规 / prompt治理体系-execution；生成域=固定架构设计链；导航见 ../../docs/agent-specs/_index.md。本篇=速查蒸馏，重叠处以 canonical 为 SoT（见 engineering-conventions §10.5）。

1. 产品定位与差异化

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

差异化 = 全闭环：生成 + 流量 + 变现三件事同时解决。竞品各有短板：

竞品 强项 短板 绘境策略
极逸 SOON 技术最强（自研三引擎+大模型） 无流量、无变现闭环 不自研引擎，用开源组合，把钱花在流量和变现
TapTap 制造 有流量 封闭、分成低 开放多渠道、创作者拿 80% 分成
FunloomAI 有付费验证 品类窄、无流量 多模板多品类、自建游戏流

护城河不在生成引擎本身（会被大模型追平），而在：游戏流推荐数据壁垒、生成质量反馈闭环、模板/素材/工作流资产沉淀、广告位 AI 优化。

2. 用户角色与权限模型

权限自下而上继承（访客→玩家→创作者→专业创作者；运营→管理员；B 端独立）。

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

权限实现：Huijing RBAC + OAuth2 + DataPermission（创作者只看自己的项目/资产），匿名玩家通过 framework 层扩展匿名 Token。

3. 系统分层架构

⚠️ 现行口径回填（2026-06-12，单源已 commit 1272383 清毒；本蒸馏同步纠偏）：下方分层图的「AI 引擎层 / 运行时栈 / 中间件层」为 1.x 蓝图态，部分组件已非现行主线，按下列裁决读：

  • AI 引擎层：生成主线 = new-api 网关 → 便宜模型直连（agent 写码于插件库，HJ-GEN-001 终审）；Dify/OpenGame = 降级远期、从未部署（C2 / HJ-GEN-001）。agentic 编排基建 = AgentScope（2026-06-25 框架 reframe：三档统一收敛一个 agent 框架；SAA / dify / coze 降最低优先级、留作「远期适配验证可插拔」目标）——原「SAA-only，AgentScope 降 long-term premium 独立轨」(HJ-AGI-002) 已被该 reframe 推翻（SAA 当时在产是历史事实，分轨口径不再现行）。「自研编排/DAG 工作流引擎」表述作废。
  • 运行时栈 Tier1：= LittleJS 增强发行版 + Runner v2（2026-06-12 创始人终裁）；「自研 Canvas Runtime<15KB」废除；「模板双层/游戏模板（填参式整局代码）」废除（随 W-CLEAN 清）→模板=LittleJS 能力插件/二次开发件；玩法/美术/关卡/UI=agent 生成域。注：「玩法模板」（品类框架·引导生成·非填参代码）未废、有效·待建，但非最高优先级（最高=Tier 0 生成可靠，玩法模板排其后；generic 桥接 7534bdf9 暂解 limbo；HJ-DEMO-AUDIT-001 创始人 06-17）。引擎重定为正交两轴（2026-06-21·tier2 触发，推翻旧「Tier2/3=Cocos+MCP 不变」）：自治富游戏生成轨（全无头·纯代码：富 2D=Phaser/Pixi，轻量档=LittleJS）走无人值守生成循环；3D/渠道导出轴（Cocos Creator 编辑器+人在环）做复杂 3D/渠道包。旧锁定的依据「MCP 158 工具让 AI 驱动可行」是事实错——该 MCP 是编辑器扩展、需编辑器在跑、非 headless，故 Cocos 进不了自治生成轨。详见 tech-decisions.md §1.1 与 tier2 富游戏设计（并入运行时 SoT docs/architecture/架构/生成引擎/agentic运行时架构图说.md §4.2/§5）。
  • 中间件层：Nacos / RocketMQ / Sentinel = MVP 生产基建三件套，已自托管 mini-infra（2026-07-01 build-vs-buy 现货尽调采纳，推翻旧「future-state 不部署」定性——Nacos 配置中心 + 服务发现、RocketMQ 异步 gen 队列、Sentinel Java 准入侧流控；见 tech-decisions.md §10）。
接入层      CDN（静态资源/游戏包） + Nginx（前端托管/SSL 终结）
前端应用    game-studio（Vue3+Vant，创作者+玩家） / game-admin（Vue3+Element Plus，运营+管理）
网关层      Spring Cloud Gateway（路由/限流/鉴权/灰度/CORS）
业务服务层  13 个 game-module（studio/project/aigc/runtime/feed/telemetry/pay/trade/community/ip/compliance/biz/ad）
基础设施层  Huijing 原生：system（用户/权限/OAuth2） / infra（文件/任务/日志） / bpm（工作流 Flowable）
AI 引擎层   ~~Dify（DAG 编排/多模型） + OpenGame（Python 代码生成）~~（降级远期未部署，见上方回填）→ 现行=new-api 网关直连便宜模型 + AgentScope（2026-06-25 reframe：三档统一收敛一个 agent 框架；~~SAA 裸图 HJ-AGI-002~~ 降最低优先级、远期适配验证可插拔目标）；素材现行=mmx-cli（图片/音乐，2026-06-12 创始人拍板默认；~~ComfyUI 退备选~~） + Fish Audio·CosyVoice（语音/音色）
运行时栈    分层：Tier1 = ~~自研壳<15KB~~ → LittleJS 增强发行版 + Runner v2（2026-06-12 终裁，15KB 红线废除、改三层约束框架，见 tech-decisions.md §1.1）/ Tier2-3 复杂2D·3D·原生：~~统一 Cocos Creator 3.8.8+MCP~~（2026-06-21 纠正为正交两轴：自治富 2D 生成轨=Phaser/Pixi 全无头，3D/渠道导出轴=Cocos 编辑器+人在环；MCP 非 headless 进不了自治轨，见 §1.1）；导出以微信小游戏格式包为枢纽
中间件层    Nacos（配置中心 + 服务发现） / MySQL 8.0 / Redis 7 / RocketMQ 5（异步 gen 队列） / Sentinel（准入侧流控） / MinIO（本地）·阿里云 OSS（生产）（Nacos/RocketMQ/Sentinel 已自托管 mini-infra，2026-07-01 反转，见上方回填）
可观测性    Prometheus / Grafana / Sentry / Jaeger（链路追踪）

调用主线：前端 → Nginx → Gateway → 业务服务层（同时调用 Huijing 原生层与 AI 引擎层）→ 中间件层；全链路指标/日志/链路上报可观测性栈。

4. 三仓库与模块归属

绘境由 3 个独立 Git 仓库组成：

仓库 定位 面向谁 技术栈
game-cloud 统一后端（Huijing Cloud fork 二开），单体启动可平滑拆微服务 所有前端 Java 17 + Spring Cloud Alibaba + MySQL
game-admin 管理后台前端（huijing-ui-admin-vue3 fork） 运营/管理员 Vue3 + Element Plus + Vite
game-studio 产品端前端（创作+消费） 创作者/玩家 Vue3 + Vant + Vite（移动优先，适配 360-430px）

后端二开原则：不改 huijing-framework 层（通过 SPI/扩展点接入，保持可升级）；新模块遵循 huijing 规范（-api / -biz 分层，VO/DTO/DO 分离）；用 DataPermission 做数据隔离；用 bpm 驱动审核流程。包命名 com.wanxiang.huijing.game.module.{模块}.{层}。新增模块流程见 ../skills/add-business-module.md。

单体启动：13 个业务模块编译为同一 JAR（game-server），Spring Profile 控制模块加载；需独立扩缩时改 Nacos 配置即拆为独立服务（Huijing Cloud 原生支持）。

5. 13 个业务模块速查表

13 模块：含 studio（创作编排/编辑器域），aigc 为无状态生成原子；能力清单按产品功能/技术功能/映射三文档分离（见 docs/architecture/产品/需求清单.md、…-技术架构与模块.md、…-需求模块映射.md）。

模块 ID 一句话职责 面向端 被依赖
studio 创作编排/编辑器域（会话/资产图/角色 rig/对白树/任务链） studio —
project 游戏项目全生命周期（创建/版本/草稿/发布/审核/状态机） studio + admin aigc, runtime, feed, community, ip, biz, compliance
aigc 无状态生成原子（Prompt/LLM/图/音/剧情/模板/校验/风格指纹；编辑器职责已迁出 studio） studio + admin studio, runtime, biz
runtime 运行时与包交付（编译/打包/Manifest/沙箱/小游戏导出/调试） studio + admin feed, ad
feed 游戏流推荐与玩家互动（Feed/推荐/互动/举报/分享） studio + admin telemetry（反哺）
telemetry 遥测与数据智能（事件摄取/聚合/看板/质量评分/告警） studio + admin feed, aigc, trade, community
pay 支付与订阅（积分充值/会员/内购/打赏） studio + admin trade
trade 商业化与结算（广告分成/创作者钱包/素材交易/B 端收款/对账） studio + admin community（激励）, biz
community 社区与互动（评论/关注/动态/排行/成就/通知） studio + admin —
ip IP 资产与版权（素材市场/版权/IP 孵化/授权/模型训练对接） studio + admin trade
compliance 合规与安全（内容安全/审核/RBAC/审计/隐私/防沉迷/渠道合规） admin 为主 aigc, ip, biz, project
biz B/G 端业务（定制/教育/文旅/代运营/资质代办/项目管理） admin + 独立 B 端门户 —
ad 广告引擎（广告位/AI 植入/联盟对接/展示上报/eCPM 优化） studio + admin trade

模块统一对外路径规范：/app/**（产品端，需用户 Token）、/admin/**（管理后台，需管理员权限），格式 /{端}/{模块}/{资源}/{动作}。

6. 模块依赖关系

graph LR
  AIGC --> PROJECT
  RUNTIME --> PROJECT
  FEED --> PROJECT
  FEED --> TELEMETRY
  TELEMETRY --> FEED
  TRADE --> PAY
  TRADE --> AD
  AD --> RUNTIME
  IP --> PROJECT
  IP --> COMPLIANCE
  BIZ --> PROJECT
  BIZ --> AIGC
  COMMUNITY --> PROJECT
  COMPLIANCE --> PROJECT

要点：project 是全局核心被依赖项；feed 与 telemetry 互为反哺（feed 消费 quality_score，telemetry 聚合 feed 行为信号）；trade 是变现汇聚点（聚合 pay/ad/ip 收益）；compliance 横切（被 aigc/ip/biz/project 依赖）。

控制面/管理面（配置注册表 + 观测审计仓 + D12 治理门 + 管理面 UI）= 三档生成共用的治理层，横切 aigc/studio/admin（2026-06-25 框架 reframe 后三档统一收敛 AgentScope，共用同一套治理面；不再是「SAA 廉价线、tier2」两条异构基建分治）：生成线只管「从注册表读配置、向观测仓写轨迹」，配置即数据、全链可观测、可审计。控制面非关键配置经 /agent CRUD 或热取即时生效、不重新部署服务代码；关键 agent、关键玩法模板、质量与安全阈值（如 prompt 正文与生成门阈值）的变更走 yudao 配置发布审批，是受治理的「发版」。这层不在 13 模块清单里单列、而是跨模块的治理底座，设计见运行时单一真相 SoT 生成引擎/agentic运行时架构图说.md §5.2（控制面与配置热取）。

7. Huijing 原生能力复用清单（不需自研，约覆盖 MVP 后台 60%+）

Huijing 模块 对应绘境需求 复用方式
system（用户/角色/菜单/部门/租户） 多角色 + 多租户隔离 直接使用，扩展用户属性
infra-file（文件管理） 封面/素材/游戏包存储 直接使用，配 OSS/MinIO
infra-job（定时任务） 数据聚合/过期清理/质量评分 直接使用
bpm（工作流 Flowable） 发布审核/下架流程 设计流程表单，直接使用
system-notify（站内通知） 生成完成/审核结果/下架通知 直接使用
system-dict（数据字典） 游戏类型/风格标签/状态枚举 直接使用
system-operatelog（操作日志） 审核/下架/发布审计 直接使用
infra-codegen（代码生成） 加速 CRUD 开发 辅助使用
system-oauth2（OAuth2） 第三方登录（微信/手机号） 扩展 SocialType
system-sms（短信） 手机号验证码登录 直接使用

需自研的游戏领域边界（Huijing 不提供）：AI 生成引擎（aigc）、游戏运行时与包交付（runtime）、游戏流推荐（feed）、小游戏多渠道转换、遥测/质量评分（telemetry）、广告引擎（ad）、创作者结算（trade）、IP/素材市场（ip）。原则：Huijing 是"基础设施底座"而非"产品主体"。

8. 中间件清单与 Game SDK 定位

8.1 中间件

中间件 用途
MySQL 8.0 业务实体主库（Huijing 原生，事务一致性）
Redis 7 推荐候选集缓存/限流/排行/熔断状态/分布式锁/幂等去重
RocketMQ 5（MVP 生产基建，自托管 mini-infra） 异步：生成任务派发、审核通知、事件摄取、结算触发（延迟/事务/死信消息）。现状：2026-07-01 build-vs-buy 尽调反转旧「未部署」口径，已落地异步 gen 队列（生产者 + 有界消费 ≤15 + CAS 幂等）
MinIO / 阿里云 OSS 游戏包/素材/封面对象存储（本地 MinIO，生产 OSS）
Nacos（MVP 生产基建，自托管 mini-infra） 注册中心 + 配置中心（多环境/热更新/单体↔微服务切换）。现状：2026-07-01 build-vs-buy 尽调反转旧「未部署」口径，已接入服务发现（AgentScope Service 注册）+ 配置热读（middleware 热参 v1 watcher，快照兜底）
Sentinel（MVP 生产基建，自托管 mini-infra） 生成准入侧 Java 流控（FLOW_GRADE_QPS 入口投递速率闸，削洪峰）。现状：2026-07-01 反转后已接入；与 DB per-creator 配额、有界 worker 池并发上限 ≤15 三层正交（见 tech-decisions.md §10）
CDN 游戏资源/封面静态分发，hash 命名长期缓存

8.2 Game SDK（WanxiangGameSDK）

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

  • 分层：Core Layer（内联，压缩后 < 8KB，游戏启动加载：Lifecycle / EventBus / Telemetry / ErrorTrack）；Plugin Layer（按需懒加载，不影响首屏：Ad / Pay / Social / Storage / Debug）。首屏总负担 < 8KB。
  • 通信：通过 postMessage 与宿主（game-studio）通信，宿主再代理后端 API；游戏 iframe 无网络权限（广告/支付/社交均由宿主在 iframe 外部渲染）。
  • 降级铁律：核心能力（Lifecycle/Telemetry/ErrorTrack）失败即静默丢弃，游戏不受影响；非核心 Plugin（Ad/Pay/Social/Storage）失败即跳过并给兜底（如广告失败免费给奖励）。Plugin 代码全部 try-catch 包裹，异常不向游戏抛，游戏主循环（requestAnimationFrame）永不被 SDK 阻塞。
  • 与 runtime 关系：runtime 编译 GamePackage 时将 SDK Core 内联到 entry.js，在 GameConfig 声明所需 Plugin，manifest 记录 SDK 版本号；宿主据 manifest 决定加载哪些 Plugin chunk。
  • 合规定位：同意即可用、拒绝即不可用（与抖音/微信小游戏同模式，法律基础《个保法》第13条第(二)款）；识别未成年后禁广告+禁付费+限时长+最小采集。

SDK 详细接口与降级规约见 ../rules/security-and-reliability.md。