From 65f8e44a8838aafdc9caf391e58e19eb924236ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Fri, 18 Sep 2026 21:04:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8B=86=E5=88=86=20DirectProject=20=E8=81=8A?= =?UTF-8?q?=E5=A4=A9=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录 DirectProject 独立聊天容器与工作台钱包布局决策 更新实施里程碑、计划和项目上下文，明确 DirectProject 固定属于项目开发工作台 记录代码与生成契约迁移的验收边界 --- CONTEXT.md | 8 +++ docs/README.md | 1 + ...ct独立聊天容器与工作台钱包布局-2026-09-18.md | 9 +++ ...计划】DirectProject聊天模块抽离-2026-09-18.md | 64 +++++++++++++++++++ ...碑】DirectProject聊天模块抽离-2026-09-18.md | 50 +++++++++++++++ 5 files changed, 132 insertions(+) create mode 100644 docs/adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md create mode 100644 docs/project-memory/plans/【实施计划】DirectProject聊天模块抽离-2026-09-18.md create mode 100644 docs/project-memory/plans/【里程碑】DirectProject聊天模块抽离-2026-09-18.md diff --git a/CONTEXT.md b/CONTEXT.md index da2aca812..724d95de3 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -174,6 +174,14 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI ## 项目开发对话（DirectProject） +**DirectProject 专属聊天模块**: +AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、发送队列、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。 +_Avoid_: 把 DirectProject 作为项目总控聊天的一个布尔分支、把四种 Agent 会话抽象成同一事实源 + +**项目工作台布局**: +承载本地项目的资源工作区、项目级工具和独立聊天产品路径的外层界面；布局拥有跨面板的账户/钱包入口，聊天模块只负责项目对话，不嵌套账户展示。 +_Avoid_: 把钱包入口塞进聊天设置、让聊天组件拥有工作台级账户状态 + **项目对话历史**: AGC 本地项目内 Codex 原始对话条目的持久集合，是聊天展示、工具卡片和线程恢复注入的唯一持久事实源。 _Avoid_: 会话缓存、展示态历史、按 UI 需要另存的对话副本 diff --git a/docs/README.md b/docs/README.md index 01f489d07..ff8264180 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 编辑器适配边界。 diff --git a/docs/adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md b/docs/adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md new file mode 100644 index 000000000..3a30b05e3 --- /dev/null +++ b/docs/adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md @@ -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 回滚，不增加运行时开关、兼容别名或条件兼容分支。 diff --git a/docs/project-memory/plans/【实施计划】DirectProject聊天模块抽离-2026-09-18.md b/docs/project-memory/plans/【实施计划】DirectProject聊天模块抽离-2026-09-18.md new file mode 100644 index 000000000..faa037abe --- /dev/null +++ b/docs/project-memory/plans/【实施计划】DirectProject聊天模块抽离-2026-09-18.md @@ -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。 diff --git a/docs/project-memory/plans/【里程碑】DirectProject聊天模块抽离-2026-09-18.md b/docs/project-memory/plans/【里程碑】DirectProject聊天模块抽离-2026-09-18.md new file mode 100644 index 000000000..c877915b5 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】DirectProject聊天模块抽离-2026-09-18.md @@ -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 运行时不因本次结构重构新增验收范围；若现有环境无法运行，记录为未验证而不添加替代兼容路径。