diff --git a/docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md b/docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md new file mode 100644 index 00000000..c68d571b --- /dev/null +++ b/docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md @@ -0,0 +1,345 @@ +--- +title: "feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.3 + Phaser）" +type: feat +status: active +date: 2026-06-22 +origin: docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md +--- + +# feat: tier2 富游戏自治生成线实现方案（AgentScope 2.0.3 + Phaser） + +## Summary + +把 tier2 富游戏自治生成线从设计落成可执行序列：先在新顶层 `tier2/` 搭起一个独立的 AgentScope 2.0.3 Python 模块（fork 现有廉价线种子 worker、单写起步、本地 runner、不上 Agent Service），再用 M3 写代码逻辑、mmx 产美术音乐，在三层校验（初期只焊 L1）的笼子里连续迭代生成引擎。顺序连续、判据离散——M3 证路是软门、便宜档 n≥30 是硬门、退路树沿用《tier2 实现详设》的数字触发线，只有硬门通过才投入重机器（工作室 Agent Team、第二装载分支、配置外置、控制面、ReMe）。Phase A（集成+环境+迭代）写成可立即执行的详细单元；Phase B（重机器）写成纲要、显式 gated 在 B 门后。 + +## Problem Frame + +绘境现有生成线只擅长超休闲单局小游戏（LittleJS 声明式数据壳 + 便宜模型填空 + 九门 harness）。合成、经营、挂机这类多系统富游戏（肥鹅美食街档）它做不出——难在重 UI 表现层、多系统稠密接线、大内容量。2026-06-20 对抗审查把"声明式数据壳 + 自由 JS"判到几何色块单局这一档的天花板，富游戏必须另起一轨。 + +tier2 就是这条轨：用约束自治（O2）的单写 ReAct agent + Phaser 引擎，在确定性验收门里把富游戏逼出来。它的 WHAT 已在 origin 充分设计并过双评审。但整条线最深、最没证过的赌注是——**便宜或中等模型的自治 agent 能不能稳定写出那约 56% 的表现层**。历史上王蓝莓 12 文件经营游戏与 2026-06-11 Phaser 五门 spike 证的都只是"形态"（真引擎工程装得下、Phaser 能过门），用的都是最贵模型 Fable + 重人工编排，不是便宜模型自治。这份计划要做的，是把这条赌注在最便宜的时候、用可判定的判据验掉，而不是在未验证的机器上过度投入。 + +## Key Technical Decisions + +- **代码落点 = 新顶层 `tier2/`**：独立模块、与 `wg1/`（廉价线 Python worker）并列、与 game-cloud 的 Java SAA 线运行期零耦合。理由：origin 定 tier2 为"独立 AgentScope 模块、SAA 可删、运行期零依赖"；物理隔离 + forbidden-import 守门把这条落地。这是可调整的——若改为 `wg1/` 下或别的根，全部 `**Files:**` 路径随之平移。 + +- **锁 AgentScope 2.0.3；但「迁移=版本钉」只对 AgentScope 框架接缝成立，种子业务模块链要按 Phaser 重写**：迁移面取证证明种子用到的 AgentScope 框架符号（`Agent`/`ReActConfig`/`UserMsg`/`OpenAICredential`/`OpenAIChatModel` + duck-typed `ChatUsage`）在 2.0.3 全兼容、0 改签名——**这层确实是版本钉**（`requirements` 钉 `2.0.3`）。**但 `studio.py` 拖着的业务模块链（`validate.py`/`run.py`/`roles.py`/`prompt.py`）是 LittleJS 专属、要按 Phaser 重写、工作量≈net-new**：`validate` 的硬规则（禁 import / 禁 littlejsengine / 必须单 `export default` 工厂）对 Phaser 多文件 `src/` 工程**完全反转**；`run` 的 `scaffold`/`build`/`play` 是 LittleJS 单包 iife 形态；`roles.DESIGN_SYSTEM` 全是声明式壳 few-shot。别让"框架符号兼容"误导成"整个 U2 是平移"。真正的 AgentScope 新功夫另在 net-new 的多轮 ReAct / Workspace / Service（Phase B）。 + +- **顺序软、判据硬**：先集成+环境再连续迭代（顺序连续，不设建设前的离散生死门），但生成证据的判据保持离散可判定——A 门 = M3 证路（软，创始人试玩判"有肥鹅味的可玩雏形"）；B 门 = 便宜/强便宜档 deepseek-v4 跑 n≥30，过门率/单款成本/收敛/失败分布达《tier2 实现详设》阈值（硬）；退路树沿用《tier2 实现详设》数字触发线（v4-pro<40%→更模板化 / 某系统装不出→补骨架 / 全线<20%→便宜模型天花板换档），达任一触发线即转退路、不再调参。双评审揪出"软化顺序时别把判据也软化"是本计划最要紧的一条纠正。 + +- **起步只单写（阶段 2），工作室 Agent Team（阶段 1）后置到 Phase B**：最快拿到"M3+mmx 能不能产过门 mini-肥鹅"的真信号。生产态正式流程仍是阶段 1 工作室设计 → 阶段 2 单写实现；起步只跑阶段 2 是 spike 范围裁剪，不是永久颠倒。 + +- **复用 `_client.py`/`cost.py` 走显式传参，禁读模块级全局**：`cost.compute()` 已是纯函数显式传参可直接复用；但 `_client.chat()` 内部读模块级 `BASE_URL`/env key —— tier2 调用须把 endpoint/key/model/pricing/quota/retry/timeout 全显式传入，否则暗中继承 SAA/L2 的模型路由与预算表，"SAA 可删"成空话。 + +- **CDP harness 对 Phaser 是重写适配层、不是参数化；其底座是迭代开跑前的前置阻断验证**：`play.cdp.cjs` 的探针硬编码 LittleJS 专属 `#game-engine` 选择器、`window.__engine.snapshot().frame` 帧源、`window.__gameHostEngineInitFired` boot 信号；Phaser 的帧源、canvas 注入、活动 hash 全不同。沙箱底座（agentscope-runtime BrowserSandbox 是否暴露足够 `page.evaluate`/CDP，不够则回落复用 `play.cdp.cjs` 路 + Phaser driver 重写）须在生成迭代开跑前出结论（origin 标记的 spike 前置阻断项）。 + +- **tier2 装载/契约/沙箱独立，绝不碰 Tier0/1 ECS-lite 装载路**：`contracts/agent-loop/source-project.schema.json` 第 5 行明示 tier2 另立独立 schema；`boot-game-host.js` 的 `opts.engine` 注入边界可参照、但 Phaser boot 序列独立、不改它；`build-from-source.mjs` 的 `new Function` + 静态禁则路不复用（tier2 是真 `src/` 工程 + 真 Workspace 沙箱）。 + +- **M3 走 Anthropic 原生端点 + 启动校验 + 首 smoke 三证**：`AnthropicChatModel` + `AnthropicCredential.base_url` 指 new-api `/v1/messages` + thinking 分离；启动前校验 `max_tokens` 严格大于 `thinking_budget`；首个 M3 smoke 必须证明 thinking 分离 / 工具调用 / new-api quota 计费三者都通。模型统一从 new-api 出口走（`baseUrl`+`NEWAPI_KEY`），协议/SDK 不锁。 + +- **三层校验初期只焊 L1，L3 只评分绝不阻塞/拒发，绝不让 LLM 自评**：L1 编译/启动/运行错误必须解决、循环；L2 设计符合尽量；L3 效果（M3 视觉软检）只进趋势/告警/人工终审减负，绝不参与"算不算完成"、绝不单独拒发（防 Goodhart）。 + +- **forbidden-import CI 守门升为 pre-spike 验收项**（= 《tier2 四层工程架构》§11 T4）：禁运行期 import SAA 配置 / 现有 `studio.py` 运行态 / L2 模型路由表；只许种子拷贝 + 显式传参复用 `_client.py`/`cost.py`。 + +## High-Level Technical Design + +实现主轴（顺序软 / 判据硬 · Phase A 详 / Phase B 纲要）： + +```mermaid +flowchart TB + subgraph PA["Phase A · 集成+环境+生成迭代（立即可执行）"] + U1["U1 tier2 独立模块骨架
落点 tier2/ · 锁 2.0.3 · 复用 client/cost · forbidden-import"] + U2["U2 fork 种子 → 2.0.3 + Agent 内多轮 ReAct
放开 max_iters · 两阶段角色(起步只单写)"] + U3["U3 Phaser 浏览器探针路径(前置阻断验证)
沙箱底座小验证 + CDP harness 为 Phaser 重写"] + U4["U4 mini-肥鹅 Phaser 靶子
经营骨架+耦合点+数据表schema+资产占位"] + U5["U5 mmx 资产管线接成 agent 工具"] + U6["U6 L1 门重写 + 富游戏专属门
引擎无关 L1 + 联动/经济门 + latch"] + U7["U7 生成迭代闭环 + 证据门
M3 Anthropic端点+三层校验(只L1)+四熔断"] + U1 --> U2 --> U7 + U1 --> U3 --> U7 + U4 --> U7 + U5 --> U7 + U6 --> U7 + U3 --> U6 + end + U7 --> GA{"A 门 · M3 证路(软)"} + GA -->|过| GB{"B 门 · 便宜档 n≥30(硬)
达《实现详设》阈值?"} + GA -->|不过| R["退路树(数字触发线)"] + GB -->|达退路线| R + GB -->|过 · 硬证据| PB + subgraph PB["Phase B · 重机器（B 门后才投 · 纲要）"] + U8["U8 工作室阶段1 + Agent Service
create_app + Agent Team(SubAgentTemplate/EXPLORE)"] + U9["U9 第二装载分支 + tier2 源项目契约七要素"] + U10["U10 平台化: 配置外置(引线A)+控制面(D12/trace)+ReMe"] + end +``` + +依赖与排序：U1 是地基（其余都依赖）；U2/U3/U4/U5/U6 可并行推进，全部汇入 U7 的迭代闭环；U3 的沙箱前置阻断验证须在 U7 开跑前出结论，且 U6 的门重写依赖 U3 的探针。Phase B 三单元在 B 门通过后才进入细化与建设。 + +## Requirements + +承接 origin 的 R1-R21（见 origin: `docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md`），按关注点分组并溯源到实现单元。 + +**起步 · 集成与环境（无论生成证据如何都要做）** + +- R1. AgentScope 集成 pre-spike 档：起步只用 `Agent`+`ReActConfig`+`Workspace` 本地 runner，不上 Agent Service / Agent Team / 配置外置。→ U1, U2 +- R2. 单写循环演进 + 版本钉：fork 种子，`agentscope` 钉 2.0.3，多轮自治从外层 repair 搬进 Agent 内 ReAct（放开 `max_iters`），运行期零依赖现有 worker。→ U2 +- R3. Phaser 浏览器探针路径前置阻断验证：Workspace 解决代码/构建/shell；L1 门要的浏览器真跑低层探针接 CDP harness，对 Phaser 是重写；底座可行性须迭代开跑前出结论。→ U3 +- R4. mini-肥鹅 fixture（迭代靶子 + spike 产物目录范本）：经营骨架（三系统+耦合点、先天过 boot），产物以 `Workspace.workdir` 本地多文件工程形态、harness 直接构建+真跑，不走正式契约/落库。→ U4 +- R5. mmx 资产管线最简形态：接成单写 agent 可调资产工具。→ U5 +- R6. L1 门抽象重写：现九门为 LittleJS 单文件壳而建、带病灶，抽象重写进 L1（引擎无关）+ L2（设计符合），补富游戏专属跨表联动门/经济门、修 latch。→ U6 +- R7. 成本计量 + 轨迹最小版：接 new-api quota（复用 `cost.py`），落最小轨迹仓。→ U1, U7 + +**生成迭代 · M3 + mmx · 判据离散** + +- R8. M3 走 Anthropic 原生端点 + smoke gate：启动前校验 `max_tokens > thinking_budget`，首 smoke 证 thinking 分离/工具调用/quota 计费。→ U7 +- R9. 三层校验初期只焊 L1，L2 尽量、L3 只评分绝不阻塞/拒发、绝不让 LLM 自评。→ U6, U7 +- R10. 四道熔断（步数硬顶/预算闸/卡死探测/双层超时），任一触发优雅收尾、每轮 checkpoint；早期预算闸只需时间盒，强制 fail-closed 是规模化前项。→ U7 +- R11. 生成证据判据离散：A 门 M3 证路（软）/ B 门便宜档 n≥30（硬，达《实现详设》阈值）才转重机器。→ U7 +- R12. 退路树离散触发：沿用《tier2 实现详设》数字触发线，达任一线即转退路、不再调参。→ U7 + +**重机器 · B 门通过后才投** + +- R13. 阶段 1 工作室（Agent Team 星形）：`SubAgentTemplate`+`PermissionMode.EXPLORE` 只读设计 worker，跨 session 对话，设计结论写工程内文档。→ U8 +- R14. 第二装载分支 + tier2 源项目契约七要素（独立 schema + finish 工具，与 ECS-lite 解耦并存）。→ U9 +- R15. 完整配置外置（认领引用线A 阶段 2-3）。→ U10 +- R16. 控制面接入：D12 补 tier2 入口/预算/并发/补偿，统一 trace 契约，观测走 `TracingMiddleware`→OTel。→ U10 +- R17. 长期记忆/经验召回（ReMe vs 树内 mem0，起步前小验证 + 创始人定）。→ U10 + +**收口 · 对齐（横切硬约束）** + +- R18. 正典档对齐（《自治富游戏引擎》升三层校验口径）——已在 origin 收口提交完成。→ 已交付 +- R19. §11 六条跨档 TODO 作 follow-up doc-sync。→ Open Questions +- R20. forbidden-import 守门升为 pre-spike CI 静态检查验收项（= 四层档 T4）。→ U1 +- R21. spike 产物承载 = `Workspace.workdir` 本地多文件工程，harness 直接构建+真跑，不走正式契约/落库（落库随重机器后置）。→ U4 + +--- + +## Implementation Units + +### Phase A — 集成 + 环境 + 生成迭代（到 A/B 证据门 · 立即可执行） + +### U1. tier2 独立模块骨架 + 依赖 + 复用 + forbidden-import 守门 + +- **Goal**：在 `tier2/` 立起一个独立 AgentScope 2.0.3 Python 模块骨架，含独立依赖、对 `_client.py`/`cost.py` 的显式传参复用接缝、以及禁运行期 import SAA 的 CI 守门。这是其余单元的地基。 +- **Requirements**：R1, R7, R20 +- **Dependencies**：无 +- **Files**： + - `tier2/gen-worker/requirements.txt`（新建：`agentscope==2.0.3` + `phaser` 工具链所需 + `pyyaml`；不复用 `wg1/gen-worker/requirements-l2.txt` 的 2.0.1） + - `tier2/gen-worker/worker/cost_reuse.py`（新建：薄包装，显式传 endpoint/key/pricing/quota，内部转调 `wg1/gen-worker/worker/cost.py:compute`——纯函数可直接复用） + - `tier2/gen-worker/worker/client_reuse.py`（新建：薄包装，显式传 endpoint/key/model/retry/timeout，禁读 `_client.py` 模块级 `BASE_URL`/全局） + - `tier2/.agent`（新建：模块目标/边界/红线声明，参照 `game-runtime/games/_wg1-gen/.agent`） + - `tier2/ci/check-forbidden-import.sh`（新建：参照 `.agents/tools/check-deadlinks.sh` 形制，扫 `tier2/` 禁 import `wg1.*` 运行态 / SAA 配置 / L2 模型路由） + - `tier2/README.md`（新建：指向本 plan + origin + agentscope-2.0.3-facts） +- **Approach**：tier2 自有 env、独立锁 2.0.3。复用边界严格走"显式传参"——`cost.compute()` 已是纯函数直接调。**注意 agent 循环真正消费的不是 `_client.chat()`（那是 L1 裸路、agent 不调），而是 `_client` 的模块级 `BASE_URL` + `get_api_key()` + import 副作用（`.env` 加载 + 必须在 import agentscope 前设 NO_PROXY 代理旁路——`config.py:11` 注释明示是 spike 头号坑）**。所以要显式参数化的是 endpoint/key 来源 + 显式、有序地处理那个代理旁路副作用，而非包装 `chat()`。forbidden-import 脚本进 CI（pre-spike 验收项）。 +- **Patterns to follow**：`wg1/gen-worker/worker/cost.py:compute`（纯函数范本）、`game-runtime/games/_wg1-gen/.agent`（模块隔离声明）、`.agents/tools/check-deadlinks.sh`（CI 脚本形制） +- **Test scenarios**： + - `tier2/ci/check-forbidden-import.sh` 对一个故意 `import wg1...` 的样例文件返回非零（守门生效）；对干净 tier2 代码返回零。 + - `cost_reuse` 用显式传入的 pricing/qpu/usd_rate 调 `compute`，结果与直接调 `wg1` `cost.compute` 一致（复用未走样）。 + - `client_reuse` 在未设模块级 `BASE_URL` 时仍能用显式 endpoint 工作（证不依赖全局）。 +- **Verification**：`pip install -r tier2/gen-worker/requirements.txt` 成功且 `agentscope.__version__ == "2.0.3"`；forbidden-import CI 在干净树通过、对违例样例失败；复用包装的单测绿。 + +### U2. fork 种子 worker → 2.0.3 + Agent 内多轮自治 ReAct + +- **Goal**：以 `wg1/gen-worker/worker/agent_loop/studio.py` 为种子拷贝到 `tier2/`，版本钉 2.0.3（代码零签名改），把多轮自治从外层 repair 循环搬进 Agent 内 ReAct（放开 `max_iters`），并按两阶段重写角色 prompt（起步只单写阶段 2）。 +- **Requirements**：R1, R2 +- **Dependencies**：U1 +- **Files**（标注 **fork**=框架接缝可平移 / **重写**=LittleJS 专属、按 Phaser 重做、工作量≈net-new）： + - `tier2/gen-worker/worker/agent_loop/studio.py`（**fork**：编排骨架可平移；`_agent_reply` 的 `ReActConfig(max_iters=1)` 放开为多轮，外层 `for attempt in range(max_repairs)` 改为 Agent 内 reason→act→读结果→再 reason） + - `tier2/gen-worker/worker/agent_loop/config.py`（**fork**：保留 `RecordingChatModel.__call__` 成本取证覆写——2.0.3 仍命中；清 `config.py:30-32` 关于 DeepSeek cache 的过时注释） + - `tier2/gen-worker/worker/validate.py`（**重写**：现 `extract_code` 只认单 ```js 块、`validate` 硬规则=禁 import / 禁 littlejsengine / 必须单 `export default` 工厂——对 Phaser 多文件 `src/` 工程完全反转，重写为多文件抽取 + Phaser 工程校验） + - `tier2/gen-worker/worker/run.py`（**重写**：`scaffold`/`build`/`play` 三件是 LittleJS 单包 iife 形态，换成 Phaser 多文件 scaffold + 构建 + Phaser CDP harness 接线） + - `tier2/gen-worker/worker/prompt.py`（**重写**：`build_messages` 按 Phaser 工程 + 两阶段重组） + - `tier2/gen-worker/worker/agent_loop/roles.py`（**重写**：`DESIGN_SYSTEM` 全是 LittleJS 声明式壳 + gatespec/tap-targets few-shot，按 Phaser 富游戏 + 单写实现角色重写；阶段 1 工作室角色留 Phase B） +- **Approach**：fork-为-起点、独立演进、运行期零依赖现有 worker、不回写（origin §1.1）。**分清两层**：AgentScope 框架接缝（`studio.py`/`config.py` 的 6 符号）据迁移取证是版本钉、零签名改，重点回归验证 `RecordingChatModel.__call__` 仍被 Agent 经 `await model(...)` 命中（成本取证命脉）；**但 `validate`/`run`/`prompt`/`roles` 是 LittleJS 专属业务逻辑、需按 Phaser 重写（≈net-new），按"6 符号兼容"排期会严重低估**。多轮 ReAct 也是 net-new（种子是单轮），用 2.0.3 `Agent`+`ReActConfig(max_iters=N)`。 +- **Execution note**：先为"Agent 内多轮 ReAct 写源→build→读 verdict→再 reason"写一个最小集成测试（mock 模型 + 假 verdict），证循环骨架跑通，再接真 M3。 +- **Patterns to follow**：`wg1/gen-worker/worker/agent_loop/studio.py`（种子，run_studio@230 / _agent_reply@153 / repair@266 / 五接线点@270-300）、`config.py:RecordingChatModel`（usage 取证） +- **Test scenarios**： + - Agent 内多轮：mock 模型先返回"调写工具"再返回"纯文本收尾"，循环正确在收尾终止、产出 src/。 + - `max_iters` 硬顶：mock 模型永远调工具，循环在 `max_iters` 处停（不无限）。 + - `RecordingChatModel.__call__` 在 2.0.3 被命中：跑一轮真/mock 模型，断言 per-call usage（input/output/cache_input tokens）被捕获。 + - 版本钉：`agentscope.__version__ == "2.0.3"` 且 6 个框架符号 import 不报错。 + - 消息形态复验（2.0.3）：`UserMsg(name, content=str)` 仍把 str 包成 `TextBlock`、`agent.reply` 返回 block-list `Msg`（这层是形态契约、不在 6 符号 import 面内）。 +- **Verification**：最小集成测试绿；一轮 mock 端到端（组 context→reason→act 写 src/→读 verdict→收尾）跑通；usage 捕获非空。**注意：6 符号 import 通过≠迁移完成**——`validate`/`run`/`prompt`/`roles` 的 Phaser 重写另有各自验收（不被本单元的框架接缝绿误判为"迁移已完成"）。 + +### U3. Phaser 浏览器探针路径（spike 前置阻断验证 + CDP harness 重写） + +- **Goal**：先做沙箱底座小验证定方案，再把 `play.cdp.cjs` 的低层探针为 Phaser 重写（参数化引擎钩子 + 新增经营 driver）。这是生成迭代能否照设计跑起来的前置阻断项。 +- **Requirements**：R3 +- **Dependencies**：U1 +- **Files**： + - `tier2/harness/SANDBOX-PROBE.md`（新建：小验证结论——agentscope-runtime BrowserSandbox 是否暴露足够 `page.evaluate`/CDP；不够则回落自建薄沙箱 + 复用 `play.cdp.cjs` 路） + - `tier2/harness/play-phaser.cdp.cjs`（fork 自 `game-runtime/games/_wg1-gen/_shared/play.cdp.cjs`：参数化 canvas 选择器 `#game-engine`、帧源 `window.__engine.snapshot().frame`、boot 信号 `window.__gameHostEngineInitFired` 三个 LittleJS 专属钩子为 Phaser 等价；新增经营类 driver） + - `tier2/harness/drivers/business-sim.driver.js`（新建：经营品类确定性 driver——"点合成→凑齐订单物品→交单→看金币涨"序列） +- **Approach**：先出 SANDBOX-PROBE 结论（前置阻断），它决定本地 runner 选型。CDP 探针对 Phaser 是**重写适配层**——帧源、canvas 注入、活动 hash 取法全不同，不是简单参数化。沿用 `play.cdp.cjs` 的 `checkAssertion`/`runDriver` 分发/九门组装骨架，但引擎钩子与经营 driver 全换。 +- **Patterns to follow**：`game-runtime/games/_wg1-gen/_shared/play.cdp.cjs`（探针 #game-engine、`__engine.frame`、boot 信号、9 driver runDriver@217、checkAssertion@189、九门组装 main@894）、`game-runtime/src/host/boot-game-host.js`（`opts.engine` 注入边界，参照不改） +- **Test scenarios**： + - Covers AE（机制地板）：一个手搓的过门 Phaser mini 经营页跑过重写后的 L1 门（boot/frame/像素/hash/输入改状态/控制跟手）。 + - 一个故意空壳页（不响应输入）被重写后的门判 fail（守假绿）。 + - business-sim driver 真输入驱动 mini-肥鹅到赢/输双终态并 latch。 + - 沙箱探针矩阵：navigate/screenshot/`page.evaluate`/输入注入逐项在选定底座上可用（SANDBOX-PROBE 结论的可执行验证）。 +- **Verification**：SANDBOX-PROBE.md 出明确结论（复用现有 CDP 或回落自建薄沙箱）；重写后的 harness 对过门页 pass、对空壳页 fail；经营 driver 跑通赢输双路径。 + +### U4. mini-肥鹅 Phaser 靶子工程 + 数据表 schema + 资产占位 + +- **Goal**：预建 mini-肥鹅 经营骨架 Phaser 工程作迭代靶子（三系统+耦合点、先天过 boot），数据表 schema 留空给 LLM 填，配共用资产占位图。产物以 `Workspace.workdir` 本地多文件工程形态承载。 +- **Requirements**：R4, R21 +- **Dependencies**：无（可与 U2/U3 并行） +- **Files**： + - `tier2/fixtures/mini-foie-gras/`（新建 Phaser 经营骨架工程：合成系统 3×3 棋盘 / 资源系统 {coins,ingredients} / 订单系统；耦合点=合成产出进库存、订单读库存、金币门控解锁；参照 `game-runtime/games/wanglanmei-ref/src/game-shop.js` 的系统结构，Phaser 重写非代码复用） + - `tier2/fixtures/mini-foie-gras/data/`（数据表 schema：12 物品 / 6 合成链 / 5 订单 / 2 货币，留空给 LLM 填值） + - `tier2/fixtures/_assets/`（共用资产池占位图） +- **Approach**：按《tier2 实现详设》mini-肥鹅 fixture 规格 mini 化复刻——砍任务弹窗/背包深度/上百物品，留三个联动系统 + 胜负（赢=金币 20→100，输=连续 3 订单流失）。是 Phaser 版（不是 LittleJS 的 wanglanmei-ref 代码复用，只参照系统/耦合结构）。spike 产物不走正式源项目契约/落库——harness 直接在 workdir 构建+真跑。 +- **Patterns to follow**：`game-runtime/games/wanglanmei-ref/`（src/game-shop.js@729 经营骨架、entry.js@42 引擎动态 import Option C 范式）、《tier2 实现详设》mini-肥鹅 fixture 规格 +- **Test scenarios**： + - 骨架先天过 boot：mini-肥鹅 工程构建 + 真跑过 U3 的 L1 boot/frame 门（无 LLM 填值也能起）。 + - 跨表耦合可达：合成产出的物品能满足某订单的 requires（跨表可达性，经营专属硬门的前提）。 + - 胜负双路径：harness driver 能把骨架驱动到赢（金币达 100）和输（连续 3 流失）双终态。 +- **Verification**：mini-肥鹅 骨架构建成功、过 boot 门；赢输双路径可被 driver 驱动到 latch 终态。 + +### U5. mmx 资产管线接成 agent 可调工具 + +- **Goal**：把 mmx-cli 接成单写 agent 可调的资产生成工具（进 Toolkit、有 tool schema），产美术/音乐，用量计入成本台账。 +- **Requirements**：R5 +- **Dependencies**：U1 +- **Files**： + - `tier2/gen-worker/worker/tools/mmx_asset_tool.py`（新建：包装 mmx-cli 为 AgentScope `Tool` 工具函数，参数 schema = 资产类型/描述/规格；产物落 `Workspace.workdir` 资产目录） +- **Approach**：最简形态——mmx 作 agent 同一 ReAct 回路里可调的资产工具（符合"一台游戏工作站"范式），而非旁路并行管线。用量 quota 计入 `cost_reuse` 台账。资产产物进 fixture 的 `_assets/` 同构目录。 +- **Patterns to follow**：memory `mmx-asset-pipeline`（mmx-cli 用法、quota 对账）、AgentScope 2.0.3 `Toolkit(tools=[...])` + `Tool` 工具函数（见 agentscope-skill v2-building-blocks） +- **Test scenarios**： + - mmx 工具被 agent 调用一次，产出资产文件落 workdir、且 quota 计入台账。 + - 工具失败（mmx 不可达/超时）返回结构化错误，agent 能据此降级（不崩循环）。 +- **Verification**：agent 经工具调用产出一个占位级资产；失败路径返回可恢复错误。 + +### U6. L1 门抽象重写 + 富游戏专属门 + +- **Goal**：把现九门抽象重写进 L1（引擎无关的确定性门），补 tier2 富游戏专属的跨表联动门、经济门、latch（胜利/弃守分流）的 `assertAfterPlay` 规格。 +- **Requirements**：R6, R9 +- **Dependencies**：U3 +- **Files**： + - `tier2/harness/gates/l1-engine-agnostic.js`（新建：能装载/不报错/帧 delta/像素回读/活动 hash/引擎调用前缀/输入改状态/控制跟手——从九门抽象重写、引擎无关） + - `tier2/harness/gates/business-sim-gates.js`（新建：跨表联动门（订单引物品可达·合成 DAG 无环）+ 经济门（可盈利可破产）+ latch 分胜利/弃守） +- **Approach**：现九门为 LittleJS 单文件壳而建、带病灶（latch 空壳蹭过）。抽象重写时三层职责绝不混——L1 确定性门拒发权全来自确定性信号、零 LLM 判定；富游戏专属门走 observe→enforce（默认只观测，达标率稳后才赋拒发权）。 +- **Patterns to follow**：`game-runtime/games/_wg1-gen/_shared/play.cdp.cjs`（九门组装 main@894、checkAssertion@189、latch 终态轮询@1040、readGameState@168 可测性红线）、《tier2 四层工程架构》§4.1 三层校验 +- **Test scenarios**： + - 联动门：订单 requires 无法被任何合成链产出的工程被判 fail（跨表可达性）；合成链成环被判 fail（DAG 无环）。 + - 经济门：开局即破产/永远攒不到目标金币的数值配置被判 fail（可盈利可破产）。 + - latch：只合成不交单的空转工程不蹭过 latch（弃守 ≠ 胜利）。 + - observe→enforce：新增门默认只 observe（记录不拒发），达标率阈值后才 enforce。 +- **Verification**：联动/经济/latch 门对正例 pass、对各退化反例 fail；observe/enforce 档位可配。 + +### U7. 生成迭代闭环 + 证据门（M3 + 三层校验 + 四熔断 + A/B 门 + 退路树） + +- **Goal**：把 U1-U6 汇成可跑的生成迭代闭环——M3 走 Anthropic 原生端点写代码、三层校验（初期只焊 L1）裁决、四熔断关着，并落 A 门（M3 证路软）/ B 门（便宜档 n≥30 硬）证据门与退路树触发线 + 采集字段。 +- **Requirements**：R7, R8, R9, R10, R11, R12 +- **Dependencies**：U2, U3, U4, U5, U6 +- **Files**： + - `tier2/gen-worker/worker/agent_loop/m3_model.py`（新建：`AnthropicChatModel`+`AnthropicCredential.base_url` 指 new-api `/v1/messages`+thinking；启动校验 `max_tokens > thinking_budget`；**含 `RecordingChatModel` 的 Anthropic 变体——subclass `AnthropicChatModel` 同样覆写 `__call__` 抓 `ChatUsage`**。⚠️ 现有 `RecordingChatModel(OpenAIChatModel)` 对 Anthropic 路不生效；不做这个变体，A 门 M3 路的 per-call usage 抓不到、成本证据链断、A 门与 B 门成本口径不可比） + - `tier2/gen-worker/worker/finish_spike.py`（新建：**spike-grade 最小产物收尾**。M3 开 thinking 时 `generate_structured_output` 的强制 `tool_choice` 被 Anthropic 拒——改用 `tool_choice=auto` 非强制 + 兜底重试，或一个最简 finish 工具把多文件 `src/` 吐到 `Workspace.workdir`，不走正式契约/落库（与 R21 一致）。Phase B U9 升正式 finish + 源项目契约） + - `tier2/gen-worker/worker/breakers.py`（新建：四熔断——步数硬顶/预算闸时间盒/卡死探测/双层超时；预算闸早期只时间盒上限） + - `tier2/gen-worker/worker/evidence/gates.py`（新建：A 门 M3 证路记录 + B 门 n≥30 统计，阈值引《tier2 实现详设》§过门判据，不复列） + - `tier2/gen-worker/worker/evidence/fields.py`（新建：采集字段表——run_id/model/stage/pass/repairs/fail_stage/fail_system/cost_rmb/wall_s/file_count/长程一致性，承《实现详设》） + - `tier2/gen-worker/worker/evidence/retreat.py`（新建：退路树数字触发线——v4-pro<40%/全线<20%/超 max_iters） +- **Approach**：闭环 = 组 context→M3 reason→Workspace act 写多文件 src/→**经 `finish_spike` 收尾吐产物到 workdir**→build→真跑→三层校验→repair/checkpoint→产出。初期只焊 L1，L2/L3 渐进，L3 永远软。**A 门是两段与，不是纯软门**：① M3 产物先确定性过 L1（机器判，别对崩溃页试玩）② 再创始人试玩判"有肥鹅味的可玩雏形"（软）——两段都过才算 A 门过。B 门硬（便宜档 deepseek-v4-flash/pro 各 n≥30，过门率/¥/收敛达《实现详设》阈值）才允许转 Phase B。**给"A 门后、B 门 n≥30 前"的前置物调参加显式上限**（≤K 轮或 ≤¥/≤墙钟，超即按退路树 KEEP/缓行处置），把"不再调参"从触发线之后前移一个兜底闸，杜绝未达触发线时无限调参。退路树达任一数字触发线即转退路、不再调参。**环境切分见 Risks——本计划"项目初始化"在 6c6g 搭骨架，"运行调优"（M3+mmx 真生成、n≥30 spike、CDP 真跑）转 Mac/mini-desktop。** +- **Execution note**：先 M3 smoke（thinking 分离/工具调用/quota 三证）再接迭代闭环；先 M3 证路（A 门）再用便宜档比成本（B 门 n≥30）。 +- **Patterns to follow**：`wg1/gen-worker/worker/agent_loop/studio.py`（迭代骨架）、`wg1/gen-worker/worker/cost.py`（per-model 折¥）、《tier2 实现详设》§模型矩阵/过门判据/采集字段/退路树 +- **Test scenarios**： + - M3 smoke：一次 M3 调用证 thinking 分离（拿到 ThinkingBlock）+ 工具调用 + quota 计费三者都通。 + - M3 路 per-call usage 捕获：`RecordingChatModel(AnthropicChatModel)` 跑一次 M3，断言 input/output/cache_input tokens 被抓到非空（成本证据链不断）。 + - **闭环首次端到端（独立验收门 · 最高风险点）**：M3 真调一次 → 写多文件 src/ → `finish_spike` 收尾 → build → Phaser harness 真跑 → 三层裁决 → 产出一行采集。这是闭环首次贯通的独立 gate，不被分散子测试掩盖。 + - 启动校验：`max_tokens <= thinking_budget` 配置在启动期被拒（不到运行期才撞）。 + - 四熔断：步数/时间盒/卡死/超时各造一个触发样例，闭环优雅收尾、每轮 checkpoint 存在。 + - 证据采集：一次迭代 run 产出采集字段表一行（pass/repairs/cost_rmb/fail_system 等齐全，**M3 路成本非空**）。 + - A 门两段与：M3 产物未过 L1 时 A 门判不过（不靠对崩溃页试玩）；过 L1 + 创始人试玩才过。 + - A/B 门逻辑 + 调参上限：mock 一批 run 的 pass 分布，B 门按《实现详设》阈值正确判 go / 退路；A→B 间调参超 K 轮上限即按退路树 KEEP/缓行（不无限调）。 +- **Verification**：M3 smoke 三证 + M3 路 usage 非空；闭环首次端到端独立门通过；四熔断各自可触发并优雅收尾；一次迭代产出完整采集字段；A/B 门 + 退路树 + 调参上限对 mock 分布给出正确判定。 + +--- + +### Phase B — 重机器（B 门通过后才投 · 纲要） + +> 以下三单元在 B 门硬证据通过后才进入细化与建设。此前不投，避免在未验证的机器上过度排细节。细度为纲要级——建设前据 origin + 当时实测再细化。 + +### U8. 工作室阶段 1 + Agent Service + +- **Goal**：上官方 Agent Service（`create_app`）+ Agent Team 星形（阶段 1 工作室多 agent 设计），恢复生产态两阶段。 +- **Requirements**：R13, R1（解禁 service） +- **Dependencies**：U7（B 门通过） +- **Files（纲要）**：`tier2/service/`（`create_app` + storage/message_bus/workspace_manager）、`tier2/gen-worker/worker/agent_loop/studio_roles.py`（阶段 1 设计 worker 角色） +- **Approach（纲要）**：用官方 `create_app(storage, message_bus, workspace_manager)`（REST+SSE+durable session，Redis 后端）；阶段 1 工作室 = Agent Team 星形，只读设计 worker 经 `create_app(sub_agent_templates=[SubAgentTemplate(permission_context=PermissionMode.EXPLORE)])` 注册、leader `AgentCreate` 按 `subagent_type` 拉起——AgentScope 原生机制（见 agentscope-skill v2-deploy）。 +- **Test scenarios（纲要）**：阶段 1 leader 经 AgentCreate 拉起只读 worker、worker 不能写文件（EXPLORE 生效）；阶段 1→2 收敛到单写；Agent Service `POST /sessions`+SSE 断线 replay。 +- **Verification**：阶段 1 多 agent 设计跑通且只读、阶段 2 单写、SSE 可恢复。 + +### U9. 第二装载分支 + tier2 源项目契约七要素 + +- **Goal**：立 tier2 自己的源项目契约（七要素）与 feed 第二装载分支，与 Tier0/1 ECS-lite 装载路解耦并存。 +- **Requirements**：R14 +- **Dependencies**：U7（B 门通过） +- **Files（纲要）**：`contracts/agent-loop/tier2-source-project.schema.json`（新建独立 schema，绝不扩 `source-project.schema.json`）、`game-runtime/src/host/boot-phaser-host.js`（新建第二装载分支，参照 `boot-game-host.js` 的 opts.engine 注入边界但 Phaser boot 序列） +- **Approach（纲要）**：七要素=类型标记/文件树 manifest/入口/构建 profile/依赖锁/内容哈希/落库寻址；finish 工具的参数 schema 与该契约共用一份定义（防漂移）。绝不碰 Tier0/1 装载契约与 `build-from-source.mjs` 的 `new Function` 路。 +- **Test scenarios（纲要）**：tier2 Phaser 工程经第二分支落库→取回→feed 真跑；Tier0/1 装载路不受影响（回归）；finish 工具产物形状 = 契约认的形状。 +- **Verification**：tier2 产物 feed 真跑通；Tier0/1 装载零回归。 + +### U10. 平台化：配置外置 + 控制面接入 + ReMe + +- **Goal**：完整配置外置（引线A 阶段 2-3）、控制面接入（D12/统一 trace 契约）、长期记忆 ReMe，让 tier2 被配置/观测/审计/限流地管起来。 +- **Requirements**：R15, R16, R17 +- **Dependencies**：U8, U9（B 门通过） +- **Files（纲要）**：认领引用《生成主线架构演进路线》阶段 2-3（不另立分期）；`contracts/trace/`（additive 立位，公共核心子集+扩展段）；tier2 接 D12 运行治理门入口 +- **Approach（纲要）**：配置外置归线A、本档只引用；trace 走官方 `TracingMiddleware`→OTel→Studio + adapter 映射统一契约；D12 现仅覆盖 SAA，tier2 入口/预算扣减/并发释放/失败补偿需补；ReMe vs 树内 mem0 起步前小验证 + 创始人定；强制 fail-closed 预算闸自建 Middleware（订阅 `ModelCallEndEvent`）。 +- **Test scenarios（纲要）**：配置改 prompt/模型不发版生效；轨迹按统一契约公共核心子集可查；D12 对 tier2 入口限流/降级生效；fail-closed 预算闸越硬上限即终止本次生成。 +- **Verification**：配置热改生效、轨迹可反查、预算闸硬熔断。 + +--- + +## Scope Boundaries + +**早期不做（B 门硬证据通过后才投）** + +- 工作室 Agent Team（阶段 1）、官方 Agent Service 服务化、第二装载分支与完整源项目契约、完整配置外置、控制面/管理面 UI、引擎能力包接口抽象、ReMe 长期记忆、强制 fail-closed 预算闸——全排在 B 门后（即 Phase B）。 + +**本计划不做（属主在别处或别线/别会话）** + +- 不重排 0 号 spike 可跑 runbook（归《tier2 实现详设》）与控制面治理细节（归《agentic 集成架构》）——只引用、只落执行序列。 +- 不碰 gamedef 废除（另一会话）；不碰 SAA 廉价线运行态（运行期零耦合，forbidden-import 守门）。 +- 不做 Cocos / Tier3 / 3D / 渠道导出（正交轴、Phaser 证成后）。 +- 不拍实测类阈值（¥3/款、过门率、ReMe vs mem0），迭代中校准。 + +**Deferred to Follow-Up Work** + +- 《tier2 四层工程架构》§11 六条跨档 TODO（studio.py "演进 vs fork" 措辞统一、trace 契约立位时机、SAA 线 player 软门是否与 tier2 同步收紧等）作 doc-sync follow-up。 + +--- + +## Risks & Dependencies + +- **最大风险（全线 go/no-go 所系）**：便宜/中等模型自治写 56% 表现层能否稳定达 B 门阈值——零证据，正是 U7 迭代要验的赌注。务必与"2026-06-18 已证便宜模型产 Tier0/1 声明式数据壳过门"硬区分：后者已证、是另一档（gameDefinition 数据壳）；tier2 的 Phaser 富游戏自治零证据，历史 Fable+Phaser 只证形态。 +- **前置阻断（U3）**：Phaser 浏览器探针路径可行性（agentscope-runtime BrowserSandbox 够不够，不够回落自建薄沙箱）须在 U7 迭代开跑前出结论，否则 spike 跑不起来。 +- **运行环境切分（逐单元 · 6c6g 搭骨架 / Mac·mini-desktop 跑调优）**：6c6g 禁 chrome（exit 144）、本机零依赖，凡需真跑 chrome/headless+esbuild 的验证必在 mini-desktop。逐单元归属——**6c6g 可完成**：U1（pip install / 纯函数复用单测 / forbidden-import CI）、U2（mock 模型集成测试 / 版本钉 / 消息形态复验）、U4 与 U5 的骨架与 schema 文件创建。**必须 mini-desktop 真跑**：U3（`page.evaluate`/CDP 探针矩阵真验）、U4（mini-肥鹅 构建+真跑过 boot 门）、U6（门对过门页 pass/空壳页 fail 真验）、U7（M3 smoke / 四熔断真触发 / 闭环端到端 / n≥30）。即"项目初始化（骨架+mock 级）"在 6c6g 完成、"运行调优（真跑迭代）"转交 Mac。 +- **外部依赖**：new-api 网关（`baseUrl`+`NEWAPI_KEY`，凭据见 `docs/内网凭据与端点.md`，M3 走 Anthropic 端点）；mmx-cli（创始人已亲验）；已 clone 的 AgentScope 2.0.3 源码 `/root/oss/agentscope`。 +- **版本风险**：tier2 独立锁 2.0.3，不随廉价线（2.0.1）走；2.0 系列内部 API 仍在变（参照 agentscope-skill 的 v2 离线镜像 + 源码为权威，SKILL.md 正文示例是 1.x 勿照抄）。 + +--- + +## Open Questions + +**Resolve Before Planning（建设前要定）** + +- U3 沙箱底座可行性（BrowserSandbox vs 自建薄沙箱 + 复用 CDP）——属主标记的 spike 前置阻断项，U7 迭代开跑前必须出结论。 +- ReMe vs 树内 mem0 长期记忆后端选型——起步前小验证 + 创始人定（影响 U10）。 + +**Deferred to Implementation** + +- 过门率/成本阈值（¥3/款、50%/70%）最终校准值，及 B 门 n≥30 在 M3 证路后对各便宜档的具体分配。 +- CDP 探针对 Phaser 重写的具体接口（帧源/canvas 注入/活动 hash 取法）。 +- 第二装载分支与源项目契约的字段级细节、与 finish 工具 schema 的共用落点。 +- tier2 独立 service 错误码/契约归属（运行期零耦合 → 自有空间，细节随建设定）。 + +--- + +## Sources & Research + +- Origin：`docs/brainstorms/2026-06-22-tier2-整体实现方案-requirements.md`（R1-R21、已定决策、已过 Codex+Opus 双评审）。 +- 属主设计档：`docs/architecture/架构/生成引擎/` 下《tier2 四层工程架构》（§9 spike-grade 7 前置物、§11 T4 forbidden-import）、《tier2 实现详设》（0 号 spike runbook/模型矩阵/过门判据/采集字段/退路树/源项目契约七要素）、《自治富游戏引擎》（O2/引擎选型/三层校验）、《agentic 集成架构》（控制面/D12/trace）、《agentic 运行时架构图说》。 +- 子代理研究（本计划）：repo 文件级定位（种子 `studio.py` run_studio@230 / `ReActConfig(max_iters=1)`@158 / repair@266 / 五接线点；`_client.py`/`cost.py` 复用边界；`play.cdp.cjs`@1131 探针；Tier0/1 装载契约边界；`wanglanmei-ref` 12 文件经营样板）；AgentScope 2.0.1→2.0.3 迁移面取证（6 符号全兼容、迁移=版本钉+注释清理非 API 重写）。 +- 框架权威：`/root/oss/agentscope`（2.0.3 源码）；`.agents/knowledge/agentscope-2.0.3-facts.md`（速查）；agentscope-skill 的 `references/v2-building-blocks.md`/`v2-deploy.md`（v2 离线镜像，集成权威；SKILL.md 正文 1.x 勿照抄）。 +- 关键记忆：`saa-agentic-infra-decision`、`m3-agentic-anthropic-protocol`、`generation-lifecycle-project-model`、`true-structured-foundation-proven`（Tier0/1 数据壳已证、与 tier2 硬区分）、`mmx-asset-pipeline`、`tiered-engine-cocos-decision`。