games-development-ai/docs/agent-specs/_archive/2026-06-17-固定游戏架构与SAA-agentic-studio-review.md

固定游戏架构 + SAA agentic studio(Opus 设计 · 2D/3D 兼容) — review 版

类型:review 版(架构基座,结论先行)。日期:2026-06-17 · 设计者:Opus(主 agent,effort=max)· 评审:codex + opus 一轮。 关系:这是 生命周期项目模型 v2 的具体落地——把"可维护源项目"由 ad-hoc 结构升级为Opus 一次性设计的固定架构,并补上"LLM as 工作室 = SAA agentic studio(agent 列表)"。 触发:创始人裁定——「Opus 先设计游戏架构、固定下来;简单游戏架构固定;尽量 2D/3D 兼容;cheap 模型在固定架构上生成;后续优化架构 + studio agent 列表 = 完整 agentic 环境;靠 SAA 榨满 cheap 模型;单款生成 < $1。」

---

🟢 状态横幅(2026-06-18 · 真结构化地基双证成立 · SAA 现由本 session 独家开发):本 review 的核心立论(cheap 在固定架构填槽产可维护结构化源)已从代码层双证——① spike:便宜模型对 source-project.schema.json 产连贯 gameDefinition 92-100%(¥0.011/款,behaviors 带真逻辑 JS);② build 段:gameDefinition→build-from-source→真浏览器过九门(deepseek-v4-flash 满分、便宜模型 3/4 款过门,截图实证)。"改源不改包/可维护源项目/LLM as 工作室" 代码级成立。配套产出 运行时访问约定 v0(rt 对象)+ build-from-source 装配 PoC。16 节点 studio 全图已建并合入 dev/2.0.0(非"在飞设计")。现产线仍是 iife/GameConfig 路(SaaFullGraphE2eTest 60%),gameDefinition studio 产线化中替换它(generate 仍产 iife 空壳、build 不读源=待填坑,plan docs/plans/2026-06-18-001 五单元)。协调红线解除:本 review/execution canonical 现归本 session 维护。

---

1. 结论:范式

Opus 一次性设计高质量固定架构 → cheap-model agents 在 SAA agentic studio 里填定义好的槽 → 产出可维护游戏。

维度	设计
谁设计结构	Opus(一次,固定)——非 cheap 每款发明
cheap 模型角色	在固定架构里填槽(逻辑/参数/资产/关卡/规则),不发明结构
能力放大器	SAA agentic studio(多专长 agent + 迭代 + 门 + 反馈)= 榨满 cheap
2D/3D	数据驱动游戏定义模型(维度无关)+ 引擎适配器(2D 现 / 3D 后)
预算	单款 < $1(给 agentic env 充足迭代空间)

为什么这化解评审 P0:两评审的命门 = "cheap 产不出结构化可维护源"。答案——cheap 不用产结构,Opus 给固定脚手架,cheap 填好定义的槽。填一个优秀固定脚手架,远比凭空造结构可靠,也是榨满 cheap 的正解。命门由此从"cheap 能否发明结构"降级为"cheap 能否在固定架构+好 env 里填好游戏"(远更可信)。

---

1.5 已定决策 + 新约束(创始人 2026-06-17)

• 游戏定义模型 = 轻量声明式 + 领域模型(✓ 待确认①):实体/组件/行为/场景/规则的领域模型,轻量(非 AAA ECS)。
• Phase 1 只 2D 适配器(✓ 待确认②),定义格式留 3D 前向兼容。
• 救场升级阶梯(✓ 待确认⑤,带限额):cheap 打底 → 连续 5 次发布失败 → 升高一档模型 → 高档再失败 3 次 → 放弃本次生成。全过程编辑步骤 + 日志必须完整留存(供 Opus 事后分析优化)——硬观测要求,非可选。
• agentic 形态新约束:① context cache 命中(固定架构是稳定可缓存上下文 → 结构化 prompt 让固定/共享前缀被缓存,降成本)② 成本优化 ③ agent 独立性(清晰契约、松耦合、可独立开发/优化/缓存)。
• 架构 vs 玩法 = 解耦(架构玩法无关):固定架构 = 领域模型框架,玩法是填进去的数据+行为模块,非绑定;玩法模板 = 该架构的品类预设(引导填),非独立架构;极端品类差异用"通用核心 + 品类 additive profile"吸收,不分叉架构。一举三得:稳定固定上下文→cache 命中高、cheap 永远填同一套已知结构→可靠、长期可维护。(Opus 子代理对抗验证中)
• agent 列表 = Opus 子代理(aa4d7f2)深析(含 OpenGame 等 prior-art 参考)→ 精化结果见 §10.1(权威);全图 16 节点已建并合入 dev/2.0.0(2026-06-18,§4 现状注)。

2. 固定 vs 可填边界

graph TB
  subgraph FIXED["固定架构(Opus 设计一次 · 全游戏共用)"]
    A[项目骨架/manifest/构建管线]
    B[游戏运行时契约:固定生命周期]
    C[游戏定义 schema:实体/组件/系统/场景/规则]
    D[引擎适配器:2D LittleJS 现 / 3D Cocos 后]
    E[可填槽定义 + 结构校验门]
  end
  subgraph FILL["可填(cheap agents 每款生成,符合上面契约)"]
    F[实体/组件/行为模块]
    G[参数/平衡 数据]
    H[关卡/内容 数据]
    I[资产规格/引用]
    J[胜负规则]
  end
  FILL -->|conform to| FIXED
  FIXED -->|build adapter| K[(可玩产物 bundle<br/>宿主/feed 不变)]

• 固定:不随游戏变,Opus 设计、长期演进(版本化升级)。
• 可填:每款由 cheap agents 生成,必须符合固定契约(结构校验门把关)。
• 关键:可填面是数据驱动的——逻辑读参数、资产用引用、行为是符合契约的模块 → 这才让"修改=改源某槽+重构建"成立(生命周期模型)。

---

3. 2D/3D 兼容:游戏定义模型 + 引擎适配器

核心抽象 = 一套声明式、维度无关的游戏定义模型(轻量,非 AAA ECS,守"简单"):

• 实体 entity:有 transform(position/rotation/scale——2D 用 xy/z=0,3D 用 xyz,同一字段两维都成立)+ 组件列表。
• 组件 component:渲染(sprite/mesh,适配器解释)、碰撞、物理等声明式属性。
• 系统/行为 behavior:游戏逻辑(读参数、操作实体)——是逻辑,与维度无关。
• 场景 scene / 规则 rule:关卡构成、胜负条件——数据驱动。
• 引擎适配器:把游戏定义渲染/模拟到具体引擎——Phase 1 = 2D 适配器(LittleJS,实体→sprite);Phase 2 = 3D 适配器(Cocos,实体→mesh/node)。

关键收益:同一份游戏定义,换适配器即换引擎。Phase 1 只实现 2D 适配器,但定义格式不写死 2D → Phase 2 加 3D 适配器无需改格式。这正对齐分层引擎决策(LittleJS Tier1 / Cocos Tier2-3)。

守"简单 + 尽量兼容":定义模型做到维度无关但轻量(不预建 3D 全套,只不 bake-in 2D-only 假设);3D 适配器留 Phase 2 真建。"preferably 2D/3D"= 格式前向兼容,非 Phase 1 就上 3D。

---

4. SAA agentic studio(agent 列表)

现状(2026-06-18):本表是设计初版(从现 11 节点起步的演进意图);权威精化列表见 §10.1(Opus 深析 aa4d7f2 + OpenGame prior-art 并入)。实现已落地:§10.1 的全图 16 节点已建并合入 dev/2.0.0(render·classify·design·generate·validate·scaffold·asset·build·play·player·nreview·modify·escalate·repair·emit·giveup),非"在飞设计"——故"初版 vs 深析"是设计演进叙事,建成的是 §10.1 全图。写游戏代码 + 修 bug = 一个核心代码 agent(generate 写 / repair 修两面)。

studio = SAA 裸图编排的多 cheap-agent 协作系统,在固定架构上造/维护游戏。agent 列表(初版,可演进):

agent	职责	现 SAA 节点映射
design	brief/对话 → 结构化游戏设计(机制/实体/胜负)	render+design
scaffold	按固定骨架实例化本款项目(偏确定性)	scaffold
logic	填实体/组件/行为模块(符合契约)	generate
config/balance	产参数/关卡(数据驱动)	generate(扩)
asset	产/规格 六类资产	新(D5/六类)
build	适配器构建 → bundle	build
QA	九门真玩 + 结构校验	validate+play+player
repair	门失败定位+回喂修	现修复回路
modify	生命周期:在固定结构上改一处+重构建	新(生命周期)

• 后续优化 = 调架构 + 调 agent 列表(加/精化 agent)= 创始人说的"持续做成完整 agentic 环境"。
• SAA 提供编排底座(StateGraph/ReactAgent/subAgents/checkpoint,见 saa-agentic-infra-decision);固定架构提供结构;cheap 提供生成;门提供质量。四者合起来榨满 cheap。
• 单款 < $1 → env 可放心多 agent + 迭代 + 重试(cheap 单价低,$1 容得下几十次调用)。
• 接法 A/B(2026-06-18):现 16 节点 = 接法A(裸图确定性编排,九门定 done,已建七成、躯干);接法B = generate/repair 长成 ReactAgent 自治 tool-use loop(写源/build/跑九门/读错/改 config-asset 为 tools),九门兜底化解铁律张力——自治在门内、裁决在门外(§10.5 已留口)。先 A 稳地基、后 B 增量演进不返工。
• 产线化执行计划:本设计的落地路 = plan 2026-06-18-001(五单元:运行时约定 2D 适配器/build-from-source 产线化/generate 真产/可靠性兜底/ReAct 演进)。玩法模板 = 品类 prompt 模板(主 agent 调度子 agent 用,非代码非节点)。

---

5. 与既有决策映射(全自洽,无推翻)

• 分层引擎(LittleJS Tier1 / Cocos Tier2-3):= 本架构的 2D / 3D 适配器,完美对齐。
• SAA agentic 基线:= studio 的编排底座,本设计是其"应用层"。
• 生命周期项目模型:= 本架构是其"可维护项目"的具体形态(Opus 设计的固定结构)。
• 现 11 节点 SAA 图 + W-G1 worker:= studio 的雏形,reframe 到固定架构 + 扩 modify/asset/lifecycle。
• 打包产物/宿主/feed:适配器构建后仍产现 GamePackage engineBundle 形态 → 不变(blast radius 收窄)。

---

6. blast radius / 风险

• blast radius:大——新增固定架构(游戏定义 schema + 2D 适配器)、studio agent 列表重构(SAA 图扩)、worker 产出改为"填固定架构"。但宿主/feed/打包产物侧不变。
• 最大风险(两条):
  1. 固定架构的抽象层质量:维度无关游戏定义模型设计得好不好,直接决定 cheap 好不好填、2D/3D 兼容真不真。这是 Opus 设计的核心价值点,需 Opus 精设 + 评审。
  2. cheap 在固定架构里填的可靠性/成本:仍需验证(但命门已大降:填脚手架 >> 造结构)。重新框成 spike:给定固定架构+SAA env,cheap 填出过门游戏的成功率 + 单款成本 < $1。
• 守"简单"风险:游戏定义模型别过度抽象成重型 ECS——轻游戏要轻;以"够轻游戏用 + 不写死 2D"为度。

---

7. 工作序列(架构设计先行)

1. Opus 设计固定架构(本 spec 深化 → execution):游戏定义 schema + 项目骨架 + 2D 适配器契约 + 可填槽 + 结构校验门。这是新 trunk,先做。
2. 设计 SAA agentic studio:agent 列表 + 编排(扩现 11 节点图)+ 各 agent 在固定架构上的输入输出契约。
3. 重新框 spike 验证:固定架构 + SAA env 下,cheap(90% M3/10% DS)填游戏的四门成功率 + 单款 < $1 + modify 局部性。架构定了再验,不再让 cheap 发明结构。
4. 过 → execution → 两线开工(后端线:架构 schema/校验/studio 编排;引擎线:2D 适配器/资产/九门)。

---

8. 待确认项

1. 游戏定义模型抽象度:轻量声明式(实体/组件/行为/场景/规则,维度无关但不预建 3D 全套)——这个度对吗?还是更简(纯 config+单逻辑模块)/更全(完整 ECS)?
2. 2D/3D 兼容深度 Phase 1:Phase 1 只实现 2D 适配器、定义格式留 3D 前向兼容(不实现 3D)——可否?
3. agent 列表初版(design/scaffold/logic/config/asset/build/QA/repair/modify)够不够、缺哪个?
4. 固定架构是否先以一两个品类(如点击/躲避)打样,再泛化到更多品类?
5. 单款 $1 预算下,是否允许 env 内升级到 pro 模型救场(exhaust cheap 后),还是严格 cheap-only?(影响成功率 vs 成本)

---

10. Opus 深析并入(子代理 aa4d7f2 · 2026-06-17)

10.1 agent 列表(在现 11 节点 SAA 图 + W-G1 worker 上演进,非重写)

现 11 节点已覆盖 OpenGame 六阶段的 5 个 → 加 3、拆 1、固化 2 契约 = 9 生成 agent + 1 离线 skill-curator:

• 新增:classify(物理优先分类 brief→{archetype, physicsProfile, tickModel},成功率最大杠杆,填错品类比写错码更致命)· asset(六类资产,provider 可插拔=mmx-cli,音乐"记谱→合成"两步)· modify(生命周期改一处,11 节点图真空白)
• 拆分:design→「classify→GDD」;generate→「logic + config/balance」
• 复用:render/design/scaffold(语义升级为"建源项目")/logic/build/QA(validate+play+player)/repair
• 离线冷路径:skill-curator(经验沉淀,经 Git 注册表与热路径解耦;MVP 先只做 Debug Skill,Template Skill 推迟)
• 独立性:延续 SAA NodeAction 读 state→Map.of 写回,零共享可变态,可独立开发/优化/缓存。
• 澄清(创始人确认):写游戏代码 + 修 bug = 一个核心代码 agent(logic 写 + repair 修 = 它的写/修两面,自纠错环,OpenGame 单 agent 同款),非两个独立 agent;其余 agent(classify/design/asset/config/build/QA)不写游戏代码。
• 条件新增 narrative-designer-reviewer(创始人 a=no):剧情/叙事/TRPG 类保留在 MVP(不分轨),配一个独立的"设计 + 代码评审"agent——因九门确定性测不了叙事连贯,用 agentic 评审当那道质量门。质量门按品类换机制:动作类=确定性九门,叙事类=独立评审 agent(终判留创始人)。

10.2 领域模型补两维(回答待确认①)

轻量声明式领域模型对,但 profile 必须从纯物理扩到含三维:tickModel(realtime/turn-based/event)· inputModel(continuous/discrete-choice/text-command)· progressModel(metric/narrative)。否则剧情/TRPG 类绷断(见 10.5)。

10.3 缓存策略(DeepSeek 字节级前缀缓存,hit 便宜~10×)

prompt 三段式:固定前缀(契约/few-shot/能力面,永不变)→ 共享中段(GDD)→ 可变后缀(brief/反馈)。5 层缓存(L1 架构契约前缀=最大块,第二款起省~90% input)。动作:冻结 system 前缀为版本化资产(进 Prompt Registry,CI 卡 byte 不变)· few-shot 固化为常量(现从文件读=字节不稳)· repair 回喂只追后缀 · 抽 prompt_cache_hit_tokens 进成本台账 · 同品类聚类批跑。 ⚠️ 最大单点风险:经 new-api 网关转发后前缀缓存是否透传未知 → 必须先实测。

10.4 救场阶梯 + 观测(创始人原话落地)

• 阶梯锚定九门 verdict.pass=false(非主观自评,防 split-brain):cheap → 连续 5 失败→升档(stage1→stage2)→ 再失败 3→giveup。接 SAA 图 playRouter 双层 state 计数(failCount/modelTier),模型档读 state 作用到 generate/repair,recursionLimit 按 5+3 重算;worker 侧对称。
• 观测 80% 已有(attempts[] 含 stage_fail/guards/usage + design/gatespec/verdict 经 _extract_trace 落 trace_json);补 2 埋点:升档事件(tierBefore/After)+ 放弃前完整 dump(所有 attempts 源码/verdict 整包落盘,现 giveup 丢中间源码)——喂 Opus 离线分析优化。

10.5 OpenGame + 架构绑玩法裁定

• OpenGame(CUHK MMLab arXiv,开源 TS/Phaser)= 单自治 agent 跑六阶段工具流,非多拟人角色;抄设计不抄码:Physics-First 分类→classify、Debug Skill(签名→验证过的修复)→repair、Template Skill(骨架萃取)→skill-curator。九门 harness 自评强于 OpenGame-Bench。不堆角色(ChatDev 7 高管=cheap 吃不消的纯 token 开销)。
• 架构绑玩法?不绑(领域模型玩法正交,scale-20 已证 cheap 在统一契约写井字棋/扫雷/CCD/match)。硬边界=tick/input/progress 三接缝:轻量动作类(躲避/点击/合成)全在内;TRPG/剧情/叙事类是边界(事件驱动+长文本+九门测不了叙事连贯)→ 保留在 MVP,配独立"设计+代码评审"agent 当质量门(创始人 a=no:九门测不了叙事就用 agentic 评审替代,非排除;质量门按品类换机制)。

10.6 下一步两个 spike(决定缓存与 classify 成不成立)

1. new-api 网关缓存透传(最高优先:决定整个缓存策略)。
2. classify 准确率(便宜模型分类对不对,错则污染下游)。 打样先用实时动作类(躲避/点击),非经营模拟(后者不暴露 tick 边界=假信心)。

10.7 待确认更新

①领域模型=轻量声明式 ✓ 但补 tick/input/progress 三维 · ④打样先实时动作类 ✓ · ⑤救场=允许升档带限额 ✓(见 10.4)· (a) narrative/TRPG 留 MVP + 配独立"设计+代码评审"agent ✓(创始人 a=no,非分轨) · (b) MVP 只做 Debug Skill、缓 Template Skill ✓(创始人 b=yes) · 澄清:写码+修 bug=一个核心代码 agent(logic+repair 两面)✓