games-development-ai/docs/agent-specs/2026-06-23-design-agent-phase1-execution.md

topic, type, phase, date, status, origin, owner

topic	type	phase	date	status	origin	owner
Phase 1 执行版 —— 策划 agent(create)+ API-存在静态门 + 好玩机检	execution	1 of 3	2026-06-23	execution-pending（待 §6.8 双评审 + 创始人批准后执行）	docs/agent-specs/2026-06-23-design-agent-audio-asset-line-review.md（review-closed）	Mac 开发执行线

Phase 1 执行版：策划 agent(create)+ API-存在静态门 + 好玩机检

承接 review 版(已 §6.8 收口)的 Phase 1。仅 create 路;不含 modify(Phase 3)/音频资产线(Phase 2)。 执行版 = 模块/文件/契约/步骤/失败路径/验收/回滚;不预写不可验证的代码细节。

---

1. 目标与范围边界

目标:让 amodel create 路的 design 节点变成"会读 skill 的策划 agent",产出含进货/库存环 + 节奏目标值 + 好玩自检的设计 → 喂现有 code ReAct;并加两道玩法无关的质量门(API-存在静态门 + 好玩机检),把"能玩"抬到"更好玩"。

范围内:

• 策划 agent = tool-using JS agent(复用 tools/amodel-gen/ 的 m3.mjs + read_file 工具),读真 sim skill(不手抄),输出设计文本 + gatespec。
• designNode amodel 路改为 shell-out 到该 JS 设计 agent;gamedef 路 design 不动(零回归)。
• check 加 API-存在静态门(校验插件/ctx 方法真存在)。
• 扩 sim-business-game-design skill(进货/库存范式 + 节奏目标值 + §10 标注可机检项 + 定 N)。
• 好玩门 = design 产 per-game gatespec 断言(复用现成 assertAfterPlay→play_spec→H)+ 设计时 N-of-8 自检。

范围外(硬边界):

• 不碰 modify 生命周期(Phase 3 净新建)。
• 不碰音频/图片资产线(Phase 2);Phase 1 BGM 维持现状(静音 / 修对 ZzFXM 兜底,见 U6 失败路径)。
• 通用九门零改、绝不加玩法语义(创始人定)。
• 不碰 gamedef/factory design 路;不动 code ReAct harness 的生成逻辑(只改它的输入)。
• 不改 design 输出为结构化 schema(维持富化散文 brief,review D8)。

---

2. 前置条件

• mini staging repo 同步(本会话改动已 push,feat/mac-amodel-foundation @88d3a237)。
• NEWAPI_KEY / new-api 网关可达(docs/内网凭据与端点.md);M3 可调。
• 基线绿:v3 干净 re-gen 八/九门、SAA 83 确定性回归、amodel e2e(执行前各跑一次留底)。

---

3. 模块与文件(repo-relative)

模块	文件	改动
设计 agent harness	game-runtime/tools/amodel-gen/gen.mjs	加 --mode design(或新 design.mjs):scaffold-free,read_file/list_dir + done(emit 设计文本+gatespec)
设计 agent prompt	game-runtime/tools/amodel-gen/prompt.mjs	加 buildDesignSystemPrompt():薄指令指 read sim skill + 可达性自检 + 好玩 N-of-8 + 产 gatespec
API-存在静态门	game-runtime/tools/amodel-gen/tools.mjs（check）	新增:解析游戏源 <plugin>.<m>( / ctx.<m>( → 比对各 api.d.ts 方法集 → 未知方法报错
SAA design 节点	game-cloud/.../saa/SaaStudioNodes.java（designNode）	amodel 路 shell-out 到 JS 设计 agent(复用 runProcessSplit 范式);gamedef 路保 Java DESIGN_SYSTEM
配置	game-cloud/.../saa/AigcExecutorProperties.java / SaaStudioGraph.Models	design amodel 模型档(D1:M3)+ shell-out 开关(回滚用)
design 层知识	.agents/skills/sim-business-game-design.md	扩:进货/库存资源循环范式 + 节奏目标值指引 + §10 标注可机检 N 条
蒸馏	.agents/skills/agentic-amodel-generation.md + .agents/README.md	记设计-agent 形态 + API 静态门 + 第 6 footgun

---

4. 数据流与依赖

brief ─▶ designNode(amodel) ─shell-out─▶ JS 设计 agent
                                          read_file: sim skill + 用到的 api.d.ts
                                          done ─▶ 设计文本 + ```gatespec
        ◀── 设计文本 ───────────────────────────────────────────────┘
designNode: enriched = brief + 设计文本   (现有逻辑不变)
            gatespec → merge play_spec.assertAfterPlay/expectLatch/...  (现有逻辑不变)
enriched ─▶ generate(code ReAct, 现有) ─▶ check(+API-存在静态门) ─▶ build ─▶ validate ─▶ play(通用九门 + per-game 断言)

关键:design→code 的喂法(K_ENRICHED 富化-brief)已通,不改;只是把 design 的产出方从"Java 单次调用"换成"会读 skill 的 JS agent"(amodel 路)。gatespec→play_spec 的 merge 已存在,不改——per-game 好玩/经济断言顺这条现成路走。

---

5. 接口 / 数据契约

• 设计 agent CLI 契约(对齐现有 gen.mjs --mode saa 范式):node gen.mjs --mode design --brief "..." [--game-id <id>] --key <NEWAPI_KEY> → stdout 末行单行 JSON { ok, designText, gatespec? }(或落临时文件,designNode 读)。stderr/stdout 分流(沿用 runProcessSplit,末行 JSON 不被 stderr 污染)。
• 设计 agent 工具集:read_file / list_dir(只读,repo 根)+ done({designText});无 write/无 shell(design 不落文件,只产文本)。
• 设计文本契约:紧凑中文设计稿(覆盖 sim skill §8 配方)+ 末尾一个 ```gatespec JSON 块(expectLatch + assertAfterPlay[],经营含经济断言如 {path:"currency",op:"decreased"} 或营收 {path:"score",op:"increased"})+ 一段「好玩自检:命中 §10 第 X/Y/… 条」。
• API-存在静态门契约:输入 = 游戏源 + 各插件 api.d.ts;规则 = 游戏调的 plugins.<键>.<方法> / ctx.<方法> 必须在对应 api.d.ts 的 interface 里声明;违者 check FAIL,报「<键>.<方法> 不存在,见 <api.d.ts> 真方法名」。允许列表:动态/非插件成员(如自有对象方法)不误伤——只校验已知插件键 + ctx 面。

---

6. 实现单元(依赖序)

U1. 设计 agent harness（JS,tool-using）

• 目标:gen.mjs 加 --mode design:不 scaffold、只给 read_file/list_dir/done,跑 ReAct 让 M3 读 sim skill+api.d.ts → 产设计文本+gatespec,stdout 末行 JSON。
• 文件:game-runtime/tools/amodel-gen/gen.mjs、game-runtime/tools/amodel-gen/prompt.mjs(buildDesignSystemPrompt)。
• 依赖:无(复用 m3.mjs / TOOLS 子集)。
• 失败路径:M3 超时/失败 → 末行 JSON {ok:false},designNode 回落 brief-only(沿用现有 degrade)。
• 验收:本地 --mode design --brief "经营 brief" → 末行 JSON 含非空 designText + 合法 gatespec;run-log 显示真 read 了 sim skill。

U2. 设计 agent 薄 prompt（指读 skill + 可达性 + 好玩 + gatespec）

• 目标:buildDesignSystemPrompt()——薄指令:① read .agents/skills/sim-business-game-design.md(别手抄)② 按 §8 配方产设计稿 ③ 可达性自检(只用 12 插件+boot.ctx 能达成的机制,落不到的剔除/简化,见 skill §9)④ 好玩自检:过 §10、命中 ≥N 条并写明 ⑤ 末尾产 ```gatespec(expectLatch + assertAfterPlay,经营含经济/营收断言)。
• 文件:game-runtime/tools/amodel-gen/prompt.mjs。禁反引号(模板字面量陷阱,node --check 每改必跑)。
• 依赖:U1。
• 验收:产的设计含进货/库存环 + 节奏目标值 + 好玩自检 N≥定值 + 合法 gatespec。

U3. designNode amodel 路 shell-out（gamedef 不动）

• 目标:designNode 加 amodel 分支:saaSourceMode==amodel → shell-out JS 设计 agent(复用 runProcessSplit),拿 designText 回填 → 现有 enriched/gatespec/play_spec merge 原样复用;gamedef 路保 callAndRecord(designModel, DESIGN_SYSTEM, brief)。
• 文件:game-cloud/.../saa/SaaStudioNodes.java、AigcExecutorProperties.java(shell-out 开关 + design amodel 模型档)。
• 依赖:U1、U2。
• 失败路径:shell-out 非零/末行 JSON ok:false → 落 K_DESIGN_TEXT 占位 + 回落 brief-only(对齐现有 design 失败 degrade);绝不裸退图。
• 验收:amodel 路真走 JS 设计 agent(trace 可见);gamedef 路 design 行为字节不变(回归)。

U4. API-存在静态门（check,玩法无关）

• 目标:check 解析游戏源(game-logic/core/render)的 plugins.<键>.<方法>( 与 ctx.<方法>( → 比对各插件 src/plugins/<name>/api.d.ts + PluginContext 方法集 → 未知方法 FAIL。
• 文件:game-runtime/tools/amodel-gen/tools.mjs。
• 依赖:无(独立)。先以 advisory 上线(记录不阻断)跑几轮看误报,再转硬 FAIL。
• 失败路径/误伤防护:只校验已知插件键(host-config 注入的 11 + ctx 面),非插件对象方法跳过;插件键→dir 映射坑(juice→particles-juice)写进映射表。
• 验收:对 v3 stopBgm 与历史 defineScenes 报错;对 v3 其余真方法零误报;模板 _template 零误报。

U5. 扩 sim-business-game-design skill

• 目标:补 ① 进货/库存资源循环范式(进货扣币→库存→售卖→补货;§1/§3)② 节奏目标值指引(spawn 区间/rush 起点参考区间,治"太快")③ §10 标注哪几条可机检 + 定 N(如飘字+音效/score-delta/解锁/经济扣减,N=4)。
• 文件:.agents/skills/sim-business-game-design.md。
• 依赖:无(U2 的 prompt 指它)。
• 验收:skill 含进货范式 + 节奏区间 + 可机检 N 条标注;设计 agent 读后产出体现。

U6. 好玩/经济 per-game 断言接线 + 蒸馏

• 目标:① 确认 design 产的 gatespec 经济/营收断言经现成 merge 进 play_spec.assertAfterPlay、被 H 门校验(无新管线,仅验证链路通)② 蒸馏:agentic-amodel-generation 记设计-agent 形态 + API 门 + 第 6 footgun(stopBgm→stop)。
• 文件:.agents/skills/agentic-amodel-generation.md、.agents/README.md;(经济断言驱动可达性靠 U2 设计 + driver,记 open 若 driver 不可达则降 advisory)。
• 依赖:U2、U3、U4。
• 验收:re-gen 经营游戏的 play_spec 含经济/营收断言且 H 门据其判定;skill 索引更新。

---

7. 边界 / 失败路径汇总

• 设计 agent 失败/超时 → brief-only degrade(不退图)。
• shell-out 末行 JSON 被 stderr 污染 → 沿用 runProcessSplit 分流(批 B 已验)。
• API-存在静态门误报 → advisory 先行 + 允许列表 + 键→dir 映射;确无误报再转硬门。
• 经济断言对应动作 driver 不可达 → 该断言降 advisory(记 open O,不阻断;Phase 3 modify/driver 增强再硬化)。
• BGM:Phase 1 不修音频通道;若 design 选 ZzFXM 兜底,必须连带修 SongData shape footgun,否则显式接受静音(写进验收,不假装有声)。
• 富化 design 扰动刚转绿的 amodel e2e → 每次执行前后跑 e2e + 83 回归,红即回滚(开关)。

---

8. 验证方法

• 单元:U1 本地 --mode design 出 JSON;U4 对 v3/_template 跑 check(报 stopBgm、零误报);U2 设计含进货/节奏/好玩。
• 集成(端到端 re-gen v4):经现新设计 agent 干净 re-gen 一台经营游戏 → 看产出有进货环 + 节奏舒适 + 好玩 N-of-8 命中 + 过通用九门 ≥8/9 + 过 API 静态门 + play_spec 经济断言被 H 校验。创始人亲玩判"更好玩"(对比 v3)。
• 回归:gamedef design 字节不变;SAA 83 确定性回归全绿;amodel e2e 不回归。

9. 完成条件

• A1(review):干净 re-gen 经营游戏自带进货/库存 + 节奏舒适(亲玩 + N-of-8 机检过),九门 ≥8/9,经济断言过。
• A4(review):API 静态门拦掉 stopBgm/defineScenes 类、通用九门零品类语义。
• A5(review):gamedef + 通用九门 + SAA 83 + amodel e2e 全绿。

10. 回滚

• design shell-out 由 AigcExecutorProperties 开关控制 → 关之即回 Java DESIGN_SYSTEM(amodel 也回单次调用)。
• API-存在静态门 advisory→hard 两段;hard 出问题降回 advisory。
• skill/prompt 改动纯文本,git revert 即回。
• 各改动 amodel-gated,gamedef/factory/通用九门零触碰 → 回滚面小。

---

11. 待执行前定（origin Open Items 收敛）

• O1【D1】design amodel 模型档定 M3?(执行前一次小量测:M3 vs stage1 设计质量)。
• O3【U5】§10 可机检 N 值(建议 N=4)+ 进货范式具体子型。
• O6【U4】API 门覆盖面(插件方法 + ctx 面;arg-shape 类不在本门,留 footgun-doc)。
• O7【U6】Phase 1 BGM:修 ZzFXM SongData footgun 兜底 vs 显式静音——二选一写死验收。

下一步:本执行版过 §6.8 双评审 → 创始人批准 → 按 U1→U6 序执行。