初始化

2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
@@ -0,0 +1,68 @@
+# 报告协作工作台（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`（确定性打分，不替代上线前真人盲评）。