diff --git a/docs/project-memory/plans/【实施计划】AGC无人值守游戏生成可靠性收口-2026-08-13.md b/docs/project-memory/plans/【实施计划】AGC无人值守游戏生成可靠性收口-2026-08-13.md new file mode 100644 index 000000000..ab91bdf12 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】AGC无人值守游戏生成可靠性收口-2026-08-13.md @@ -0,0 +1,249 @@ +# AGC 无人值守游戏生成可靠性收口实施计划 + +日期:`2026-08-13` + +## 1. 目标 + +本次收口的验收对象不是单个报错点,而是一次完整的用户任务: + +> 用户提交一段游戏需求后,不再确认权限、不再补充“继续”、不再手工重试,AGC 在有界时间内自动产出一版可玩的游戏,并完成当前 revision 的静态验证与桌面、移动双视口真实试玩;若外部依赖或环境确实不可恢复,则必须自动收束为带安全原因的明确失败,不能永久停留在运行中、待确认或等待某个专业 Agent。 + +“产出了一份 HTML”不等于完成。最终完成必须同时满足: + +1. 权威入口产物存在、非占位且可解析。 +2. 游戏具备真实主要玩法,而不是装饰按钮或固定奖励假体。 +3. `playable-web-game-state.v1`、start、primary-action、restart 合同可由真实浏览器执行。 +4. 当前 revision 通过 `game.static_smoke`。 +5. 当前 revision 通过 desktop 与 mobile `preview.validate`。 +6. Runtime、manifest、产物和验证回执的终态一致。 + +## 2. 当前失败基线 + +本次复现暴露的不是孤立实现缺陷,而是生成控制面的系统性断链: + +- 普通工作台提交使用 `project-supervisor-gui`,进入固定专业任务图;一个单 HTML MVP 也会被美术、音频等前置依赖阻塞。 +- 现役 `project-supervisor-game-chat` 已具备“单主 `code-prototype` + 按真实缺口动态委派美术”的快车道,但普通 GUI 默认没有复用它。 +- 工作台仍展示“严格审批”,运行期间可以进入 `waiting-for-confirmation` 或要求用户继续,不满足无人值守目标。 +- `game.static_smoke` 失败时,持久回执可能只剩 `safeDetail=null`、`detailUnavailable=true`;同一 owner 看不到失败项,只能猜测修补。 +- 可修复的验证失败可能结束旧任务、留下空队列或失败卡片,未保证回到同一主 Run 继续“诊断 -> 修复 -> 重验”。 +- 子任务可以先报告 completed,再在投影阶段发现正式产物缺失,造成 Runtime 终态、manifest 状态和文件事实不一致。 +- `execution-owner` 对应进程消失后,持久 Runtime 仍可能显示 running,缺少自动对账和续跑闭环。 +- game-chat 当前首个可玩版本软预算为 4200 秒、硬上限为 4500 秒;固定图和重复猜错会把简单任务拖到一小时以上。 + +直接 Codex 能在数分钟内生成明显更完整的可运行雏形,说明首要瓶颈是 Runtime 的路由、反馈和验收控制,而不是基础模型完全不具备实现能力。 + +## 3. 范围 + +### 3.1 本次必须完成 + +1. **默认单主生成路由** + - 普通 AGC 项目工作台的新建/修改游戏请求默认使用 `project-supervisor-game-chat`。 + - 持久路由前零 child;持久路由后只启动 `code-prototype`。 + - 美术只在 `asset.list` 证明精确缺口后动态委派,且一次只处理一个依赖槽。 + - 保留 `project-supervisor-gui` 给显式专业 DAG/开发诊断入口,不再作为普通生成默认值。 + +2. **无人值守安全策略** + - 对可信 game-chat autonomous root 及其绑定 child,项目内可恢复写入、受限静态验证、真实试玩、任务路由和严格边界内的动态委派自动执行。 + - 该模式不得进入普通 `waiting-for-confirmation` 或 `waiting-for-user-input`;模型信息不足时先采用目标合同允许的安全默认值。 + - 越界路径、任意命令、发布、凭据、系统设置和未列入白名单的外部副作用继续失败关闭,不能为了“无人值守”扩大权限。 + +3. **可操作的验证诊断与自动修复循环** + - `game.static_smoke` 失败回执向同一 run owner 返回脱敏、结构化的失败码、检查项、项目相对路径和有界说明。 + - 公共聊天和跨 owner 回执只展示安全摘要,不泄露绝对路径、命令原始输出、密钥、URL query 或内部 fingerprint。 + - 可修复失败必须回到同一 `code-prototype` Run,继续修改后按“脚本解析 -> static smoke -> desktop/mobile preview.validate”顺序重验。 + - 相同 revision、相同失败指纹无新 mutation 时不得无限重试;命中停滞门后明确失败。 + +4. **完成投影与正式产物一致性** + - owner 子任务进入 completed 投影前,逐项验证其声明的正式 artifact 存在、非空,并对 JSON/PNG/HTML 执行已有格式门。 + - 只读验证任务不得声明由自己写入的正式文件产物。 + - 产物缺失时不能把 manifest 写成 completed;必须产生可修复 blocker 并由主 Run 接管,或在不可恢复时明确 failed。 + - 根 Run 只有在当前任务图、正式产物、static smoke 和双视口试玩全部对齐后完成。 + +5. **Runner 消失后的自动对账** + - 读取 `execution-owner` 时同时核对 boot identity 与进程存活性,不能只相信 JSON 中的 PID。 + - owner 已消失且 durable task 仍为可恢复活跃态时,新 Runner 启动/项目 hydration 自动恢复队列;不能永久显示 running。 + - 外部副作用结果未知时进入 `needs-reconciliation` 并保留证据,不能盲目重做;纯 Provider、项目内文件和验证动作可以按现有 durable checkpoint 安全续跑。 + - 对账与恢复必须幂等,同一 run 不产生重复 child、重复消息或重复付费生成。 + +6. **有界端到端验收** + - 新增一个从普通 GUI 提交到 game-chat 单主路由的回归入口。 + - 用确定性 Provider/工具夹具覆盖“首次 smoke 失败 -> 同主 Run 取得具体诊断 -> 修复 -> smoke 通过 -> 双视口试玩通过 -> completed”。 + - 覆盖 owner 中途消失后新 boot 自动续跑,最终只产生一个根终态。 + - 任何人工确认、人工澄清、固定专业 DAG 等待、旧 revision 验证复用或 console error 都使 E2E 失败。 + +### 3.2 本次不做 + +- 不直接修改用户下载目录中的失败示例;它只作为复现样本。 +- 不把直接 Codex 生成的某个三消 HTML固化成平台模板。 +- 不恢复已退役的主站玩法入口、公开作品系统或旧创作模板后端。 +- 不允许任意 shell、项目外路径写入、自动发布或自动消费未知外部付费能力。 +- 不以隐藏错误、自动点击确认或延长预算冒充可靠性修复。 + +## 4. 目标状态机 + +```text +accepted + -> route-pending + -> code-prototype-running + -> asset-audit + -> optional-art-delivery + -> implementation + -> syntax/static-validation + -> desktop-mobile-playtest + -> completed + +可修复失败: +validation-failed -> owner-repairing -> validation + +进程中断: +owner-lost -> recovery-scan -> same-run-resumed + +外部结果未知: +owner-lost -> needs-reconciliation -> explicit terminal/recovered + +不可恢复或停滞: +any active state -> failed (safe terminal reason) +``` + +普通无人值守生成路径禁止出现: + +```text +waiting-for-confirmation +waiting-for-user-input +fixed-art/audio dependency wait +running with a dead owner and no recovery record +completed with missing artifacts or stale validation +``` + +## 5. 实施切片 + +### 切片 A:入口和路由收敛 + +主要位置: + +- `apps/ai-game-creator-shell/src/App.tsx` +- `apps/ai-game-creator-shell/src/features/agent-runtime/model.ts` +- `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs` +- `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs` + +实施内容: + +- 把普通项目工作台的 autonomous build source 改为 game-chat 单主来源。 +- 把 source 选择抽成可测试的纯函数,避免 UI 分支再次漂移。 +- 保持显式专业/CLI 调试来源不变。 +- 调整工作台状态投影,不再向默认用户展示固定专业 DAG 和无效“严格审批”承诺。 + +### 切片 B:无人值守权限与失败反馈 + +主要位置: + +- `runtime_tools/policy.rs` +- `runtime_actions/provider_action_batch.rs` +- `runtime_tools/command_ops.rs` +- `runtime_actions/action_audit.rs` +- `runtime_actions/provider_request_builders.rs` + +实施内容: + +- 为可信 game-chat autonomous binding 建立窄白名单自动策略。 +- 对该来源的确认型动作做“安全自动执行或明确拒绝”二分,不能挂起等待。 +- 为 `command.run_limited/game.static_smoke` 定义稳定的 safe detail schema。 +- 保证同 owner 的下一轮 Provider context 能读取失败项,公共 UI 仍只拿安全摘要。 +- 增加失败指纹与 revision liveness 测试,阻止无 mutation 重复 smoke。 + +### 切片 C:完成门和恢复对账 + +主要位置: + +- `runtime_protocol/autonomous_completion.rs` +- `runtime_driver/task_start.rs` +- `runtime_driver/recovery_scan.rs` +- `runner/project_owner.rs` +- `runner/recovery.rs`(以实际调用边界为准) + +实施内容: + +- 将 artifact 合同校验前移到 terminal projection。 +- 对完成声明、manifest 状态和文件事实做一次原子/锁内判断。 +- owner 丢失时按 durable action 类型判断 same-run resume 或 reconciliation。 +- 恢复后重新核对当前 revision,旧 smoke/试玩回执不能过门。 +- 缩短无进展窗口;预算只限制时间,不能替代完成门。 + +### 切片 D:端到端门禁和权威文档 + +主要位置: + +- `apps/ai-game-creator-shell/tests/appSurface.test.ts` +- Runtime Rust 定向测试模块 +- `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` +- `docs/project-memory/shared-memory/development-workflow.md` +- `docs/project-memory/shared-memory/decision-log.md` +- 必要时 `docs/project-memory/shared-memory/pitfalls.md` + +实施内容: + +- 固定普通 GUI -> game-chat 的来源契约。 +- 增加无确认、失败自修复、artifact 真实性和 owner-loss 恢复测试。 +- 增加确定性 E2E;真实 Provider smoke 作为现场验收,不把 mock E2E 说成真实生成已经成功。 +- 把新的默认路由、无人值守安全边界和复验命令写回权威文档。 + +## 6. 验收矩阵 + +| 场景 | 预期结果 | +|---|---| +| 普通工作台提交单 HTML 游戏需求 | source 为 `project-supervisor-game-chat`,只启动 `code-prototype` | +| 素材完整 | 零美术委派、零额外扣费 | +| 缺少规范图和图集 | 先规范图后图集,一次一个 delivery,主 Run 认领后继续 | +| 项目内文件修改、static smoke、preview validate | 在可信 autonomous binding 下不等待人工确认 | +| 请求任意系统命令或项目外写入 | 明确 blocked/failed,不执行,也不挂起等待确认 | +| 首次 JS/static smoke 失败 | 同一 owner 得到结构化失败项,修改后自动重验 | +| 连续同 revision 同错误 | 停滞门阻断重复猜测,明确失败或回到可行动步骤 | +| 子任务回复 completed 但 artifact 缺失 | manifest 不得 completed;产生修复 blocker | +| 最后 mutation 后只存在旧验证 | 根 Run 不得 completed,强制重验当前 revision | +| Runner 在 Provider/文件动作间退出 | 新 boot 幂等恢复同 run,不重复 child/消息 | +| Runner 在未知付费外部动作中退出 | `needs-reconciliation`,不自动重复扣费 | +| 最终完成 | 无 console error;static + desktop/mobile playtest 均属于当前 revision | + +## 7. 验证命令 + +按实际改动范围至少运行: + +```bash +npm --prefix apps/ai-game-creator-shell run typecheck +npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts apps/ai-game-creator-shell/tests/appSurface.test.ts --run +cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_chat_ -- --nocapture --test-threads=1 +cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml autonomous_completion_contract -- --nocapture --test-threads=1 +cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml action_receipt -- --nocapture --test-threads=1 +cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_execution_owner -- --nocapture --test-threads=1 +npm run check:encoding +git diff --check +``` + +如果完整 Rust suite 受既有 Windows 文件锁影响,必须单独复跑新增 filter,并在交付中如实记录完整门仍不干净;不能用定向通过替代全量结论。 + +现场真实验收还需要: + +1. 使用新的空项目提交一个明确、无需追问的小游戏需求。 +2. 全程不点击确认、不发送继续、不手工重试。 +3. 记录首个可玩版本耗时、Provider/工具轮数、委派数和失败修复次数。 +4. 核对最终 manifest、current revision、static receipt、desktop/mobile playtest receipt 和浏览器 console。 +5. 中途强制结束 Runner 一次,重新启动客户端后确认 same-run 自动续跑且没有重复付费动作。 + +## 8. 完成定义 + +只有以下条件全部满足,本计划才算实现完成: + +- 普通 GUI 默认进入单主快车道。 +- 一个确定性端到端夹具证明首次验证失败可由同一主 Run 自动修好并最终完成。 +- 一个 owner-loss 夹具证明新 boot 自动恢复且终态唯一。 +- 可信无人值守路径不存在普通人工确认或澄清等待。 +- completed 前 artifact、当前 revision static smoke 与双视口试玩均被强制复核。 +- 相关定向测试、类型检查、编码检查和 diff 检查通过。 +- 使用真实 Provider 的空项目 smoke 成功;若现场外部服务不可用,则代码可以提交为“实现完成、真实现场验收未完成”,不得宣称目标已完全达成。 + +## 9. 回滚边界 + +- 默认路由可回退到原 `project-supervisor-gui`,但不能同时保留两套普通入口形成随机分流。 +- 自动权限只由可信 source + root profile + binding fingerprint 共同启用;回滚时删除该窄例外,不修改全局策略默认值。 +- 新 safe detail schema 只增加脱敏诊断,不改变原始审计账本的权限边界。 +- 恢复逻辑只消费现有 durable task/action/profile/owner 记录,不删除 `.agent`、锁文件或用户产物。