From dcfaa199bf2814207bc1f57ee70225d648e1a665 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= Date: Tue, 18 Aug 2026 20:08:51 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=E4=BC=9A=E5=95=86=20?= =?UTF-8?q?Markdown=20=E4=BA=A7=E7=89=A9=E6=8F=90=E4=BA=A4=E5=88=B0?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1=E8=BF=87=E7=A8=8B=EF=BC=8C=E5=B9=B6=E8=A1=A5?= =?UTF-8?q?=E5=85=85=20Angular=20=E5=AF=B9=E6=8E=A5=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 8BF/会商工作区可将 Markdown 产物一键提交到任务过程报告，后端记录提交状态以便跨用户与刷新后保持已提交；同时为 Angular 智能体对话对接文档补上前后端参考代码索引。 Co-authored-by: Cursor --- .../docs/angular-智能体对话对接文档.md | 315 +++++++++++++++++- .../artifacts/artifact-file-detail.tsx | 11 +- .../eightbf-roundtable/api/task-context.ts | 77 +++++ .../pages/EightBfRoundtablePage.tsx | 13 + .../api/artifact-submissions.ts | 74 ++++ .../components/HighFidelityReport.tsx | 44 +++ .../components/Step2Panel.tsx | 75 +++-- .../components/Step2SandboxLayout.tsx | 15 + .../components/Step3Panel.tsx | 4 + .../components/Step3ReportMode.tsx | 31 ++ .../components/Step3SummaryMode.tsx | 31 ++ .../components/TaskArtifactSubmitButton.tsx | 50 +++ .../hooks/useTaskArtifactSubmission.ts | 207 ++++++++++++ .../lib/task-artifact-submission.ts | 40 +++ .../pages/RoundtablePlanningPage.tsx | 13 + .../roundtable_artifact_submissions.py | 22 ++ .../roundtable_artifact_submissions/base.py | 17 + .../roundtable_artifact_submissions/memory.py | 57 ++++ .../roundtable_artifact_submissions/sql.py | 80 +++++ 19 files changed, 1133 insertions(+), 43 deletions(-) create mode 100644 frontend-web/src/roundtable-planning/api/artifact-submissions.ts create mode 100644 frontend-web/src/roundtable-planning/components/TaskArtifactSubmitButton.tsx create mode 100644 frontend-web/src/roundtable-planning/hooks/useTaskArtifactSubmission.ts create mode 100644 frontend-web/src/roundtable-planning/lib/task-artifact-submission.ts diff --git a/frontend-web/docs/angular-智能体对话对接文档.md b/frontend-web/docs/angular-智能体对话对接文档.md index 34f0b92b..05bc4855 100644 --- a/frontend-web/docs/angular-智能体对话对接文档.md +++ b/frontend-web/docs/angular-智能体对话对接文档.md @@ -12,6 +12,12 @@ http://localhost:5173/#/page/workspace/agents/roundtable-structure/chats/new 本文覆盖：**登录拿 Token → 列模型/切模型 → 建会话/存聊天记录 → 流式对话 → 思考内容 → 步骤条（含创建脚本/执行脚本/写入文件及全部工具）→ 用户协助卡片 → 消息列表渲染 → 停止/重连/上传/产物**。 **不包含**智能体配置（创建/编辑智能体、技能绑定等）。 +路径约定（均相对本仓库根目录 `deerflow-server/`）： + +- 前端：`frontend-web/src/…` +- 后端：`offline-backend-20260512/backend/…`（下文若写 `app/`、`deerflow/`，都在这个 backend 目录下） +- 每节末尾有 **参考代码**；文末第 20 节是总索引。 + --- ## 0. 先看这一页 @@ -45,6 +51,17 @@ Content-Type: application/json 用 Bearer **不必**再带 CSRF。不要用 cookie 登录（`/login/local` 只把 JWT 写进 HttpOnly cookie，不适合 Angular 跨域 API 客户端）。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 前端两个 Base URL | `frontend-web/src/core/config/index.ts`（`getBackendBaseURL` / `getLangGraphBaseURL`） | +| 环境变量注入 | `frontend-web/src/env.ts` | +| LangGraph SDK 客户端（自动带 Bearer） | `frontend-web/src/core/api/api-client.ts` | +| Gateway fetch 自动带 Authorization | `frontend-web/src/core/api/fetch-client.ts` | +| CSRF：有 Bearer 则跳过 | `offline-backend-20260512/backend/app/gateway/csrf_middleware.py` | +| 登录接口白名单 | `offline-backend-20260512/backend/app/gateway/auth_middleware.py` | + --- ## 1. 架构与端到端流程 @@ -77,6 +94,19 @@ sequenceDiagram 2. `context.agent_id = "roundtable-structure"` 3. 会话 `metadata.agent_id = "roundtable-structure"`（历史列表按此过滤） +**参考代码** + +| 说明 | 路径 | +|------|------| +| 路由挂载 AgentChatPage | `frontend-web/src/pages/WorkspaceRoutes.tsx`（`agents/:agent_id/chats/:thread_id`） | +| 对话页：`assistantId` + `context.agent_id` | `frontend-web/src/pages/AgentChatPage.tsx` | +| 聊天气泡壳 | `frontend-web/src/components/workspace/chats/chat-box.tsx` | +| 发消息时写入 metadata.agent_id | `frontend-web/src/core/threads/hooks.ts`（`onCreated` / `thread.submit`） | +| 非内置 assistant_id → agent_id | `offline-backend-20260512/backend/app/gateway/services.py`（`build_run_config`） | +| Lead Agent 工厂 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py` | +| 智能体种子（id / 中文名 / 技能） | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/config.yaml` | +| 智能体 SOUL | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/SOUL.md` | + --- ## 2. CORS / 跨域（Angular 必读） @@ -94,6 +124,8 @@ GATEWAY_CORS_ORIGINS=http://localhost:4200,http://127.0.0.1:4200,https://your-an 或开发期临时 `GATEWAY_CORS_ALLOW_ALL=1`（勿用于生产）。 +**参考代码**：`offline-backend-20260512/backend/app/gateway/app.py`（搜 `GATEWAY_CORS_ORIGINS` / `local_vite_origins` / `cors_expose_headers`）。回归：`offline-backend-20260512/backend/tests/test_taskcop_cors.py`。 + 浏览器跨域读 SSE 还需要暴露这些响应头（Gateway 已配）： - `Content-Location`（从中解析 `run_id`，取消/重连要用） @@ -210,6 +242,20 @@ function authHeader(): HttpHeaders { } ``` +**参考代码** + +| 说明 | 路径 | +|------|------| +| 前端登录 API | `frontend-web/src/core/auth/api.ts`（`loginByUsername` / `loginByToken`） | +| Token 存取、拼 Bearer | `frontend-web/src/core/auth/index.ts`（`getAuthorizationHeaderValue` / `setStoredAuth`） | +| 类型 `LoginByUsernameResponse` | `frontend-web/src/core/auth/index.ts` | +| 登录页（含 token 换票） | `frontend-web/src/pages/LoginPage.tsx` | +| 后端登录路由 | `offline-backend-20260512/backend/app/gateway/routers/auth.py`（`/login/username`、`/login/token`、`/me`） | +| JWT 签发 | `offline-backend-20260512/backend/app/gateway/auth/jwt.py` | +| 请求里解析 cookie / Bearer | `offline-backend-20260512/backend/app/gateway/deps.py`（`get_current_user`） | +| 登录配置（口令门 / token_login） | `offline-backend-20260512/backend/config.yaml` → `auth_login`；schema：`deerflow/config/login_config.py` | +| 登录契约说明 | `offline-backend-20260512/backend/docs/AUTH_LOGIN.md` | + --- ## 4. 模型列表与切换 @@ -266,6 +312,20 @@ Authorization: Bearer 每轮都可以换模型；换了只影响 **下一轮**，不会改写历史。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 前端拉模型 | `frontend-web/src/core/models/api.ts`、`frontend-web/src/core/models/types.ts` | +| 输入框模型下拉 + 档位 | `frontend-web/src/components/workspace/input-box.tsx`（`InputMode`、`ModelSelector`） | +| 档位写入 context | `frontend-web/src/core/threads/hooks.ts`（`thread.submit` 的 `context`：`thinking_enabled` / `is_plan_mode` / `subagent_enabled`） | +| 本地记住所选模型 | `frontend-web/src/core/settings/local.ts`（`deerflow.thread-model.{threadId}`） | +| 后端模型列表 | `offline-backend-20260512/backend/app/gateway/routers/models.py` | +| context 白名单 | `offline-backend-20260512/backend/app/gateway/services.py`（`_CONTEXT_CONFIGURABLE_KEYS`） | +| 本轮实际用哪个模型 | `offline-backend-20260512/backend/app/gateway/services.py`（`_resolve_effective_run_model_name`） | +| 创建 ChatModel、关思考 | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` | +| 模型配置源 | `offline-backend-20260512/backend/config.yaml` → `models[]` | + --- ## 5. 会话（Thread）= 聊天记录的存储单位 @@ -393,6 +453,20 @@ DELETE {LG}/threads/{thread_id} `status`：`idle` | `busy` | `interrupted` | `error` 正在跑时为 `busy`。同一会话再发会被 `multitask_strategy: "reject"` 打回 **HTTP 409**。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 线程类型 / context 类型 | `frontend-web/src/core/threads/types.ts` | +| 列表、标题、路由 | `frontend-web/src/core/threads/utils.ts`（`titleOfThread` / `pathOfThread`） | +| 分页搜索 | `frontend-web/src/core/threads/hooks.ts`（`useThreadsPage`） | +| 智能体最近对话 | `frontend-web/src/components/workspace/agents/agent-recent-chats.tsx` | +| 工作区会话列表 UI | `frontend-web/src/components/workspace/workspace-nav-chat-list.tsx` | +| 建/搜/改/删/state/history | `offline-backend-20260512/backend/app/gateway/routers/threads.py` | +| ThreadResponse / Search 模型 | 同上文件内 `ThreadResponse`、`ThreadCreateRequest`、`ThreadSearchRequest` | +| 删除时清本地目录 | `frontend-web/src/core/threads/hooks.ts`（delete 后再调 Gateway DELETE） | +| 409 中文文案 | `offline-backend-20260512/backend/app/gateway/services.py`（`create_or_reject` / RunManager） | + --- ## 6. 发起智能体对话（核心） @@ -511,6 +585,21 @@ Last-Event-ID: <上一帧 id> 心跳是注释行：`: heartbeat`，忽略即可。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 前端 `useStream` + `thread.submit` | `frontend-web/src/core/threads/hooks.ts`（`useThreadStream`、构造 `messages` / `context`） | +| SDK 包装 | `frontend-web/src/core/api/api-client.ts` | +| stream_mode 规范化 | `frontend-web/src/core/api/stream-mode.ts` | +| 停止：`thread.stop` / `runs.cancel` | `frontend-web/src/core/threads/hooks.ts`（`stopThreadRun`） | +| 输入框停止按钮 | `frontend-web/src/components/workspace/input-box.tsx` | +| 后端 stream / cancel / join | `offline-backend-20260512/backend/app/gateway/routers/thread_runs.py`（`RunCreateRequest`、`stream_run`、`cancel_run`、`join_run`） | +| 真正起跑 | `offline-backend-20260512/backend/app/gateway/services.py`（`start_run`） | +| 后台跑图 + 发 SSE | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py`（`run_agent`） | +| Run 生命周期 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/manager.py` | +| 流式设计说明 | `offline-backend-20260512/backend/docs/STREAMING.md` | + --- ## 7. SSE 事件协议（Angular 必须自己解析 POST 流） @@ -655,6 +744,18 @@ async function streamRun( } ``` +**参考代码** + +| 说明 | 路径 | +|------|------| +| SSE 组帧（`event:` / `data:` / `id:`） | `offline-backend-20260512/backend/app/gateway/services.py`（`format_sse`、`sse_consumer`） | +| 心跳 / 订阅 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/stream_bridge.py` | +| 首帧 `event: metadata` | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py`（`bridge.publish(..., "metadata", {run_id, thread_id})`） | +| `messages-tuple` → 内部 `messages` | 同上 `run_agent`；SSE 事件名 `_lg_mode_to_sse_event` | +| chunk 序列化成 `[chunk, meta]` | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py`（`serialize_messages_tuple` / `serialize_channel_values`） | +| 前端消费：onCustomEvent / onUpdateEvent | `frontend-web/src/core/threads/hooks.ts` | +| 协议说明 | `offline-backend-20260512/backend/docs/STREAMING.md` | + --- ## 8. 消息数据结构（历史 + 实时共用） @@ -707,6 +808,14 @@ async function streamRun( | `ai` 有 `tool_calls` 或仅有思考 | **不单独当最终气泡**，进入步骤条 | | `tool` | **几乎不单独成气泡**，并进步骤条 / 协助卡片 | +**参考代码** + +| 说明 | 路径 | +|------|------| +| 分组、抽文本、抽思考、隐藏消息 | `frontend-web/src/core/messages/utils.ts`（`groupMessages` / `extractContentFromMessage` / `extractReasoningContentFromMessage` / `isHiddenFromUIMessage`） | +| 检索结果识别 | `frontend-web/src/core/messages/search-results.ts` | +| 序列化后的 message dict | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py` | + --- ## 9. 消息列表如何分组渲染 @@ -765,6 +874,20 @@ async function streamRun( `busy` 且还没有最终 `assistant` 气泡时，在列表底部显示跳动的「正在生成」。 上传文件未完成时可插一条 mock AI：`additional_kwargs.element === "task"`，文案「文件上传中，请稍候...」。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 列表入口、分组渲染 | `frontend-web/src/components/workspace/messages/message-list.tsx` | +| 单条用户/助手气泡 | `frontend-web/src/components/workspace/messages/message-list-item.tsx` | +| Markdown | `frontend-web/src/components/workspace/messages/markdown-content.tsx` | +| 气泡/会话滚动容器 | `frontend-web/src/components/ai-elements/message.tsx`、`conversation.tsx` | +| 跳动「正在生成」 | `frontend-web/src/components/workspace/streaming-indicator.tsx` | +| 技能来源展示 | `frontend-web/src/core/skill-display/runtime.ts` | +| 导出 | `frontend-web/src/core/threads/export.ts`；Word：`frontend-web/src/components/workspace/messages/download-word-button.tsx` | +| 删除消息 | `frontend-web/src/components/workspace/messages/delete-message-button.tsx` | +| 问题跳转 | `frontend-web/src/components/workspace/question-navigator.tsx` | + --- ## 10. 思考内容如何对接 @@ -809,6 +932,17 @@ function splitThink(content: string): { answer: string; thinking: string | null `thinking_enabled: false` 时模型不应再吐思考；若仍出现 ``，继续剥掉以免露标签。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 抽思考 / 剥 ``（含未闭合） | `frontend-web/src/core/messages/utils.ts`（`extractReasoningContentFromMessage`、`splitInlineReasoning`） | +| 步骤条里的思考步 | `frontend-web/src/components/workspace/messages/message-group.tsx`（`convertToSteps` 的 `reasoning`） | +| 独立思考折叠块 | `frontend-web/src/components/ai-elements/reasoning.tsx` | +| 文案「思考」 | `frontend-web/src/core/i18n/locales/zh-CN.ts`（`t.common.thinking`） | +| 模型思考流字段 | `offline-backend-20260512/backend/packages/harness/deerflow/models/vllm_provider.py` | +| 关思考注入 extra_body | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` | + --- ## 11. 步骤条（Chain of Thought）— 请做全 @@ -925,6 +1059,23 @@ interface WebFetchArgs { url: string } 字段名不统一（`content` / `page_content` / `snippet` / `m_title` / `name`），展示时做并集兜底。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| **步骤条主实现（必看）** | `frontend-web/src/components/workspace/messages/message-group.tsx`（`convertToSteps`、按 `name` 分支、`ArtifactWriteToolCall`） | +| ChainOfThought 组件 | `frontend-web/src/components/ai-elements/chain-of-thought.tsx` | +| 中文底稿 | `frontend-web/src/core/i18n/locales/zh-CN.ts` → `toolCalls`；类型 `frontend-web/src/core/i18n/locales/types.ts` | +| 工具一句话说明 | `frontend-web/src/core/tools/utils.ts`（`explainToolCall`） | +| 检索结果卡片 | `frontend-web/src/core/messages/search-results.ts` | +| 写文件实时预览 | `frontend-web/src/core/artifacts/streaming-write-preview.ts` | +| bash / ls / read / write / glob / grep | `offline-backend-20260512/backend/packages/harness/deerflow/sandbox/tools.py`（参数都要求先填 `description`） | +| 工具装配（含 MCP、内置） | `offline-backend-20260512/backend/packages/harness/deerflow/tools/tools.py` | +| present_files | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/present_file_tool.py` | +| skill_list / skill_view / search_skills | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/skill_tools.py` | +| 启用哪些工具 | `offline-backend-20260512/backend/config.yaml` → `tools[]` | +| 会商页步骤条（对照用，对话页以 message-group 为准） | `frontend-web/src/roundtable-planning/lib/step-display.tsx` | + --- ## 12. 用户协助卡片（ask_clarification） @@ -1007,6 +1158,17 @@ input.messages = [{ type: "human", content: "<上面拼好的文本>" }] 不要调 `/state` 的 resume，也不要自己造 ToolMessage。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 卡片 UI、拼「我选择：」、多卡合并提交 | `frontend-web/src/components/workspace/messages/message-list.tsx`（`ClarificationCard`、`handleSubmitAllClarifications`） | +| 识别 tool 消息 | `frontend-web/src/core/messages/utils.ts`（`isClarificationToolMessage`） | +| 工具定义 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_tool.py` | +| 截住工具、写 `additional_kwargs.clarification`、goto END | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/clarification_middleware.py`（`_build_payload`） | +| `allow_multiple` 解析 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_utils.py` | +| 提交后又走同一套 sendMessage | `frontend-web/src/pages/AgentChatPage.tsx`、`frontend-web/src/core/threads/hooks.ts`（**不是** Command resume） | + --- ## 13. 其它卡片与面板 @@ -1056,6 +1218,18 @@ interface Todo { content?: string; status?: 'pending' | 'in_progress' | 'complet `setup_agent` / `setup_writing` 带 approval kwargs。普通 `roundtable-structure` 对话 **不会出现**，可忽略。 Deep Research 的 `setup_research_approval` 同理。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| present_files 分组渲染 | `frontend-web/src/components/workspace/messages/message-list.tsx`（`assistant:present-files`） | +| 产物 API | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` | +| 产物前端 | `frontend-web/src/components/workspace/artifacts/`（如 `artifact-file-detail.tsx`） | +| 子任务卡 | `frontend-web/src/components/workspace/messages/subtask-card.tsx` | +| `task` 工具 / 子代理 | `offline-backend-20260512/backend/packages/harness/deerflow/subagents/` | +| Todo 面板 | `frontend-web/src/components/workspace/todo-list.tsx`；类型 `frontend-web/src/core/todos/types.ts` | +| write_todos 中间件装配 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py`（`_build_middlewares`） | + --- ## 14. 标题、追问、错误态 @@ -1095,6 +1269,18 @@ POST {GATEWAY}/api/threads/{thread_id}/suggestions | 上下文压缩 | `custom.context_compacting` | 「正在压缩上下文…」 | | 会话不属于当前用户 | 403/404 | 回到新建 | +**参考代码** + +| 说明 | 路径 | +|------|------| +| 标题展示 | `frontend-web/src/components/workspace/thread-title.tsx` | +| 列表用 title | `frontend-web/src/core/threads/utils.ts`（`titleOfThread`） | +| 临时标题 + LLM 标题 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/title_middleware.py` | +| 追问 API 调用 | `frontend-web/src/components/workspace/input-box.tsx`（`/api/threads/${threadId}/suggestions`） | +| 追问后端 | `offline-backend-20260512/backend/app/gateway/routers/suggestions.py` | +| 409 toast | `frontend-web/src/core/threads/hooks.ts`（`isActiveRunConflictError` / `onError`） | +| 压缩 toast | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/summarization_middleware.py`（`custom.context_compacting`） | + --- ## 15. 文件上传（用户侧） @@ -1138,6 +1324,16 @@ PDF/PPT/Excel/Word 会转成 Markdown 一并放入 uploads。 限额：`GET /api/threads/{thread_id}/uploads/limits`。 列表/删除：`GET …/uploads/list`，`DELETE …/uploads/{filename}`。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 前端上传 | `frontend-web/src/components/workspace/input-box.tsx`；预览 `frontend-web/src/components/workspace/messages/uploaded-file-preview-dialog.tsx` | +| 后端上传路由 | `offline-backend-20260512/backend/app/gateway/routers/uploads.py` | +| 目录与虚拟路径 | `offline-backend-20260512/backend/packages/harness/deerflow/uploads/manager.py` | +| 文档转 Markdown | `offline-backend-20260512/backend/packages/harness/deerflow/utils/file_conversion.py` | +| 说明文档 | `offline-backend-20260512/backend/docs/FILE_UPLOAD.md` | + --- ## 16. 推荐的页面结构（对标 AgentChatPage） @@ -1162,6 +1358,20 @@ PDF/PPT/Excel/Word 会转成 Markdown 一并放入 uploads。 `roundtable-structure` 是「结构化抽取」智能体：给它方案报告或席位交付，产出 flow-json 流程图数据，常伴随写文件 + 展示文件。不要当成多智能体会商编排页（`/roundtable` 是另一套 API）。 +**参考代码** + +| 说明 | 路径 | +|------|------| +| 对话页整页 | `frontend-web/src/pages/AgentChatPage.tsx` | +| 路由 | `frontend-web/src/pages/WorkspaceRoutes.tsx` | +| ChatBox（标题栏 + 列表 + 输入） | `frontend-web/src/components/workspace/chats/chat-box.tsx` | +| 输入框 | `frontend-web/src/components/workspace/input-box.tsx` | +| 左栏最近会话 | `frontend-web/src/components/workspace/agents/agent-chat-sidebar.tsx`、`agent-recent-chats.tsx` | +| 欢迎/推荐问题 | `frontend-web/src/components/workspace/agent-welcome.tsx`、`agents/agent-question-chips.tsx` | +| 智能体种子 | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/` | +| 会商编排（不要和本页搞混） | `frontend-web/src/roundtable-planning/`、`offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` | +| iframe 嵌现网 UI（备选） | `frontend-web/docs/embed-iframe-chat.md` | + --- ## 17. 最小对接顺序（验收清单） @@ -1240,22 +1450,95 @@ Base：`{GATEWAY} = http://host:8001`，LangGraph `{LG} = {GATEWAY}/api`。 --- -## 20. 参考实现位置（本仓库） +## 20. 参考实现总索引 -| 主题 | 文件 | +路径均相对仓库根 `deerflow-server/`。后端根目录 = `offline-backend-20260512/backend/`。 +各节正文末尾也有对应表；这里按主题汇总，加粗的是对接时优先打开的文件。 + +### 20.1 前端：页面与 UI + +| 主题 | 路径 | |------|------| -| 对话页 | `frontend-web/src/pages/AgentChatPage.tsx` | -| 发消息 / SSE | `frontend-web/src/core/threads/hooks.ts` | -| 消息分组 | `frontend-web/src/core/messages/utils.ts` | -| 步骤条 | `frontend-web/src/components/workspace/messages/message-group.tsx` | -| 协助卡片 | `frontend-web/src/components/workspace/messages/message-list.tsx` | -| 中文步骤文案 | `frontend-web/src/core/i18n/locales/zh-CN.ts` → `toolCalls` | -| 登录 | `frontend-web/src/core/auth/api.ts` | -| 模型 | `GET /api/models` ← `app/gateway/routers/models.py` | -| 会话 / 状态 | `app/gateway/routers/threads.py` | -| 流式 | `app/gateway/routers/thread_runs.py` | -| SSE 帧 | `app/gateway/services.py` `format_sse` | -| 协助卡 payload | `deerflow/agents/middlewares/clarification_middleware.py` | -| 沙箱工具 description | `deerflow/sandbox/tools.py`（bash / write_file / …） | +| **智能体对话页** | `frontend-web/src/pages/AgentChatPage.tsx` | +| 路由 `agents/:agent_id/chats/:thread_id` | `frontend-web/src/pages/WorkspaceRoutes.tsx` | +| 对话壳（标题 / 列表 / 输入 / 产物入口） | `frontend-web/src/components/workspace/chats/chat-box.tsx` | +| **消息列表 + 协助卡片** | `frontend-web/src/components/workspace/messages/message-list.tsx` | +| 用户/助手气泡 | `frontend-web/src/components/workspace/messages/message-list-item.tsx` | +| **步骤条（创建脚本/执行脚本/写入文件等）** | `frontend-web/src/components/workspace/messages/message-group.tsx` | +| Markdown | `frontend-web/src/components/workspace/messages/markdown-content.tsx` | +| 子任务卡 | `frontend-web/src/components/workspace/messages/subtask-card.tsx` | +| 思考折叠块 | `frontend-web/src/components/ai-elements/reasoning.tsx` | +| ChainOfThought 控件 | `frontend-web/src/components/ai-elements/chain-of-thought.tsx` | +| 输入框（模型、档位、发送、停止、追问、上传） | `frontend-web/src/components/workspace/input-box.tsx` | +| Todo 条 | `frontend-web/src/components/workspace/todo-list.tsx` | +| 会话标题 | `frontend-web/src/components/workspace/thread-title.tsx` | +| 正在生成 | `frontend-web/src/components/workspace/streaming-indicator.tsx` | +| 会话列表 UI | `frontend-web/src/components/workspace/workspace-nav-chat-list.tsx` | +| 该智能体最近对话 | `frontend-web/src/components/workspace/agents/agent-recent-chats.tsx` | +| 左栏 | `frontend-web/src/components/workspace/agents/agent-chat-sidebar.tsx` | +| 产物预览 | `frontend-web/src/components/workspace/artifacts/` | +| 中文步骤文案 `toolCalls.*` | `frontend-web/src/core/i18n/locales/zh-CN.ts` | -智能体种子：`offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/`（`id: roundtable-structure`，`name: 结构化抽取`）。 +### 20.2 前端：协议与状态 + +| 主题 | 路径 | +|------|------| +| **发消息 / useStream / cancel / 409** | `frontend-web/src/core/threads/hooks.ts` | +| 线程类型 | `frontend-web/src/core/threads/types.ts` | +| 标题与路由 | `frontend-web/src/core/threads/utils.ts` | +| **消息分组、思考、隐藏** | `frontend-web/src/core/messages/utils.ts` | +| 检索结果归一化 | `frontend-web/src/core/messages/search-results.ts` | +| **登录 API** | `frontend-web/src/core/auth/api.ts` | +| Bearer 存取 | `frontend-web/src/core/auth/index.ts` | +| 模型 API / 类型 | `frontend-web/src/core/models/api.ts`、`frontend-web/src/core/models/types.ts` | +| LangGraph Client | `frontend-web/src/core/api/api-client.ts` | +| Gateway fetch + 401 | `frontend-web/src/core/api/fetch-client.ts` | +| Base URL | `frontend-web/src/core/config/index.ts`、`frontend-web/src/env.ts` | +| 写文件流式预览 | `frontend-web/src/core/artifacts/streaming-write-preview.ts` | +| 工具一句话 | `frontend-web/src/core/tools/utils.ts` | + +### 20.3 后端：HTTP + +| 主题 | 路径 | +|------|------| +| **登录 /me** | `offline-backend-20260512/backend/app/gateway/routers/auth.py` | +| JWT | `offline-backend-20260512/backend/app/gateway/auth/jwt.py` | +| **CORS** | `offline-backend-20260512/backend/app/gateway/app.py` | +| 鉴权中间件 | `offline-backend-20260512/backend/app/gateway/auth_middleware.py` | +| **模型列表** | `offline-backend-20260512/backend/app/gateway/routers/models.py` | +| **会话 CRUD / search / state** | `offline-backend-20260512/backend/app/gateway/routers/threads.py` | +| **runs/stream / cancel / join** | `offline-backend-20260512/backend/app/gateway/routers/thread_runs.py` | +| start_run、SSE、context 白名单 | `offline-backend-20260512/backend/app/gateway/services.py` | +| 上传 | `offline-backend-20260512/backend/app/gateway/routers/uploads.py` | +| 产物 | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` | +| 追问 | `offline-backend-20260512/backend/app/gateway/routers/suggestions.py` | +| 简化开放聊天（不要用来复刻本页） | `offline-backend-20260512/backend/app/gateway/routers/open_chat.py` | + +### 20.4 后端：运行时与工具 + +| 主题 | 路径 | +|------|------| +| **跑图 + 发 SSE 事件** | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py` | +| RunManager | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/manager.py` | +| StreamBridge | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/stream_bridge.py` | +| 消息序列化 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py` | +| Lead Agent | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py` | +| **协助卡中间件** | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/clarification_middleware.py` | +| 协助工具 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_tool.py` | +| **bash / write_file 等（description）** | `offline-backend-20260512/backend/packages/harness/deerflow/sandbox/tools.py` | +| 工具总装 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/tools.py` | +| present_files | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/present_file_tool.py` | +| 标题 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/title_middleware.py` | +| 模型工厂 | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` | + +### 20.5 配置、种子、文档 + +| 主题 | 路径 | +|------|------| +| **roundtable-structure 种子** | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/config.yaml` | +| 同上 SOUL | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/SOUL.md` | +| 模型 / 工具开关 | `offline-backend-20260512/backend/config.yaml` | +| 流式协议 | `offline-backend-20260512/backend/docs/STREAMING.md` | +| 登录契约 | `offline-backend-20260512/backend/docs/AUTH_LOGIN.md` | +| 上传 | `offline-backend-20260512/backend/docs/FILE_UPLOAD.md` | +| iframe 嵌入备选 | `frontend-web/docs/embed-iframe-chat.md` | diff --git a/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx b/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx index 9af34f0b..fda1e389 100644 --- a/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx +++ b/frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx @@ -154,6 +154,7 @@ export function ArtifactFileDetail({ hideFileName = false, onDownloadClick, toolbarActions, + headerLeadingAction, researchSessionId, }: { className?: string; @@ -189,6 +190,8 @@ export function ArtifactFileDetail({ * 放置全文改写入口，避免再在沙箱内容区叠一个文字按钮。 */ toolbarActions?: ReactNode; + /** Replaces the left file-type badge for an embedded workspace action. */ + headerLeadingAction?: ReactNode; }) { const { t } = useI18n(); const { artifacts, setOpen, select } = useArtifacts(); @@ -1203,9 +1206,11 @@ export function ArtifactFileDetail({
- - {fileTypeLabel} - + {headerLeadingAction ?? ( + + {fileTypeLabel} + + )} {!hideFileName && ( {/* markdown：隐藏文件名（仅留 MD 徽标），把横向空间让给工具栏，避免窄面板下 diff --git a/frontend-web/src/eightbf-roundtable/api/task-context.ts b/frontend-web/src/eightbf-roundtable/api/task-context.ts index 280414a0..ef38b004 100644 --- a/frontend-web/src/eightbf-roundtable/api/task-context.ts +++ b/frontend-web/src/eightbf-roundtable/api/task-context.ts @@ -73,6 +73,8 @@ export function createEightBfFallbackTask(taskId: string): EightBfTask { } const TASK_DETAIL_PATH = "/task/{taskId}"; +const PROCESS_REPORT_ADD_PATH = "/task/process-report/add"; +const PROCESS_REPORT_PATH = "/task/process-report/{id}"; const DICTIONARY_TYPES = { priority: "task_priority", direction: "task_direction", @@ -94,6 +96,21 @@ function externalUrl(path: string): string { return `${externalApiBase()}${path.startsWith("/") ? path : `/${path}`}`; } +export interface EightBfTaskProcessReportInput { + taskId: string; + agentId: string; + agentName: string; + content: string; + /** 与岗位会商一致：测试分析岗的过程产物位置为 0。 */ + position: number; + reportName: string; + submitStatus: 0 | 1; +} + +export interface EightBfTaskProcessReportReceipt { + id: string; +} + /** * 当前 DeerFlow 的外部业务请求适配器沿用任务系统的默认约定：使用 * `Authorization: Bearer admin`，而不是 DeerFlow 登录接口返回的 token。 @@ -122,6 +139,66 @@ async function fetchExternalTaskSystem( }); } +async function externalTaskError(response: Response, fallback: string): Promise { + const text = await response.text().catch(() => ""); + try { + const payload = JSON.parse(text) as { message?: unknown; msg?: unknown; detail?: unknown }; + const detail = firstText(payload.message, payload.msg, payload.detail); + if (detail) return new Error(`${fallback}（${response.status}）：${detail}`); + } catch { + // Keep the HTTP status when this deployment returns a non-JSON error body. + } + return new Error(`${fallback}（${response.status}）`); +} + +function findProcessReportId(payload: unknown): string { + if (!payload || typeof payload !== "object") return ""; + const source = payload as Record; + const direct = firstText( + source.id, + source.processReportId, + source.process_report_id, + source.reportId, + ); + if (direct) return direct; + return findProcessReportId(source.data); +} + +/** + * Create the external task system's process report in its unsubmitted state. + * The local gateway stores the returned id so a refresh can later submit the + * same report instead of creating a duplicate one. + */ +export async function createEightBfTaskProcessReport( + input: EightBfTaskProcessReportInput, +): Promise { + const response = await fetchExternalTaskSystem(PROCESS_REPORT_ADD_PATH, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(input), + }); + if (!response.ok) throw await externalTaskError(response, "过程产物登记失败"); + const id = findProcessReportId(await response.json().catch(() => null)); + if (!id) throw new Error("过程产物登记成功，但接口未返回报告 ID"); + return { id }; +} + +/** Submit an already-registered process report to the external task system. */ +export async function updateEightBfTaskProcessReport( + reportId: string, + input: EightBfTaskProcessReportInput, +): Promise { + const response = await fetchExternalTaskSystem( + PROCESS_REPORT_PATH.replace("{id}", encodeURIComponent(reportId)), + { + method: "PUT", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(input), + }, + ); + if (!response.ok) throw await externalTaskError(response, "过程产物提交失败"); +} + function firstText(...values: unknown[]): string { for (const value of values) { if (value === undefined || value === null) continue; diff --git a/frontend-web/src/eightbf-roundtable/pages/EightBfRoundtablePage.tsx b/frontend-web/src/eightbf-roundtable/pages/EightBfRoundtablePage.tsx index e66a0331..0bfc7447 100644 --- a/frontend-web/src/eightbf-roundtable/pages/EightBfRoundtablePage.tsx +++ b/frontend-web/src/eightbf-roundtable/pages/EightBfRoundtablePage.tsx @@ -15,9 +15,12 @@ import { fetchEightBfTask, fetchEightBfTaskDictionaries, normalizeEightBfTask, + createEightBfTaskProcessReport, + updateEightBfTaskProcessReport, type EightBfTask, type EightBfTaskDictionaries, } from "@/eightbf-roundtable/api/task-context"; +import type { TaskArtifactSubmissionConfig } from "@/roundtable-planning/lib/task-artifact-submission"; import { PositionBusinessChainFlow } from "@/position-roundtable/components/PositionBusinessChainFlow"; import RoundtablePlanningPage from "@/roundtable-planning/pages/RoundtablePlanningPage"; import { listChains } from "@/roundtable-planning/api/chains"; @@ -79,6 +82,15 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa () => buildEightBfTaskContext(task, taskDictionaries), [task, taskDictionaries], ); + const taskArtifactSubmissionConfig = useMemo( + () => taskId ? { + taskId, + position: 0, + createProcessReport: createEightBfTaskProcessReport, + updateProcessReport: updateEightBfTaskProcessReport, + } : undefined, + [taskId], + ); useEffect(() => { if (!taskId) { @@ -305,6 +317,7 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa /> } rootClassName="eightbf-roundtable" + taskArtifactSubmissionConfig={taskArtifactSubmissionConfig} /> ); } diff --git a/frontend-web/src/roundtable-planning/api/artifact-submissions.ts b/frontend-web/src/roundtable-planning/api/artifact-submissions.ts new file mode 100644 index 00000000..ae6afaf7 --- /dev/null +++ b/frontend-web/src/roundtable-planning/api/artifact-submissions.ts @@ -0,0 +1,74 @@ +import { apiFetch } from "@/core/api/fetch-client"; +import { getBackendBaseURL } from "@/core/config"; + +export interface RoundtableArtifactReference { + sessionId?: string | null; + threadId: string; + nodeKey?: string | null; + sourceKey: string; + path: string; + name: string; + mimeType?: string | null; + revision: number; +} + +export interface RoundtableArtifactSubmissionRecord { + id: string; + taskId: string; + version: number; + submitted: boolean; + submittedAt?: string | null; + cancelledAt?: string | null; + taskDeliveryId?: string | null; + artifact: RoundtableArtifactReference; +} + +function endpoint(taskId: string): string { + return `${getBackendBaseURL()}/api/roundtable/tasks/${encodeURIComponent(taskId)}/artifacts`; +} + +async function readError(response: Response, fallback: string): Promise { + const body = await response.text().catch(() => ""); + try { + const parsed = JSON.parse(body) as { detail?: unknown; message?: unknown }; + const detail = typeof parsed.detail === "string" + ? parsed.detail + : typeof parsed.message === "string" + ? parsed.message + : ""; + if (detail) return new Error(detail); + } catch { + // The status fallback below is more useful than an opaque HTML response. + } + return new Error(`${fallback}（${response.status}）`); +} + +export async function listRoundtableArtifactSubmissions( + taskId: string, + submitted: boolean, +): Promise { + const response = await apiFetch(`${endpoint(taskId)}?submitted=${submitted}`, { method: "GET" }); + if (!response.ok) throw await readError(response, "读取产物提交状态失败"); + const payload = await response.json() as { items?: RoundtableArtifactSubmissionRecord[] }; + return Array.isArray(payload.items) ? payload.items : []; +} + +export async function saveRoundtableArtifactSubmission( + taskId: string, + body: { + submitted: boolean; + registerOnly?: boolean; + submissionId?: string; + taskDeliveryId?: string; + expectedVersion?: number; + artifact: RoundtableArtifactReference; + }, +): Promise { + const response = await apiFetch(`${endpoint(taskId)}/submission`, { + method: "PUT", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ taskId, ...body }), + }); + if (!response.ok) throw await readError(response, "保存产物提交状态失败"); + return response.json() as Promise; +} diff --git a/frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx b/frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx index 90903387..6ad55f75 100644 --- a/frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx +++ b/frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx @@ -32,6 +32,7 @@ import { type ThreadIdMap, } from "@/roundtable-planning/api/multi-agent"; import { ConsensusDocxDownloadButton } from "@/roundtable-planning/components/ConsensusDocxDownloadButton"; +import { TaskArtifactSubmitButton } from "@/roundtable-planning/components/TaskArtifactSubmitButton"; import { desensitize } from "@/lib/desensitize"; import { markdownComponents } from "@/roundtable-planning/components/markdown-components"; import { @@ -46,6 +47,7 @@ import type { import type { UseStep3DashboardReturn } from "@/roundtable-planning/hooks/useStep3Dashboard"; import type { ReportIntent, UseStep3ReportReturn } from "@/roundtable-planning/hooks/useStep3Report"; import type { UseStep3SummaryReturn } from "@/roundtable-planning/hooks/useStep3Summary"; +import type { TaskArtifactSubmissionController } from "@/roundtable-planning/lib/task-artifact-submission"; interface SeatDelivery { /** Display name of the seat (e.g. "情报收集"). */ @@ -93,6 +95,7 @@ interface HighFidelityReportProps { onReset: () => void; openArtifactPreview: (threadId: string, path: string) => void; seatStubMessages: Record; + taskArtifactSubmission?: TaskArtifactSubmissionController; } interface SeatArtifacts { @@ -139,6 +142,7 @@ export const HighFidelityReport: React.FC = ({ onReset, openArtifactPreview, seatStubMessages, + taskArtifactSubmission, }) => { // 「结果绘制」模式：把现有报告内容收起到左栏，右侧由方案可视化智能体绘制图表 HTML。 const consensusDocTitle = useMemo(() => { @@ -445,6 +449,7 @@ export const HighFidelityReport: React.FC = ({ savedSummary={savedSummary} summary={summaryFlow} onViewStatic={() => setSummaryMode(false)} + taskArtifactSubmission={taskArtifactSubmission} /> ); } @@ -467,6 +472,7 @@ export const HighFidelityReport: React.FC = ({ report={reportFlow} dashboard={dashboardFlow} onBack={() => setDrawMode(false)} + taskArtifactSubmission={taskArtifactSubmission} /> ); } @@ -917,6 +923,27 @@ export const HighFidelityReport: React.FC = ({
+ {seat.threadId && ( + + )} +
+ + {submitButton &&
{submitButton}
} +
); } diff --git a/frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx b/frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx index 6c6bec18..7cc7a822 100644 --- a/frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx +++ b/frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx @@ -24,6 +24,8 @@ import { import { ThreadContext } from "@/components/workspace/messages/context"; import type { AgentThreadState } from "@/core/threads"; import { cn } from "@/lib/utils"; +import { TaskArtifactSubmitButton } from "@/roundtable-planning/components/TaskArtifactSubmitButton"; +import type { TaskArtifactSubmissionController } from "@/roundtable-planning/lib/task-artifact-submission"; const CLOSE_MODE = { chat: 100, artifacts: 0 }; const OPEN_MODE = { chat: 60, artifacts: 40 }; @@ -48,6 +50,8 @@ interface Step2SandboxLayoutProps { * 左侧消息列表保持可见；置空即恢复沙箱（文件预览/列表）。 */ sidePanel?: React.ReactNode; + /** 任务深链页面的 Markdown 过程产物提交能力。 */ + taskArtifactSubmission?: TaskArtifactSubmissionController; } export function Step2SandboxLayout({ @@ -58,6 +62,7 @@ export function Step2SandboxLayout({ artifactsFill = false, onArtifactsClose, sidePanel, + taskArtifactSubmission, }: Step2SandboxLayoutProps) { const layoutRef = useRef(null); const { @@ -118,6 +123,16 @@ export function Step2SandboxLayout({ allowVirtualMarkdownEdit // 会商「消息列表沙箱」按需求不脱敏产物内容（用户要拿原始文件）。 disableDesensitize + headerLeadingAction={( + + )} /> ) : (
diff --git a/frontend-web/src/roundtable-planning/components/Step3Panel.tsx b/frontend-web/src/roundtable-planning/components/Step3Panel.tsx index efd3f88e..6b309355 100644 --- a/frontend-web/src/roundtable-planning/components/Step3Panel.tsx +++ b/frontend-web/src/roundtable-planning/components/Step3Panel.tsx @@ -20,6 +20,7 @@ import type { UseStep3SummaryReturn } from "@/roundtable-planning/hooks/useStep3 import type { ThreadIdMap } from "@/roundtable-planning/api/multi-agent"; import { stripReasoning } from "@/roundtable-planning/lib/reasoning"; import { useMemo } from "react"; +import type { TaskArtifactSubmissionController } from "@/roundtable-planning/lib/task-artifact-submission"; export interface Step3PanelProps { threadIds: ThreadIdMap | null; @@ -54,6 +55,7 @@ export interface Step3PanelProps { /** Step 2 沙箱预览产出文件（与第二步相同）。 */ openArtifactPreview: (threadId: string, path: string) => void; seatStubMessages: Record; + taskArtifactSubmission?: TaskArtifactSubmissionController; } export function Step3Panel(props: Step3PanelProps) { @@ -80,6 +82,7 @@ export function Step3Panel(props: Step3PanelProps) { onReset, openArtifactPreview, seatStubMessages, + taskArtifactSubmission, } = props; const seatDeliveries = useMemo( @@ -127,6 +130,7 @@ export function Step3Panel(props: Step3PanelProps) { onReset={onReset} openArtifactPreview={openArtifactPreview} seatStubMessages={seatStubMessages} + taskArtifactSubmission={taskArtifactSubmission} /> ); } diff --git a/frontend-web/src/roundtable-planning/components/Step3ReportMode.tsx b/frontend-web/src/roundtable-planning/components/Step3ReportMode.tsx index c4e33bca..dc8dc872 100644 --- a/frontend-web/src/roundtable-planning/components/Step3ReportMode.tsx +++ b/frontend-web/src/roundtable-planning/components/Step3ReportMode.tsx @@ -45,6 +45,7 @@ import { ConsensusDocxDownloadButton } from "@/roundtable-planning/components/Co import { ScrollToBottomButton } from "@/roundtable-planning/components/ScrollToBottomButton"; import { Step2Message } from "@/roundtable-planning/components/Step2Panel"; import { Step2SandboxLayout } from "@/roundtable-planning/components/Step2SandboxLayout"; +import { TaskArtifactSubmitButton } from "@/roundtable-planning/components/TaskArtifactSubmitButton"; import { desensitize } from "@/lib/desensitize"; import { markdownComponents } from "@/roundtable-planning/components/markdown-components"; import type { DraftStep3Snapshot } from "@/roundtable-planning/api/drafts"; @@ -57,6 +58,7 @@ import type { ReportIntent, UseStep3ReportReturn, } from "@/roundtable-planning/hooks/useStep3Report"; +import type { TaskArtifactSubmissionController } from "@/roundtable-planning/lib/task-artifact-submission"; interface SeatDelivery { sender: string; @@ -88,6 +90,7 @@ interface Step3ReportModeProps { /** 页面层常驻的大屏多页流（模式二）。 */ dashboard: UseStep3DashboardReturn; onBack: () => void; + taskArtifactSubmission?: TaskArtifactSubmissionController; } type SourceModal = "consensus" | "seats" | "files" | null; @@ -108,6 +111,7 @@ export function Step3ReportMode({ report, dashboard, onBack, + taskArtifactSubmission, }: Step3ReportModeProps) { const reportSeatDeliveries = useMemo( () => seatDeliveries.map((d) => ({ sender: d.sender, content: d.content })), @@ -376,6 +380,7 @@ export function Step3ReportMode({ activeThreadId={activeArtifactThreadId ?? reportThreadId} isStreaming={isStreaming} seatMessages={activeSeatMessages} + taskArtifactSubmission={taskArtifactSubmission} > @@ -428,6 +434,7 @@ export function Step3ReportMode({ threadIds={threadIds} coordinatorName={coordinatorName} seatNameMap={seatNameMap} + taskArtifactSubmission={taskArtifactSubmission} onClose={() => setModal(null)} /> )} @@ -513,6 +520,7 @@ function AgentProgressPanel({ availableModels, modelsLoading, setSelectedModel, + taskArtifactSubmission, }: { phase: UseStep3ReportReturn["phase"]; dialogues: UseStep3ReportReturn["dialogues"]; @@ -526,6 +534,7 @@ function AgentProgressPanel({ availableModels: ReadonlyArray; modelsLoading: boolean; setSelectedModel: (model: string) => void; + taskArtifactSubmission?: TaskArtifactSubmissionController; }) { const busy = phase === "creating" || phase === "streaming"; // 只有「正在建线程」时锁输入（线程没建好没法插话）；绘制中允许输入并发送—— @@ -610,6 +619,7 @@ function AgentProgressPanel({ onFileCardClick={(path) => { if (msg.agentThreadId) onArtifactPreview(msg.agentThreadId, path); }} + taskArtifactSubmission={taskArtifactSubmission} /> ))} @@ -822,11 +832,13 @@ function SeatFilesModal({ threadIds, coordinatorName, seatNameMap, + taskArtifactSubmission, onClose, }: { threadIds: ThreadIdMap | null; coordinatorName: string | null; seatNameMap: Record; + taskArtifactSubmission?: TaskArtifactSubmissionController; onClose: () => void; }) { const seatEntries = useMemo(() => { @@ -932,6 +944,25 @@ function SeatFilesModal({
{formatBytes(f.sizeBytes)} +
{formatBytes(f.sizeBytes)} + + ); +} diff --git a/frontend-web/src/roundtable-planning/hooks/useTaskArtifactSubmission.ts b/frontend-web/src/roundtable-planning/hooks/useTaskArtifactSubmission.ts new file mode 100644 index 00000000..7dfbca9d --- /dev/null +++ b/frontend-web/src/roundtable-planning/hooks/useTaskArtifactSubmission.ts @@ -0,0 +1,207 @@ +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; + +import { apiFetch } from "@/core/api/fetch-client"; +import { + listRoundtableArtifactSubmissions, + saveRoundtableArtifactSubmission, + type RoundtableArtifactReference, + type RoundtableArtifactSubmissionRecord, +} from "@/roundtable-planning/api/artifact-submissions"; +import { buildArtifactDownloadUrl, type ThreadIdMap } from "@/roundtable-planning/api/multi-agent"; +import type { + TaskArtifactSubmissionConfig, + TaskArtifactSubmissionController, + TaskArtifactSubmissionState, + TaskArtifactTarget, + TaskProcessReportPayload, +} from "@/roundtable-planning/lib/task-artifact-submission"; + +type StatusEntry = { + state: TaskArtifactSubmissionState; + error: string | null; + record?: RoundtableArtifactSubmissionRecord; +}; + +function normalizedPath(path: string): string { + const trimmed = path.trim(); + if (!trimmed.startsWith("write-file:")) return trimmed; + try { + return decodeURIComponent(new URL(trimmed).pathname).trim(); + } catch { + return trimmed; + } +} + +function fileName(path: string): string { + const normalized = normalizedPath(path); + return normalized.split("/").filter(Boolean).pop() || normalized || "产物.md"; +} + +function isMarkdownTarget(target: TaskArtifactTarget): boolean { + return /\.(md|markdown)$/i.test(normalizedPath(target.path)) + || target.mimeType?.toLowerCase().includes("markdown") === true; +} + +function recordKey(target: TaskArtifactTarget): string { + const source = target.agentId?.trim() || `thread:${target.threadId}`; + return `${source}\u001f${normalizedPath(target.path)}\u001f0`; +} + +function payloadFrom( + config: TaskArtifactSubmissionConfig, + target: TaskArtifactTarget, + content: string, + submitStatus: 0 | 1, +): TaskProcessReportPayload { + const name = target.name?.trim() || fileName(target.path); + const agentId = target.agentId?.trim() || target.threadId; + return { + taskId: config.taskId, + agentId, + agentName: target.agentName?.trim() || agentId, + content, + position: config.position, + reportName: name, + submitStatus, + }; +} + +/** + * Bridges the task system's process-report API and DeerFlow's task-scoped + * submission ledger. The ledger is read on mount, so "已提交" survives reloads + * and is shared by all users opening the same task. + */ +export function useTaskArtifactSubmission( + config: TaskArtifactSubmissionConfig | undefined, + threadIds: ThreadIdMap | null, + agentNameToRole: Record | undefined, +): TaskArtifactSubmissionController | undefined { + const [entries, setEntries] = useState>({}); + const entriesRef = useRef(entries); + entriesRef.current = entries; + const pendingRef = useRef(new Map>()); + + const resolveTarget = useCallback((target: TaskArtifactTarget): TaskArtifactTarget => { + const normalized = normalizedPath(target.path); + const matchedAgentId = target.agentId || Object.entries(threadIds ?? {}) + .find(([, threadId]) => threadId === target.threadId)?.[0]; + const role = matchedAgentId ? agentNameToRole?.[matchedAgentId.toLowerCase()] : undefined; + return { + ...target, + path: normalized, + name: target.name || fileName(normalized), + mimeType: target.mimeType || (isMarkdownTarget({ ...target, path: normalized }) ? "text/markdown" : null), + agentId: matchedAgentId || target.threadId, + agentName: target.agentName || role?.displayName || matchedAgentId || target.threadId, + }; + }, [agentNameToRole, threadIds]); + + useEffect(() => { + if (!config?.taskId) { + setEntries({}); + return; + } + let cancelled = false; + void Promise.all([ + listRoundtableArtifactSubmissions(config.taskId, true), + listRoundtableArtifactSubmissions(config.taskId, false), + ]).then(([submitted, registered]) => { + if (cancelled) return; + const next: Record = {}; + for (const record of [...submitted, ...registered]) { + const key = `${record.artifact.sourceKey}\u001f${normalizedPath(record.artifact.path)}\u001f${record.artifact.revision}`; + next[key] = { + state: record.submitted ? "submitted" : "idle", + error: null, + record, + }; + } + setEntries(next); + }).catch((error) => { + // State recovery is additive. A transient read failure must not prevent a + // user from submitting a Markdown artifact from the current session. + console.warn("[roundtable] 读取任务产物提交状态失败", error); + }); + return () => { cancelled = true; }; + }, [config?.taskId]); + + const submit = useCallback(async (rawTarget: TaskArtifactTarget) => { + if (!config || !isMarkdownTarget(rawTarget)) return null; + const target = resolveTarget(rawTarget); + const key = recordKey(target); + const existingPending = pendingRef.current.get(key); + if (existingPending) return existingPending; + const existing = entriesRef.current[key]; + if (existing?.state === "submitted" && existing.record) return existing.record; + + const operation = (async () => { + setEntries((current) => ({ ...current, [key]: { ...current[key], state: "submitting", error: null } })); + try { + let content = target.content; + if (content == null) { + const response = await apiFetch(buildArtifactDownloadUrl(target.threadId, target.path), { method: "GET" }); + if (!response.ok) throw new Error(`读取 Markdown 产物失败（${response.status}）`); + content = await response.text(); + } + + let record = entriesRef.current[key]?.record; + let reportId = record?.taskDeliveryId || undefined; + if (!reportId) { + const receipt = await config.createProcessReport(payloadFrom(config, target, content, 0)); + reportId = receipt.id; + const artifact: RoundtableArtifactReference = { + threadId: target.threadId, + sourceKey: target.agentId || `thread:${target.threadId}`, + path: target.path, + name: target.name || fileName(target.path), + mimeType: target.mimeType || "text/markdown", + revision: 0, + }; + record = await saveRoundtableArtifactSubmission(config.taskId, { + submitted: false, + registerOnly: true, + taskDeliveryId: reportId, + artifact, + }); + } + + await config.updateProcessReport(reportId, payloadFrom(config, target, content, 1)); + const submitted = await saveRoundtableArtifactSubmission(config.taskId, { + submitted: true, + taskDeliveryId: reportId, + expectedVersion: record?.version, + artifact: { + threadId: target.threadId, + sourceKey: target.agentId || `thread:${target.threadId}`, + path: target.path, + name: target.name || fileName(target.path), + mimeType: target.mimeType || "text/markdown", + revision: 0, + }, + }); + setEntries((current) => ({ ...current, [key]: { state: "submitted", error: null, record: submitted } })); + return submitted; + } catch (error) { + const message = error instanceof Error ? error.message : "提交产物失败，请重试"; + setEntries((current) => ({ ...current, [key]: { ...current[key], state: "error", error: message } })); + throw error; + } finally { + pendingRef.current.delete(key); + } + })(); + pendingRef.current.set(key, operation); + return operation; + }, [config, resolveTarget]); + + return useMemo(() => { + if (!config) return undefined; + return { + enabled: true, + isMarkdown: isMarkdownTarget, + targetFor: resolveTarget, + stateFor: (target) => entries[recordKey(resolveTarget(target))]?.state || "idle", + errorFor: (target) => entries[recordKey(resolveTarget(target))]?.error || null, + submit, + } satisfies TaskArtifactSubmissionController; + }, [config, entries, resolveTarget, submit]); +} diff --git a/frontend-web/src/roundtable-planning/lib/task-artifact-submission.ts b/frontend-web/src/roundtable-planning/lib/task-artifact-submission.ts new file mode 100644 index 00000000..d9a1d5e1 --- /dev/null +++ b/frontend-web/src/roundtable-planning/lib/task-artifact-submission.ts @@ -0,0 +1,40 @@ +import type { RoundtableArtifactSubmissionRecord } from "@/roundtable-planning/api/artifact-submissions"; + +export interface TaskProcessReportPayload { + taskId: string; + agentId: string; + agentName: string; + content: string; + position: number; + reportName: string; + submitStatus: 0 | 1; +} + +export interface TaskArtifactSubmissionConfig { + /** External task-system id, not the local roundtable draft storage key. */ + taskId: string; + position: number; + createProcessReport: (payload: TaskProcessReportPayload) => Promise<{ id: string }>; + updateProcessReport: (reportId: string, payload: TaskProcessReportPayload) => Promise; +} + +export interface TaskArtifactTarget { + threadId: string; + path: string; + name?: string; + mimeType?: string | null; + agentId?: string; + agentName?: string; + content?: string; +} + +export type TaskArtifactSubmissionState = "idle" | "submitting" | "submitted" | "error"; + +export interface TaskArtifactSubmissionController { + enabled: boolean; + isMarkdown: (target: TaskArtifactTarget) => boolean; + targetFor: (target: TaskArtifactTarget) => TaskArtifactTarget; + stateFor: (target: TaskArtifactTarget) => TaskArtifactSubmissionState; + errorFor: (target: TaskArtifactTarget) => string | null; + submit: (target: TaskArtifactTarget) => Promise; +} diff --git a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx index 15eb69ed..3b319763 100644 --- a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx +++ b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx @@ -152,6 +152,8 @@ import { listAgents } from "@/core/agents"; import { listBusinessMappings } from "@/strategy-components/api/business-mapping"; import { emitWujieEvent, isWujieEnv, onWujieEvent, readWujieProps } from "@/core/embed/wujie"; import { collectRoundtableDeliverables } from "@/roundtable-planning/lib/roundtable-deliverables"; +import { useTaskArtifactSubmission } from "@/roundtable-planning/hooks/useTaskArtifactSubmission"; +import type { TaskArtifactSubmissionConfig } from "@/roundtable-planning/lib/task-artifact-submission"; /** * 业务码 → 任务工作区业务码（``TaskBusiness``），用于深链 taskId 模式底部「快捷跳转」栏 @@ -324,6 +326,8 @@ export default function RoundtablePlanningPage({ newTaskLabel, /** 独立业务页可隐藏通用的设置入口。 */ hideHeaderSettings = false, + /** 可选的外部任务过程产物提交适配器（8BF 使用，通用圆桌保持不显示）。 */ + taskArtifactSubmissionConfig, }: { compactChrome?: boolean; lockedChainId?: string | null; @@ -351,6 +355,7 @@ export default function RoundtablePlanningPage({ hideHeaderSaveDraft?: boolean; newTaskLabel?: string; hideHeaderSettings?: boolean; + taskArtifactSubmissionConfig?: TaskArtifactSubmissionConfig; }) { const { theme } = useTheme(); // 全工作区跨页的后台作业完成通知器（Provider 挂在 PageLayout 常驻层）。 @@ -718,6 +723,12 @@ export default function RoundtablePlanningPage({ taskContext, }); + const taskArtifactSubmission = useTaskArtifactSubmission( + taskArtifactSubmissionConfig, + step2.threadIds, + step2.agentNameToRole, + ); + // 同步 step1StateRef,让 buildInitialIntent / Persona / Step 3 都能读到最新值。 useEffect(() => { step1StateRef.current = { @@ -2460,6 +2471,7 @@ export default function RoundtablePlanningPage({ onBackgroundSuspend={handleBackgroundSuspend} isViewingHistory={drafts.loadedFromDraftRef.current} onTriggerToast={triggerToast} + taskArtifactSubmission={taskArtifactSubmission} /> )} @@ -2489,6 +2501,7 @@ export default function RoundtablePlanningPage({ onReset={handleStartNewTask} openArtifactPreview={step2.openArtifactPreview} seatStubMessages={step2.seatStubMessages} + taskArtifactSubmission={taskArtifactSubmission} /> )} diff --git a/offline-backend-20260512/backend/app/gateway/routers/roundtable_artifact_submissions.py b/offline-backend-20260512/backend/app/gateway/routers/roundtable_artifact_submissions.py index 3d7cdde9..b2bf48e9 100644 --- a/offline-backend-20260512/backend/app/gateway/routers/roundtable_artifact_submissions.py +++ b/offline-backend-20260512/backend/app/gateway/routers/roundtable_artifact_submissions.py @@ -52,6 +52,7 @@ class ArtifactSubmissionRequest(BaseModel): task_id: StrictStr | None = Field(default=None, max_length=128, validation_alias=AliasChoices("taskId", "task_id")) submitted: bool + register_only: bool = Field(default=False, validation_alias=AliasChoices("registerOnly", "register_only")) submission_id: StrictStr | None = Field(default=None, max_length=64, validation_alias=AliasChoices("submissionId", "submission_id")) task_delivery_id: StrictStr | None = Field(default=None, max_length=255, validation_alias=AliasChoices("taskDeliveryId", "task_delivery_id")) expected_version: int | None = Field(default=None, ge=0, validation_alias=AliasChoices("expectedVersion", "expected_version")) @@ -200,6 +201,27 @@ async def set_artifact_submission( "submission": _response(conflict.row).model_dump(by_alias=True, exclude_none=False), }, ) from conflict + elif body.register_only: + if not artifact["thread_id"]: + raise HTTPException(status_code=422, detail="artifact.threadId is required when registering an artifact") + try: + row = await store.register( + path_task_id, + artifact, + task_delivery_id=body.task_delivery_id, + actor_id=actor_id, + expected_version=body.expected_version, + ) + except SubmissionVersionConflict as conflict: + raise HTTPException( + status_code=409, + detail={ + "code": "version_conflict", + "message": "登记产物版本冲突：另一写入已更新,请刷新后重试。", + "current_version": conflict.row.get("version", 0), + "submission": _response(conflict.row).model_dump(by_alias=True, exclude_none=False), + }, + ) from conflict else: try: row = await store.cancel( diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/base.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/base.py index b3d01ff7..83dcea9e 100644 --- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/base.py +++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/base.py @@ -37,6 +37,23 @@ class RoundtableArtifactSubmissionStore(ABC): """ raise NotImplementedError + @abstractmethod + async def register( + self, + task_id: str, + artifact: dict[str, Any], + *, + task_delivery_id: str | None = None, + actor_id: str | None = None, + expected_version: int | None = None, + ) -> dict[str, Any]: + """Persist a generated-but-not-yet-submitted artifact receipt. + + This lets the UI retain the external task-process-report id across a + refresh before the user explicitly submits the Markdown artifact. + """ + raise NotImplementedError + @abstractmethod async def cancel( self, diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/memory.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/memory.py index ea7bda10..2fc41c7b 100644 --- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/memory.py +++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/memory.py @@ -109,6 +109,63 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore) ) return deepcopy(row) + async def register( + self, + task_id: str, + artifact: dict[str, Any], + *, + task_delivery_id: str | None = None, + actor_id: str | None = None, + expected_version: int | None = None, + ) -> dict[str, Any]: + """Save an external receipt while keeping the artifact unsubmitted.""" + from deerflow.persistence.roundtable_artifact_submissions.sql import SubmissionVersionConflict + + key = submission_key(task_id, artifact) + row = self._rows.get((task_id, key)) + values = _artifact_values(artifact) + if row is None: + now = _now() + row = { + "id": uuid4().hex, + "task_id": task_id, + "idempotency_key": key, + **values, + "task_delivery_id": task_delivery_id, + "submitted": False, + "version": 0, + "submitted_at": None, + "cancelled_at": None, + "created_by": actor_id, + "updated_by": actor_id, + "submitted_by": None, + "cancelled_by": None, + "created_at": now, + "updated_at": now, + } + self._rows[(task_id, key)] = row + return deepcopy(row) + + if expected_version is not None and row.get("version", 0) != expected_version: + raise SubmissionVersionConflict(deepcopy(row)) + + changed = ( + row.get("task_delivery_id") != task_delivery_id + or any(row.get(name) != value for name, value in values.items()) + ) + if changed: + now = _now() + row.update(values) + row.update( + { + "task_delivery_id": task_delivery_id, + "updated_by": actor_id, + "updated_at": now, + "version": row.get("version", 0) + 1, + } + ) + return deepcopy(row) + async def cancel( self, task_id: str, diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/sql.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/sql.py index b4e33e44..5c8e9073 100644 --- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/sql.py +++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_artifact_submissions/sql.py @@ -88,6 +88,22 @@ def _requires_submission_update( ) +def _requires_registration_update( + row: RoundtableArtifactSubmissionRow, + artifact: dict[str, Any], + task_delivery_id: str | None, +) -> bool: + """Compare receipt metadata without treating ``submitted=False`` as a change.""" + return ( + row.task_delivery_id != task_delivery_id + or row.session_id != artifact.get("session_id") + or row.thread_id != artifact.get("thread_id") + or row.node_key != artifact.get("node_key") + or row.artifact_name != artifact.get("name") + or row.mime_type != artifact.get("mime_type") + ) + + class RoundtableArtifactSubmissionRepository(RoundtableArtifactSubmissionStore): def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None: self._sf = session_factory @@ -181,6 +197,70 @@ class RoundtableArtifactSubmissionRepository(RoundtableArtifactSubmissionStore): raise RuntimeError("submit: retry loop exhausted (unexpected)") + async def register( + self, + task_id: str, + artifact: dict[str, Any], + *, + task_delivery_id: str | None = None, + actor_id: str | None = None, + expected_version: int | None = None, + ) -> dict[str, Any]: + """Persist an external process-report receipt before user submission.""" + key = submission_key(task_id, artifact) + for _attempt in range(2): + async with self._sf() as session: + result = await session.execute( + select(RoundtableArtifactSubmissionRow) + .where( + RoundtableArtifactSubmissionRow.task_id == task_id, + RoundtableArtifactSubmissionRow.idempotency_key == key, + ) + .with_for_update() + ) + row = result.scalars().first() + now = datetime.now(UTC) + + if row is None: + row = RoundtableArtifactSubmissionRow( + id=uuid4().hex, + task_id=task_id, + idempotency_key=key, + task_delivery_id=task_delivery_id, + submitted=False, + created_by=actor_id, + updated_by=actor_id, + created_at=now, + updated_at=now, + version=0, + ) + _apply_artifact(row, artifact) + session.add(row) + try: + await session.commit() + except IntegrityError: + await session.rollback() + continue + await session.refresh(row) + return _to_dict(row) + + if expected_version is not None and row.version != expected_version: + raise SubmissionVersionConflict(_to_dict(row)) + + if not _requires_registration_update(row, artifact, task_delivery_id): + return _to_dict(row) + + _apply_artifact(row, artifact) + row.task_delivery_id = task_delivery_id + row.updated_by = actor_id + row.updated_at = now + row.version = row.version + 1 + await session.commit() + await session.refresh(row) + return _to_dict(row) + + raise RuntimeError("register: retry loop exhausted (unexpected)") + async def cancel( self, task_id: str,