games-development-ai/.agents/skills/agentic-amodel-generation.md

name, description

name	description
agentic-amodel-generation	当运行或调试 amodel-gen 底层 ReAct 工具循环(read/write/list/check/build/done + 循环外 play)、或排查便宜档 cheap-worker shell-out 复用的 gen.mjs 工具面时使用:harness 文件职责、mini-desktop 运行配方、九条踩坑红线。

skill:agentic A-model 游戏生成 harness(ReAct + M3,已实证)

一句话:给模型 read/write/list/check/build/done 工具,让它自己读 skill→读插件 api.d.ts→读范例→写多文件 LittleJS src/→自查 check/build→done,harness 再跑循环外 play 出"能跑能玩"判定。这是底层 A-model harness 手册（gen.mjs 及工具循环）——现行被便宜档 cheap-worker（AgentScope/Python）shell-out 复用（reframe 前定位为「A-model 生成的生产形态」；旧 gamedef/factory 单次产线已废）。

配套:code 层手册 littlejs-game-dev.md · design 层 sim-business-game-design.md · 设计权威 2026-06-21-agentic-amodel-generation-design.md(已删,git 定位:git show 8ea97234:docs/agent-specs/2026-06-21-agentic-amodel-generation-design.md)。旧 cheap-model-game-generation.md 的 gamedef/worker-loop 路对 A-model 已退役,只看其通用纪律。

---

1. 何时用

• 要让一个模型(默认 M3,经 new-api)从一句 brief 自动生成一款可跑可玩的多文件 LittleJS 小游戏;
• 验证某模型/某 brief 的生成可达性;
• 作为便宜档 cheap-worker（AgentScope）的底层工具循环被 shell-out 复用（旧定位「SAA 生成图 generate 节点进程外 spike」随 SAA 降最低优先级远期化）。

2. 链路(agentic generate 内循环)

scaffold(clone _template → games/amgen-<id>/)
  → ReAct 循环(M3 @ new-api,openai 协议 + function-calling):
       system+brief → M3 发 tool_calls → harness 执行 → 回喂 → 循环
       工具:read_file/list_dir(repo 只读)· write_file(scoped)· check · build · done
       done 门:check 与 build 都 PASS 才接受(harness 复核)
  → play(循环外·权威门:serve + headless Chrome boot + 帧推进 + 截图 + 交互 = 能跑能玩)
  → verdict.json + run-log/run-summary + 截图

四层(自上而下,设计文档详):L1 env(mini-desktop 沙箱)→ L2 harness(本 ReAct)→ L3 context(agent 经 read_file 按需自取 skill/api/范例,不预塞)→ L4 prompt(薄,指 agent 读真 skill,绝不手抄)。

3. harness 位置 + 文件

game-runtime/tools/amodel-gen/(node,零三方依赖——Node22 全局 fetch/WebSocket):

文件	职责
tools.mjs	scaffold(clone _template,删 dist/test)+ 5 工具 read/write/list/check/build;check=node --check+五法/导出名/红线 lint(去注释串再扫)
m3.mjs	new-api M3 客户端(openai+tools,超时/重试;key:env 优先、docs/内网凭据与端点.md 兜底)
prompt.mjs	L4 薄 prompt + 工具 schema(指 agent 读真 skill)
play.mjs	循环外权威门:CDP(全局 WebSocket)boot+帧推进+截图+do(start)/tap+读 __gameHost.state()
gen.mjs	orchestrator:scaffold→ReAct(compaction+loop-detection+done 门)→play→落证据

4. 运行配方(mini-desktop)

# 同步 harness(Mac→mini)
rsync -az -e "ssh -o ProxyCommand=none" game-runtime/tools/amodel-gen/ \
  root@100.64.0.7:/root/game-staging/repo/game-runtime/tools/amodel-gen/
# 跑一款(端口两两错开,避开 live 48080)
ssh -o ProxyCommand=none root@100.64.0.7 'cd /root/game-staging/repo/game-runtime && \
  NEWAPI_KEY=sk-... node tools/amodel-gen/gen.mjs --id <id> --brief "<玩法一句话>" \
  --max-steps 45 --port 4321 --cdp 9223'
# 证据:games/amgen-<id>/evidence/{run-summary.json,run-log.txt,first-paint.png,after-play.png}

控制组(无 agent,验管线):node tools/amodel-gen/tools.mjs scaffold ctrl1 && ... build ctrl1 && node tools/amodel-gen/play.mjs ctrl1 4320 9222。

5. 关键坑 / 红线(踩过的,务必守)

1. write 路径必须含 game-runtime/ 前缀(所有工具路径 = repo-根相对)。prompt 里 game 目录写 game-runtime/games/amgen-<id>/,与 read/write 同源——少前缀 → 写全被拦 → agent 原地打转(mole2 实证)。boundary 报错要回显正确允许路径。
2. token compaction 必须做:全历史每步重发会爆炸(2.3M token!)。gen.compactHistory 折叠旧的大 tool 结果 / 旧 write 内容为占位(保留最近 ~8 条)→ 降到 ~200K。文件在磁盘,agent 需要可重新 read_file。
3. 停机纪律:① scaffold 删 test/(去掉"写测试"诱因)② prompt 明示"check+build 绿就立即 done、没有 edit_file(用 write_file 整覆盖)、别写测试/额外文件" ③ 双绿后 harness 一次性催 done。缺它 → agent 绿了还乱写测试耗尽步数(mole1 实证,45 步未 done)。
4. check 加"game.js≠_template"防假绿:写路径错→没覆盖→check 会在未改的模板上 PASS,蒙混过关。
5. update(dt) 必调 opts.runtime.bundle.tick(dt):否则插件 onFrame 不推进、timer 永不到期、一局不结束(check 已硬拦)。
6. boot envelope(沿用 _template):全局名 TemplateGame + buildTemplateHostConfig(host-config 导出名固定,别改)+ 标记 __gameBooted/__gameHost/__gameForensics;play 用 ?engine=real;build --global-name=TemplateGame。
7. 路径深度:游戏落 games/<id>/(直接在 games/ 下,与 catch-fruit 同深度)→ src/*.js import 插件用 ../../../src/(3-up)。嵌更深一层会变 4-up,esbuild 解析失败。
8. 固定 plumbing 不让 agent 碰:index.html/entry.js/src/main.js(scaffold 自带);agent 只写 src/{game,core,render,host-config,assets}.js。
9. shell-out 集成:调用方 validate 必须尊重子工具的 ok 判定,不能只查产物存在(批B Fix A 实证)。gen.mjs --mode saa 的 done-gate 顺序是 stage→smoke:smoke 失败 done 被拒,但 stage 已把陈旧坏 bundle 落盘(harness 返 ok:false/stagedDir:null 却留了文件)。调用方 validate 节点(shell-out 方,如现行 cheap-worker、旧 SAA 图)若只断言 _wg1-gen/<id>/bundle.iife.js 存在 → 误过坏件 → 路由 play → 九门必崩 + 白耗一次 ~10min 真玩。修法:generate 把 harness ok 写进 state(K_AMODEL_GEN_OK),validate 先尊重该标记(false→直接救场、不读陈旧产物);且 generate 不自增 failCount(留 validate 统一计一次,与 factory/gamedef「generate产出/validate计数」同口径,否则双重计数提前 escalate/giveup)。

6. M3 实证(2026-06-21,HJ-AGI-003)

run	玩法	steps	tokens	check/build/done/play
mole1/mole3	打地鼠	14	200K	全 ✓(mole3 自闭环)
dodge1	陨石躲避(移动+碰撞+提速)	13	175K	全 ✓
react1	反应点击(寿命靶+save-progress)	22	378K	全 ✓

3/3 跨玩法干净自闭环,截图实锤可玩。M3 tool-calling 经 new-api openai 协议快(~2s/步、不触慢思考)。bar=能跑能玩(暂丢九门;九门是旧管线的,A-model 验证另议)。

7. 主流定性(设计 §0.8)

整体 = Anthropic taxonomy 的 orchestrator workflow + 内嵌 agentic(ReAct)+ evaluator-optimizer(repair),属"受约束 agentic"——主流且被推荐用于可预测生产管线。已采纳"循环内便宜快反馈(check/build)+ 循环外昂贵权威验证(play)"分层。按需补的缺口:agent scratchpad、更强的长循环压缩、play 失败→repair 回环(spike 暂线性 done→play)。

8. 现行集成与状态（指针）

reframe 后本 harness 的工具循环由便宜档 cheap-worker（AgentScope/Python）shell-out 复用；便宜档生成质量已收口（M1 达标门三品类各 5/5 过九门、richness 加固不跌破，见 ../knowledge/tech-decisions.md §5.1），旧「Phase4 cutover 删 gamedef/factory」路径随 gameDefinition 废除、A-model 直写真 src/ 而 moot。当前构建态另见 memory amodel-generation-build-state。（2026-07-09 勘误：「过九门 ＝ 生成质量已收口」的口径已被裁定三收窄——过九门自此只算机械预筛通过，玩法层验收另需独立模型玩法判定，便宜档真实率按新基线重锚（W-AXIS 收尾波）；当日审计并证「richness 非阻塞旁路」是病根之一，所引 §5.1 条目已同步补注。见质量 SoT《游戏质量与爆火能力》裁定三。）