细化 Direct 租约重构规范与实施计划

补充操作准入、失败隔离与回合清理的目标行为
更新重构里程碑及合同工作的范围边界
新增租约简化实施顺序、验收场景与回滚计划

docs/project-memory/plans/【实施计划】Direct操作控制与租约简化-2026-10-03.md

@@ -0,0 +1,102 @@
+# 【实施计划】Direct 操作控制与租约简化
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 0.1 |
+| Status | proposed（评审草案，未开始实现） |
+| Date | 2026-10-03 |
+| Milestone | [Direct 合同与租约机制重构：租约切片](./【里程碑】Direct合同与租约机制重构-2026-10-03.md) |
+| Parent Spec | [Direct 操作控制简化提案](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#direct-操作控制简化提案2026-10-03待实现) |
+
+## 交付与优先级
+
+交付结果：普通操作由回合活动状态、时间、并发和原有权限决定能否开始，成功或失败如实返回 Agent；任何单次普通失败不再要求整轮排空或开启返修批次。
+
+必须项是移除全局排空和合同准入耦合，并验证结束后的控制边界。风险项是原生后台进程归属、迟到写入、重复结算与远端付费结果不确定。诊断 UI 与新增可观测性不作为本切片工作。
+
+本次仅规划一个可独立验收的租约切片。实施时每个步骤完成即检查对应边界，失败先定位本步骤，不扩展为合同或调度器重写；定向验证通过后做一次整体验收，额外发现仅在影响下列验收判据时扩大范围。
+
+## 修改顺序与边界
+
+### 1. 收敛操作状态与准入
+
+涉及 `agent/direct_execution.rs`。
+
+- 将操作跟踪保留为并发占用、开始时间、回合归属及取消所需的最小记录；移除具有返修批次和全局排空语义的租约模型。
+- 准入只核对原回合是否仍活动、预算、容量和调用自身限制；删除 contract-required 操作门禁、Draining 状态与 used_passes 返修控制。
+- 操作终结只结算一次；成功、失败、取消、异常均不能泄漏容量或重复计时。取消请求发出不等于本地进程已退出，尚在运行的自有工作仍须跟踪至退出或明确报告控制失败。
+- 保留累计执行时长和墙钟上限原口径，不增加 per-operation 租约期限。普通操作错误与宿主无法保持控制的错误分开处理。
+
+检查点：无合同可准入；失败不影响其它在途操作及后续操作；容量和时间限制仍有效。
+
+### 2. 接通现有工具与原生执行器
+
+涉及 `agent/direct_tool_bridge.rs`、`agent/direct_patch.rs`、`agent/direct_validation.rs`、`agent/codex_app_server/execution.rs`。
+
+- 内置、原生及第三方调用复用同一套简化控制；保留已有执行前审批、调用身份绑定与内外层不重复计时。
+- 工具真实成功/失败返回 Agent，不新增“先修复/释放租约才能继续”的反馈。验证失败返回失败，输入漂移使该证据不可复用，不切换全局阶段。
+- 原生命令已返回但仍有 processId 的情况继续按真实进程生命周期跟踪，不能提前释放归属。
+- 保留 MCP 并行受理与图片容量限制；不改工具等待结果的协议和 Codex 下一模型步的调度。
+
+检查点：通过受控执行器夹具重现“长命令在途 + 图片失败”，随后无关写入和命令仍可准入。这证明宿主不阻塞，不宣称模型能在普通图片调用等待中开始新的推理步骤。
+
+### 3. 保住关闭、写入与付费边界
+
+涉及 `agent/direct_paid_submission.rs`、执行器 shutdown/drain、原写入许可及项目事务提交调用点。
+
+- 回合正常关闭、用户取消或时间耗尽后，拒绝新调用并取消宿主拥有的工作，复用既有进程组 / Windows Job 清理与退出证明。保留结束时清理在途操作的行为，删除普通失败触发的全局 Draining 门禁。
+- 排队后的写入、原生操作审批及每次新增付费 POST 仍核验原回合；不能从“当前回合”重新取得新权限。关闭与准入/提交之间保留必要短临界区。
+- 远端已提交任务保留其 operation ID、幂等和对账；未知结果只限制对应资源操作，不阻断整轮无关工作。不要用删除本地记录表示远端已取消。
+- 控制状态持久化失败、执行器断连或无法确认自有进程退出仍报告真实控制问题，不伪装为可继续的普通工具错误。
+
+检查点：关闭后零新增 POST/执行；锁等待后的迟到写入失败；取消不盲目重发付费任务；实际进程退出有证据。
+
+### 4. 清理耦合、提示与持久状态
+
+涉及 `agent/direct_delivery.rs`、`agent/direct_runtime/mod.rs`、`prompts/runtime/texts/direct.json` 和按引用搜索确认的状态消费者。
+
+- 移除 delivery/validation 状态、报告和提示中的执行批次计数及“普通错误必须停止整轮”等旧语义；`maxRuns` 暂保留交付复核次数用途，不扩大为配置重设计。
+- 删除“操作前必须有合同”的提示前置条件；完整合同触发提示、artifact/command 移除、视觉/玩法设计留给合同工作。现有合同的收尾评估仍可调用简化后的关闭与进程清理。
+- 保留原回合预算及必要退出/恢复状态；逐项核对旧账本读取路径。旧活动记录不能恢复成新许可，已结束记录不重放；未结束记录确认执行器退出后按中断事实处理，同回合预算不清零，资源恢复沿用原 operation。
+- 只为确有跨版本读取需求的字段保留最小兼容，删除退役状态及专属测试，不建立双套运行模型。
+
+检查点：状态消费者不再依赖 used_passes/Draining；同回合不刷新预算，新回合不承接旧权限；合同未讨论部分不变。
+
+## 验证计划
+
+| 场景 | 必须证明 |
+| --- | --- |
+| 图片/命令连续失败超过旧 maxRuns | Agent 得到错误；剩余时间足够时仍可执行无关工作 |
+| 长命令在途且图片失败 | 无关文件写入、新命令不被全局排空拒绝 |
+| 容量满、成功、失败、取消、异常、重复完成通知 | 上限有效、结算一次、无容量泄漏 |
+| 验证失败与验证期间源码变化 | 证据如实失败/失效，无全局副作用停顿 |
+| 取消、正常结束、两类时间预算耗尽 | 新调用被拒绝，自有进程退出得到核实 |
+| 等锁/等容量后发生关闭，旧回合结果迟到 | 无新增付费提交、无借用新回合的文件写入 |
+| 远端已受理后失败或连接断开 | 保留同一 operation 对账，无盲目重复付费，无无关操作门禁 |
+| 原账本恢复、同回合重试、新用户回合 | 预算不重置，旧权限不复活，确认旧执行器退出后可开始新回合 |
+| 没有合同、已有合同、ExternalClient | 普通准入解耦，交付复核与独立客户端边界保持 |
+
+定向验证按实际修改选择以下过滤器；不得用真实付费生图作为默认自动化测试：
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_execution
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml codex_app_server::execution
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_paid_submission
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_tool_bridge
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_validation
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_delivery
+npm run check:doc-index
+npm run check:encoding
+git diff --check
+```
+
+必要 smoke 使用可控慢操作/失败响应与真实自有子进程，验证并行、取消和退出，不改模型循环。Windows Job 退出须由 Windows 环境提供证据；不可用时明确列为未验证项，Linux 夹具不替代该证明。
+
+## 风险与回滚
+
+- 移除计数和状态时容易遗漏原生审批、交付封口或恢复分支，必须按引用逐一核对，不能仅修改工具桥。
+- 资源级结果不确定与执行器整体失控必须区分；前者不触发全局停止，后者仍需要结束无法控制的执行器。
+- 同步修改状态消费者、报告及相关提示，不留下运行时已经允许、提示仍命令 Agent 停止的矛盾。
+- 实现按上述步骤保留可回退提交。回滚前结束自有回合并确认进程退出，核对账本版本可读性；不得通过删账本或重发远端请求完成回滚。
+
+本计划尚未实施。完成后提交逐条证据，融合主规范与长期记忆，再清理临时计划；WIP PR 在验收前保持 WIP。

docs/project-memory/plans/【里程碑】Direct合同与租约机制重构-2026-10-03.md

@@ -2,15 +2,15 @@
 
 | 字段 | 值 |
 | --- | --- |
-| Version | 0.1 |
-| Status | draft（已确认租约简化方向；合同方案与实现计划待细化，未实现） |
+| Version | 0.2 |
+| Status | proposed（本次细化租约切片，待评审，未实现） |
 | Date | 2026-10-03 |
-| Parent Spec | [AI 游戏创作智能体 App 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#宿主验收与执行许可合同)（现行实现依据，重构前须同步更新） |
+| Parent Spec | [AI 游戏创作智能体 App 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#direct-操作控制简化提案2026-10-03待实现) |
 | 关联问题 | #518、#529 |
 
 ## 本次交付与范围
 
-建立合同与租约重构分支及草稿 PR，记录已确认方向，供后续规范和实现使用。本次仅提交工作范围文档，不修改运行时行为，不代表现行主规范已经变更或问题已修复。
+在现有 WIP PR #608 内规划租约重构：将普通操作控制收敛为回合、时间、并发及既有权限检查，消除单次操作失败造成的全局停顿。本次只交付规范与计划，不修改运行时行为。验收以失败操作不阻塞无关工作、关闭后不能新增副作用为核心。
 
 优先顺序：必须项为明确操作失败与回合控制的边界；风险项为取消、并发、旧回合归属及远端结果不确定；可选项为诊断呈现，按实现需要再决定。第一个检查点是完成主规范和单里程碑实现计划，当前不进入业务代码实现。
 
@@ -24,21 +24,27 @@
 - 远端付费任务的 operation ID、幂等和结果核对继续由资源操作自身的生命周期负责；客户端停止不证明远端任务取消，不因新回合自动重复提交不确定请求。这些约束不构成阻断整轮无关工作的理由。
 - 不通过增加租约诊断、自动到期或“释放租约”工具来保留当前全局门禁模型。
 
-## 尚未确定的合同边界
+## 合同工作的边界
 
-已识别 artifact/command 验收与 Agent 自身读取、执行结果判断的重叠，但是否保留某些产品场景的强制交付检查、何时触发，以及如何调整相关工具与提示词，尚未最终确定。此前讨论过可选合同方向，不将其记为已经确认的完整方案。
+已确认后续提示 Agent 在用户要求制作、完成或交付游戏时创建合同，由 Agent 理解用户意图，宿主不按关键词或未交付脚手架自动要求登记；artifact/command 验收门禁将移除，视觉/玩法继续讨论。这些合同调整不纳入本次租约实现，唯一交叉项是解除普通操作的合同存在性门禁及同步清除与之矛盾的准入提示。
 
-当前 maxRuns 同时关联执行批次和交付复核次数；移除返修批次约束后如何处理交付复核、既有配置及持久化账本，须在实现前明确。时间预算的具体数值与计时方式本次不改。
+本切片移除执行/返修批次，`maxRuns` 暂仅保留既有交付复核次数用途；交付复核不影响工具准入。时间预算数值和计时方式保持不变。保留回合预算防重置与必要恢复信息，旧活动租约不能迁移成新执行权限；未确认旧执行器退出时不能开启冲突执行。
 
-## 后续验收目标（待主规范细化）
+不改 Codex 模型循环、工具调度、MCP 返回协议，不新增图片 start/status/wait 工具或后台 Agent；保留现有并行调用能力与资源事务锁。不新增超时自动释放租约、续租或手动释放租约工具。
+
+## 租约切片验收标准
 
 - [ ] 图片生成失败后，Agent 收到真实错误；无关文件编辑和命令不因全局排空被拒绝。
 - [ ] 一条长命令与失败图片请求同时存在时，不复现 #529 的全局拦写；长命令仍受并发容量、取消和时间控制。
 - [ ] 并发超过上限时保持有界；成功、失败、取消及异常路径正确释放槽位。
 - [ ] 回合结束或时间耗尽后零新增调用，已拥有的本地进程正确回收；迟到操作不越过原回合写入边界。
 - [ ] 新用户消息可以在旧执行器正确退出后开启新回合；旧的不确定远端操作不被盲目重放。
-- [ ] 合同的创建、验收与普通操作准入的最终关系先写入主规范，再按定向回归及真实执行器夹具验证。
+- [ ] 无合同也能通过普通操作准入；既有权限、路径和付费约束仍生效。
+- [ ] 连续操作失败超过原 maxRuns 不阻止继续工作；交付复核次数不被操作成功或失败消耗。
+- [ ] 验证失败或输入变化只影响对应结果与证据，不阻断无关操作。
+- [ ] 同回合重试、重启或旧账本读取不刷新时间预算、不恢复旧操作权限。
+- [ ] 保留原有并行调度，未引入图片后台接口或修改模型循环；合同视觉/玩法判据未变化。
 
 ## 后续工作入口
 
-主规范更新后再形成单里程碑实现计划。重点核对 Direct 执行状态、原生审批适配、工具桥、验证与交付、付费提交和原回合写入许可的真实调用链；已有数据与配置仅按实际恢复需求设计最小兼容。实现完成后把稳定结论融合回主规范与共享记忆并清理本临时文件。
+租约切片对应[实施计划草案](./【实施计划】Direct操作控制与租约简化-2026-10-03.md)，评审前不进入业务代码。实现完成后把稳定结论融合回主规范与共享记忆，清理临时计划；合同工作另行规划和验收。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -159,6 +159,19 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema
 - 原生执行控制的精确协议与许可持久化，在对应里程碑评审后落地；不得提前宣布这一项已完成。
 - 不修改 Provider 的 maxRetries；不减少引擎或任意代码执行的合法能力，不引入平行 Agent 框架，不改公开 API/数据库，不提交私密运行记录。
 
+### Direct 操作控制简化提案（2026-10-03，待实现）
+
+本节记录租约重构的目标行为；当前代码仍采用下节的执行租约与返修批次。实施范围与验收见[重构里程碑](../project-memory/plans/【里程碑】Direct合同与租约机制重构-2026-10-03.md)。本提案不改变 Codex 的工具调度、模型循环或图片工具的等待返回方式。
+
+- 普通操作开始前，宿主检查原回合是否活动、时间预算是否足够、并发容量是否可用，并执行原有权限、路径及资源约束。交付合同是否存在、前一个工具是否成功不构成普通操作的准入条件。
+- 操作成功、失败或取消后结算占用与用时，返回真实结果，由 Agent 决定后续操作。移除全局 Draining、执行/返修批次计数及对应重试门禁；验证输入变化只使相关证据失效，不使无关工作停顿。不新增租约到期续租、Agent 释放租约或独立后台任务接口。
+- 保留原时间预算数值与累计口径、并发上限及回合身份。回合关闭、取消或时间耗尽后拒绝新操作，取消自有在途工作并核实本地进程退出；等待资源锁后的写入及每次新增付费提交仍核验原回合权限。操作记录清除不能代替执行结束证明。
+- 普通工具失败和资源级结果不确定不终止整个回合；资源自身的幂等、operation ID、恢复及对账继续有效，不能因客户端取消而推断远端取消，也不能盲目重复付费。宿主控制状态损坏或无法确认自有执行器退出仍按实际控制失败处理。
+- 交付复核与操作准入分离。本次仅解除合同存在性的操作门禁；合同何时创建、验收项及视觉/玩法判据在合同工作中另行处理。`validation.maxRuns` 暂保留现有交付复核次数用途，不再用于执行/返修批次；时间配置不变。
+- 同回合重试或进程重启不刷新预算；仅保留预算、回合归属、必要退出记录和资源自身恢复所需的持久状态，不恢复旧租约为可执行权限。旧版本未结束状态须先确认旧执行器退出，不能通过直接删除账本解除控制。
+
+验收至少覆盖失败图片与长命令并存时无关写入成功、连续工具失败不触发返修次数限制、所有退出路径释放并发占用、关闭后零新增执行/付费提交、迟到写入被拒绝，以及远端不确定任务不重复提交。该提案尚无实现或运行时验收证据。
+
 ### 宿主验收与执行许可合同
 
 - 正式 GUI 和 CLI 的共同 Direct 回合入口建立宿主控制状态，绑定 canonical 项目路径、稳定 clientTurnId 和原始用户输入摘要；宿主私有目录保存权威账本并独占该回合，项目 `.agent` 仅允许保存展示副本。配置或项目侧文件被改写、工具切换、Provider 重试和进程重启不得刷新同一回合的预算。