games-development-ai/tier2/HANDOFF.md

# tier2 交接 brief（6c6g → Mac）

2026-06-22。tier2 富游戏自治生成线的设计、HOW 计划与项目初始化已在 6c6g 完成，运行与调优交给 Mac / mini-desktop。这份 brief 说清你接手时有什么、接着做什么、以及哪些步骤必须在 mini-desktop 上跑。

> **⚠️ doc-sync(2026-06-25)。** 本 brief 是 2026-06-22 交接稿,两处口径已被后续裁定取代,**以运行时 SoT 与生成引擎统一执行 plan 为准**:① 下文凡「便宜档 n≥30 统计批跑」的 **tier2 验证口径**,已被创始人取代为 **n=5 收敛环**(并发跑 5、有错追加 5、收敛即 go;批跑底座保留、n 设 5)——便宜档 ≥80% 成功率门是另一回事(测成功率需统计样本)、不在此列;② L17「agentscope-runtime BrowserSandbox」——agentscope-runtime 已官方归档、能力并入 **agentscope 2.0.2 Workspace**(见 [`.agents/knowledge/agentscope-2.0-facts.md`](../.agents/knowledge/agentscope-2.0-facts.md)),沙箱底座以 2.0.2 Workspace 为准、不再引 agentscope-runtime。现行真相 = 运行时 SoT [`agentic运行时架构图说.md`](../docs/architecture/架构/生成引擎/agentic运行时架构图说.md) + 统一执行 plan [`2026-06-25-生成引擎统一执行计划`](../docs/plans/2026-06-25-生成引擎统一执行计划-AgentScope三档-plan.md)。

## 你接手时已有的

- **WHAT 需求**（已过 Codex+Opus 双评审、合入 dev/2.0.0）：`docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md`。
- **HOW 计划**（已过双评审、本分支 `docs/tier2-plan`）：`docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md`。10 个单元，Phase A（U1-U7，到 A/B 证据门）写成可立即执行的详细单元，Phase B（U8-U10）是 B 门通过后才投的纲要。
- **项目初始化骨架**（本目录 `tier2/`）：模块 `.agent` 边界声明、`README.md`、`gen-worker/requirements.txt`（锁 `agentscope==2.0.2`）、`ci/check-forbidden-import.sh`（运行期零碰 SAA 的守门）。
- **框架权威**：`/root/oss/agentscope`（2.0.2 源码）+ `.agents/knowledge/agentscope-2.0.2-facts.md`（速查）+ agentscope-skill 的 `references/v2-*.md`（v2 离线镜像）。⚠️ 该 skill 的 SKILL.md 正文示例是 1.x（`ReActAgent`/`MsgHub`），勿照抄。

## 接着做（按计划 Phase A）

照 plan 的 U1-U7 实现。几条评审已经替你压实、别再走弯路：

- **U2 是重头**：种子 `wg1/gen-worker/worker/agent_loop/{studio.py,config.py}` 的 AgentScope 框架接缝（6 个符号）与 2.0.2 兼容、是版本钉级别；但它拖着的 `validate.py`/`run.py`/`prompt.py`/`roles.py` 是 **LittleJS 专属**（`validate` 的「禁 import / 单 export default 工厂」规则对 Phaser 多文件工程完全反转），这几件要按 Phaser **重写、工作量≈net-new**，别按「fork+钉版本」排期。
- **U3 是前置阻断**：先做沙箱底座小验证（agentscope-runtime BrowserSandbox 是否暴露足够 `page.evaluate`/CDP，不够则回落复用 `play.cdp.cjs` 路），再把 CDP 探针为 Phaser **重写**（`#game-engine` 选择器 / `__engine.frame` 帧源 / boot 信号全换）。这道结论出来前，U7 的生成迭代跑不起来。
- **U7 成本取证**：M3 走 `AnthropicChatModel`，所以成本台账要补一个 `RecordingChatModel(AnthropicChatModel)` 变体——现有的只覆盖 OpenAI 路，不补则 A 门 M3 成本抓不到。
- **判据离散**：A 门 = M3 产物先确定性过 L1（机器判）+ 创始人试玩（软）两段与；B 门 = 便宜档 n≥30 达《tier2 实现详设》阈值（硬）才转 Phase B。

## 环境切分（重要）

- **6c6g 已能完成 / 已交付**：项目初始化骨架（本目录）；按计划 U1（`pip install`、纯函数复用单测、forbidden-import CI）、U2 的 mock 级集成测试与版本钉，理论上 6c6g 也能跑（无 chrome）。
- **必须在 mini-desktop 真跑**：凡需 chrome/headless + esbuild 的——U3（CDP 探针矩阵真验）、U4（mini-肥鹅 构建+真跑过门）、U6（门对真页 pass/fail 真验）、U7（M3 smoke、四熔断真触发、闭环端到端、n≥30 spike）。**6c6g 禁 chrome（exit 144）**。

## 与 A-model 分支的协调（重要 · 你同时在做这条）

你的 `feat/mac-amodel-foundation`（Tier1 廉价线 A-model agentic 优化）与 tier2 边界清晰、分立（创始人 2026-06-23 裁）：A-model 吃 LittleJS 轻量经营档，tier2 吃 Phaser 重表现富游戏档。但 A-model 造的几样资产 tier2 要**接住、别重新发明**（详见计划「与 A-model 分支的关系」节）：

- **插件契约（最大协同）**：`scene-fsm/hud-ui/session-score/timer-scheduler` 的 `api.d.ts` 是引擎无关零语义契约 + `sim-business` 配方——tier2 Phaser 能力面复用其契约/命名/配方，仅渲染 impl 按 Phaser 重做。
- **循环范式**：`amodel-gen/gen.mjs` 的多轮 ReAct done 门 + check/build 快反馈 + 历史压缩，是 tier2 U2/U7 的 working reference（种子仍 `studio.py`）。
- **九门基线**：A-model 改过 `play.cdp.cjs`（SAA-mode + driven 感知 advisory 分级 + `_forensicsView`）——tier2 U3/U6 fork 源与行号锚点**钉到 A-model 合并后的版本**重取，并复用其 driver 感知分级范式。
- **源项目契约**：A-model 升了 `source-project.schema.json` oneOf(1.0/2.0)；tier2 **仍另立独立 schema**、不加 3.0 进同一 oneOf（理由见计划 KTD7/U9）。

A-model 合并 dev/2.0.0 后，tier2 接缝（`play.cdp.cjs`、`source-project.schema.json`）会刷新——实现 tier2 时以合并后版本为准对账。

## 0 号 spike 结果（2026-06-24，feie-005 跑出 decision=accept）

M3（MiniMax-M3，中等模型）自治写出的面包店经营合成富游戏，在 `feat/tier2-phaser-engine` 分支上首次跑到
**decision=accept**：9 道 L1 门（A_boot/B_uncaught/C_frame/D_render/E_live/F_wiring/G_input/H_progress/I_control）
全过，富游戏三门（三联动/经济/latch）全过，`finished=True`，无熔断，tokens≈20K/36K（+508K 缓存），墙钟约 610s。
金标装配链冒烟（fixture）始终保持 ACCEPT，门一道没放松——失败全在 M3 产物对契约的命中，不在平台。

第一次满 40 轮跑只过 5/9（decision=fix），收敛靠拆掉四个真问题，每个都补成机器门：

- **loop 不自纠（头号）**：AgentScope 2.0.2 原生 ReAct 一旦模型产出「无 tool_call 的纯文本回合」就退出
  （`_agent.py:612`），M3 调一次 run_gates 看到 fix 就收尾、根本没续修（tool_calls=9/40、无熔断）。
  修法 = 编排层加有界外层 resume（`agent_loop/studio.py`）：agent 停下后若没真 finish 且门没绿且有预算，
  带 verdict 失败反馈再 reply（跨 reply 保留 memory=原地续修），上限 6 次，middleware 硬熔断 60/80 兜底。
  外加 finish 门（门没绿不许 finish）。这是 wg1「外层 Python repair」范式的回归——纯自治 ReAct 会过早放弃。

- **数据表自创 schema**：平台锁定的 `tables.js` 按固定 key 读数据表（mergeChains/currencies/orders{requires:{id:qty}}），
  M3 却自创 recipes/initialCoins/数组 requires → 合成系统空转却仍 boot（假绿）。
  修法 = `validate_datatable`（build 段自动跑）：查 schema + DAG 无环 + 订单可达性 + 破产路 patience 可达性，
  失败响亮回喂精确指引（平台读哪些 key、你缺/错哪个）。

- **改了平台锁定文件**：M3 重写了装载胶水 `main.js`，丢了 recHook 透传 → F 门 calls=0、合成不记引擎调用。
  修法 = `LOCKED_PLATFORM_FILES`（toolkit `write_source` 拒改 main.js/game-core/systems/layout/tables/util/play-runtime）。

- **破坏表现层平台命脉**：输入路由（命中→core.tapCell）与逐帧 `core.update` tick 原先混在 agent 可写的
  play-scene 里，M3 重写时一起改没了/坐标错位/把工厂写成 `class extends Phaser.Scene`+`init(data)` 取 core
  （但 main.js 用工厂模式建 scene、不喂 data → this.core=undefined → 整个空转）。
  修法 = 抽进锁定文件 `src/scenes/play-runtime.js`（bindInput+tick）+ `validate_play_scene` 契约门（build 段跑）：
  play-scene 必须工厂模式收 deps、闭包捕获 core、返回配置对象、暴露 handleNormalizedInput、调 bindInput+tick。

**对「中等模型自治写富游戏」这条路的判断 = go（留观微调）。** M3 一旦被机器门挡在正确契约上，有能力自治写出
过全门的多系统富游戏，还能从 verdict 反馈自己修平衡（把 patience 从 45~65s 调到 8~12s 修破产路）。但收敛
**强依赖机器门把每类契约违规变成响亮可修反馈** —— 纯放开 ReAct + 软约束 prompt 不行（它会过早放弃 + 自创 schema +
改平台文件）。下一步：n≥30 跑测真实成功率与墙钟/成本分布（本次 n=1 是机制验证、非统计）；把四道门里偏脆的文本契约
检查（play-scene 工厂结构）考虑做成更稳的结构化校验，或进一步收窄 agent 可写面。相关 commit 在
`feat/tier2-phaser-engine`（b43d59c/f8ec30c/0fd0d4f/f64dcc6/8f2bbce 五个）。

## 图说对账补全（2026-06-24）

把 0 号 spike 为过门收窄掉、但 tier2 图说明确要求的「核心引擎待补」项补齐。改动全部加性 / observe-only：金标 fixture 冒烟仍 ACCEPT（九门 9/9 + 富游戏三门 3/3，门一道没放松），真依赖下全链 import + 自测 + 一款真 M3 跑端到端验证通过。

**n≥30 runbook 执行基建（G 族）。** 第一段只跑了 M3、n=1、driver 冻结；要测真实成功率与成本分布，得先有批跑底座。新增便宜档模型 client（`worker/config.py` 的 `build_model_openai`，deepseek-v4-flash/pro 经 new-api OpenAI 兼容路，与 M3 的 Anthropic 原生路并存，base 口径相反、各自注释写清）；结构化采集字段（`worker/run_record.py`，把 G4 采集字段表编译成可序列化 RunRecord，含退路树分流键 fail_system）；退路树五出口判定器（`worker/fallback_tree.py`，Q1–Q4 数字触发线 → go/R1/R2/R3/KEEP，★阈值集中常量区待实测校准）；批跑编排与矩阵聚合（`batch_run.py` 跑 model×variant×n 矩阵、断点续跑、失败隔离；`aggregate.py` 出三图并喂判定器）。

**观测/成本接线（H 族）。** 此前 `observability/{cost,trace}.py` 件已造齐却是孤儿、从未接进 run 主链。现在 `run_studio` 收口把 RecordingChatModel.records 折成 ¥（新增 `observability/newapi_pricing.py` 活读 new-api /api/pricing 倍率，取不到回落显式参数并告警，绝不中断主链）；新增 `Tier2TraceMiddleware` 挂在 writer agent 最外层洋葱，把 ReAct 全事件旁路 ingest 进 TraceAdapter。真跑实测：cost_rmb=1.29（pricingSource=newapi-live）、trace 647 事件 dropped=0。`contracts/trace/` 立了 additive trace 事件契约位（忠实于 trace.py 真实落 sink 形状）。

**L3 视觉软检接线（D 族 · observe-only）。** player_system 提示词此前从不被调、verdict.L3.score 恒 null。现在 `run_studio` 收口后调一次 M3 多模态（真截图 after-play.png + 真玩取证 → fun 1–5 映射 0–100 分），只写 verdict.L3.{scoreOnly,score,notes}，绝不参与 decision。真跑实测：L3 score=25 准确指出「`[object Object]` 满屏 + 订单零交付却判胜」，而 decision=fix 仍由 L1 硬门 / 熔断裁、与 L3 无关——observe-only 铁律落实、防 Goodhart 成立（坏游戏正确被拒，金标仍过）。

**没补的，按既定决策留后，不投机抢建：**
- *设计判后续（plan 决策⑤ gate 到 B 门后才投）*：阶段 1 工作室 Agent Team 多 agent 设计、第二装载分支 + 源项目落库取回（交后端）、完整配置外置、控制面 / 管理面（B 族；D12 与 GenerationDispatcher 属 SAA Java 后端、不在本分支）、ReMe、Agent Service / MessageBus / Workspace 双轴 / checkpoint（决策②明写「本地 runner·不上 Agent Service」）。
- *spike 统计相（是「跑」不是「写」）*：n≥30、5×6 题面变体、模型矩阵跑序、过门率 / 成本统计、★阈值校准、创始人亲玩软门——批跑底座现已就位，可直接执行。
- *跨分支（待 A-model 合并对账）*：4 个引擎无关插件复用、advisory 分级（本引擎分支 play-phaser 已字面落 driven 两态，合并时对账即可）。
- *图说待回写（交生成引擎子树 doc 线 / 在飞 session；本会话不跨分支跨 session 改 canonical）*：A4/C3 把「官方 ReplyBudgetControlMiddleware 软刹」画成现成，但 2.0.2 源码核验该类不存在（tier2 已用自建 on_system_prompt 替代）；C3 预算闸实际是硬熔断、比图说当前口径强；C 族 frontmatter「尚未落代码」已过时（0 号 spike PASSED）；D 族 advisory 标「待 A-model 合并」，本引擎分支已字面落。

## 协调

按 git 中介异步：本分支 `docs/tier2-plan` 已推送。你在该分支实现、提交；6c6g 侧（我）审 commit、按需更新计划/设计。完成判据是 git push，不是读屏。