d97e194383
- 注册表: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 -- <路径>)
177 lines
17 KiB
Markdown
177 lines
17 KiB
Markdown
# 产品与架构事实蒸馏
|
||
|
||
> 蒸馏来源：`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`](./tech-decisions.md)；MVP 范围见 [`mvp-scope-and-milestones.md`](./mvp-scope-and-milestones.md)。
|
||
> **子系统现行设计+现状（深一层 SoT）**：见 `docs/agent-specs/` 子系统 canonical 活档——`引擎与运行时` / `agentic编排-SAA` / `开闸验收门-W-G1` / `渠道发行` / `studio前端设计体系` / `变现与单位经济` / `战略与合规` / `prompt治理体系-execution`；生成域=固定架构设计链；导航见 [`../../docs/agent-specs/_index.md`](../../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`](./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`](./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`](../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. 模块依赖关系
|
||
|
||
```mermaid
|
||
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`](../../docs/architecture/架构/生成引擎/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`](./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`](../rules/security-and-reliability.md)。
|