# **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 交付的“工业级质感”。只要把控好这几个细节，原有的技术路线完全可以跑通，且效果会非常惊艳！