games-development-ai/docs/brainstorms/2026-06-18-生成失败根因分析-requirements.md

date, topic, title, status, review

date	topic	title	status	review
2026-06-18（创建）/ 2026-06-19（v3 二次深化重写）	生成失败根因分析	「游戏生成为什么失败」根因 + 优化方向（核心 = 用对 agentic 的 M3:Anthropic 协议 + thinking/历史全保留 + 工具循环）	active	已过两轮双评审（2026-06-18 / 2026-06-19 Codex+Opus，揪 3 P0）；**本 v3 整合二轮 P0 整改 + M3 协议/agentic 实测,战略转向待执行**

「游戏生成为什么失败」根因 + 优化方向（创始人指派:用 M3 + mmx 基于现有架构达标）

v3 二次深化(2026-06-19)说明:整合三股新输入——① 二轮双评审 P0 整改;② 6c6g 对 new-api 的 M3 双协议实测探针;③ MiniMax-M3 官方文档(Interleaved Thinking 最佳实践)。结论实质转向:最深根因不是 prompt/门,而是我们把一个 agentic + 交错思维模型当一次性 JSON 填空机用、还剥掉了 thinking、历史不保留——这是核心用法错。

结论先行（修正版,据实测 + 评审）

• M3 身份(实测确认):真 MiniMax Agentic 模型(SWE/BrowseComp/xBench 等 Agent 榜 SOTA),原生双协议(Anthropic 兼容 /anthropic 官方推荐 / OpenAI 兼容 /v1),原生 Interleaved Thinking。探针证:/v1/messages 返回原生 ['thinking','text'] 块、base_resp 是 MiniMax 印记。非 Claude 改名,非弱模型。
• 60% 失败主因重排:① 用法错(最深)= 没当 agent 用 + thinking 剥离 + 历史不留 + 救场从头重生成;② 测量假阴(部分门对某品类不适用);③ 上下文断(driver 词汇/范例)。模型能力天花板:无样本实证、非主因,但现证据仅 n=5(SaaFullGraphE2eTest 3/5),统计上撑不起强结论。
• 第一动作 = 先量真基线:mini-desktop 跑「M3 agentic + thinking 全保留」n≥30,落 verdict/截图;别在 n=5 + 错用法上押注优化方向。

一句心法(v3 升级):首版说"生成器上下文 ↔ 验证器契约没对齐";更根本的是——我们没把 agentic 模型当 agent 用。M3 的看家本事(工具调用 + 交错思维 + 多轮迭代)被「一次性填空 + 剥思考 + 从头重生成」三连击废掉。优化第一性 = 先用对 M3,再谈门/prompt/best-of-N。

---

1. M3 是什么 · 怎么调（协议 / thinking / 历史 = 用法地基）

• 三条 thinking 分离路(官方,我们一条没用对):
  1. Anthropic /v1/messages → 原生 thinking/text/tool_use 分块(最干净·官方推荐·6c6g 已实测可用);
  2. OpenAI /v1 + extra_body={"reasoning_split":True} → thinking 进独立 reasoning_details 字段(干净);
  3. OpenAI /v1 默认 → <think> 内联 content(脏 → 撑爆 max_tokens 截断 = QC 撞的病)。
• 铁律(官方文档原文):多轮必须把完整模型返回(thinking+text+tool_use 所有块)回传进历史,"切勿修改 content…否则 Interleaved Thinking 失效、发挥不出最佳性能"。→ 现 looseParse 只抠 JSON、丢 thinking + 救场从头重生成 = 正好违反它。
• QC 的「thinking:disabled」是错补丁:它为躲截断把 thinking 关了(丢质量),正解是用路 1/2 分离 + 保留,不是关。
• max_tokens=16000 是输出上限,不是上下文窗:M3 输入窗 512K → context engineering 不受限(driver 文档/范例/schema/反例随便喂);输出抬到 <128K 给 thinking+答案留够(创始人定)。

---

2. 三难门判据（保留）+ 门假阴审计（评审修正:点击消除 H 归上下文,非测量)

• 判据(逐字 play.cdp.cjs):F_wiring(923-931 命中引擎调用)/ H_progress(960-988,读 gatespec 自声明的 assertAfterPlay[] + latch 驻留)/ I_control(508-526,y=800 连点 |moved|≥25∧dist≤70)。
• I_control = 真测量问题(归环境/harness):只适配 tap-target/挡板横移;键盘/拖拽类必假阴 → 按 control-scheme 分型。
• H_progress = 评审修正为上下文/生成问题,非门测错:H 门读 gatespec 的 assertAfterPlay,金样 match3(消除类)用 tap-pairs+score increased 断言 H 门本来就过 → 点击消除失败是生成选错 driver/断言(退到 tap-targets+remaining),不是 remaining=alive.length 把门测错。修法在 prompt/gatespec(选对 driver+score),不改 H 门本体。
• F_wiring:driver 没触核心路径 → fx/audio 零调用 → 连带败(与 H 同根)。

---

3. 三桶根因（用法桶升为首 · 标证据强度）

① 用法桶(最深 · 代码直证)

• 没把 M3 当 agent 用:现 SAA 是确定性图,generate=单次吐 JSON、repair=另一次单调用;M3 的 tool-use + 交错思维完全没用上。
• thinking 剥离:SaaPrompts.looseParse(503)只截最外层 {...} 抠 JSON,丢弃任何 thinking;SaaStudioGraph.model()(138-149)没配 thinking 路。
• 历史不留:buildMessages(348-356)每轮是全新 [system,user(brief+feedback)],无上一轮 assistant 响应(更无 thinking/tool 历史) → 交错思维断链。
• 救场从头重生成(a3 未做,评审 P0):gamedef repair 只喂题面+门 verdict,连上一版源码都不回传(只 factory regenerate 特例喂);prompt 还命令"重新产出完整模块" → 便宜模型反复犯同错、打翻已过部分。
• best-of-N 缺失且整图串行:SaaGraphDispatcher newSingleThreadExecutor(101)+Semaphore(1)(113)包住整条 graph.invoke(非只 play)+ 固定端口 → K 候选无法并行(评审修正:不是"只 play 串")。

② 上下文桶(纯加料 · 必要非充分)

• driver 词汇 8 vs 3:harness 支持 8 种(play.cdp.cjs:207-214),DESIGN_SYSTEM 只教 3(SaaPrompts.java:265),tap-pairs 等没教。评审警示:必要非充分——QC 7c02ff91 自证补了 flap-to-gap/seek-x、便宜模型仍产不出 nextGap/nextPlatform 配套障碍实体 = 真能力变量,补 driver 不全治。
• 失败品类无 worked example(gd-archetypes.test.mjs:34-85 有现成金样可内联)/ 隐性门约定(paddleY=800)未写 / 缺反例 / 512K 输入窗没喂满(可塞全 driver+每品类范例+schema+检索同类)。

③ 环境/测量桶

• M3 thinking 协议错用(走 OpenAI 默认内联致截断;QC 关 thinking 是错补丁)/ Java SaaStudioGraph.model() M3 兜底未配 thinking / I_control 品类假阴 / 模型路由:models.yaml 现 stage1 主码=deepseek-v4-flash、M3 仅视觉+兜底,要扶正 M3 需 n≥30 真基线(现仅 n=5,不可扶正)。

---

4. 优化清单（执行序 · 标在飞去重 · 放置 003）

第 0 步(前置硬门 · 评审焊死):mini-desktop 跑「M3 agentic + thinking 全保留」n≥30 真基线 + 落 verdict/截图 + 2 款失败款「只改 driver 不改门」证伪实验。过=上下文桶;不过=能力变量。没这个数,下面不押注。

① 用对 M3(用法桶 · 首 · 治最深)→ 003-U1

• U-A 协议切干净 thinking:M3 走 Anthropic /v1/messages(或 OpenAI reasoning_split=True),thinking 保持开;Java 用 Spring AI AnthropicChatModel(指 new-api anthropic 端点)替 OpenAiApi 那条。
• U-B 完整历史 + thinking 回传:每轮 response.content(thinking+text+tool_use)全留进历史;repair 改连续对话(恢复并升级 a3,非从头重生成)。
• U-C agentic 工具循环(接法B/ReAct 提主路):给 M3 工具(写源/build/跑九门/读 verdict/改),九门从"外部判官"变 M3 手里的验证工具,交错思维迭代修。SAA ReactAgent 落地;便宜模型 tool-use 可靠性仍需我们任务上实测(官方称 SOTA)。
• max_tokens 抬 <128K。

② 测量/环境 → 003-U5(门/运行时)+ 003-U1(M3 配置)

• I_control 按 control-scheme 分型(真活,给枚举);H/F 不改门本体、改 gatespec 约定(消除类用 score+tap-pairs);模型路由 n≥30 达标后切 M3 主码。

③ 上下文(纯加料)→ 003-U1

• 8/8 driver 决策树 + 失败品类 worked example + 隐性约定 + 反例 + 512K 喂满(检索增强同类范例)。【在飞:QC driver 上半已补,扩齐 8/8。】

④ 次要 → 003-U1/003-U2

• best-of-N(需先重构 dispatcher 解整图串行;K 候选相关性致上界 <94%,墙钟 K×3.5-16min,成本对账)/ JSON mode(per-model 实测;Anthropic 协议下 tool_use/structured 输出更稳,可能 moot)。

在飞去重(QC 分支 feat/mac-gamedef-qc-concurrent):已做 thinking py-side(但方向是"关"→要改成"分离+保留")、assert 进展过滤、driver 上半。本分析把"点状修"扩成"用对 M3(agentic+thinking+历史)为首 + 三门修对 + context 补齐 + best-of-N 次要"的系统版。

---

5. 放置（创始人 2026-06-19 定）

• 全归 003,001 已收口不重开。 用对 M3(U-A/B/C)+ 上下文 + best-of-N/JSON → 003-U1;门判据/运行时(I_control 分型/资产)→ 003-U5;模型路由 flip → 003-U2。
• 接法B/ReAct 从 P2(agentic canonical)提为 003-U1 的 M3 主路(创始人 2026-06-19 转向:M3 是 agentic 模型,该当 agent 用;agentic编排-SAA.md 待同步 P2→主路)。
• 角色分工:本档(6c6g)出方向 + 精确可执行项;所有 codegen 由 Mac 在 003-U1/U5 落地。

---

6. 验证闭环（挂 003-U1）

1. 第 0 步真基线门(上)——先量「M3 agentic+thinking 全保留」真起点。
2. 单变量 A/B(同组 n≥10):① thinking 开 vs 关、Anthropic vs OpenAI 协议 → ② agentic 工具循环 vs 单次 → ③ context 补料 → ④ best-of-N。每轮记成功率 + 逐门过门率 + 每过门成本(M3 计费口径=Anthropic 格式,待 new-api channel 确认)。
3. 达标门:SaaFullGraphE2eTest 加 minSuccessRate=0.8 硬断言;≥80% 才走 003-U2 flip;成本破 ¥0.15/款临时允许(质量优先,Phase-3 压回)。

---

关键锚点（代码 + 实测证据）

• M3 双协议实测(6c6g curl,2026-06-19):/v1/chat/completions → usage_source:anthropic+claude_cache 字段、简单题无 thinking;/v1/messages+thinking → content blocks:['thinking','text']、base_resp(MiniMax)。
• MiniMax-M3 官方文档:Agentic/Interleaved Thinking;最佳实践=完整回传 thinking/reasoning_details 入历史;reasoning_split=True(OpenAI)/原生块(Anthropic)。
• 用法桶代码:SaaPrompts.java(looseParse 503 / buildMessages 348-356)· SaaStudioGraph.java(model() 138-149 / M3 fallback 89-91)· SaaGraphDispatcher.java(单线程 101 / Semaphore 113 / invoke 275)· 端口 SaaGenNodes.java:455-456。
• 门 + driver:play.cdp.cjs(F 923-931 / H 960-988 / I 508-526 / 8 driver 207-214)· 金样 gd-archetypes.test.mjs:34-85(match3 tap-pairs+score 过 H)。
• 框架 reasoning 支持:Spring AI Alibaba getMetadata().get("reasoningContent")(ModelExecuteManager/LLMExecuteProcessor)· AnthropicChatModel 可用。
• 模型路由:wg1/gen-worker/worker/models.yaml(deepseek 主 / M3 视觉+兜底)。
• 在飞:git show 0ee2bf61 7c02ff91(origin/feat/mac-gamedef-qc-concurrent)。