# MAF 多智能体会商 Phase-4 前端实施计划

## 决策回顾（已与用户确认）
- **入口**：独立顶级菜单 `/page/maf/*`，新增侧边栏一级项「MAF 会商」
- **实时更新**：纯前端轮询，`GET /runs/{id}/events?after_seq=N&limit=1000`，间隔 1.8s，复用现有后端，零 SSE、零后端改动
- **流程图**：要。基于 `confirmed_facts`（来自 `run.maf_checkpoint.fact_ledger`）+ 末轮 `final_result.content` 解析的 `flow-json`，复用 `@xyflow/react` + `flow-graph.ts` + `FlowGraphPanel`
- **审批**：卡片式，仿 `IntentClarificationCard` 的视觉/交互模式（参数摘要 + 批准/拒绝按钮 + 备注 textarea），落到 `POST /approvals/{id}/decision`

## 关键数据契约（已核实后端源码）
- **后端只读**：16 个端点全部命中，无改动。`GET /health` 返回 `enabled` 决定页面内容（入口仍可见，未启用时显示空态）。
- **事件流**：单调 `(run_id, seq)`，`GET /events?after_seq=N` 返回 `{events:[...], latest_seq}`；前端推进 `after_seq=latest_seq`。payload 已在后端**写入时脱敏**（`sanitize_payload`），前端直接渲染。
- **事件分类**（`event_normalizer.py`）：`run.started/completed/failed/cancelled`、`agent.turn_started/message.delta/message.completed`、`tool.requested/started/completed/failed`、`skill.started/completed/failed/selected`、`artifact.created`、`action.waiting_approval/approved/rejected`、`workflow.checkpointed`。
- **事实账本**（`fact_ledger.empty_ledger`）：`candidate_facts`/`confirmed_facts`/`evidence`/`tool_results`/`executed_actions`/`pending_actions`/`failed_or_unknown_actions`/`conflicts`。`confirmed_facts` 条目含 `{candidate_id, text, agent_id, confirmed_by, evidence_refs[]}`。
- **Run 字段**（`run_to_dict`）：`id, session_id, status, maf_checkpoint(含 fact_ledger + final_result + seat_outcomes), last_event_seq, started_at, finished_at, error_code, error_message_safe, token_usage, latency_ms`。
- **终态判定**：`runIsLive(status) = ["pending","running","waiting_approval","cancelling","cancel_failed"].includes(status)`，非 live 即停轮询。
- **Action/Approval**：`GET /runs/{id}/actions`、`GET /runs/{id}/approvals`；`POST /approvals/{id}/decision` `{decision:"approved"|"rejected"}`。

## 复用清单（已定位到文件:行）
- `apiFetch`（`core/api/fetch-client.ts`）：内部自动注入 `Authorization`（`getAuthorizationHeaderValue()`）+ `credentials:"include"`，**返回 Response 不解析、不拼 URL**。调用方拼 `${getBackendBaseURL()}/api/maf-roundtable/...`，自行 `res.ok` 检查 + `res.json()`。
- `getBackendBaseURL`（`core/config/index.ts`）：未设时返回 `""`，相对路径同源可用。
- TanStack Query 模式（`strategy-components/api/task-buttons.ts`）：`useQuery`+`refetchOnWindowFocus:false`；`useMutation`+`onSuccess invalidate`；queryKey 用嵌套数组 `["maf-roundtable", runId, "events"]`。
- 轮询模式（`core/scheduled-tasks/hooks.ts:105-115`）：函数式 `refetchInterval: (query) => runIsLive(query.state.data?.status) ? ms : false`。
- `FlowGraphPanel`（`roundtable-planning/components/FlowGraphPanel.tsx`）：props `{data: FlowGraphData, streaming, onClose, ...}`，自动 `useTheme()` 取明暗。`FlowGraphData = {title, nodes:[{id,label,type,detail?,group?}], edges:[{from,to,label?}]}`。`extractFlowGraph(text)`（`flow-graph.ts:263`）容错解析 ```flow-json``` 代码块（含半截 JSON）。
- `IntentClarificationCard`（`roundtable-planning/components/IntentClarificationCard.tsx`）：卡片视觉模板（`rounded-xl border-red-100` + 「需要确认」徽标 + 选项按钮 + textarea + 提交）。
- 时间线 feed（`roundtable-planning/components/Step1Panel.tsx` + `MessageBubble` + `useAutoScroll` + `ScrollToBottomButton`）：数组入、按 seq 序渲染。
- `useDesensitizeSubtree`（`roundtable-planning/lib/use-desensitize-subtree.ts`）：仅挂 header/面板框架；时间线 body 不挂（payload 已脱敏 + hook 自身警告勿用于消息列表）。
- 路由（`pages/PageRoutes.tsx:143-169`）：`<Route path="maf/*" element={<MafRoutes/>}/>`（仿 `RoundtableRoutes.tsx`）。
- 菜单（`core/page-layout/sidebar-menu.ts`）：在 `sidebarMenuItems` 数组加一级项，`icon` 用 lucide 组件（非字符串 key）。新节点经 `use-sidebar-menu.ts` 自动走 static→inject→override→role→desensitize 流水线，无需额外注册。

## 文件夹结构（镜像 `roundtable-planning/`，全新 `src/maf-roundtable/`）
```
frontend-web/src/maf-roundtable/
├── api/
│   ├── types.ts            # TS 类型（snake_case 直传，后端即 snake_case）
│   ├── client.ts           # BASE()=getBackendBaseURL()+"/api/maf-roundtable"；apiFetch 封装 + readJson<T>/parseDetail
│   ├── sessions.ts         # 会话 CRUD hooks（list/get/create/update/delete）
│   ├── runs.ts             # run hooks（get/list/create/cancel/resume/recover）+ useMafHealth
│   ├── events.ts           # listEvents(runId, afterSeq) 原始 fetch（供轮询 hook 用）
│   └── approvals.ts        # 审批 hooks（list + decide mutation）
├── hooks/
│   ├── use-maf-run-status.ts   # GET /runs/{id} useQuery，函数式 refetchInterval 停终态
│   └── use-maf-events.ts       # ★ cursor 轮询 hook（核心）
├── lib/
│   ├── event-timeline.ts       # 纯函数：events[] → TimelineEntry[]（delta 聚合、tool 生命周期折叠、approval 锚点）
│   └── fact-flow-graph.ts      # 纯函数：confirmed_facts+evidence → FlowGraphData
├── components/
│   ├── MafRunHeader.tsx        # 状态徽标 + token/延迟 + 取消/恢复/重试
│   ├── MafEventTimeline.tsx    # 时间线 feed（MessageBubble + useAutoScroll）
│   ├── MafSeatStatusPanel.tsx  # 席位状态矩阵 + execution_stage 徽标
│   ├── MafFactFlowPanel.tsx    # 包一层 FlowGraphPanel，数据来自 fact-flow-graph
│   ├── MafApprovalCard.tsx     # 卡片式审批（批准/拒绝 + 备注）
│   └── MafHealthGate.tsx       # health.enabled=false → 空态
├── pages/
│   ├── MafSessionsPage.tsx     # 会话列表 + 新建
│   └── MafRunDetailPage.tsx    # 单 run 工作区（三栏）
└── index.ts
```

## 核心：cursor 轮询 hook（`hooks/use-maf-events.ts`）
不用纯 `useQuery+refetchInterval`：cursor `after_seq` 需每次推进，queryFn 不持有「上次 latest_seq」，塞 queryKey 会抖动。**用自定义 hook**（结合 scheduled-tasks 的 refetchInterval 思路 + roundtable-planning 的 reader-loop 家族）：
```ts
export function useMafEvents(runId?: string, active=false) {
  const [events, setEvents] = useState<MafEvent[]>([]);
  const afterSeqRef = useRef(0);                  // 避免 setInterval 闭包旧值
  useEffect(() => {
    if (!runId || !active) return;
    let cancelled = false;
    const poll = async () => {
      const res = await listEvents(runId, afterSeqRef.current);
      if (cancelled || !res.events.length) return;
      setEvents(prev => mergeBySeq(prev, res.events));  // seq 去重
      afterSeqRef.current = res.latest_seq;
    };
    poll();                                        // 进入即补拉（after_seq=0 全量历史）
    const id = setInterval(poll, 1800);
    return () => { cancelled = true; clearInterval(id); };
  }, [runId, active]);
  return events;
}
```
- **补拉历史**：进入页面 `after_seq=0` 立即拉全部已落库事件 → 天然支持断线补拉/刷新恢复。
- **终态停止**：`active` 由 `useMafRunStatus` 的 `runIsLive(status)` 传入，终态时 effect 清理 interval。
- **去重**：后端 `(run_id,seq)` + `source_event_id` 双重去重，前端再按 `seq` 做 `mergeBySeq`，幂等。
- **切换 run**：`runId` 变 → effect 重置（events 清空、afterSeq 归零）。

## 流程图数据流（`lib/fact-flow-graph.ts`）
两源按优先级合并 → `FlowGraphData`：
1. **`confirmed_facts`（主）**：每条已确认事实 → `task` 节点（label=text 截断、detail=全文、group=confirmed_by）；`evidence_refs` 连到 `evidence`（→ `role`）或 `tool_results`（`tool:{name}:{turn}` → `deliverable`）节点；证据根用 `start`。
2. **`final_result.content` 的 ```flow-json```（次）**：用现成 `extractFlowGraph(text)` 解析叠加为「结论流程图」。

输出喂 `<FlowGraphPanel data={...} streaming={!terminal}/>`（非终态蚂蚁线动）。两源皆空 → 空态「尚无可绘制事实」。

## 页面布局（`MafRunDetailPage`，三栏 / 窄屏堆叠）
- **左：时间线**（`MafEventTimeline`）—— `event-timeline.ts` 折叠成可读条目（delta 聚合气泡、tool 折叠「调用 X→完成」、action.waiting_approval 插锚点），复用 MessageBubble + useAutoScroll + ScrollToBottomButton。
- **中上：席位状态**（`MafSeatStatusPanel`）—— `maf_checkpoint.seat_outcomes` 的 agent × status 矩阵 + `execution_stage` 徽标。
- **中下：事实/结论流程图**（`MafFactFlowPanel`）—— 折叠面板，默认展开。
- **右：审批卡片**（`MafApprovalCard` 列表）—— 仅 pending 时显示；含工具名、参数摘要（脱敏）、批准/拒绝按钮 + 备注 textarea → `POST /approvals/{id}/decision`，成功后 invalidate `["maf-roundtable","approvals",runId]`，事件轮询自然看到 `action.approved/rejected`。

## 路由 + 菜单接入（3 处）
1. **新建** `pages/MafRoutes.tsx`（仿 `RoundtableRoutes.tsx`）：`index→MafSessionsPage`、`runs/:runId→MafRunDetailPage`、`*→重定向`。
2. **改** `pages/PageRoutes.tsx`：加 `import MafRoutes` + `<Route path="maf/*" element={<MafRoutes/>}/>`（插 `notebook` 后）。
3. **改** `core/page-layout/sidebar-menu.ts`：数组末尾加 `{ id:"maf-center", label:"MAF 会商", icon:Network, children:[{id:"maf-roundtable", label:"会商列表", icon:MessageSquareText, path:"/page/maf"}] }`。**不加 `adminOnly`**（全员可见；`/health.enabled=false` 由 `MafHealthGate` 客户端控制页面空态）。

## 实施顺序
1. `api/types.ts` + `api/client.ts`（地基）
2. `api/{sessions,runs,events,approvals}.ts`（端点 hook）
3. `hooks/{use-maf-run-status,use-maf-events}.ts`（轮询核心）
4. `lib/{event-timeline,fact-flow-graph}.ts`（纯函数）
5. `components/*`（6 个组件）
6. `pages/*`（2 个页面）+ `index.ts`
7. `pages/MafRoutes.tsx` + 接入 `PageRoutes.tsx` + `sidebar-menu.ts`
8. `pnpm typecheck` + 手动核对路由/菜单显隐

## 文件清单
- **新建**（14）：`maf-roundtable/api/{types,client,sessions,runs,events,approvals}.ts`、`maf-roundtable/hooks/{use-maf-run-status,use-maf-events}.ts`、`maf-roundtable/lib/{event-timeline,fact-flow-graph}.ts`、`maf-roundtable/components/{MafRunHeader,MafEventTimeline,MafSeatStatusPanel,MafFactFlowPanel,MafApprovalCard,MafHealthGate}.tsx`、`maf-roundtable/pages/{MafSessionsPage,MafRunDetailPage}.tsx`、`maf-roundtable/index.ts`、`pages/MafRoutes.tsx`
- **改动**（2）：`pages/PageRoutes.tsx`、`core/page-layout/sidebar-menu.ts`
- **后端**：无改动

## 验证
- `pnpm typecheck`（tsc --noEmit）通过
- 手动：菜单「MAF 会商」→ 列表 → 新建会话 → 启动 run → 时间线滚动 → 席位状态更新 → 流程图随 confirmed_facts 增长 → 审批可批准 → 终态停轮询
- 退路：`/health.enabled=false` → 入口可见但页面显示未启用提示；旧 `roundtable-planning` 零改动