diff --git a/docs/brainstorms/2026-06-17-mac-work-list-requirements.md b/docs/brainstorms/2026-06-17-mac-work-list-requirements.md new file mode 100644 index 00000000..3f6d68f6 --- /dev/null +++ b/docs/brainstorms/2026-06-17-mac-work-list-requirements.md @@ -0,0 +1,138 @@ +--- +date: 2026-06-17 +topic: mac-work-list +--- + +# Mac 工作清单(前端+引擎线 · Phase 1 主账) + +## Summary + +为「前端+引擎线」(本机 lili-mac)排定 Phase 1 工作账,锚定在**固定游戏架构 + SAA agentic studio**(契约 8/8 已冻,我线全部现在可开工)。我线的活 = 协调档 §7.2 的 **E1–E6 + 广度 8 页**:后端 SAA 图产 `gameDefinition`/`assetSpec`,我做**消费/适配/QA/创作 UI 侧**。最高价值首件 = **E1 2D 适配器(gameDefinition→LittleJS)**;关键路径 = 后端 B6 + 引擎 E1/E3/E4 合流出「一句话→生成→玩」M0 真闭环。 + +--- + +## Problem Frame + +2026-06-17 创始人按"要不要浏览器/视觉"切两开发线,本机由"便宜模型生成 L1"转为「前端+引擎线」。随后两次 pull 落地了**契约冻结门 8/8 ✅** + **SAA 固定架构图 16 节点**(B2),协调档 §7 刷新为"契约冻结后各线当前工作清单"。本账**重锚**到这一现状:早版按旧 W-G1 Python worker 主线 + 旧 §6 搭的骨架(R1–R8)已被 §7.2 的 E1–E6 取代——主线现是 SAA 图,worker 降为引擎线**复用**的组件(build.mjs 共调 / asset 角色 / few-shot 来源),不再是"转默认产线"。 + +--- + +## 已落地基线(re-baseline · 不再列为 TODO) + +- **引擎**:`game-runtime/src/plugins/` 8 业务插件(collision 含 swept CCD、physics-lite、particles-juice、gamefeel、palette-post、audio-music、save-progress、runtime-probe;`_example` 样例不计)。预判"4 短板"实测已突破。 +- **worker 九门 real-play**:scale **18/19 过九门(94.7%)**,仅 t2048 因 latch 挂(见 E4)。driver 覆盖**已补齐**:angrybirds drag-aiming(`runDragAiming`@play.cdp.cjs:368,commit `06e59de6`,pass)、multiball(commit `cc5fa486`,pass)、tap-targets 自产、brief-pin 数值自产化均已落地。首局体验门(组 C,additive 非阻断)已落地、本机 M1 跑通(breakout 全过)。 +- **worker 派发壳**:`service.py` 已含 `/generate` + HMAC-SHA256 `X-Callback-Signature` + 回调内部路(commit `d59093f8`),供 SAA/worker 两路复用。 +- **前端**:8 个 studio 页已落地(Feed/Play/Create/Message/Profile/Project/Biz/Dashboard,共 10 个 views 目录含 login/share)+ 设计体系(`tokens.css`/vue-i18n zh+en/组件库/Vant 深色主题)。**注**:这 8 个 ≠ demo 设定的"八大页";demo 八大页里**素材中心、玩法模板中心两页仍缺**(见广度)。 +- **联合 spike**:缓存透传 ✅ 绿(76–93% 命中)、classify 准确率 ✅ 绿(M3 archetype 93%/$0.003)。 + +--- + +## Key Decisions + +- **重锚到 §7.2 E1–E6**:用协调档/执行档的权威 E-ID 体系,本账作其详账,避免与 §7.2 漂移。 +- **契约 8/8 已冻 → 我线全部可开工**:E1–E6 不再"卡契约";依赖 B 步只是跨线协调(各对 mock 建半边),非阻塞。 +- **worker = 复用组件,非主线**:固定架构主线是 SAA 图;worker 提供 build.mjs 共调 / asset 角色 / few-shot 来源 / cost 折算。 +- **插件库不预补门面**:18/19 在无预补下达成(限**当前语料**;若后续 grid/HUD 密集体裁批量重写同逻辑则复评)。 +- **权威 e2e 在 mini-desktop,本机 = 快走查**。 +- **创始人 2026-06-17 裁定**:game-admin 前端归本线(入广度,≈M3)· 六类资产 = P-CRT-02 六类(定 E3 assetSpec)。 + +```mermaid +flowchart TB + subgraph FE["前端+引擎线 (本机 lili-mac)"] + e6["E6 创作/修改/预览 UI"] + e1["E1 2D 适配器 gameDefinition→LittleJS"] + e3["E3 asset 产消 (六类资产)"] + e4["E4 九门 QA + narrative reviewer"] + e5["E5 Prompt Registry few-shot 冻结"] + end + subgraph BE["后端线 (6c6g / mini-desktop)"] + b6["B6 studio 编排 /studio/create,modify"] + g["SAA 固定架构图 (16 节点)"] + cb["handleCallback 建版本→组包→入 feed (唯一写入路径)"] + end + e6 -->|"/studio/create (frozen yaml)"| b6 + b6 --> g + g -->|"gameDefinition"| e1 + g -->|"assetSpec"| e3 + e1 --> e4 + e4 -->|"engineBundle / 过九门"| cb +``` + +--- + +## Requirements + +> 采协调档/执行档权威 **E-ID**(E1–E6);广度页用列表。状态:✅已落地 / 🔄部分 / ⏳开口。每项附验收(对齐执行档 §10.2)。 + +**Tier 0(生成引擎 · 关键路径 · 现在可开工)** + +| E | 工作项 | 文件 | 状态 | 验收(§10.2) | +|---|---|---|---|---| +| E1 | **2D 适配器(`SourceProject.gameDefinition`→LittleJS 可玩)= 最高价值首件**:实体→sprite、behavior→逻辑 | `game-runtime/src/`(新增 adapter 层) | ⏳ 开口·新 | 单测 实体→sprite/behavior→逻辑 + 九门真玩绿 | +| E2 | 唯一构建实现核对:SAA build 节点与 worker 共调 `scripts/build.mjs`(**不动**) | `game-runtime/scripts/build.mjs` | 🔄 共调已有,补核对 | 同源同参 `__GameBundle` 一致;同 `buildInputHash` 字节等价 | +| E3 | **asset 产消(六类资产 = 图元/角色/特效/场景/界面/音乐 · P-CRT-02)**:asset 节点 spec→`assets[]`→宿主消费 + provider=mmx-cli 插桩 | `game-runtime/` + worker asset 角色 | ⏳ 开口·新 | `assets[]` 非空 → GamePackage `assets[]` → 宿主非空 assetContext | +| E4 | 九门 QA harness 复用(**禁重写**)+ narrative 路质量门接 reviewer;**含 t2048 latch(唯一剩门)** | `_shared/*`(不动)+ reviewer 角色 | 🔄 18/19,t2048 开口 | 九门真玩绿(mini-desktop 4320/9222) | +| E5 | Prompt Registry 冻结 few-shot(byte 稳)+ CI 卡 byte(现 `_few_shot()` 读文件=字节不稳) | `contracts/prompts/`、`prompt.py` | ⏳ 开口·新 | CI:few-shot byte 不变 | +| E6 | 前端创作(接 `/studio/create`)/ 修改(接 `/studio/modify`)/ 预览 UI(对 **frozen** studio.yaml + mock) | `game-studio/src/` | 🔄 Create 已存,补真接+进度 | 真机 UI 走查(mini-desktop CDP)create/modify/预览闭环 | + +- **E4 子项(t2048)**:抗死锁盲态体裁——放宽 H 门 latch 为"score↑ ∧ board 变 + G 兜",或升级"填库死锁"driver;立为体裁规则补档。实现期按数据二选一。 +- **E6 子项(进度反馈)**:补 UI 形态(成功/失败/进行中落点),与 SSE/轮询传输选择**分离**(后者视后端定)。 + +**广度(Tier 1+ · 账本级 · 价值×独立性)** + +- 创作页完善 · feed · 钱包 · 消息社交 · 账号(均已有骨架,补真接/完善) +- **玩法模板中心页(新页,低)**:浏览/选择/应用模板到草稿;先对 mock,真接等后端模板 API,毕业门绑 **M1** +- **素材中心页(新页,低)**:素材浏览/选用加入草稿;先对 mock,真接等后端素材 API,毕业门绑 **M3** +- 设计体系 HJ-FE-DS-001(P1–P5 大半已落地) +- **game-admin 运营台前端(创始人 2026-06-17 裁定归本线)**:限曝光/导出/经营看板 + 赋余额/订阅入口;`game-admin` repo(huijing-ui-admin-vue3 fork);低优先 ≈ M3 +- 新页验收(mock 阶段最小状态):加载中 / 空列表 / 选中→应用 交互路径可走查 + +--- + +## Success Criteria(= 执行档 §10.2 引擎+前端线验收门) + +1. **E1**:`gameDefinition` 渲成可玩(实体→sprite、behavior→逻辑)单测绿。 +2. **E4**:九门真玩绿(mini-desktop),cheap 在固定架构填出过九门游戏 `verdict.pass=true`;scale 维持 ≥18/19,t2048(唯一剩门)解决后 19/19。**注**:19/19 经放宽 latch 门达成(体裁固有边界,非生成能力增益);语料 19 款(simon×3 变体)无第 20,scale-20 目标另需生成第 20 款。 +3. **E3**:`sourceProject.assets[]` 非空 → GamePackage `assets[]` → 宿主加载(非空 assetContext)。 +4. **E2**:同 `buildInputHash` → 字节等价 bundle(从源可复现)。 +5. **E6**:create/modify/预览闭环真机 UI 走查过(编排器旁路会掩盖 UI 缺陷,真 UI 走查是唯一手段)。 +6. **M0 失败门**:E1/E4 任一门挂或 GamePackage manifest 不符 schema → M0 不清、阻 M1 在其上开工。 + +--- + +## Scope Boundaries + +- **不做(后端线 / 6c6g)**:SAA 图(B2)、studio 编排 B6、源落库/构建落包、`handleCallback` **入 feed**(唯一写入路径在后端)、全部 game-cloud 后端、契约/Flyway/prompt 后端段。**我线只产出过九门的 engineBundle/GamePackage,"入 feed" 是跨线集成点**。 +- **不做(本 Phase 外 → P2/P3)**:3D 适配器/Cocos(P2)、云部署/监控运维(P2)、真支付/短信/广告/渠道(P3)、全维优化。 + +--- + +## Dependencies / Assumptions + +- **契约 8/8 已冻**(源项目 schema+V18 DB · SAA ALL_KEYS · trace 扩展键 · studio.yaml 生命周期 API · GamePackage/构建 API)→ 两线可独立开工,各对 mock 建半边。 +- **M0 集成 = 后端 B6 + 引擎 E1/E3/E4 合流**(跨线协调点,非阻塞)。 +- **硬约束(回归红线)**:九门 harness 禁重写;`build.mjs` 唯一构建脚本不动;GamePackage 产物面既冻;modify 不动 currentVersion、不自动入 feed;new-api 缓存命中只落成本台账、不接收益结算。 +- **接缝**:`cost.py`(B9 缓存命中字段)、few-shot(E5 来源 `prompt.py`)为 worker/SAA 两路共用,改动须双路兼容。 +- 权威 e2e 机 = mini-desktop(Linux);本机 M1 = 快走查自检。 +- 安全:NEWAPI_KEY 仅在 `wg1/gen-worker/.env`(gitignore),不入提交;生成 + 九门在本机跑。 + +--- + +## Outstanding Questions + +> 原两项 Resolve-Before-Planning 已由创始人 2026-06-17 裁定:**game-admin 前端归本线**(入广度)· **六类资产 = P-CRT-02 六类**(写入 E3)。 + +**Deferred to Planning** + +- E4/t2048:走"放宽 latch 门"还是"填库死锁 driver"——实现期按数据定。 +- E6 进度反馈:SSE 节点流(SAA 强项)还是前端轮询——视 B6 契约定。 +- 最简模板首件:M0 端到端先打通哪一档 archetype(8 档:clicker/dodge/match/runner/idle/merge/tycoon/generic;倾向 clicker/dodge 最简)。 + +--- + +## Sources / Research + +- 协调档:`docs/agent-specs/2026-06-17-多session分工与任务总账.md`(§7.2 我线当前清单 E1–E6、契约 8/8 冻结进度)。 +- 执行档:`docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md`(§7.2 E 步定义、§10.2 验收门、§4.1 数据流、§3.2/3.3 文件路径、§5.5 asset 契约)。 +- 现状盘点(file:line 实证):`game-runtime/src/all-plugins.js`(8 业务插件)、`game-runtime/games/_wg1-gen/_shared/play.cdp.cjs:368`(runDragAiming)、`{angrybirds,multiball}/evidence/verdict.json`(pass)、`t2048/evidence/verdict.json`(pass=false)、`wg1/gen-worker/worker/service.py`(/generate+HMAC)、`game-studio/src/views/`(10 目录)、`game-studio/src/host/`(宿主装载契约)。 +- 提交锚:`06e59de6`(angrybirds drag-aiming)、`cc5fa486`(multiball)、`d59093f8`(worker 派发壳+HMAC)。 diff --git a/docs/plans/2026-06-17-002-feat-mac-engine-frontend-tier0-plan.md b/docs/plans/2026-06-17-002-feat-mac-engine-frontend-tier0-plan.md new file mode 100644 index 00000000..2f19df62 --- /dev/null +++ b/docs/plans/2026-06-17-002-feat-mac-engine-frontend-tier0-plan.md @@ -0,0 +1,312 @@ +--- +title: "feat: Mac 前端+引擎线 P1 — E1–E6（固定架构消费/适配/QA/前端侧）" +status: active +date: 2026-06-17 +type: feat +origin: docs/brainstorms/2026-06-17-mac-work-list-requirements.md +--- + +# feat: Mac 前端+引擎线 P1 — E1–E6（固定架构消费/适配/QA/前端侧） + +## 摘要 + +把固定游戏架构的**引擎线消费侧**从"契约冻结"推进到"端到端可生产":后端 SAA 图产 `SourceProject.gameDefinition` + `assetSpec`,本线建 **E1 2D 适配器(gameDefinition→LittleJS 可玩)→ E2 从 sourceProject 真构建(build.mjs)→ E4 九门 QA → E3 asset 产消 → E5 Prompt Registry 冻结 → E6 前端创作/修改/预览 UI**。关键路径 = **E1+E2(从源真构建)**——它是后端确定性 modify 路 guard-pending 的硬依赖(后端 001 计划 U6 在等本线落)。范围 = 引擎+前端线 Tier 0(E1–E6)+ 两新页广度;`game-admin` 前端、既有页打磨 = Deferred Follow-Up。 + +> origin:[`docs/brainstorms/2026-06-17-mac-work-list-requirements.md`](../brainstorms/2026-06-17-mac-work-list-requirements.md)。设计权威:[`docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md`](../agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md) §5/§7.2/§10.2。跨线对侧:[`docs/plans/2026-06-17-001-feat-backend-tier0-gen-mainline-plan.md`](2026-06-17-001-feat-backend-tier0-gen-mainline-plan.md)(后端线 B 步)。 + +--- + +## 问题背景 + +契约 8/8 已冻、B2 SAA 拓扑 16 节点已合入,但**引擎线消费侧是真空白**:`game-runtime/src/` 下无任何 `gameDefinition` 消费者(末次 grep 零命中);唯一"定义→渲染"先例是 W-G1 的 LLM 直写 `generated-factory.js`(非 JSON 定义→适配器)。后端 001 计划明确把"从 sourceProject 真构建"划归本线 E2,其确定性 modify 路**维持 guard fail-loud、等本线落**(后端 KTD5/U6,创始人 2026-06-17 确认)。同时 `/studio` 前端 api 真空(`game-studio/src/api/` 无 `studio.ts`),`Create.vue` 仍接旧两步 `aigc.generate` 路。地基稳:宿主装载链(`inject.ts` engineBundle 分支)、九门 harness、`build.mjs`、GamePackage 产物面全已冻、可复用零改。 + +--- + +## 需求追溯(origin → 本计划单元) + +| origin(brainstorm E-ID / §10.2 门) | 单元 | +|---|---| +| E1 2D 适配器(gameDefinition→LittleJS) | U1 | +| E2 build.mjs 共调核对 + 从源真构建 | U2 | +| E4 九门 QA harness 复用 + narrative reviewer | U3 | +| E3 asset 产消(六类资产) | U4 | +| E5 Prompt Registry few-shot 冻结 | U5 | +| E6 前端创作/修改/预览 UI | U6 | +| 广度:玩法模板中心页 + 素材中心页(新页) | U7 | + +成功标准(origin §10.2):2D 适配器单测绿 · 九门真玩绿(mini-desktop)· asset 产消通 · 构建字节确定性 · 前端真机 UI 走查过。 + +--- + +## 关键技术决策(KTD) + +1. **E1 适配器 = 声明式解释器,逻辑代码由 code agent 产、编进 bundle**(跨线已锁,后端 001 KTD5/U6 确认):适配器读 `gameDefinition` 的 entities/components/scenes/rules/config 做渲染+场景装配+胜负判定;`behaviors` 的真逻辑由核心 code agent 产出、经 `build.mjs` 编进 `__GameBundle`(非适配器解释)。适配器输出物须命中 `GameHostFactory`→`GameInstance` 契约(`game-runtime/src/core/game-host.d.ts`),骨架范本 = `_goldenpath-probe/factory.js`。**E1 对冻结契约 `source-project.schema.json` 编程(contract-first)、用 schema 合规 fixtures/golden 自测,不阻塞于 producer 是否已建**(创始人 2026-06-17:gameDefinition 是冻结 keystone 契约、换适配器即换引擎)。方向已锁,但**逻辑码入 entry-bundle 的接缝形态未定**——提为 U1 硬前置:先用单 behavior gameDefinition 手工走通"适配器产骨架 + 逻辑码拼入 → entry-bundle → build → 九门"最小贯穿验形态,再展开 U1 其余。 +2. **E1+E2 = "从 sourceProject 真构建"管线 = 净新建 + 后端硬依赖**:当前两路(worker/SAA)都直写 factorySrc(整工厂)、不消费 sourceProject;"源 → 适配器 → `generated-factory.js` 文件 → entry-bundle"装配链 与 `buildInputHash/sourceHash`(仅 V18 SQL 有列)**两端皆未建 = 净新建**(非"核对 build.mjs 已统一"——那仅旧 factorySrc 路)。`build.mjs` 本身不动。E1/E2 落地解后端确定性 modify guard;**SAA 改产填充版 gameDefinition(而非 factorySrc)= 跨线集成项**(后端 off-factorySrc,与本线在冻结契约处交汇)。 +3. **受控面墙(回归红线)**:生成/适配代码只许调插件公开面 + **6 受控面**(getContext2d/onFrame/getInput/getAudioContext/time/random);静态门禁 9 类 token(`import`/`littlejsengine`/`Math.random`/`Date.now`/`addEventListener`/`requestAnimationFrame`/`new AudioContext`/`document.`/`window.`);引擎 import 只活集成段 host,能力经 `boot.ctx.getEngine()`。**注**:GameInstance 的渲染面 = `boot.mainContext`(render(g) 入参),`getContext2d` 是**插件面**(game-host.d.ts:20-22);6 受控面管的是插件/能力访问,非游戏自身渲染目标。 +4. **九门 harness 禁重写**:E4 复用 `_shared/{serve-and-play.sh,play.cdp.cjs,…}` 子进程不改;新品类只产 play-spec(driver 选型)+ 接 narrative reviewer 质量门。真承重件 = `expectLatch` + `G_input`(非 progress 计数);首局门 additive 不并入 `verdict.pass`;**串行单实例、禁并发 CDP target**。 +5. **few-shot 字节稳 = 两处生成入口逐字同源**:`wg1/gen-worker/worker/prompt.py` 与后端 `SaaPrompts.java` 的 system+few-shot **逐字同源、grep 比对**(公平性铁律,`a2cbabe6` 先例);冻结走 `contracts/prompts/` 升 version + 四道闸 CI,P0/P1 口径一字不动。 +6. **E6 对 frozen `studio.yaml` + mock 先做**:`/studio/{create,modify}` 后端在建(001 U1),本线先建 `studio.ts` api + 改造 Create.vue + 新建 modify 入口,对 mock;预览**复用 GamePlayer 零新建**。 +7. **worker 跑通 ≠ 准予发布**(split-brain 防线):九门绿=机制可玩,发布裁决归治理层(P0 安全/金丝雀/人审),本线不置 `published`。 +8. **输入坐标 = 逻辑像素**:`x∈[0,390]/y∈[0,844]`(非归一),视口固定 390×844 不自处理 DPR。 +9. **LittleJS 真接线硬门**(build-vs-buy):E1/E2 收口须 grep `bundle.iife.js` / `.meta.json` 证 LittleJS 真入包("产物里没有 X = 验收 fail")。 + +--- + +## 高层技术设计(HTD) + +### 本线在全链中的落点(从源真构建 → 宿主 → 九门) + +```mermaid +flowchart TB + subgraph BE["后端线 (6c6g · 001 计划)"] + G["SAA 固定架构图"] -->|"emit sourceProject (gameDefinition+assets[])"| SRC[("game_source_project")] + LOGIC["code agent 产 behavior 逻辑码"] + end + subgraph ME["前端+引擎线 (本线 · 本计划)"] + E1["U1 E1 2D 适配器
gameDefinition → factory(entry-bundle)"] + E2["U2 E2 build.mjs
entry-bundle → __GameBundle(iife)"] + E4["U3 E4 九门 QA
play.cdp.cjs(禁重写)"] + E3["U4 E3 asset 产消
assets[] → 宿主"] + E6["U6 E6 创作/修改/预览 UI"] + end + SRC --> E1 + LOGIC --> E2 + E1 -->|"entry-bundle.js"| E2 + E2 -->|"engineBundle(__GameBundle.bootGameHost)"| CB["handleCallback (后端唯一写入路径)"] + CB --> PKG[("GamePackage 产物")] + PKG -->|"inject.ts engineBundle 分支(零改)"| E4 + E3 -.->|"sourceProject.assets[].url"| PKG + E6 -->|"/studio/create,modify (mock→真)"| BE +``` + +### 依赖与排序(U1–U7) + +```mermaid +flowchart LR + U1["U1 E1 适配器
(最高价值·真空白)"] --> U2["U2 E2 从源构建
(解后端 guard)"] + U2 --> U3["U3 E4 九门 QA"] + U1 --> U4["U4 E3 asset 产消"] + U5["U5 E5 Prompt 冻结
(较独立)"] + U3 --> U6["U6 E6 创作 UI"] + U6 --> U7["U7 两新页"] +``` + +> 关键路径 = U1→U2→U3(从源真构建 + 九门验,M0 核心纵切的引擎半边,且解后端 modify guard)。U4/U5 较独立可并行。U6/U7 接 frozen studio.yaml + mock 起,真接等后端 001 U1。 + +--- + +## 实现单元 + +> 顺序按依赖与跨线解阻塞:U1(E1 适配器)→ U2(E2 从源构建,解后端 guard)→ U3(E4 九门验)= M0 引擎半边;U4(E3 asset)/U5(E5 prompt)较独立;U6(E6 前端)→ U7(新页)。测试/权威 e2e:mini-desktop(4320/9222 串行);本机 M1 = 快走查。 + +### U1. E1 — 2D 适配器(gameDefinition → LittleJS 可玩) + +**Goal**:在 `SourceProject.gameDefinition` 与 `GameHostFactory`→`GameInstance` 契约间架适配器:entities→sprite、components(render/collision/physics)→渲染/碰撞装配、scenes→实体组装、rules(condition→win/lose/score/advance)→胜负判定、config→平衡参数;按 `profile.tickModel`(realtime/turn-based/event)决定是否挂 update 循环。 +**Requirements**:E1(origin);§10.2-1。 +**Dependencies**:无(消费已冻 `source-project.schema.json`;骨架范本就位)。 +**Files**: +- `game-runtime/src/adapter/`(新增 adapter 层:gameDefinition→GameInstance) +- 参照(不改):`game-runtime/src/core/game-host.d.ts`(`GameHostFactory`/`GameInstance` 契约)、`game-runtime/games/_wg1-gen/_goldenpath-probe/factory.js`(合契约工厂骨架)、`game-runtime/src/host/generic-host-config.js`(7 插件标准集装配) +- 测试:`game-runtime/src/adapter/adapter.test.mjs` +**Approach**: +- 适配器是**纯声明式解释器**:读 entities/components/scenes/rules/config 装配 GameInstance(init 建实体+订阅输入、update 按 tickModel 推进、render 画到入参 `g`、`_forensicsView` 导出 `phase`+状态)。`behaviors` 真逻辑码不在适配器内(KTD1:由 code agent 产、E2 编进 bundle)——适配器为其留挂载点。 +- 能力一律经 `boot.ctx.getEngine()` + 6 受控面;零引擎 import(KTD3)。 +- `transform.position{x,y,z?}` 2D 用 xy/z=0 同字段无分叉;逻辑像素 390×844(KTD8)。 +- MVP 最小集(执行档 §5.1):profile 三维 + 单 behavior + config + assets 引用渲染;复杂结构随品类迭代。 +**Patterns to follow**:`_goldenpath-probe/factory.js`(init/update/render/`_forensicsView` 形状)、`generic-host-config.js`(`buildGenericHostConfig`)。 +**Test scenarios**: +- happy:含 2 实体 + render 组件 + 1 rule(score)的 gameDefinition → GameInstance,init 后实体可见、update 推进、render 画出有色像素。 +- happy:`tickModel=turn-based` → 不挂 rAF-style update 循环(事件驱动);`realtime` → 挂。 +- edge:空 components / 无 behaviors → 适配器产可玩骨架(几何兜底,不崩)。 +- edge:rule outcome=win 条件达成 → `_forensicsView().phase` 转 gameover 并驻留(latch 语义)。 +- error:gameDefinition 缺 required(entities/scenes/rules)→ 明确报错,不静默产空壳。 +- integration:适配器输出经 host 装配 → `_forensicsView()` 透出 `phase`/状态(供九门 H 门读)。 +**Verification**:adapter 单测绿;产物喂 host 能装配出 `_forensicsView` 可读的 GameInstance;**硬验:最小集(单 behavior + spec-only asset)产出件须独立过九门 H 门 latch(phase→gameover 驻留),非仅"可装配 _forensicsView"**;若单 behavior 不足驱 latch,上修最小集到"能产胜负推进的最小 behavior 组合"(防 t2048 式 phase 卡 playing)。 + +### U2. E2 — 从 sourceProject 真构建(build.mjs)+ 同源核对 + +**Goal**:打通"sourceProject → 适配器装配 entry-bundle → `build.mjs` → `__GameBundle`(iife)"管线,使确定性"从源真构建"可达(解后端 001 U6 的 guard-pending);并核对 SAA build 节点与 worker 共调 `build.mjs` 产出一致。 +**Requirements**:E2(origin);§10.2-4;跨线解后端 modify guard。 +**Dependencies**:U1(适配器产 entry-bundle)。 +**Files**: +- `game-runtime/scripts/build.mjs`(**不动**;只调用) +- `game-runtime/src/adapter/`(装配 entry-bundle.js 的入口拼装,接 `entry-bundle.template.js`) +- 测试:`game-runtime/src/adapter/build-from-source.test.mjs` +**Approach**: +- 命令面:`node scripts/build.mjs /entry-bundle.js /bundle.iife.js --global-name=__GameBundle`(唯一入口,KTD2);`LOCKED_BUILD_OPTIONS` 不改。 +- 缓存键 `buildInputHash=sha256(sourceHash+buildProfile)`;同 hash → 字节等价 bundle(确定性门)。 +- **净新建主工作量**:适配器把存储的 sourceProject(`game_source_project` / state)落成 `generated-factory.js` 文件(= entry-bundle 的固定 import 目标)→ scaffold-等价写盘 → `build.mjs` 编;+ `buildInputHash/sourceHash` 规范化序列化 + sha256 + 缓存命中查/落(当前零实现)。'共调 build.mjs 已统一' **仅旧 factorySrc 路**;'同源核对'退为收口校验,非主工作量。 +- 收口 grep `bundle.iife.js`/`.meta.json` 证 LittleJS 真入包(KTD9)。 +**Patterns to follow**:`entry-bundle.template.js`(逐字拷为各 game 的 entry-bundle.js)、`build.mjs` metafile 产出。 +**Test scenarios**: +- happy:同一 sourceProject 构建两次 → 字节等价 bundle(buildInputHash 命中)。 +- happy:适配器装配的 entry-bundle 经 build.mjs → iife 暴露 `window.__GameBundle.bootGameHost`。 +- edge:sourceProject 变一处 config → buildInputHash 变 → 重新构建(不误命中旧缓存)。 +- error:本机无 esbuild → build.mjs 显式报错给指引(不静默产空)。 +- integration:worker 路与 SAA 路对同一源产 `__GameBundle` 字节一致(同源同参核对)。 +**Verification**:从源构建产可玩 iife;字节确定性单测绿;grep 证 LittleJS 真接线;后端 001 U6 的"确定性 build-from-source"依赖在本单元落地后可解 guard(交后端 follow-up 接)。 + +### U3. E4 — 九门 QA harness 复用 + narrative reviewer 接入 + +**Goal**:固定架构产出件经九门 harness 真玩验绿(**禁重写 harness**);为 narrative 路(`progressModel=narrative`)接 narrative-reviewer 质量门替九门;闭 t2048 唯一剩门。 +**Requirements**:E4(origin);§10.2-2;origin 成功标准 worker scale ≥18/19→19/19。 +**Dependencies**:U1、U2(有可玩产出才可真玩)。 +**Files**: +- `game-runtime/games/_wg1-gen/_shared/*`(**禁改**;子进程复用) +- 各 game 的 `play-spec.json`(driver 选型 + assertAfterPlay + expectLatch) +- t2048:`game-runtime/games/_wg1-gen/t2048/`(latch 放宽规则或填库死锁 driver,见 Open Questions) +- narrative reviewer 角色:`wg1/gen-worker/worker/agent_loop/`(reviewer 角色)+ 后端 narrative 路对接 +**Approach**: +- 复用 A–I 九门 + 首局门(additive 不并入 `verdict.pass`);新品类只产 play-spec(8 driver 类型自适应);真承重件 = `expectLatch`+`G_input`(KTD4)。 +- narrative 路:`progressModel=narrative` → 走 narrative-reviewer(执行档 §5.9),非九门 H 门。**注:narrative-reviewer 是净新建质量门(worker/_shared 现零代码),非 harness 复用**——判定逻辑/prompt/质量标准全新建,须验判定有效性(已知劣质叙事→needsRepair=true / 合格→false),非仅验路由分流。 +- t2048:抗死锁盲态体裁,latch 难达——放宽 H 门 latch 为"score↑∧board 变+G 兜"或升级填库死锁 driver,立体裁规则补档。 +**Execution note**:真玩 e2e 在 mini-desktop(4320/9222),与生成批跑**串行**(flock);串行单实例多趟 fresh navigate,禁并发 CDP target。 +**Patterns to follow**:`game-e2e-cdp-harness` skill(driver 类型/latch/首局门红线)、现 `asteroids/play-spec.json`。 +**Test scenarios**: +- happy:一款固定架构产出件 → 九门全过 `verdict.pass=true`(mini-desktop)。 +- happy:t2048 经放宽规则/driver → H 门 latch.pass=true(原 pass=false→true)。 +- edge:`progressModel=narrative` 游戏 → 走 narrative-reviewer 门、不卡九门 H 进展门。 +- edge:首局门 FAIL → 不阻断 `verdict.pass`(additive 派生维度)。 +- error:产出件装载失败 → A 门 fail,九门正确判 fail(不假绿)。 +- integration:scale 维持 ≥18/19;t2048 闭后 ≥19/19。 +**Verification**:九门真玩绿(mini-desktop);scale 不回退;narrative 路有独立质量门;harness 文件零改(git diff 证)。 + +### U4. E3 — asset 产消(六类资产 → 宿主) + +**Goal**:打通六类资产(`sprite/character/effect/scene/ui/music`)产消通道:asset 节点产 spec → `sourceProject.assets[]` → 构建解析为 GamePackage `assets[]` → 宿主经 `assets[].url` 加载。 +**Requirements**:E3(origin);§10.2-3;六类资产 = P-CRT-02(创始人 2026-06-17 确认)。 +**Dependencies**:U1(适配器消费 assets[].ref 渲染)。 +**Files**: +- `game-runtime/src/adapter/`(消费侧:assets[].ref→渲染) +- `wg1/gen-worker/worker/agent_loop/`(asset 角色:产六类 spec)+ provider=mmx-cli 插桩 +- 测试:`game-runtime/src/adapter/asset.test.mjs` +**Approach**: +- 消费侧:适配器读 `sourceProject.assets[].ref`,构建时解析为 GamePackage `assets[]`(image/audio…),宿主经 url 走 `/drawImage`(inject.ts CSP img-src 已放行)。 +- **MVP 边界**:asset 节点 v0 可只产 spec 不真生图(canvas 几何兜底),但 `assets[]` 产消通道**必须打通**(补 v2 review "assets[] 空"缺口);真资产 provider(mmx-cli)为 additive 升级。 +- **单步槽位调度、非六路并发**(studio.yaml:18 已狠切)。 +**Patterns to follow**:`mmx-asset-pipeline` memory(mmx-cli 默认、音乐记谱→合成两步)、`game-package.schema.json` assets 字段。 +**Test scenarios**: +- happy:含 2 类资产(sprite+music)的 sourceProject → GamePackage `assets[]` 非空 → 宿主 assetContext 非空。 +- happy:asset spec-only(无真图)→ 适配器 canvas 几何兜底渲染(不崩、九门 D 门有色像素)。 +- edge:`assets[]` 空 → 适配器全几何兜底(向后兼容现 prompt 硬规则 7)。 +- edge:六类枚举外的 category → 校验拒(严格枚举)。 +- integration:asset 节点产 spec → 落 sourceProject → 构建 → 宿主加载,端到端 assetContext 非空(九门 assets 门)。 +**Verification**:assets[] 产消端到端通(九门 asset 门);spec-only 兜底可玩;provider 可切不动消费侧。 + +### U5. E5 — Prompt Registry few-shot 冻结(字节稳 + CI 卡 byte) + +**Goal**:把 `prompt.py` 的 SYSTEM + few-shot 从"从文件读"(字节不稳、破前缀缓存)冻结为 `contracts/prompts/` 版本化资产,CI 卡 byte 不变;两处生成入口(Python/SAA)逐字同源。 +**Requirements**:E5(origin);CI few-shot byte 不变(执行档 §7.2 E5 / §5.8.1)。**注**:§10.2 五门(适配器/九门/asset/构建/UI)不含 E5,E5 验收 = CI 字节门。 +**Dependencies**:无(较独立,可并行 U1–U4)。 +**Files**: +- `wg1/gen-worker/worker/prompt.py`(`_few_shot()` 改读版本化常量,非文件) +- `contracts/prompts/`(冻结 system+few-shot 为 `id@version` 资产;现有 `registry.yaml` + `config.generic-coder` v0.0.1 STUB) +- 后端对侧核对:`SaaPrompts.java`(逐字同源 grep 比对) +- CI:`contracts/prompts/eval/`(byte 不变门) +**Approach**: +- 固化 `config.generic-coder` 的 system+few-shot 为版本化资产;few-shot 不再实时读 `_goldenpath-probe/factory.js`,改读已冻常量(字节确定)。 +- 改 prompt 走升 version + 四道闸 CI(Schema/成功率≥80%/Golden 回归/成本延迟),P0/P1 口径一字不动(KTD5)。 +- grep 比对 `prompt.py` 与 `SaaPrompts.java` 的规则段逐字同源。 +**Patterns to follow**:`prompt-governance` skill(第 8 类契约、id@version 加载、四道闸)、`a2cbabe6`(Python/SAA 逐字同改先例)。 +**Test scenarios**: +- happy:few-shot 从冻结资产读 → 多次构 messages 字节完全一致(CI byte 门)。 +- happy:`prompt.py` 与 `SaaPrompts.java` 规则段 grep diff = 空(逐字同源)。 +- edge:改 prompt 未升 version → CI 拒(version 门)。 +- error:P0/P1 口径被改 → CI 红线拒(一字不动门)。 +**Verification**:CI few-shot byte 不变门绿;两处入口逐字同源 grep 证;缓存命中率不因 few-shot 抖动下降(spike 已证 76–93%)。 + +### U6. E6 — 前端创作/修改/预览 UI(对 frozen studio.yaml + mock) + +**Goal**:新建 `studio.ts` api + 改造 `Create.vue` 接 `/studio/create`(一步式)+ 新建 modify 入口接 `/studio/modify` + 预览复用 GamePlayer;对 frozen studio.yaml + mock 先做,后端 001 U1 落后真接。 +**Requirements**:E6(origin);§10.2-5(真机 UI 走查)。 +**Dependencies**:U1–U3(有可玩产出才有意义);后端 001 U1(真接;之前对 mock)。 +**Files**: +- `game-studio/src/api/studio.ts`(新建,对齐 studio.yaml create/modify/extend) +- `game-studio/src/views/create/Create.vue`(改造:旧 `aigc.generate` 两步 → `/studio/create` 一步式) +- `game-studio/src/views/create/`(新建 modify 入口视图/组件) +- 预览:`game-studio/src/host/GamePlayer.vue`(**复用零新建**,喂 preview 版 versionId) +- 测试:`game-studio/src/views/create/Create.spec.ts` + 真机 CDP 走查脚本 +**Approach**: +- `studio.ts` 对 frozen studio.yaml 出 create/modify/extend 调用;Create.vue 改一步式(generic 桥接已落,缺省 templateId=generic)。 +- modify 入口:换美术/调参/改关卡=deterministic、改玩法=regenerate-module(modifyPatch 形态,执行档 §5.6);出新预览版不动 currentVersion。 +- 进度反馈:补 UI 形态(成功/失败/进行中落点),与 SSE/轮询传输选择分离(后者视后端定,Open Questions)。 +- 对 mock 先达"可走查骨架"(加载/空/选中→应用三态),后端 U1 真接后真数据走查。 +**Execution note**:收口前**必做真机 CDP 走查**(编排器/curl 全绿不算)+ **必另跑真实 IP/明文 http origin** 验上下文依赖(crypto.subtle 等);textarea 用原型 setter+dispatch input(Vue v-model),按钮精确文案匹配。 +**Patterns to follow**:`ui-walkthrough-cdp` skill(真机走查 7 坑 + 文案匹配 + token 注入只读走查)、现 `Create.vue` generic 桥接 + `aigc.ts`/`project.ts` api 形态。 +**Test scenarios**: +- happy:Create 一步式 → POST `/studio/create`(mock)→ 跳 task/预览;templateId 缺省 generic。 +- happy:modify 入口换美术(deterministic)→ POST `/studio/modify` 带 modifyPatch → 新预览版(GamePlayer 预览)。 +- edge:`template/list` 空 → 不再"模板体系重构中"死路,走 generic 创作入口。 +- edge:mock 三态(加载/空/选中→应用)可走查。 +- error:create 失败 → UI 明确失败态(非静默)。 +- integration(真机):真 IP/http origin 走查 create→预览闭环,上下文依赖特性不退化。 +**Verification**:对 mock 骨架可走查;后端 U1 真接后真机 CDP 走查 create/modify/预览闭环过;真实 origin 验过。 + +### U7. 广度 — 玩法模板中心页 + 素材中心页(新页,mock-first) + +**Goal**:补 demo 八大页缺的两新页:玩法模板中心(浏览/选择/应用模板到草稿)+ 素材中心(素材浏览/选用加入草稿);先对 mock,真接等后端模板/素材 API。 +**Requirements**:origin 广度;demo 八大页补全。 +**Dependencies**:U6(创作页接缝);后端模板/素材 API(真接,deferred 跨线)。 +**Files**: +- `game-studio/src/views/template/`(新建玩法模板中心页 + 路由) +- `game-studio/src/views/asset/`(新建素材中心页 + 路由) +- `game-studio/src/router/index.ts`(+2 路由) +- 测试:对应 `.spec.ts` +**Approach**: +- 入口/IA:与现有 8 页导航一致(底部 Tab 或创作页二级入口,实现时定);对 mock API 建骨架。 +- 毕业门:玩法模板页绑 **M1**、素材中心页绑 **M3**(后端 API 就位后真接 + UI 走查才算过 Phase 1)。 +**Patterns to follow**:现有 8 页视图 + 设计体系组件库(AppButton/Icon/Field/EmptyState)。 +**Test scenarios**: +- happy:玩法模板中心列模板(mock)→ 选择 → 应用到草稿(传 templateId 到创作)。 +- happy:素材中心列素材(mock)→ 选用 → 加入草稿 assetContext。 +- edge:mock 空列表 → EmptyState(非崩)。 +- edge:新路由不与现有 10 目录路由冲突。 +**Verification**:两页对 mock 可走查;路由接入;后端 API 就位后真接走查(M1/M3 毕业门)。 + +--- + +## 范围边界(Scope Boundaries) + +### Deferred to Follow-Up Work(P1 内、各起后续) +- **game-admin 运营台前端**(创始人裁定归本线,≈M3 低优先):限曝光/导出/经营看板 + 赋余额/订阅入口;`game-admin` repo(huijing-ui-admin-vue3 fork)。未设计到可拆单元,用到时起计划。 +- **既有页打磨广度**:feed / 钱包 / 消息社交 / 账号(均有骨架,补真接/完善)+ 设计体系迭代。 +- **真资产 provider 接入**(E3 升级):mmx-cli 真生图/音乐合成(MVP 用 spec-only 兜底)。 + +### 不在 P1(边界) +- 全部 game-cloud 后端——SAA 图/B 步、studio 编排 B6、源落库、`handleCallback` 入 feed = 后端线(001 计划)。 +- 3D 适配器 / Cocos → P2;真支付/短信/广告/渠道 → P3;云部署/监控运维 → P2。 +- 护城河增厚(素材电商/IP/角色 rig/六类资产模块化深化)→ P2/P3。 + +--- + +## 风险与依赖 + +- **R1 跨线解阻塞(E1/E2 → 后端 U6)**:后端确定性 modify guard-pending 在本线"从源真构建"。缓解:E1/E2 排最先,落后通知后端起 follow-up 接 guard。 +- **R2 E1 真空白(无先例)**:无 gameDefinition 消费者先例。缓解:`_goldenpath-probe/factory.js` 作骨架范本 + 契约已冻 + MVP 最小集先跑通一档。 +- **R3 E1 边界做成孤儿**:适配器 vs code agent 逻辑码的接缝。缓解:KTD1 已锁(跨线 001 确认),E1 kickoff 再与后端核对一次逻辑码入 bundle 的精确接缝(Open Questions)。 +- **R4 E6 比预期大 + 卡后端**:`studio.ts` 真空 + Create 改造,真接卡后端 001 U1。缓解:对 mock + frozen yaml 先做,真接异步。 +- **R5 假绿/旁路掩盖缺陷**:九门/编排器/curl 全绿 ≠ 真可玩/真可用。缓解:E4 真承重 latch+G_input;E6 真机走查 + 真实 origin(KTD4/6)。 +- **依赖**:mini-desktop(权威构建/测/九门 e2e,4320/9222 串行);后端 001(B6/U1 /studio API · SAA 产 gameDefinition/assetSpec);契约 8/8 已冻;`build.mjs`/harness/宿主装载契约/GamePackage 既冻零改。 + +--- + +## 待确认(Open Questions) + +**Resolve before E1 实现(跨线协调,非创始人)** +1. **逻辑码入 bundle 接缝形态**(U1/U2,U1 硬前置):code agent 产的 behavior 逻辑码以何形态进 entry-bundle(独立模块 / 拼入 factory)?先做最小贯穿实验验形态(见 KTD1),再展开 U1。 +2. **gameDefinition producer 迁移**(跨线集成):SAA 何时由 factorySrc 改产填充版 gameDefinition?**创始人 2026-06-17 裁定:gameDefinition 是冻结 keystone 契约,E1 contract-first 对 schema 编程、不阻塞于 producer**;producer 迁移 = 后端 off-factorySrc 的集成期事,两线在冻结契约处交汇(非 E1 开工阻塞)。 + +**Deferred to 实现期** +2. **t2048 latch**(U3):放宽 H 门 latch vs 填库死锁 driver——按数据定。 +3. **E6 进度反馈**(U6):SSE 节点流(SAA 强项)vs 前端轮询——视后端 001 进度契约定。 +4. **U7 新页入口形态**:底部 Tab vs 创作页二级入口——实现时按现有导航体系定。 + +--- + +## Sources & Research + +- origin 需求档 `docs/brainstorms/2026-06-17-mac-work-list-requirements.md`(E1–E6 + §10.2 门 + 创始人裁定:game-admin 归本线、六类资产=P-CRT-02)。 +- execution spec `docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md`:§5.1(SourceProject/gameDefinition)、§5.5(asset 产消)、§5.6(modifyPatch)、§5.7(确定性构建)、§7.2(E 步)、§10.2(引擎线验收门)。 +- 跨线对侧 `docs/plans/2026-06-17-001-feat-backend-tier0-gen-mainline-plan.md`(KTD5/U6:从源真构建=本线 E2,后端 guard-pending;HTD 数据流接缝)。 +- 实证代码:`game-runtime/src/core/game-host.d.ts`(GameHostFactory/GameInstance 契约)、`game-runtime/games/_wg1-gen/_goldenpath-probe/factory.js`(工厂骨架)、`game-runtime/scripts/build.mjs`(唯一构建)、`game-runtime/games/_wg1-gen/_shared/play.cdp.cjs`(九门,禁改)、`game-studio/src/host/inject.ts`(engineBundle 装载分支)、`game-studio/src/views/create/Create.vue`(现 generic 桥接)、`wg1/gen-worker/worker/prompt.py`(few-shot 字节不稳根因)、`contracts/prompts/registry.yaml`(第 8 类契约)。 +- skills/rules:`game-e2e-cdp-harness`(九门/latch/首局门红线)、`cheap-model-game-generation`(6 受控面/9 静态门/逻辑像素坐标)、`ui-walkthrough-cdp`(真机走查/真实 origin)、`prompt-governance`(四道闸/逐字同源)、`build-vs-buy`(LittleJS 真接线 grep 门)、`runtime-and-multichannel`(Tier1 LittleJS 增强发行版/三层约束)。