# MAF-R0 阶段 0 交付文档:旧会商交互基线与组件映射 > 状态:已完成 > 更新时间:2026-08-03 --- ## 1. 实验原型隐藏说明 ### 已完成的操作 - `/page/maf/*` 路由(`MafSessionsPage` + `MafRunDetailPage`)已从正式菜单移除。 - `workspace-nav-chat-list.tsx:199` 保留了墓碑注释:`{/* [MAF-R0] 实验原型已从正式菜单隐藏,仅保留路由供开发诊断:/page/maf */}` - `MafRoutes.tsx` 文件头部标注为 `[MAF-R0 实验原型 — 仅供开发诊断,已从正式菜单移除]`。 - 该原型仅可通过手动输入 URL `/page/maf` 访问,不在任何侧边栏、导航菜单或工作区入口中出现。 - 停止在该原型上新增业务功能。 ### 原型文件位置 | 文件 | 用途 | |------|------| | `src/pages/MafRoutes.tsx` | 路由定义(index → MafSessionsPage, runs/:runId → MafRunDetailPage) | | `src/maf-roundtable/pages/MafSessionsPage.tsx` | 会话列表页(642 行) | | `src/maf-roundtable/pages/MafRunDetailPage.tsx` | 单 run 工作区(195 行) | | `src/maf-roundtable/` | 完整模块(33 文件:api/hooks/components/lib/tests) | | `vitest.maf.config.ts` | MAF 专用测试配置 | | `package.json` → `test:maf` | MAF 测试脚本 | --- ## 2. 旧会商 8 类页面状态交互地图 旧会商入口:`src/roundtable-planning/pages/RoundtablePlanningPage.tsx`(4376 行,三步合一)。 ### 状态 1:空白 / 新建 - 触发:点击「新建会商」或首次进入。 - 表现:中心区域显示欢迎语 + 业务链选择入口 + 底部输入框。左侧历史列表为空或显示已有草稿。 - 关键组件:`RoundtablePlanningPage`(currentStep=1 初始态)、`Step1Panel`(空消息列表 + 输入栏)。 - 数据:`useDraftPersistence` 创建新草稿记录。 ### 状态 2:历史切换 - 触发:点击左侧草稿列表中的某一条。 - 表现:加载该草稿的 Step1/Step2/Step3 快照,恢复到对应步骤。 - 关键组件:`useRoundtableDrafts`(列表)、`useDraftPersistence`(加载 + hydrate)。 - 数据:`GET /api/roundtable-drafts/{id}` 或 `GET /api/roundtable-task-drafts/{id}`。 ### 状态 3:用户提问 - 触发:用户在 Step1 输入框输入任务文本并点击发送。 - 表现:用户气泡立即插入,随后出现 `MessageLoadingPlaceholder`(spinner + 跳动点),等待 SSE 首帧。 - 关键组件:`Step1Panel`(输入栏 → 发送)、`MessageBubble`(用户气泡)、`MessageLoadingPlaceholder`。 - 数据:`POST /api/intent/init` → `POST /api/intent/stream`(SSE)。 ### 状态 4:意图澄清 - 触发:总控/意图智能体判断信息不足,返回 `ask_clarification` 帧。 - 表现:对话流中嵌入 `IntentClarificationCard`(单选/多选 + 自定义输入),用户选择后提交。 - 关键组件:`IntentClarificationCard`(选项卡)、`Step1Panel`(澄清提交逻辑)。 - 数据:SSE 帧 `phase=clarification`,用户回答后继续 `POST /api/intent/stream`。 ### 状态 5:总控派活 - 触发:Step1 完成(INTENT_READY)→ 进入 Step2 → 总控输出派活计划。 - 表现:总控气泡显示派活计划(谁做什么),`ParallelSeatStrip` 显示参与席位头像条(running/done/error 徽章)。 - 关键组件:`Step2Panel`(派活叙事)、`ParallelSeatStrip`(席位条)、`MessageBubble`(总控气泡)。 - 数据:`POST /api/multi-agent/init`(SSE,建立 thread map)→ `POST /api/multi-agent/run/stream`。 ### 状态 6:席位发言 - 触发:总控派活后,各席位按序/并行执行。 - 表现:每个席位的气泡流式出现(`StreamingCursor` 闪烁尾标),工具调用显示为 `MessageStepsCard`(ChainOfThought 折叠卡)。 - 关键组件:`MessageBubble`(席位气泡 + avatar)、`StreamingCursor`、`MessageStepsCard`(工具步骤)、`DialogueSpeedMeter`(tok/s)。 - 数据:SSE delta 帧按 message id 合并。 ### 状态 7:审批 - 触发:席位执行外部写操作,WriteGuard 拦截并请求审批。 - 表现:对话流中嵌入审批卡(工具名 + 风险等级 + 摘要),用户点击批准/拒绝。 - 关键组件:MAF 原型中为 `MafApprovalCard`;旧会商中审批通过 `roundtable-jobs` 的 clarify-resume 机制。 - 数据:`POST /api/maf-roundtable/approvals/{id}/decision`(MAF)或 `POST /api/roundtable-jobs/{id}/clarify-resume`(旧)。 ### 状态 8:完成 / 失败恢复 - 触发:所有席位完成 + 总控收束 → Step3;或 SSE 错误帧 / 网络断开。 - 表现(完成):Step3 显示最终报告(Markdown 总结 / HTML 看板 / 大屏),可追问。 - 表现(失败):错误提示 + 恢复按钮;后台任务可挂起/恢复。 - 关键组件:`Step3Panel` → `HighFidelityReport`(Report/Dashboard/Summary/FileBrowse 模式);失败时 `RoundtableJobNotifier`。 - 数据:`useStep3Summary` / `useStep3Report` / `useStep3Dashboard`;失败恢复 via `POST /api/roundtable-jobs/{id}/resume`。 --- ## 3. 旧组件 → 新 MAF view-model 映射表 | 旧组件 / hook | 新 MAF 对应 | 映射说明 | |---|---|---| | `RoundtablePlanningPage`(三步壳) | `MafRoundtableConversationPage` | 不再有步骤切换;单一连续时间线。 | | `Step1Panel`(意图问答) | `ConversationTimeline` + `ClarificationCard` | 意图理解变为 `manager.intent` 事件卡。 | | `Step2Panel`(研讨对话流) | `ConversationTimeline` + `SeatMessageBubble` | 席位发言由 SSE `agent.message.*` 驱动。 | | `Step3Panel` / `HighFidelityReport` | `FinalResultCard` | 结论作为时间线中的结果卡。 | | `MessageBubble` | `SeatMessageBubble` / 总控气泡 | 重写为 MAF view model;不复用旧 props。 | | `MessageStepsCard` | `ToolProgressCard` | 工具过程由 `tool.started/progress/completed` 事件驱动。 | | `IntentClarificationCard` | `ClarificationCard` | 由 `clarification.required` 事件触发。 | | `ParallelSeatStrip` | `ParticipantStrip` | 状态改由 `manager.dispatch` + `seat.delivery.submitted` + `manager.review.decision` 驱动。 | | `useStep1Intent` | 删除 | 意图理解完全服务端化。 | | `useStep2Orchestration` | 删除 | 编排完全服务端化;前端只消费 SSE。 | | `useDraftPersistence` | `use-maf-conversations` | 历史改为 conversation 列表。 | | `useRoundtableDrafts` | `use-maf-conversations` | 同上。 | | `useStep3Summary/Report/Dashboard` | 删除 | 结论由服务端生成,前端只渲染结果卡。 | | `useAutoScroll` | 可复用(无业务依赖) | 纯 UI 滚动逻辑。 | | `useDialogueSpeedMetrics` | 可复用(无业务依赖) | 纯 UI 速度指标。 | | `MafApprovalCard`(原型) | `ApprovalMessageCard` | 重写为 conversation 时间线内卡片。 | | `MafEventTimeline`(原型) | 删除 | 不再暴露 run/event 管理后台。 | | `MafSeatStatusPanel`(原型) | `ParticipantStrip` | 合并到右侧席位条。 | --- ## 4. 禁止复用的旧业务 hook / API / 状态清单 以下模块 **严禁** 被新 MAF conversation 页面直接 import 或调用: ### 4.1 旧会商 API 客户端(`src/roundtable-planning/api/`) | 文件 | 禁止原因 | |------|----------| | `multi-agent.ts` | 调用 `/api/multi-agent/*`,包含前端 thread map 和编排逻辑 | | `intent.ts` | 调用 `/api/intent/*`,前端驱动意图流 | | `drafts.ts` | 调用 `/api/roundtable-drafts`,旧草稿状态 | | `task-drafts.ts` | 调用 `/api/roundtable-task-drafts`,旧任务草稿 | | `roundtable-jobs.ts` | 调用 `/api/roundtable-jobs`,旧后台任务 | | `chains.ts` | 调用 `/api/roundtable-chains`,旧业务链 CRUD | | `recommend.ts` | 调用 `/api/recommend/stream`,旧推荐流 | | `flow-extract.ts` | 调用 `/api/flow-extract/*`,旧流程图提取 | | `ingest.ts` | 调用 `/api/flow-extract/ingest-eligibility` | | `dashboard-sessions.ts` | 调用 `/api/dashboard-sessions` | | `diagnostics-report.ts` | 调用 `/api/roundtable-diagnostics/report` | ### 4.2 旧会商业务 Hook(`src/roundtable-planning/hooks/`) | 文件 | 禁止原因 | |------|----------| | `useStep1Intent.ts` | 前端驱动意图状态机 | | `useStep2Orchestration.ts` | 前端编排循环(thread map、派活、轮次控制) | | `useDraftPersistence.ts` | 旧草稿持久化逻辑 | | `useRoundtableDrafts.ts` | 旧草稿列表 | | `useStep3Summary.ts` | 前端驱动总结生成 | | `useStep3Report.ts` | 前端驱动看板生成 | | `useStep3Dashboard.ts` | 前端驱动大屏生成 | ### 4.3 旧会商业务状态类型 - `Step1Snapshot`、`Step2Snapshot`、`Step2Dialogue`、`StubAiMessage`、`ParallelSeatView` - `ThreadIdMap`、`ClarificationPayload`、`LeaderDispatch`、`StreamPhase` - `DraftRecord`、`DraftMeta`、`DraftStep1Snapshot`、`DraftStep2Snapshot`、`DraftStep3Snapshot` - `RoundtableJob`、`JobStatus`、`DispatchChainNode`、`StartJobPayload` - `IntentSummary`、`IntentFileRef`、`IntentStreamPhase` ### 4.4 MAF 原型中禁止继续扩展的模块 | 文件 | 禁止原因 | |------|----------| | `src/maf-roundtable/pages/MafSessionsPage.tsx` | 实验原型,不作为产品主界面 | | `src/maf-roundtable/pages/MafRunDetailPage.tsx` | 实验原型,暴露 run/session 管理 | | `src/maf-roundtable/hooks/use-maf-events.ts` | 原型轮询 hook | | `src/maf-roundtable/api/sessions.ts` | 原型 session CRUD | | `src/maf-roundtable/api/runs.ts` | 原型 run 管理 | | `src/maf-roundtable/api/events.ts` | 原型事件轮询 | | `src/maf-roundtable/lib/session-form.ts` | 原型表单逻辑 | ### 4.5 允许参考但必须重写的视觉组件 以下组件的 **交互模式和信息架构** 可作为参考,但新 MAF 页面必须使用独立实现(MAF view model + tdesign-react),不得直接 import: - `MessageBubble.tsx`(气泡布局) - `MessageStepsCard.tsx`(工具步骤折叠) - `IntentClarificationCard.tsx`(澄清选项卡) - `ParallelSeatStrip.tsx`(席位头像条) - `ScrollToBottomButton.tsx`(回到底部按钮) - `Avatars.tsx`(头像 SVG) ### 4.6 可安全复用的无业务依赖工具 - `useAutoScroll.ts`(纯滚动逻辑) - `useDialogueSpeedMetrics.ts`(纯速度指标) - `src/lib/use-desensitize-subtree.ts`(DOM 脱敏,已标注多模块共享) - `markdown-components.tsx`(markdown 渲染配置,需确认无旧状态依赖) --- ## 5. 验收确认 - [x] 旧会商 `RoundtablePlanningPage` 无代码行为变化(未修改任何 `src/roundtable-planning/` 文件)。 - [x] `/page/maf/*` 原型已从菜单隐藏,仅保留路由供开发诊断。 - [x] 8 类页面状态已记录,含触发条件、表现、关键组件和数据流。 - [x] 旧组件到新 MAF view-model 的映射表已完成。 - [x] 禁止复用的 hook/API/状态清单已明确。 - [x] 任何人可根据本文档判断新版是否「像原页面」。