AIclinicalresearch/docs/03-业务模块/ASL-AI智能文献/06-技术文档/Deep Research V2.0 开发计划审查与优化建议书.md

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