Files
deerflow-code/frontend-web/docs/maf-r0-旧会商交互基线与组件映射.md
T
董宏凯andCursor 99642fca6c feat(maf): conversation-driven MAF roundtable (R1/R2) + server-owned stage-3 dispatch
Backend:
- Conversation API at /api/maf-roundtable/conversations: create/list/detail,
  paginated messages, atomic send+run start, owner-only isolation,
  admin read-only diagnostic access
- SSE real-time event stream (GET /conversations/{id}/stream) backed by
  ConversationEventHub + conversation_events store; multi-worker deployment doc
- Deterministic server-owned stage-3 dispatch contracts (dispatch_contracts.py):
  routing resolved from trusted MAF deployment config instead of manager-chosen
  agent ids; config.yaml keeps stage-3 routing deployment-owned
  (default_manager_agent_id / seat ids / business_routes / max_seats_per_run)
- Conversation persistence (conversations/messages stores) + v2 migration script
- Tests: conversations, conversation stream, migration, phase3 conversation dispatch

Frontend:
- Vitest test infra for MAF (vitest.maf.config.ts + test:maf script) with
  component tests for ApprovalCard/RunHeader/SessionsPage and use-maf-events
- Session form lib, flow-graph dialog / run-detail / sessions page updates,
  routes and nav tweaks
- Docs: R0 legacy interaction baseline mapping, updated implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-03 12:09:47 +08:00

199 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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] 任何人可根据本文档判断新版是否「像原页面」。