# 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 分批节奏：两批走（推荐）

```mermaid
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. 波及面

```mermaid
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.5~9KB → 总计 7~12KB，红线内但 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/`（接入步骤可复用，压批②成本）。