9ae3334240
tech-decisions §5.1 回写:richness 架构落地(纯 LLM 非阻塞、代码零丰富度断言)+ 富游戏 M1 全 3 品类 100% 达标 + 退役授权 authorized;蒸馏 stale-play-spec 复用坑(复验须 --offset)与 amgen-base* 是 load_brief 依赖(清理须排除)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
41 KiB
技术决策事实蒸馏（ADR 风格）
蒸馏来源：
docs/architecture/架构/README.md（§6 决策记录、§6.6/6.7/6.8 工具链，最权威）、docs/architecture/架构/13模块.md（各模块技术栈/边界）、docs/architecture/架构/README.md、docs/superpowers/specs/mvp-execution-spec-design.md（执行约束）。 目的：让后续 Agent 一篇掌握"为什么这么选、放弃了什么、风险在哪、哪些还没拍板、哪些源档互相打架"。 相关：架构与模块见product-and-architecture.md；范围里程碑见mvp-scope-and-milestones.md；术语见glossary.md；红线约束见../rules/security-and-reliability.md、../rules/engineering-conventions.md。
总原则（一句话）：用开源生态组合替代烧钱自研，钱与人力集中在竞品做不了的"游戏流分发 + 创作者变现闭环 + 数据驱动优化"。 所有核心组件均开源/可替换，无单点供应商锁定。
1. 关键决策表（ADR）
⚠️ 回填（2026-06-10，HJ-AUDIT-001;再回填 2026-06-12；三回填 2026-06-15 HJ-AGI-002）：下表「AI 生成引擎」行已被取代两轮——
C2 裁定后 MVP 主线=模板驱动（LLM 直出 GameConfig+固定模板）→ 现行主线=agent 写码于插件库（HJ-GEN-001 终审 2026-06-12：游戏模板/填参线随 W-CLEAN 清除退役;「玩法模板」(品类框架·引导生成·非 pre-built 代码)未废=有效·待建但非最高优先级(最高=Tier 0 生成可靠，玩法模板排其后;HJ-DEMO-AUDIT-001 创始人 06-17，见完成度与优先级总账);生产生成=便宜模型经 new-api+harness 门。agentic 基建=SAA(Spring AI Alibaba v1.1.2.2)裸图编排 (HJ-AGI-002；short-term SAA-only，AgentScope 降 long-term premium 独立轨)— 此「SAA-only / AgentScope 降 premium」结论已被 2026-06-25 框架 reframe 推翻（superseded）：框架统一收敛 AgentScope（三档共用一个 agent 框架），SAA / dify / coze 降最低优先级、留作「远期适配验证可插拔」目标。HJ-AGI-002 当时确实在产、是历史事实，但其分轨口径不再现行。）。Dify/OpenGame 均未部署、降级远期。§1.1 Tier1 行的「OpenGame 文生代码」同此。 ⚠️ 回填（2026-06-11，Tier1 重设计·创始人专门会话）：下表「游戏运行时」行的 Tier1「自研 Canvas<15KB」被二次质疑裁定取代——自研壳实为机制演示（资产载而不绘/零 juice/只胜不败），手搓引擎=critical risk；15KB 红线废除（系 srcdoc 内联架构的衍生约束，前提已失效），改为三层约束框架（SLO 地板@千元机+4G P75 / 预算入场券 B1 gz≤350KB·raw≤1.5MB / 工程增强层 E1-E6），引擎=契约下可换的实现，终裁待 LittleJS vs Phaser eval-spike。单一事实源：docs/brainstorms/2026-06-11-tier1-runtime-constraints-requirements.md+docs/agent-specs/_archive/2026-06-11-Tier1运行时重设计-review.md。
| 决策点 | 选择 | 理由 | 放弃的备选（why-not） | 风险 |
|---|---|---|---|---|
| 后端框架 | Huijing Cloud（Java 17 + Spring Cloud Alibaba），fork 二开 | 60%+ 后台能力开箱即用（RBAC/OAuth2/BPM/文件/通知/审计/代码生成/多租户）；社区活跃（60k+ star）；单体启动可平滑拆微服务 | NestJS(Node)：v1 验证可行但缺企业级基础设施，微服务生态弱，后台/工作流要从零建；Go(Kratos/go-zero)：性能好但 RBAC/BPM/代码生成无现成方案 | 绑定 Huijing 升级节奏；须守"不改 framework 层"才可升级 |
| AI 生成引擎 | 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 版是 Huijing 官方主推、社区最活跃、文档最全、二开友好度最高；Vant 适配游戏流滑动体验 | React + Next.js：与 Huijing 前端生态不一致，二开成本高（v1 用的就是 Next.js，v2 切 Vue3） | 两端两套组件库；C 端游戏流须独立 H5，admin 风格不适用 |
| 数据库 | MySQL 8.0 | Huijing 默认，社区方案最多，迁移成本最低；需 JSONB/全文检索时再加 PostgreSQL/ES | PostgreSQL：JSONB/全文检索更强但 Huijing 适配成本高 | 复杂检索能力弱，靠后续叠加 ES/PG 补 |
| 消息队列 | RocketMQ 5 | Huijing 默认集成；延迟消息/事务消息/死信队列完整，适合生成任务调度、审核通知、事件摄取、结算触发 | Kafka：偏大数据流、运维重，MVP 过度；Redis Stream：可靠性不足，无死信/事务消息 | 运维复杂度高于 Redis Stream，但生产更可靠 |
| 游戏运行时（分层，见 §1.1） | Tier1 |
Tier1 首屏极快（P75<3s）、AI 生成纯 JS 直接可运行、平台完全控制沙箱； |
Three.js：仅 web3D、与 Cocos 重复（不选）；Phaser 3 全栈：纯 2D、导出弱（ |
Cocos web 包体较重(MB级)→Tier2/3 不进游戏流、走渠道/App 分发； |
| 多渠道导出 | 以"微信小游戏格式包"为统一中转；Tier2/3 用 Cocos 官方一键导出，Tier1（LittleJS）渠道 adapter 走 W-CH-α 竞标（ |
快手无专用导出接口，标准路径=导出微信包→快手开发者工具"微信格式兼容转换"；抖音有自有导出接口；导出可异步离线、不影响实时预览 | LayaAir 官方平台清单无快手，不走 LayaAir CLI 路线 | DevTool import 仍需真机验证；三平台各自真机 |
| AI 素材工具链 | 图片/音乐现行=mmx-cli（MiniMax，2026-06-12 创始人亲验拍板默认；agent 造游戏直接 CLI 调用，免 GPU/免训练）； |
（以下为 ComfyUI 备选时的理由，留作历史）ComfyUI 节点化、可训 IP 风格 LoRA 出系列一致素材、自部署无审查/无限频、长期成本低于商用 API；Fish/CosyVoice 中文效果最佳、支持 few-shot 音色克隆 | 直接调 Midjourney/DALL-E API：无法训风格 LoRA、游戏场景（武器/战斗）易被拒、按次付费贵 | ComfyUI 需 GPU（无 GPU 走 CPU 慢 10x 或 mock/外部 API） |
| 内容安全 | 图片→safe-content-ai（自部署快检）+ 阿里云内容安全（高风险兜底确认）；文本/音频→阿里云审核 API；AI 输出→skills/prompt-governance.md） |
自部署做首道快检（免费/低延迟），高风险样本二次送阿里云确认；阿里云违禁词库持续更新、语义强于规则 | 单一商用 API：成本高且首道检测延迟大 | 双层链路一致性需治理；阈值（block 0.7 / review 0.4）须在 Nacos 调优 |
补充选型（同源 §7 治理章，非主决策但已定）：Nacos（注册+配置中心，Huijing 原生）、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(增长期)。
1.1 分层运行时设计
⚠️ 引擎口径已更新（2026-06-21 · tier2 触发）：tier2 自治富游戏生成轨的引擎定为 Phaser/Pixi（全无头·纯代码）、agent 框架定为 AgentScope（Python·独立 service·自治 ReAct），Cocos 仅留 3D/渠道导出轴（编辑器+人在环）——下表与本 §1.1 凡写「Tier2/3=Cocos+MCP 锁定」「MCP 158 工具可 AI 驱动」「Phaser 否决/落选」处，均按此口径理解，详见本节末 §1.1 supersession 横幅与 tier2 富游戏设计（已并入运行时 SoT
docs/architecture/架构/生成引擎/agentic运行时架构图说.md§4.2/§5）。这同时澄清了 §1/§2/§4 里"AgentScope 降 long-term premium 独立轨"的旧口径：AgentScope 不再只是悬置的远期备选，而是 tier2 富游戏线现行选定的 agent 框架（tier2 核心已落、0 号 spike 已 accept，见 §4 与运行时 SoT生成引擎/agentic运行时架构图说.md§4.2/§5）。进一步：2026-06-25 框架 reframe 已把这层澄清推到底——三档统一收敛 AgentScope（不再「廉价线 SAA-only、tier2 AgentScope」两套基建并存），SAA / dify / coze 整体降最低优先级、留作「远期适配验证可插拔」目标。 下表保留决策史、只加纠正标注，不删。
游戏产物分三层，对应不同运行时：Tier1 = LittleJS 增强发行版 + Runner v2（agent 写码于插件库生成，HJ-GEN-001；原「自研 Canvas + OpenGame 生成」已废除，见下表）；Tier2/3 统一用 Cocos Creator 3.8.8 + MCP。（术语澄清：废的是游戏模板/填参线（W-CLEAN），「玩法模板」(品类框架)未废、待建。） MVP 仅交付 Tier1；非目标保持收敛（Tier2/3 仅远期探针，见 §7）。
| 层 | 定位 | 选型 | 生成路径 | 状态 |
|---|---|---|---|---|
| Tier1 极轻量H5/2D | 游戏流即点即玩，首屏 P75<3s + 点卡→可玩 S2（常态≤2s） | docs/agent-specs/_archive/2026-06-11-T1引擎终裁包.md）：引擎 URL 化交付享 HTTP+编译双缓存； |
✅ W-T1b 主门过（拔高样板「暖阳小卖部」2026-06-12 创始人亲玩判 passed），MVP 唯一交付层。真护城河=沙箱/SDK/契约/三容器（全保留）；存量 1.x 双轨冻结；引擎复议权=拔高暴露引擎级阻塞（终裁包 §4.5-3） | |
| Tier2 复杂2D+3D | 中重度含 3D，渠道分发 | Cocos Creator 3.8.8 + MCP（备选 PlayCanvas）〔⚠️ 2026-06-21 纠正：此「锁定」仅指 3D/渠道导出轴，Cocos 用编辑器+人在环；自治富 2D 生成轨改 Phaser/Pixi〕 | Cocos-MCP agentic 工具编排（studio 编排） | ✅ 锁定（限 3D/渠道导出轴）。 |
| Tier3 独立App | 打包为原生应用 | Cocos 原生导出（同 Tier2 引擎） | 同 Tier2 + 打包 | ✅ 锁定引擎。否决 Unity（AI 适配差、启动重）；MVP 后投入 |
自研工期评估（为什么 Tier2/3 复用 Cocos 而非自研）：Tier1 薄壳约 0.5–1.5 人月（可行，且必须自研以控沙箱/SDK/三容器预加载）；自研 3D 引擎数十人月~数年、自研原生框架数十人月——3 周窗口下绝不可行，必须复用成熟引擎。选 Cocos 因其一栈覆盖复杂2D+3D+原生/小游戏导出，且 MCP(158工具)使 AI 驱动可行（2026-06-21 纠正：该 MCP 是编辑器扩展、非 headless，无法无人值守驱动；Cocos 此处仅指 3D/渠道导出轴的人在环作者，自治富 2D 生成轨改 Phaser/Pixi）（与"开源组合替代烧钱自研"总原则一致）。（2026-06-11 回填：「必须自研以控沙箱/SDK」已被推翻——控制点在沙箱/SDK/契约层，与渲染引擎解耦；Tier1 渲染层亦改复用成品轻引擎，自研壳退役，见 §1.1 表）
导出枢纽 = 微信小游戏格式包：微信=引擎导出官方格式；抖音=自有导出接口；快手=无专用接口，走"微信格式兼容转换"（快手开发者工具）。LayaAir 官方平台清单无快手，不走 LayaAir CLI 路线。Tier2/3 用 Cocos 官方一键导出微信包；Tier1（LittleJS）渠道 adapter 走 W-CH-α 对比竞标（LittleJS+自研 adapter vs Cocos 导出，HJ-CH-001 §4；「Tier1 自研 Canvas 自做 adapter」随自研壳退役）。
选型依据：Cocos 3.8.8/MIT 一栈覆盖2D/3D/原生导出，故 3D/原生/渠道导出轴 选 Cocos；Three.js r184/MIT/113k★ 仅 web3D、与 Cocos 重复故不选；LayaAir 2.1k★、无 AI/MCP 生态、清单无快手（否决）；Unity 启动 7-10s×2-3 与 P75<3s 冲突（否决）。 ⚠️ supersession + 纠错（2026-06-21 · tier2 触发）：上句原作"headless MCP(158 工具) 使 AI 驱动可行"是事实错——Cocos 的 MCP 是编辑器扩展、需 Cocos Creator 在跑、非 headless（取证级核实），故 Cocos 进不了 tier2 全自治生成 loop。引擎重定为正交两轴：自治生成轨（全无头：富 2D=Phaser/Pixi、轻量档=LittleJS） vs 3D/渠道导出轴（Cocos，编辑器+人在环）；Phaser 的"spike 落选"只在 Tier1 轻量档冷启动维度、与 headless 自治维度正交。本表其余 Tier2/3=Cocos / Phaser 否决 行均按此口径理解。详见 tier2 富游戏设计（并入运行时 SoT
docs/architecture/架构/生成引擎/agentic运行时架构图说.md§4.2/§5，引擎选型）。
1.2 A11 调整回路（试玩后纠错 · 切片三 2026-06-29）
用户试玩生成的游戏后用自然语言提调整，这条回路在便宜档线落地。架构 = A 两段式：判意图（/modify/plan 收原话 → 便宜档 worker 取 base 源 + 一次轻 LLM 把自然语言分类成 mode/target/payload + 风险）与执行（用户确认后调已结构化的 /modify）分离成两次请求，HITL 走前端在两次调用之间的确认——绕开"自然语言进不了已结构化的执行入口"与"危险回问做成任务内暂停态却撞上内部状态机无暂停态"两道阻断（A2A 原生 input-required 暂停态留后期）。可改性的根基是生成侧工程规范性：资产统一在 assets.js、数值集中在 core.js，使一次修改落到"那一处"，这是生成质量、不是给调整加静态门（判意图仍 LLM 驱动）。执行分两档：确定性类（换资产 / 调数值，改一处、零 LLM）+ 模块重生成（改玩法，有界单文件重写、复用续跑与三层校验）。验收 = 九门 + 三层校验 + 三断言（改动真生效非 no-op / 非目标模块字节稳定[改前改后真比对、不信执行器自报] / 新版本血缘可查）。
现状：便宜档代码完成、本机逐段一手真验（真九门、真 LLM 重写、断言集成 smoke）；受计费真后端 e2e 排部署窗口（创始人 2026-06-29 定不动 live）；复杂档随 tier2 跟进。关键收敛：A11 后端骨架（契约 / /modify 编排 / game_source_project 血缘 / D12 配额）已大面积落地，真活在便宜档接入 + 判意图/执行/三断言。设计面 SoT = 运行时 SoT 生成引擎/agentic运行时架构图说.md §六；执行留痕 = docs/plans/2026-06-28-003-feat-studio-A11-对话式调整回路-plan.md。
2. 这些选型如何服务护城河（为什么"够用即可"）
投资人版与技术决策版口径一致：技术深度不追第一，生态完整度追第一。 生成能力会被通用大模型 12-18 个月追平，故选型刻意"够用、可替换、低成本"，把自研投入压在竞品的空白——游戏流分发与变现闭环。真正壁垒：① 游戏流推荐数据壁垒（真实流量积累，无法购买）② 生成质量反馈闭环（玩家数据→quality_score→优化建议→创作者迭代）③ 模板/素材/工作流资产沉淀（马太效应）④ 广告位 AI 优化（提升 eCPM）。对应的工程取舍：自研只做 feed/telemetry/SDK/变现链路/发行版包装层与契约（runtime 出列：渲染循环=LittleJS，自研面只剩引擎能力包装与插件协议——2026-06-12 审计 R5 纠正「护城河预划过粗给自研免检光环」；agentic 编排自研只剩护城河件——checkpoint + 验收门；框架本身（2026-06-25 reframe 后三档统一收敛 AgentScope，SAA / dify / coze 降最低优先级、留作远期适配验证可插拔目标）采主流标准对接、不自研），其余（后台、工作流、生成、素材、安全）全用开源/商用组合。Build-vs-Buy 硬门=.agents/rules/build-vs-buy.md。
3. 待确认项（源档明确标注未拍板，勿当既定事实）
来源：架构选型审阅版 §11 + 技术决策版 §1.2 指标口径。后续若已敲定，应回填本表并注明决策时间。
| # | 待确认项 | 候选 | 出处 |
|---|---|---|---|
| 1 | deepseek-v4-flash/deepseek-v4-pro + MiniMax-M2.7/M3 渠道全活；W-G1 L1 冒烟用 deepseek-v4-flash 打底、pro 升难档——原「DeepSeek key 未激活」已过时） |
— | 2026-06-08-mvp业务决策.md D1 |
| 2 | v1 运行时资产移植方式 | Canvas2D 渲染 + 小游戏转换逻辑：移植为 Java 服务，还是保留 Node 微服务 | 选型审阅版 §11.2 |
| 3 | 产品端域名方案 | game-studio 与 game-admin 同域不同路径，还是不同子域名 | 选型审阅版 §11.3 |
| 4 | 2026-06-10-真实鉴权与匿名玩家-review.md §9.1）：C 验证码为主+邀请码旁路、玩家开放注册（受限期凭邀请码）、创作/发布限 A2 白名单、互动即弹一键登录、实名提现前收、匿名=纯客户端 anonId+聚合侧剔除（glossary/contracts 已同步修订）；待出 execution 版排建设（建议 M-b 后） |
— | 鉴权评审版 §9.1 |
| 5 | Tier3 独立App 运行时引擎 | Cocos Creator 3.8.8 + MCP 统一 Tier2/3（见 §1.1） | 运行时选型研究 |
| 6 | 2026-06-08-mvp业务决策.md D2 复审注 |
— | HJ-AUDIT-001 R4 + mvp业务决策 D2 |
4. 关键口径（落地前以此为准）
多份源档由不同子代理产出，下列口径已统一裁定，落地一律以本表权威单值为准。整体原则：蓝图/选型以技术决策版（HJ-ARCH-001）为准，执行/排期以 mvp-execution-spec（HJ-MVP-SPEC-001）为准。 投资人版（HJ-ARCH-002）仅作对外叙事，不作技术依据。
| 口径点 | 权威结论 |
|---|---|
| 运行时技术栈 | Tier1=LittleJS（2026-06-12 终裁）+Runner v2（原自研<15KB 壳退役、存量 1.x 冻结）；Tier2/3=Cocos Creator 3.8.8+MCP〔⚠️ 2026-06-21 纠正：Cocos 仅留 3D/渠道导出轴，自治生成轨=Phaser/Pixi〕（见 §1.1）。Three.js/LayaAir/Unity 仍否决；Phaser 经 spike 竞标落选（该落选只在 Tier1 轻量档冷启动维度；Phaser 是 tier2 自治轨选定引擎——败于冷开/交付形态，工程质量合格，证据留 spike 目录） |
| 生成成功率指标 | MVP 验收按 ≥80% 判定；≥85% 为远期蓝图目标，勿用 85% 卡 MVP |
| 时间线 | 双路线并存：投资人版 5 人/11 周、执行 spec 10 人/3 周；执行排期以 mvp-execution-spec 为准（含逐日计划与里程碑） |
| MVP 范围/口径 | MVP 验收以 Doc A 的 55 项 P0 产品功能为准；技术实现范围经 Doc C 反查 Doc B（工作量 ≈137 技术项）。详见 mvp-scope-and-milestones.md §3 |
| 模块划分 | 13 模块（含 game-module-studio 创作编排域，aigc 为无状态生成原子）；能力清单拆为产品功能(Doc A)/技术功能(Doc B)/映射(Doc C) 三文档分离 |
| 生成主线（三档统一 AgentScope、SAA 最低优先级远期适配） | src/（HJ-GEN-001 终审 2026-06-12，旧游戏模板/填参线随 W-CLEAN 退役〔M-b 执行器写链语义保留复用〕），便宜模型经 new-api + harness 九门，引擎=LittleJS；gameDefinition 已废、A-model 写真 src/ 现行（无 factory/gamedef 双轨、无 cutover）；per-gen 预算硬闸 <¥10（图/音另算）。已实证地板（W-G1 L1 worker + 九门真玩 + 3 款冒烟，¥0.01–0.03<¥0.15 闸；全 20 款 bake-off + 四模型横比 + Claude-free judge 门待跑，配方见 skills/cheap-model-game-generation.md）。复杂档（tier2 富游戏）：自治 ReAct agent 用 AgentScope + Phaser 造多系统富游戏（合成/经营/挂机这类，对标肥鹅美食街），产物=真 Phaser src/ 源工程，三层校验兜底；per-gen 预算硬闸 <¥50（图/音另算）。现状=0 号 spike 已 accept、核心已落（见运行时 SoT 生成引擎/agentic运行时架构图说.md §4.2/§5 与 tier2/HANDOFF.md）。运行时单一真相 SoT = 生成引擎/agentic运行时架构图说.md（§5.2 控制面 / §5.7 成本）。Dify/OpenGame=远期增强未部署 |
4.1 生产质量三层 reframe（创始人亲玩校准锁定，2026-06-14·WG1 review §8）
W-G1 实证后创始人亲玩校准拍定：生产环无 Claude，质量由三层兜底，各司其职、不可互相替代——
| 层 | 是什么 | 能判 / 判不出 |
|---|---|---|
| ① 确定性门（地板/可玩性真值，Claude-free） | 九门（A–G 假绿守卫 + H 机制/latch + I 控制手感）+ 适配性真玩 driver（读 state 接球，解盲打假阴性）。手感尽量拆成确定性门（latch 终态驻留 / 控制跟手 / 碰撞穿透[门 J 规划]） | 能判：能跑/真接线/有进展/真结束/跟手。拆得掉的全自动判 |
| ② 便宜 player（主观层，消费 gate-H） | M3 静态截图 + flash 运行数据，判拆不掉的主观好玩/美术/节奏；须人锚校准（calibrate.py vs 创始人 labels.json） |
判不出物理/碰撞/控制的交互手感——实证把碰撞有问题的件高估为最佳（两 player 均 fun=4，text 漏控制 bug）。有结构性天花板 |
| ③ 创始人抽检（人锚，现阶段不可替代） | gate-H 盲打假阴性 + player 漂移的最终纠偏 | 没有它会把碰撞有问题的件当"最佳"发出去 |
- "上下文是杠杆"实证：同 flash 仅改接地（grounding）→ 成本 −50%、修复轮次 −80%；player rubric 锚定（1-5 分级 + 空心→≤2）把 player MAE 1.25→0.75。结论 = 工程沉淀在 agent harness（任务协议/状态模型/门禁/judge 校准），单次生成是消耗品（harness 复利）。
- Opus 定位：builder / teacher / calibrator——建好即退，不进生产环（否则"生产无 Claude"前提破）；SAA 框架藏在 job/callback 契约#6 后保持可替换。
5. 关键技术风险与降级（技术决策版 §8，决策落地必读）
每条决策都自带风险与"降级方案"——这是"够用即可、可替换"原则在工程上的兜底。摘录高/极高影响项：
⚠️ 下表「LLM 调用不稳定」行的"Dify 重试+熔断"与「OpenGame 社区停更」整行为 1.x 蓝图态：Dify/OpenGame 降级远期、从未部署（C2/HJ-GEN-001），其应对/降级机制已 moot；现行 LLM 不稳定应对=new-api 网关多模型切换 + harness 门兜底，"模板填充"措辞同 §4 已废（填参式游戏模板已废 W-CLEAN）。
| 风险 | 概率/影响 | 应对 | 降级方案 |
|---|---|---|---|
| LLM 调用不稳定（超时/限流/幻觉） | 高/高 | Dify 重试+熔断；多供应商切换 | 确定性 Fallback 生成器（退化为模板填充） |
| 生成游戏质量不可控 | 高/高 | JSON Schema 强校验 + 可玩性自动测试 + 模板约束 | 质量不达标不入库 |
| 游戏沙箱逃逸 | 低/极高 | CSP + iframe sandbox + 无网络 + postMessage 校验 | 检测异常立即销毁 iframe |
| OpenGame 社区停更 | 中/中 | fork 维护，核心 pipeline 简单可自维护 | 退化为纯 Dify + 模板生成 |
| 广告联盟审核不通过 | 中/高 | 提前申请资质 + 内容合规前置 | 延迟广告上线，先做订阅/B 端（或先用 mock 广告） |
| MQ 重复消费致数据不一致 | 中/高 | 消息幂等消费（message_id + Redis 去重） | 定时任务修复 + 告警 |
| 第三方 SDK 数据泄露 | 低/极高 | 广告/支付 SDK 宿主侧隔离 + 最小权限 | 紧急下线第三方 SDK |
5.1 便宜档私有方言对模型有量化成本（2026-06-28 对照实验,evidence 见 agent-specs）
便宜档让模型直接写一套私有运行时方言(L1/L2/L3 三层骨架 + createGame 五法 + _forensicsView 契约 + ctx 受控面 + 输入收归 L1 + 几十条红线)。母语 vs 方言对照实验(同 brief 点击得分、同模型 MiniMax-M3、各 n=5、用契约无关的 fair-verdict 五信号判据)实测:M3 在母语(标准 Canvas/rAF/addEventListener)下 5/5 一次成型、3 步、约 14K 输入 token、约 55s;在现状方言下产同一个能玩的游戏要 约 26 倍 token、3–9 倍时间,还出现母语从未有的失败模式(一局磨满 20 分钟未收敛、反复撞静态检查返工、按错路径读插件)。结论:之前记在"M3 弱"头上的低良率/高成本,很大一部分是方言强加的税,不是模型天花板(M3 不弱)。
⚠️ 方向修正(2026-06-29 创始人纠正,推翻"换母语"初判):便宜档按 SoT 定位是"AI 参与深度低的高质游戏"(轻量≠简单,见运行时 SoT §一/§4.1),不是简单玩具;L2 插件库是"降 AI 参与=便宜+高质"的核心载体、不是"税"。"换母语扔插件"会让 AI 从头写整个游戏 = 升 AI 参与,与便宜档"降 AI 参与"的核心策略正相反,故推翻。本实验测的点击得分恰是产品不做的简单玩具、对象本身无产品意义——它留下的真发现是:当前 AI 在方言里写 game-logic.js 时,学插件 API 形状的摩擦极大(drawButton 当返按钮对象、define 想批量都是按母语直觉猜错;9 步 358K),"降 AI 参与"的设计意图没兑现。修正方向(创始人方向 3,分阶段)= ① 保留插件库,让插件 API 向模型母语直觉对齐(drawButton 真返按钮对象、define 批量,消除"按直觉写就错"的坑)+ RAG/few-shot/skill 补 API 密度,把学习摩擦降到接近母语;② 扩玩法模板与工程脚手架覆盖,缩小 AI 自由写的面。地基(确定性受控面 + 九门)仍是护城河。详见 ../../docs/agent-specs/2026-06-28-母语vs方言-生成对照实验-evidence.md,它给 ../../docs/agent-specs/2026-06-20-生成设计合理性-对抗审查裁决.md 的"表现力硬编码"补量化证据。
✅ 落地(2026-06-29 阶段一B 改签名):方向①「插件 API 向母语直觉对齐」已全部完成——附 A 15 处可改签名 #1-#15 逐插件改逐插件验:drawButton 返命中矩形(#5,治"误把 void 当返回值"#1 翻车点根因)、sessionScore.add / juice.burst / gamefeel 工厂(免 new)、collision·physics 几何挂实例、Aabb 兼收 {x,y,w,h}(#12)、ctx.random()·ctx.time() 可调用 + 保留方法双 API(#1,单点 buildContext 包装、框架内部不破)、audioMusic 语义音名、timer·scene·juice.render doc 钉死。另修一个正交真 bug:check 的 API 静态门方法名正则漏认泛型声明 get<T>(、把真实存在的 save.get 误判不存在、误杀一整类带存档游戏(851b86fe)。2a20e5e7→2be7b718 共 13 提交,每处单元+确定性验、各插件测试绿、双源 prompt 一致、形状门 11/11 不破。减摩擦端到端见效:改签名前栽在 save.get 泛型门 bug 的打地鼠+高分游戏(2 attempts/¥6.69/失败),改后一次过九门、¥0.64/209s、不 thrash。剩:方向①的补密度(阶段一C few-shot/RAG)+ 方向②扩模板(数据点门控)。详见 ../../docs/agent-specs/2026-06-29-便宜档降AI参与-减摩擦与扩模板覆盖-设计.md。
✅ 方向②扩模板 数据点(2026-06-29,难品类经营,修正了假设):建经营黄金骨架 game-runtime/games/_template-shop/(蒸馏过门的 bake-shop-serve 实证 pattern + 母语化 API + 多样性参数空间 + fill-in 标记,独立过九门)+ 品类路由接入(scaffold-saa <id> [template] / cheap_run.scaffold(template) / run_studio(scaffold_template, scaffold_desc),缺省回落 _template)。同一咖啡馆 brief 三路对照(n=1):软脚手架(给骨架 + 软提示)892 行/¥0.85——AI 把预算填进增富化(自加 combo+VIP)、对 ~890 行基线三指标全平没降;强制换皮(write_whitelist 锁 game-logic.js、只许改 core 主题数值+render 观感)696 行(-22%)/¥0.34(-51%)/tokens-64%,game-logic 0-diff、仍过门仍 distinct。结论:"扩模板降工作面"成立但只在"强制换皮"模式(脚手架+锁循环只换皮)——降本杠杆不是脚手架本身、是写边界强制;软脚手架买的是质量/过门鲁棒(增富化)、不买成本。取舍:强制换皮省成本但封顶增富化,软脚手架反之。n=5 收敛环确认(经营,5 个不同店主题 奶茶/书店/花店/拉面/冰淇淋):5/5 全过九门 · 成本均 ¥0.252(-64% vs 基线)· game-logic 全 0-diff · 全 1 轮 · 5 店菜单互异——成本腰斩稳 / 过门 100% / 多款不雷同 三件全确认。🔴 创始人纠正(2026-06-29,推翻 reskin 策略框):上面 reskin 的成本数据作留痕(锁写省成本机制为真),但**「reskin 锁循环只换皮作阶段二成本主线」= 错、越线、已废**。① 便宜 = LLM 低参与度,不是游戏低质量;底线 = 2D 丰富游戏(进货/解锁/成长/音乐/丰富玩法),reskin 砍复杂度违背底线;"低参与" = agent 不在引擎/plumbing 上耗(脚手架+插件包了)、精力放游戏设计。② 架构红线:项目代码只做机械确定性的事;玩法/美术/音乐的「丰富生成」= 生成 agent 设计创作职责(靠 sim-business-game-design + 组合插件),「丰富校验」= 纯 LLM 验证 agent 非阻塞——绝不写成代码校验、不进九门、不进脚手架。故"丰富脚手架/脚手架好玩门断言"也废。修正后下一步:接 sim-business 设计指导到生成 agent(现 prompt 漏)+ 建 LLM 丰富度验证 agent → 喂 M1 达标门(标=过九门+丰富);脚手架保持轻起点。
✅ 切片一收口落地(2026-06-30,上面"修正后下一步"全部交付并验证):生成 agent 接上 sim-business 设计指导(cheap_roles.py + prompt.mjs 双源,"先设计后写码"步 + MVP-first 铁律 + 8 条好玩自检);新建纯 LLM 丰富度验证 agent cheap_verify.py——读产物源码逐条裁 8 条好玩清单、写进 run-summary 的 richness 字段,非阻塞(失败降级不阻断)、不进 verdict、不改达标判定、零 code-presence 断言(命中与否 100% 由 LLM judge 裁,代码只搬运计数——红线落地;sim-business §10 那 4 条"可机检好玩门"刻意不实现)。富游戏重验 M1 达标门(全新 gameId、三品类各 n=5):click/whack/shop 各 5/5 = 100% 过九门、整体达标 ✅——richness 加固没压垮达标,plan 担心的"丰富后跌破"未发生;richness 均分 shop 4.2 / click 3.4 / whack 2.4(8 条 rubric 偏经营,最贴 shop,whack 低是品类不匹配非质量差)。退役授权据新富游戏 M1 报告重算 authorized=True。基建线同轮交付:统一 trace 落库(tier2 JsonlFileSink + cheap-worker 接线 + SAA 扩展段 schema)、配置注册表运行时热取(cheap_roles 三级回落加载器、Java @Scheduled TTL、check_registry.py 一致性 CI 门)、生成控制面只读管理面(后端 3 端点 + game-admin Vue 三 card)。两个测试坑(留给后来人):① bake-off 复跑同一 gameId 会复用 _wg1-gen/<id>/play-spec.json 旧 spec(ensure_play_spec 是"已存在不覆盖"语义)——旧薄游戏 spec 驱新富游戏会假失败(自动驱动器卡菜单 phaseNow=menu、score 0→0、E_live/G_input/H_progress 齐挂),auto_vs_golden.py 有 staged-spec 残留断言守卫而 bake_off.py 没有,故达标门复验务必 --offset 取全新 gameId(或先清 _wg1-gen 实验 staging);② cheap_run.game_dir("base4")=games/amgen-base4 是 load_brief 的 brief 来源依赖,清理 amgen-* 实验产物时必须排除 amgen-base*,否则断掉所有品类的 bake-off brief。
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"+ CSPscript-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）
MVP/近期非目标（保持收敛）：MVP 不做 3D、不做专业级游戏引擎（Unity/Unreal 级）、不做海外市场；不做完全开放式代码生成（harness 九门约束——agent 写码于 LittleJS 插件库，非旧"配置填参"线）；不自研大模型（接入通用 LLM + 开源 Agent 框架）。
远期分层路线（仅探针，不进 MVP）：Tier2 复杂2D+3D、Tier3 独立App（统一 Cocos+MCP，见 §1.1）为远期方向；MVP 至多做 1 个 Cocos-MCP 探针验证链路可行性，不投入工程。Unity 始终否决。
8. 鉴权与匿名身份落点（2026-06-10 建设+e2e 收口，HJ-PASSPORT-EXEC-001）
- 落点=system 内 passport 独立子包（非新 game-module）：零 RPC 直注 SmsCodeService/OAuth2TokenService；错误码取 system 远段
1_002_090/091；全部新文件收敛*/passport/子包（fork 合并冲突面≈0）。跨模块校验走PlayerApi（@Primary 本地化，照 OAuth2TokenApiImpl 范式）。 - 身份矩阵：创作者=手机验证码（Debug 渠道，码落
system_sms_code）发 userType=MEMBER 真 OAuth2 token；陌生玩家=邀请码旁路注册（wanxiang.passport.invite-register-enabled开关退役，核销=条件 UPDATE 原子恰一，并发实证）；匿名玩家=纯客户端 anonId + 14 端点 @PermitAll +game_runtime_session.player_user_id可空（V11）；A2 创作白名单=game_player.creator_flag5 个 Service 入层挂点。 - mock 并存机制（批跑零中断的根）：
TokenAuthenticationFilter先查真 token、查不到才 mock——stagingmock-enable:true下Bearer test1与真 token 天然并存无开关；mock 白名单豁免=PlayerApiImpl「game_player 无行∧mockEnable→放行」（生产 mockEnable=false 自动收紧）。 - 前端守卫真源=
isRealLogin()（仅 localStorage 真 token；既有isLogin()因 token 恒有 env/mock 兜底值恒真不可用作守卫）；互动转正挂点=Feed.vueonInteract单函数入口（share/report 是其内联分支，无独立函数）。 - 匿名写链审计列：见 rules/engineering-conventions §1.2 红线（系统身份注入范本 + V11 漏继承审计列之雷 + TelemetryEventEnum 真守门人）。
9. 多模板架构落点（2026-06-10 M-c 批① merge 收口，HJ-MC-TPL-EXEC-001）
- runtime=单
startRuntime工厂内 switch(templateId) 分发（拍板，弃「每模板独立工厂」）：生命周期/finish(score)/loop/drawBase/cleanText 共享单份（红线代码不复制不漂移），玩法差异只在init<T>()（状态+交互+draw 玩法层+finish 触发）；所有函数定义在 startRuntime 体内（toString() 注入约束）；空串 templateId 兼容旧包并入 clicker case；未知模板走game_error防御分支不静默错渲染。体积实测：clicker+merge 双玩法 min 后 raw=4,828B（硬线 15,360B 的 31%，软门 8,192B）。 - 后端=Loader/Validator「templateId→资源」Map 缓存：PromptResourceLoader 逐模板装 (promptVersion, promptBody, schemaText)，GameConfigSchemaValidator 逐模板编译 JsonSchema；校验逻辑零新码（仍 schema.validate(node)），同源铁律保持（注入 LLM 文本==校验文本，per templateId）；isReady()=全模板就绪（任一缺失整体自禁用含模板名）。模板白名单唯一同源=
AigcTemplateConstants.SUPPORTED_TEMPLATE_IDS编译期常量（Properties 默认值与 validateTemplateExists 同读；不注入 executor Properties——@ConditionalOnProperty关闭时 Bean 缺席）。pom maven-resources includes 已通配（新模板两资源自动进 classpath）。 - runtime↔player 承重接口纪律：跨进程共享公式（merge 棋盘布局）必须钉死全部参数字面双侧一致（含 spec 散文易漏的 topPad 类参数），主 agent 收口逐字符比对；运行时实证=player 按公式推演 8 产料+7 拖拽全格命中、score=2^(targetLevel-1)-1 理论值吻合。
- 新模板接入操作配方：见
.agents/skills/add-game-template.md（批② idle/tycoon 直接套用）。