# Research 会话拆分与记录化改造 PRD

> 文档性质：Research 模块优化需求文档。
>
> 更新日期：2026-03-27。
>
> 当前状态：Phase 1 已实施完成。
>
> 目标：将当前单页 Research 工作台升级为“研究记录列表 + 新建研究 + 研究详情”的三段式产品形态，补齐后端记录化与后台执行能力，并扩展“汇报提纲”“讲话稿”模板。

---

## 1. 背景与问题

当前 Research 已具备以下能力：

- 研究任务定义表单
- `plan -> run` 双阶段流程
- 结构化 SSE 事件流
- 章节化研究报告、时间线、证据工作区
- 章节重跑与导出能力

但当前实现仍有以下产品问题：

1. 入口、创建、执行、查看全部堆叠在单个页面中，操作心智负担偏高。
2. 当前“会话列表”本质上是前端本地工作台状态，不是正式研究记录，无法稳定支持跨端、跨浏览器、长期沉淀。
3. 研究执行生命周期仍绑定当前页面请求，刷新或断线后的状态恢复不够可靠。
4. 输出模板仍偏研究型，缺少更贴近日常汇报场景的“汇报提纲”“讲话稿”。

因此，本次改造目标不是继续优化单页工作台，而是把 Research 从“前端临时工作台”升级为“可沉淀、可追溯、可迭代的研究记录系统”。

---

## 2. 目标

本次改造的核心目标：

1. 让用户先看到“研究记录”，再进入“新建”和“详情”，形成清晰的信息架构。
2. 让 Research 记录从前端 localStorage 升级为后端可查询、可持久化的数据资产。
3. 让研究执行从“请求内 SSE 直连执行”升级为“Celery 后台任务 + Redis Stream + SSE 订阅”模型。
4. 扩展更贴合政务汇报场景的输出模板。
5. 为后续澄清、研究后继续对话、重新生成保留扩展位，但不纳入本期交付。

---

## 3. 非目标

本次改造不包含以下内容：

1. 多人协作评审与批注。
2. 研究订阅、定时刷新。
3. 条款级回链、证据 pin / exclude 的完整二次治理。
4. 对外部互联网数据源的接入。

---

## 4. 用户价值

### 4.1 主要用户

- 业务研究人员
- 政策梳理人员
- 领导汇报材料准备人员
- 需要把检索结果沉淀为正式研究产物的知识工作者

### 4.2 核心价值

1. 从“临时问一轮”升级为“可复用的研究记录”。
2. 让研究执行与页面生命周期解耦，刷新或断线后仍可恢复状态与结果。
3. 输出更接近日常汇报材料生产场景。

---

## 5. 产品形态调整

### 5.1 页面结构

当前单页 `/research` 调整为三段式：

1. `/research`
   - 研究记录列表页
2. `/research/new`
   - 新建研究页
3. `/research/:id`
   - 研究详情页

### 5.2 核心原则

1. 列表页负责“看记录和进入操作”。
2. 新建页负责“定义任务、生成计划、启动研究入口”。
3. 详情页负责“查看计划、查看报告、查看证据、订阅进度、章节重跑”。

---

## 6. 需求范围

## 6.1 研究记录列表

新增研究记录列表页，默认展示当前用户的研究记录。

列表字段：

- 标题
- 更新时间
- 输出模板类型
- 状态
- 简要结论

列表操作：

- 查看详情
- 新建研究
- 删除记录
- 归档记录

其中“简要结论”取值规则：

1. 优先使用最终报告的执行摘要。
2. 若报告尚未生成，则使用研究计划摘要。
3. 若仍无内容，则展示状态型提示语，例如“待规划”“研究中”。

建议支持的状态：

- `draft`：草稿
- `clarifying`：澄清中
- `planned`：计划已生成
- `running`：研究中
- `cancelled`：已中断
- `completed`：已完成
- `failed`：失败

### 6.1.1 建议补充能力

为了便于后续扩展，列表页第一版建议预留以下筛选条件：

- 标题搜索
- 时间范围
- 输出模板
- 状态

第一版如果时间有限，可只做后端字段预留，前端暂不开放筛选 UI。

### 6.1.2 删除与归档规则

建议区分“删除”和“归档”：

1. 删除
   - 面向误建记录、测试记录、无价值草稿
   - Phase 1 默认仅允许删除 `draft`、`planned`、`failed` 状态记录
2. 归档
   - 面向已完成但短期不常查看的正式研究
   - 已归档记录默认不出现在主列表，可通过筛选查看
   - 归档仅影响当前记录的列表可见性，不级联影响其父版本或子版本

第一版若时间有限，至少应支持“删除草稿/失败记录”和“归档已完成记录”中的一种。

## 6.2 新建研究页

新建研究页与详情页彻底分离。

新建页包含以下区域：

1. 研究任务输入区
2. 显式资料范围区
3. 计划预览与确认区

用户流程：

1. 输入初始主题、问题、目标、范围、模板、深度。
2. 点击“开始规划”。
3. 系统直接生成正式研究计划。
4. 用户确认计划后跳转到详情页。
5. 详情页基于 `autoRun=true` 发起后台执行并订阅进度。

### 6.2.1 Phase 2 预留

计划前澄清仍是目标能力，但不纳入 Phase 1 交付。本期只保留数据模型与路由扩展位，不实现澄清交互区。

后续若补齐该能力，建议规则为：

1. 澄清问题最多 3 轮。
2. 每轮优先聚焦边界最关键的缺口，例如时间范围、地域范围、汇报口径、是否必须围绕已导入材料。
3. 当信息达到生成计划的最低充分性后，应停止澄清并进入计划生成。

## 6.3 研究详情页

研究详情页承接当前 Research 工作台的大部分能力，并把运行恢复、后台任务订阅和章节重跑收敛到同一页面。

详情页建议包含：

1. 研究基本信息
2. 已确认研究计划
3. 研究进度与时间线
4. 最终报告
5. 证据工作区
6. 导出 / 归档 / 章节重跑入口

### 6.3.1 Phase 2 预留

研究后继续对话、重新生成与版本派生仍是目标能力，但不纳入 Phase 1。本期仅保留：

1. 版本字段预留（`parent_record_id`、`root_record_id`、`version_no`）
2. 详情页头部可展示版本信息占位
3. 后续扩展时不改变当前三页架构

---

## 7. 输出模板扩展

在现有模板基础上新增两类输出模板：

1. 汇报提纲
2. 讲话稿

### 7.1 汇报提纲

适用场景：

- 领导汇报前整理提纲
- 会议材料提纲输出
- 专题情况汇报骨架

默认章节建议：

1. 汇报背景
2. 核心结论
3. 主要依据
4. 重点问题
5. 建议动作
6. 需关注事项

### 7.2 讲话稿

适用场景：

- 会议讲话准备
- 工作部署口径整理
- 政策宣贯发言稿草拟

默认章节建议：

1. 开场背景
2. 总体判断
3. 当前重点
4. 风险和问题
5. 下一步安排
6. 结束强调

### 7.3 服务指南特殊处理

当前系统对办事指南类资料已存在结构化证据识别与抽取能力，例如：

- 申请材料
- 收费项目
- 办理时限
- 办理窗口
- 咨询投诉
- 办理流程

新增模板“汇报提纲”“讲话稿”也应继续复用这类结构化证据，而不是退化为只看普通文档摘要。

具体要求：

1. 当研究命中服务指南结构化证据时，模板生成仍应优先吸收这些字段。
2. 在“汇报提纲”中，适合将其组织为“办理条件/材料/时限/费用/风险提醒”等汇报项。
3. 在“讲话稿”中，适合将其组织为“群众关注点、办理堵点、执行要求、服务改进方向”等表达。
4. quick 与 deep 两种模式下，该能力均应保留。

---

## 8. quick / deep 模式定位

当前系统存在两种研究模式：

1. `quick`
2. `deep`

本次新架构下，两者的定位应明确区分。

### 8.1 quick 模式定位

`quick` 不是 QA 的别名，也不应被理解为“随便生成一个短答案”。

在新架构下，`quick` 的定位应是：

- 面向轻量研究任务的“快速成稿模式”
- 仍然走正式 Research 记录体系
- 仍然允许生成计划、查看记录、导出结果
- 但在研究范围、澄清轮次、材料覆盖、报告结构复杂度上做轻量化控制

适用场景：

- 需要在较短时间内形成一版结构化结论
- 明确问题、明确范围、对全面性要求低于 deep
- 更接近“快速汇总、快速成稿、快速汇报提炼”

典型任务示例：

- 快速梳理某一专题近一年的政策口径
- 针对已导入材料形成一版汇报提纲
- 针对单一事项形成一版讲话稿骨架

### 8.2 deep 模式定位

`deep` 的定位仍然是：

- 面向复杂研究任务的深度研究模式
- 强调问题拆解、多源证据汇总、冲突识别和章节化输出
- 更适合政策链条、执行研判、对比分析等复杂场景

### 8.3 quick 与 QA 的边界

建议边界如下：

1. QA
   - 面向即时问答
   - 结果偏一次性对话
   - 不以正式研究记录为核心产物
2. Research quick
   - 面向轻量研究
   - 结果仍然沉淀为正式研究记录
   - 可以继续对话、导出和重新生成
3. Research deep
   - 面向复杂研究
   - 强调过程完整性、证据覆盖和结构化报告质量

### 8.4 新架构下 quick 的产品要求

在新架构下，quick 模式建议具备以下特征：

1. 计划前澄清轮次更少，默认 0 到 1 轮，必要时最多 2 轮。
2. 默认研究深度更偏 `standard`。
3. 检索与纳入材料数量控制更轻，优先围绕显式资料和高相关结果生成。
4. 输出强调“短、准、可汇报”，而不是覆盖尽可能多的子问题。
5. 研究完成后仍可升级为 deep 再次研究。

### 8.5 quick 到 deep 的升级路径

quick 到 deep 不建议设计为一个独立按钮或平行入口，而应视为“重新生成”的一个子场景。

建议规则：

1. 当用户位于 quick 研究详情页并点击“重新生成”时，可在同一交互中选择：
   - 继续 quick
   - 升级为 deep
2. 升级为 deep 后，仍然创建新版本，不覆盖原 quick 结果。
3. 升级时复用以下内容：
   - 原始 task
   - 已确认计划中的可复用部分
   - 已导入资料范围
   - 研究后对话中新增要求
4. 因此，产品层面不再单独提供“升级为 deep”入口，统一收敛到“重新生成”流程内。

### 8.6 当前实现与目标态说明

需要明确：当前代码虽然暴露了 `quick / deep` 两种模式字段，但执行层还没有完全拆成两套独立引擎策略。

因此本次 PRD 中对 quick 的定义属于“目标态定位”：

1. 第一阶段先把 quick 明确定义为“轻量研究模式”。
2. 后续在执行策略上逐步补齐 quick 的轻量化约束。

---

## 9. 数据资产与版本化要求

本次改造要求 Research 从“前端本地会话”升级为“后端研究记录”。

每条研究记录至少应沉淀：

- 研究标题
- 研究状态
- 研究模式
- 研究任务定义
- 研究计划
- 研究结果报告
- 证据引用摘要
- 显式资料范围
- 澄清阶段消息
- 研究后对话消息
- 简要结论
- 版本关系

### 9.1 版本化要求

重新生成不能覆盖既有研究结果。

每次重新生成都应形成一个新的版本，至少具备：

- 当前版本 ID
- 父版本 ID
- 根记录 ID
- 版本号
- 版本创建时间

### 9.2 session_id 关联要求

新记录体系保留与现有 `session_id` 关联的扩展位，但 Phase 1 的主执行恢复不再依赖 session：

1. 运行恢复由 `research_record_runs` + Redis Stream + latest run 元数据承接
2. `session_id` 作为后续多轮上下文扩展位保留
3. 详情页刷新后优先根据 latest run 恢复订阅或读取结果

因此，研究记录应至少保存一个主 `session_id`，必要时允许不同阶段扩展出更多内部运行会话标识。

---

## 10. 兼容与迁移要求

### 10.1 现有能力复用

以下能力应尽量复用现有实现，而不是推翻重做：

- 研究计划生成
- 研究执行 SSE
- 章节重跑
- 证据工作区
- 导出能力

### 10.2 旧数据迁移

Phase 1 不做 localStorage 旧数据迁移。

原因：

1. 旧本地工作台状态不是正式记录模型，迁移成本高且不稳定。
2. 本期优先保证新架构主链路稳定落地。
3. 旧单页工作台在调用点迁移完成后直接下线。

### 10.3 旧接口兼容策略

现有接口：

- `POST /research/plan`
- `POST /research/run`
- `POST /research/sections/rerun`

新架构下建议采取“外层新增 records 资源，内层复用旧执行接口语义”的并存策略：

1. 前端新页面优先调用记录化接口。
2. 记录化接口内部可编排调用现有计划与执行能力。
3. 旧 `research.py` 接口行为保持不变，不改成 Celery 化执行。
4. 新 records 路由独立引入 Celery worker + Redis Stream 模型。

---

## 11. 验收标准

### 11.1 功能验收

1. 用户可以从 `/research` 查看研究记录列表。
2. 用户可以从 `/research/new` 创建新研究。
3. 用户可以生成研究计划并从详情页启动后台研究。
4. 详情页可展示计划、报告、时间线、证据，并支持章节重跑。
5. 新增模板“汇报提纲”“讲话稿”可正常生成计划、执行研究与导出。
6. quick 模式在新架构下仍然作为正式 Research 记录存在，而不是退化为普通 QA。
7. 列表页至少支持标题搜索、归档、删除三项基础能力。
8. 运行中的研究在页面刷新后可基于 latest run 元数据恢复订阅或恢复结果。
9. 章节重跑成功后刷新详情页，报告章节、证据区引用和导出使用的引用集合都以最新结果为准，不回退到旧引用。

### 11.2 数据验收

1. 研究记录可在后端持久化保存。
2. 列表页字段完整可用。
3. 详情页刷新后数据不丢失。
4. 研究记录可独立存储 latest run 元数据与完整 report。
5. 研究记录保留 `session_id` 扩展位，但 Phase 1 不依赖该字段完成恢复。

### 11.3 体验验收

1. 页面拆分后，用户能清晰区分“新建研究”和“查看研究”。
2. 页面刷新或订阅断开后，不会影响后端继续执行。
3. 用户能理解 quick 和 deep 的区别，不会把 quick 误解为 QA。
4. 用户能理解“删除”和“归档”的差异。

---

## 12. 分期建议

### Phase 1

1. 建立后端研究记录模型与列表/详情 API。
2. 前端拆分为列表页、新建页、详情页。
3. 引入 `research_record_reports` 与 `research_record_runs`。
4. 将执行升级为 Celery worker + Redis Stream + SSE 订阅。
5. 接入两个新增模板。
6. 在 UI 和文档中明确 quick / deep 的产品定位。
7. 补齐标题搜索、删除/归档、latest run 元数据、root_record_id 等基础能力。

[Research模块Phase1改造实施计划.md](Research模块Phase1改造实施计划.md)


### Phase 1 实施完成状态（2026-03-27 更新）

**已完成：**

| 功能 | 状态 |
|------|------|
| 后端研究记录模型 (`research_records` / `reports` / `runs`) | ✅ |
| 列表/详情/创建三页拆分 | ✅ |
| Celery worker + Redis Stream + SSE 订阅 | ✅ |
| 列表筛选：标题、状态、模式、模板、时间范围、归档 | ✅ |
| 列表操作：删除、归档 | ✅ |
| 卡片式列表展示（替代表格，优化摘要展示） | ✅ |
| 新建页：模板化研究模式预设、资料篮右侧面板 | ✅ |
| 详情页：计划/报告/时间线/证据/冲突缺口 | ✅ |
| 报告章节：重跑本节、转成新任务 | ✅ |
| 引用快速预览（精确到 chunk，citation_map） | ✅ |
| QA 智能问答引用预览 | ✅ |
| Guide 结构化证据提示 (`hasGuideEvidence`) | ✅ |
| `briefing_outline` / `speech_draft` 模板及默认章节 | ✅ |
| quick / deep 双模式差异化（文档预算、章节数） | ✅ |
| 页面刷新恢复 (latest_run 元数据) | ✅ |
| 全局资料篮抽屉 (ResearchBasketDrawer) | ✅ |
| 导入链路 (`sessionStorage → /research/new`) | ✅ |
| Word / Markdown 导出 | ✅ |
| 删除级联子表清理 | ✅ |
| 并发 run 防重 | ✅ |
| 成功后清空 `last_error` | ✅ |
| SSE 订阅前校验 run 归属 | ✅ |
| archive 排除 running 状态 | ✅ |

**Phase 1 已知限制（不阻塞上线）：**

1. "导入已有研究记录"路径未实现（只有 basket/new）
2. `cancelled` 状态枚举已定义，cancel API 延期 Phase 2
3. 版本链 UI 未实现（`parent_record_id` / `root_record_id` 字段已建）
4. 列表排序选项未实现（默认 `updated_at DESC`）

### Phase 2

1. 增加计划前澄清模式。
2. 增加研究后继续对话。
3. 增加基于反馈重新生成（创建新版本）。
4. 落实版本链派生能力与版本历史 UI。
5. 增加 cancel 能力（Redis flag + 阶段边界检查）。
6. "导入已有研究记录"路径。
7. 列表排序选项。

### Phase 3

1. 版本对比 UI。
2. 优化导出与汇报模板样式。

---

## 13. 风险与决策

### 13.1 主要风险

1. 若继续依赖 localStorage，会导致研究记录列表不可信。
2. 若重新生成直接覆盖旧结果，会破坏追溯能力。
3. 若执行仍绑定当前 HTTP 请求，长时间研究在刷新或断线时会出现体验断层。
4. 若 run 层不做严格用户隔离，会带来越权访问风险。
5. 若不保留服务指南结构化证据，汇报提纲和讲话稿模板会在高频政务场景下明显退化。

### 13.2 关键决策

1. Research 记录必须后端持久化。
2. 重新生成默认创建新版本，不覆盖旧版本。
3. 研究执行采用“Celery 后台任务 + Redis Stream + SSE 订阅”模型。
4. 新架构保留 quick / deep 双模式，且两者都进入记录化流程。
5. 旧 `research.py` 接口行为保持不变，新 records 路由独立承载后台执行能力。

### 13.3 Phase 1 实施决策

以下决策在实施计划评审中确定，与本 PRD 具有同等约束力：

1. Phase 1 不含 cancel 能力。`cancelled` 状态保留在枚举中但不实现 API，Phase 2 再补。
2. 不做 localStorage 旧数据迁移，永不迁移。
3. 直接替换旧页面（ResearchView.vue、SessionSidebar.vue），不保留回退路径。
4. “开始研究”由详情页发起：详情页先调用 `POST /run` 启动 Celery 任务，再订阅 `runs/{run_id}/events`。
5. 研究报告通过独立 API 加载（`GET /records/{id}/report`），详情接口和列表接口均不返回完整 report。
6. 删除规则：仅允许删除 `draft`、`planned`、`failed` 状态的记录。
7. 创建记录时 task 为必填，不允许空 task 创建。
8. `generate plan` 前端统一发送空对象 `{}`，由后端从 `record.task_json` 读取任务。
9. `useSSE` 在 `AbortError` / 组件卸载场景不触发业务完成态 `onDone`，`onDone` 仅表示流自然结束。
10. full run 重订阅前清空 `report + progress + references`；`section_rerun` 重订阅前只清空 `progress + references`，不得清空已有完整报告。
11. `section_rerun` 开始时可将记录置为 `running`，成功和失败都必须恢复为 `completed`；失败只写 `run.error + record.last_error`，不降低记录状态。
12. `section_rerun` 成功后必须同步更新主记录 `references_json`，保证刷新、证据区和导出引用一致。
13. Celery 入队失败必须有补偿：
   - full run 入队失败：`run=failed`、`record.status=failed`、写 `record.last_error`
   - `section_rerun` 入队失败：`run=failed`、写 `run.error + record.last_error`，不降低记录状态