HaHafeng
8f06d4f929
Backend: - Add SSE streaming client (unifuncsSseClient) replacing async polling - Add paragraph-based reasoning parser with mergeConsecutiveThinking - Add requirement expansion service (DeepSeek-V3 PICOS+MeSH) - Add Word export service with Pandoc, inline hyperlinks, reference link expansion - Add deep research V2 worker with 2s log flush and Chinese source prompt - Add 5 curated data sources config (PubMed/ClinicalTrials/Cochrane/CNKI/MedJournals) - Add 4 API endpoints (generate-requirement/tasks/task-status/export-word) - Update Prisma schema with 6 new V2.0 fields on AslResearchTask - Add DB migration for V2.0 fields - Simplify ASL_DEEP_RESEARCH_EXPANSION prompt (remove strategy section) Frontend: - Add waterfall-flow DeepResearchPage (phase 0-4 progressive reveal) - Add LandingView, SetupPanel, StrategyConfirm, AgentTerminal, ResultsView - Add react-markdown + remark-gfm for report rendering - Add custom link component showing visible URLs after references - Add useDeepResearchTask polling hook - Add deep research TypeScript types Tests: - Add E2E test, smoke test, and Chinese data source test scripts Docs: - Update ASL module status (v2.0 - core features complete) - Update system status (v6.1 - ASL V2.0 milestone) - Update Unifuncs DeepSearch API guide (v2.0 - SSE mode + Chinese source results) - Update module auth specification (test script guidelines) - Update V2.0 development plan Co-authored-by: Cursor <cursoragent@cursor.com>
72 lines
5.5 KiB
Markdown
72 lines
5.5 KiB
Markdown
# **Deep Research V2.0 开发计划审查与优化建议书**
|
||
|
||
**审查对象：** 07-Deep Research V2.0 开发计划.md
|
||
|
||
**审查基准：** V4.1 PRD、Unifuncs API 官方文档、系统高可用性架构标准
|
||
|
||
**审查结论：** 整体架构设计（pg-boss \+ 异步轮询 \+ 单页瀑布流）非常优秀。但在**容错机制、数据解析提取、前端状态管理、以及终端 UX 细节**上存在明显隐患，需进行针对性修正。
|
||
|
||
## **🔴 一、 核心高危风险与修正建议 (Critical Risks & Fixes)**
|
||
|
||
### **1\. Unifuncs 轮询逻辑的“脆弱性” (Worker 改造部分)**
|
||
|
||
* **原计划缺陷：** 在 deepResearchV2Worker.ts 的伪代码中，轮询逻辑简单地使用了 await unifuncsClient.queryTask()。如果在长达 15 分钟的轮询中，发生了一次短暂的网络抖动或 Unifuncs 网关返回了 502/504，整个 try-catch 就会抛出异常，导致这个耗费了大量时间的长任务直接 failed。
|
||
* **修正方案：**
|
||
在 Worker 的 while 循环内部，**必须包裹 try-catch 并引入重试机制（Exponential Backoff）**。遇到网络请求失败时，不能直接退出，而是应该记录 warning 并 continue 等待下一次 5s 后的轮询，连续失败超过 5 次才判定任务崩溃。
|
||
|
||
### **2\. 输出解析的“幻觉陷阱” (JSON Parsing)**
|
||
|
||
* **原计划缺陷：** 计划中提到使用 extractSection 提取 \<JSON\_LIST\_SECTION\> 后，直接调用 safeParseJsonList。但在实际的大模型输出中，即便你规定了 XML 标签，模型极大概率会在标签内输出 Markdown 代码块，例如：
|
||
\<JSON\_LIST\_SECTION\>
|
||
\`\`\`json
|
||
\[{"title": "..."}\]
|
||
|
||
\</JSON\_LIST\_SECTION\>
|
||
如果直接 \`JSON.parse()\` 必定报错崩溃。
|
||
|
||
* **修正方案：**
|
||
utils/resultParser.ts 中的 safeParseJsonList 方法**必须**包含预处理逻辑：
|
||
1. 使用正则清洗掉可能存在的 json\` 和 首尾包裹符。
|
||
2. 增加**兜底方案 (Fallback)**：如果正则和清洗均宣告失败，调用一次系统自带的 DeepSeek-V3，传入提取出的坏字符串，要求其强制吐出标准 JSON Array（利用 response\_format: { type: "json\_object" }），确保 Step 4 的表格必定能渲染。
|
||
|
||
## **🟡 二、 前端架构与交互体验优化 (Frontend UX/Architecture)**
|
||
|
||
### **1\. 终端日志自动滚动的“反人类”交互 (AgentTerminal)**
|
||
|
||
* **原计划缺陷：** 计划中提到“新日志出现时 auto-scroll 到底部”。如果用户在长达 5 分钟的执行过程中，向上滚动滚轮想查看之前的思考日志，此时新日志一推过来，页面又被强制拉回到底部，这种体验非常“反人类”。
|
||
* **修正方案：**
|
||
修改 Auto-scroll 触发逻辑：前端通过 ref 判断当前滚动条位置，**只有当用户处于滚动条最底部（或距离底部 \< 50px）时，收到新日志才自动滚动到底部**。如果用户已经向上滚动阅读历史，则只在容器内部静默追加日志，不改变视口位置（可浮现一个“↓ 有新日志”的提示小红点）。
|
||
|
||
### **2\. 前端状态管理的“螺旋地狱” (State Management)**
|
||
|
||
* **原计划缺陷：** 计划在 6.2 节中明确写道：“页面级状态（useState 即可，无需 Zustand）”。
|
||
这是一个有 4 个复杂步骤（Landing \-\> Setup \-\> HITL \-\> Terminal \-\> Results）的单页应用。如果将 taskId、query、logs、step 全塞在父组件的 useState 里，会导致极其严重的**属性透传（Prop Drilling）和父组件频繁全量重渲染**。
|
||
* **修正方案：**
|
||
坚决反对在此场景下仅使用 useState。建议使用现有的 @tanstack/react-query 缓存状态，或者引入极其轻量的 Context API / Zustand。特别是终端日志（Logs）频繁追加时，不能让整个大页面跟着一起重绘，终端组件应当是局部渲染的。
|
||
|
||
## **🟢 三、 业务细节与数据闭环补充 (Business Details)**
|
||
|
||
### **1\. Word 导出功能的缺失逻辑 (Word Export)**
|
||
|
||
* **原计划缺陷：** 提到“报告 \+ 文献表格 → 完整 Markdown → Pandoc 转 Word”。但 result\_list 存的是 JSON Array，Pandoc 不认识 JSON。
|
||
* **修正方案：**
|
||
在 services/wordExportService.ts 中，需要明确增加一步\*\*“JSON to Markdown Table”\*\*的转化方法。
|
||
即把 JSON 数组转化为：
|
||
| 文献标题 | 期刊 | 发表年份 | 链接 |
|
||
|---|---|---|---|
|
||
| Efficacy of... | Lancet | 2023 | \[PubMed\](...) |
|
||
|
||
再将这个生成的 Markdown Table 拼接到 synthesis\_report 的末尾，最后统一送给 Pandoc 渲染。
|
||
|
||
### **2\. 第一步“需求扩写”的成本追踪漏洞**
|
||
|
||
* **原计划缺陷：**
|
||
数据库 Schema 只增加了 Unifuncs 任务的 tokenUsage 记录。但 Step 1 中，调用本地 DeepSeek-V3 把一句话扩写成几百字的“自然语言指令书”，也是要消耗 Token 的。
|
||
* **修正方案：**
|
||
在 AslResearchTask 模型中，应将 tokenUsage 分离或扩展为能够记录两次消耗的结构。例如：internal\_token\_usage (记录扩写的成本) 和 external\_token\_usage (记录 Unifuncs 成本)，以实现精细化的财务核算。
|
||
|
||
## **📝 最终评审结论**
|
||
|
||
请开发团队长仔细阅读上述 6 条修正建议，并同步更新到研发 Task 列表中。
|
||
|
||
特别是在\*\*【JSON解析防崩溃】**和**【终端条件自动滚动】\*\*这两点上，直接决定了本次 V2.0 交付的“工业级质感”。只要把控好这几个细节，原有的技术路线完全可以跑通，且效果会非常惊艳！ |