@@ -1,5 +1,41 @@
# AI 游戏创作智能体 App 实施计划
## 当前策划入口与退役边界
策划 V1、策划会话 Runtime V2 均已删除，当前“做方案”只使用独立 Design Agent，现行合同见[策划 Agent 生产迁移与工作区浏览 ](./【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md )。旧 V1/V2 Runtime、命令、会话、审批卡、身份白名单和专属测试不作为兼容或恢复目标；历史方案中的 lifecycle v3、planning binding 等要求不能作为孤立代码的保留依据。共享能力按现役调用判断，不因名称相似删除当前 Design Agent 或通用 Runtime。
前端测试遵循相同退役边界：`appSurface` harness 不保留无消费者的旧策划响应流、GDD 状态工厂及其导出，不再引用已删除的旧 PlanGdd 类型；现役 Design Agent 测试使用当前会话与工作区契约。
## 固定视觉门禁与任务身份的现行边界
图片产物按项目需求选择，不恢复按固定 Agent 身份要求视觉资源的旧完成门禁。已停用门禁的空调用、不可达检查和无消费者包装直接清理；现役 `validate_manifest_required_visual_asset` 、图片检查、内部切片提交及各完成合同继续按各自调用场景执行，不因清理旧门禁而一并删除。
自主任务父身份校验只核对当前父任务及 Run Profile 绑定，不代表 Goal Contract 已持久化，也不新增等待 Goal 文件的前置条件。manifest seed 同步保留执行状态，不以素材检查结果重新推导任务状态。用户修订的持久状态判据继续供 lineage 重放与修订请求校验使用，不依赖已无消费者的查询包装或旧策划审批写入入口。现役 Design Agent 审批只更新自身会话；旧 `UserRevisionRequested` delivery 仍保留读取、claim 重放和完成门禁兼容，不为消除 warning 删除持久状态支持。
## OAuth 认证路线的契约冲突与待决边界
**状态（2026-09-23）：明确暂缓，待决定 AGC 是否支持使用用户 Codex OAuth 登录态。** AuthBridge 认证桥尚未接通正式入口；既不能认定为现役已支持能力，也不能仅因生产无构造点而宣布整条链退役。
### 冲突事实与证据
- **生产入口 ** ： `src/agent/codex_app_server/mod.rs` 的 `acquire_at_workspace` 只在正式路径构造 `PlatformSession` 或显式自定义连接的 `AppDataKey` 。`find_game_creator_codex_auth_path` 、`read_game_creator_codex_auth_bridge` 及旧凭据 resolver 限定为 `cfg(test)` ；没有正式配置 / feature 接通 AuthBridge 构造。当前[模型别名与对话选择方案 ](./【技术方案】AGC后台模型别名与对话选择-2026-09-05.md )描述的是官方平台路由与显式自定义 Key。
- **仍存在的实现与承诺 ** ：提交 `485ed50b26217d20fad2ac192c949fd3f20914da` （ ， #439 ）新增 `model_catalog.rs` 、`model_catalog/auth_handoff.rs` 及相关测试，并在[本方案“SDK 串行工具的等价接入” ](#sdk-串行工具的等价接入 )写入 OAuth 模型目录来源校验、私有凭据轮换续传及身份隔离要求。这里“目录”指模型及能力列表，不是文件目录。
- **时间顺序 ** ：正式凭据 fallback 被限定测试的记录见 `2e15289264` （
- **验证边界 ** ：OAuth 目录测试使用真实 Codex 配合模拟认证和本地服务，轮换测试验证私有缓存及身份隔离；这些不能证明正式客户端已接通真实用户 OAuth 登录。每回合模型目录捕获也服务现役平台代理，不能随 OAuth 专属链整体删除。
### 暂缓期间的处理
保留认证桥相关 warning、现有实现及待决记录，不新增 `allow` ，不为清零把整条业务链继续移入 `cfg(test)` ，不擅自接通用户登录态读取，也不把现状记录为“已支持 OAuth”。该待决项与其它已完成的 warning 清理独立，不阻止其它改动提交。
### 下一决策点与关闭条件
| 决策 | 关闭条件 |
| --- | --- |
| 不支持用户 Codex OAuth 登录态 | 同步撤销相关文档承诺，删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试；保留现役平台 / 自定义 Key 路由、共享模型目录和隔离运行环境，完成定向验证。 |
| 支持用户 Codex OAuth 登录态 | 先明确入口、授权与凭据隔离合同，再接通正式构造路径；验证真实登录、模型目录来源、轮换续传、身份切换与错误恢复，不能仅凭模拟测试或取消编译告警关闭。 |
当前尚未选择上述任一路线。本节是该冲突的维护位置，不依赖临时编译警告清单；决定后在此更新为最终合同，决策历史由 Git 保留。记录冲突本身不构成功能接入或退役决定。
## 2026-09-23 Direct 宿主继续请求输入修复
- 首次模型请求使用原始结构化用户输入，保留 Skill 提及及其它引用；未提供结构化输入时沿用请求正文与图片转换。
@@ -29,7 +65,7 @@
| 分层验证 | 视觉、定点玩法、项目测试和必要完整闭环按已登记标准执行；不混淆证明范围 | 双端正例与单端失败反例 |
| 统一预算 | 内置验证、托管脚本和原生命令执行受同一宿主预算约束；不以命令文本猜测“是不是试玩”，不把每条普通开发命令单独计为一次返修 | 捆绑 app-server 的执行前控制、拒绝无副作用、跨入口/重启/耗尽/超时用例 |
| 稳定基线 | 可复用的固定种子跑酷基线，真实短按/长按跳跃、单次收力、滑铲释放及公平越障窗口 | 物理单测、双端真实输入、原案例缺陷参数反例 |
| 速度可归因 | 已实现请求分段计时继续有效；新增 实际并行批读与宿主首轮上下文预取 | 有界读取/并发屏障/安全边界/减少独立读取往返证据 |
| 速度可归因 | 实际并行批读与宿主首轮上下文预取按真实调用验证；界面耗时与模型使用记录各守其证明范围，旧请求分段计时链不算生产能力 | 有界读取/并发屏障/安全边界/减少独立读取往返证据 |
| 工具并行 | 现有全部工具并行、在途上限、同资源事务和付费防重继续有效 | 混合调用、图片双 POST 同时到达、同参防重回归 |
### 自动预检与可信脚手架
@@ -106,12 +142,12 @@
- 外部验证只通过客户端提供的 Node/npm 入口运行，在同一预算内保存退出码和有界输出；生产 Skill 明确禁止转到原生 shell 自建并重复执行另一套试玩来规避预算。任意原生 shell 的语义不能由字符串猜测可靠识别，本合同不声称已通过权限沙箱硬阻断所有绕行。
- 鉴权、权限、余额、项目身份、传输丢失、取消及付费结果不确定继续遵守原终止/对账边界；确定性参数错误先修参数，不原样重复付费请求。
### 分段耗时
### Direct 历史、审计与耗时的现行边界（2026-09-23 核准）
- 在既有 Direct 回合审计记录中追加计时，关联 clientTurnId、独立 attempt 和 request 身份。记录 configured/requested model、reasoning effort 与封闭的路由分类；上游返回的 model 单独标明，不能把配置值冒充实际模型 。
- 区分连接准备、客户端回合锁等待、turn/start 应答、HTTP 发出到响应头、首 body chunk、首 SSE event、首内容 delta、流终态、工具与上下文压缩。不可见的上游排队/推理保持未知，缺字段不得补零 。
- 并发时按区间并集计算占用，同时保留分维度统计，不能把重叠时间累加为整轮墙钟。条目记录达到上限后统计仍继续；流 EOF、错误、取消和 Drop 均正确收尾 。
- 只保留时间、计数、模型安全标识和状态，不保留凭据、端点 URL、请求/响应正文或推理内容；统计失败不能覆盖本来的业务结果。旧历史不回填推测值 。
- DirectProject 的完整回合条目只写入 `.agent/conversations/project.jsonl` ，按 [ 原始历史与异常恢复 ]( ./【技术方案】DirectProject%20Codex原始历史与异常恢复-2026-09-04.md ) 保存 canonical 用户条目和 Codex 完成的原始 item。工具调用与结果从同一事实源读取，前端继续使用安全投影；完整私有历史不能直接作为埋点或上传报告 。
- GUI 回合不再创建 `.agent/runtime/direct-codex/turns/<clientTurnId>.jsonl` 平行审计日志，也不再由该链写入 `agent.db` 的 `direct.codex.turn` 摘要。旧 `DirectCodexTurnAudit` 、 `DirectTurnMetrics` 、沿途审计 / 计时参数、专用批量 JSONL 追加包装和退役测试已删除。旧审计专题归入历史，不要求恢复其 writer、 `offeredRead` / `firstDesign` 投影或分段计时落盘；代理的字节流透传、错误传递和独立模型记录测试继续维护 。
- 会话运行中的对话和工具界面耗时仍按生命周期事件显示；模型请求 / 响应身份仍由 `.agent/model-usage.jsonl` 独立记录，Provider proxy 本体继续承担路由与响应型号观察。两者都不能证明 HTTP 首包、首 SSE、首内容 delta 或各阶段占用已形成生产分段计时记录；旧计时 fixture 通过也不能作为生产接入证据。 `project.jsonl` 的 `recordedAt` 只是完成 item 的写入时间，不是 turn 起止时间；重进历史缺终态边界时不能承诺精确耗时，也不得补造请求阶段统计 。
- 历史项目可能留有旧审计文件或摘要；本次契约收敛不删除、迁移或重写用户数据，也不要求新回合继续追加。现役模型使用记录、产品埋点、Runtime Agent 审计和付费 / 恢复凭证各守原有合同，不因 Direct 平行日志停用而退役 。
### 工具并发
@@ -124,6 +160,8 @@
### SDK 串行工具的等价接入
> OAuth 状态（2026-09-23）：下列 OAuth 目录与凭据轮换要求已有下游实现和测试，但正式凭据入口尚未接通 AuthBridge。是否支持用户 Codex OAuth 登录态仍待决，详见本方案的[契约冲突与待决边界 ](#oauth-认证路线的契约冲突与待决边界 )。平台代理使用的共享模型目录能力继续有效。
- DirectProject 对外保留完整补丁和计划能力，由宿主 MCP 提供 `agc_apply_patch` 与 `agc_update_plan` 。精确关闭 SDK 的旧计划工具注册；缺少合法回包通道的原生问答工具不再声明可用，需要用户信息时使用现有聊天。
- 通过同一可信捆绑 Codex 和身份/路由隔离的 HOME 取得完整模型目录，只置空 `apply_patch_tool_type` 以移除 SDK 全局串行补丁处理器。不得修改模型名称或其它 metadata，不为未知模型伪造显式条目；匹配和 fallback 仍由 SDK 执行。
- 代理模式的 bundled 目录和 OAuth 的实际远端/有效缓存来源分别核验，不能把模型目录导出 exit0 当作远端成功。每个 Direct 用户回合创建新模型目录快照和进程；旧执行器完全收束后才进入下一回合，不在活动执行中重启或重放。该行为是按回合冻结 metadata，不是实例内动态 overlay。
@@ -139,7 +177,7 @@
| 环境可用 | 运行时分发/完整性定向测试，真实 Node/npm 与浏览器 CDP smoke，缺失与损坏失败关闭 |
| 验证收敛 | 同轮跨入口与重启预算测试，超限停止，成功复用与源码/素材变更失效，层级不混淆 |
| 交付收尾 | 内置 Skill/提示词与工具合同一致，定向回归，无旁路无限试玩指引 |
| 可观测 | 本地 mock SSE 分片/错误/Drop/跨轮测试、区间并集测试、模型身份与敏感数据边界 |
| 可观测 | 现役历史写入与安全投影、界面生命周期耗时、模型使用记录及敏感数据边界；旧审计 / 计时测试不替代生产调用证据 |
| 工具并发 | 不同工具可在首个响应前开始且乱序按 ID 回包；两个不同图片同时到达 mock 平台，同参只提交一次，容量和 manifest 合并测试 |
| 整体 | 范围匹配 Rust/脚本测试、类型检查、Skill 包校验、文档索引、编码与 diff 检查；真实 Provider/安装包未运行时单独列明 |
@@ -356,7 +394,7 @@ DirectProject 的生图、素材处理、构建和试玩可能跨越短生命周
DirectProject 工作区只恢复自身对话，不按专业 Agent 默认任务占位行批量读取旧会话或生成专业 Agent 文本回执。专业 Agent 结果加载 effect 必须以当前 Runtime 模式为边界，并在模式切换时清空旧结果。仍供开发入口使用的 `read_local_conversation` 在 blocking worker 内完整执行权限校验、会话目录解析和历史读取，避免文件访问或锁等待阻塞 Tauri 窗口线程。
项目打开链路的目录检查、manifest 读取、 项目 revision 读取和 Planning V2 hydrate 也必须通过 blocking worker 执行；它们可能碰到项目写锁，不能在 Tauri 窗口线程同步等待。
项目打开链路的目录检查、manifest 读取和 项目 revision 读取也必须通过 blocking worker 执行；它们可能碰到项目写锁，不能在 Tauri 窗口线程同步等待。Planning V2 hydrate 已随旧策划 Runtime 删除，不再属于现役打开链路。
DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking worker 中执行权限校验、JSONL 历史解析和消息投影，不能因为它只读取一份项目历史就保留同步 Tauri command。
@@ -1173,7 +1211,7 @@ game-project/
- 聊天输入 `/export` 会生成待确认的 `project.export_package` 内置命令，确认后只把 `game/**` 、`assets/**` 和 `exports/README.md` 打包到 `exports/playtest-package-*.zip` ；缺少 `exports/README.md` 时先按项目 manifest 生成最小试玩说明，已有文件原样保留。发布前若 `code-prototype` 未完成且没有运行中的预览，直接阻止发布，不触发用户项目构建；可运行原型完成后才允许按 `build` 脚本补齐产物。发布进度使用独立模态弹窗展示，遮罩覆盖整个工作区并阻止交互，不再使用聊天确认卡；导出前重新校验可玩入口，拒绝符号链接和越界路径，不把 `.agent/` 、`memory/` 、日志、trace、运行时配置或密钥文件写入 ZIP。
- 聊天输入 `/exports` 会只读执行 `project.export_list` ，列出当前项目 `exports/playtest-package-*.zip` 历史试玩包，并提供显示目录或继续 `/export` 的草稿；该命令不删除文件、不分享文件、不新增面板。
- 聊天输入 `/preview` 会生成待确认的 `preview.start` 内置命令，确认后启动只读本地 HTTP 预览并切换到客户端内运行视图；`/open-preview` 在本地项目已初始化后生成待确认的 `preview.open` ，只激活当前授权项目对应的 `127.0.0.1` 运行容器；`/preview-status` 只查询当前授权项目的本地 HTTP 预览并写入 `preview.status` 命令日志；`/preview-stop` 只停止当前项目预览，不展示或停止其它项目遗留的全局预览。
- 聊天输入 `/memory [short|long|blackboard]` 读取 短期、长期或 黑板记忆； `/remember [short|long|blackboard] 内容` 生成待确认的 `memory.write` 并追加短期、长期或黑板记忆，未写 scope 时默认追加长期记忆；主窗口“记到黑板”“覆盖黑板”“清空黑板”只填入 `/remember blackboard ` 、 `/memory-set blackboard ` 或 `/forget-memory blackboard` 草稿，仍由用户补内容并走聊天确认； `/memory-set [short|long|blackboard] 内容` 生成待确认的 `memory.write` 并覆盖保存对应记忆； `/forget-memory [short|long|blackboard]` 生成待确认的 `memory.delete`
- 短期、长期和 黑板记忆由现役 Runtime 工具与原生读写入口维护；记忆斜杠命令已按 2026-09-22 退役 ADR 清理，未接入正式调用的本地记忆删除 helper 及专属测试一并移除，不删除用户现存记忆文件 。
- 聊天输入 `/canvas 画板项目ID` 会生成待确认的 `canvas.project_open` ，只打开本机 Genarrative 编辑器里的指定画板项目，不开放任意 URL；确认后聊天先反馈正在打开，再回写真实打开 URL。画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
- 聊天输入 `/sync-canvas-project 画板项目ID` 会生成待确认的 `canvas.project_sync` ，通过 External Editor API 把该画板项目资源下载到 `assets/canvas-sync/` 并登记为画板来源资产；画板项目 ID 为空或包含控制字符时在聊天侧直接拒绝。
- 聊天输入 `/generate-art 提示词` 会生成待确认的 `canvas.asset_generate` ，通过 External Editor API 生成首版美术素材并写入 `assets/canvas-generated/` ；提示词为空时在聊天侧直接拒绝。
@@ -1192,7 +1230,7 @@ game-project/
- `check:native-shells` 会运行 `ai-game-creator-shell:check` 和 `ai-game-creator-shell:build -- --no-bundle` ，并静态检查 release 与 debug 启动都只登记 `client / index.html` 这一个默认窗口、禁止 Tauri setup 自动打开 developer 窗口、开发面板必须挂在 `devMode` 分支内，正式用户 App 的运行容器只接受 `http://127.0.0.1:*` ， `frame-src` ，Tauri 预览激活命令不得调用 opener，用户主流程不得调用旧工作区窗口切换 command。
- 共享契约提供 `GAME_CREATION_AGENT_CAPABILITIES` 和内置命令权限枚举；开发模式会展示能力列表。
- 共享契约提供 manifest task schema 和 ready-task 选择器，用于记录任务拆分、专业组、角色模板、依赖、产物、验收条件和当前可执行任务。
- 开发模式可读取、保存、删除短期记忆和长期记忆文件；正式用户界面不提供记忆管理入口，短期 / 长期 / 黑板记忆只由 `project-supervisor` 运行期的记忆工具在授权项目内读写。
- 原生入口保留短期、长期和黑板记忆的读取与保存；正式用户界面不提供记忆管理入口， 运行期的记忆工具只 在授权项目内读写。项目命令权限 id 的去留与具体 helper 分开判断。
- 共享契约提供 `GAME_CREATION_APP_LIMITED_RUN_COMMANDS` ；当前真实命令为 `game.static_smoke` ，用于检查 `game/index.html` 的可玩原型门槛并写入 `.agent/logs/command.log` 。
- 后台 Agent 的项目 revision 以 `.agent/runtime/project-revision.json` 为唯一事实源，per-run 验证门禁以 `.agent/runtime/verification/<agentId>/<runId>.json` 为事实源。每次 `file.write` 、`file.patch` 、`file.delete` 或 `project.restore` 都必须在实际修改前保守推进 revision，并永久记住当前 run 的 `requiresVerification=true` ；失败或崩溃不回退。只有成功且绑定当前 revision 的 `project.verify` 或 `command.run_limited / game.static_smoke` 才能放行空 actions；未修改项目的只读任务不强制验证，但最终回复仍必须绑定请求开始时的 `responseRevision` 。per-run context bundle 使用 v2， `nextLoopIndex` 续跑，revision 数值或成功验证输出中的动态时间戳不能绕过 context stall。
- `.agent/manifest.json` 会记录当前 `preview` 状态和 `commandRuns` 受限命令运行结果，作为本地产物索引的最小真相源。
@@ -1391,10 +1429,11 @@ game-project/
- 普通项目对话由一个 project-bound Codex app-server thread 执行。客户端系统提示词包含最小工程合同、项目 prompts 和审核 Skill 索引；源码与 Skill 正文按任务需要读取。提示词、工具描述与 Skill 直接描述当前任务、输入和成功条件，细节按调用需要提供。
- 首页提供“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。每次首页提交自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 作为受限结构化首轮上下文传给同一 Codex thread。
- 2026-09-23 清理了未注册的 DirectHome 用户对话命令及旧附件 sidecar 渲染链；首页仍先创建项目再进入 DirectProject，不恢复无项目对话。自动项目命名和提示润色仍调用内部 `direct_game_creator_home_codex_chat` ，其 DirectHome 只读隔离通道与测试继续保留。附件作为 canonical `userItem.content` 中的 `agc_attachment_reference` 携带名称、媒体类型、大小、项目相对路径及状态，经现役 validation/wire 校验与投影；路径映射不等于灌入全文，也不按 GDD 特判。附件清洗与数量上限继续复用 `direct_codex_attachments.rs` ，旧 sidecar DTO、header、专属 prompt key 和测试不再是保留合同。
- `agc-skill-pack.v1` 包含完整游戏交付流程、项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影，以及 Unity/Godot 编辑器常用操作八项审核 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync` ，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文由 Codex 原生 Skill 机制按意图加载，一层引用只能经 `agc_read_skill_resource` 读取清单内 Markdown。引用路径按平台无关规则拒绝反斜杠、盘符、UNC、绝对路径和 `..` ，不能依赖当前宿主的 `std::path` 语义判断其它平台路径。
- DirectProject 连接客户端内置的 `agc_tools` STDIO MCP，并在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置。内置工具包括审核引用读取、图片生成、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search` 。内置 MCP 进程负责协议；真实浏览器、付费平台调用与受控搜索通过随机 loopback 地址回到客户端主进程，GUI 登录态、开发者 Key、项目路径、revision、operation 与幂等键由客户端持有并隔离于模型上下文。内置与用户启用的第三方 MCP 工具沿用 DirectProject 自动批准方式；付费资源工具由客户端绑定稳定回合身份、串行执行并优先恢复匹配账本。`llm.webSearchEnabled` 控制 DirectProject 的 AGC 受控搜索工具暴露与执行。原生工具与审批权限以下方“DirectProject Codex 完整访问覆盖”为准。
- 陶泥儿生成复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端使用当前 AGC 登录会话及账号路由，受控的 ExternalDeveloper 发布模式在客户端内部使用按服务器 origin 隔离的私有 Key。凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
- 自定义 LLM API Key 路由在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理使用请求自带的 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，按实际 API Provider 响应判断请求结果。
- 自定义 LLM API Key 路由在 DirectProject 及内部 DirectHome 辅助调用中 经 loopback `/responses` 流式代理转发。代理使用请求自带的 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，按实际 API Provider 响应判断请求结果。
- 2026-08-12 计划拒绝恢复：结构化 `runtime.plan_update` 被 Runtime 拒绝后，下一轮 Provider 请求按请求级目录收窄到实际项目 mutation 与 `respond_to_user` （已进入协作编排的 Supervisor 保留 `agent.delegate / agent.run_status` ），并明确禁止再次规划、读取、搜索或验证；后续已有真实 mutation observation 后解除临时目录，不改变持久 executable policy。
@@ -1446,7 +1485,7 @@ game-project/
- 恢复扫描必须把 `resetting` 、`compensating` 和仍带替换锚点的 `in-progress` 识别为可恢复状态，并在 Direct app-server 启动前持有同一专用执行锁完成阶段清理、补偿和中性化。补偿只恢复旧文件并清除本地 replacement CAS 锚点；已 `prepared / accepted` 的阶段账本、原 `Idempotency-Key` 与 `operationId` 必须保留，同冻结意图续跑复用原请求身份，未知账本在文件 mutation 前失败关闭。冻结意图一致但进程 invocation 已变化时允许安全接管本轮；`completed` 则以外层原始 `clientTurnId` 为权威，忽略模型重采样 brief 并等值回放。客户端必须在启动 Direct Codex 前幂等落盘原始 User 消息与稳定回合 ID；最终 assistant 回复必须在 Tauri 成功返回和 `completed` 事件前，以同一稳定回合 ID 幂等写入项目主对话，重启后项目对话只续跑真正未回答的原始回合，不能生成新身份或重复应用已完成代码修改。
- workflow 在调用严格图集事务前必须先持久化 `strictSpritesheetPending` ，并冻结严格事务覆盖的九项旧合同身份：`.agent/manifest.json` 中受管 asset identity、客户端私有回执、公开 `assets/manifest.art.json` 、主图集、四张 canonical 切片和公开切片清单；旧路径允许按真实状态冻结为缺失。异步 Provider 返回终态后，客户端必须先把脱敏且可恢复的完成结果绑定到原 retained stage ledger，再允许本地严格事务提交。恢复在同一项目写锁内完成底层严格事务对账与 workflow CAS；若九项新合同与当前规范图身份完整一致、规范图/背景图替换锚点属于本轮，且私有回执的 resource/asset/task identity 与本轮 retained spritesheet 完成结果一致，才保留整组新结果并补写 `completed` 。若九项仍逐项精确等于冻结的旧合同，严格合同判定、写入 `compensating` 、恢复规范图/背景图与登记、回读验证和清除锚点必须全部位于同一项目锁内；`compensating` 重启也必须重新验证旧合同。任一文件存在性、摘要、顶层 asset identity、retained result 或 CAS 处于第三种状态时进入本地 reconciliation，保留 workflow、阶段账本和文件现场，禁止制造新旧混合包或重新付费。恢复若只能证明完整新合同而无法重建中断前尚未持久化的阶段告警，完成结果必须追加明确恢复告警，不能用空 warning 集合伪装为原阶段没有告警。
- 工具完成结果同时返回主包 `assetPaths` 、实际成功持久化的 `slicePaths` 、安全身份投影 `resources` ，并把普通 `warnings` 与 `sliceWarnings` 分开。每张本地切片都以真实 Canvas `resourceId / assetObjectId / taskId` 和源图集 `sourceResourceId` 登记为顶层 manifest asset；同路径替换保留本地 asset ID。严格图集事务继续覆盖主图、四张 canonical 切片、公开切片清单、私有回执和 `.agent/manifest.json` ，失败时整组恢复。旧项目缺顶层切片登记时只能由客户端私有回执授权补登记；可编辑的公开切片清单不能单独成为 `.agent` Canvas 身份来源。
- `regenerate` 授权只取当前请求中最新一条原始 `role=User` 消息，并绑定外层稳定 `clientTurnId` ；引号或代码中的按钮文案/示例、历史消息、模型自行填写的 `mode` 、MCP 自动批准和缺失 clientTurnId 均不能形成付费替换授权。授权判定先对完整原文做 Unicode NFKC 与常见撇号规范化，随后整串必须完整匹配审核过的独立立即执行指令，只允许句号/感叹号收尾；不得剥离引号、方括号或代码片段，动作前后也不得携带 brief、条件、否定、选择、确认、费用、延迟或任意其它文本。复杂风格需求必须先在非付费消息中描述，再由下一条独立“请重新生成美术”确认消息签发授权；不能靠开放式 deny 词表猜测当前付费同意。工具桥只保留授权判定和摘要，不保存或回传用户原文 。同一进程重复水合相同 `clientTurnId` 时，“回合仍在运行”只属于瞬时占用状态，前端不得以稳定 assistant messageId 将其写成终态；原执行的成功回复仍由 Tauri 在返回前持久化。DirectProject app-server 的 cwd、sandbox writable root 和文件变更批准根统一为用户选择的整个项目根； canonical 项目根的 原生 OS 路径字节与权威 manifest `projectId` 通过域标签和各自 长度前缀编码后共同进入 Direct 连接池和 thread 身份，稳定符号链接改指其它项目、同路径重建项目、不同非 UTF-8 路径或内嵌 NUL 的项目 ID 都不能复用旧连接。 `assets/` 、 `game/` 与其它项目文件可写， `.agent/` 、 `.git/` 、密钥文件和 Runtime 控制面由项目文件层拒绝，网络关闭，命令执行、MCP 扩权和额外权限申请一律拒绝。受控 `agc_tools` 子进程从同一项目根 cwd 经相同权限校验反查 canonical 项目根供客户端内部桥使用，不能把该根加入其它 Codex writable roots 。`resources` 只返回本地 asset/path/kind/media type、Canvas project/resource/asset/task ID 与 reference resource IDs，不返回 prompt、model、provider route、绝对路径、URL、Token、Cookie 或 API Key。客户端付费资源生成（图片、视频、角色动画、音效、背景音乐）统一调用站内 `/api/editor/...` 路由并复用平台登录态，不走 External v1；
- `regenerate` 的模式选择遵循 2026-09-03 MCP 能力边界：Codex 根据当前用户请求，经审核后的工具显式选择 `mode=regenerate` ；客户端不再通过自然语言关键词、Unicode 归一化、否定词表或独立确认句式判断高层业务意图。工具桥继续校验项目权限，将操作绑定活动客户端回合与稳定 `clientTurnId` 、冻结首次 `brief` 摘要，串行处理同一重生成动作，并在同回合等值重试时返回已完成结果；缺少活动回合或摘要冲突仍拒绝。账号、计费、幂等账本、锁、付费结果未知与恢复合同继续有效。2026-09-23 已删除无调用的旧文本判断函数，不恢复该旧语义门禁 。同一进程重复水合相同 `clientTurnId` 时，“回合仍在运行”只属于瞬时占用状态，前端不得以稳定 assistant messageId 将其写成终态；原执行的成功回复仍由 Tauri 在返回前持久化。DirectProject 的 cwd 和 AGC 项目身份根使用用户选择的 canonical 项目根；其 原生 OS 路径字节与权威 manifest `projectId` 通过域标签和独立 长度前缀编码后绑定 连接池及 thread 身份，项目被替换时不能复用旧连接。进程 sandbox 与文件、命令、权限请求的批准规则按本文件后续“DirectProject Codex 完整访问覆盖”；客户端 MCP 仍保持项目绑定和业务权限校验 。`resources` 只返回本地 asset/path/kind/media type、Canvas project/resource/asset/task ID 与 reference resource IDs，不返回 prompt、model、provider route、绝对路径、URL、Token、Cookie 或 API Key。客户端付费资源生成（图片、视频、角色动画、音效、背景音乐）统一调用站内 `/api/editor/...` 路由并复用平台登录态，不走 External v1；
- 成功响应中的 `warnings / sliceWarnings` 与错误响应采用同一脱敏边界：逐条移除宿主绝对路径、凭据与 URL，并设置固定长度上限；非阻断告警不成为绕开错误分支隐私保护的旁路。
- Direct 同进程重复水合若收到“同一 stable turn 仍在运行”，必须释放当前 App 实例的恢复 claim；该结果不落 assistant 终态，后续显式刷新对话可按原 `clientTurnId` 再次读取已落盘回复或续跑，不要求重载整个 WebView，也不启动无界自动轮询。
- 对话恢复从新到旧扫描全部合法 Direct User 回合；较新的 User 已有稳定 assistant 时必须继续寻找更早未回答回合，不能提前结束扫描。普通成功回复或普通错误回复若终态 assistant 持久化失败，同样必须释放当前 App 实例的恢复 claim，使后续显式重新加载对话时能以原稳定 `clientTurnId` 重试；claim 只表示当前实例内正在恢复，不能成为磁盘终态的替代品。
@@ -1528,7 +1567,7 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
- `agc_write_file` 是用户直接触发、失败即整轮无法落盘的项目写入通道，原先却用零等待 `acquire_project_write_lock` ：任何重叠都在 24-42ms 内被判成“项目正在被其他写操作占用”，而 `file.write / file.patch / file.delete` 等入口用的是约 10 秒有界等待。现统一为 `acquire_game_creator_agent_runtime_project_write_lock_with_wait` ：短暂重叠排队等成功，只有预算耗尽才报出带持锁方身份的错误；同一轮并行写多个文件按同一把锁串行。这是 2026-07-22 同一形状修复在 Direct 通道上的补齐，与 2026-08-13 一节“这些结果统一投影为争用并进入既有有界等待”的口径一致。**失败耗时是判据**：几十毫秒说明该入口没等，不是锁没释放。
- 这条等待是**同步轮询**（2_000 × 5ms，最多约 10 秒），而 `handle_direct_tool_bridge` 是 async handler：直接在 handler 里跑完整条写路径会占住一个 tokio worker，争用窗口内同一轮并行写多个文件时会有多个 worker 被占，而这条 bridge 与只读端点、UI 命令共享同一个 runtime——Issue #318 现场“只读工具全部正常”这条诊断特征会在争用窗口内失效。因此写路径经 `bridge_write_file_in_blocking_pool` 走 `tokio::task::spawn_blocking` （仓库既有模式，如 `codex_app_server.rs` 的 DirectProject 历史落盘），等待语义与错误文案不变；定向用例用默认 `current_thread` runtime 加心跳任务锁住“等待期间 runtime 仍在推进”。
- 争用错误必须带持锁方身份才可行动：`项目正在被其他写操作占用：<锁路径>（持锁方 commandId=<命令> pid=<进程> createdAt=<创建时间> ownerIsSelf=<是否本进程>） 。锁文件处于 delete-pending 或尚未写完时读不到身份，也必须显式表达成“不可读”，不得默认成“没有持锁方”。前缀逐字不变： `project_gates.rs` 、 `provider_recovery.rs` 、 `planning_session_v2.rs` 、 `direct_runtime.rs` 和前端 `App.tsx` 都按它把争用识别成可等待的瞬时状态；这句话已是 `crate::project::PROJECT_WRITE_LOCK_CONTENTION_PREFIX` 单一真源，四个站点不再各自手写中文 。
- 争用错误必须带持锁方身份才可行动：`项目正在被其他写操作占用：<锁路径>（持锁方 commandId=<命令> pid=<进程> createdAt=<创建时间> ownerIsSelf=<是否本进程>） 。锁文件处于 delete-pending 或尚未写完时读不到身份，也必须显式表达成“不可读”，不得默认成“没有持锁方”。现役调用方通过 `crate::project::PROJECT_WRITE_LOCK_CONTENTION_PREFIX` 单一真源识别争用，不各自手写中文；已删除的 `planning_session_v2.rs` 不再列为现役调用点 。
- `create_new` 的失败必须分三类处置，不能再共用一句文案：可重试（目标已存在、Windows `sharing violation(32)` / `lock violation(33)` / `ACCESS_DENIED(5)` ）进入有界等待；明确判定不是争用的权限 / ACL 拒绝（Unix `EACCES` ）失败关闭且文案不含争用前缀；其它 I/O 错误原样上报。**重试性只能由错误码决定，不能用 `path.exists()` 这类一次 metadata 观察决定**：目标被删除时目录项先消失、删除挂起随后才结束，`create_new` 会在这个拆链窗口里返回 `ACCESS_DENIED(5)` ，而 `exists()` 往往已经报 false（本机实测 6 万次建锁 / 删锁竞争里 396-538 例命中该组合）。按“目标不存在”当场判成权限拒绝，等待层就会立刻失败关闭——正是本次要消灭的“毫秒级直接失败”，只是换成更误导的 ACL 文案。平台判据以 `project_write_lock_open_failure_for(platform, error)` 保留、平台由参数传入而不是 `#[cfg]` ： ，
- Windows 上真实 ACL 拒绝与删除拆链窗口在错误码上不可区分，所以终态改判放到**等待预算耗尽之后**：`ProjectWriteLockFailure::exhausted_projection(waited)` 只在“真的等过预算 + 目标此刻仍不存在 + 错误码是 `ACCESS_DENIED(5)` ”三个条件同时成立时才投影成权限拒绝；单次试探（`max_attempts == 1` ，例如 hydrate 的 `try_acquire_...` ）没有等待证据，保持争用语义。代价是 Windows 上真实 ACL 拒绝会先等满等待窗口（约 10 秒）才报权限错误；Unix 的 `EACCES` 立即判定、不等待。
- 重试与否改由**类型**决定，不再解析错误文案：`acquire_project_write_lock_failure` 返回 `ProjectWriteLockFailure::{Retryable, Terminal}` ，有界等待按 `is_retryable()` 分流，`acquire_project_write_lock` 只是它的文案包装。零等待入口前缀不变，只在“错误码不可区分且目标此刻不存在”时补一句“可能是删除挂起、删除拆链窗口或权限 / ACL 拒绝”，把两种处置都交给调用方，而不是替它猜一个。
