games-development-ai/.agents/skills/cheap-model-game-generation.md

name, description

name	description
cheap-model-game-generation	当需要 new-api 便宜模型成本口径、前缀缓存降本、代理旁路坑、或「模型能力画像/质量评估三层/别归模型造不出」等跨路结论时查阅:W-G1 便宜档实证。⚠️ 起新便宜档生成走 cheap-worker,勿照本篇已退役的 gamedef/factory 链路。

便宜模型直出可玩轻游戏 · L1 生成 worker 配方（W-G1 实证）

⚠️ 状态（2026-06-26）：本篇是 reframe 前的旧 W-G1 / gamedef-factory 路。 reframe（2026-06-25）已废 gamedef + 统一 AgentScope；便宜档生成已迁到 cheap-worker/（Python/AgentScope + 直写 LittleJS src/ 多文件 + import 复用 tier2 框架层 + shell-out 现有 node 工具），不再是本篇的「裸 openai client 不引 AgentScope + generated-factory.js + buildGenericHostConfig 套壳」。

• 便宜档 Python 线现状 → memory amodel-generation-build-state（WU-A spike）+ 执行 plan git show 8ea97234:docs/plans/2026-06-26-001-feat-cheap-worker-python-spike-plan.md；AgentScope 2.0.2 实现 API 速查 → ../knowledge/agentscope-2.0-facts.md「便宜档 cheap-worker 实现 API 速查」节。
• 仍有效（跨路通用，与 worker 实现无关）：成本口径（§2）、代理旁路坑（§3）、driver-coverage / 模型能力画像（§9）、质量评估三层（§8）。
• 已失效（被 reframe 推翻）：§1 链路（factory/gamedef）、§3「不引 AgentScope」VERDICT、§5–7 的 generated-factory / buildGenericHostConfig 套壳。
• 勿照本篇 §1/§5/§6 起新便宜档生成 —— 走 cheap-worker。

适用：用 new-api 便宜模型（DeepSeek/MiniMax）在插件库 + 装载契约上生成可真玩的 Tier1 轻游戏；质量由 harness 门保证、非模型自觉（HJ-GEN-001）。 真玩取证门见 game-e2e-cdp-harness.md §7（九门：A–G 假绿守卫 + H 机制/latch + I 控制手感）；本篇讲生成侧（谁生成 / 怎么校验 / 成本 / 坑 / 自产 gatespec）。 活样板：worker = wg1/gen-worker/（lane 分支 wg1/gen-worker）；生成产物 + harness = game-runtime/games/_wg1-gen/；交付报告 = wg1/gen-worker/REPORT.md。

1. 链路（已退役 · 仅留指针）

旧 gamedef/factory 链路 = brief → 便宜模型写 generated-factory.js（一个 GameHostFactory）→ 静态校验门 → 套官方 generic 壳（entry-generic.js + buildGenericHostConfig）→ esbuild --global-name=__GameBundle iife → P1 宿主 bootGameHost 装载 → 九门真玩、失败回喂重试。reframe 后废：便宜档改 cheap-worker（Python/AgentScope）直写 LittleJS src/ 多文件、import 复用 tier2 框架层（见篇首注 + agentic-amodel-generation.md）。铁律不变——能编译 / 能渲染 / 能动 ≠ 能玩，必须过九门真玩才算 pass。（2026-07-09 勘误：九门 pass 自此降为「未见明显死」的机械预筛地板，验收 ＝ 机械预筛 ∧ 独立模型对真玩证据的玩法判定，过九门不再单独等于 pass；铁律里「不由生成模型自评、必须真玩取证」的内核不变、且被强化。见质量 SoT《游戏质量与爆火能力》裁定三。）

2. 模型与成本（2026-06-14 网关实测）

模型	定位	实测
deepseek-v4-flash	打底（易档）	reasoning 模型；易档 0 重试 ¥0.01；三款冒烟过 A–G 核心门（H/I 逐游戏可选）
deepseek-v4-pro	难档升档	Simon 0 重试 ¥0.06
MiniMax-M2.7	备选，不优先	completion_ratio=4 拉高成本 ¥0.117 贴 ¥0.15 闸
MiniMax-M3	备选	非 reasoning，响应干脆（1-token 回 ok）

网关 100.64.0.8:3000 共 11 模型，上四款 + MiniMax-M2.7-highspeed 渠道全活（各打 1 发 ping 实测）；MiniMax 另有 M2/M2.1/M2.5 + highspeed 阶梯，横比可按需扩。原「DeepSeek key 未激活」（作战清单:32）已过时——经 new-api 网关四模型即时可用。

成本口径（¥上界，不计缓存折扣）：quota =(prompt + completion×completion_ratio)× model_ratio × group_ratio；¥ = quota / quota_per_unit(500000)× usd_rate(7.3)。闸门 ¥0.15/款（旧 W-G1 口径；现行便宜档 per-gen 硬闸 <¥10，见 ../knowledge/tech-decisions.md §4）。取价 /api/pricing、取率 /api/status；精确 logs.quota 需网关 access token（sk- key 无管理权，故只给上界）。

前缀缓存降本 60–75%（2026-06-17 实测，HJ-PREFIX-CACHE-001）：把长 system/skill 前缀固定、只变尾缀 brief，命中前缀缓存可省 60–75% prompt 成本。3/4 关键模型支持——

• deepseek-v4-flash / deepseek-v4-pro：标准 OpenAI 前缀缓存，命中率 ~75%，用 prompt_cache_hit_tokens 检测；
• MiniMax-M3：经 Anthropic 转发、返 Anthropic 风格字段，命中率 ~74%，用 prompt_tokens_details.cached_tokens 检测（勿用 prompt_cache_hit_tokens，此字段恒 0）；
• MiniMax-M2.7：不支持（缓存率 0），别依赖它省成本。
• 通用检测 extract_cache_info(usage)：先查 prompt_cache_hit_tokens>0（DeepSeek 路），再查 prompt_tokens_details.cached_tokens>0（M3 Anthropic 路），都无则视作 miss；生成日志应记 cache_info 供周期成本对账。

3. L1 纪律 + 坑红线

• 统一出口 = new-api 网关——baseUrl 指 new-api + key 走 NEWAPI_KEY（env / .env，gitignored，绝不入库）。协议不锁：同一 baseUrl 下 OpenAI /v1/chat/completions 与 Anthropic /v1/messages 并存、按模型选；不是「只 OpenAI 兼容 / 禁厂商 SDK」。（旧「裸 openai client、不引 AgentScope」spike VERDICT 已随 2026-06-25 reframe 失效——便宜档现走 AgentScope cheap-worker。）
• reasoning 模型（flash/pro/M2.7）烧 max_tokens 于 reasoning_tokens → max_tokens 必须给够，否则 finish=length、content 空。
• 代理旁路坑：本机 clash（HTTP(S)_PROXY=127.0.0.1:7897）会把发往 100.64.0.8 的请求经代理转发 → 502；NO_PROXY 大小写两版都要含网关 host，且须在 import openai 之前设。
• 输入坐标契约坑（便宜模型与人皆易错）：输入是逻辑像素 x∈[0,390] / y∈[0,844]，非归一 [0,1]（game-runtime/src/host/boot-game-host.js:295）。写错 → 能编译能渲染能动但点击全失灵（详见 harness §7 G 门，正是这门逮住的）。
• 静态门禁用 token：import / littlejsengine / Math.random / Date.now / addEventListener / requestAnimationFrame / new AudioContext / document. / window.——生成代码只许调插件公开面 + 6 受控面（getContext2d/onFrame/getInput/getAudioContext/time/random），随机与时钟一律走受控 random / time（确定性可复现）。
• bundle 入库：dist/ 被 .gitignore 吞，故 bundle 输出文件名 bundle.iife.js（不落 dist/）——它是交付物须入库。

4. 静态校验门（跨路思路见 §2 · factory 契约已退役）

「静态门先于真玩门、把必失败件挡在 CDP 开销前」的思路跨路仍有效（见 §2 坑红线）。旧 factory 路的具体契约扫描（default export + init/update/render/destroy 四方法齐 + getEngine 用法 + 禁用 token）随 gameDefinition 废除退役；cheap-worker 按 src/ 多文件工程另做静态门。

5. 边界与生产接线（旧 factory 路 · 摘要）

• 旧 factory 路只消费冻结契约（game-host.d.ts / 6 受控面 / __GameBundle / bootGameHost）零修改、只在 lane 分支。生产接线曾闭合（AigcGenerateExecutor.dispatchGeneric → worker service.py（run_studio）→ HMAC 回调 → 落库入 feed，见 ../rules/security-and-reliability.md §1.3）；单款卡九门 = 质量门正确拒发不可玩、非故障。
• 跨路承重结论（保留）：单点失败 ≠ 模型壁垒——scale-20 实证（§9）便宜模型相当能干，多数失败是宿主键盘桥 host bug + driver-coverage（harness 太朴素），真难点是 harness driver 覆盖 + 宿主门面完备，不是模型能力。旧 WG1 bakeoff 天花板 / Claude-free 评估门规划见 git show 6d2f8789^:docs/agent-specs/_archive/2026-06-14-WG1-bakeoff天花板与Claude-free评估门-review.md（已随 _archive 清理删除，git 定位）。

6. latch 终态契约 + 套壳（旧 factory 路 · latch 承重保留）

旧 factory 路把 L1 产出靶定为官方通用装载壳（buildGenericHostConfig 标准 7 插件装配 → esbuild --global-name=__GameBundle），reframe 后套壳环节由 cheap-worker + tier2 框架层承接。两条跨路承重契约保留：

• 可测性红线：产物须导出 _forensicsView()（纯只读、闭包实时值：phase / score / remaining / progress / gameoverReason + 实体位置），供宿主 host.state() 透传取证；技巧游戏另导出 ball/paddle 等实体 {x,y,vx,vy,w} 供适配真玩与手感门。
• ★ latch 终态驻留：phase ∈ booting|playing|gameover，进 gameover 后恒驻留（禁自动重开）；宿主 inject.ts 每 500ms 轮询 phase 代发 game_end 结算——瞬时终态会被漏读 → 闭环静默断裂，故必须驻留。

7. design agent 自产 gatespec（旧 factory 路 · 家族二分保留）

旧 factory 路把确定性手感门（H/I）从手写 brief 升级为 design agent 自产、studio 抽取合入，使确定性门覆盖任意生成游戏、随生成规模自动扩张（harness 复利一环）。具体挂点（roles.py 的 DESIGN_SYSTEM 产 gatespec、studio.py 的 _extract_gatespec 抽取合入）随 reframe 由 cheap-worker 承接。

• 跨路承重结论（保留）= gatespec/driver 按玩法家族二分（a2cbabe6 实证）：离散点击目标类 → 必产 tap-targets + 导出 targets[{x,y,idx,occupied}]、绝不 none（否则 dispatch 面盲打卡 H_progress、latch 不触发）；规避/推理族 → safeOnly:true + 导出 safe（仅 _forensicsView 测试可见、不渲染）+ 断言 result=="win"；安全放置族 → 断言 progress↑；技巧挡板类 → paddle-intercept（ball.x 绝不 ball.y）；其余 none。两侧 prompt 须逐字同改保公平。

8. 质量评估：确定性门兜底 + 人锚天花板（W-G1 校准实证，2026-06-14）

确定性门（Claude-free，优先） 已能把多数"坏"变可判：九门 + latch + 控制手感门 + 适配真玩。"上下文是杠杆"实证：同 flash 仅改接地，成本 −50%、修复轮次 −80%；player rubric 锚定（1-5 分级 + 空心→≤2）把 MAE 1.25→0.75。

但便宜 player agent 做"好玩裁判"有结构性天花板：

• 静态截图（M3 视觉）+ 运行数据（flash 文本）判不出交互动态质量（物理/碰撞/控制手感）。实证：创始人亲玩把碰撞有问题的 pro 判 fix，两个 player 都给 fun=4（高估）；text 还漏了 m27 的控制 bug。
• gate-H 盲打脚本会假阴性：固定坐标 taps 打不动技巧游戏→"0 进展"≠空心（创始人把被判空心的 v2 排第 2）。解法 = 适配性真玩 driver（读 state 接球，harness §7）。
• founder/人锚不可替代（至少现阶段）：没有它会把碰撞有问题的 pro 当"最佳"发出去。校准 harness = wg1/gen-worker/worker/agent_loop/calibrate.py（吃 calibration/labels.json 人锚，算 player vs 人锚 MAE/吻合/反样本否决）。
• 路线：确定性门做"地板"（能跑/真接线/有进展/latch/跟手），手感尽量拆成确定性检查（碰撞穿透门 J 规划中）；拆不掉的主观手感留创始人抽检。

9. scale-20 放量实证:模型能力画像 + spec 预判推翻(W-G1 lane v3,2026-06-14)

flash 打底放量 14 款(主力 8 + 压测 6),Opus 对抗审计核实(2 个 ultracode workflow):

• 主力 7/8 真可玩(0 假绿):井字棋/见缝插针/打砖块/跑酷/太空侵略者/Doodle/扫雷(扫雷=borderline——本体可玩,但门弱断言经"踩雷 lose"路径满足、证据薄)。flappy 唯一未过=driver-coverage(升 pro 仍挂,但源码物理合理、理想 AI 得分→是 flap-to-gap driver 太朴素,非模型天花板)。
• 压测:match3 ✅;2048/Tetris/Asteroids 三款键盘游戏全挂于宿主缺键盘桥(非模型,见 game-e2e-cdp-harness.md §8);multiball/愤怒小鸟=driver-coverage。
• ★ 模型能力画像(flash):文本 HUD / 网格状态机(井字棋胜负+AI、扫雷洪泛)/ 子步 swept CCD(asteroids/multiball)均自写正确;计时/物理精度(Flappy)需题面 pin 死数值 + 收紧观测契约(Doodle 实证:收紧计分 + seek-x driver → regen 首发过)。栽点主要在静态门可拦的纪律滑坡(Date.now/Math.random/缺 render·destroy/没调 getEngine),零 CDP 成本拦下、回喂即修。
• ★ spec 预判的门面缺口几乎全推翻:CCD / 文本HUD / 网格 / match-finding / 手势均非缺口(便宜模型自带或自写;故"碰撞穿透门 J"已非急需)。真·L0 门面缺口收敛为唯一一处=宿主键盘桥(已 spawn_task 交 L0)。完整数据见 git show 6d2f8789^:docs/agent-specs/_archive/2026-06-14-WG1-scale20-短板量化报告.md（已随 _archive 清理删除，git 定位）。
• M3 视觉 player 当生产过滤器(calibration/m3_test.json):与门 8/9 一致、抓显性空心(flappy fun1)、漏截图不可见失败(键盘死/弱证据,恰被确定性门兜住)→ 三层互补(门=地板 / M3=主观过滤 + 便宜 fun 信号 / 创始人=人锚)。MAE 压低待创始人对新款补锚(框架沿用 calibrate.py)。
• ★ 规避/推理族:题面须自产「安全位」+ 断言用胜利终态(saolei borderline 修复,2026-06-15):tap-targets 盲点首个对扫雷会盲踩雷秒负、核心玩法零暴露(门弱断言被 lose 路径满足→ false-borderline)。修法 = 题面令 _forensicsView 自产 safe(测试专用 x-ray,=!cell.mine,勿渲染/勿给玩家避雷提示)→ harness driver safeOnly:true 只揭安全格到 win → 断言改 result=="win"。flash 一次过且自产 safe 正确(generated-factory.js:337)→ 坐实缺口在题面、非模型能力。通则:凡「盲点首个会致负」的家族(扫雷类),题面给 oracle 安全位 + driver 避负 + 断言用胜利终态;门只证「机制点亮+可赢可达」,好不好玩归 M3+创始人。详见 git show 6d2f8789^:docs/agent-specs/_archive/2026-06-15-WG1-tap-targets-driver-自产缺口-L1brief.md（已随 _archive 清理删除，git 定位）。
• ★ driver-coverage 6 款闭口 + 重生成归因(2026-06-15):scale-20 余 6 款 driver-coverage 失败全部归因(详 git show 6d2f8789^:docs/agent-specs/_archive/2026-06-15-WG1-driver-coverage闭口与P2对照-L1报告.md（已删，git 定位）+ harness skill §8 四因铁律)——0 个模型造不出 / 0 个 3D 硬界:flappy/multiball 重生成即过(原件『缝隙贴顶』/『底部丢球未实现』=实例缺陷非模型短板,收紧 brief + 增强 driver〔vy 前瞻 / 弃守排空〕后 flash 翻绿,multiball retries=0);t2048/asteroids 宿主键盘桥(L0 已修)重打包即活;asteroids/angrybirds 盲玩=可测性边界,经 enrich exportState(asteroids 暴露陨石坐标 / angrybirds pin+导出 launch 物理常数)+ 适配 driver(aim-fire / drag-aiming 解析)转确定性闭口(asteroids score 0→6、angrybirds 0→20 清场)。生成侧铁律:单件失败禁直接归『模型造不出』,必重生成区分『实例 bug / 可测性缺口 / 模型短板』——『模型造不出』是最大伪报源(原 flappy『升 pro 仍挂=模型天花板』被本轮证伪=driver+实例)。

10. gamedef 路 × 保真度谱系（已退役 · 跨路红线保留）

SAA gameDefinition 路已随 reframe 废（A-model 直写真 src/）。Plan B Phase-2 质量门（real-play CDP + rubric + 三契约）逆出的三条跨路红线保留（详 git show 6d2f8789^:docs/agent-specs/_archive/2026-06-21-planB-phase2-closeout.md，已随 _archive 清理删除、git 定位）：

• 别归『模型造不出』（呼应 §9 末红线）：同档 §9 实证 flash / 九门路曾产可玩打砖块 → 非绝对天花板；只在一条配置测 2 轮就判天花板 = 伪报，根因常是模型选择 + prompt 局限。
• 杠杆排序（复杂机制保真）：few-shot 对复杂机制无效（LLM 无视/复现不出）< 换更强模型 / skeleton-first 确定性骨架（结构强制、LLM 只填参，绕过坍缩）；简单玩法 few-shot + 保真铁律有效。
• 质量门 ≫ gen 自评 accept：gen 的「accept ≥80%」放过 assets=0 / 静止不可玩 / 不忠实 / 雷同 / 几何占位 的游戏——只有 real-play（帧变=真玩）+ rubric（设计保真）+ 三契约逮得住，质量门不可由 gen 自评代替（此结论跨路有效，现行便宜档九门 + LLM 丰富度验证同理）。

11. 便宜档 AgentScope harness 失败模式:小瑕疵→整文件重写→漏参熔断死圈（2026-07-08 根因实证）

一次真实失败运行（amgen-dify-9da8f701，brief=躲避掉落街机，最终 ok=False）暴露出一条结构性死圈,它不是玩法差、不是模型造不出,而是工具面缺一条增量修改路径把「可恢复的小瑕疵」推成了「整局失败」。链条是这样的:agent 写出的 game-logic.js 带了个小红线违规——rng()/nowMs() 在 ctx 不可用时回退用了 Math.random()/Date.now()（game-logic.js:125/127）,check 的 \bMath\.random\s*\( 纯文本正则照样命中,判 FAIL;agent 正确地想去修它,但便宜档六工具面只有整体覆盖的 write_file、没有增量 edit——于是「改三行小函数」被迫变成「重写 22KB 整文件」,而 MiniMax 在吐这么长的 tool-call 参数时反复把 path 字段整个漏掉（Service 日志 Input validation failed for tool 'write_file': 'path' is a required property 连撞四次,前面还先幻觉调了个根本不存在的 edit 工具）;四次相同签名失败触发 tier2 stuck 熔断,ChatService.run 抛 Tier2CircuitBreak 强杀回合,九门收口从未运行（_wg1-gen/<id>/ 目录不生成、无 verdict）,judge_cheap_verdict({}) 判未过 → ok=False。

几条容易误判的地方,写清避免下次栽:

• check 工具 state=success ≠ 结果 PASS。 AgentScope 记的是工具执行成功,不是校验通过;read_file 读不到文件也返 "ERROR: ..." 文本、同样记 state=success（cheap_toolkit.py）。判成败要看工具的返回内容,不看 state。
• 丰富度分与 ok 无因果。 本局丰富度 8/12、degraded=False 仍 failed——richness 是 reply 结束后另跑的非阻塞旁路评分,ok 只认九门 verdict。别拿丰富度当上线判据。
• 品类跑偏≠模板锚死,且与 ok 无因果。 本局产出「按序点击」而非 brief 的「躲避掉落」,但对照另一发真运行 amgen-dify-1783477578（同为动作类 brief、同六工具面）成功把点圆模板改成了纵向卷轴射击——模型有能力偏离模板,跑偏更多是「反复找不到 brief 文件 + 无同品类范例」叠加的把握不稳,不是「克隆 _template 只改 game-logic」硬锚。且就算做对品类,红线没修 + 熔断一样 failed。
• 读多写少（读列 : 写 ≈ 3.6~25:1）是系统性常态,不是杀手。 九发对照全部如此,成功局比本局空转还狠。空转烧钱耗时,但不决定成败;真杀手是上面那条死圈,一旦产物带个需小修的红线就高概率复现,而带增量 Edit 工具的运行天然规避它。

非根因清单（别把症状当根因）:不是预算/成本（¥4.32 远低于软停 ¥10）、不是上下文压缩崩、不是超时/轮数闸、不是 L1 写保护误伤（错误是「缺 path」不是「拒写」)。

附带的可追溯性缺口:brief 原文在 worker/Service 任何日志与产物里都没落盘（worker 只记 trace_id/gameId、Service 没记 input、agent 找的 start.brief 根本不存在)——生成的核心输入事后不可审计,该补落盘。

修法方向(不写代码,经 Codex+Opus 双评审校正,详见计划档):①给便宜档一条可靠的增量 edit/apply-patch 工具(read→精确替换→复用 cheap_run.write_file 的 L1/L3+whitelist 回写、不触发 check、加入软停 blocked-tools) + 对「连撞同签名畸形参数」做窄口径纠偏(仅 schema 缺字段类、不重置 stuck 计数、cheap-only 别改坏共享 tier2 熔断)——治死圈这一终止模式的最高杠杆;②**_template 的 rng 本就合规(ctx?ctx.random.next():0)、根本无 nowMs,违规是模型无视合规模板自造的**——不是"改模板",而是让 check 红线报错指到行并点破「函数内回退也算裸调、正则按纯文本命中」+ 提示层加「照模板逐字克隆、禁自造裸回退」与 check-early(写完即 check),比造工具更上游更省;③补 brief 落盘(落 game_dir/evidence/ 脱敏限长、别落工程根——源工程可进素材市场交易)。死圈只是失败模式之一:实测 23 局真过门率仅 ~39%(跑到门 83% 但多为 E/G/H 玩法坏死挂门),三修消除死圈但到不了 MVP ≥80%,80% 缺口(玩法正确性)属质量线另一工作面。（2026-07-09 勘误：这三个数字与归因已被五路审计推翻——「真过门率 ~39%」是 stripCode 假阴修复前所测，字符串内 //（如赛博文案 'JACK IN // FLOOR'）被误当注释抹掉真代码、把写对的模型反复拒到熔断烧钱（commit 0be0f61c），修复并给 per-genre 起点后 xtheme／it5-lockcore／r1 三批各 5/5、模型未变，过门率随工具移动不随模型；「多为 E/G/H 玩法坏死」大半是误标，真因多为判卷驱动器合约缺口——进不去菜单／认不出终局／score 键没对上，小补丁即过，真坏死是少数且已被 per-genre scaffold 修掉；故「80% 缺口＝玩法正确性」不成立。诚实边界：只能判 80% 不是 MiniMax 天花板，不能反推已稳定 95%+。见质量 SoT《游戏质量与爆火能力》裁定三与同日诊断档 docs/brainstorms/2026-07-09-生成线harness方向性诊断与换轴方向.md §2.5。）