代码提交

2026-08-15 12:51:58 +08:00
1 parent 500dab29ab
commit 70da7c5649
@@ -1,6 +1,6 @@
 # GPT Researcher 接入 DeerFlow 的可实施开发方案

-> 文档状态：设计稿，可进入任务拆分与开发评审  
+> 文档状态：持续实现中；本次已补齐报告实时写作、对话工作台与浏览器端 Word 导出
 > 编写日期：2026-08-14  
 > GPT Researcher 核对基线：[`5d84d2f5553e70a2765a8ff3a0d2672d60437ce8`](https://github.com/assafelovic/gpt-researcher/tree/5d84d2f5553e70a2765a8ff3a0d2672d60437ce8)  
 > 上游本地代码：`F:\react01\deeflow-code\gpt-researcher`（当前 HEAD 与上述基线一致）  
@@ -51,7 +51,7 @@ GPT Researcher 当前真正直接使用 LangGraph 的生产代码主要在：
 2. 保持上游研究流程和报告生成方法的主体结构，减少功能偏差。
 3. 在四个边界上使用 DeerFlow Adapter：模型、研究材料、事件、产物。
 4. 搜索结果一律由 DeerFlow 提供完整正文和元数据，使 GPT Researcher 不再自行联网、抓取或调用 MCP。
-5. 新建独立前端入口 `/page/deep-research`，不进入 `open-canvas`，不修改 AI 写作状态机。
+5. 新建独立前端入口 `/page/strategy/qa/deep-research`，不进入 `open-canvas`，不修改 AI 写作状态机。

 ### 2.3 第一版的能力范围

@@ -66,7 +66,7 @@ GPT Researcher 当前真正直接使用 LangGraph 的生产代码主要在：
 - 后台执行、刷新恢复、断线重连、取消、重试、人工审核后继续。
 - 历史会话、报告追问、产物下载。

-PDF、DOCX 自动导出建议做成可选能力。原因不是 LangGraph，而是 DeerFlow 当前依赖中没有上游导出使用的全部库。核心研究功能可以保持零 LangGraph 依赖变更；如果部署方需要服务端 PDF/DOCX，再启用独立的 `deep-research-export` 可选依赖组。
+PDF 自动导出仍建议做成可选能力。DOCX 已改为复用前端现有 `docx` 依赖在浏览器本地生成：完成态报告导出为 Word 时会附带收集到的参考来源，不新增 Python 或 LangGraph 依赖。私有报告配图暂不嵌入 Word；若后续需要嵌图，应通过鉴权产物接口取得 Blob 后写入 `ImageRun`。

 ---

@@ -104,7 +104,7 @@ PDF、DOCX 自动导出建议做成可选能力。原因不是 LangGraph，而
 | 详细报告 | 总体研究后按子主题并行展开 | `DetailedReport` | 子主题任务并行，最终合并引言和结论 |
 | 深度研究 | 按 breadth/depth 递归探索 | `DeepResearchSkill` | 有界递归、分支事件、统一去重和取消 |
 | 多智能体编审 | 有计划、复核、修订、事实核查 | `ChiefEditor` + `EditorAgent` | LangGraph 1.x 图，支持暂停和恢复 |
-| 自定义报告 | 用户给定报告结构或提示 | upstream custom report/prompt | 配置白名单与模板变量，不允许任意系统指令覆盖 |
+| 自定义报告 | 用户给定报告结构或提示 | upstream custom report/prompt | 已支持：受限 `custom_outline` 保存到配置快照；标题/编号列表决定详细报告和多智能体章节，其他模式作为受保护的写作结构约束 |

 ### 4.2 用户可见能力

@@ -113,9 +113,9 @@ PDF、DOCX 自动导出建议做成可选能力。原因不是 LangGraph，而
 3. 查看自动生成的研究计划。
 4. 在开启人工审核时，修改或批准研究计划。
 5. 实时查看：当前阶段、搜索问题、材料数量、子主题、递归分支、写作和核查进度。
-6. 查看来源列表、来源正文摘要、来源类型、时间、相关度和被引用情况。
+6. 查看来源列表、来源正文摘要、来源类型、时间、相关度和被引用情况；研究停止后可调整后续追问使用的来源集合。
 7. 查看流式报告预览。
-8. 下载 Markdown、HTML，以及部署已启用时的 PDF、DOCX。
+8. 下载 Markdown、HTML 和浏览器本地生成的 Word；PDF 仍按部署能力决定是否开放。
 9. 研究完成后继续针对本次报告和材料追问。
 10. 取消正在运行的任务；刷新页面后恢复状态；服务重启后自动续跑或重新领取。
 11. 查看、重命名、删除历史研究会话。
@@ -179,6 +179,8 @@ F:\react01\deeflow-code\gpt-researcher

 当前版本固定为 `5d84d2f5553e70a2765a8ff3a0d2672d60437ce8`。本章所有 `gpt_researcher/...`、`multi_agents/...` 和 `backend/...` 路径均相对于该目录；实施时以该本地目录作为 vendoring 的唯一来源，不从浮动分支重新下载文件。

+当前实现的可执行代码是对这些控制流的 DeerFlow 适配，而非直接 import 上游包（上游 Provider、检索/抓取和 MCP 栈不能越过 DeerFlow 的安全边界）。固定 commit、许可证、逐文件映射、不可突破的适配约束和后续直接 vendoring 的补充义务，见 `offline-backend-20260512/backend/packages/harness/deerflow/agents/deep_research/UPSTREAM.md`。
+
 最关键的源码位置如下：

 | 用途 | 本地文件 |
@@ -365,6 +367,17 @@ offline-backend-20260512/backend/app/gateway/

 ### 7.4 前端

+当前 Phase 2 已落地为与现有 Vite + React 页面目录一致的轻量实现：
+
+```text
+frontend-web/src/pages/DeepResearchPage.tsx
+frontend-web/src/strategy-components/api/deep-research.ts
+frontend-web/src/pages/StrategyRoutes.tsx
+frontend-web/src/core/page-layout/sidebar-menu.ts
+```
+
+其中 `DeepResearchPage` 同时承载创建表单、历史会话、对话式 SSE 研究过程、流式报告草稿、来源库、报告预览和 MD/HTML/Word 下载。后续在页面复杂度明显增加时，可按下方的目标目录拆分；不能为了目录形式而重复实现另一套状态或 API client。
+
 ```text
 frontend-web/src/deep-research/
 ├── routes/DeepResearchRoutes.tsx
@@ -389,10 +402,10 @@ frontend-web/src/deep-research/

 路由修改：

- 在 `frontend-web/src/pages/PageRoutes.tsx` 增加：
+- 当前实现已在 `frontend-web/src/pages/StrategyRoutes.tsx` 增加：

 ```tsx
-<Route path="deep-research/*" element={<DeepResearchRoutes />} />
+<Route path="qa/deep-research" element={<DeepResearchPage />} />
 ```

 - 在 `frontend-web/src/core/page-layout/sidebar-menu.ts` 的「问答管理」下增加：
@@ -401,8 +414,8 @@ frontend-web/src/deep-research/
 {
  id: "qa-deep-research",
  label: "深度研究",
-  icon: Search,
-  path: "/page/deep-research",
+  icon: Telescope,
+  path: "/page/strategy/qa/deep-research",
 }
 ```

@@ -1207,17 +1220,13 @@ resume 请求示例：
 ### 17.1 路由

 ```text
-/page/deep-research                 创建页 + 历史列表
-/page/deep-research/:sessionId      研究工作台
+/page/strategy/qa/deep-research    创建页、历史列表和研究工作台
 ```

-`DeepResearchRoutes.tsx`：
+当前版本使用单页会话选择，不需要再维护一套嵌套路由：

 ```tsx
-<Routes>
-  <Route index element={<DeepResearchHomePage />} />
-  <Route path=":sessionId" element={<DeepResearchSessionPage />} />
-</Routes>
+<Route path="qa/deep-research" element={<DeepResearchPage />} />
 ```

 ### 17.2 创建页
@@ -1519,6 +1528,8 @@ tests/test_deep_research_user_isolation.py

 ### Phase 1：标准报告后端 MVP

+实现状态（2026-08-14）：已完成领域配置、材料/LLM/上下文/产物 Adapter、Basic runner、五类持久化表、租约式 dispatcher/executor、Gateway API 和定向测试。当前 Basic runner 是 DeerFlow 原生实现；上游 GPT Researcher 的选定源码尚未 vendoring，仍应在 Phase 3/4 的详细报告、递归研究和多智能体实现中按本文第 6 章从本地固定 commit 引入。
+
 任务：

 1. 新增 config/types/cancellation/events。
@@ -1538,6 +1549,8 @@ tests/test_deep_research_user_isolation.py

 ### Phase 2：独立前端页面

+实现状态（2026-08-14）：已完成路由与菜单入口、创建表单（将所选 mode 写入后端 config）、会话历史、作业 SSE、取消/重新开始、实时来源刷新、报告预览和 MD/HTML 下载。本轮将右侧工作区改为对话式：原始课题、研究过程、流式报告草稿、最终报告与报告追问按对话顺序展示；报告 `report_chunk` 依赖持久化 SSE 重放，刷新时不重新调用模型。页面与 AI 写作页面、Context 和路由完全隔离。
+
 任务：

 1. 增加路由和菜单。
@@ -1553,12 +1566,14 @@ tests/test_deep_research_user_isolation.py

 ### Phase 3：详细报告与 Deep Research

+实现状态（2026-08-14）：已完成 `DetailedRunner` 和 `DeepRunner`，并由 `DeepResearchEngine` 分发；Gateway capabilities 与创建校验已开放 `detailed`、`deep`，前端模式选择与递归阶段事件也已接入。详细报告按本地上游 `gpt-researcher/backend/report_type/detailed_report/detailed_report.py` 的“子主题规划 → 分主题研究 → 章节汇编”控制流做 Adapter 化实现；递归模式按 `gpt-researcher/gpt_researcher/skills/deep_research.py` 的“分支 → learning → follow-up”控制流适配。二者不直接调用上游的模型、检索器或抓取器，而是只通过 DeerFlow 的 `AdapterBundle` 复用现有材料收集和 LangGraph 1.x 运行时。
+
 任务：

 1. 接入 Detailed runner。
 2. 接入 Deep runner并修复已知空查询问题。
 3. 增加全局预算、分支事件和来源去重。
-4. 增加高级配置 UI。
+4. 增加高级配置 UI。（已完成：仅暴露已由运行器使用的语言、语气、预算、并发、模式专属参数和 `custom_outline`。）

 验收：

@@ -1569,6 +1584,8 @@ tests/test_deep_research_user_isolation.py

 ### Phase 4：LangGraph 多智能体与人工审核

+实现状态（2026-08-14）：已完成 `MultiAgentRunner`。它按本地上游 `gpt-researcher/multi_agents/agents/orchestrator.py` 的 editor → researcher → writer → reviewer 结构，用当前已安装的 LangGraph 1.x `StateGraph` 编排，不引入上游的 retriever、scraper 或额外 agent 框架。初次运行产生 plan-review `awaiting_input` 事件；`RecordingEventSink` 将 interrupt、计划和租约状态写入既有 durable job，前端可批准或提交修订，`POST /api/deep-research/jobs/{id}/resume` 重新入队后从事件日志恢复原计划并继续执行。审阅不通过时按 `max_revision_loops` 有界回到改写节点。
+
 任务：

 1. vendor LangGraph 多智能体选定代码。
@@ -1585,10 +1602,12 @@ tests/test_deep_research_user_isolation.py

 ### Phase 5：追问、图片和完整导出

+实现状态（2026-08-14）：图片生成和报告追问子项已完成。由于当前 DeerFlow 部署本身只有识图、没有可直接复用的文生图 Provider，深度研究新增了部署级 `deep_research.image_generation`（OpenAI 兼容 `POST {base_url}/images/generations`）适配器；默认关闭且不保存任何密钥到 session/job。开启后 capabilities 才向前端开放「为报告生成配图」开关。四种 Runner 在文本报告完成后共用 `runners/images.py`：最多四张、优先报告二级章节、请求 `b64_json`，图片保存为隐藏 runtime thread 的受限 `research-image-01..04.(png|jpg|webp)` 产物，并以 `deep-research://` 私有 URI 插入 Markdown。前端经携带现有鉴权头的会话产物接口下载成 Blob 再预览，因此不会泄露 hidden thread id，也不依赖可能过期的第三方 URL；图片服务未配或单张失败只产生可恢复 warning，文字报告照常完成。完成态报告还支持 owner-scoped `GET /messages`、`POST /chat`：问题与回答写入既有消息表，模型仅接收本报告、已选来源和近期消息；回答中的 `[[source:id]]` 仅在 id 属于该会话来源时保留并写入 citation ids。用户可在研究任务停止后以 `PATCH /sessions/{id}/sources/{source_id}` 调整“已选来源”，该集合会立即约束后续追问但不会倒改已完成的报告；运行中返回 409，以免与自动策展写入竞态。`allow_new_research=true` 明确返回 422，不会暗中重新搜集信息。DOCX 已通过浏览器端 `docx` 生成，无需部署新离线 wheel；PDF 与含私有图片嵌入的服务端文档导出仍是后续可选子项。
+
 任务：

-1. 报告追问与消息持久化。
-2. DeerFlow ImageProvider 适配和图片插入。
+1. 报告追问与消息持久化。（已完成）
+2. DeerFlow ImageProvider 适配和图片插入。（已完成）
 3. 可选 PDF/DOCX 导出依赖与 capability。
 4. 完善配额、监控和管理配置。

@@ -1647,7 +1666,8 @@ tests/test_deep_research_user_isolation.py
 | 事实核查回环 | 复用，增加最大回环和来源约束 |
 | 引言、正文、结论 | ReportGenerator 复用 |
 | 引用和参考链接 | Markdown processing 复用并绑定 source id |
-| 图片生成与插入 | 后续接 DeerFlow ImageProvider |
+| 报告完成后的追问 | 已支持：仅报告/已选来源/近期消息，持久化 source-id 引用，不会隐式重新搜索；停止后可人工调整已选来源 |
+| 图片生成与插入 | 已支持：部署级 OpenAI 兼容 ImageProvider，可选开关、受鉴权产物、报告内预览；未配置时优雅跳过 |
 | Markdown | 核心支持 |
 | HTML | 核心支持并清洗 |
 | PDF/DOCX | 可选依赖能力 |