From dced7d000deae5ea4a57ac6f5a09619569972843 Mon Sep 17 00:00:00 2001 From: zizi Date: Sun, 7 Jun 2026 01:44:56 +0000 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=BB=BA=E7=AB=8B=20.agents=20?= =?UTF-8?q?Agent=20=E6=B2=BB=E7=90=86=E4=BD=93=E7=B3=BB=E4=B8=8E=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=85=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 CLAUDE.md（项目定位/目标/目录）与 AGENTS.md（工作入口指南） - 新增 .agents/{README,knowledge,rules,skills,workflows} 共 12 份能力中枢文档 - 基于 7 份架构文档蒸馏，统一 4 处源档冲突（运行时栈/成功率/工期/范围） - 全部 91 条相对交叉链接已校验通过 Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/README.md | 86 ++++++++ .agents/knowledge/glossary.md | 44 ++++ .agents/knowledge/mvp-scope-and-milestones.md | 128 +++++++++++ .agents/knowledge/product-and-architecture.md | 164 ++++++++++++++ .agents/knowledge/tech-decisions.md | 88 ++++++++ .agents/rules/engineering-conventions.md | 203 ++++++++++++++++++ .agents/rules/security-and-reliability.md | 167 ++++++++++++++ .agents/skills/add-business-module.md | 122 +++++++++++ .agents/skills/ai-generation-pipeline.md | 180 ++++++++++++++++ .agents/skills/contract-first-development.md | 102 +++++++++ .agents/skills/runtime-and-multichannel.md | 149 +++++++++++++ .agents/workflows/ai-development-protocol.md | 138 ++++++++++++ AGENTS.md | 90 ++++++++ CLAUDE.md | 64 ++++++ 14 files changed, 1725 insertions(+) create mode 100644 .agents/README.md create mode 100644 .agents/knowledge/glossary.md create mode 100644 .agents/knowledge/mvp-scope-and-milestones.md create mode 100644 .agents/knowledge/product-and-architecture.md create mode 100644 .agents/knowledge/tech-decisions.md create mode 100644 .agents/rules/engineering-conventions.md create mode 100644 .agents/rules/security-and-reliability.md create mode 100644 .agents/skills/add-business-module.md create mode 100644 .agents/skills/ai-generation-pipeline.md create mode 100644 .agents/skills/contract-first-development.md create mode 100644 .agents/skills/runtime-and-multichannel.md create mode 100644 .agents/workflows/ai-development-protocol.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 00000000..57750438 --- /dev/null +++ b/.agents/README.md @@ -0,0 +1,86 @@ +# .agents/ —— 绘境AI 项目的 Agent 能力中枢 + +> 本目录沉淀并积累项目的**全部 Agent 能力、技能与规则**，让团队在长期开发中**复利式积累知识、流程与能力**，持续提升 AI 驱动开发的**能力、准确率与稳定性**。 +> +> 工作入口指南见 [`../AGENTS.md`](../AGENTS.md)；项目定位/目标/目录见 [`../CLAUDE.md`](../CLAUDE.md)。 + +--- + +## 一、本目录是什么 + +随着项目长期、跨会话推进，零散的认知和踩坑很容易丢失，AI 每次都"从零理解"。`.agents/` 把这些沉淀成**结构化、可检索、可复用**的资产：事实蒸馏、硬约束、操作手册、元流程各归其位。**每次任务从这里取经验、向这里存经验**，能力随时间累积而非反复重置。 + +--- + +## 二、目录结构与职责 + +| 子目录 | 职责 | 回答的问题 | +|---|---|---| +| `knowledge/` | 事实与蓝图的蒸馏（产品、架构、范围、术语） | **是什么** | +| `rules/` | 必须遵守的硬约束（工程规范、安全可靠性） | **必须怎样** | +| `skills/` | 可复用操作手册 playbook（怎么做某一类事） | **怎么做** | +| `workflows/` | 元流程（如何承接、推进、收尾一个任务） | **如何承接任务** | + +### 完整文件清单 + +**knowledge/** + +| 文件 | 一句话说明 | +|---|---| +| `knowledge/product-and-architecture.md` | 产品定位、12 模块与依赖、三仓三端架构蒸馏 | +| `knowledge/tech-decisions.md` | 技术栈与关键选型理由 | +| `knowledge/mvp-scope-and-milestones.md` | MVP 的 131 项 P0 范围、里程碑与验收指标 | +| `knowledge/glossary.md` | 术语表 | + +**rules/** + +| 文件 | 一句话说明 | +|---|---| +| `rules/engineering-conventions.md` | 命名/分层/API 路径/错误码/提交/PR 等工程规范 | +| `rules/security-and-reliability.md` | 安全基线、幂等、超时重试、合规与可靠性约束 | + +**skills/** + +| 文件 | 一句话说明 | +|---|---| +| `skills/add-business-module.md` | 新增一个 game-module 业务模块的标准步骤 | +| `skills/ai-generation-pipeline.md` | AI 生成链路（Dify + OpenGame + aigc 壳）开发手册 | +| `skills/runtime-and-multichannel.md` | 运行时打包、沙箱、SDK 与多渠道导出手册 | +| `skills/contract-first-development.md` | 契约先行：契约对齐与并行解耦 | + +**workflows/** + +| 文件 | 一句话说明 | +|---|---| +| `workflows/ai-development-protocol.md` | 任务承接→分析→评审→执行→验证→沉淀的完整协议 | + +--- + +## 三、使用方式（按任务类型查阅） + +| 任务类型 | 先读 | 再读 | +|---|---|---| +| **分析** | `workflows/ai-development-protocol.md` + 相关 `knowledge/` | 原始 `docs/architecture/` 长文档 | +| **评审** | `rules/`（拿约束当尺子） + `knowledge/` | 对应 `skills/` 看实践标准 | +| **编码** | 对应 `skills/`（操作手册） + `rules/engineering-conventions.md` | `knowledge/` 对齐上下文 | +| **调试** | `knowledge/glossary.md` + 相关 `skills/` | `rules/security-and-reliability.md`（排查可靠性/幂等问题） | + +> 通用顺序：**先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进与收尾。** + +--- + +## 四、维护规则（关键） + +`.agents/` 的价值取决于是否被持续、规范地维护。务必遵守： + +1. **何时新增 vs 更新现有** + - 出现**全新主题**（新模块手册、新流程）→ 新增文件。 + - 是对已有主题的**补充/修正**→ 更新现有文件，不要另起炉灶造重复。 +2. **先查重**：新增前先检索本目录，避免重复条目和同义文件。 +3. **过时即处理**：信息失效时**立即修正或删除**，不留误导性内容；与代码/文档冲突时以已验证事实为准。 +4. **单一主题、精炼、可检索**：每个文件聚焦一个主题，用表格与要点，便于 Agent 快速定位；避免照搬源文档大段内容，做蒸馏与索引。 +5. **同步索引与交叉链接**：任何对 `.agents/` 的结构性变更（增/删/改名文件），都要**同步更新本 README 的清单**，以及 [`../AGENTS.md`](../AGENTS.md) 中相关导航与交叉链接，保持全局一致。 +6. **语言**：一律使用**简体中文**。 +7. **相对路径链接**：文件间交叉引用使用相对路径，保证仓库迁移后链接不失效。 + +> 维护本身就是任务收尾的一部分——见 [`workflows/ai-development-protocol.md`](workflows/ai-development-protocol.md) 的"沉淀"环节。 diff --git a/.agents/knowledge/glossary.md b/.agents/knowledge/glossary.md new file mode 100644 index 00000000..d9f7be18 --- /dev/null +++ b/.agents/knowledge/glossary.md @@ -0,0 +1,44 @@ +# 术语表 + +> 蒸馏来源：技术决策版 §11.1 附录术语表、§3.4 SDK 设计、§4 核心链路；能力全景；执行 spec。 +> 目的：统一项目黑话，调试/评审/编码时快速对齐。每条一句话。 +> 相关：[`product-and-architecture.md`](./product-and-architecture.md) · [`tech-decisions.md`](./tech-decisions.md) · [`mvp-scope-and-milestones.md`](./mvp-scope-and-milestones.md)。 + +| 术语 | 一句话释义 | +|---|---| +| **GameConfig** | 游戏配置 JSON，描述玩法/关卡/角色/规则；创作者通过配置（而非写 JS）驱动游戏，是安全合规可控的基础。 | +| **GamePackage** | 可运行的游戏包 = 代码 + 资源 assets + manifest；由 aigc 产出、runtime 编译打包上传 OSS。 | +| **Manifest**（GameManifest） | 游戏包描述文件，含 runtimeVersion/configUrl/入口 entry/assetList/hash/checksum/preloadPolicy/bundleSize；宿主据它加载资源与决定加载哪些 SDK Plugin。 | +| **GenerationTask** | 一次 AI 生成任务实体，记录 prompt/template_id/dify_workflow_id/retry_count/duration_ms/error_code；状态机：queued→running→succeeded/failed/timed_out/canceled。 | +| **quality_score** | 基于玩家行为信号（完成率/30s 留存/点赞率/收藏率/举报率/失败率）聚合的游戏质量评分；由 telemetry 算出，反哺 feed 推荐排序。 | +| **Feed** | 游戏流推荐列表（"像刷短视频一样发现游戏"）；MVP 用规则+行为信号排序，候选集存 Redis Sorted Set、TTL 60s、cursor 分页。 | +| **DAG** | 有向无环图，描述 AI 生成工作流的节点编排（解析→匹配→LLM→校验→资源→打包），由 Dify 可视化编排，支持条件/并行/重试。 | +| **Game Skill** | OpenGame 的经验积累机制，类似模板级 few-shot 模板，提升生成质量。 | +| **HuijingGameSDK** | 注入到每个生成游戏中的平台 SDK，是平台能力注入 iframe 沙箱游戏的**唯一通道**（无 SDK 则平台仅为静态托管）。 | +| **SDK Core** | SDK 核心层，内联到游戏入口、压缩后 < 8KB，含 Lifecycle/EventBus/Telemetry/ErrorTrack，必选；失败即静默丢弃，游戏零感知。 | +| **SDK Plugin** | SDK 插件层，按需懒加载、不影响首屏，含 Ad/Pay/Social/Storage/Debug；失败即跳过并给兜底（如广告失败免费发奖励）。 | +| **三容器策略** | 游戏流预加载机制（参考抖音）：只保留前一/当前/后一三个 iframe 容器，当前播放时预加载下一款 Manifest+关键资源，超时自动跳过下一款。 | +| **保底曝光**（bonus_new_creator） | 新创作者前 3 个作品给固定基础曝光量，避免冷启动无人可见，是创作者激励的关键。 | +| **降权**（低质降权） | 高跳出/加载失败/高举报的内容自动下调推荐权重（error_rate 为硬降权；report_rate 达阈值触发人工审核）。 | +| **idempotency_key** | 幂等键，防止"重复点击生成/重复提交/MQ 重复消费/支付回调重复"导致重复处理（Redis 5min 去重 + 状态机 + 乐观锁）。 | +| **DataPermission** | Yudao 数据权限机制，实现行级数据隔离（如创作者只看自己的项目/资产）。 | +| **单体启动** | 12 个业务模块编译为同一 JAR（game-server），用 Spring Profile 控制模块加载；需独立扩缩时改 Nacos 配置即拆为独立微服务（Yudao Cloud 原生支持）。 | +| **契约先行**（contract-first） | Day 0 先锁定 7 个契约文件（API/DB/SDK/GamePackage/事件/Dify IO/广告位）写入 `contracts/` 提交 git，各工位据此 mock 并行开发，联调延后至 Day 11。 | +| **门禁（7 道）** | 创作全链路 7 道质量/合规阻断点：①Prompt 安全 ②AI 产出合规 ③资产入库版权+风格 ④组装 Schema 完整性 ⑤编译后性能（≤10MB/首屏≤2MB/无外网） ⑥预览可玩性自测 ⑦发布终审（合规+适龄）。 | +| **Fallback 生成器**（确定性 Fallback） | LLM 不可用/超时/熔断时退化为"模板填充"的确定性生成，保证生成链路不全断。 | +| **Game SDK 降级铁律** | Plugin 层代码全部 try-catch 包裹、异常不向游戏抛；游戏主循环（requestAnimationFrame）永不被 SDK 阻塞——"游戏稳定性 > 数据完整性"。 | +| **WS1-WS5** | MVP 5 个工位：WS1 平台基座、WS2 AI 生成、WS3 运行时与分发、WS4 产品前端、WS5 数据与变现（详见 mvp-scope-and-milestones.md）。 | +| **M0-M5** | MVP 6 个里程碑：M0 契约锁定 / M1 全栈可启动 / M2 创作链路 / M3 分发链路 / M4 变现链路 / M5 MVP 交付。 | +| **三仓库** | game-cloud（后端 Yudao fork）/ game-admin（Vue3+Element Plus 管理后台）/ game-studio（Vue3+Vant 产品端），三个独立 Git 仓库。 | +| **game-module-{name}** | 游戏领域自研业务模块统一命名；12 个：project/aigc/runtime/feed/telemetry/pay/trade/community/ip/compliance/biz/ad，按 `-api`/`-biz` 分层。 | +| **三种创作模式** | 覆盖小白到专业：模式 A 一句话生成（Prompt→成品，AI 主导）、模式 B 资产驱动创作（先攒资产再组装，AI 辅助单项）、模式 C 工作流编排（专业创作者在 Dify 可视化自定义节点）。 | +| **资产空间**（Asset Workspace） | 每个创作者独立、归其所有的素材空间，含视觉/音频/设计/商业化四类资产；每类资产支持 AI 生成、手动上传、市场获取三种产出方式。 | +| **DataPermission 之外的隔离** | 匿名玩家通过 framework 层扩展的"匿名 Token"机制接入，只能浏览试玩、不能发布/收藏/进后台。 | +| **eCPM** | 每千次广告展示收益，是广告变现核心指标；平台用游戏内容标签 + 玩家画像优化 eCPM。 | +| **T+1（结算周期）** | 自有渠道广告分成次日（T+1）自动入账创作者钱包，外部渠道按月结算；满 5 元即可提现。 | +| **分成比例** | 广告收益按创作者层级分成：小白 80% / 进阶 75% / 专业 70%（投资人叙事统一口径"创作者拿 80%"）。 | +| **SLO / Error Budget** | 服务可用性目标与可消耗的不可用预算：游戏流 API 99.5%（月 3.6h）、AI 生成 99%（月 7.2h）、支付 99.9%（月 43min）。 | +| **最终一致性 + 补偿** | 跨模块写操作尽量不用分布式事务，改"本地事务 + MQ 事件 + 失败补偿"，定时任务扫描超 5 分钟"中间态"记录重试或告警。 | +| **Golden Config 回归** | 用模板标准配置样例做比对回归，确保模型/模板迭代后生成质量不退化。 | +| **trace_id** | Gateway 入口注入、全链路透传（含 Dify/OpenGame 调用与运行时 SDK）的追踪 ID，是调试与可观测的主线。 | +| **DAU** | 日活跃用户；MVP 目标 1,000 DAU，正式目标 100,000 DAU。 | diff --git a/.agents/knowledge/mvp-scope-and-milestones.md b/.agents/knowledge/mvp-scope-and-milestones.md new file mode 100644 index 00000000..a1fc6b0f --- /dev/null +++ b/.agents/knowledge/mvp-scope-and-milestones.md @@ -0,0 +1,128 @@ +# MVP 范围与里程碑事实蒸馏 + +> 蒸馏来源：`docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md`（HJ-MVP-SPEC-001，执行权威）、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`（§6 能力统计、§8 MVP 范围）、`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§1.2 指标、§9 路线）、`docs/architecture/2026-06-06-v2模块架构与MVP覆盖度.md`（PRD 覆盖核对）。 +> 目的：让后续 Agent 一篇掌握 MVP 端到端闭环、量化验收线、范围口径、5 工位分工、M0-M5 里程碑、契约先行要点。 +> 相关：架构模块见 [`product-and-architecture.md`](./product-and-architecture.md)；选型与"范围张力"见 [`tech-decisions.md`](./tech-decisions.md)；术语见 [`glossary.md`](./glossary.md)。契约先行 playbook 见 [`../skills/contract-first-development.md`](../skills/contract-first-development.md)。 + +--- + +## 1. 端到端闭环链路（一句话） + +**创作者登录 → 资产管理 → Prompt 生成 / 资产组装 → 预览试玩 → 发布 → 审核 → 游戏流推荐 → 玩家试玩 → 互动 → 分享 → 广告展示 → 收益归集 → 创作者钱包可见 → 遥测采集 → 质量评分 → 推荐优化。** + +数据回路闭环：遥测事件 → quality_score → feed 推荐排序 → 更多曝光/试玩 → 更多事件（feed 与 telemetry 互为反哺）。 + +--- + +## 2. 量化验收标准 + +| 指标 | 标准 | 出处与备注 | +|---|---|---| +| P0 能力覆盖 | **131 / 131** 项全部可用且可验证 | 执行 spec（范围由 105 扩到 131，见下文第 4 节） | +| 端到端链路 | 创作→生成→预览→发布→审核→游戏流→试玩→互动→广告→收益 全走通 | 执行 spec | +| **生成成功率** | **≥ 80%**（基于 3-5 个模板，MVP 验收线） / **≥ 85%**（技术决策版蓝图远期目标） | 两个数字并存：执行 spec §1.2 与 AI 链路验收均为 **80%**；技术决策版 §1.2/§4.1 为 **85%**。**MVP 验收按 80% 判定** | +| 游戏流首屏 | **P75 < 3s**（技术决策版另列 P95 < 6s） | 执行 spec + 技术决策版 §7.1 | +| 冒烟测试 | 核心 **5 条**链路自动化通过（`deploy/smoke-test.sh`） | 执行 spec | +| Bug 门槛 | **P0 Bug = 0**；P1 遗留 ≤ 10 个 | 执行 spec §1.2 | + +--- + +## 3. 能力总量与 MVP 范围口径 + +能力全景去重合并后共 **299 项**独立业务能力，按优先级： + +| 维度 | P0 | P1 | P2 | 合计 | +|---|---|---|---|---| +| 全平台 | **131** | 113 | 54 | **299** | + +各模块 P0 分布（合计 131）：project 11 / aigc 16 / runtime 19 / feed 16 / telemetry 16 / pay 3 / trade 7 / community 6 / ip 1 / compliance 27 / biz 5 / ad 4。 + +**两套范围口径（重要，存在张力）**： + +- **保守口径（能力全景 §8）**：MVP = **105 项 P0 核心闭环**，仅 project(11)+aigc(16)+runtime(19)+feed(16)+telemetry(16)+compliance(27)；pay/trade/community/ip/biz/ad **仅预留接口与数据模型，不实现业务逻辑**。 +- **执行口径（mvp-execution-spec）**：MVP = **131 项 P0 全量**；pay/trade/community/ip/biz/ad 的那部分 P0（共 26 项 = 3+7+6+1+5+4）也由 **WS5 真实交付**（钱包/分成/广告/站内信/B 端表单等），非仅预留接口。 + +口径取舍：**以执行 spec 的 131 全量为准**（更新、更具体）。能力全景"仅预留接口"是更早的保守范围，已被取代。张力分析见 [`tech-decisions.md`](./tech-decisions.md) §4。 + +--- + +## 4. 5 工位编制（WS1-WS5）与职责边界 + +10 人、3 周（15 工作日），每项 P0 平均 1 人天（10×15=150 人天 > 131 项，留约 19 人天缓冲）。 + +| 工位 | 代号 | 人数 | 角色 | 职责边界 | 负责 P0 数 | +|---|---|---|---|---|---| +| 平台基座 | **WS1** | 2 | 后端 Senior×2 | Yudao fork / Gateway / DB / CI-CD / **project / compliance** | 38（project 11 + compliance 27） | +| AI 生成 | **WS2** | 2 | AI 工程师 + 后端 | Dify / OpenGame / ComfyUI / **aigc** / 质量门禁 | 16（aigc） | +| 运行时与分发 | **WS3** | 2 | 后端 + 前端(SDK) | **runtime / SDK / LayaAir 导出 / feed** / 互动 / 分享 | 35（runtime 19 + feed 16）+ SDK | +| 产品前端 | **WS4** | 2 | 前端×2 | game-studio 全页面 / game-admin 审核+模板+看板（承载所有 P0 的 UI） | 全 P0 的前端表现 | +| 数据与变现 | **WS5** | 2 | 后端 + 产品运营 | **telemetry / ad / trade / pay / community / biz** / seed / 验收 | 41（telemetry16+ad4+trade7+pay3+community6+biz5） | + +> 注：WS1 38 + WS2 16 + WS3 35 + WS5 41 = 130；WS4 不重复计数（承载 UI）。源档 WS5 小标题「ad 4 / trade 7」与其下逐条列举（ad 列 5 条、trade 列 8 条）数目略有出入，属文案漂移，以实际契约为准。 + +--- + +## 4b. PRD 功能到三仓三端的覆盖（覆盖度版核对结论） + +模块架构与 MVP 覆盖度文档逐条核对 MVP PRD，结论：**三仓库 + 内部子模块拆分完整覆盖 PRD，无需第四个模块。** 关键映射示例： + +| PRD 需求块 | game-cloud 模块 | game-studio 页面 | game-admin 页面 | +|---|---|---|---| +| 自然语言/模板创作 | aigc(prompt/template/generation) | creator/CreateProject·GenerationStatus | game/template | +| 预览与轻量编辑 | runtime(compiler/package) | creator/DraftEditor·PreviewPlay | — | +| 发布/版本/状态 | project(publish+bpm·version) | creator/PublishFlow·profile/MyGames | game/review·version·project | +| 游戏流/即点即玩/互动 | feed(recommend/interaction/share)·runtime | feed/FeedPage·play/PlayPage | game/feed | +| 审核/内容安全/推荐管理 | project+bpm·compliance·feed | — | game/review·content-safety·feed | +| 账号/权限 | system(OAuth2/SMS/RBAC) | auth/ | system/（原生） | + +六处"看似遗漏"实则已覆盖：匿名玩家（framework 扩展匿名 token）、内容安全（aigc 加 `service/safety/`）、游戏运行容器（studio `components/game-runtime/` 纯前端）、CDN（deploy 配置）、数据导出（telemetry-admin 接口）、防沉迷（system 用户表加 `birthDate` 字段预留）——均无需新模块。 + +--- + +## 5. 里程碑表（M0-M5） + +| 里程碑 | 日期 | 验证标准 | 验证人 | +|---|---|---|---| +| **M0 契约锁定** | 6/9 上午 | `contracts/` 目录 **7 个**契约文件提交 git | 全员签字 | +| **M1 全栈可启动** | 6/11（Day 3） | `docker compose up` → 全服务绿灯 + Swagger 可调 project CRUD | WS1 lead | +| **M2 创作链路跑通** | 6/18（Day 8） | Prompt → AI 生成 → 预览试玩 端到端（**真 LLM，非 mock**） | WS2 lead | +| **M3 分发链路跑通** | 6/20（Day 10） | 发布 → 审核 → 游戏流 → 试玩 → 互动 → 分享 | WS3 lead | +| **M4 变现链路跑通** | 6/23（Day 11） | 广告展示 → 收益 → 钱包可见 | WS5 lead | +| **M5 MVP 交付** | 6/27（Day 15） | 种子用户走通全链路 + 冒烟全绿 + P0 Bug = 0 | 产品负责人 | + +三周节奏：**Week 1（6/9-6/13）** 基座 + 各工位基于契约 mock 独立开发；**Week 2（6/16-6/20）** 链路串通 + 功能完善（Day 10 全链路端到端走通，允许有 bug）；**Week 3（6/23-6/27）** Day 11-12 专职联调（不加新功能）→ Day 13 修 P0 Bug + 性能/安全加固 → Day 14 冒烟脚本 + demo 内容（≥10 款）→ Day 15 灰度 staging + 10 人种子内测 + 交付确认。 + +--- + +## 6. 契约先行（Day 0）与 Mock/并行解耦 + +**Day 0（6/9 上午）全员半天锁定 7 个契约文件，写入 `contracts/` 提交 git。锁定后各工位 mock 对方接口独立开发，联调统一在 Day 11 起。** + +| 契约文件 | 内容 | 负责人 | +|---|---|---| +| `api-schemas/*.yaml` | 各模块 API 的 OpenAPI 3.0 定义（Request/Response） | WS1 lead 主笔，全员 review | +| `db-schemas/V1__*.sql` | 核心表结构（Flyway 迁移脚本） | WS1 | +| `sdk-interface.d.ts` | HuijingGameSDK 全部 public API 类型 + postMessage 协议 | WS3 SDK 负责人 | +| `game-package.schema.json` | GamePackage manifest 格式 + 目录结构 | WS3 + WS2 | +| `events.schema.json` | telemetry 事件名 + 字段（v1） | WS5 | +| `dify-workflow-io.json` | Dify workflow 输入/输出契约 | WS2 | +| `ad-slot.schema.json` | 广告位配置格式 | WS5 | + +Mock 与真实对接节奏（并行解耦核心）： + +| 工位 | 依赖谁 | Mock 方式 | 真实对接 | +|---|---|---|---| +| WS4（前端） | WS1/2/3/5 的 API | `vite-plugin-mock` 基于契约 yaml 自动生成 | Day 6 起逐步替换（改 `.env` 的 `VITE_API_BASE_URL`） | +| WS3（SDK） | WS4（宿主） | 独立测试页模拟 postMessage | Day 6 集成 | +| WS2（aigc） | WS1（project） | 内存态写入 + MQ mock | Day 5 真实对接 | +| WS5（telemetry） | WS3（SDK 上报） | curl 模拟 `/events/batch` | Day 6 真实对接 | + +解耦纪律：每日 10:00 站会（每人 2 分钟）；阻塞超 30 分钟立即升级；后端新增/变更 API 必须同步更新 `contracts/api-schemas/` 并通知前端。详细 playbook 见 [`../skills/contract-first-development.md`](../skills/contract-first-development.md)。 + +--- + +## 7. MVP 交付物清单（执行 spec §10） + +`game-cloud/`（后端全模块可编译运行）、`game-admin/`（可登录可操作）、`game-studio/`（全链路可用）、`contracts/`（API/DB/SDK/事件契约）、`deploy/`（docker-compose 全栈/中间件/AI + `sql/seed-*.sql` + `smoke-test.sh`）、`docs/mvp/`（本 spec + 每日进展 changelog）。 + +**主要执行风险与应对**：Dify/OpenGame 集成超预期 → WS2 前 3 天攻坚，失败则 Day 3 切纯 Dify+模板填充；联调期 bug 过多 → Week 3 前 2 天只联调不加功能、P0 优先；广告联盟审核未过 → 先 mock 广告，真实对接可延到 MVP 后 1 周；某工位落后 → Day 5/Day 10 两次检查点，落后则他工位支援。 diff --git a/.agents/knowledge/product-and-architecture.md b/.agents/knowledge/product-and-architecture.md new file mode 100644 index 00000000..5e0d3885 --- /dev/null +++ b/.agents/knowledge/product-and-architecture.md @@ -0,0 +1,164 @@ +# 产品与架构事实蒸馏 + +> 蒸馏来源：`docs/architecture/2026-06-06-系统概要设计-投资人版.md`、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`、`docs/architecture/2026-06-06-v2架构选型审阅版.md`、`docs/architecture/2026-06-06-v2模块架构与MVP覆盖度.md`、`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md` +> 目的：让后续 Agent 读本篇即掌握产品定位、用户角色、分层架构、三仓库、12 模块与依赖、Yudao 复用边界、SDK 定位，不必重读原始长文档。 +> 相关：决策见 [`tech-decisions.md`](./tech-decisions.md)；MVP 范围见 [`mvp-scope-and-milestones.md`](./mvp-scope-and-milestones.md)；术语见 [`glossary.md`](./glossary.md)。 + +--- + +## 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） | + +权限实现：Yudao RBAC + OAuth2 + DataPermission（创作者只看自己的项目/资产），匿名玩家通过 framework 层扩展匿名 Token。 + +--- + +## 3. 系统分层架构 + +``` +接入层 CDN（静态资源/游戏包） + Nginx（前端托管/SSL 终结） +前端应用 game-studio（Vue3+Vant，创作者+玩家） / game-admin（Vue3+Element Plus，运营+管理） +网关层 Spring Cloud Gateway（路由/限流/鉴权/灰度/CORS） +业务服务层 12 个 game-module（project/aigc/runtime/feed/telemetry/pay/trade/community/ip/compliance/biz/ad） +基础设施层 Yudao 原生：system（用户/权限/OAuth2） / infra（文件/任务/日志） / bpm（工作流 Flowable） +AI 引擎层 Dify（DAG 编排/多模型） + OpenGame（Python 代码生成） + ComfyUI（图片素材） + Stability Audio / Fish Audio·CosyVoice（音频/音色） +运行时栈 自研轻量 Canvas Runtime（<15KB，Web 预览/游戏流）+ LayaAir CLI（小游戏多渠道导出）；选型理由与"Phaser3 vs 自研轻量"张力见 tech-decisions.md §1、§4 +中间件层 Nacos / MySQL 8.0 / Redis 7 / RocketMQ 5 / MinIO（本地）·阿里云 OSS（生产） +可观测性 Prometheus / Grafana / Sentry / Jaeger（链路追踪） +``` + +调用主线：前端 → Nginx → Gateway → 业务服务层（同时调用 Yudao 原生层与 AI 引擎层）→ 中间件层；全链路指标/日志/链路上报可观测性栈。 + +--- + +## 4. 三仓库与模块归属 + +绘境由 3 个独立 Git 仓库组成： + +| 仓库 | 定位 | 面向谁 | 技术栈 | +|---|---|---|---| +| **game-cloud** | 统一后端（Yudao Cloud fork 二开），单体启动可平滑拆微服务 | 所有前端 | Java 17 + Spring Cloud Alibaba + MySQL | +| **game-admin** | 管理后台前端（yudao-ui-admin-vue3 fork） | 运营/管理员 | Vue3 + Element Plus + Vite | +| **game-studio** | 产品端前端（创作+消费） | 创作者/玩家 | Vue3 + Vant + Vite（移动优先，适配 360-430px） | + +后端二开原则：不改 yudao-framework 层（通过 SPI/扩展点接入，保持可升级）；新模块遵循 yudao 规范（`-api` / `-biz` 分层，VO/DTO/DO 分离）；用 DataPermission 做数据隔离；用 bpm 驱动审核流程。包命名 `cn.huijing.game.module.{模块}.{层}`。新增模块流程见 [`../skills/add-business-module.md`](../skills/add-business-module.md)。 + +**单体启动**：12 个业务模块编译为同一 JAR（`game-server`），Spring Profile 控制模块加载；需独立扩缩时改 Nacos 配置即拆为独立服务（Yudao Cloud 原生支持）。 + +--- + +## 5. 12 个业务模块速查表 + +| 模块 ID | 一句话职责 | 面向端 | 被依赖 | +|---|---|---|---| +| project | 游戏项目全生命周期（创建/版本/草稿/发布/审核/状态机） | studio + admin | aigc, runtime, feed, community, ip, biz, compliance | +| aigc | AI 生成引擎（Prompt 解析/模板匹配/LLM 编排/DAG 工作流/生成任务） | studio + admin | 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 依赖）。 + +--- + +## 7. Yudao 原生能力复用清单（不需自研，约覆盖 MVP 后台 60%+） + +| Yudao 模块 | 对应绘境需求 | 复用方式 | +|---|---|---| +| system（用户/角色/菜单/部门/租户） | 多角色 + 多租户隔离 | 直接使用，扩展用户属性 | +| infra-file（文件管理） | 封面/素材/游戏包存储 | 直接使用，配 OSS/MinIO | +| infra-job（定时任务） | 数据聚合/过期清理/质量评分 | 直接使用 | +| bpm（工作流 Flowable） | 发布审核/下架流程 | 设计流程表单，直接使用 | +| system-notify（站内通知） | 生成完成/审核结果/下架通知 | 直接使用 | +| system-dict（数据字典） | 游戏类型/风格标签/状态枚举 | 直接使用 | +| system-operatelog（操作日志） | 审核/下架/发布审计 | 直接使用 | +| infra-codegen（代码生成） | 加速 CRUD 开发 | 辅助使用 | +| system-oauth2（OAuth2） | 第三方登录（微信/手机号） | 扩展 SocialType | +| system-sms（短信） | 手机号验证码登录 | 直接使用 | + +**需自研的游戏领域边界**（Yudao 不提供）：AI 生成引擎（aigc）、游戏运行时与包交付（runtime）、游戏流推荐（feed）、小游戏多渠道转换、遥测/质量评分（telemetry）、广告引擎（ad）、创作者结算（trade）、IP/素材市场（ip）。原则：Yudao 是"基础设施底座"而非"产品主体"。 + +--- + +## 8. 中间件清单与 Game SDK 定位 + +### 8.1 中间件 + +| 中间件 | 用途 | +|---|---| +| MySQL 8.0 | 业务实体主库（Yudao 原生，事务一致性） | +| Redis 7 | 推荐候选集缓存/限流/排行/熔断状态/分布式锁/幂等去重 | +| RocketMQ 5 | 异步：生成任务派发、审核通知、事件摄取、结算触发（延迟/事务/死信消息） | +| MinIO / 阿里云 OSS | 游戏包/素材/封面对象存储（本地 MinIO，生产 OSS） | +| Nacos | 注册中心 + 配置中心（多环境/热更新/单体↔微服务切换） | +| CDN | 游戏资源/封面静态分发，hash 命名长期缓存 | + +### 8.2 Game SDK（HuijingGameSDK） + +生成的游戏运行在 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)。 diff --git a/.agents/knowledge/tech-decisions.md b/.agents/knowledge/tech-decisions.md new file mode 100644 index 00000000..938e1973 --- /dev/null +++ b/.agents/knowledge/tech-decisions.md @@ -0,0 +1,88 @@ +# 技术决策事实蒸馏（ADR 风格） + +> 蒸馏来源：`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§6 决策记录、§6.6/6.7/6.8 工具链，最权威）、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`（§7 技术栈理由）、`docs/architecture/2026-06-06-v2架构选型审阅版.md`（§8 取舍、§11 待确认项）、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`、`docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md`（执行约束）。 +> 目的：让后续 Agent 一篇掌握"为什么这么选、放弃了什么、风险在哪、哪些还没拍板、哪些源档互相打架"。 +> 相关：架构与模块见 [`product-and-architecture.md`](./product-and-architecture.md)；范围里程碑见 [`mvp-scope-and-milestones.md`](./mvp-scope-and-milestones.md)；术语见 [`glossary.md`](./glossary.md)；红线约束见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)、[`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)。 + +总原则（一句话）：**用开源生态组合替代烧钱自研，钱与人力集中在竞品做不了的"游戏流分发 + 创作者变现闭环 + 数据驱动优化"。** 所有核心组件均开源/可替换，无单点供应商锁定。 + +--- + +## 1. 关键决策表（ADR） + +| 决策点 | 选择 | 理由 | 放弃的备选（why-not） | 风险 | +|---|---|---|---|---| +| **后端框架** | Yudao Cloud（Java 17 + Spring Cloud Alibaba），fork 二开 | 60%+ 后台能力开箱即用（RBAC/OAuth2/BPM/文件/通知/审计/代码生成/多租户）；社区活跃（60k+ star）；单体启动可平滑拆微服务 | **NestJS(Node)**：v1 验证可行但缺企业级基础设施，微服务生态弱，后台/工作流要从零建；**Go(Kratos/go-zero)**：性能好但 RBAC/BPM/代码生成无现成方案 | 绑定 Yudao 升级节奏；须守"不改 framework 层"才可升级 | +| **AI 生成引擎** | Dify（自部署，DAG 编排/多模型）+ OpenGame（Python 微服务，代码生成）+ Java 壳（任务调度） | Dify 可视化编排/多模型热切换/可观测开箱即用；OpenGame 为 CUHK MMLab 2025 SOTA、6 阶段 pipeline 论文验证、含 benchmark；组合 4-6 周跑通 vs 自研 6-12 月 | **纯自研**：6-12 月，时间不允许；**LangGraph**：纯 Python 无可视化 UI，运营无法参与编排；**Coze**：字节闭源不可控；**n8n**：通用自动化非 LLM 原生 | LLM 不稳定/幻觉（→Fallback 兜底）；OpenGame 社区停更（→fork 自维护，可退化为纯 Dify+模板）；Dify 升级不兼容（→锁版本+壳层隔离） | +| **前端** | Vue3 + Element Plus（game-admin）/ Vue3 + Vant（game-studio，移动优先适配 360-430px） | Element Plus 版是 Yudao 官方主推、社区最活跃、文档最全、二开友好度最高；Vant 适配游戏流滑动体验 | **React + Next.js**：与 Yudao 前端生态不一致，二开成本高（v1 用的就是 Next.js，v2 切 Vue3） | 两端两套组件库；C 端游戏流须独立 H5，admin 风格不适用 | +| **数据库** | MySQL 8.0 | Yudao 默认，社区方案最多，迁移成本最低；需 JSONB/全文检索时再加 PostgreSQL/ES | **PostgreSQL**：JSONB/全文检索更强但 Yudao 适配成本高 | 复杂检索能力弱，靠后续叠加 ES/PG 补 | +| **消息队列** | RocketMQ 5 | Yudao 默认集成；延迟消息/事务消息/死信队列完整，适合生成任务调度、审核通知、事件摄取、结算触发 | **Kafka**：偏大数据流、运维重，MVP 过度；**Redis Stream**：可靠性不足，无死信/事务消息 | 运维复杂度高于 Redis Stream，但生产更可靠 | +| **游戏运行时**（Web 预览/游戏流） | 自研轻量 Canvas Runtime（< 15KB） | 首屏极快（P75<3s），AI 生成纯 JS 直接可运行，平台完全控制沙箱/SDK 注入 | **Phaser 3 全栈**：纯 2D 引擎，多渠道导出弱、小游戏适配需自研；**LayaAir 全栈**：引擎 200-500KB 过重拖慢游戏流、项目结构复杂不适合 AI 生成、编辑器与"零门槛"冲突；**Cocos Creator**：偏专业引擎，项目重，AI 生成适配难 | 复杂游戏仿真能力有限（非目标，用模板约束兜底） | +| **多渠道导出** | LayaAir CLI（`layaair2-cmd`，导出工具链） | 原生支持微信/抖音/快手/OPPO/vivo 等 10+ 小游戏平台一键导出，省自研三端转换约 2 个月；导出可异步离线，不影响实时预览 | （与运行时同表的全栈方案均被否，仅取其 CLI 导出能力） | DevTool import 仍需真机验证（架构选型版列为遗留风险） | +| **AI 素材工具链** | 图片/角色/场景/封面→ComfyUI（自部署）；音乐/音效→Stability Audio API；语音/音色→Fish Audio / 阿里 CosyVoice | ComfyUI 节点化、可训 IP 风格 LoRA 出系列一致素材、可被 Dify 编排、自部署无审查/无限频、长期成本低于商用 API；Stability Audio 版权清晰（全授权训练数据）；Fish/CosyVoice 中文效果最佳、支持 few-shot 音色克隆 | 直接调 **Midjourney/DALL-E API**：无法训风格 LoRA、游戏场景（武器/战斗）易被拒、按次付费贵 | ComfyUI 需 GPU（无 GPU 走 CPU 慢 10x 或 mock/外部 API） | +| **内容安全** | 图片→safe-content-ai（自部署快检）+ 阿里云内容安全（高风险兜底确认）；文本/音频→阿里云审核 API；AI 输出→Dify Guardrails 节点 | 自部署做首道快检（免费/低延迟），高风险样本二次送阿里云确认；阿里云违禁词库持续更新、语义强于规则；Dify 节点内做 Prompt 注入检测 + 输出 schema 校验 | 单一商用 API：成本高且首道检测延迟大 | 双层链路一致性需治理；阈值（block 0.7 / review 0.4）须在 Nacos 调优 | + +补充选型（同源 §7 治理章，非主决策但已定）：Nacos（注册+配置中心，Yudao 原生）、Redis 7（候选集缓存/限流/排行/熔断/分布式锁/幂等去重）、MinIO 本地·阿里云 OSS 生产（对象存储+CDN）、Flowable/BPM（审核/发布/下架流程）、Prometheus+Grafana+Sentry+Jaeger（可观测）、Flyway（DB 迁移）、Sentinel（熔断降级）、穿山甲+优量汇（广告，覆盖 80%+ 国内移动广告市场）、ClickHouse（远期，事件量爆增后从 MySQL 迁移）。 + +存储分层口径（技术决策版 §5.2，"先简后扩"）：业务实体→MySQL 8.0；游戏包/素材/封面→MinIO/OSS；推荐候选集/热数据→Redis Sorted Set；事件流→MySQL 分区表(MVP)→ClickHouse(增长期)；搜索→MySQL FULLTEXT(MVP)→Elasticsearch(增长期)。 + +--- + +## 2. 这些选型如何服务护城河（为什么"够用即可"） + +投资人版与技术决策版口径一致：**技术深度不追第一，生态完整度追第一。** 生成能力会被通用大模型 12-18 个月追平，故选型刻意"够用、可替换、低成本"，把自研投入压在竞品的空白——游戏流分发与变现闭环。真正壁垒：① 游戏流推荐数据壁垒（真实流量积累，无法购买）② 生成质量反馈闭环（玩家数据→quality_score→优化建议→创作者迭代）③ 模板/素材/工作流资产沉淀（马太效应）④ 广告位 AI 优化（提升 eCPM）。对应的工程取舍：自研只做 feed/telemetry/runtime/SDK/变现链路，其余（后台、工作流、生成、素材、安全）全用开源/商用组合。 + +--- + +## 3. 待确认项（源档明确标注未拍板，勿当既定事实） + +来源：架构选型审阅版 §11 + 技术决策版 §1.2 指标口径。后续若已敲定，应回填本表并注明决策时间。 + +| # | 待确认项 | 候选 | 出处 | +|---|---|---|---| +| 1 | MVP 首选 LLM | 通义千问 / DeepSeek / OpenAI 兼容接口（Dify 支持热切换，可后置） | 选型审阅版 §11.1 | +| 2 | v1 运行时资产移植方式 | Canvas2D 渲染 + 小游戏转换逻辑：移植为 Java 服务，还是保留 Node 微服务 | 选型审阅版 §11.2 | +| 3 | 产品端域名方案 | game-studio 与 game-admin 同域不同路径，还是不同子域名 | 选型审阅版 §11.3 | +| 4 | MVP 登录方式 | 手机号验证码 / 邮箱+密码 / 微信扫码（均经 Yudao OAuth2/SMS 支持） | 选型审阅版 §11.4 | + +--- + +## 4. 存在张力 / 需对齐（源档之间互相打架，落地前必须以正确一份为准） + +> 这是本篇最高价值部分。多份源档由不同子代理/不同日期产出，存在三处实质冲突。建议口径：**蓝图/选型以技术决策版（HJ-ARCH-001）为准，执行/排期以 mvp-execution-spec（HJ-MVP-SPEC-001）为准。** 投资人版（HJ-ARCH-002）措辞偏旧，仅作对外叙事，不作技术依据。 + +| 张力点 | 各源档表述 | 冲突实质 | 建议以哪份为准 | +|---|---|---|---| +| **运行时技术栈** | 能力全景 + 投资人版：runtime 写 **Phaser 3 / Canvas / WebGL**；技术决策版 §6.6 + 开发团队版：改为 **自研轻量 Canvas Runtime(<15KB) + LayaAir CLI 导出**，并明确否掉 Phaser3 全栈/LayaAir 全栈/Cocos | 早期文档（Phaser3）与后期决策（自研轻量+LayaAir）不一致；能力全景/投资人版未同步更新 | **技术决策版**（最新、最完整）。代码与 `product-and-architecture.md` 已按"自研轻量 Runtime + LayaAir CLI"对齐 | +| **生成成功率指标** | 技术决策版 §1.2/§4.1：**≥ 85%**；执行 spec §1.2 验收 + AI 生成链路验收：**≥ 80%**（基于 3-5 个模板） | 蓝图目标值 vs MVP 验收值口径不同（85% 是远期目标，80% 是 3 周 MVP 验收线） | 两个都对、出处不同：**蓝图沿用 85%，MVP 验收用 80%**。验收时按 80% 判定，勿用 85% 卡 MVP | +| **时间线** | 技术决策版 §9 + 投资人版：**约 11 周（5 人，5 个 Phase）**；执行 spec：**10 人 × 3 周（15 工作日）131 项 P0 全量** | 两套并存的实施节奏（11 周/5 人 vs 3 周/10 人），人力与周期完全不同 | 执行排期**以 mvp-execution-spec 为准**（更新、最具体、含逐日计划与里程碑）；11 周版作为更宽松的备用蓝图 | +| **MVP 范围** | 能力全景 §8：**MVP = 105 项 P0 核心闭环**（project+aigc+runtime+feed+telemetry+compliance），pay/trade/community/ip/biz/ad **仅预留接口与数据模型，不实现业务逻辑**；执行 spec：**131 项 P0 全量交付**，pay/trade/community/ip/biz/ad 的部分 P0 由 WS5 真实交付 | 范围被执行 spec 从 105 扩到 131；"仅预留接口"的旧表述与"WS5 真实交付变现/社区/B 端 P0"冲突 | 执行**以 mvp-execution-spec 的 131 全量为准**；能力全景"仅预留接口"是更早、更保守的范围，已被执行 spec 取代。详见 [`mvp-scope-and-milestones.md`](./mvp-scope-and-milestones.md) | + +其他次要不一致（非阻塞，提示存在即可）：开发团队版内 Dify 端口在 §1.3 与 §10/速查链接间有 3000/3001 漂移、后端端口有 48080/48090 漂移；执行 spec §7 中 WS5「ad 4 项 / trade 7 项」的小标题与其下逐条列举（ad 实列 5 条、trade 实列 8 条）数目对不上——均属文案层面，以实际契约/Swagger 为准。 + +--- + +## 5. 关键技术风险与降级（技术决策版 §8，决策落地必读） + +每条决策都自带风险与"降级方案"——这是"够用即可、可替换"原则在工程上的兜底。摘录高/极高影响项： + +| 风险 | 概率/影响 | 应对 | 降级方案 | +|---|---|---|---| +| LLM 调用不稳定（超时/限流/幻觉） | 高/高 | Dify 重试+熔断；多供应商切换 | 确定性 Fallback 生成器（退化为模板填充） | +| 生成游戏质量不可控 | 高/高 | JSON Schema 强校验 + 可玩性自动测试 + 模板约束 | 质量不达标不入库 | +| 游戏沙箱逃逸 | 低/极高 | CSP + iframe sandbox + 无网络 + postMessage 校验 | 检测异常立即销毁 iframe | +| OpenGame 社区停更 | 中/中 | fork 维护，核心 pipeline 简单可自维护 | 退化为纯 Dify + 模板生成 | +| 广告联盟审核不通过 | 中/高 | 提前申请资质 + 内容合规前置 | 延迟广告上线，先做订阅/B 端（或先用 mock 广告） | +| MQ 重复消费致数据不一致 | 中/高 | 消息幂等消费（message_id + Redis 去重） | 定时任务修复 + 告警 | +| 第三方 SDK 数据泄露 | 低/极高 | 广告/支付 SDK 宿主侧隔离 + 最小权限 | 紧急下线第三方 SDK | + +## 6. 决策落地的关键工程参数（供选型校验，技术决策版 §4/§7） + +- **AI 生成**：生成任务状态机 queued→running→succeeded/failed/timed_out/canceled；超时 120s；失败重试 ≤2 次、超时重试 ≤1 次；队列最大积压 500（超则返回 429）；P50<60s、P95<180s。 +- **运行时沙箱**（安全铁律）：iframe `sandbox="allow-scripts allow-same-origin"` + CSP `script-src 'self'; connect-src 'none'`（游戏内零网络请求）+ postMessage 来源与 schema 双校验；资源总 ≤10MB、首屏 ≤2MB；加载超时 5s 自动跳过+降权。 +- **推荐打分**（规则非 ML）：`Score = w1·quality_score + w2·freshness + w3·interaction_rate − w4·skip_rate − w5·error_rate − w6·report_rate + bonus_new_creator + bonus_featured`；候选集 Redis Sorted Set、TTL 60s、cursor 分页。 +- **幂等四场景**：重复点生成→idempotency_key（Redis 5min）；MQ 重复→message_id 去重集合；支付回调重复→订单状态机+乐观锁（version）；发布重复→version 唯一约束+状态前置校验。 + +## 7. 不做（明确非目标，技术决策版 §1.3） + +不做 3D 开放世界生成；不做专业级游戏引擎（Unity/Unreal 级）；MVP 不做海外市场；不做完全开放式代码生成（用模板约束保证稳定与合规——创作者通过**配置**而非写 JS 驱动游戏）；不自研大模型（接入通用 LLM + 开源 Agent 框架）。 diff --git a/.agents/rules/engineering-conventions.md b/.agents/rules/engineering-conventions.md new file mode 100644 index 00000000..9f04f444 --- /dev/null +++ b/.agents/rules/engineering-conventions.md @@ -0,0 +1,203 @@ +# 工程编码与协作硬规范 + +> 本文是绘境AI 全栈工程师 / 前端 / AI 工程师 / QA 必须遵守的**硬规则**。违反即不通过 review。 +> 蒸馏来源：`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§4 编码 / §5 Git / §6 联调 / §7 测试 / §11 Checklist）、`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§7.6-7.8 工程治理）、`docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md`（§8 技术约束）。 +> 配套：可靠性/安全红线见 [`security-and-reliability.md`](security-and-reliability.md)；元流程见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)；事实蓝图见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；模块落地手册见 [`../skills/add-business-module.md`](../skills/add-business-module.md)。 + +--- + +## 1. 后端（Java）编码规范 + +| 规则 | 硬要求 | +|---|---| +| 包命名 | `cn.huijing.game.module.{模块}.{层}`，如 `cn.huijing.game.module.aigc.service`。模块名小写，与 `game-module-{模块}` 一致 | +| 类命名 | 后缀严格统一：`XxxController` / `XxxService`+`XxxServiceImpl` / `XxxMapper` / `XxxDO` / `XxxVO` / `XxxDTO` | +| 异常处理 | 业务异常一律 `throw exception(错误码枚举)`（Yudao `ServiceException`），禁止裸抛 `RuntimeException`、禁止吞异常返回 null | +| 日志 | 类上 `@Slf4j`；关键链路成功 INFO、失败 ERROR，错误日志必须含 `trace_id` 与关键业务 ID（如 `taskId`/`versionId`） | +| 注释 | 类注释 +复杂方法注释 +字段注释，**一律简体中文**；对外接口、错误路径、补偿逻辑必须有注释 | +| 事务 | `@Transactional` **只加在 Service 层**，范围尽量小；事务内禁止远程调用（Feign/HTTP/MQ 发送放事务提交后） | + +### 1.1 DO / VO / DTO 分层语义（不可混用） + +| 类型 | 定位 | 所在包 | 约束 | +|---|---|---|---| +| **DO** | 数据库映射对象，字段与表一一对应 | `-biz` 的 `dal/dataobject` | 不出现在 Controller 出入参；不做业务组合 | +| **VO** | 视图对象，面向前端，可裁剪/组合 | `-biz` 的 `controller/.../vo` | 仅 Controller 层使用；分 `ReqVO`/`RespVO` | +| **DTO** | 模块间传输对象（Feign 契约） | **`-api` 包** | 跨模块共享，消费方引用 `-api`，不得引用对方 `-biz` | + +### 1.2 SQL 规范 + +- 禁止 `select *`，必须显式列出字段。 +- 大表查询必须命中索引；`WHERE`/`ORDER BY`/`JOIN` 字段需有对应索引，新查询要确认执行计划。 +- 分页用游标或 `LIMIT`；禁止深分页 `LIMIT 100000,20` 这类全表扫描。 +- 复杂查询走 MyBatis XML，简单 CRUD 用 MyBatis-Plus。 + +### 1.3 错误码分配（每模块独占一段，禁止冲突） + +错误码格式 `1-{模块段}-{业务}-{细分}`，各模块独占一段： + +| 段 | 模块 | 段 | 模块 | +|---|---|---|---| +| `1-001-***-***` | system | `1-104-***-***`（推断顺延） | telemetry | +| `1-002-***-***` | infra | `1-105-***-***`（推断顺延） | pay | +| `1-100-***-***` | project | `1-106-***-***`（推断顺延） | trade | +| `1-101-***-***` | aigc | `1-107-***-***`（推断顺延） | community | +| `1-102-***-***` | runtime | `1-108-***-***`（推断顺延） | ip | +| `1-103-***-***` | feed | `1-109-***-***`（推断顺延） | compliance | +| `1-002-***-***` 之后 | bpm 等 Yudao 原生沿用 Yudao 既有段 | `1-110 / 1-111-***-***`（推断顺延） | biz / ad | + +> 源档明确给出 system/infra/project/aigc/runtime/feed 六段；其余模块按"每模块一段顺延"规则分配（推断），新增模块时在 `-api` 的错误码常量类登记，避免与既有段重叠。 + +--- + +## 2. 前端（TypeScript / Vue）编码规范 + +| 规则 | 硬要求 | +|---|---| +| 组件命名 | PascalCase 单文件组件，如 `GameContainer.vue` | +| API 文件 | 按模块一个文件（`api/game/project.ts`）；函数名 = `{HTTP方法}{资源}{动作}`，如 `getProjectList` / `postProjectPublish` | +| 状态管理 | Pinia，**按业务域拆 store**（一个域一个 store，禁止 god store） | +| 样式 | `game-admin` 用 Element Plus 变量；`game-studio` 用 Vant + CSS Variables（移动优先，适配 360-430px） | +| 类型 | 严格 TypeScript，**禁止 `any`**（必须用时注释说明充分理由） | +| 请求 | 统一使用封装的 `request` 实例，自动处理 Token 注入 / Refresh 刷新 / 错误提示；禁止裸 `fetch`/`axios` | + +> admin 二开：新页面放 `views/game/`、API 放 `api/game/`，复用 Yudao CRUD 组件（`XTable`/`XForm`/`Dialog`），不改 Yudao 原生 views。 + +--- + +## 3. SDK（HuijingGameSDK，TypeScript）编码规范 + +| 规则 | 硬要求 | +|---|---| +| 零依赖 | SDK **不引入任何第三方库** | +| 体积预算 | Core（Lifecycle+EventBus+Telemetry+ErrorTrack）压缩后 **< 8KB**；每个 Plugin **< 5KB**（Ad<5 / Pay<3 / Social<4 / Storage<2 / Debug<15，仅 dev）；首屏只加载 Core | +| 异步安全 | 所有对外 API **不返回 Promise**（fire-and-forget），零同步等待，不占游戏主线程 | +| 错误隔离 | 每个 Plugin 内部 `try-catch`，**异常绝不向游戏抛**；游戏主循环（requestAnimationFrame）永不被 SDK 阻塞 | +| 版本兼容 | 新版本**只增字段/方法，不删不改已有签名**；semver 管理，manifest 记录版本号 | + +> SDK 降级铁律与合规定位（同意即可用/未成年保护）属可靠性红线，详见 [`security-and-reliability.md`](security-and-reliability.md)。 + +--- + +## 4. 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` | 运营看板 | + +> 权限在网关 +注解双重校验；`/app/**` 走用户 Token + DataPermission（创作者只见自己数据），`/admin/**` 走 RBAC。前端不可作为唯一边界，详见 [`security-and-reliability.md`](security-and-reliability.md)。 + +--- + +## 5. API 契约与版本管理 + +| 维度 | 规则 | +|---|---| +| URL 版本 | URL Path 版本 `/api/v1/...`，大版本不兼容才升 `v2` | +| 兼容判定 | **新增字段不算 breaking**；删除/重命名字段 = 新版本 | +| 并行期 | 新版本上线后，旧版本**保留 ≥ 3 个月**；废弃用 Header `Deprecation: true` + `Sunset: ` | +| 服务间契约 | 每个模块 `-api` 包声明 **Feign 接口 + DTO**，消费方引用该包；API 变更必须在 PR 描述标注受影响的消费方 | +| 契约对齐 | 后端**先写 `-api` 的 VO/DTO**，前端据此定义 TS 类型；联调前锁定契约（见 [`../skills/contract-first-development.md`](../skills/contract-first-development.md)） | + +### 5.1 事件 Schema 版本（telemetry / MQ 事件） + +| 规则 | 说明 | +|---|---| +| 带版本号 | 每个事件类型带 `schema_version`（如 `game_play_start.v2`） | +| 向后兼容 | 新增字段给默认值；老消费者忽略未知字段 | +| 不兼容变更 | 用新事件名（如 `game_play_start_v3`），新老并行消费直到老版本下线 | + +--- + +## 6. Git 协作规范 + +### 6.1 分支策略 + +``` +main ← 始终可部署，保护分支（禁直推） + └── develop ← 集成分支，CI 通过才能合入 + ├── feature/{module}-{brief} ← 功能开发（MVP 期可用 feature/{ws}-{module}-{brief}） + ├── fix/{module}-{brief} ← Bug 修复 + └── release/x.y.z ← 发版（冻结后只修 bug） +``` + +### 6.2 Commit 规范（Conventional Commits） + +``` +(): +type: feat / fix / refactor / docs / test / chore / perf +scope: 模块名（aigc / project / feed / studio / admin / sdk ...） +subject: 动词开头，简明描述（中英文均可） +``` + +示例：`feat(aigc): integrate Dify workflow API for game generation`、`fix(feed): cursor pagination returns duplicate games`。 + +### 6.3 PR 规范 + +- 单次 **< 500 行**变更，超过必须拆分。 +- **至少 1 人 review + CI 通过**（main 强制）才能合入。 +- PR 描述模板要点： + +| 区块 | 必填内容 | +|---|---| +| 变更内容 | 新功能 / Bug 修复 / 重构 | +| 影响范围 | 影响的模块 / 影响的 API（如变更）/ 数据库迁移（如有） | +| 测试 | 单元测试通过 / 集成测试通过（涉及 DB/MQ）/ 本地手工验证 | +| 截图 | UI 变更附截图或录屏 | + +--- + +## 7. 测试规范（测试金字塔） + +| 层级 | 覆盖范围 | 工具 | 运行时机 | 目标覆盖率 | +|---|---|---|---|---| +| 单元 | Service / Util / Validator | JUnit 5 + Mockito | 每次 push | 核心逻辑 **> 80%** | +| 集成 | Controller + DB + MQ + 外部 API | Testcontainers（MySQL/Redis/RocketMQ） | PR merge | 核心链路 **100%** | +| E2E | 前端→后端→DB 全链路 | Playwright（前端）+ RestAssured（API） | 部署 staging 后 | 核心 happy path | +| 性能 | API 吞吐/延迟/并发 | k6 / wrk | Phase 3 末 + 上线前 | 满足性能指标 | +| 安全 | OWASP Top 10 / 渗透 | ZAP + 人工渗透 | 上线前 + 季度 | 无 Critical/High | + +**硬约束**： + +- 测试文件命名：单元测试 `XxxServiceTest.java`，集成测试 `XxxServiceIntegrationTest.java`。 +- 测试基类：继承 `game-spring-boot-starter-test` 的 `BaseDbUnitTest` / `BaseDbAndRedisUnitTest`。 +- **单测应 Mock 外部依赖**；需要真 DB 的场景一律用集成测试（Testcontainers），不要让单测连真库。 + +--- + +## 8. 数据库迁移规范（Flyway） + +| 规则 | 硬要求 | +|---|---| +| 命名 | `V{版本号}__{描述}.sql`，如 `V1.0.0__create_game_project.sql` | +| 只增不回滚 | 已合入的迁移文件**禁止修改**；需回滚则写**新的补偿迁移** | +| DDL/DML 分开 | 结构变更与数据变更拆成不同迁移文件 | +| CI 阻断 | CI 阶段执行 `flyway validate`，不通过则阻断合入 | +| 大表变更 | 用 `gh-ost` / `pt-online-schema-change` **不锁表** | + +--- + +## 9. 模块开发 Checklist + +新增一个业务模块时按下列清单逐项完成（**完整 playbook 见 [`../skills/add-business-module.md`](../skills/add-business-module.md)**）： + +- [ ] 创建 `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（Knife4j）验证 API 文档自动生成 +- [ ] 更新模块速查表，并通知前端接口就绪（附 Swagger 地址 + 示例 curl） diff --git a/.agents/rules/security-and-reliability.md b/.agents/rules/security-and-reliability.md new file mode 100644 index 00000000..4d48fc7c --- /dev/null +++ b/.agents/rules/security-and-reliability.md @@ -0,0 +1,167 @@ +# 安全、合规、可靠性与一致性硬底线 + +> 本文是绘境AI 不可逾越的**红线**。涉及安全、合规、幂等、一致性、可靠性、可观测性与 SDK 降级。任何设计/实现违反即驳回。 +> 蒸馏来源：`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§3.4 SDK 降级 / §7.1-7.5 非功能 / §8 风险）、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§4.2 / §10.5 内容安全）、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`（§3.10 compliance 27 项 P0）。 +> 配套：编码/契约规范见 [`engineering-conventions.md`](engineering-conventions.md)；元流程见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)；事实蓝图见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；运行时/沙箱手册见 [`../skills/runtime-and-multichannel.md`](../skills/runtime-and-multichannel.md)。 + +--- + +## 1. 安全基线 + +| 层面 | 措施 | 落地阶段 | +|---|---|---| +| 接入防护 | WAF（阿里云/Cloudflare）+ DDoS 高防 | 上线前 | +| 传输 | 全站 HTTPS + HSTS + TLS 1.3 | Phase 1 | +| 鉴权 | OAuth2 + JWT + **Refresh Token 轮换（access 7天 / refresh 30天）** | Phase 1 | +| 权限 | RBAC + **DataPermission（创作者只看自己的项目/资产）** | Phase 1 | +| 游戏沙箱 | `iframe sandbox` + CSP + postMessage 来源校验 + schema 校验 | Phase 2 | +| 内容安全 | 四类检测：文本 / 图片 / AI 输出 / 音频 | Phase 2 | +| 注入防护 | Prompt 注入检测 + SQL 参数化 + XSS 过滤 + **SSRF 白名单**（内网 IP 阻断） | Phase 1 | +| 密钥管理 | Nacos 加密 / K8s Secret，**密钥 90 天轮换**；禁止硬编码进代码 | Phase 1 | +| 审计 | 全量操作日志 + **保留 180 天** + 关键操作实时告警 | Phase 1 | +| 渗透测试 | 上线前一次 + **每季度一次**，无 Critical/High 才放行 | 上线前 / 季度 | + +> **权限必须在可信边界（网关 + 服务端）强制，前端不是边界。** 匿名玩家只能浏览试玩，不能发布/收藏/进后台。 + +### 1.1 游戏沙箱具体配置（runtime / compliance 共守） + +- `iframe sandbox="allow-scripts allow-same-origin"`。 +- CSP：`script-src 'self'; connect-src 'none'`（**游戏内禁止任何网络请求**）。 +- postMessage：校验来源 origin 在白名单 + 消息 schema 校验，防伪造。 +- 资源总大小 ≤ 10MB，首屏 ≤ 2MB；创作者通过**配置（非代码）**驱动游戏，平台对运行时代码有完全控制权。 + +### 1.2 内容安全分层（自部署快检 + 商用兜底） + +- 第一道：`safe-content-ai`（自部署）快检——免费、低延迟。 +- 第二道：高风险样本送**阿里云内容安全**二次确认；文本/音频审核走阿里云 API；AI 输出走 Dify 节点内置 Guardrails。 +- 阈值（Nacos 配置）：**block = 0.7（直接拦截）/ review = 0.4（送人工）/ pass < 0.4（自动通过）**。 + +--- + +## 2. 创作链路 7 道门禁 + +在创作全链路设置 7 道门禁，确保产出质量与平台安全，缺一不可： + +| 门禁 | 检测内容 | 阻断条件 | 责任模块 | +|---|---|---|---| +| ① Prompt 安全 | 违禁词 / 敏感意图 / 注入攻击 | 命中 → 拒绝 + 提示修改 | compliance | +| ② AI 产出合规 | 图片涉黄涉暴 / 文本违规 / 音频侵权 | 不通过 → 不入库 | compliance | +| ③ 资产入库 | 版权声明完整 / 与 IP 库比对 / 文件安全 | 疑似侵权 → 冻结 + 人工复核 | ip | +| ④ 组装完整性 | GameConfig JSON Schema / 必填字段 / 资源引用有效 | 缺失 → 编译失败 + 提示 | runtime | +| ⑤ 性能门禁 | **包 ≤10MB / 首屏 ≤2MB / 无外部网络请求** | 超限 → 阻断 + 优化建议 | runtime | +| ⑥ 可玩性自测 | 加载成功 / 启动成功 / 30s 无崩溃 / 结束事件触发 | 失败 → 阻断发布 | runtime | +| ⑦ 发布终审 | 标题/简介/封面/标签/适龄/全链路合规汇总 | 人工或自动决策 | bpm + compliance | + +--- + +## 3. 幂等性（写操作必须幂等） + +| 场景 | 问题 | 方案 | +|---|---|---| +| 用户重复点击"生成" | 重复创建生成任务 | 前端防抖 + 后端 **`idempotency_key`（Redis 5min 去重）** | +| MQ 重复消费 | 同一消息处理多次 | 每条消息携带 `message_id`，消费前查 **Redis SET 已处理集合（5min TTL）** | +| 支付回调重复 | 重复入账 | **订单状态机 + 乐观锁（version 字段）**，已完成订单不可重入 | +| 发布重复提交 | 重复创建审核流程 | `project_version` **唯一约束 + 状态前置校验** | + +--- + +## 4. 分布式一致性 + +**原则：尽量避免分布式事务，用最终一致性 + 补偿替代。** + +| 场景 | 涉及模块 | 方案 | +|---|---|---| +| 生成成功 → 写版本 + 扣积分 | aigc → project + pay | 本地事务写版本 + MQ 通知扣积分；扣积分失败 → 补偿（标记版本待支付） | +| 审核通过 → 上架 + 刷新 feed | bpm → project + feed | 审核通过本地事务写状态 + MQ 广播 feed 刷新缓存 | +| 支付成功 → 发货 + 通知 | pay → project/ad + community | 支付本地事务 + MQ 事件扇出（各模块独立消费） | + +> **兜底机制（必做）**：定时任务扫描"中间态"超 **5 分钟**的记录 → 自动重试或告警。任何跨模块写都要能被对账扫描发现。 + +--- + +## 5. SLO 与可靠性策略 + +### 5.1 SLO 与 Error Budget + +| 服务 | SLO | Error Budget（月） | +|---|---|---| +| 游戏流 API | **99.5%** 可用 | 3.6 小时 | +| AI 生成 | **99%**（允许更高失败率） | 7.2 小时 | +| 支付 | **99.9%** | 43 分钟 | + +### 5.2 可靠性策略 + +| 策略 | 实现 | 落地阶段 | +|---|---|---| +| 熔断降级 | **Sentinel**（Yudao 集成），per-API 规则 | Phase 1 | +| 生成降级 | LLM 不可用 → **确定性 Fallback 生成器**（模板填充） | Phase 2 | +| 游戏加载降级 | 加载超时 **5s → 自动跳过** + 错误记录 + 降权 | Phase 3 | +| 数据库高可用 | MySQL **主从（生产）**；MVP 单节点 + 每日全量备份 + binlog | 上线前 | +| 消息可靠 | RocketMQ **同步刷盘 + 死信队列** + 延迟消息 | Phase 2 | +| 回滚 | 每次部署**保留前 3 个版本镜像，5 分钟内可回退** | CI/CD 内置 | + +> 凡涉及外部服务、异步任务、支付、通知、文件、模型调用、远程 API，都必须处理**超时、失败、重试、幂等、补偿**五件事。 + +--- + +## 6. 可观测性与日志规范 + +| 规则 | 硬要求 | +|---|---| +| 格式 | JSON 结构化：`timestamp / level / trace_id / span_id / module / message / context` | +| 级别 | ERROR（需人处理）/ WARN（需关注）/ INFO（关键链路）/ DEBUG（仅 dev） | +| 脱敏 | Token / 密码 / 手机号 / 身份证 **脱敏后输出**（如 `138****1234`），禁止明文落日志 | +| trace_id | **网关入口注入，全链路透传**（含 Dify / OpenGame 调用），调试模式贯穿生成→编译→加载→运行 | +| 保留 | ERROR/WARN **90 天**；INFO **30 天**；DEBUG 仅 dev | + +**告警升级链**： + +| 级别 | 条件 | 通知方式 | 响应时间 | +|---|---|---|---| +| P0 Critical | 服务不可用 / 数据丢失 / 安全事件 | 电话 + 短信 + 群 | 5 分钟 | +| P1 High | 5xx > 2% / 生成成功率 < 70% / 支付异常 | 短信 + 群 | 15 分钟 | +| P2 Medium | P95 > 800ms / MQ 积压 > 500 / 错误率上升 | 群通知 | 1 小时 | +| P3 Low | 非核心模块降级 / 日志异常增长 | 群通知 | 工作时间 | + +--- + +## 7. SDK 降级铁律（HuijingGameSDK） + +SDK 是平台能力注入 iframe 沙箱游戏的唯一通道，其稳定性直接决定游戏体验，**铁律不可破**： + +| 分类 | 模块 | 失败时游戏行为 | 用户感知 | +|---|---|---|---| +| **核心（异步不阻塞）** | Lifecycle / Telemetry / ErrorTrack | 上报失败 → **静默丢弃**，游戏不受影响 | 零感知 | +| **非核心（失败即跳过）** | Ad | 加载失败/超时 → **跳过广告，给玩家免费奖励** | "广告不可用，已赠送奖励" | +| **非核心（失败即跳过）** | Pay | 网络异常 → 提示稍后重试，**不阻断游戏** | toast 提示 | +| **非核心（失败即跳过）** | Social | 排行/好友失败 → 展示本地缓存或空态 | 功能降级，可继续玩 | +| **非核心（失败即跳过）** | Storage | 云存档失败 → **回退 localStorage** | 换设备可能丢进度 | + +**编码铁律**： + +- Plugin 层每个调用都包裹 `try-catch`，**异常绝不向游戏抛**。 +- 每个 Plugin 调用带 **5s 超时**（`Promise.race([fn(), timeout(5000)])`），失败返回 fallback 让游戏继续。 +- **游戏主循环（requestAnimationFrame）永远不被 SDK 阻塞**；Core 上报失败静默丢弃（稳定性 > 数据完整性）。 +- 广告/支付/社交 SDK 在**宿主侧 iframe 外部**运行（游戏 iframe 无网络权限），游戏只通过抽象 API 触发。 + +**合规定位**： + +- **同意即可用，拒绝即不可用**（与抖音/微信小游戏同模式，法律基础《个保法》第13条第(二)款）。 +- **识别未成年人后**：禁止广告展示 + 禁止付费 + 限制时长 + 最小数据采集（实名认证后触发）。 +- 隐私政策注册前强制展示，列出 SDK + 第三方 SDK（穿山甲/优量汇/微信支付等）采集的数据类型/用途/保留期；提供数据删除权入口。 + +--- + +## 8. 关键技术风险与应对 + +| # | 风险 | 概率/影响 | 应对 | 降级方案 | +|---|---|---|---|---| +| 1 | LLM 调用不稳定（超时/限流/幻觉） | 高/高 | Dify 内置重试+熔断 + 多供应商切换 | 确定性 Fallback 生成器 | +| 2 | 生成游戏质量不可控 | 高/高 | JSON Schema 强校验 + 可玩性自动测试 + 模板约束 | 质量不达标不入库 | +| 3 | 游戏沙箱逃逸 | 低/极高 | CSP + sandbox + 无网络 + postMessage 校验 | 检测异常立即销毁 iframe | +| 4 | OpenGame 社区停更 | 中/中 | fork 维护 + 核心 pipeline 可自维护 | 退化为纯 Dify + 模板生成 | +| 5 | Dify 版本升级不兼容 | 中/中 | 锁定版本 + 壳层隔离 | 自部署可控 | +| 6 | 广告联盟审核不通过 | 中/高 | 提前申请资质 + 内容合规前置 | 延迟广告上线，先做订阅/B端 | +| 7 | MQ 重复消费致数据不一致 | 中/高 | 消息幂等消费（§3） | 定时任务修复 + 告警 | +| 8 | 分布式事务部分失败 | 中/高 | 最终一致性 + 补偿（§4） | 中间态扫描 + 人工介入 | +| 9 | 第三方 SDK 数据泄露 | 低/极高 | 广告/支付 SDK 宿主侧隔离 + 最小权限 | 紧急下线第三方 SDK | diff --git a/.agents/skills/add-business-module.md b/.agents/skills/add-business-module.md new file mode 100644 index 00000000..2cb86795 --- /dev/null +++ b/.agents/skills/add-business-module.md @@ -0,0 +1,122 @@ +# 新增业务模块操作手册（add-business-module） + +> 蒸馏来源：`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§2 后端模块地图 / §4.1 编码规范 / §11 模块开发 Checklist）、`docs/architecture/2026-06-06-v2模块架构与MVP覆盖度.md`（目录结构）、`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§7.10 扩展性 / SPI）。 +> 适用：在 `game-cloud` 后端新增一个 `game-module-{name}` 业务模块（如 pay / trade / community / ip / biz / ad，或后续新模块）。 +> 配套：工程规范见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；可靠性/数据隔离红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；模块全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；契约先行见 [`./contract-first-development.md`](./contract-first-development.md)；任务协议见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)。 + +--- + +## 目标 + +把一个新业务能力沉淀为标准 Yudao 风格的双 Maven 模块（`-api` + `-biz`），可被 `game-server` 单体加载、对外暴露 `/app/**` 与 `/admin/**` 接口、有库表迁移与测试、契约同步给前端。**产出后即可被前端联调、被其他模块通过 Feign 调用。** + +## 前置 + +- 已读 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)，确认该能力**确实需要新模块**（多数 MVP 需求在既有模块加子包即可，见模块架构文档 §4 遗漏分析的判断方式）。 +- 本地中间件已起（`docker compose -f deploy/docker-compose.middleware.yml up -d`），可跑 Flyway 与集成测试（Testcontainers 依赖 Docker）。 +- 已在模块速查表（开发团队版 §2.2）与错误码段位表（开发团队版 §4.1）为新模块预留了**模块编号**与**错误码段**。 + +--- + +## 模块物理结构（以 project 为样板） + +新模块拆成两个 Maven 子模块：`-api`（契约，被别人引用）与 `-biz`（实现，只本模块用）。 + +``` +game-module-{name}/ +├── game-module-{name}-api/ # 契约层：可被其他模块依赖 +│ └── src/main/java/cn/huijing/game/module/{name}/ +│ ├── api/ # Feign 接口（供别的模块同步调用） +│ ├── dto/ # 模块间传输对象 DTO +│ ├── enums/ # 枚举（状态/类型） +│ └── enums/ErrorCodeConstants.java # 本模块错误码常量（独占一段） +│ +└── game-module-{name}-biz/ # 实现层：只本模块内部使用 + └── src/main/java/cn/huijing/game/module/{name}/ + ├── controller/admin/ # 后台接口（运营/管理员，/admin/{name}/**） + │ └── vo/ # admin 端 VO（ReqVO/RespVO/PageReqVO） + ├── controller/app/ # 产品端接口（创作者/玩家，/app/{name}/**） + │ └── vo/ # app 端 VO + ├── service/ # 业务逻辑（@Transactional 只加这里） + ├── dal/mysql/ # Mapper 接口 + DO（数据库映射对象） + ├── dal/dataobject/ # DO（与表字段一一对应） + ├── convert/ # DO ↔ VO/DTO 转换器（MapStruct） + ├── job/ # 定时任务（如对账/聚合/清理） + └── mq/consumer/ # RocketMQ 消费者（幂等消费） + └── src/main/resources/ + └── db/migration/ # Flyway 迁移脚本 V{x.y.z}__{desc}.sql + └── src/test/java/... # 单元测试 + 集成测试 +``` + +> 包名固定 `cn.huijing.game.module.{name}.{层}`（开发团队版 §4.1）。`-api` 只放契约，**禁止**放实现/DO/Mapper；`-biz` **禁止**被其他业务模块依赖。 + +--- + +## 步骤清单（照做） + +| # | 步骤 | 关键动作 | 验证 | +|---|---|---|---| +| 1 | 建模块 | 复制 project 的 `-api`/`-biz` 两个 pom 改 artifactId；`-biz` 依赖本模块 `-api` + 需要的他模块 `-api` | `mvn -pl game-module-{name}-biz compile` 通过 | +| 2 | `-api` 定义契约 | 写 DTO/枚举/Feign 接口/`ErrorCodeConstants`；**先于 `-biz` 完成**，前端据此定义 TS 类型 | 契约同步进 `contracts/api-schemas/{name}.yaml` | +| 3 | `-biz` 实现分层 | 按 controller(admin/app)→service→dal(DO+Mapper)→convert 落地；MQ/job 按需加 | 单元测试覆盖 service | +| 4 | Flyway 迁移 | `-biz` 的 `db/migration/` 下新建 `V{x.y.z}__{desc}.sql`，如 `V1.0.0__create_game_{name}.sql`；只新增不改旧文件 | `mvn flyway:migrate -pl game-module-{name}-biz` 成功 | +| 5 | game-server 引入依赖 | 在 `game-server/pom.xml` 加 `game-module-{name}-biz` 依赖（单体把全部模块编进一个 JAR） | `mvn -pl game-server compile` 通过 | +| 6 | Nacos 模块配置 | 如有模块级配置（开关/阈值/外部 API key），在 `deploy/nacos/` 加配置项并导入 | Nacos 控制台可见配置 | +| 7 | 单元测试（Service） | `XxxServiceTest`，继承 `BaseDbUnitTest`/`BaseDbAndRedisUnitTest`；外部依赖用 Mockito 桩 | `mvn test -pl game-module-{name}-biz` 绿 | +| 8 | 集成测试（Controller+DB） | `XxxServiceIntegrationTest`，Testcontainers 自动起 MySQL/Redis；覆盖核心 API | `mvn verify -pl game-module-{name}-biz -Pintegration` 绿 | +| 9 | Swagger/Knife4j 验证 | 启动 `game-server`，开 `http://localhost:48080/doc.html` 确认接口与字段自动生成正确 | doc.html 可见新模块分组 | +| 10 | 更新文档 | 更新开发团队版 §2.2 模块速查表 + [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md) 模块清单/依赖 | 文档与代码一致 | +| 11 | 通知前端 | 给前端 Swagger 地址 + 示例 curl（含鉴权头）；契约变更走 [`./contract-first-development.md`](./contract-first-development.md) | 前端可联调 | + +**API 路径规范**（开发团队版 §2.3）：`/{端}/{模块}/{资源}/{动作}`。`/app/**` 走用户 Token，`/admin/**` 走管理员权限。例：`POST /app/{name}/xxx`、`GET /admin/{name}/page`。 + +--- + +## 错误码段位规则 + +每个模块**独占一段** 9 位错误码，避免冲突（详见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)）。已分配段（开发团队版 §4.1）： + +| 段位 | 模块 | +|---|---| +| `1-001-xxx-xxx` | system | +| `1-002-xxx-xxx` | infra | +| `1-100-xxx-xxx` | project | +| `1-101-xxx-xxx` | aigc | +| `1-102-xxx-xxx` | runtime | +| `1-103-xxx-xxx` | feed | +| `1-104-xxx-xxx` 起 | 新模块按顺序续段（telemetry/pay/trade/...，落地时在规范文件登记） | + +错误码常量集中写在 `-api` 的 `ErrorCodeConstants.java`，用 Yudao `ServiceException` + 错误码枚举抛出（不要裸抛 RuntimeException）。 + +--- + +## 完整 Checklist（可勾选） + +- [ ] 已确认确需新模块（而非在既有模块加子包） +- [ ] 创建 `game-module-{name}-api` 与 `game-module-{name}-biz` 两个 Maven 模块 +- [ ] `-api` 中定义 VO/DTO 入口、枚举、Feign 接口、`ErrorCodeConstants`（独占错误码段） +- [ ] `-biz` 中建 `controller/admin/` + `controller/app/` + `service/` + `dal/mysql/` + `convert/`（按需 `job/`、`mq/consumer/`） +- [ ] 编写 Flyway 迁移 `V{x.y.z}__{desc}.sql`（只新增，不改旧迁移） +- [ ] `game-server/pom.xml` 引入新模块 `-biz` 依赖 +- [ ] Nacos 添加模块级配置（如有） +- [ ] 单元测试（Service 层）通过 +- [ ] 集成测试（Controller + DB，Testcontainers）通过 +- [ ] Swagger（Knife4j）`doc.html` 验证 API 文档自动生成 +- [ ] 更新开发团队版 §2.2 模块速查表 + [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md) +- [ ] 通知前端：附 Swagger 地址 + 示例 curl +- [ ] 契约文件 `contracts/api-schemas/{name}.yaml` 已同步并提交 git + +--- + +## 常见坑 + +| 坑 | 后果 | 正确做法 | +|---|---|---| +| 改 Yudao framework 层源码 | 升级 Yudao 时冲突、不可维护 | **不改 framework 层**，走 SPI/扩展点（如 PayChannel/AdProvider/ConversionAdapter SPI，见技术决策版 §7.10） | +| 自己写 SQL 做数据隔离 | 创作者能看到别人的项目/资产 | 用 Yudao **DataPermission**（数据权限）做隔离，"创作者只看自己的"（技术决策版 §7.4） | +| 审核流自己写状态流转 | 流程僵硬、无法可视化配置 | 审核/发布/下架走 **bpm（Flowable）** 工作流驱动（开发团队版 §2.2 project 依赖 bpm） | +| `-biz` 被别的模块依赖 | 编译耦合、循环依赖 | 跨模块只依赖对方 `-api`；同步调用用 Feign，异步用 RocketMQ | +| `@Transactional` 加在 Controller 或范围过大 | 长事务、锁竞争 | 只加在 Service 层，范围尽量小（开发团队版 §4.1） | +| 修改已存在的 Flyway 迁移文件 | `flyway validate` 失败、CI 阻断 | 新建迁移补偿，绝不改旧文件（开发团队版 §9） | +| 单元测试连真实 DB | 测试慢、不稳定 | 业务逻辑用 Mock；真需要 DB 用集成测试 + Testcontainers | +| `select *` / 大表无索引查询 | 慢查询、性能事故 | 必须指定字段；大表查询必须命中索引（开发团队版 §4.1） | diff --git a/.agents/skills/ai-generation-pipeline.md b/.agents/skills/ai-generation-pipeline.md new file mode 100644 index 00000000..2f2e78ad --- /dev/null +++ b/.agents/skills/ai-generation-pipeline.md @@ -0,0 +1,180 @@ +# AI 生成链路开发与联调手册（ai-generation-pipeline） + +> 蒸馏来源：`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§4.1 AI 生成链路 / §6.2 §6.7 选型 / §7.10 产物缓存 / §8 风险）、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`（3.2 aigc 能力清单）、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§10 外部工具层开发指南 / §6.2 联调）。 +> 适用：开发/调试 aigc 模块与其外部 AI 引擎（Dify / OpenGame / ComfyUI）。 +> 配套：降级/可靠性红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；选型背景见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md)；模块全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；新模块流程见 [`./add-business-module.md`](./add-business-module.md)；契约见 [`./contract-first-development.md`](./contract-first-development.md)。 + +--- + +## 目标 + +把自然语言 Prompt 经 **aigc Java 壳 → Dify 编排 → OpenGame 代码生成 / ComfyUI 素材生成**，产出可运行的 GamePackage（config + code + assets）并写回 project。**产出后 runtime 可编译预览、创作者可试玩发布。** + +## 前置 + +- AI 引擎已起：`docker compose -f deploy/docker-compose.ai.yml up -d`（ComfyUI 需 GPU，无 GPU 时图片走 mock 或外部 API）。 +- RocketMQ Consumer 已注册（生成任务靠 MQ 异步驱动；若一直 QUEUED 多半是 Dify 没起或 Consumer 没注册，见开发团队版 §9）。 +- Dify workflow 已发布并拿到 `workflow_id`；OpenGame `/generate` 端点 curl 可调通。 + +--- + +## 1. 架构（四段） + +``` +┌──────────────────────────────────────────────────────────────┐ +│ game-module-aigc（Java 壳，Spring Boot） │ +│ ├─ Controller 接收创作请求（/app/aigc/generate） │ +│ ├─ TaskDispatcher RocketMQ 异步调度（削峰/重试/超时） │ +│ ├─ DifyClient HTTP 调 Dify Workflow API │ +│ └─ ResultWriter 写回 project 模块（草稿/版本） │ +├──────────────────────────────────────────────────────────────┤ +│ Dify（Docker 自部署）— DAG 可视化编排 │ +│ ├─ 多 LLM 热切换（通义千问 / DeepSeek / OpenAI） │ +│ └─ 节点：安全检测→意图解析→模板匹配→GameConfig+Schema │ +│ →HTTP 调 OpenGame→HTTP 调 ComfyUI→质量评估 │ +├──────────────────────────────────────────────────────────────┤ +│ OpenGame Agent（Python 微服务，HTTP API） │ +│ └─ 6 阶段 pipeline：脚手架→设计→素材→代码→验证→修正 │ +│ 输出可运行 Web 游戏代码（HTML/JS/CSS + assets） │ +├──────────────────────────────────────────────────────────────┤ +│ ComfyUI（自部署）— 图片/贴图/角色/场景/封面素材生成 │ +│ └─ 节点化 workflow，可训练 IP 风格 LoRA，HTTP API 对接 Dify │ +└──────────────────────────────────────────────────────────────┘ +``` + +> 分工铁律：企业级监控/链路 trace/高并发优化都在 **Dify 壳外侧（Java 壳）** 做，**不改 Dify/OpenGame 内核**，保证可升级、可替换（技术决策版 §6.2）。 + +--- + +## 2. 生成链路时序 + +``` +创作者 Prompt + 模板/风格 + → ① Prompt 安全检测（违禁词/敏感意图/注入攻击 → 命中即拒绝） + → ② 意图解析（LLM 提取玩法/角色/规则/风格结构化参数） + → ③ 模板匹配（语义映射到预制玩法：躲避/跑酷/射击/解谜/点击收集） + → ④ GameConfig 生成 + JSON Schema 校验（数值范围/必填/资源引用） + → ⑤ OpenGame 代码生成（6 阶段 pipeline） + → ⑥ 质量评估（结构完整性 / 资源有效性 / 运行成功率） + → 输出 GamePackage（config + code + assets）→ ResultWriter 写回 project +``` + +素材生成（图片/封面）由 Dify 的 HTTP 节点在链路中并行调 ComfyUI（能力全景 3.2 第 16/17/34/37 项）。 + +--- + +## 3. 生成任务状态机 + +状态：`queued / running / succeeded / failed / timed_out / canceled`（技术决策版 §4.1，能力全景 3.2 第 6 项）。 + +``` +[*] → QUEUED ──消费消息──→ RUNNING +RUNNING → SUCCEEDED（生成完成 + 质量通过）→ [*] +RUNNING → FAILED（生成失败 / 质量不达标） +RUNNING → TIMED_OUT（超时 120s） +FAILED → QUEUED（重试 ≤ 2 次）；超次 → [*] +TIMED_OUT→ QUEUED（重试 ≤ 1 次）；超次 → [*] +QUEUED / RUNNING → CANCELED（用户取消）→ [*] +``` + +要点： +- **LLM 调用编排**：单次 LLM 调用超时 30s、重试 2 次、熔断降级、供应商故障切换（能力全景 3.2 第 7 项）。 +- **任务级**：超时阈值 120s；失败重试 ≤2、超时重试 ≤1；用户可在 QUEUED/RUNNING 取消。 +- 失败要做**原因分类 + 可读提示**（描述不清/违规/超时/匹配低/校验失败，能力全景 3.2 第 11 项）。 + +--- + +## 4. 性能指标与限流 + +| 指标 | 目标 | 出处 | +|---|---|---| +| 生成 P50 耗时 | < 60s | 技术决策版 §4.1 | +| 生成 P95 耗时 | < 180s | 技术决策版 §4.1 | +| **生成成功率（蓝图目标）** | **≥ 85%** | 技术决策版 §4.1 / §1.2 系统目标 | +| **生成成功率（MVP 执行验收）** | **≥ 80%**（基于 3-5 个模板） | `docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md` §1.2 / §4 Week2 Day10 | +| 队列最大积压 | 500 任务，超过返回 **429** | 技术决策版 §4.1 | + +> 两个成功率数字来源不同：**≥85%** 是技术决策版的产品蓝图目标；**≥80%** 是 MVP 执行 spec 的落地验收线（3 周交付的现实门槛）。开发以 80% 为通过线、85% 为目标线。 + +--- + +## 5. Dify 开发流程 + +```bash +open http://localhost:3001 # 本地 Dify UI + +# 创建/编辑游戏生成 Workflow： +# 1. Dify UI → Studio → 创建 Workflow +# 2. 加节点：LLM / HTTP(OpenGame) / HTTP(ComfyUI) / 条件分支 / 变量赋值 +# 3. 测试运行 → 逐节点查看输入/输出 +# 4. 发布为 API → 获取 workflow_id +``` + +后端 `DifyClient` 调用： + +```http +POST http://localhost:3001/v1/workflows/run +Content-Type: application/json +Authorization: Bearer + +{ + "inputs": { "prompt": "...", "template_id": "..." }, + "response_mode": "blocking" +} +``` + +> 升级 Dify 必须**锁定版本**，能力增强放壳层（Java 侧）做，不动内核（技术决策版 §8 风险 5）。 + +--- + +## 6. ComfyUI 开发流程 + +```bash +open http://localhost:8188 # 本地 ComfyUI + +# 设计图片生成 workflow（节点拖拽）： +# 1. 加载模型节点（Flux / SDXL / 自训练 IP 风格 LoRA） +# 2. 配置 prompt / negative_prompt / 尺寸 / 步数 +# 3. 运行验证效果 +# 4. 导出 workflow：Save → API Format（得到 workflow JSON） +``` + +Dify HTTP 节点对接 ComfyUI： + +```http +POST http://localhost:8188/prompt # 提交：body { "prompt": , "client_id": "..." } +GET http://localhost:8188/history/{prompt_id} # 轮询取结果图片 URL +``` + +> 选 ComfyUI 而非直调 Midjourney/DALL-E：可训练 **IP 风格 LoRA** 出风格一致的系列素材、节点 workflow 可被 Dify 编排、自部署无审查/无 API 限制、长期成本更低（技术决策版 §6.7）。 + +--- + +## 7. 降级（铁律） + +LLM 不可用 → 退化为**确定性 Fallback 生成器**（模板参数填充，不依赖 LLM），保证"LLM 挂了仍能出基础可玩游戏"（能力全景 3.2 第 10 项，技术决策版 §7.2 / §8 风险 1）。降级细则与超时/重试/熔断标准见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。 + +--- + +## 8. 本地地址速查 + +| 组件 | 地址 | 联调方式 | +|---|---|---| +| Dify | `http://localhost:3001` | DifyClient 调 Workflow API；UI 看执行日志 | +| OpenGame | `http://localhost:8100` | Dify 节点调用，或直接 curl `/generate` | +| ComfyUI | `http://localhost:8188` | Dify HTTP 节点对接 `/prompt` + `/history` | +| safe-content-ai | `http://localhost:8200` | 图片 NSFW 快检（compliance 用） | + +--- + +## 9. 常见坑 + +| 坑 | 排查 / 应对 | +|---|---| +| 生成任务一直 QUEUED | 查 Dify 是否启动 + RocketMQ Consumer 是否注册（开发团队版 §9）；查 TaskDispatcher 日志 | +| OpenGame 社区停更 | fork 自维护（核心 pipeline 逻辑简单可控）；最坏退化为**纯 Dify + 模板**生成（技术决策版 §8 风险 4） | +| Dify 升级不兼容 | **锁定版本** + 壳层隔离，自部署可控；能力增强放 Java 壳侧（技术决策版 §8 风险 5） | +| 同一 Prompt 反复烧 LLM token | 开**生成产物缓存**：相同 Prompt hash 命中即跳过 LLM 调用（技术决策版 §7.10），省成本 + 加速 | +| LLM 输出 GameConfig 不合规/字段缺失 | 链路内 JSON Schema 强校验 + 资源有效性校验，不达标不入库（技术决策版 §8 风险 2） | +| 生成游戏质量飘忽 | 用模板约束输出 + 可玩性自动测试；模板级 Golden Config 回归比对防退化（能力全景 3.2 第 38 项） | +| 素材生成 ComfyUI 无 GPU 慢/不可用 | CPU 模式慢 10x；MVP 无 GPU 时图片走 mock 或外部 API（开发团队版 §1.3） | diff --git a/.agents/skills/contract-first-development.md b/.agents/skills/contract-first-development.md new file mode 100644 index 00000000..c0f0a584 --- /dev/null +++ b/.agents/skills/contract-first-development.md @@ -0,0 +1,102 @@ +# 契约先行与并行解耦联调手册（contract-first-development） + +> 蒸馏来源：`docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md`（§3 契约先行 / §6 并行解耦与 Mock / §8.3 联调规则）、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§6 联调协议）、`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§7.7 API 契约与版本）。 +> 适用：多工位（前端/后端/SDK/AI/数据）并行开发同一交付时，先锁契约、再各自 mock 解耦、最后集中联调。 +> 配套：工程规范（错误码/API 路径/`-api` 包）见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；新模块契约落地见 [`./add-business-module.md`](./add-business-module.md)；生成链路契约见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md)；SDK 契约见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；任务协议见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)。 + +--- + +## 目标 + +**Day0（开发首日）半天全员锁定契约**，写入 `contracts/` 并提交 git；之后各工位基于契约 **mock 对方接口独立开发**，集中联调在 **Day11** 开始。把"等对方接口"的串行依赖，换成"对着契约并行"。 + +## 前置 + +- 已读 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)，对齐 12 模块边界与端（`/app` vs `/admin`）。 +- 工位划分明确（MVP spec：WS1 基座 / WS2 AI / WS3 运行时+SDK / WS4 前端 / WS5 数据变现）。 + +--- + +## 1. 理念 + +``` +Day0 上午（半天）：全员对齐 → 锁定 7 个契约文件 → 提交 git（里程碑 M0） + ↓ +Day1~Day10：各工位基于契约 mock 对方接口，独立并行开发 + ↓ +Day11~Day12：集中联调（只联调、不加功能） +``` + +契约一旦锁定即为各工位的"对接面"。变更契约必须同步 `contracts/` 并通知相关方（见第 4 节）。 + +--- + +## 2. 7 个契约文件清单 + +| 契约文件 | 内容 | 负责人 | +|---|---|---| +| `contracts/api-schemas/*.yaml` | 所有模块 API 的 OpenAPI 3.0 定义（Request/Response） | WS1 lead 主笔，全员 review | +| `contracts/db-schemas/V1__*.sql` | 核心表结构（Flyway 迁移脚本） | WS1 | +| `contracts/sdk-interface.d.ts` | HuijingGameSDK 全部 public API 类型 + postMessage 协议 | WS3 SDK 负责人 | +| `contracts/game-package.schema.json` | GamePackage manifest 格式 + 目录结构 | WS3 + WS2 | +| `contracts/events.schema.json` | telemetry 事件名 + 字段（v1） | WS5 | +| `contracts/dify-workflow-io.json` | Dify workflow 的输入/输出契约 | WS2 | +| `contracts/ad-slot.schema.json` | 广告位配置格式 | WS5 | + +--- + +## 3. Mock 策略表 + +| 工位 | 依赖谁 | Mock 方式 | 真实对接时间 | +|---|---|---|---| +| WS4 前端 | WS1/WS2/WS3/WS5 的 API | `vite-plugin-mock` 基于契约 yaml 自动生成 | Day6 起逐步替换 | +| WS3 SDK | WS4（宿主） | 独立测试页模拟 postMessage | Day6 集成 | +| WS2 aigc | WS1（project） | 内存态写入 + MQ mock | Day5 真实对接 | +| WS5 telemetry | WS3（SDK 上报） | curl 模拟 `/events/batch` | Day6 真实对接 | + +--- + +## 4. 真实对接切换 + +| 场景 | 做法 | +|---|---| +| 前端 mock → 真实 API | 改 `.env` 中 `VITE_API_BASE_URL` 即可（开发团队版 §6.1，MVP spec §8.3） | +| 后端新增/变更 API | **必须同步** `contracts/api-schemas/` 并通知前端（MVP spec §8.3） | +| 契约定义顺序 | 后端**先写 `-api` 包的 VO/DTO**，前端据此定义 TS 类型（开发团队版 §6.1） | + +> API 演进规则：新增字段不算 breaking；删除/重命名字段 = 升版本（技术决策版 §7.7）。 + +--- + +## 5. 联调规则 + +| 规则 | 说明 | 出处 | +|---|---|---| +| 时间窗 | Day11~Day12 预留 2 天，**只联调不加新功能** | MVP spec §6.3 | +| 主导与响应 | 前端主导提 bug，后端 **30 分钟内**响应 | MVP spec §6.3 | +| Bug 优先级 | **P0 当天必修**；P1 联调期内修复 | MVP spec §6.3 | +| 阻塞升级 | 阻塞 **> 30 分钟**立即升级到每日站会 | MVP spec §6.2 / §8.3 | +| 每日站会 | 每天 **10:00**，每人 2 分钟（昨天/今天/阻塞点） | MVP spec §6.2 | +| 问题跟踪 | 联调 bug 提 Issue，打标签 `联调` + 模块名 | 开发团队版 §6.1 | + +--- + +## 6. 联调速查 + +| 观察点 | 地址 / 工具 | +|---|---| +| 后端 API 文档 | Swagger / Knife4j `http://localhost:48080/doc.html` | +| Dify 执行日志 | Dify UI `http://localhost:3001`（逐节点输入/输出） | +| SDK 事件流 | game-studio 开发模式 **DebugPanel**（实时 postMessage 事件流，开发团队版 §6.3） | + +--- + +## 7. 常见坑 + +| 坑 | 后果 | 应对 | +|---|---|---| +| 契约偏差到联调才暴露 | Day11 集中爆雷、返工 | WS1 在 Day10 预留时间专门修对接时发现的契约偏差（MVP spec §4 Week1 Day10）；前端 Day6 起提前对接早暴露 | +| 契约变更未同步 | 前后端字段不一致、联调失败 | 任何 API 增改**先改 `contracts/` 再写代码**，并通知相关方（MVP spec §8.3） | +| 前端先于 `-api` 定 TS 类型 | 与后端 VO/DTO 错位 | 顺序固定：后端 `-api` VO/DTO 先行 → 前端据此定 TS（开发团队版 §6.1） | +| mock 与真实响应结构不一致 | 切真实 API 后页面崩 | mock 严格依据契约 yaml 生成，不手捏假数据 | +| 阻塞硬扛不升级 | 拖垮整条链路进度 | 阻塞 > 30 分钟必升级站会，会后 10 分钟两人对齐（MVP spec §6.2） | diff --git a/.agents/skills/runtime-and-multichannel.md b/.agents/skills/runtime-and-multichannel.md new file mode 100644 index 00000000..67ac25c9 --- /dev/null +++ b/.agents/skills/runtime-and-multichannel.md @@ -0,0 +1,149 @@ +# 运行时、Game SDK 与多渠道导出手册（runtime-and-multichannel） + +> 蒸馏来源：`docs/architecture/2026-06-06-系统概要设计-技术决策版.md`（§3.4 Game SDK / §4.2 运行时三容器 / §6.6 运行时与导出选型）、`docs/architecture/2026-06-06-v2业务能力全景与模块归属.md`（3.3 runtime 能力清单）、`docs/architecture/2026-06-07-系统概要设计-开发团队版.md`（§2 模块地图 / §10.4 LayaAir CLI）。 +> 适用：开发/调试 runtime 模块、HuijingGameSDK、多渠道（微信/抖音/快手）小游戏导出。 +> 配套：SDK 降级铁律与沙箱安全红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；工程规范见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；架构全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；上游生成见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md)；契约见 [`./contract-first-development.md`](./contract-first-development.md)。 + +--- + +## 目标 + +把 GameConfig 编译为**可运行 Web 包**并版本化交付，注入 HuijingGameSDK，在 iframe 沙箱中安全运行（三容器预加载），并支持向微信/抖音/快手等小游戏渠道**静态导出**。**产出后游戏流可即点即玩、可分发到外部渠道。** + +## 前置 + +- OSS（本地 MinIO）+ CDN 可用；LayaAir CLI 已装（`npm install -g @aspect/layaair-cmd`，开发团队版 §10.4）。 +- SDK Core 体积达标（< 8KB 压缩）；上游 aigc 产出的 GamePackage 符合 `game-package.schema.json` 契约。 + +--- + +## 1. runtime 模块职责 + +| 职责 | 说明 | +|---|---| +| GameConfig → 可运行 Web 包编译 | `service/compiler/`：config + logic + assets → web bundle | +| Manifest 生成 | runtimeVersion / configUrl / assetList / hash / preloadPolicy / bundleSize | +| 包存储版本化 | `service/package/`：checksum(sha256) + CDN，路径 `/games/{gameId}/versions/{versionId}/` | +| 预览交付端点 | `controller/app/`：按版本返回 manifest + 资源 URL（`GET /app/runtime/preview/:versionId`） | +| 多渠道转换 | `service/conversion/`：LayaAir CLI 导出微信/抖音/快手包 | + +渲染层：**自研轻量 Canvas Runtime（< 15KB）**，iframe sandbox + SDK Core 注入，AI 生成的纯 JS 直接可运行，平台完全控制沙箱（技术决策版 §6.6）。 + +--- + +## 2. 三容器预加载策略 + +参考抖音短视频预加载，只保留前/当/后三个容器（技术决策版 §4.2，能力全景 3.3 第 12/13 项）： + +``` +[Container N-1] [Container N] [Container N+1] + (销毁中) (当前播放) (预加载完成) +``` + +- 当前游戏播放时，**预加载下一款** manifest + 关键资源。 +- 加载**超时则自动跳过**下一款 + 记录 `game_load_failed` + 错误上报降权（能力全景 3.3 第 13/14 项）。 +- 上滑切换：销毁 N-1，N+1 转为当前，再预加载新的 N+1。 + +--- + +## 3. 安全边界 + +| 项 | 配置 | 出处 | +|---|---|---| +| iframe sandbox | `sandbox="allow-scripts allow-same-origin"` | 技术决策版 §4.2 | +| CSP | `script-src 'self'; connect-src 'none'`（游戏内**无网络请求**） | 技术决策版 §4.2 | +| postMessage 校验 | 来源（origin 白名单）+ schema 双校验，防伪造 | 技术决策版 §4.2，能力全景 3.3 第 17 项 | +| 资源大小 | 总资源 ≤ 10MB，首屏 ≤ 2MB，超限编译失败 | 技术决策版 §4.2，能力全景 3.3 第 9 项 | + +> 游戏 iframe **禁止网络**，所以广告/支付/社交都在宿主侧 iframe 外渲染（见第 4 节）。沙箱逃逸是极高危风险，检测到异常立即销毁 iframe（技术决策版 §8 风险 3）。详细红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。 + +--- + +## 4. HuijingGameSDK + +SDK 是**平台能力注入游戏的唯一通道**——没有 SDK，平台就是静态文件托管（技术决策版 §3.4）。分两层： + +``` +Core（内联 < 8KB，游戏启动时加载，异步不阻塞） +├── Lifecycle ready/started/paused/resumed/completed/error + onPause/onResume +├── EventBus SDK ↔ 宿主 postMessage 通信 +├── Telemetry 事件批量上报（10 条 / 5s flush，sendBeacon 兜底） +└── ErrorTrack onerror + unhandledrejection 捕获、去重、不中断游戏 + +Plugin（按需懒加载，首次调用对应 API 时加载，不影响首屏） +├── Ad 激励视频 / 插屏 / Banner（宿主侧渲染） +├── Pay 内购 / 打赏触发（宿主侧弹支付 UI） +├── Social 排行榜 / 好友 / 邀请 / 分享（宿主代理请求） +└── Storage 云存档 / 进度（失败回退 localStorage） +``` + +SDK ↔ 宿主 postMessage 协议（消息 `type`）：`init` / `lifecycle` / `telemetry` / `ad` / `pay` / `social` / `storage`。 + +关键决策（技术决策版 §3.4）： +- **广告与支付在宿主侧（iframe 外）渲染**——因为它们要网络权限，而游戏沙箱无网络。 +- 事件 SDK 内缓冲 10 条 / 5s flush，减少 postMessage 频率、不影响帧率。 +- **降级铁律**：Plugin 层全部 `try-catch` 包裹，异常不向上抛，游戏主循环（requestAnimationFrame）永不被 SDK 阻塞。完整降级表见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。 + +--- + +## 5. SDK 与 runtime 的关系 + +``` +runtime 编译 GamePackage 时： +1. 把 SDK Core 代码内联进游戏 entry.js 头部 +2. GameConfig 声明所需 Plugin（ad / pay / social / storage） +3. manifest.json 记录 SDK 版本号 +4. 宿主据 manifest 决定加载哪些 Plugin chunk +``` + +游戏代码**不直接引用**广告联盟/支付 SDK——只通过 `sdk.ad.showRewarded()` 等抽象 API 触发，具体实现对游戏透明、由宿主在 iframe 外管理（技术决策版 §3.4）。 + +--- + +## 6. 多渠道导出（LayaAir CLI） + +**构建期静态转换**（非运行时动态适配），导出可异步离线进行、不影响实时预览（技术决策版 §6.6）。 + +```bash +# 导出微信 / 抖音 / 快手小游戏包 +layaair2-cmd publish -p wechat -i ./game-output/ -o ./dist/wechat/ +layaair2-cmd publish -p douyin -i ./game-output/ -o ./dist/douyin/ +layaair2-cmd publish -p kuaishou -i ./game-output/ -o ./dist/kuaishou/ +``` + +Java（runtime `service/conversion/`）落地： + +``` +ProcessBuilder 执行 LayaAir CLI 命令 → 异步等待进程 → 产物上传 OSS +``` + +渠道适配器（开发团队版 §2.1）各自处理**尺寸 / 资质 / 文案 / 违禁词**： +- `WechatAdapter.java` — 微信小游戏适配规则 +- `DouyinAdapter.java` — 抖音小游戏适配规则 +- `KuaishouAdapter.java` — 快手小游戏适配规则 + +> 外部进程调用要按 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md) 处理超时/失败/重试/产物校验。 + +--- + +## 7. 资源优化 + +| 手段 | 说明 | 出处 | +|---|---|---| +| hash 命名长期缓存 | hash 文件名启用 CDN 永久缓存 | 能力全景 3.3 第 10 项 | +| WebP/AVIF 转换 | 素材压缩 + 尺寸裁剪降首屏 | 能力全景 3.3 第 23 项 | +| CDN 发布刷新 | 发布时刷新需更新的 HTML/Manifest CDN 缓存 | 能力全景 3.3 第 26 项 | +| 低端设备降级 | 限制粒子/音频预加载，帧率锁 **30fps** | 能力全景 3.3 第 20 项 | + +--- + +## 8. 常见坑 + +| 坑 | 排查 / 应对 | +|---|---| +| postMessage 收不到 | 查 iframe **origin 白名单**是否放行 + Console 报错（开发团队版 §9）；确认 schema 校验未误拦 | +| DevTool import 导出包看着对 | 渠道包**仍需真机验证**（开发者工具 import 不等于真机通过） | +| 小游戏导出拖慢预览 | 导出可**异步离线**进行，与实时预览解耦，不影响游戏流加载（技术决策版 §6.6） | +| 首屏超 2MB / 总包超 10MB | 编译门禁直接阻断 + 给优化建议；走 WebP/AVIF + 音频懒加载 | +| 三容器内存涨 | 严格只保留前/当/后三容器，及时销毁 N-1（技术决策版 §4.2） | +| 加载卡死无兜底 | 加载超时 5s 自动跳过 + 错误记录 + 降权（技术决策版 §7.2） | diff --git a/.agents/workflows/ai-development-protocol.md b/.agents/workflows/ai-development-protocol.md new file mode 100644 index 00000000..506a00af --- /dev/null +++ b/.agents/workflows/ai-development-protocol.md @@ -0,0 +1,138 @@ +# AI 驱动开发元流程 + +> 本文是绘境AI 项目承接**任意任务**的统一打法：从识别 → 分析 → 评审 → 执行 → 验证 → 沉淀的完整协议。所有 Agent / 工程师在本仓库做事都遵循它。 +> 配套硬规则：[`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)、[`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；事实蓝图：[`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；操作手册：[`../skills/`](../skills/)；目录索引：[`../README.md`](../README.md)。 + +--- + +## 1. 总流程 + +```mermaid +flowchart TD + A[识别任务类型与复杂度] --> B[读 .agents/knowledge 与 docs、docs/memorys] + B --> C{复杂 / 高风险?} + C -- 否 --> S[简单路径: 目标→最小改动→验证→报告] + C -- 是 --> D[Restate 理解: 目标/范围/事实/假设/影响面/风险/验证计划] + D --> E[评审版 spec: docs/agent-specs/YYYY-MM-DD-topic-review.md] + E --> F[两轮评审] + F --> G[执行版 spec: docs/agent-specs/YYYY-MM-DD-topic-execution.md] + G --> H{需要并行?} + H -- 是 --> I[子代理拆分: 互不重叠职责 + 共享事实包] + H -- 否 --> J[实施: 最小改动/复用既有/契约先行/中文注释] + I --> J + J --> K[验证: 单测/集成/类型/构建/冒烟] + S --> K + K --> L[沉淀回 .agents: 更新 knowledge/rules/skills + 同步 README] +``` + +编号步骤： + +1. **识别任务类型与复杂度**——先判断这是分析/评审/编码/调试/写作中的哪一类，是否复杂、高风险、跨模块、用户可见。 +2. **取经验**——先读 [`../knowledge/`](../knowledge/) 与 `docs/`（架构原档）；若存在 `docs/memorys/`，先检索同类历史任务，避免重复劳动。 +3. **复杂/高风险任务先 Restate**——复述理解，声明：目标、范围边界、已验证事实、假设、影响面（blast radius）、风险、验证计划。 +4. **评审版 spec**——产出 `docs/agent-specs/YYYY-MM-DD-topic-review.md`：**结论先行**，只留背景/目标/非目标/推荐方案/关键权衡/影响面/风险兼容/验收标准/待确认项，多用 Mermaid，降低认知负荷，不写代码级细节。 +5. **两轮评审**——评审版经**两轮**评审确认后再进入执行。 +6. **执行版 spec**——产出 `docs/agent-specs/YYYY-MM-DD-topic-execution.md`：目标与范围边界、前置条件、涉及模块与文件路径、数据流与依赖、接口/数据契约、关键实现步骤、边界失败路径、验证方法、完成条件、回滚策略。不预写不可验证的代码细节。 +7. **（可选）子代理拆分执行**——见 §4。 +8. **实施**——最小必要改动、复用既有模式、**契约先行**、**全中文注释**、可追溯日志。 +9. **验证**——见 §5；无证据不得声称完成。 +10. **沉淀**——见 §6，把有价值的产出回写 `.agents` 并同步索引。 + +> **简单、低风险、局部、易验证的任务**走简单路径：目标 → 最小改动 → 验证 → 报告，不必走全套 spec 流程。 + +--- + +## 2. 任务类型分支 + +| 类型 | 打法 | 产出形态 | +|---|---|---| +| **分析** | 第一性原理 + 金字塔原理拆解；给出问题、边界、假设、风险、推荐路径 | 结论先行的分析结论 | +| **评审** | 按**严重度排序**，每条给：影响 / 根因 / 修复建议 | 问题清单（先严重后次要） | +| **编码** | 最小改动 + 复用既有模式 + 中文注释 + 验证；**禁止顺手重构**无关代码 | 可编译可验证的变更 | +| **调试** | 症状 → 复现 → 观察 → 缩小范围 → 根因 → 针对性修复 → 验证 → **清理临时调试代码** | 根因 + 修复 + 验证证据 | +| **写作** | 可评审、可直接落地的内容，多用表格与清单 | 即可入库的文档 | + +### 2.1 简单路径 vs 全流程的分流判据 + +命中**任一**下列信号即走全流程（Restate → 评审版 spec → 两轮评审 → 执行版 spec）；全部不命中才走简单路径： + +| 信号 | 判据 | +|---|---| +| 跨模块 | 改动牵动 ≥ 2 个 game-module，或触达 `-api` 契约 / 事件 schema | +| 用户可见 | 改变产品端/管理端行为、API 出入参、SDK 对外签名 | +| 高风险面 | 涉及鉴权、支付、合规门禁、沙箱、幂等、分布式一致性（见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)） | +| 数据结构 | 新增/变更 DO/表结构、Flyway 迁移、Redis/MQ 数据格式 | +| 不可逆 | 删除字段/接口、数据迁移、线上配置变更 | + +> 简单路径仅适用：单文件局部改、纯文案/注释、补一个不改契约的单测、明确无副作用的 bugfix。**拿不准时按全流程走。** + +### 2.2 本项目典型任务的落法（示例） + +| 任务 | 类型 | 路径 | 关键动作 | +|---|---|---|---| +| 新增一个 game-module | 编码 | 全流程 | 执行版 spec + 契约先行；落地照 [`../skills/add-business-module.md`](../skills/add-business-module.md) | +| 给 aigc 加一个生成失败错误码 | 编码 | 简单 | 在 `-api` 错误码段登记 + 单测，不动契约 | +| 排查"生成任务一直 QUEUED" | 调试 | 简单→视根因 | 先查 Dify/MQ Consumer 日志复现，再定位 | +| 评估是否引入 ClickHouse | 分析 | 全流程 | 第一性原理 + 评审版 spec，结论先行 | +| 审查一个支付回调 PR | 评审 | —— | 按严重度列问题；重点幂等/状态机/乐观锁 | + +--- + +## 3. 证据规则 + +区分三种信息，**不得混为一谈**： + +- **已验证事实**——来自代码、文档、日志、测试、运行输出。 +- **推断**——基于上下文的合理判断，未直接验证，须标注"（推断）"。 +- **假设**——为推进临时采用，须后续确认。 + +铁律： + +- 凡可只读核实的，**先查代码/文档/配置/测试/日志**，关键歧义仍在再问用户（只问影响决策的最小必要问题）。 +- **没有验证证据，绝不声称"完成 / 修复 / 通过 / 无问题"。** + +--- + +## 4. 子代理使用规范 + +| 规则 | 说明 | +|---|---| +| 边界不重叠 | 拆分为**互不重叠的文件 / 职责边界**，避免写冲突（一个文件只由一个子代理负责） | +| 共享事实包 | 为每个子代理提供同一份"事实包"（如 [`../knowledge/`](../knowledge/) + 契约文件），保证多代理产出一致 | +| 并行前提 | 并行**仅用于无共享状态、无顺序依赖**的任务；有依赖的按序执行 | +| 模型档位 | 关键任务统一用 **Opus Max**，以最高标准最深推理完成 | + +> 契约先行 + 各工位 mock 对方接口独立开发，是本项目并行解耦的基础，见 [`../skills/contract-first-development.md`](../skills/contract-first-development.md)。 + +--- + +## 5. 验证 + +收尾前跑最相关的验证，并在报告中给出证据： + +- 改动行为的**单元测试**；涉及 DB/MQ 的**集成测试**（Testcontainers）。 +- **类型检查 / lint / 构建**（后端 `mvn test`/`mvn verify`，前端 `pnpm test`，SDK `pnpm test:size` 体积检查）。 +- 必要的**冒烟测试**（核心链路）。 +- 跑不了的，**说明原因并给出下一步验证建议**。 + +> 测试分层与覆盖率要求见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md) §7。 + +--- + +## 6. 与 .agents 的闭环沉淀 + +每次有价值的交付后，按"维护即收尾"原则回写： + +1. **判断新增 vs 更新**：全新主题 → 新增文件；已有主题补充/修正 → 更新现有文件（先查重，不造重复）。 +2. **回写对应层**：事实 → `knowledge/`；硬约束 → `rules/`；操作手册 → `skills/`；流程 → `workflows/`。 +3. **同步索引**：任何结构性变更（增/删/改名）**同步更新 [`../README.md`](../README.md) 的文件清单**与交叉链接（统一相对路径）。 +4. **过时即处理**：信息失效立即修正或删除；与代码/文档冲突时以**已验证事实**为准。 +5. **询问是否落 memorys**：关键任务信息按需持久化到 `docs/memorys/YYYY-MM-DD-任务描述.md`（描述 10–20 字），供同类任务复用。 + +--- + +## 7. 停止规则 + +- 能回答核心问题即止，不为润色措辞、堆砌细节、展示分析过程而扩张范围。 +- **最小方案优先**：够用就不引入更复杂设计；不为一次性代码建长期抽象。 +- 关键证据缺失时，点明缺口；只有当它真会影响决策时，才问最小必要的问题。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..79be9cfb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,90 @@ +# AGENTS.md — 绘境AI 项目 Agent 工作入口 + +> **本项目采用 AI 驱动开发。** 无论你是 AI Agent 还是工程师，开始任何任务前都从这里进入。 +> 本文件回答"**怎么在本项目里干活**"：先读什么、去哪查、守什么规矩、如何把经验沉淀回来。 +> 项目"是什么/目标/目录"见 [`CLAUDE.md`](CLAUDE.md)。 + +--- + +## 一、开始任何任务前的必读顺序 + +下面 7 份文档构成对项目的完整认知。**首次接手或做架构级任务时按序通读**；日常开发**优先读 [`.agents/knowledge/`](.agents/knowledge/) 下的蒸馏版**，需要细节再回溯原始长文档。 + +| 顺序 | 文档 | 定位 | +|---|---|---| +| 1 | `docs/architecture/2026-06-06-系统概要设计-投资人版.md` | 商业定位、资本效率、壁垒与窗口期 | +| 2 | `docs/architecture/2026-06-06-v2业务能力全景与模块归属.md` | 12 模块 / 299 项能力 / P0 范围全景 | +| 3 | `docs/architecture/2026-06-06-v2架构选型审阅版.md` | 选型权衡与审阅结论 | +| 4 | `docs/architecture/2026-06-06-v2模块架构与MVP覆盖度.md` | 模块架构与 MVP 覆盖度核对 | +| 5 | `docs/architecture/2026-06-06-系统概要设计-技术决策版.md` | 技术决策全貌（架构基线） | +| 6 | `docs/architecture/2026-06-07-系统概要设计-开发团队版.md` | 日常开发手册：环境/目录/规范/联调/提交 | +| 7 | `docs/superpowers/specs/2026-06-07-mvp-execution-spec-design.md` | MVP 执行 spec：10 人×3 周、131 项 P0、契约先行 | + +> 提示：原始文档很长，直接全读会拖慢任务。**蒸馏版位于 `.agents/knowledge/`，是日常默认入口。** + +--- + +## 二、`.agents/` 目录导航 + +`.agents/` 是项目的"Agent 能力中枢"，分四类。维护规则见 [`.agents/README.md`](.agents/README.md)。 + +### knowledge/ —— 事实与蓝图蒸馏，回答"**是什么**" + +| 文件 | 一句话说明 | +|---|---| +| [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md) | 产品定位、12 模块与依赖、三仓三端架构蒸馏 | +| [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md) | 技术栈与关键选型理由（Yudao/Dify/OpenGame/自研Runtime+LayaAir 等） | +| [`.agents/knowledge/mvp-scope-and-milestones.md`](.agents/knowledge/mvp-scope-and-milestones.md) | MVP 的 131 项 P0 范围、里程碑与验收指标 | +| [`.agents/knowledge/glossary.md`](.agents/knowledge/glossary.md) | 术语表（游戏流/GameConfig/Manifest/质量分等） | + +### rules/ —— 硬约束，回答"**必须怎样**" + +| 文件 | 一句话说明 | +|---|---| +| [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) | 命名/分层/API 路径/错误码/提交/PR 等工程规范 | +| [`.agents/rules/security-and-reliability.md`](.agents/rules/security-and-reliability.md) | 安全基线、幂等、超时重试、合规与可靠性约束 | + +### skills/ —— 可复用操作手册（playbook），回答"**怎么做某类事**" + +| 文件 | 一句话说明 | +|---|---| +| [`.agents/skills/add-business-module.md`](.agents/skills/add-business-module.md) | 新增一个 game-module 业务模块的标准步骤 | +| [`.agents/skills/ai-generation-pipeline.md`](.agents/skills/ai-generation-pipeline.md) | AI 生成链路（Dify + OpenGame + aigc 壳）开发手册 | +| [`.agents/skills/runtime-and-multichannel.md`](.agents/skills/runtime-and-multichannel.md) | 运行时打包、沙箱、SDK 与多渠道导出手册 | +| [`.agents/skills/contract-first-development.md`](.agents/skills/contract-first-development.md) | 契约先行：API/DB/SDK/事件契约对齐与并行解耦 | + +### workflows/ —— 元流程，回答"**如何承接一个任务**" + +| 文件 | 一句话说明 | +|---|---| +| [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md) | 任务承接→分析→评审→执行→验证→沉淀的完整协议 | + +--- + +## 三、工作协议（强约束） + +以下为精炼条款，详细流程见 [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md)。 + +1. **先读再动**：遇到有真实复杂度的任务，先读 [`.agents/knowledge/`](.agents/knowledge/) 与相关 `docs/`，对齐事实再动手。 +2. **复杂/高风险先评审**：跨模块、改动用户可见行为、或涉及外部服务/支付/数据的任务，**先出评审版 → 两轮评审 → 再执行**，不要直接写代码。 +3. **证据规则**：区分"已验证事实 / 推断 / 假设"。**没有验证证据，不得声称"完成 / 已修复 / 通过 / 无问题"。** 跑得了的（测试、构建、lint、冒烟）必须跑。 +4. **最小变更**：只改与当前需求直接相关的代码，复用既有模式，不顺手重构无关命名/目录/格式。 +5. **中文注释**：所有代码必须配完整简体中文注释；外部交互、核心实现、错误路径要有可追溯日志。 +6. **契约先行**：接口/数据结构变更先更新契约（`contracts/` 与 `-api` 包），再实现，并通知相关方。 + +--- + +## 四、沉淀机制（同样是强约束） + +`.agents/` 的目的，是让团队在长期开发中**复利式积累能力**，持续提升 AI 驱动开发的**能力、准确率与稳定性**。因此： + +- **每完成一个有价值的任务，必须把可复用的产出回写到 `.agents/` 对应目录：** + - 新的事实/蓝图认知 → `knowledge/` + - 新的硬约束/踩坑红线 → `rules/` + - 新的可复用操作套路 → `skills/` + - 流程层面的改进 → `workflows/` +- **先查重再新增**：能更新现有文件就不要新建；过时内容即时修正或删除。 +- **变更 `.agents/` 时，同步更新 [`.agents/README.md`](.agents/README.md) 的索引与相关交叉链接**，保持导航一致。 +- 一切内容用**简体中文**，保持单一主题、精炼、可快速检索。 + +> 不做沉淀的任务是"一次性消耗"；做了沉淀，下一次同类任务才能站在已有成果上更快更准。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..155faa2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,64 @@ +# 绘境AI 游戏生态平台 + +> 本文件只讲三件事：**项目定位、项目目标、项目目录**。 +> 工作方式、规范、技能、流程一律见 [`AGENTS.md`](AGENTS.md) 与 [`.agents/`](.agents/)，本文件不重复。 + +--- + +## 一、项目定位 + +**绘境AI = AI 驱动的全民游戏创作与变现生态平台。** + +核心命题： + +- **零基础**用户用一句话就能做出**可上线、可变现**的轻量小游戏； +- **玩家**像刷短视频一样在"游戏流"里发现并即点即玩； +- **平台**靠广告分成 / 订阅会员 / B 端定制三条线变现。 + +差异化壁垒 = **生成 + 流量 + 变现"全闭环"**。竞品多停在"生成工具"，绘境把"做得出 → 有人玩 → 赚到钱"接成一条链路；真正护城河不在生成引擎（会被大模型追平），而在数据、网络效应、资产与合规四层壁垒。 + +--- + +## 二、项目目标（MVP 阶段） + +MVP 目标：交付一个**种子用户可试用的全链路闭环**——创作→生成→预览→发布→审核→游戏流→试玩→互动→广告→收益→遥测→推荐优化。 + +关键量化指标： + +| 指标 | 目标值 | 来源 | +|---|---|---| +| AI 生成成功率 | **≥ 80%**（基于 3-5 个模板） | MVP 执行 spec | +| 游戏流首屏加载 | **P75 < 3s** | MVP 执行 spec | +| 服务可用性 | **≥ 99.5%** | 可用性目标 | +| MVP 基础设施成本 | **< 5000 元/月**（投资人版核算约 ¥4,300/月，年化 ~5 万） | 投资人版 | +| P0 能力覆盖 | **131/131 项全量可验证** | MVP 执行 spec | + +> **两份路线来源不同，如实标注差异，勿混用：** +> - **投资人版（HJ-ARCH-002）**：**5 人核心团队 + ¥4,300/月基础设施 + 11 周 MVP**，强调资本效率与窗口期验证。 +> - **MVP 执行 spec（HJ-MVP-SPEC-001）**：**10 人 × 3 周（15 工作日）全量交付 131 项 P0**，强调契约先行 + 五工位并行。 +> - 生成成功率：投资人版未直接给数值，**spec 明确为 ≥80%**（非 85%）。引用指标时以对应文档为准。 + +--- + +## 三、项目目录 + +### 3.1 三个独立 Git 仓库（业务代码仓，当前仓库尚不含其代码） + +| 仓库 | 定位 | 技术栈 | +|---|---|---| +| **game-cloud** | 后端（Yudao Cloud fork + 12 个游戏业务模块） | Java 17 + Spring Cloud Alibaba + MySQL + RocketMQ + Redis + Nacos + Dify + OpenGame | +| **game-admin** | 管理后台前端（运营/管理员用） | Vue3 + Element Plus（yudao-ui-admin-vue3 fork） | +| **game-studio** | 产品端前端（创作者 + 玩家用） | Vue3 + Vant + 自研轻量 Canvas Runtime(<15KB) + HuijingGameSDK；小游戏多渠道导出用 LayaAir CLI | + +### 3.2 当前仓库（文档仓）目录结构 + +``` +games-development-ai/ +├── CLAUDE.md # 本文件：定位/目标/目录 +├── AGENTS.md # AI/工程师工作入口指南 +├── docs/ +│ ├── architecture/ # 6 份架构设计文档（投资人版/能力全景/选型/模块/技术决策/开发团队版） +│ └── superpowers/specs/ # MVP 执行 spec 等执行级规格 +├── docs-design/ # 产品/视觉设计资料 +└── .agents/ # Agent 能力中枢（knowledge/rules/skills/workflows） +```