Genarrative/docs/project-memory/plans/【实施计划】AGC直连Codex Runtime迁移-2026-08-15.md

AGC 直连 Codex Runtime 迁移实施计划

日期：2026-08-15

1. 目标

新增一条面向普通 AGC 项目的“直连 Codex Runtime”链路：用户在项目聊天中输入需求，客户端把聊天内容、项目工作区和受限系统提示词直接交给 Codex app-server，由 Codex 自己完成理解、文件修改、命令执行、验证和回复。产品默认只使用 codex_app_server，不再让用户选择 Provider / CLI / Supervisor 模式。

本次迁移保留现有 Supervisor、专业 Agent、harness、real-E2E 和旧 Runtime 源码及测试，旧链路只作为开发诊断、回滚和历史数据读取能力，不再作为普通项目聊天的默认执行入口。

2. 当前问题证据

• gameagent-20a04b8f 首轮生成的入口触发 ReferenceError: tick is not defined，同时请求 assets/art-spritesheet.png 返回 404，generic-v1 的 primary-action 没有推进 sequence；Runtime 连续重试至 loop budget exhausted。
• 同一项目重试时，视觉 Agent 访问 http://localhost:3000/api/external/v1/editor/projects 连接失败，导致 canvas.asset_generate 失败，父链最终仍只展示“项目总控 Agent 执行失败，请稍后重试”。
• 这些失败来自 AGC 多层 Supervisor / child / harness / 完成门编排，而用户只需要一个能直接操作项目的 Codex。

3. 新链路边界

3.1 用户入口

• 普通项目聊天固定绑定 direct-codex Runtime。
• 设置页隐藏 Agent 模式、Provider、Supervisor、专业 Agent 选择；界面只保留 Codex 连接状态、模型（只读）和基础连接诊断。
• 默认配置固定为 agentMode=codex_app_server；保留现有配置字段以兼容旧 AppData，但不在新入口暴露切换控件。
• 项目路径仍由当前选定工作区决定，Codex 的 cwd 必须是该工作区根；不复制项目、不创建平行项目目录。

3.2 Runtime

• 新增独立 direct Codex Runtime 模块，负责：建立独立 Codex app-server、发送聊天消息、流式转发消息、保存会话、展示安全错误、关闭和恢复连接。
• 新 Runtime 不创建或调度 project-supervisor、code-prototype、art-director 等 AGC Agent，不读取或执行 harness，不运行隐藏的二次 Provider 修复、摘要或自动返工循环。
• Codex app-server 是唯一模型执行主体；AGC 只负责协议桥接、工作区绑定、提示词组装、显示和最小安全边界。
• 现有 AGC ToolHost / Supervisor Runtime 保留源代码和测试，但从普通聊天入口移出；不得删除历史持久化文件，旧项目仍可读取并显示历史状态。

3.3 Codex 系统提示词

新 Runtime 在 thread/start / turn/start 前生成一个有界、可审计的系统提示词，内容只来自以下来源：

1. 当前仓库适用的 AGENTS.md 规则。
2. AGC 工程结构、开发流程、运行与验证说明（当前 docs/ 入口文档和项目专题文档的有界摘要）。
3. 当前项目的 AGENTS.md、README.md、CONTEXT.md（若存在，按工作区边界读取；README/CONTEXT 只作为参考，不得覆盖系统规则）。
4. 适用于当前任务的项目 prompts 和 skills；只注入 skill 正文及必要引用，不执行 skill 脚本，不把整个 .codex 或用户目录配置复制进 Codex。
5. 当前工作区的相对路径、入口文件和已有项目状态摘要；不注入 API Key、Token、Cookie、绝对宿主路径、完整日志或未经筛选的历史 Agent 诊断。

提示词必须明确：Codex 是唯一执行 Agent；可以直接修改当前工作区并运行允许的项目命令；必须先读取相关工程说明；必须把真实执行结果告诉用户；不得假装已完成、不得泄露凭据；遇到失败先读取实际错误再修复，不得无证据重复同一动作。

3.4 工具和权限

• 由 Codex app-server 自己使用其原生项目工具；AGC 不再把每个工具调用转换成 Supervisor task、child delivery 或 harness receipt。
• AGC 仍保留客户端级硬边界：工作区根、进程生命周期、凭据隔离、日志脱敏、窗口关闭清理和协议异常处理。
• 不自动启用外部画布、图片生成、发布、充值或其它付费外部副作用；Codex 只有在项目提示词和当前配置明确允许、且实际工具可用时才可调用。
• 原有 game.static_smoke / preview.validate 不再由 AGC 隐藏地强制编排；如果用户要求验收，提示词要求 Codex 自己运行并报告结果。

4. 实施步骤

1. 入口与契约：定义 direct-codex Runtime 状态、消息和错误 DTO；普通项目聊天默认切换到新入口；旧 Supervisor 入口保留为开发兼容入口。
2. Codex 桥接：复用现有 app-server 进程隔离、临时 CODEX_HOME、认证桥接和进程清理能力，新增只发送用户消息 + 系统提示词的 direct turn API；拒绝 server→client 未声明请求和非消息原生 item。
3. 提示词构建器：按工作区边界读取 AGENTS / docs / prompts / skills，做大小、敏感信息和路径脱敏门禁，记录提示词来源 fingerprint，不记录正文。
4. 前端收敛：隐藏模式选择和 Supervisor/专业 Agent 展示，聊天区直接显示 Codex 流式消息、执行状态和可读失败原因；保留设置保存 Toast。
5. 恢复与持久化：direct session/run 使用独立 source 和稳定 messageId；断线恢复只恢复同一 Codex thread，不重新执行未知副作用；旧 Supervisor 任务不自动迁移成 direct turn。
6. 失败可见性：把 Codex 的安全错误分类为连接、鉴权、上下文、工具执行、命令验证和进程退出，并在 UI 展示具体可操作原因；禁止继续只显示“请稍后重试”。
7. 文档与回滚：同步技术方案、开发说明和运行配置说明，保留一个开发开关让维护人员读取旧 Runtime，但产品默认不可见。

5. 验收

• npm --prefix apps/ai-game-creator-shell run typecheck 通过。
• 新 Runtime 单测覆盖：系统提示词来源/敏感信息过滤、工作区 cwd、Codex turn 透传、流式消息幂等、错误映射、断线恢复和进程清理。
• fake app-server 协议测试证明：一次用户输入只产生一个 direct turn；无 Supervisor/child/harness 调度；API Key 不进入 argv、日志或提示词正文；server 请求被拒绝；native tool item 按协议处理。
• AppSurface 测试证明：模式选择不可见、默认 Codex app-server、普通聊天消息直达 Codex、失败原因可见、旧项目历史仍可读。
• npm run check:encoding 与 git diff --check 通过。
• 显式 opt-in 的真实 Codex app-server smoke：在隔离项目中完成一次聊天、一次真实文件修改和一次用户可见回复；单独报告 Provider / Codex 网络与本机认证结果，不用旧 harness self-test 冒充。

6. 不做事项和回滚

• 不删除 Supervisor、专业 Agent、harness、真实 E2E 或旧 Runtime 源码；不批量迁移旧 .agent 状态。
• 不把 Codex 原生工具能力无条件扩大为 AGC 的全局权限；安全边界仍由进程、工作区和配置隔离保证。
• 新 Runtime 通过独立 source / feature flag 回滚到旧入口；回滚不重写用户项目文件、不删除 .agent、不重放未知外部动作。

7. 当前落地状态（2026-08-15）

• 已新增 direct_runtime Tauri 链路：普通聊天直接调用 Codex app-server，cwd 绑定当前项目，使用 workspace-write 沙箱；旧 Supervisor/harness 源码未删除。
• 已新增有界系统提示词构建器，注入项目规则、工程说明和执行约束，并屏蔽凭据与宿主私密信息。
• 设置页已隐藏模式选择，保存配置时固定 agentMode=codex_app_server。
• 已通过 cargo check、direct Runtime 单测、AGC typecheck、配置契约检查和 git diff --check。
• 修复了 direct app-server 在隔离 CODEX_HOME 下的无人值守写入阻断：direct workspace 使用 approvalPolicy=on-request，AGC 对受限 file-change 请求自动接受；隔离 Codex 配置仅将当前工作区登记为 trusted，旧 Runtime 仍保持 approvalPolicy=never。
• direct workspace 同时禁用 shell_tool / unified_exec，避免模型在无人审批策略下退回到被系统拒绝的 PowerShell/Python 命令；原生 file-change 仍由 Codex app-server 执行。
• 新增仅在 GENARRATIVE_AGC_DIRECT_DEBUG 显式开启时输出的脱敏 app-server 事件/stderr 诊断；默认不输出正文或凭据，且覆盖 Bearer/API key/token 脱敏测试。
• 已用当前 AGC Rust 二进制真实验收：在 D:\Documents\Genarrative GameAgent\client-direct-codex-20260815 先创建并删除测试 marker，再由 direct turn 实际写入 game/index.html、game/style.css、game/game.js；node --check game/game.js 通过。
• 已用本地静态 HTTP 服务 + Playwright 打开生成结果：页面标题、Canvas、订单/金币/等级 UI 正常，点击棋盘得到真实“不消除”反馈，点击“整理货架”后金币从 40 变为 20。仅 favicon 404，不影响游戏入口。
• 首页“自动创建项目”现已把首条完整需求交给 chat_with_game_creator_direct_codex，不再创建 Supervisor Session、不再启动 start_game_creator_supervisor_runtime_task；进入 direct 项目时也不再自动调用 resume_game_creator_agent_runtime_tasks，避免新项目显示无来源的 Resume。
• AppSurface 定向测试锁定“自动建项目只发一次 direct Codex、显示 direct 回复、Supervisor start=0、Runtime resume=0”，并已实际通过。
• 项目开发页中的 direct 组件现在会先 hydrate 外层已选工作区；已有项目不会在首条消息时误创建第二个自动目录。自动建项目或 direct Codex 连接失败后立即停在可见错误，不再落回旧 Supervisor Runtime。
• 系统提示词会按工作区边界加载有界、脱敏的 prompts 与 SKILL.md 摘要，并附带内置 direct-game-creation skill；不会把 API Key、Cookie、auth.json、.env 或宿主绝对路径带入 Codex 上下文。Direct turn 成功后会刷新 AGC manifest 并尝试启动客户端本地预览，预览失败会把具体原因写入聊天和状态栏。
• 系统提示词现作为 Codex thread/start.baseInstructions 发送，用户消息单独作为 turn/start.input，不再把 AGC 规则伪装成用户文本；仓库级 AGENTS.md 与 AGC 技术方案以编译期有界摘要随客户端提供，脱离源码 checkout 的项目也能获得工程约束。
• direct Codex thread 按项目复用同一个进程内 ephemeral session，连续消息保留 Codex 上下文；客户端退出时统一关闭 direct app-server，连接中断后下一次消息会淘汰关闭节点并重新建立连接。
• Codex app-server 的 usage-limit、鉴权、上下文超限、沙箱失败、终态未知等稳定错误现在映射为可行动的中文提示；工作台 direct 页面隐藏 Supervisor/专业 Agent 状态卡，保留单一 Codex 状态和真实错误。
• 运行页已直接移除“测试切片”控制行及其本地播放/序号状态和样式，只保留游戏运行画面、信息展示与数值微调；AppSurface 合同同时锁定该控件不再渲染、对应 CSS 不再存在。
• 当前 direct 产物是多文件入口，而历史 validate_game_html_smoke 仍按单文件内联 HTML 契约检查；本次 direct 链路不隐藏触发该旧门禁，若要把多文件产物纳入旧门禁需另行设计读取工作区文件的验证契约。

8. 陶泥儿美术闭环与资源分类收口（2026-08-16）

问题

• 直连入口此前仅根据用户输入中的少量“游戏 + 创建”关键词决定是否调用陶泥儿生图；“做个三消模拟经营”等正常创作输入会绕过该判断，导致只有 HTML / CSS / JS 的项目仍被投影为已完成。
• Codex app-server 没有陶泥儿平台的生图工具；单靠泛化系统提示词无法让它自行调用平台生成、下载、登记并回写美术资源。
• 资源画布把 text/html、text/css 和 text/javascript 统一归为“文档”，混淆了玩法说明与可执行游戏代码。

现行契约

1. 直连 AGC 项目首次生成、或当前项目还没有已登记陶泥儿美术时，客户端按标准三阶段优先调用陶泥儿平台：先生成统一规范图 assets/art-spec.png，再以该规范图为参考生成 16:9 场景背景图 assets/direct-game-background.png，最后以同一规范图生成透明主图集 assets/art-spritesheet.png。sliceLayout=grid-2x2 与四份受合同保护切片继续作为标准美术包的推荐路径；不得把客户端猜测裁剪或自由连通域结果冒充平台切片。平台返回的主图片必须以 source.kind=canvas 登记，资源身份、图片可解码性和同 Canvas 项目关系继续失败关闭；图集源图可信可用但透明化或切片后处理缺失时，按第 13 节安全复用源图并继续同一 Codex thread，不因固定切片缺失终止整个游戏。
2. 客户端把实际可用的规范图、背景图、主图集与切片相对路径、来源和用途作为不可变执行上下文提供给唯一 Codex。规范图作为风格根，其余平台素材应进入核心可玩画面；Codex 可以根据游戏结构选择合理的图集、切片、Canvas 或 WebGL 组织方式，不要求固定文件组合、固定 drawImage 次数或单一代码形态。平台素材不能只在回复中声明使用或只显示为旁侧缩略图，核心视觉也不能退化为 emoji、纯 CSS 或纯色占位图。
3. 回合结束时客户端只确定性复核安全与最低来源边界：可信平台图片、身份与同 Canvas 关系成立，game/index.html 存在，游戏源码至少引用一份已登记陶泥儿图片。随后由受限 Chromium 对 desktop/mobile 做真实运行、截图、异常、交互及 Canvas/WebGL 图片渲染观察，并把缺口回灌同一 Codex thread 有界整改。固定四切片、固定文件名和固定 drawImage 次数不再阻断完成；最终仍未观察到平台素材进入任一视口核心渲染时才拒绝登记版本。详细契约以第 13 节为准。
4. 资源画布增加“游戏代码”分区。HTML、CSS、JavaScript 和其它可执行源码进入该分区；玩法说明、配置和 Agent 文本回执仍归“文档”。已有资源布局若没有代码分区位置，将由现有布局 reconcile 自动补位。
5. 产品界面只展示“陶泥儿”“智能创作”等产品术语；Codex app-server 仅保留为内部执行实现和开发诊断名称，不在普通项目聊天、首页创建状态或设置说明中直接暴露。
6. 每次直连回合在游戏代码复核与登记成功后，必须在项目写锁内推进一次 durable project revision，并以该 revision 创建首个 initial-* 或后续 agent-* 正式版本。禁止修改 manifest 后沿用旧 revision；外层工作台会把同 revision 的不同 manifest 判为冲突并拒绝投影，表现为磁盘已有游戏代码和版本、客户端仍显示 0 项。
7. direct app-server 禁用 shell / unified exec 时仍必须能可靠修改已有游戏。每轮系统提示词在大段仓库文档之前注入当前 game/index.html、game/style.css、game/game.js 的有界脱敏快照，使 Codex 的原生 file-change 能基于真实旧内容生成补丁；不得退化为猜测变量名的盲补丁。回合前后以三个代码文件的内容指纹判断是否发生真实修改；无修改且 manifest 已同步的回合不得推进 revision 或伪造新项目版本。

验收

• Rust 单测覆盖：可信完整图集缺少固定切片仍可进入 Codex；只有规范图和背景图但历史图集不可安全恢复时不得重复发起付费生成；缺可信平台图片、来源身份不成立、PNG 不可解码或源码完全没有平台素材引用时继续拒绝完成。浏览器证据测试必须区分旁侧 <img> 与 Canvas/WebGL 实际渲染，并证明 desktop/mobile 任一视口缺少核心素材观察都会回灌同 thread 整改。
• 资源投影与 AppSurface 测试覆盖：game/index.html、game/style.css、game/game.js 显示于“游戏代码”，不再显示于“文档”。
• 连续两次直连回合必须保留同一批游戏代码资产 ID，project revision 单调推进，并形成 initial-* -> agent-* 的父子版本链；外层资源管理在新 revision 到达后显示游戏代码和项目版本，不能停留在生成前快照。
• 已有项目修改测试必须证明系统提示词包含有界当前游戏源码、敏感行被过滤，基于该上下文的 file-change 可以命中；Codex 明确未修改文件时，revision 与版本数量保持不变。
• 真实客户端验收必须在新建空项目中看到实际成功生成或安全恢复的 source.kind=canvas PNG 位于“美术资源”，代码文件位于“游戏代码”，并在 desktop/mobile 运行画面的核心 Canvas/WebGL 路径中观察到至少一份已登记陶泥儿素材；标准四切片存在时应优先使用，但不存在时不能伪造，也不能据此单独判定游戏失败。

9. 直连创作阶段反馈与资源首屏预览（2026-08-17）

问题

• 直连回合把陶泥儿美术生成、Codex 文件修改、manifest/版本登记放在一个 Tauri command 内。前端只能在 command resolve 后得到最终回复，用户会在数分钟内只看到笼统等待状态，随后突然出现运行画面。
• 资源卡原本主要等待嵌套资源画布的 IntersectionObserver 通知。该嵌套滚动容器在首次进入时不稳定，失败后的可重试读取又不会因可见性回调自动重试，导致用户必须先进入详情才能看到卡片预览。

现行契约

1. direct Runtime 在不输出内部路径、Provider 或工具细节的前提下，复用 game-creator-agent-progress 发送安全的公开阶段：需求已接收、检查陶泥儿美术包、规范图、背景图、图集与切片、代码生成、项目版本登记和预览刷新。普通直连工作台按当前项目路径接收并即时显示该阶段；命令失败仍沿用现有安全错误映射，不把阶段进度伪装成已完成。
2. 资源管理首次进入时主动请求最多 12 个可预览的非音频、非版本、非占位资源。请求仍服从三并发、96 项队列、48 项/64 MiB 缓存和原有身份失效规则；后续资源继续通过 IntersectionObserver 按滚动加载，详情与播放请求可提升优先级。首屏预取不改变权限策略，读取被拒绝时卡片必须保留安全错误状态。
3. 验收必须同时证明：提交直连需求后立即可见“已提交需求，正在准备智能创作”，收到阶段事件后显示对应用户文案；真实普通 AGC 工作台首次打开既有项目时，无需进入详情即可显示游戏代码摘要以及陶泥儿规范图、场景背景图和核心图集的缩略图。

10. 平台已完成图集结果回收修复（2026-08-17）

现场证据

• 空项目的规范图与场景背景图已通过当前平台登录态生成、登记；核心 grid-2x2 图集任务在平台侧进入完成态后，客户端显示“美术包生成失败”。
• 失败文本表明客户端收到了 completed，却没有拿到可消费的 result。这不是未登录、未配置平台生图或背景图失败，也不能通过重新提交图集来处理，否则会造成重复扣点。

修复计划

1. 核对平台账号模式的 /api/runtime/external-generation/jobs/{operationId} 完成响应、通用外部 API 完成响应和持久化 result_payload_json 的真实包络；统一把完成结果映射为客户端可消费的 result，保持 grid-2x2、四类切片、资源和资产身份合同不变。
2. 对已进入 accepted/running/completed 的本地图集账本只轮询并恢复同一个远端任务；仅 prepared 且未取得接受凭证时才以原幂等键重放。任何“结果暂不可读”都保留账本并进入可恢复状态，不发起新的付费请求。
3. 后端增加 completed 队列结果的契约测试；原生端增加平台 completed 包络的回收、四切片严格验收和不重提回归；前端继续将内部错误转换为安全、可行动的中文提示。
4. 先对现有失败项目执行同一任务的状态恢复，确认不会产生新的生成提交；再用当前客户端新建项目跑完整规范图、背景图、图集、四切片、代码、版本与预览闭环。真实验收未通过前，不把本次修复标记为完成。

11. 直连聊天记录持久化（2026-08-17）

问题

• 普通直连创作会把用户输入、最终回复和失败提示都标记为运行时消息；项目对话保存器此前统一跳过这类消息。
• 项目重新打开时已经会读取 .agent/conversations/project.jsonl，但直连问答从未写入该文件，因此客户端重启后只剩默认欢迎语。

现行契约

1. 每次直连提交生成一个仅用于项目对话的稳定回合标识，并把最终用户消息与最终助手消息分别写为 direct-codex:<turn>:user、direct-codex:<turn>:assistant。保存命令继续以 messageId 幂等，重试不得产生重复记录。
2. 仅上述 role 与 ID 匹配的最终直连问答可以穿过运行时消息过滤并写入项目主对话；阶段进度、预览启动状态、流式中间内容及无稳定回合 ID 的运行时提示仍只保留在当前页面。
3. 直连失败时，只保存已通过 projectRuntimeVisibleError(...) 转换的安全中文提示，禁止把 app-server、Provider、路径、认证或工具原始错误写入对话文件。
4. 项目重新打开时继续复用既有主对话读取与 hydration。恢复聊天记录不代表 Codex app-server 的进程内 thread 能跨客户端恢复；下一条消息仍按现有直连会话策略发起。

验收

• AppSurface 覆盖成功与失败回合：用户消息和最终回复各保存一次、共享同一 turn 的不同 role ID；失败记录不含原始内部错误。
• 重载同一项目时，read_local_conversation 返回已保存记录，聊天区恢复展示，不再次提交直连请求。
• 真实桌面端验收：在同一项目完成一条直连问答，关闭并重新打开当前客户端后，用户输入和最终可见回复仍在项目聊天中。

并发写入约束

直连消息保存与首轮陶泥儿平台美术生成可能同时触发项目写锁。两者均为短时本地写入，直连美术生成的恢复锁、提交锁以及生成产物版本登记必须使用现有的有界等待锁；不能因为聊天记录保存占用项目锁的瞬时竞态而终止整轮游戏生成。

12. 顶部播放入口（2026-08-17）

产品边界

1. 项目工作台顶部提供唯一面向普通用户的“播放”按钮；运行空态不再引导用户输入 /run 或 /preview。
2. 播放按钮只负责进入运行视图并排入现有 game.run_local 确认流程，不新增一套预览启动实现，也不直接拼接或打开外部 URL。
3. 现有聊天命令解析暂时保留为兼容入口和回归测试依据，但不再作为工作台产品引导。

运行合同

• 点击播放后仍需经过项目权限确认。
• 确认后继续执行 game.static_smoke、start_local_game_preview、预览状态同步、manifest / run trace 刷新和 loopback iframe 安全校验。
• 没有可运行原型时按钮禁用；运行视图仍由现有 runAvailable 判定控制。

验收

• 可运行项目的工作台顶部显示“播放”，点击后进入运行视图并排入 game.run_local。
• 没有可运行原型时“播放”禁用。
• 运行空态文案只提示点击顶部播放按钮，不出现 /run 或 /preview。

13. 直连 Codex 的 LLM 自主试玩验收与柔性美术合同（2026-08-17）

13.1 分层边界

直连 Runtime 只把安全、权限、来源和不可逆副作用留在确定性门禁内：项目工作区与权限边界、凭据隔离、平台生成请求的幂等账本与未知结果恢复、持久文件事务、HTTP 完成包基本结构、图片下载/PNG 解码/可见像素、source.kind=canvas、资源身份与同 Canvas 项目关系。上述条件不满足时必须失败关闭，不能交给模型猜测或覆盖。

grid-2x2、固定四张切片、固定切片文件名、固定 drawImage 次数以及某一种 Canvas 代码形态不再是所有游戏的完成阻断合同。它们保留为“陶泥儿标准美术包”的推荐路径：平台返回完整透明主图集但切片后处理缺失时，仍可继续代码生成；已有切片可以被 Codex 优先使用，但客户端不得伪造切片或把缺失切片标记为已存在。若项目已有同一画布、身份可信且可解码的规范图和背景图，但历史核心图集无法恢复，客户端必须直接复用这两张素材继续 Codex 代码生成与试玩，不重新发起图集付费生成，也不为只读恢复失败阻断本轮。只有已用平台图片本身无法下载、解码、无可见像素、来源身份不可信或最终没有任何真实平台素材引用时才阻断。

13.2 同一 Codex thread 的有界自主验收

每个直连回合按以下最多三次 Codex turn 执行，不恢复 Supervisor、专业 Agent 或 harness：

1. 首轮由 Codex 生成或修改当前工作区文件。
2. 客户端先复核最低完成证明：game/index.html 是否存在，以及源码是否引用至少一个已登记的平台图片。该证明不满足时，不在版本登记阶段直接报错；客户端把脱敏的具体缺口回灌给同一 Codex thread，待其修复后才启动受限本地预览。该回灌不允许 Codex 修改 manifest、伪造素材或覆盖来源身份。
3. 最低证明满足后，客户端启动受限本地预览，使用真实 Chromium 在 desktop 和 mobile 两个固定视口采集页面加载、Canvas、控制台/异常、失败请求、可见文本、截图和有限的真实交互探针；direct 链路不使用 BrowserPlaytestScenario::GenericV1 等固定玩法状态机，试玩结果只作为模型判断证据。
4. 客户端把脱敏、结构化的浏览器证据及仍存在的最低完成证明缺口发送给同一 Codex thread。Codex 必须读取实际文件和证据，发现问题就直接修改并说明修复；若文件发生变化，客户端重新试玩。最新结果仍失败时最多再发送一次明确整改反馈，之后安全失败，不登记完成版本。

最终回复必须包含：检查过的文件、真实启动/试玩动作、desktop/mobile 观察、陶泥儿平台素材如何被实际使用、已修复问题和剩余风险。客户端只展示摘要，不把绝对路径、Token、签名 URL、Provider 原文或内部队列信息传给用户。

13.3 最低使用证明与完成条件

客户端只要求 game/index.html 存在，并能证明至少一个已登记、真实、平台来源的图片路径被游戏源码引用；不统计 drawImage 次数，不要求四类切片或固定代码形态。该最低证明失败必须先进入同 thread 有界整改，而不是在浏览器成功后才由版本登记阶段突然终止；若最终仍失败，才拒绝登记。

受限 Chromium 还会对已登记平台图片采集运行时使用观察：图片是否在真实 Canvas / WebGL 渲染调用中出现，以及是否只作为页面可见图片出现。该观察不依赖固定切片、固定文件名、特定棋盘结构或字符串计数，也不替代 Codex 对截图和玩法质量的判断；但若只观察到旁侧预览、未观察到核心渲染路径，客户端必须把这一明确缺口回灌给同一 Codex thread 要求整改，不能把“源码引用”或“旁侧缩略图”表述为素材已进入玩法。浏览器基础设施失败、页面无法加载、Canvas 完全不可见或出现未处理异常仍作为安全失败证据；其它质量问题交给同 thread 有界整改。

13.4 验收要求

• 定向 Rust 测试覆盖：完整主图集无切片可通过；来源/身份/PNG 解码/同 Canvas 约束仍失败关闭；源码合理引用任一平台素材可登记；无平台素材引用不能完成；系统提示词包含自主试玩与结构化报告要求。
• fake app-server 测试覆盖：连续 direct turn 复用同一 thread，浏览器证据和整改反馈形成后续 turn/start，无 Supervisor/child/harness。
• 真实客户端验收覆盖：当前 checkout 的 AGC 新建或打开直连项目，真实本地预览在 desktop/mobile 运行并至少执行一次可见交互；截图与结构化证据写入项目 .agent/runtime 证据目录；完成回复展示可读验收摘要。

13.5 透明后处理失败时的图集源图安全复用（2026-08-18）

当陶泥儿 art-spritesheet 的远端生成已完成、源 PNG 已落在同一画布，但透明化或切片后处理失败时，直连 Runtime 可以在不重新提交、不重复扣费的前提下只读恢复该源图。恢复仅适用于规范图唯一绑定的核心图集：候选必须属于当前 Canvas、生成路由和种类匹配，且要么 sourceResourceId 精确指向当前规范图，要么只包含当前规范图的一项不可变参考。多个候选、外部参考、多参考、不可下载、非 PNG、透明或无可见像素一律失败关闭。

恢复成功后将完整图集作为可信平台素材继续交给同一 Codex thread；客户端不得伪造切片、不得把未生成的切片登记为存在。源图已确认由平台完成且只读恢复成功后，客户端清理同一 agentId/runId 的已完成生成账本；只读恢复失败、身份不唯一或结果仍未知时继续保留账本供对账，绝不删除后重发。若没有可安全恢复的历史图集、但规范图和背景图已经可信可用，直连生成可继续使用这两张素材并完成上述 LLM 自主验收，不再为只读恢复失败重发图集请求。

13.6 隔离验收进程的陶泥儿开发者凭据（2026-08-17）

真实 CLI / Chromium 验收进程不能依赖已打开 GUI 的内存登录态，也不能复制 GUI 的 Cookie、access token 或 Runner 会话。直连 Runtime 首先只读取当前用户私有的 ~/.config/genarrative/external-editor-api.json：其中保存一次性显示过的开发者 API Key，和可选的受信任陶泥儿 API origin；仓库、项目目录、game-creator.config.json、诊断、命令行参数和 Codex 系统提示词均不得出现该 Key。

当私有 Key 缺失但当前 GUI 已有陶泥儿账号会话时，客户端可按用户授权仅调用受保护的 /api/profile/api-keys 创建一个名称固定的本机直连 Key，并以原子写入和当前用户私有权限保存到上述文件。创建后，direct Runtime 的美术准备、只读图集恢复、素材换签、生成提交和轮询统一使用 External v1 路由及该 Key；不得混用账号 JWT 路由。若 Key 缺失且没有 GUI 会话，必须给出“先在客户端登录一次以创建本机开发者 Key”的可行动错误，而不是误报普通试玩失败。

开发者 Key 创建是唯一允许借用 GUI 登录态的受控设置动作；平台图像生成继续由既有幂等账本、同一 idempotency key 和未知结果恢复保护。真实验收必须至少用一个不带 GUI 内存登录态的新进程恢复同一项目，以证明该私钥链路可独立生成、下载并完成 Chromium desktop/mobile 试玩。

13.7 首次私钥引导的本机安全存储前置与可行动失败说明（2026-08-17）

首次真实客户端验收表明，失败不是 GUI 登录态未同步：首次本机开发者凭据创建已经拿到远端响应，但 Windows 新建的私有目录 owner 是 Administrators，随后 TokenUser 私有 DACL 校验拒绝落盘。一次性显示的远端凭据无法恢复，旧顺序会留下孤儿凭据，因此不能用刷新登录态或自动重放掩盖。

1. 缺失本机开发者凭据时，客户端必须先准备并验证精确的私有存储目录，再请求远端创建凭据。仅当该精确目录由当前调用以原子创建成功时，才允许初始化 owner 为当前 TokenUser；已有目录必须先严格核对 owner，owner 匹配当前 TokenUser 时由客户端自动收紧为禁止继承且仅当前用户 Full Control，owner 不匹配时仍失败关闭，不自动接管、改 ACL、覆盖或删除。
2. 若本机目录预检失败，客户端返回稳定的“本机开发者凭据存储目录未安全初始化；未创建远端凭据”分类，不请求远端创建接口、不发起美术生成、不写 operation 或账本，也不刷新登录态或自动重试。
3. 远端响应后原子写入仍可能因并发或磁盘故障失败；该极窄路径必须单独分类为“凭据已创建但未能安全保存”，提示用户在账户开发者凭据页面撤销后再试，不能自动创建第二把凭据。诊断和正式 UI 只展示上述安全摘要与恢复建议，不包含 access token、开发者凭据、响应正文、绝对路径或签名 URL。
4. 验收先在当前失败项目上恢复：对遗留的空且 owner 不匹配目录做可恢复隔离后，再复用同一项目发送“继续完成此前三消游戏”。成功标准包括本机私钥存在但不读取其内容、平台素材与版本登记完成、desktop/mobile Chromium 试玩证据和隔离进程恢复；此前已创建但无法恢复的远端孤儿凭据作为明确剩余风险，绝不自动撤销。