deerflow-code/frontend-web/docs/maf-r0-旧会商交互基线与组件映射.md

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. 验收确认

• 旧会商 RoundtablePlanningPage 无代码行为变化（未修改任何 src/roundtable-planning/ 文件）。
• /page/maf/* 原型已从菜单隐藏，仅保留路由供开发诊断。
• 8 类页面状态已记录，含触发条件、表现、关键组件和数据流。
• 旧组件到新 MAF view-model 的映射表已完成。
• 禁止复用的 hook/API/状态清单已明确。
• 任何人可根据本文档判断新版是否「像原页面」。