拆分 DirectProject 聊天架构文档
记录 DirectProject 独立聊天容器与工作台钱包布局决策 更新实施里程碑、计划和项目上下文，明确 DirectProject 固定属于项目开发工作台 记录代码与生成契约迁移的验收边界
This commit is contained in:
@@ -174,6 +174,14 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI
|
||||
|
||||
## 项目开发对话（DirectProject）
|
||||
|
||||
**DirectProject 专属聊天模块**:
|
||||
AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、发送队列、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。
|
||||
_Avoid_: 把 DirectProject 作为项目总控聊天的一个布尔分支、把四种 Agent 会话抽象成同一事实源
|
||||
|
||||
**项目工作台布局**:
|
||||
承载本地项目的资源工作区、项目级工具和独立聊天产品路径的外层界面；布局拥有跨面板的账户/钱包入口，聊天模块只负责项目对话，不嵌套账户展示。
|
||||
_Avoid_: 把钱包入口塞进聊天设置、让聊天组件拥有工作台级账户状态
|
||||
|
||||
**项目对话历史**:
|
||||
AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。
|
||||
_Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本
|
||||
|
||||
@@ -35,6 +35,7 @@
|
||||
- [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：新单 Agent 策划会话、GDD 策略、未来 MCP/Skill 兼容插槽、阶段任务与退役验收合同。
|
||||
- [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
|
||||
- [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。
|
||||
- [DirectProject 独立聊天容器与工作台钱包布局](./adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md)：DirectProject 与 Supervisor 等路径分容器，钱包入口由项目工作台布局独立承载。
|
||||
- [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
|
||||
- [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
|
||||
- [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# DirectProject 独立聊天容器与工作台钱包布局
|
||||
|
||||
状态：已接受
|
||||
|
||||
AGC 项目开发工作台的普通项目固定使用 DirectProject；它不再作为 `ProjectSupervisorView` 的条件分支，而由 `view/project-development/chat/` 下的 `DirectProjectChatView` 与 controller 拥有自己的订阅、历史、发送、队列、附件和中止生命周期。Supervisor 调试、Design Agent 与 Planning V2 是独立入口。行为中立的 Composer、消息、工具卡片和设置基础表现可以复用，但不同产品路径不共享行为容器，也不保留运行时 feature flag、兼容别名、Direct fallback 或双跑路径。
|
||||
|
||||
项目工作台布局拥有跨面板的账户/钱包入口。钱包不再作为 `walletEntry` 传入 DirectProject 聊天上下文或聊天设置浮层，而是在 `ProjectDevelopmentView` 的布局级头部/工具栏独立渲染；本次只改变布局归属与嵌套关系，保留钱包入口本身的可用性。
|
||||
|
||||
这项边界选择是为了让 DirectProject 的事实源与生命周期可以独立测试和演进，同时避免把工作台级账户状态与聊天状态耦合；一次性替换通过 Git revert 回滚，不增加运行时开关、兼容别名或条件兼容分支。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 【实施计划】DirectProject 聊天模块抽离
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Milestone | `docs/project-memory/plans/【里程碑】DirectProject聊天模块抽离-2026-09-18.md` |
|
||||
| Status | implemented |
|
||||
| Owner | Codex |
|
||||
|
||||
## 修改边界
|
||||
|
||||
### 允许修改
|
||||
|
||||
- `apps/ai-game-creator-shell/src/App.tsx`：删除 DirectProject 专属状态、ref、effect、订阅/历史/发送/队列/附件/中止处理和 Direct 专属 JSX 接线；保留项目开发工作台壳与 Supervisor/Design/Planning 入口选择。
|
||||
- `apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx`、`useDirectProjectChatController.ts` 与 `generated/`：新增 DirectProject 表现容器、controller 及其 ts-rs 契约目录；共享 reducer/分页/队列模块只引用这份 Direct 契约，不复制类型。
|
||||
- `ProjectSupervisorView`：删除 Direct 分支，只保留 Supervisor、Design Agent、Planning V2；行为中立的公共表现组件按需复用或抽出。
|
||||
- `ProjectSupervisorSettingsDialog` 与 `ProjectDevelopmentView`：移除聊天侧钱包注入和聊天设置中的钱包行，在工作台布局头部/工具栏独立渲染钱包入口，保留账户入口功能。
|
||||
- 现有 DirectProject 测试文件：按新模块责任迁移 import、测试入口和 harness，不新增场景或断言集合。
|
||||
- 当前 ADR、里程碑和实施计划文档，以及必要的 `CONTEXT.md` 术语。
|
||||
|
||||
### 明确不修改
|
||||
|
||||
- Rust、Tauri 命令、共享 DTO、Thread Manager、Codex app-server 和 `.agent/conversations/project.jsonl` / 运行态事件合同。
|
||||
- DirectProject 的路由判定语义、模型配置语义、聊天投影规则、历史锚点与分页协议。
|
||||
- Supervisor、Design Agent、Planning V2 的正式行为与页面入口。
|
||||
- 任何运行时 feature flag、兼容别名、双跑路径或旧行为墓碑代码。
|
||||
|
||||
## 实现顺序
|
||||
|
||||
1. 以当前测试为基线，标记 DirectProject 断言归属：纯 reducer/投影/分页/附件测试归内部模块，Composer 的队列/恢复/中止断言归 Direct 容器 harness，项目开发页面只保留入口接线断言；不增加新测试场景。
|
||||
2. 建立 `direct-project-chat/` 私有模块边界，复用现有 `directThreadChat`、`directHistoryPaging`、`directHistoryAnchorGate`、`directTurnPresentation`、`chatComposerQueue` 与附件映射，不复制第二套事实源或 reducer。
|
||||
3. 将 DirectProject 生命周期整体搬入 `DirectProjectChat`：项目切换清理、订阅 bootstrap/notify/consume、首屏锚点、历史连拉、用户回合预写、Direct invoke、鉴权重试、FIFO 出队、附件上传、中止 released 分支和 manifest 刷新均由该容器管理。
|
||||
4. 将 Direct 专属 JSX 从 `ProjectSupervisorView` 移入 Direct 表现模块：Direct 回合分区、运行中过程卡、Direct Composer、队列、附件、模型/推理选择、语音、中止、Direct 设置；共享组件只保留无行为真相的视觉表现。
|
||||
5. 项目开发工作台固定挂载 `DirectProjectChat`；只有 Supervisor 调试、Design Agent、Planning V2 进入各自独立容器；删除 `directCodex` 作为共享组件行为开关及所有只服务它的 props，不保留 Direct fallback 或运行时 feature flag。
|
||||
6. 将钱包从聊天树移到 `ProjectDevelopmentView` 的工作台头部/工具栏：删除 `cloneElement` 对聊天元素的注入，删除 `ProjectSupervisorSettingsDialog` 的钱包行和 Direct 上下文字段；钱包入口仍由布局直接渲染。
|
||||
7. 把现有测试按所有权迁移并运行定向验证；若发现行为差异，只修复抽离造成的回归，不扩展产品范围。完成后删除旧 Direct 分支与无 caller 的兼容代码。
|
||||
|
||||
## 测试迁移映射
|
||||
|
||||
| 现有测试 | 新归属 |
|
||||
| --- | --- |
|
||||
| `directThreadChat.test.ts` | Direct 事件/历史状态模块 |
|
||||
| `directHistoryPaging.test.ts` | Direct 历史分页模块 |
|
||||
| `directHistoryAnchorGate.test.ts` | Direct 订阅锚点模块 |
|
||||
| `directTurnPresentation.test.ts` | Direct 聊天投影表现模块 |
|
||||
| `directCodexTurnAttachments.test.ts` | Direct 附件模块 |
|
||||
| `chat-composer.suite.ts` 的 FIFO、恢复出队、终止与竞态用例 | Direct 容器/发送队列 harness |
|
||||
| `project-development.suite.ts` 的 Direct 入口、历史、工具卡片、运行态隔离和连续回合用例 | Direct 容器接线；仅迁移测试入口，不新增场景 |
|
||||
|
||||
## 验证命令
|
||||
|
||||
1. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts apps/ai-game-creator-shell/tests/directHistoryAnchorGate.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directCodexTurnAttachments.test.ts`
|
||||
2. `npx vitest run apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`
|
||||
3. `npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`
|
||||
4. `npm run check:doc-index`
|
||||
5. `npm run check:encoding`
|
||||
6. `git diff --check`
|
||||
|
||||
## 风险与回滚点
|
||||
|
||||
- **状态遗漏**：任何 Direct 专属 state/ref/effect 留在 `App.tsx` 都会形成双重所有权；以 `rg` 扫描 Direct 专属符号和 `directCodex` props 作为删除检查。
|
||||
- **事实源漂移**：不得在新容器里重新维护 messages、turn-stream 或 tool-calls 副本；继续只使用项目对话历史、运行态事件和聊天投影。
|
||||
- **竞态回归**：重点检查 subscribe 回执前 notify 欠账、首屏锚点闸门、`turn.completed` 与 invoke finally 的 FIFO 出队窗口、提交早于 `turn.started` 的中止以及项目切换时附件/队列清理。
|
||||
- **布局回归**：钱包必须在工作台布局头部/工具栏出现，且聊天设置不再包含钱包行；账户入口功能不能因聊天抽离丢失。
|
||||
- **回滚**：本次采用一次性替换；失败时整体 Git revert，不保留旧/新双路径或运行时 fallback。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 【里程碑】DirectProject 聊天模块抽离
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | proposed |
|
||||
| Date | 2026-09-18 |
|
||||
| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
|
||||
|
||||
## 目标
|
||||
|
||||
把普通项目的 DirectProject 聊天从 `App.tsx` 与混合的 `ProjectSupervisorView` 中抽出为独立产品容器，并把项目级钱包入口提升到工作台布局层。
|
||||
|
||||
## 范围
|
||||
|
||||
- 公开入口只有一个 `DirectProjectChat`；内部可按状态、订阅/历史、发送/队列、附件和表现职责拆成私有模块。
|
||||
- DirectProject 容器拥有项目对话历史、运行态事件、聊天投影、首屏锚点、历史分页、发送回合、FIFO 队列、附件、中止和项目切换清理。
|
||||
- `App.tsx` 保留通用项目壳状态，只传窄项目上下文与布局同步出口；不再拥有 Direct 专属 state/ref/effect/handler。
|
||||
- `ProjectSupervisorView` 只服务 Supervisor、Design Agent、Planning V2；共享 Composer、消息、Markdown、工具卡片和通用设置表现可以复用，但不共享产品行为容器。
|
||||
- 钱包入口由项目工作台布局（`ProjectDevelopmentView` 的布局级头部/工具栏）独立渲染，不进入聊天上下文或聊天设置浮层。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不改变 DirectProject 的 Tauri/Rust 命令、DTO、Thread Manager、Codex app-server、持久化事实源或运行态事件语义。
|
||||
- 不改变 DirectProject 的路由选择条件、发送/队列/附件/中止/历史锚点/投影行为；钱包仅按已确认的布局归属调整。
|
||||
- 不合并 Supervisor、Design Agent、Planning V2；不新增通用 Agent 聊天框架。
|
||||
- 不新增测试场景或 Provider E2E；现有测试按新模块所有权迁移。
|
||||
- 不保留 Direct 旧条件分支、alias、feature flag、双跑或兼容 fallback。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 现有 DirectProject 真相源收敛与 Thread Manager 事件订阅已作为当前行为合同。
|
||||
- 现有 DirectProject 纯模块测试与 `chat-composer.suite.ts`、`project-development.suite.ts` 页面断言作为迁移基线。
|
||||
- `ProjectDevelopmentView` 已是钱包插槽注入与项目布局的外层边界，可移除向聊天元素的 `cloneElement` 注入。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] DirectProject 只通过独立 `DirectProjectChat` 入口渲染，不再通过 `directCodex` 条件分支进入 `ProjectSupervisorView`。
|
||||
- [ ] DirectProject 的订阅、历史、投影、发送、队列、附件、中止和项目切换状态不再由 `App.tsx` 持有。
|
||||
- [ ] Supervisor、Design Agent、Planning V2 的现有入口和行为不被 Direct 抽离改变。
|
||||
- [ ] 钱包入口由项目工作台布局独立渲染，聊天组件和聊天设置不接收或渲染 `walletEntry`。
|
||||
- [ ] 现有 DirectProject 测试断言按新模块所有权迁移，测试场景与覆盖范围不减少，也不新增场景。
|
||||
- [ ] 代码中不存在 Direct 旧 fallback、feature flag、兼容 alias 或共享行为条件分支。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：迁移后的 Direct 纯模块测试、现有 Composer/项目开发页面测试、非 Direct 现有测试与 TypeScript 检查。
|
||||
- 文档：`npm run check:doc-index`、`npm run check:encoding`、`git diff --check`。
|
||||
- 边界：Thread Manager 订阅回执竞态、首屏锚点、历史连拉、实时/历史合并、FIFO 出队、附件清理、中止 released 分支和项目切换。
|
||||
- 未验证项：真实 Provider/app-server 运行时不因本次结构重构新增验收范围；若现有环境无法运行，记录为未验证而不添加替代兼容路径。
|
||||
Reference in New Issue
Block a user