# 报告协作工作台（AgentScope 多智能体）—— 前端模块

实现计划：`docs/agentscope-多智能体报告协作工作台-前端实施计划.md`
（配套后端计划：`docs/agentscope-多智能体报告协作工作台-后端实施计划.md`）。

**联调对接：** `docs/agentscope-多智能体报告协作工作台-前端对接指南.md`（环境配置、API 时序、验收清单）。

**进度（2026-09-06）：** 页面与契约已完成，默认对接真实后端（`GET/POST /api/report-collaboration/*`）。后端 `RC-BE-000`～`018` 已落地。联调见 `docs/agentscope-多智能体报告协作工作台-前端对接指南.md`。

## 结构

```text
src/report-collaboration/
  api/        # 契约类型 + REST/SSE 客户端
    types.ts        # 前后端共享领域类型（冻结契约，字段与后端 Pydantic 一致）
    client.ts       # rcFetch：鉴权、X-Idempotency-Key、X-Expected-Revision、409/422/429/5xx 错误映射
    sessions.ts / plans.ts / runs.ts / reports.ts   # 端点函数
    driver.ts       # 真实后端统一门面（getReportCollaborationDriver；Mock 驱动已移除）
  state/
    event-normalizer.ts  # SSE/REST 事件防御性归一化
    event-reducer.ts     # durable 事件 reducer（seq 去重、乱序缓冲、节点状态机守卫、乐观消息替换）
    selectors.ts         # 页面状态投影（并行聚焦过滤、画布方案、阶段推导）
    message-adapter.ts   # CollaborationMessage → LangGraph Message + BaseStream 外观 + 虚拟业务卡
  hooks/
    useReportCollaborationSession.ts  # 快照→SSE→合帧 reducer→动作（send/select/startRun/commands）
    useReportCollaborationStream.ts   # SSE 连接/指数退避重连/after_seq 续接
    useReportCollaborationMessages.ts # 消息组装（聚焦过滤 + 业务卡 + thread 外观）
    useReportPanelLayout.ts           # 两栏宽度（持久化）、窄屏切换、键盘分隔条
    useReportPlanSelection.ts         # 预览（纯前端）与选定（服务器事实）分离
  components/  # Header / 两栏 Layout / 会话面板（复用 MessageList）/ 方案卡 /
               # 画布（@xyflow/react）/ 节点抽屉 / Composer / 干预卡 / 报告预览 / 历史 / 状态栏
  pages/ReportCollaborationPage.tsx
  styles/report-collaboration.css   # --rc-* 语义 token（Chrome 109 兼容，无 color-mix）
  tests/        # node:test 单测（reducer / adapter），运行：pnpm test:report-collaboration
```

## 路由与入口

- `/page/workspace/report-collaboration` 新会话；`/page/workspace/report-collaboration/:sessionId` 会话页（按 sessionId 重挂）。
- 侧边栏导航项「报告协作」（`workspace-nav-chat-list.tsx`）。
- `WorkspaceRoutes.tsx` 引入页面与 CSS。

## 关键约束（与计划一致）

- 消息区**复用** `MessageList`：AgentScope 文本 / TeamSay / 工具调用与返回经
  `message-adapter.ts` 一对一映射，经 `ThreadContext.Provider` + 合成 `BaseStream` 渲染；
  不另做摘要卡或第二套渲染器。
- MessageList 新增的**通用业务卡插槽** `businessCardSlot`（分组 `assistant:business-card`，
  判据 `additional_kwargs.report_collaboration_card`，见 `core/messages/utils.ts`）只在本页
  传入；其他页面零行为变化。
- 服务器快照 + durable SSE 是唯一事实源；`previewPlanId` / 聚焦成员 / 面板宽度均为纯展示状态。
- 节点抽屉只读合同；重跑/纠偏经对话命令（`targetNodeId`/`agentRunId`）。

## 只走真实后端

Mock 驱动（`mock.ts`）与切换开关（`deerflow.rc-mock` / `VITE_RC_MOCK`）已移除，
页面永远请求真实后端。历史遗留的浏览器设置可执行
`localStorage.removeItem('deerflow.rc-mock')` 清掉（不再被读取）。日常联调请保证：

- `config.yaml` → `report_collaboration.enabled: true`
- 需要成员自动执行时再开 `worker_enabled: true`

## 后端契约冻结说明

`api/types.ts` 按后端计划 §5/§7 编写，已与 `app/report_collaboration/contracts/` 对齐。
快照端点约定 `GET /sessions/{id}` 返回 `SessionSnapshot`
（session/messages/plans/run/nodes/agent_runs/commands/report_versions/last_seq）。
`GET /runs/{id}/stream` 已按 `after_seq` / `Last-Event-ID` 重放 durable 事件（`RC-BE-011`）。queued run 的领取/租约恢复已落地（`RC-BE-012`），质量角色内核已落地（`RC-BE-013`）。报告改写 / apply / restore 已由 `RC-BE-015` 挂载。后端 20 项质量评测集见 `RC-BE-018`（确定性打分，不替代上线前真人盲评）。