合并 origin/master 到资源工作台 V3 分支：解 4 处冲突并保留两侧行为
- WorkspaceLauncher.tsx：保留本分支清单快照 CAS 拒收提示（manifestMergeNotice 提示条、data-manifest-merge-* 观察点、recoverRejectedManifestSnapshot「重新读取清单」）与 activeVersionId/onActiveVersionChange 版本口径，并入 master 的策划/游戏运行态切换（onMakeGame + switchToGameRuntime、suppressInitialGameTurn 抑制首轮、supervisor key 带 agentRuntimeMode、onSwitchToGameRuntime），planningStartMode 统一取 master 的派生值（上下文 startMode 为 planning 且未切到 game 运行时） - ProjectSupervisorView.tsx：props 同时保留本分支 versions/activeVersionId 与 master 的 designView/onDesignApprove/onDesignClarify/onDesignRetry，DesignAgentSurface 审批链路与本分支资源引用输入区并存；directCodex 输入区保留本分支 @ 引用按钮 + 模型选择 + 发送按钮控制条，发送按钮禁用条件并入 master 的 designView 审批待定口径，模型选择沿用 master 的「对话中可切换」口径 - styles.css：本分支追加的资源画布/输入区样式块与 master 追加的 .design-agent-reasoning 样式块都保留，并补上本分支最后一条规则的收尾大括号 - view/project-development/index.tsx：保留本分支的 image-editor 引用（ImageCanvasProjectAssetPickerDialog、ImageCanvasQuickEditPanelView、ImageCanvasSelectedLayerToolbarView、useImageCanvasFloatingOptionDismiss），去掉 master 对已退役 features/asset-canvas 的 import（本分支已由 resource-canvas 取代），保留 master 的 DesignWorkspacePanel 与 planningStartMode 策划工作台分支 - tests/workspaceLauncherManifestMerge.test.tsx：补 master 新引入的 get_design_agent_runtime_mode mock（返回 null，与 master 各套件同口径），拒收提示断言不变 - tests/appSurface/design-agent.suite.ts：审批待定禁用输入的断言改用本分支 Lexical 输入区的禁用口径（容器 data-disabled + editor.setEditable(false)），断言意图不变 - 验证：npm run typecheck 通过；apps/ai-game-creator-shell typecheck 通过；apps/ai-game-creator-shell/tests 96 个测试文件 1380 通过 4 跳过 0 失败；全仓 vitest 297 通过 2 失败（scripts 下两例为 Windows 权限语义导致的既有失败，相关文件与实现均未参与本次合并）；npm run check:encoding 与 git diff --check 通过
This commit is contained in:
@@ -38,7 +38,8 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
|
||||
|
||||
- `.agent/manifest.json` 的 `name` 仍是本地项目显示名唯一事实源；项目组页行尾更多菜单提供行内重命名，保存必须走 Tauri 受控命令、项目写锁、manifest 写锁与既有 ACL/权限校验。重命名只更新 manifest，不改变项目目录、`projectId`、项目类型、任务、资源、版本或远端同步状态；保存成功后当前项目上下文、窗口标题和最近项目检查结果必须回读新 manifest 并保持一致。
|
||||
- 项目名称统一 trim 后非空、最多 80 个字符且不得包含控制字符。空名称、超长、控制字符或未初始化项目必须失败关闭，原 manifest 保持可用；失败提示只展示安全错误，不泄露宿主路径之外的新内部信息。
|
||||
- 首页自动创建工作区前允许一次受限 LLM 名称提炼：输入只包含用户文本需求和附件元数据摘要，输出只允许一个简短中文项目名。Rust 侧统一规范化并在空值、控制字符、超长或多行格式时返回失败；前端把有效名称传给自动建项命令，失败时继续使用现有 `GameAgent 项目 {短ID}` 默认名并照常进入创作，不重试、不阻断、不额外消耗 Provider 请求。
|
||||
- 首页自动创建游戏或素材工作区前允许一次受限 LLM 名称提炼：输入只包含用户文本需求，输出只允许一个简短中文项目名。Rust 侧统一规范化并在空值、控制字符、超长或多行格式时返回失败；前端把有效名称传给自动建项命令，失败时继续使用现有 `GameAgent 项目 {短ID}` 默认名并照常进入创作，不重试、不阻断、不额外消耗 Provider 请求。
|
||||
- 首页“做方案”直接创建 `策划项目 {短ID}`，短 ID 沿用 Rust 生成的八位随机码，与项目目录的后缀一致。该入口不调用 LLM 命名；项目显示名持久化到 manifest，项目目录与身份规则沿用现有自动建项链路。
|
||||
- 手动“新建项目”继续默认使用所选文件夹名，不额外调用 LLM；项目创建后用户可通过项目组页重命名修正显示名。自动建项命令的自定义名称必须走同一校验，未提供名称时保持现有默认名，保证旧调用与失败回退路径不变。
|
||||
|
||||
## 2026-09-02 客户端会话恢复可观测性与超时兜底
|
||||
|
||||
@@ -0,0 +1,353 @@
|
||||
# 策划 Agent 生产迁移与工作区浏览方案
|
||||
|
||||
更新时间：2026-09-10
|
||||
状态：实施中
|
||||
|
||||
## 1. 目标
|
||||
|
||||
将 `local-scripts/design_agent_refactored` 中已经验证的自由协作型策划 Agent 迁移到生产 App。生产代码只提供可靠的运行基础设施，Agent 的工作方式以原型为准。
|
||||
|
||||
迁移后，策划 Agent 应能：
|
||||
|
||||
- 持续接收用户自然语言指示；
|
||||
- 自由读取、创建、写入、局部修改、删除和搜索工作区文件；
|
||||
- 按五个策划阶段推进，并在最后进入顾问态；
|
||||
- 按阶段注入提示词和明确要求的必读资源；
|
||||
- 通过澄清卡或普通文本向用户询问；
|
||||
- 通过工具提交阶段审批；
|
||||
- 由用户通过界面批准或拒绝阶段；
|
||||
- 让用户直接查看工作区中的文件；
|
||||
- 在 Provider 失败、进程重启或窗口恢复后继续工作。
|
||||
|
||||
## 2. 总体边界
|
||||
|
||||
生产侧复用 Provider、会话恢复、文件读写、审计和 UI 通信等基建，不复用现有立项策划 Agent 的行为协议。
|
||||
|
||||
原型行为是新的策划 Agent 契约。现有 `Planning V2` 只作为 Provider 调用、持久化和恢复实现的参考来源，不作为行为、提示词、产物或审批契约。
|
||||
|
||||
常驻提示词、阶段提示、速览卡结构说明、工具名称与参数、资源目录和注入映射以迁移时核对的原型文件为基线。迁移不顺便重写提示词，不增加模型输出内容门禁。旧需求文档中已明确舍弃的行为不恢复。
|
||||
|
||||
本方案描述生产迁移目标。当前已接入独立设计会话、自由工具循环、阶段审批命令和工作区浏览命令；生产入口对无旧 Planning V2 会话的策划项目切换到新设计 Agent，已有 V2 会话仍走原链路。旧 Planning V2 专用展示尚未清理。
|
||||
|
||||
## 3. 复用与丢弃清单
|
||||
|
||||
### 3.1 复用生产基建
|
||||
|
||||
| 基建 | 复用方式 |
|
||||
| --- | --- |
|
||||
| Provider 配置 | 使用生产配置解析，不读取原型 `.env`；沿用模型、API 类型、超时和重试配置 |
|
||||
| Responses 请求 | 复用 `platform_llm::LlmRunRequest` 及现有 Provider 适配层 |
|
||||
| 流式输出 | 复用生产流式事件和前端订阅机制 |
|
||||
| Provider 重试 | 复用瞬态错误识别、退避、最大重试次数和失败持久化 |
|
||||
| 会话持久化 | 复用项目级会话目录、原子写入和恢复入口，但使用新的设计会话数据结构 |
|
||||
| 并发保护 | 保留项目级短时写锁和会话活跃保护，防止文件或状态写入损坏 |
|
||||
| 文件底层能力 | 按原型工具契约筛选已有底层函数；绑定工作区，剥离旧业务门禁；缺少的目录删除、搜索等能力局部补齐 |
|
||||
| 审计与 debug | 复用正式动作记录和诊断采集；恢复或审计必需资料保存在 `.agent`，额外 debug 改为只写、可删除、不阻塞的旁路 |
|
||||
| Tauri 通信 | 复用命令注册、事件流、会话恢复通知和前端状态同步机制 |
|
||||
| 用户文件浏览 | 复用 Game Agent 的文件列表、文件读取和工作区刷新模式 |
|
||||
|
||||
### 3.2 不迁移生产行为
|
||||
|
||||
以下内容不应进入新的策划 Agent Runtime：
|
||||
|
||||
- `plan_ask_question` / `plan_submit_gdd` 固定协议；
|
||||
- `tool_choice=required`；
|
||||
- 每轮只能调用一个工具；
|
||||
- 三轮问询上限；
|
||||
- “先问询、再一次性出完整 GDD”；
|
||||
- 固定 GDD JSON schema 和字段校验；
|
||||
- 策划产物的内容质量、格式、指纹和结构完整性校验；
|
||||
- Fast GDD 投影及专用展示模型；
|
||||
- GDD 版本审批记录；
|
||||
- 旧 Planning V2 的“问询 → 完整 GDD → 审批终态”状态转移逻辑；
|
||||
- 旧 owner 产物限制和项目门禁；
|
||||
- 旧的“批准 / 修改 / 退回重做”审批语义；
|
||||
- 多 Agent、Wiki、知识库、外部搜索和自动任务编排。
|
||||
|
||||
路径穿越、绝对路径、控制目录访问和凭据泄露防护属于安全边界，可以保留；它们不能扩展成限制正常策划创作的业务门禁。
|
||||
|
||||
现有参考入口如下。复用对象是其中的可用函数和通信机制，不是整个模块：
|
||||
|
||||
| 代码入口 | 参考内容与注意点 |
|
||||
| --- | --- |
|
||||
| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/planning_session_v2.rs` | Provider 配置、请求、重试、会话恢复；丢弃问询计数策略、强制工具和输出纠错协议 |
|
||||
| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/file_ops.rs` | 读写、补丁和删除实现；不可原封不动继承 owner、产物和任务门禁 |
|
||||
| `apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs` | 路径解析、文件列出和读取、基础写入；内部绝对路径字段不得传给模型 |
|
||||
| `apps/ai-game-creator-shell/src/App.tsx` | Tauri 事件订阅、文件刷新、会话恢复入口；不把旧策划状态投影当作新契约 |
|
||||
| `apps/ai-game-creator-shell/src/features/project-workspace/ProjectWorkspaceChatPane.tsx` | Game Agent 文件列表与读取入口；新的文件浏览应直接打开文件视图，不往聊天中追加文件正文 |
|
||||
| `apps/ai-game-creator-shell/src/features/project-workspace/GddApprovalCard.tsx` | 仅参考现有面板和通用交互样式；不沿用结构化 GDD 展示及三按钮决定模型 |
|
||||
|
||||
不为此次迁移先建设通用 Agent 框架。已有函数能够直接使用就直接使用，只有确实需要拆除业务耦合时才做局部拆分。
|
||||
|
||||
## 4. 运行目录与状态
|
||||
|
||||
设计 Agent 使用独立的会话命名空间，避免与旧 Planning V2 数据互相解释：
|
||||
|
||||
```text
|
||||
项目运行目录/
|
||||
├─ .agent/
|
||||
│ └─ design-agent/
|
||||
│ ├─ session.json
|
||||
│ ├─ conversation.jsonl
|
||||
│ └─ 待交互请求与恢复记录
|
||||
├─ design_artifacts/
|
||||
│ └─ Agent 和用户共同查看的策划工作区
|
||||
└─ .debug/
|
||||
└─ 只写诊断资料
|
||||
```
|
||||
|
||||
以上为职责布局；恢复记录和审计沿用生产已有存储载体，不因目录示意另建平行账本。原型代码和固定资源包放在应用安装资源中，不放入 `design_artifacts`，也不为每个项目或回合复制一份。
|
||||
|
||||
设计会话至少保存：
|
||||
|
||||
- `sessionId`、`projectId`；
|
||||
- 当前阶段；
|
||||
- 已批准阶段；
|
||||
- 待审批阶段和审批请求身份；
|
||||
- 待澄清请求、问题与选项；
|
||||
- 各阶段必需产物的相对路径登记；
|
||||
- 当前回合和最近错误；
|
||||
- 恢复所需的 Provider 请求与结果关联信息。
|
||||
|
||||
Runtime 不维护文档版本号，不解析文档版本，不提供版本回退、比较或恢复。
|
||||
|
||||
会话/回合/工具调用身份用于生产恢复和重复请求处理，与 Agent 自行写在策划文档头部的版本号无关。
|
||||
|
||||
策划会话在创建时保存入口选择的 AGC 模型目录 ID（例如 `quality`、`fast`），同一会话后续回合沿用该 ID；客户端不保存或推断上游真实模型名。官方 `platform-llm` 直连 api-server 时携带 AGC 客户端标记，由 api-server 根据模型目录解析实际模型，不能在客户端硬编码某个上游模型替代目录选择。
|
||||
|
||||
## 5. Agent Runtime
|
||||
|
||||
新的 Runtime 应提供自由工具循环：
|
||||
|
||||
```text
|
||||
用户消息
|
||||
→ Provider
|
||||
→ Agent 文本或工具调用
|
||||
→ Runtime 执行工具
|
||||
→ 工具结果回到上下文
|
||||
→ Agent 继续工作
|
||||
```
|
||||
|
||||
不强制 Agent 调用工具，也不强制固定输出格式。普通文本输出且没有后续工具调用时结束本轮并等待用户；澄清卡等待用户回答；只有 `submit_phase_for_approval` 提交成功才能创建待审批请求，提交失败则将缺少的路径返回 Agent，允许它继续补齐。
|
||||
|
||||
一轮有多个工具调用时沿用正常工具执行循环。澄清或审批进入等待后，不继续请求 Provider，也不执行同批剩余文件操作；未执行调用明确记录为因等待用户而未执行，不伪造成功结果。恢复历史必须保持工具调用与结果配对，避免出现缺少 tool output 的协议错误。这属于协议与暂停处理，不引入同轮调用次数门禁。
|
||||
|
||||
迁移工具集合：
|
||||
|
||||
```text
|
||||
list_dir
|
||||
read_file
|
||||
write_file
|
||||
patch_file
|
||||
delete_path
|
||||
search_text
|
||||
list_resources
|
||||
read_resource
|
||||
ask_clarification
|
||||
submit_phase_for_approval
|
||||
get_workflow_status
|
||||
```
|
||||
|
||||
工具使用相对工作区路径。工具执行结果继续通过 Runtime 统一记录和展示，但不向 Agent 暴露宿主绝对路径。
|
||||
|
||||
`patch_file` 保留原型按唯一原文匹配修改的语义、换行归一化和缺文件错误。正常工作区写入与删除不逐次请求用户审批；阶段审批不能被复用为文件操作许可。
|
||||
|
||||
`list_resources` 一次返回完整逻辑分类、资源 ID、标题和简介；`read_resource` 按一个资源 ID 读取一个文件。资源描述不增加 `required=true/false` 分类，也不增加引导同轮多次调用的说明。
|
||||
|
||||
`get_workflow_status` 只返回阶段列表、当前阶段、已批准阶段和待审批阶段，不修改状态。保留原型的常驻提示约束：用户口头表示批准或要求进入下一阶段时，Agent 先查询实际阶段，不能凭普通文本自行切换。现有 `agent.run_status` 的任务/委派状态不能替代这个工具。
|
||||
|
||||
## 6. 阶段与提示词注入
|
||||
|
||||
阶段顺序固定为：
|
||||
|
||||
```text
|
||||
concept → top_design → architecture → systems → tdd → consultant
|
||||
```
|
||||
|
||||
进入阶段时，Runtime 重新生成当前阶段上下文，内容包括：
|
||||
|
||||
- 基础策划 Agent 提示词；
|
||||
- 当前阶段提示词；
|
||||
- 当前阶段明确要求注入的必读资源正文；
|
||||
- 当前阶段必需产物的相对路径；
|
||||
- 资源读取工具的可用性说明；
|
||||
- 工作流状态查询工具的可用性说明。
|
||||
|
||||
模板、范例、类型资料和没有明确要求自动注入的文档继续保持选读。必读资源缺失、为空或读取失败时，只记录诊断并继续请求 Provider，不阻断阶段推进。
|
||||
|
||||
根据当前原型 `resources/catalog.json`，自动注入清单为：
|
||||
|
||||
| 当前阶段 | 全文注入的资源 ID | 资源文件 |
|
||||
| --- | --- | --- |
|
||||
| 概念设计 | `skills.concept` | `skills/concept.md` |
|
||||
| 顶层设计 | `skills.top_design` | `skills/top_design.md` |
|
||||
| 系统架构 | `skills.architecture` | `skills/architecture.md` |
|
||||
| 系统文档 | `skills.systems` | `skills/systems.md` |
|
||||
| 技术文档 | `skills.tdd` | `skills/tdd.md` |
|
||||
| 顾问态 | 无新增必读资源 | 使用原型顾问态提示 |
|
||||
|
||||
登记表与正文随应用资源包发布；Runtime 按登记表读取，不把正文复制进实现代码，不在运行时自动拆章节。阶段切换时替换上一阶段上下文，不累计五份身份/Skill；历史对话和工作区文件保留。
|
||||
|
||||
各阶段登记为存在性检查对象的产物保持当前原型配置：
|
||||
|
||||
| 阶段 | 工作区相对路径 |
|
||||
| --- | --- |
|
||||
| 概念设计 | `project/00_concept/design.md`、`project/速览卡.md` |
|
||||
| 顶层设计 | `project/01_top_design/design.md` |
|
||||
| 系统架构 | `project/02_architecture/design.md` |
|
||||
| 系统文档 | 空清单；系统文档由 Agent 按架构自行创建，不新增 Runtime 系统登记、解析或自动建文件功能 |
|
||||
| 技术文档 | `project/04_tdd/01_技术实现.md`、`project/04_tdd/02_美术圣经.md`、`project/04_tdd/03_数据与配表.md`、`project/04_tdd/总册.md` |
|
||||
| 顾问态 | 不提交下一阶段审批 |
|
||||
|
||||
`systems: []` 是已确定的行为，不是迁移时需要补齐的缺口。`project/analysis.md`、`project/决策台账.md`、`project/dialog.md` 保持原型中的共享过程文件口径，不升级为新的审批必需项。速览卡保留原型结构提示，但 Runtime 与 UI 不解析其章节或内容字段。
|
||||
|
||||
进入下一阶段必须由用户批准触发。Runtime 推进后向 Agent 追加明确的用户行为语义，例如“用户已批准上一阶段，现在进入顶层设计阶段”，避免 Agent 误认为 Runtime 自行推进。
|
||||
|
||||
## 7. 审批与澄清交互
|
||||
|
||||
### 7.1 阶段审批
|
||||
|
||||
Agent 完成当前阶段后必须调用 `submit_phase_for_approval`。普通文本中的“批准”“确认”“进入下一阶段”等内容不改变 Runtime 阶段。
|
||||
|
||||
提交时 Runtime 只检查：
|
||||
|
||||
- 当前阶段必需产物是否存在；
|
||||
- 之前所有阶段的必需产物是否仍然存在。
|
||||
|
||||
Runtime 不检查产物内容、格式、质量或额外文件。
|
||||
|
||||
UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide `Check`、`X` 图标，不直接使用 Emoji。两个按钮的 `aria-label` 与可见文字一致；图标设为 `aria-hidden`。
|
||||
|
||||
```text
|
||||
是否批准当前阶段？
|
||||
[批准] [继续修改]
|
||||
```
|
||||
|
||||
- 批准：批准当前阶段，推进到下一阶段，重新注入上下文并启动下一轮 Agent 工作；
|
||||
- 继续修改：清除待审批请求，恢复普通输入，不自动给 Agent 发送消息；
|
||||
- 审批期间禁用普通消息输入；
|
||||
- 选择“继续修改”后，再次出现新的审批请求前，不能重复批准旧请求；
|
||||
- 不实现 `/approve`、`批准`、`确认` 等文本检测。
|
||||
|
||||
批准与拒绝通过带请求身份的结构化命令处理。后端只接受当前待审批请求；重复点击同一已处理请求不再次推进，旧卡不能批准新的请求。此处校验请求身份与会话状态，不对文件增加指纹、快照或内容校验。进入顾问态后不自主安排新任务。
|
||||
|
||||
### 7.2 澄清
|
||||
|
||||
澄清卡是结构化的用户问询展示方式，不是阶段推进机制。普通文本问询仍然可用。用户回答澄清卡后，回答内容作为普通用户消息回到同一设计会话。
|
||||
|
||||
澄清卡提供独立的选项回答和自由文本回答。点击选项只提交请求身份和所选选项，不携带文本框草稿；Runtime 根据已保存的问题/选项形成明确的回答内容，不只传递“3”之类的序号。用户也可不选择任何选项，直接填写文本并点击“提交回答”，发送请求身份、`optionIndex: null` 和文本正文，Runtime 将其表述为“用户回答”，不将它当作某个选项的补充。新澄清请求出现时清空上一题的文本草稿。不沿用生产旧问题数量上限和固定问答字段。澄清卡待回答状态应可在重启后恢复。
|
||||
|
||||
## 8. 用户工作区浏览
|
||||
|
||||
`design_artifacts` 同时是 Agent 工作区和用户查看策划资料的文件区。用户不需要通过聊天请求 Agent 才能看到文件。
|
||||
|
||||
第一版提供只读浏览：
|
||||
|
||||
- 展示工作区相对路径；
|
||||
- 区分目录和文件；
|
||||
- 点击文件读取正文；
|
||||
- Markdown 按普通 Markdown 渲染；
|
||||
- 代码和纯文本按文本方式展示；
|
||||
- Agent 写入、局部修改或删除后刷新文件树；
|
||||
- `.agent`、`.debug` 和 Runtime 控制文件不出现在工作区文件树中。
|
||||
|
||||
文件浏览读取实际工作区，不局限于已登记或已获批的产物。审批等待期间文件浏览仍然可用；禁用的只是向 Agent 发送普通消息。
|
||||
|
||||
文件视图使用独立面板或现有文件预览容器，用户查看操作不发送 Provider 请求，也不把文件正文追加到 Agent 对话历史。提供手动刷新；文件变更事件后刷新目录，重新打开文件时读取当前磁盘内容。暂不支持内嵌预览的格式仍在目录中可见，可复用现有系统打开入口。
|
||||
|
||||
现有 Game Agent 的文件列表与读取能力可作为实现参考：
|
||||
|
||||
- `list_local_project_files`；
|
||||
- `read_local_project_file`；
|
||||
- 前端 `projectFiles` 状态；
|
||||
- `ProjectWorkspaceChatPane` 中的文件列表和读取入口。
|
||||
|
||||
用户编辑不是第一版必需能力。以后若加入编辑，可复用普通文件写入接口，不增加协同编辑协议。
|
||||
|
||||
## 9. 用户与 Agent 同时编辑
|
||||
|
||||
本方案不解决协同编辑冲突。
|
||||
|
||||
保留底层短时写锁或原子写入，只用于避免单次写入过程损坏。不要增加：
|
||||
|
||||
- 用户编辑锁和 Agent 编辑锁；
|
||||
- 文件 revision 冲突检测；
|
||||
- 乐观并发控制；
|
||||
- 三方合并；
|
||||
- 自动恢复用户版本；
|
||||
- 按作者仲裁最后写入；
|
||||
- 因冲突阻塞 Agent 工作流。
|
||||
|
||||
若用户与 Agent 同时修改同一文件，以最后一次成功写入为准。写入完成后刷新文件树，用户看到当前实际内容。
|
||||
|
||||
不承诺无损合并，不为这个问题增加新 Runtime 状态或冲突处理工具。生产现有写入锁只在单次必要操作中短时持有，不覆盖用户阅读、编辑或 Agent 请求 Provider 的整个时段。
|
||||
|
||||
## 10. 恢复、审计与 debug
|
||||
|
||||
会话恢复复用生产已有可靠机制，重点保存对话、工具调用与执行结果、当前阶段、等待请求和用户审批事件。刷新 UI 只读权威状态，不隐式批准或唤醒等待中的 Agent。
|
||||
|
||||
同一回合、工具调用和审批事件的重试复用原身份；已保存的文件操作结果不因 UI 重试再次执行。用户批准后的阶段变化和下一轮唤醒关联起来，恢复时不重复推进阶段或重复注入旧阶段。失败恢复继续使用当前阶段，不从产物内容推断阶段。
|
||||
|
||||
恢复和正式审计需要的记录留在 `.agent`。`.debug` 只记录额外诊断：正常 Runtime 不读、不校验；写入通过旁路处理，失败或积压不能阻塞 Provider、文件工具或审批，允许丢弃 debug 记录。删除整个 `.debug` 不影响恢复、阶段或审批。
|
||||
|
||||
## 11. 迁移步骤
|
||||
|
||||
1. 核对原型行为基线，选择生产 Provider、恢复、审计、文件和事件通信的可复用函数；仅拆分实际阻碍复用的局部业务耦合。
|
||||
2. 新增独立的设计会话状态结构和持久化路径。
|
||||
3. 新增自由策划 Agent Provider 回合循环。
|
||||
4. 将文件工具绑定到 `design_artifacts`，移除旧 Planning V2 的业务产物门禁。
|
||||
5. 接入阶段提示、必读资源注入和 `get_workflow_status`。
|
||||
6. 接入 `submit_phase_for_approval` 和 ✅/❌ 审批事件。
|
||||
7. 复用 Game Agent 文件浏览实现，让用户查看 `design_artifacts` 文件。
|
||||
8. 用假 Provider 验证五阶段、恢复、审批拒绝、资源读取失败和工具失败。已由 `design_runtime` 脚本化假 Provider 定向测试覆盖。
|
||||
9. 在生产入口切换到新设计 Agent。
|
||||
10. 确认没有现役调用方后，再清理旧 Planning V2 入口和专用展示逻辑。
|
||||
|
||||
实现落在生产 Rust 会话/工具层与现有 React 策划入口，不随应用再启动 Python 原型进程。保持单一用户入口，不为迁移建设第二套工作台。
|
||||
|
||||
切换前盘点旧 Planning V2 活跃会话和持久化数据。旧结构化 GDD 不能直接推断为新五阶段中的某个阶段，不自动转换或覆盖已有项目。旧会话的继续运行或只读保留方式需在实际盘点后明确，再处理入口退役；这不要求新 Agent 兼容旧 GDD 行为。
|
||||
|
||||
## 12. 验收标准
|
||||
|
||||
- Agent 可以只输出文本，也可以连续调用多个工具；
|
||||
- Agent 可以在同一阶段多轮工作，不被 GDD schema 或问询轮数限制；
|
||||
- Agent 写入的文件立即能在用户工作区文件树中看到；
|
||||
- 用户可以直接打开并阅读工作区 Markdown 文件；
|
||||
- Agent 调用审批工具后进入等待状态；
|
||||
- 审批期间不能发送普通消息；
|
||||
- ❌ 不自动唤醒 Agent；
|
||||
- ✅ 才能推进阶段并启动下一轮工作；
|
||||
- 用户文本中的“批准”不会绕过审批事件；
|
||||
- `get_workflow_status` 返回的当前阶段与 Runtime 实际阶段一致；
|
||||
- 之前阶段产物缺失时不能提交当前阶段审批；
|
||||
- 资源缺失或读取失败不会阻断 Agent；
|
||||
- Provider 瞬态失败可按生产重试策略恢复；
|
||||
- 重启后会话、阶段、待审批状态和对话可恢复；
|
||||
- debug 文件不会被正常 Runtime 读取或作为推进条件；
|
||||
- 不引入 Wiki、知识库、多 Agent 或旧 GDD 投影校验。
|
||||
|
||||
实现阶段验证分为：Rust 定向测试（阶段、暂停、恢复、工具），前端定向测试（澄清、✅/❌、输入禁用、文件浏览），以及假 Provider 全流程集成测试。最后使用生产配置执行一次真实 Provider smoke，确认流式文本、文件修改、审批推进和重开恢复；不把真实模型逐字输出当成单元测试断言。文档阶段只执行编码与差异检查，不声称完成这些运行验证。
|
||||
|
||||
## 13. 不在本次迁移范围内
|
||||
|
||||
- 用户和 Agent 的协同编辑、冲突合并和版本回退；
|
||||
- 文档内容质量审核；
|
||||
- 自动从架构文档解析系统清单；
|
||||
- 版本号自动递增；
|
||||
- Wiki、知识库及依赖 Wiki 的功能；
|
||||
- 外部搜索；
|
||||
- 多个策划身份提示词同时存在；
|
||||
- 多 Agent 协作；
|
||||
- 旧 Fast GDD 展示和 GDD schema 兼容。
|
||||
|
||||
## 14. 开发调试入口
|
||||
|
||||
项目运行模式通过 `.agent/runtime-mode.json` 持久化。新建策划项目在进入工作台前写入 `design`；“做成游戏”写入 `game`。重新打开项目时通过 `get_design_agent_runtime_mode` 读取模式，完成后一次性挂载对应工作台，不能先挂载 GameAgent 再切回策划。旧项目缺少模式文件但存在策划会话时按 `design` 恢复；明确的 `game` 标记优先于残留策划会话。无模式也无策划会话的项目仍使用游戏工作台。
|
||||
|
||||
开发构建的策划工作区页头在“刷新”旁提供“快速准备做成游戏测试”按钮。该入口与策划 Debug 日志共用 `GENARRATIVE_AGC_DESIGN_DEBUG=1` 开关：开关未启用时按钮不显示，命令也不可执行。入口仅进行本地 fixture 和会话状态写入，不调用 Provider；完成后自动刷新文件树与阶段，通过 `design-agent-update` 状态事件同步右侧审批/阶段操作区。随后仍需点击正常的“做成游戏”按钮执行资产登记与运行时切换。
|
||||
|
||||
## 15. 策划 Agent reasoning 展示现状
|
||||
|
||||
右侧栏已预留策划 Agent 的 `reasoningText` 事件字段和默认折叠的展示样式，但当前 Provider 解析链仍会过滤 reasoning 内容，尚未向策划 Runtime 产出该字段。因此现阶段只展示用户可见正文和工具状态；reasoning 折叠区在没有数据时不会出现。
|
||||
|
||||
后续若补充 reasoning，需要在策划 Agent 专用 Provider 解析层接入，不能直接修改共享 Provider 以免影响 GameAgent。
|
||||
Reference in New Issue
Block a user