games-development-ai/docs/agent-specs/_archive/2026-06-10-Mc模板波-review.md

M-c 模板波（merge / idle / tycoon）· 评审版

• 编号: HJ-MC-TPL-REVIEW-001 ｜ 2026-06-10 ｜ ✅ 已拍板（2026-06-10 创始人四项全拍，见 §7 拍板结果）→ 待出 execution 版
• 上游拍板: D2 复审（2026-06-10 R4）——维持 D2 集合、按 D2 改建：M-c 建 merge→idle→tycoon 三个模板 runtime，clicker 保留为第 4 个；dodge/runner/match 降 P1 保留契约不删（docs/agent-specs/2026-06-08-mvp业务决策.md:26）。
• 结论先行: 推荐两批走（批① merge 单模板全链收口出「新模板接入配方」→ 批② idle+tycoon 并行复用配方）；idle 离线产出推荐纯前端时间差 + SDK storage 通道（宿主落 localStorage），服务端存档降 P1；merge 拖拽在现有 Canvas Runtime 可行、低风险（CDP 可确定性派发拖拽序列）。

---

1. 背景与目标

agent 化生成 QA 闭环已在 clicker 单模板上整体收口：batch-001 accept 80.0%、M-b 真实用户链 5 样本实证、batch-002b 补产 10/10，feed 现有 30 款 clicker（docs/mvp/MVP作战清单.md:46-49）。但 MVP 模板集只有 clicker 一个真 runtime——contracts/templates/ 下 dodge/runner/match 三份 schema 均自声明「runtime 未实现，不得据此宣称可玩」（contracts/templates/dodge.schema.json:5），且该三模板属 R4 已裁定降 P1 的旧集。

本波目标：按 D2 集合新建 merge（合成升级）/ idle（放置挂机）/ tycoon（模拟经营） 三个模板的完整纵切——契约 schema → prompt 入册 → Canvas Runtime 玩法 → 后端支持集 → QA 闭环（对抗评审 + Golden 集 + 玩家 agent 真玩）→ 小批量试产入 feed。完成后 MVP 4 模板（D2 拍板口径）全部真实可玩、可批产。

非目标（红线）

• dodge / runner / match runtime 不建：三份 schema 保留在 contracts/templates/ 不删、不动内容；后端对其保持「正确失败」（见 §5）。
• 3D / Tier2-3 不碰：本波全部在 Tier1 自研 Canvas Runtime（<15KB 红线，.agents/knowledge/tech-decisions.md:22）内。
• 不动发布链 / 数据回路：生命周期事件名、game_end {score, completed, duration_ms} 契约行（quality 回路命门，game-studio/src/host/runtime/index.ts:215-217）、遥测、feed 排序逻辑逐字不动。
• 不做服务端玩家存档 / 不动鉴权：idle 离线产出走纯前端（§2.3），服务端持久化降 P1。
• 不动 game-admin；不做资产（图片/音频）生成；demo 兜底包 target: 5 不动（玩家 agent 信号锚，player_cdp.py:93）。

---

2. 推荐方案

2.1 分批节奏：两批走（推荐）

flowchart LR
    subgraph 批① merge 先行收口
        A[merge schema 入册<br>+ prompt 三件套] --> B[runtime 模板分发架构<br>+ merge 玩法]
        B --> C[玩家 agent 拖拽策略<br>+ 对抗/Golden 扩展]
        C --> D[试产 10 条<br>校准批]
        D --> E[沉淀『新模板<br>接入配方』]
    end
    subgraph 批② idle + tycoon 并行
        E --> F[idle 纵切<br>含离线产出]
        E --> G[tycoon 纵切]
        F & G --> H[各试产 10 条<br>→ 正式批 → 入 feed]
    end

推荐：批① merge 单模板收口，批② idle+tycoon 并行复用配方。 理由：

1. merge 机制最薄、最接近 clicker 参数化拼装（D2 复审注原话），但它首次引入两件「第一次」——runtime 模板分发架构（现 runtime 是单一 clicker 玩法、从不读 templateId，见 §3 意外事实）和玩家 agent 非点击交互（拖拽取证）。两件新事在单模板上调通，风险面最小。
2. 黄金模板先行是项目既定效率原则（AGENTS.md §8-1「perfect one module first, then clone」）；clicker 全链就是这么收口的（spike→试点 6/6→batch-001）。
3. idle 的离线产出是本波最大架构分叉（§2.3），叠加在「第一次建新模板」上会让 QA 闭环扩展（doctrine/Golden/CDP 策略×3）同时调试，回炉成本高（返工=效率头号杀手，AGENTS.md §8-4）。

被否选项：一波全建三模板——并行省 1 个批次窗口，但三套 prompt 冷启动 + 三套 CDP 策略 + runtime 架构改造同窗联调，任何一处卡壳全波阻塞；clicker 经验表明 prompt 需 1-2 轮升版校准（v1.0→v1.1.1 走了两轮 Golden 回归），三模板并发校准会撞同一个评审/回归资源。节奏差距估计仅 2-4 个工作日，不值得换风险。

2.2 三模板玩法循环与参数面（均为提案，参数范围执行版细化）

设计总纲（提案）：全部沿 clicker 范式——纯数值/config 驱动、无物理碰撞、单局 ≤90s 可通关（保 LLM 填参成功率 ≥80% 量级 + CDP 确定性取证预算）；字段命名沿 clicker schema 风格（templateId const 精确等值防串台 + additionalProperties:false，contracts/templates/clicker.schema.json:7-11）。

模板	玩法循环（一句话）	GameConfig 参数面草案（类别级）	真玩通关判定（一句话）
merge	拖拽两个同级物件合成更高一级，合成出目标等级物件即通关	公共三件（templateId/title/theme）+ 合成链长（3-6 级）+ 目标等级 + 棋盘格数（小棋盘 6-9 格）+ 物件文案 itemLabel	CDP 按可解局面派发确定性「按下-拖动-松开」序列合成至目标等级 → game_end{completed:true}
idle	点击产出资源 + 每秒自动产出，资源攒到目标量即通关；离开再回来补发离线产出	公共三件 + 点击产出量 + 每秒自动产出量 + 目标资源量 + 升级档（1-2 档：成本/倍率）+ 资源文案 resourceLabel + 离线产出参数（上限分钟数/效率折扣）	CDP 点击若干次后按 config 速率等待（确定性时长上限内）资源达标 → game_end{completed:true}
tycoon	进货→顾客到来→售出赚差价的经营循环，金币攒到目标量即通关	公共三件 + 进货成本/售价（差价对）+ 顾客节奏（间隔档位枚举）+ 目标金币 + 商品/顾客文案 goodsLabel/customerLabel	CDP 按「进货→售出」循环点击至金币达标 → game_end{completed:true}

三模板「真玩通关」均不改判定信封——仍锚定既有五条 AND（loaded ∧ completed ∧ duration>0 ∧ 无错 ∧ 包一致，orchestrator/player_cdp.py:833-841），只新增逐模板的驱动策略（现仅 clicker：点 target 次，player_cdp.py:13,669-676）。

2.3 idle 离线产出：本波最大架构分叉（必拍）

方案	做法	代价 / 收益
A. 纯前端时间差（推荐）	runtime 经 SDK storage 通道存「上次离开时间戳+资源量」，宿主侧落 localStorage；再次进入按 config 速率补发离线产出（带上限/折扣防爆数值）	✅ 零后端改动、零新契约实体、玩家匿名口径自洽（anonId 纯客户端已拍板，鉴权七项）；✅ CDP 取证保持确定性。❌ 换设备/清缓存丢进度；❌ 改本地时钟可刷产出——MVP 无排行榜/奖励兑现，无利益面，可接受
B. 服务端持久化	新建玩家游戏存档表 + 读写 API + anonId/登录态绑定	✅ 跨设备、防作弊。❌ 需要新契约（API+DB）、玩家身份绑定（匿名 anonId 与后续登录合并的迁移问题）、QA 闭环重测被服务端状态污染；工作量约为 A 的 3-5 倍（待执行版核实），且与「真实鉴权波」强耦合

推荐 A，服务端存档降 P1（与真实鉴权 execution 波合并考虑）。关键支撑现状：SDK 契约已预留 storage 双向键值消息类型（contracts/sdk-interface.d.ts:77），宿主侧明确留了挂点未实现（game-studio/src/host/GamePlayer.vue:251「social/storage 等骨架阶段不处理（留契约挂点）」）——本波把这个挂点的 storage 分支补上即可，存储留在宿主受信边界，runtime 内不引入可抛异常路径（守玩家 agent 五条 AND 之④，同 M-b② 红线，docs/agent-specs/2026-06-10-Mb渲染面-execution.md §3.1-4）。

2.4 merge 拖拽交互可行性评估

结论：可行，低风险。 依据：

• 现 runtime 交互仅 pointerdown（runtime/index.ts:221）；扩 pointermove/pointerup 跟踪是纯 Canvas 坐标计算，零 DOM、零新执行面，与 toString() 注入约束（函数体内自包含，runtime/index.ts:13-14）兼容。
• 玩家 agent 已用 CDP Input.dispatchMouseEvent 派发成对 press/release（player_cdp.py:566-569）；拖拽 = 在中间补 mouseMoved 帧，CDP 原生支持，仍是确定性脚本（非 LLM）。
• 降级预案（提案）：若执行版实测移动端拖拽体验差，同一套合成逻辑可切「点选两格合成」输入模式（仅输入层不同），CDP 策略退化为两次点击，更简单。

---

3. 波及面

flowchart TB
    subgraph 契约 contracts/
        S[templates/ 新增 3 份 schema] --- P[prompts: registry.yaml 增 3 条<br>04-config ×3 + eval Golden 集 ×3]
    end
    subgraph 前端 game-studio
        R[host/runtime/index.ts<br>新增模板分发 + 3 玩法循环 + 拖拽输入]
        ST[GamePlayer.vue/bridge<br>storage 通道挂点补实现 —— 仅 idle 需要]
    end
    subgraph 后端 game-cloud/aigc
        W[supportedTemplates 白名单加 3 项]
        L[PromptResourceLoader 单模板常量<br>→ 模板→资源映射]
        V[SchemaValidator 多 schema 缓存]
        T[getTemplateList 硬编码 1 条 → 4 条]
    end
    subgraph QA 闭环 orchestrator
        RB[run_batch 模板参数化]
        PC[player_cdp 逐模板驱动策略]
        J[judge 已通用·仅扩 Golden]
    end
    S --> R & V & PC
    P --> L & RB

层	改动点	现状出处（实读核验）
契约-模板	新增 contracts/templates/{merge,idle,tycoon}.schema.json，风格对齐 clicker（const templateId / additionalProperties:false / 数值带边界）	clicker.schema.json:6-11
契约-Prompt	registry.yaml 增 config.{merge,idle,tycoon}-designer 三条 + 04-config/ 三份 prompt + eval/ 三套 Golden 集；现仅 clicker 三件套（designer/adversary/fix）	contracts/prompts/registry.yaml:14-34
对抗评审	quality.adversary-review 正文措辞已模板中性（「当前模板机制」），但判定细则的 target 措辞与 Golden 集全部 clicker 域——需逐模板扩 Golden 守卫样本（含 kill 守卫），doctrine 是否分模板分段【待执行版核实】	06-quality/adversary-review.md:52,56
前端 runtime	runtime/index.ts 引入按 pkg.templateId 分发（GamePackage 顶层必填字段，contracts/game-package.schema.json:7,25）+ 3 个玩法循环；theme 色系派生/生命周期/资源加载基建复用 M-b② 成果（runtime/index.ts:88-114）；15KB 体积门重新核算（§5）	runtime/index.ts:72-79,221
前端宿主	仅 idle 批：storage 消息分支补实现（契约挂点已在 bridge.ts:63/contract.ts:38）	GamePlayer.vue:251
后端白名单	AigcExecutorProperties.supportedTemplates 现 ["clicker"]，逐批加项即开新模板；不在集合 → failed + no_template_match	AigcExecutorProperties.java:86-87、AigcGenerateExecutor.java:315-316
后端资源加载	PromptResourceLoader 的 prompt/schema 资源路径是 clicker 单模板常量 → 需改模板→资源映射（保持「注入 LLM 文本与服务端校验同源」设计，GameConfigSchemaValidator.java:21-22）	PromptResourceLoader.java:42-45
后端模板列表	getTemplateList() 硬编码返回 1 条 clicker（Create 页 canSubmit 依赖）→ 扩 4 条；validateTemplateExists 现仅非空兜底（TODO 注册表）→ 本波接 supportedTemplates 同源集合	AigcTaskServiceImpl.java:50-58,201-208
QA 编排器	run_batch.py 顶部 TEMPLATE_ID="clicker" / PROMPT_DESIGNER="config.clicker-designer" 硬编码 → 参数化；judge.py 结构校验已通用（按 templateId 读 schema，judge.py:159-161）；player_cdp.py 新增逐模板驱动策略（§2.2 表）	run_batch.py:57-60
feed/渲染面	新模板各自 draw 循环入画（theme 渐变/标题基建复用）；feed 卡片走 meta.title 链路不变，feed 不感知模板差异	runtime/index.ts:149-183

---

4. 关键权衡

1. 分批：merge 先行 vs 一波全建 → 推荐 merge 先行（§2.1，被否理由在内）。
2. idle 离线产出：纯前端 vs 服务端持久化 → 推荐纯前端 + SDK storage 通道（§2.3，被否理由在内）。
3. runtime 多模板架构：单工厂内部分发 vs 每模板独立工厂注入：推荐单 startRuntime 内按 templateId 分发。理由：toString() 注入约束下最简（一份注入面、一份生命周期/遥测红线代码）；theme 色系/资源加载/game_end 契约行只存在一处，杜绝 ×4 漂移；体积预算允许（§5）。被否：每模板独立 chunk/按需加载——注入机制复杂化、红线代码四份拷贝漂移风险，≤4 个模板的体量下属过度设计。

---

5. 风险与兼容

• 既有 30 款 clicker 内容池零影响（声明）：模板分发架构下 clicker 分支保持现行为（沿 M-b②「旧包逐像素零变化」同款向后兼容铁律）；生命周期事件名与 game_end 契约行逐字不动；验收强制含 clicker 回归（player_cdp.py --self-test 五条 AND 不回归，同 Mb 渲染面执行版 §5-6 口径）。
• dodge/runner/match「正确失败」路径保持：三模板不进 supportedTemplates → 生成请求仍走 no_template_match 失败桶（M-b 部署 #3.1 已实证 dodge 10s 正确失败，docs/mvp/MVP作战清单.md:47）；schema 文件原样保留供 P1 启用。
• 新模板首批 accept 低于 80% 的预期管理：clicker 首批 80.0% 的前提是 C1 spike 52 条种子 + 试点 6/6 + prompt 两轮升版的积累；新模板冷启动无此积累，试产批 accept 可能落在 50-70% 区间（推断，非承诺）。口径建议：试产批=校准批，不计入 M2 口径、不设硬门；M2 ≥80% 已由 clicker 达成收口（总账 §7），不受本波回退影响；每模板经 1-2 轮 prompt 升版后向 80% 量级收敛再开正式批。
• 15KB 体积红线：现 startRuntime(min) raw ≈2.2-2.6KB（M-b② 改后口径，红线 15,360B，Mb渲染面-execution.md §4）；+3 个玩法循环预估 +4.59KB → 总计 712KB，红线内但 M-b② 的 4,096B 软门必须本波重设；逐批跑 measure-runtime 体积门禁【预估数待执行版实测核实】。
• 玩家 agent 新策略的时序风险：idle 等待型取证依赖产出速率计时、merge 拖拽依赖坐标命中——执行版须定逐模板确定性预算上限（提案：单局 ≤90s）与失败重试口径，防 infra 误判混入 accept 分母。
• 代码注释陈旧（顺手修）：GameConfigSchemaValidator.java:22 与 AigcExecutorProperties.java:86 注释仍写「M-c 扩 dodge/runner/match」——R4 拍板前的旧口径，本波改注释为 merge/idle/tycoon（一行注释，无逻辑改动）。
• runtime 对未知模板无防御（现状缺口）：现 runtime 从不读 templateId，任何包都按 clicker 渲染（runtime/index.ts:72-79 仅消费 target/theme/scoreLabel）——生成侧被后端白名单挡住，但手工灌包会静默错渲染。本波模板分发落地时顺带补「未知 templateId → game_error」分支，堵住该缺口。

---

6. 验收标准（逐模板五级线，全过才算该模板 done）

级	验收线	口径
1	schema 入册	schema 落 contracts/templates/ + registry 注册 + 后端同源快照接入（PromptResourceLoader/Validator）+ 静态校验单测绿
2	runtime 真玩通关	staging 真实落包，玩家 agent 逐模板策略驱动，五条 AND 全绿；clicker 回归同窗五绿不破
3	QA 闭环扩展	对抗评审 Golden 集扩该模板（kill 守卫立得住=守卫样本全中）+ 批内查重口径覆盖
4	小批量试产	试产 10 条量级全自动流完零 infra；accept 为校准观测值（不设硬门，见 §5 预期管理）
5	入 feed	金丝雀≤10 直发口径入 feed + 浏览器实玩截图留档（渲染面：theme 入画 + 模板玩法可见）

---

7. 待拍板项（每项已带推荐）

#	拍板项	推荐	备选
1	分批节奏	两批：merge 先行收口出配方 → idle+tycoon 并行	一波全建（省 2-4 天，三个「第一次」叠加风险）
2	idle 离线产出	纯前端时间差 + SDK storage 通道宿主落 localStorage；服务端存档降 P1（并入鉴权波）	服务端持久化（跨设备/防作弊，工作量 3-5 倍+耦合鉴权）
3	每模板试产批量与口径	试产 10 条=校准批不设硬门；prompt 校准后正式批 20 条按 ≥80% 量级验收	直接 20 条上硬门（首批大概率红，浪费批次窗口）
4	merge 交互模式	拖拽为主（CDP 可确定性派发）；执行版实测移动端体验差则降级点选合成	直接点选合成（更稳但「合成」手感弱）

7.1 拍板结果（创始人 2026-06-10，四项全拍，均采推荐）

1. 分批节奏 = 两批：merge 先行（批① merge 单模板全链收口出「新模板接入配方」→ 批② idle+tycoon 并行复用）。
2. idle 离线产出 = 纯前端时间差 + SDK storage 通道（宿主落 localStorage）；服务端存档降 P1 并入鉴权建设波。
3. 试产口径 = 10 条校准批（不设硬门）+ 20 条正式批（accept ≥80% 量级）。
4. merge 交互 = 拖拽为主；执行版实测移动端体验差则降级点选合成（预案已备）。

---

8. 下一步

拍板后按双 spec 铁律出 execution 版（docs/agent-specs/2026-06-10-Mc模板波-execution.md，批①批②可分文件）：含逐模板完整 schema 字段定稿、prompt 三件套文案、runtime 分发实现步骤、体积门禁断言数、逐模板 CDP 策略伪码、验证门顺序与回滚路径。批① merge 收口后回填「新模板接入配方」至 .agents/skills/（接入步骤可复用，压批②成本）。