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
1 parent df408831e5
commit 99642fca6c
@@ -0,0 +1,198 @@
+# 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] 任何人可根据本文档判断新版是否「像原页面」。