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。

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 丰富度验证同理）。