回退Direct回合生命周期规范提交3dfb8056d
回退 3dfb8056d：删除新增的《Direct回合跨页面生命周期与运行中项目可见性》里程碑与实施计划两份文档 回退 3dfb8056d：移除 AGC 主规范中的 Direct 回合跨页面生命周期章节及其快照失败重试条款
This commit is contained in:
@@ -1,52 +0,0 @@
|
||||
# 【实施计划】Direct回合跨页面生命周期与运行中项目可见性-2026-09-15
|
||||
|
||||
Version: 1
|
||||
Status: in-progress
|
||||
Date: 2026-09-15
|
||||
Milestone: `【里程碑】Direct回合跨页面生命周期与运行中项目可见性-2026-09-15.md`
|
||||
|
||||
## 固定契约
|
||||
|
||||
只读快照命令（Tauri 本地命令，`src-tauri/src/agent/direct_runtime.rs`）：
|
||||
|
||||
- `list_game_creator_direct_active_turns() -> Vec<GameCreatorDirectActiveTurn>`
|
||||
- 字段（camelCase）：`projectPath`、`turnId`、`status`、`activity`（可空）、`startedAt`、`updatedAt`、`sequence`
|
||||
- `status` 取值集合与既有 Direct 回合事件一致：`accepted` / `running` / `streaming` / `finalizing` / `completed` / `failed`
|
||||
|
||||
身份锁与快照共用同一份进程内注册表；注册表条目在回合进入时写入 `startedAt`，在每次回合事件发射时更新 `status` / `activity` / `sequence` / `updatedAt`，在回合结束（guard drop）时移除。
|
||||
|
||||
## 代码边界
|
||||
|
||||
- `apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs`：注册表结构扩展、快照读写、新命令、Rust 定向测试
|
||||
- `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/entrypoints.rs`：事件发射时投影到注册表
|
||||
- `apps/ai-game-creator-shell/src-tauri/src/main.rs`：命令注册
|
||||
- `apps/ai-game-creator-shell/src/App.tsx`：项目打开时重连、忙碌态与进度恢复、面板挂载
|
||||
- 面板组件（新文件，落在既有 feature 目录下）+ 对应测试
|
||||
- `apps/ai-game-creator-shell/src/features/agent-runtime/model.ts` + 测试：报错归类修正
|
||||
|
||||
## 修改顺序
|
||||
|
||||
1. Rust：扩展活动回合注册表并暴露只读快照命令，配定向用例（进入 / 进度 / 终态移除 / 多项目并存）。
|
||||
2. 前端：抽出并按契约接入快照读取（失败最多重试 3 次，前两次失败第三次成功不报错；3 次全部失败才把失败原因告诉用户），实现"重新进入项目 → 恢复忙碌态与进度 → 以快照 sequence 续接 → 阻止并发提交"。
|
||||
3. 前端：在左上角空白区域挂载"正在运行的项目"面板，复用既有组件与设计 token。
|
||||
4. 报错归类：按审计结论修正会误导的映射，逐条加回归用例；真实权限拒绝保持原提示。快照重试 3 次的成功/失败两态各加一条用例。
|
||||
5. 文档：主规范与共享记忆同步；里程碑验收后删除临时计划文件。
|
||||
|
||||
## 验证命令
|
||||
|
||||
- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_taonier_active -- --test-threads=1`（名称按实际用例调整）
|
||||
- `npx vitest run apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts`
|
||||
- `npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`
|
||||
- 面板组件测试文件单独一条 vitest
|
||||
- 快照重试用例（2 次失败 1 次成功不报错、3 次失败报失败原因）
|
||||
- `npm --prefix apps/ai-game-creator-shell run typecheck`
|
||||
- `npm run check:encoding`、`git diff --check`
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- 快照命令暴露项目绝对路径给前端：与现有 `projectPath` 口径一致，不得额外泄露配置或 token；命令必须是只读、无副作用。
|
||||
- 续接基线 `sequence` 若取错，会让重新进入后的进度事件被丢弃或重复消费；取错时回滚"重连"部分，保留只读面板。
|
||||
- 忙碌态恢复不得与既有 `chatAgentBusy` 的失败清理互相覆盖；出现卡死忙碌态时优先回滚重连，不影响身份锁与后台回合本体。
|
||||
- 面板若在窄窗口挤压主内容，先按既有响应式约定隐藏面板，不改主布局。
|
||||
- 重试必须有界且串行：并发重试会放大 IPC 与注册表读取，也会让"第几次失败"失去唯一含义。
|
||||
- 报错归类修正若与既有断言冲突，先确认断言锁的是"正确行为"还是历史错误文案，再决定改断言还是改实现。
|
||||
@@ -1,34 +0,0 @@
|
||||
# 【里程碑】Direct回合跨页面生命周期与运行中项目可见性-2026-09-15
|
||||
|
||||
Version: 1
|
||||
Status: in-progress
|
||||
Date: 2026-09-15
|
||||
Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`「2026-09-15 Direct 回合跨页面生命周期与运行中项目可见性」
|
||||
|
||||
## 目标
|
||||
|
||||
离开项目界面不再等于"回合消失"：后台继续跑的 Direct 回合必须能被前端重新发现并续接进度，同一项目在回合结束前不允许再发起第二条付费回合；壳层左上角提供"正在运行的项目"面板，列出当前确有在跑回合的项目并可点击进入。
|
||||
|
||||
## 边界
|
||||
|
||||
- 只读投影：新增命令只读当前 GUI 进程内的活动回合注册表，不写项目文件、不新增持久化账本。
|
||||
- 不新增取消入口；不改变身份锁排他性、项目写锁语义、计费与幂等身份。
|
||||
- 不新增跨端契约（Tauri 本地命令，不进 `packages/shared` / `shared-contracts` / OpenAPI）。
|
||||
- 面板与重连共用同一份快照，不各自维护第二份"谁在跑"的真相。
|
||||
- 报错归类修正只处理"说明与真相无关"的情况，不放宽身份锁、不吞真实失败。
|
||||
- 读取活动回合快照失败时最多重试 3 次，重试次数固定，不做无限重试或并发放大；只有 3 次全部失败才把失败原因告诉用户。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 重新进入有在跑回合的项目后：界面进入"正在处理"、显示最近一次进度、以快照 `sequence` 续接后续事件；回合结束前提交第二条需求不会真正发起第二条付费回合。
|
||||
- 回合结束（completed / failed）后：忙碌态解除、可以再次发送；不重复追加助手消息。
|
||||
- 无在跑回合的项目：行为与今天一致（可正常发送，不出现额外提示或阻塞）。
|
||||
- 左上角面板：列出所有在跑项目，按 `startedAt` 升序，显示项目名（缺失时回退目录名）与状态/时长，点击进入对应项目；没有在跑回合时不渲染面板外壳。
|
||||
- 快照读取失败最多重试 3 次：前两次失败第三次成功时不出现用户可见失败；连续 3 次失败后才出现一次带失败原因的提示，且不阻断发送、不清空既有状态、不显示成业务失败或权限结论。
|
||||
- 已修的错误映射不回归：`direct-codex-turn-already-running:` 与历史同义中文正文都归一到"仍在处理这个项目的上一条需求"；真正的 `项目权限策略拒绝执行：<command>` 仍显示审批提示。
|
||||
|
||||
## 未决事项
|
||||
|
||||
- "离开页面即取消"仍是未采纳的另一种语义；本轮只实现后台继续。
|
||||
- 应用重启后的"未完成回合"恢复不在本里程碑范围（回合注册表是进程内状态）；若未来要求跨重启恢复，需要另立里程碑并定义持久化身份与对账合同。
|
||||
- 面板是否需要展示非 Direct（专业 Agent / 策划 Agent）运行中的项目，本轮不做；先把 Direct 回合这条事实链路做正确。
|
||||
@@ -1379,52 +1379,3 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
|
||||
## 2026-09-14 新游戏策划到真实美术接入的连续交付
|
||||
|
||||
DirectProject 在收到完整游戏策划或游戏制作请求后，必须把视觉素材作为同一交付链路处理：先读取当前项目已登记资源；策划案包含角色、对象、背景、特效、界面或其它视觉实体且现有资源不满足时，Codex 必须在同一游戏实现任务中调用审核的 `agc_tools` 生图或编辑工具，读取返回的资源身份与相对路径，把真实产物接入游戏源码，再构建并验证实际渲染。生成了素材但源码仍使用 emoji、CSS 形状或临时占位图替代策划要求的视觉元素，不能报告游戏完成。只有策划明确不需要视觉素材，或现有已登记素材完全满足需求时，才允许跳过生图；图片生成、处理、登记和接入不因用户没有重复输入“生图”而降级为可选建议。
|
||||
|
||||
## 2026-09-15 Direct 回合跨页面生命周期与运行中项目可见性
|
||||
|
||||
DirectProject 的陶泥儿智能创作回合属于**项目**，不属于页面。离开项目界面（切到首页或其它项目）不终止在跑的回合：回合继续持有身份锁、继续调用 Provider 与工具、继续写入项目。因此"界面里看不到进度"不等于"回合结束"，更不等于"权限被拒绝"。壳层必须让这条事实对用户可见、可续接、可等待。
|
||||
|
||||
### 目标
|
||||
|
||||
- 重新进入同一个项目时，前端必须得知"该项目有一轮 Direct 回合仍在跑"，恢复"正在处理"状态与最近一次进度，并阻止发起第二条付费回合。
|
||||
- 壳层左上角提供"正在运行的项目"面板：列出当前确有在跑 Direct 回合的项目（显示名 + 状态 + 已运行时长），可点击进入对应项目。
|
||||
- 流经 `projectRuntimeVisibleError` 的真实错误不得被投影成与真相无关的说明：回合仍在运行不能被说成权限/审批问题；项目写锁 ACL 拒绝不能被说成审批配置；写锁争用不能被吞成无信息的通用失败。
|
||||
|
||||
### 非目标
|
||||
|
||||
- 本轮不新增取消入口：离开页面即取消的语义不在范围内。
|
||||
- 不改变 Direct 回合的身份锁排他性、项目写锁语义、计费与幂等身份。
|
||||
- 不引入跨进程或持久化的回合账本：面板与重连都只基于当前 GUI 进程内的活动回合注册表；应用退出后不恢复"正在运行"显示。
|
||||
- 不新增跨端契约：新命令是 Tauri 本地命令，不进 `packages/shared` / `shared-contracts` / OpenAPI。
|
||||
|
||||
### 参与入口、状态与跨模块边界
|
||||
|
||||
- 回合身份由 Rust 的 Direct 回合身份锁持有，注册表键是 canonicalize 后的项目根；一个项目同时最多一条 Direct 回合。
|
||||
- 回合进度的事实源是 Direct 回合更新事件发射器（status / activity / sequence / updatedAt）。同一次发射必须同时投影到活动回合注册表，面板与重连读的是这份投影，不允许前端各自维护第二份"谁在跑"的真相。
|
||||
- 只读快照经单一命令下发给前端；前端只做表现与临时 UI 状态，不据此写业务状态、不据此改项目文件。
|
||||
- 终态（completed / failed）后回合离开注册表，面板对应行随之消失；本特性不提供历史运行记录。
|
||||
|
||||
### 行为合同
|
||||
|
||||
1. 活动回合快照字段固定为：`projectPath`、`projectName`、`turnId`、`status`（`accepted` / `running` / `streaming` / `finalizing` / `completed` / `failed`）、`activity`（可空）、`startedAt`、`updatedAt`、`sequence`，全部为毫秒级时间戳或稳定标识。`projectName` 在回合进入时从项目清单读取一次，读不到或为空时回退为项目目录名，读取失败不得阻断回合。
|
||||
2. 重新进入项目：快照命中该项目时，前端必须恢复"正在处理"状态与最近一次进度文案；必须以该回合的 `sequence` 作为事件续接基线，使后续进度继续生效；回合结束前不允许发起第二条 Direct 回合；回合结束不得重复追加助手消息（沿用既有回合幂等身份）。
|
||||
3. 快照未命中：按"当前没有在跑的回合"处理。读取失败按下面的重试合同处理，两者都不得阻断发送、不得清空既有状态、不得把查询失败显示成业务失败。
|
||||
4. 同一项目并发第二条回合仍由身份锁拒绝，前端按稳定前缀 `direct-codex-turn-already-running:` 收口为"仍在处理这个项目的上一条需求，请稍候"。
|
||||
5. 面板按 `startedAt` 升序展示，显示名直接用快照的 `projectName`（不在面板里另发起清单读取）；空列表时不渲染面板外壳，不留空白占位。
|
||||
6. 面板与重连都不得展示内部诊断（Provider 指纹、token、绝对路径以外的内部细节按既有项目路径展示口径处理）。
|
||||
|
||||
### 失败与边界
|
||||
|
||||
- 读取活动回合快照（含面板刷新）遇到错误时**最多重试 3 次**：同一查询、有界间隔，期间任意一次成功即按成功处理，不向用户显示失败；**3 次全部失败后**才把失败原因告诉用户。失败文案只说明"读取正在运行的项目失败"，不得改写成业务失败、权限或审批结论，也不得据此判定"没有在跑的回合"。重试次数固定为 3，不得无限重试、不得并发放大请求。
|
||||
- 回合在进行中时项目被删除或改名：面板行按快照里的项目路径展示，点击后按既有打开项目失败口径处理，不在面板内发明新文案。
|
||||
- 同一 GUI 进程里不同项目的回合互不影响；身份锁的跨进程排他语义不变。
|
||||
|
||||
### 验收标准与证据
|
||||
|
||||
- Rust 定向用例覆盖：进入后可从快照读到自己的项目与回合身份；进度更新反映 `status`/`activity`/`sequence`/`updatedAt`；终态后离开快照；多项目并存互不覆盖；既有身份锁排他与残留回收用例不变。
|
||||
- 前端模型层用例覆盖：`direct-codex-turn-already-running:` 与历史同义中文正文都归一到"仍在处理"，真正的 `项目权限策略拒绝执行：<command>` 仍保留审批提示。
|
||||
- 前端 App 级用例覆盖：重新进入有在跑回合的项目后处于忙碌态且无法提交第二条回合；回合结束后恢复可发送；无在跑回合的项目不受影响。
|
||||
- 面板用例覆盖：排序、显示名回退、空态不渲染、点击进入项目。
|
||||
- 重试用例覆盖：前两次失败、第三次成功时不产生用户可见失败；连续 3 次失败后出现一次带失败原因的提示，且不阻断发送、不清空既有状态。
|
||||
- 门禁：AGC typecheck、`appSurface` 全量、模型层定向 vitest、Rust 壳定向 `cargo test`、`npm run check:encoding`、`git diff --check`。
|
||||
- 真实 Provider 长回合与真实跨项目并发的运行时证据若未取得，必须在交付记录里显式列为未验证项。
|
||||
|
||||
Reference in New Issue
Block a user