ailine/backend/app/agent_subgraphs/research/README.md

# 研究分析子图 (Research Analysis Subgraph)

该子图负责处理研究分析相关的请求，基于 LangGraph 状态机编排多阶段研究流水线，支持联网搜索、信息提取与验证、结构化报告生成等功能。子图设计遵循"可中断、可恢复、质量优先、透明可追溯"原则，通过内置人工干预点和多源交叉验证保障输出质量。

> **使用公共工具**：意图理解、人工审核、格式化输出、检查点持久化、条件路由、LLM 调用、数据库工具、状态基类

---

## 🎯 核心架构

### 技术栈

| 层级 | 组件 | 说明 |
|:-----|:-----|:-----|
| **编排框架** | LangGraph StateGraph | 状态机驱动的子图工作流编排，支持条件路由与中断恢复 |
| **LLM 服务** | 智谱 AI / DeepSeek API | 意图理解、任务分解、信息提取、报告生成等认知任务（使用公共 LLM 工具） |
| **向量检索** | Qdrant / pgvector | 历史研究结果语义检索，实现记忆增强研究 |
| **关系存储** | PostgreSQL | 研究项目、报告版本、引用记录持久化（使用公共数据库工具） |
| **搜索服务** | 多源搜索 API 网关 | 统一接入通用搜索、学术数据库、专业知识库等外部信息源 |
| **图表生成** | 图表服务 | 趋势图、对比图、分布图等可视化图表自动生成 |

### 子图分层架构

子图采用分层设计，各层职责清晰、边界明确，便于独立测试与演化。

```
┌─────────────────────────────────────────────────────────────────┐
│                        主图 (Main Graph)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ 状态映射 / 结果聚合
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    研究分析子图接口层                            │
│  - 状态转换：主状态 ↔ 子图状态（使用公共状态基类）               │
│  - 错误传播与优雅降级                                            │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                        工作流编排层                              │
│  - 节点调度与条件路由（使用公共路由工具）                        │
│  - 人工干预点暂停/恢复管理（使用公共审核工具）                  │
│  - 状态持久化与检查点（使用公共检查点工具）                        │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                          节点层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │意图理解  │ │任务分解  │ │搜索执行  │ │信息提取  │ │报告生成│ │
│  │(公共工具)│ │          │ │          │ │          │ │        │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │信息源筛选│ │信息整合  │ │结构生成  │ │人工审核  │          │
│  │          │ │          │ │          │ │(公共)    │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                          工具层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │搜索工具集│ │提取工具集│ │验证工具集│ │图表工具集│        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
└─────────────────────────────────────────────────────────────────┘
```

### 数据流总览

研究分析子图的数据流向遵循"输入 → 理解 → 检索 → 处理 → 整合 → 生成 → 审核 → 输出"的线性推进路径，每个阶段的状态变更均被完整记录，支持断点续作。

```
用户研究请求
     │
     ▼
┌─────────────┐
│  意图理解   │ ← 使用公共意图理解工具
└──────┬──────┘
       │
       └─────┐
             ▼
┌─────────────┐
│  任务分解   │
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│  多源搜索   │────▶│ 信息源筛选  │
└─────────────┘     └──────┬──────┘
                           │
                           ▼
┌─────────────┐     ┌─────────────┐
│  报告生成   │◀────│ 报告结构确认│
└──────┬──────┘     └─────────────┘
       │
       ▼
┌─────────────┐
│  格式输出   │ ← 使用公共格式化工具
└──────┬──────┘
       │
       ▼
   返回主图
```

---

## 📂 模块与文件结构

子图代码组织遵循 LangGraph 最佳实践，核心模块职责分明。

```
app/research/
├── __init__.py
├── graph.py              # 子图构建入口，定义状态图与路由
├── state.py              # 子图状态定义（继承公共状态基类）
├── nodes/                # 节点实现
│   ├── __init__.py
│   ├── decomposition.py  # 任务分解节点
│   ├── search.py         # 搜索执行节点
│   ├── extraction.py     # 信息提取节点
│   ├── integration.py    # 信息整合与冲突检测节点
│   ├── structure.py      # 报告结构生成节点
│   └── generation.py     # 报告生成节点
├── tools/                # 子图特有工具集
│   ├── search/           # 搜索工具集
│   ├── extract/          # 信息提取工具集
│   ├── verify/           # 信息验证工具集
│   └── chart/            # 图表生成工具集
└── persistence/          # （使用公共检查点工具，无需单独实现）
```

> **注意**：以下模块使用公共工具，无需单独实现：
> - 意图理解节点 → 使用 `agent_subgraphs.common.intent`
> - 人工审核节点 → 使用 `agent_subgraphs.common.human_loop`
> - 格式输出节点 → 使用 `agent_subgraphs.common.format`
> - 检查点持久化 → 使用 `agent_subgraphs.common.checkpoint`
> - 条件路由 → 使用 `agent_subgraphs.common.routing`
> - LLM 调用 → 使用 `agent_subgraphs.common.llm`
> - 数据库操作 → 使用 `agent_subgraphs.common.db`

---

## 🎯 演进路线与核心机制

研究分析子图的能力演进分为五个层级，每一层在上一层的基座上叠加更复杂的认知与决策能力。

### Level 1：基础单轮研究流水线

**核心机制**：单一意图理解 → 单次搜索 → 简单提取 → 直接报告生成。

- 使用 LLM 解析用户请求，生成搜索关键词。
- 调用通用搜索引擎获取原始结果。
- 基于规则或轻量模型提取关键信息片段。
- 按照预设模板生成 Markdown 格式报告。

**适用场景**：快速知识查询、简单概念解释。

**实现指引**：子图默认配置为完整流水线的最小化变体，通过路由条件识别“简单查询”后走该分支。

### Level 2：多阶段搜索与信息验证

**核心机制**：引入“广度→深度→验证”三轮搜索策略，叠加信息冲突检测与多源交叉验证。

- **第一轮广度搜索**：使用主要关键词并行查询多个信息源，获取广泛上下文。
- **第二轮深度搜索**：基于首轮结果识别出的关键话题，生成细化关键词进行深入检索。
- **第三轮验证搜索**：针对关键事实（如时间、数据、人名）执行验证性搜索，对比多个独立来源。
- **冲突检测**：自动识别不同来源对同一事实的冲突描述，按严重程度分级标记。
- **交叉验证评分**：对每条关键信息计算多源一致性得分，低分项触发人工审核或补充搜索。

**适用场景**：市场调研、事件分析、学术资料整理等对信息准确性要求较高的任务。

**实现指引**：搜索执行节点内部维护搜索轮次状态，每一轮均可动态调整关键词；信息整合节点输出冲突报告。

### Level 3：人工干预点与动态路由

**核心机制**：在关键决策点（信息源确认、报告结构调整）插入人工审核节点，子图挂起等待用户反馈，并根据反馈动态调整后续路由。

- **信息源筛选审核**：自动筛选后的信息源列表（含可信度、时效性评分）展示给用户，用户可增删或调整优先级。
- **报告结构审核**：生成的报告大纲与可视化建议展示给用户，用户可调整章节顺序、增删模块。
- **路由反馈闭环**：
  - 用户要求添加信息源 → 返回搜索执行节点补充检索。
  - 用户调整报告结构 → 重新进入结构生成节点。
  - 关键信息冲突且用户无法裁决 → 返回搜索执行节点补充验证来源。

**适用场景**：专业研究报告、决策支持分析等需要人类专家介入的场景。

**实现指引**：人工审核节点使用 LangGraph 的 `interrupt` 机制实现状态挂起；路由函数读取用户反馈字段决定下一节点。

### Level 4：记忆增强研究

**核心机制**：利用历史研究结果作为上下文，避免重复搜索，提升研究深度与连贯性。

- **语义检索历史**：将当前研究主题与意图向量化，从向量库检索相关历史研究项目。
- **上下文注入**：将匹配到的历史报告摘要、关键结论、已确认信息源作为先验知识注入意图理解与任务分解阶段。
- **增量更新**：对于相似主题的后续研究，仅搜索新增或变化的信息，与历史结果融合生成更新报告。

**适用场景**：周期性行业分析、追踪式课题研究、企业内部知识累积复用。

**实现指引**：在意图理解节点前增加记忆检索步骤，检索结果存入子图状态的 `historical_context` 字段供下游节点消费。

### Level 5：自主研究规划与多模态分析

**核心机制**：子图具备初步的自主规划能力，能够分解开放式研究问题，并协调多模态搜索与分析工具。

- **复杂任务自主分解**：LLM 根据高层研究目标生成多步骤研究计划，包括子任务依赖关系、预期信息源类型。
- **多模态搜索与分析**：除文本外，支持图像、视频、表格数据的搜索与信息提取。
- **质量自评估与迭代**：生成报告后，由 LLM 对报告完整性、一致性进行自评，识别信息缺口并自动触发补充搜索。
- **插件化工具扩展**：第三方可通过标准接口注册自定义搜索源或分析工具。

**适用场景**：综合性行业白皮书撰写、跨领域技术调研、深度竞品分析。

**实现指引**：任务分解节点升级为规划节点，输出结构化的研究计划图；工具调用采用 OpenAI Function Calling 风格统一接口。

---

## 🔧 核心组件详解

### 1. 意图理解节点

**职责**：接收用户原始请求，区分简单查询、深度研究、对比分析等意图类型，评估研究复杂度。

**输入**：用户自然语言请求、历史记忆上下文（可选）。

**输出**：
- `intent_type`：意图类别枚举。
- `complexity_level`：复杂度评分（影响流程分支选择）。
- `clarified_query`：消歧后的核心研究问题。

**实现要点**：
- 使用 LLM 进行少样本分类，输出结构化 JSON。
- 结合关键词匹配与规则兜底（如“对比”、“区别” → 对比分析）。
- 复杂度评分综合考虑用户指定信息源数量、时间范围跨度、是否需要可视化等因素。

### 2. 任务分解节点

**职责**：将复杂研究任务拆解为原子子任务，生成搜索关键词列表，并设计初步报告结构。

**输入**：澄清后的研究问题、意图类型、复杂度评分。

**输出**：
- `sub_tasks`：子任务列表，每个子任务包含描述与预期信息类型。
- `search_keywords`：多组搜索关键词（支持广度/深度/验证轮次）。
- `draft_outline`：初步报告章节大纲。

**实现要点**：
- 针对对比分析类意图，自动生成对比维度矩阵。
- 关键词生成利用 LLM 同义词扩展与上下位词推理能力。
- 初步大纲作为后续报告结构生成的基础框架。

### 3. 搜索执行节点

**职责**：根据搜索策略执行多轮搜索，收集原始信息并记录元数据。

**输入**：搜索关键词组、搜索策略（广度/深度/验证）、信息源偏好。

**输出**：
- `raw_search_results`：原始搜索结果列表，每条包含标题、摘要、URL、来源域名、发布时间。
- `search_metadata`：搜索执行记录（搜索词、时间戳、来源类型）。

**实现要点**：
- 内部调用统一搜索网关，屏蔽不同搜索源的 API 差异。
- 支持并行请求多个搜索源，通过 `asyncio.gather` 提升效率。
- 每条结果附带初始可信度评分（基于域名信誉库与来源类型）。

### 4. 信息源筛选节点（人工干预点）

**职责**：自动筛选低质量信息源，将候选列表提交用户确认，根据反馈决定后续流向。

**输入**：原始搜索结果列表。

**输出**：
- `confirmed_sources`：用户确认使用的信息源列表。
- `user_feedback`：用户添加/删除/优先级调整记录。

**实现要点**：
- 自动筛选规则：排除可信度评分低于阈值的来源、发布时间过旧的内容、已被屏蔽的域名。
- 人工审核界面以简洁列表形式展示信息源，支持多选、拖拽排序。
- 若用户选择“跳过审核”，则直接使用自动筛选后的结果进入下一阶段。

### 5. 信息提取节点

**职责**：从确认后的信息源中提取结构化关键信息，标注实体与术语。

**输入**：确认后的信息源内容（网页全文或摘要）。

**输出**：
- `extracted_fragments`：信息片段列表，每条包含内容文本、提取类型（事实/观点/数据）、来源指针。
- `entity_annotations`：实体识别结果（时间、地点、人物、组织、专业术语）。

**实现要点**：
- 使用 LLM 进行开放式信息抽取，遵循预定义的抽取模式（如“主体-关系-客体”）。
- 对数值类信息（百分比、金额、增长率）进行归一化处理，便于后续对比。
- 每条信息片段保留完整来源元数据，支持最终报告的引用溯源。

### 6. 信息整合与冲突检测节点

**职责**：融合多源信息片段，检测冲突并进行交叉验证，生成结构化信息视图。

**输入**：提取的信息片段列表。

**输出**：
- `integrated_info`：按主题/时间线/对比维度组织的结构化信息。
- `conflict_report`：冲突项列表，含冲突等级与各方陈述。
- `verification_summary`：关键事实的多源验证结果。

**实现要点**：
- 采用聚类算法或 LLM 语义匹配将描述同一事实的片段聚合。
- 冲突检测基于事实三元组比对（如“X 公司市场份额 20%” vs “X 公司市场份额 25%”）。
- 高优先级冲突（如核心数据差异超过阈值）触发路由至人工审核或补充搜索。

### 7. 报告结构生成节点（人工干预点）

**职责**：基于整合后的信息生成详细报告结构，提交用户确认或调整。

**输入**：结构化信息、初步大纲、用户偏好。

**输出**：
- `confirmed_outline`：确认后的报告结构（多级标题）。
- `visualization_suggestions`：建议的图表类型与数据映射。

**实现要点**：
- 报告结构生成考虑信息量分布与逻辑叙事顺序。
- 可视化建议基于数据特征（如时间序列 → 折线图，类别对比 → 柱状图）。
- 用户反馈可触发结构调整或返回信息整合节点重新组织内容。

### 8. 报告生成节点

**职责**：按照确认的结构生成完整报告草稿，自动插入引用标记。

**输入**：确认的报告结构、结构化信息、引用元数据。

**输出**：
- `draft_report`：包含章节内容与引用标记的完整报告文本。
- `citation_map`：引用标记到来源 URL 的映射表。

**实现要点**：
- 使用 LLM 逐章节生成内容，确保风格统一与逻辑连贯。
- 引用标记采用 `[^1]` 脚注风格，在报告末尾聚合展示来源链接。
- 对于数据可视化部分，调用图表服务生成图片并嵌入 Markdown 引用。

### 9. 人工审核节点

**职责**：在特定检查点挂起子图执行，等待用户输入，将反馈存入状态供后续路由消费。

**输入**：待审核内容（信息源列表、报告结构等）。

**输出**：用户反馈（确认、修改指令、取消等）。

**实现要点**：
- 基于 LangGraph `interrupt` 函数实现状态持久化挂起。
- 反馈数据结构化存储，包含操作类型（confirm/modify/cancel）与具体参数。
- 支持超时自动确认（可配置）以保证流程不无限阻塞。

### 10. 最终格式化节点

**职责**：将报告草稿转换为用户指定输出格式，生成执行摘要，准备返回主图。

**输入**：确认后的报告草稿、输出格式偏好。

**输出**：
- `final_report`：格式化后的报告内容。
- `executive_summary`：执行摘要（可选）。
- `suggestions`：后续研究建议（可选）。

**实现要点**：
- 支持 Markdown、HTML、纯文本三种输出格式。
- 执行摘要通过 LLM 从完整报告中提炼核心观点与结论。
- 最终输出聚合到子图状态 `output` 字段，由接口层转换回主状态。

---

## 🔀 条件路由详解

子图内部通过条件路由函数实现动态流程控制，主要路由点如下：

### 入口路由：选择流程模式

- **位置**：意图理解节点之后。
- **条件**：
  - `complexity_level == "simple"` → 简化流程（跳过任务分解与多轮搜索）。
  - `complexity_level in ["moderate", "complex"]` → 完整流程。
- **实现**：路由函数读取状态中的 `complexity_level` 字段返回下一节点名称。

### 搜索策略路由

- **位置**：任务分解节点之后。
- **条件**：
  - 用户要求“快速概览” → 单轮搜索。
  - 用户要求“深度分析” → 多轮搜索（广度→深度→验证）。
  - 意图为“对比分析” → 按对比维度分别搜索后融合。
- **实现**：根据 `intent_type` 与用户偏好字段决定搜索执行节点的内部模式。

### 信息源确认路由

- **位置**：信息源筛选节点（人工干预点）之后。
- **条件**：
  - 用户点击“确认” → 进入信息提取节点。
  - 用户点击“添加信息源” → 返回搜索执行节点，携带补充关键词。
  - 用户点击“调整优先级” → 重新排序后再次进入审核（循环）。
- **实现**：读取 `user_feedback.action` 字段进行路由。

### 冲突处理路由

- **位置**：信息整合节点之后。
- **条件**：
  - 无冲突或仅有低优先级冲突 → 进入报告结构生成。
  - 存在高优先级冲突且用户未选择“忽略” → 进入人工审核节点。
  - 用户要求“补充验证” → 返回搜索执行节点进行第三轮验证搜索。
- **实现**：评估 `conflict_report` 中的最高冲突等级与用户历史选择。

### 报告结构确认路由

- **位置**：报告结构生成节点（人工干预点）之后。
- **条件**：
  - 用户确认 → 进入报告生成节点。
  - 用户要求修改结构 → 重新调用结构生成节点（带修改指令）。
  - 用户要求调整内容 → 返回信息整合节点调整结构化信息。
- **实现**：读取 `user_feedback` 中的结构修改指令进行路由。

### 输出格式路由

- **位置**：最终格式化节点之前。
- **条件**：
  - `output_format == "markdown"` → Markdown 格式化。
  - `output_format == "html"` → HTML 格式化。
  - `output_format == "text"` → 纯文本格式化。
- **实现**：读取用户偏好或默认配置选择格式化器。

---

## 📊 状态设计

子图状态采用 TypedDict 定义，按研究阶段分层组织，完整记录中间产物以支持中断恢复与调试。

### 状态结构概览

| 分组 | 字段 | 类型 | 说明 |
|:-----|:-----|:-----|:-----|
| **输入** | `user_request` | `str` | 用户原始研究请求 |
| | `preferences` | `dict` | 用户指定的信息源、输出格式等偏好 |
| | `historical_context` | `list[dict]` | 记忆检索注入的历史研究摘要 |
| **意图与任务** | `intent_type` | `str` | 意图类别 |
| | `complexity_level` | `str` | 复杂度评级 |
| | `clarified_query` | `str` | 澄清后的核心问题 |
| | `sub_tasks` | `list[dict]` | 子任务列表 |
| | `search_keywords` | `list[list[str]]` | 多轮搜索关键词组 |
| | `draft_outline` | `list[str]` | 初步报告大纲 |
| **搜索与收集** | `raw_search_results` | `list[dict]` | 原始搜索结果（含元数据） |
| | `confirmed_sources` | `list[dict]` | 用户确认使用的信息源 |
| | `user_source_feedback` | `dict` | 用户对信息源的调整记录 |
| **提取与整合** | `extracted_fragments` | `list[dict]` | 结构化信息片段 |
| | `integrated_info` | `dict` | 按主题/时间线组织的整合信息 |
| | `conflict_report` | `list[dict]` | 冲突项列表 |
| | `verification_summary` | `dict` | 关键事实验证结果 |
| **报告生成** | `confirmed_outline` | `list[dict]` | 确认后的报告结构 |
| | `visualization_suggestions` | `list[dict]` | 图表建议 |
| | `draft_report` | `str` | 报告草稿（含引用标记） |
| | `citation_map` | `dict` | 引用标记到来源映射 |
| | `user_structure_feedback` | `dict` | 用户对报告结构的调整 |
| **控制流** | `current_phase` | `str` | 当前执行阶段 |
| | `next_node` | `str` | 下一节点名称 |
| | `interrupt_point` | `str` | 中断点标识 |
| | `error_info` | `dict` | 错误信息（如有） |
| **输出** | `final_report` | `str` | 最终报告内容 |
| | `output_format` | `str` | 输出格式 |
| | `executive_summary` | `str` | 执行摘要 |

### 状态更新原则

- **增量写入**：每个节点只修改其职责范围内的字段，其他字段只读。
- **原子提交**：节点执行成功后才将变更合并到全局状态。
- **版本记录**：每次状态变更均记录前序版本，支持回滚（用于人工审核场景）。
- **持久化友好**：所有字段均可 JSON 序列化，便于通过检查点器持久化。

---

## 🔄 工作流程与中断恢复

### 完整研究流程（四个阶段）

| 阶段 | 步骤 | 节点 | 人工干预 |
|:-----|:-----|:-----|:---------|
| **理解与分解** | 1. 意图理解 | `intent_understanding` | 否 |
| | 2. 任务分解 | `task_decomposition` | 否 |
| **检索与收集** | 3. 多源搜索执行 | `search_execution` | 否 |
| | 4. 信息源筛选与确认 | `source_filtering` | **是** |
| **提取与整合** | 5. 关键信息提取 | `information_extraction` | 否 |
| | 6. 信息整合与冲突检测 | `information_integration` | 否（可能触发审核） |
| **生成与输出** | 7. 报告结构确认 | `structure_generation` | **是** |
| | 8. 报告生成与格式化 | `report_generation` + `final_formatting` | 否 |

### 简化流程（快速查询模式）

当 `complexity_level == "simple"` 时，子图走精简路径：

1. 意图理解（简化版，不拆解任务）。
2. 单次搜索执行（仅广度搜索）。
3. 快速信息提取（不进行深度整合）。
4. 直接生成简短回答（跳过结构确认）。

### 中断与恢复机制

子图支持在以下位置中断并持久化状态：

- 信息源筛选节点（人工干预点 1）
- 报告结构生成节点（人工干预点 2）
- 任意节点执行完成后的检查点（由检查点器自动保存）

**恢复流程**：
1. 主图传入相同的 `thread_id` 与中断前状态。
2. 子图从检查点加载状态，定位 `interrupt_point`。
3. 若中断点为人工审核节点，等待用户反馈后继续执行。
4. 若为其他检查点，直接从下一节点开始执行。

---

## 🔒 安全与边界控制

### 安全机制

| 类别 | 机制 | 实现位置 |
|:-----|:-----|:---------|
| **内容安全** | 搜索关键词过滤、结果内容审查、成人内容屏蔽 | 搜索工具网关 |
| **数据安全** | 用户数据加密存储、传输层 TLS、敏感信息脱敏 | 持久化层与接口层 |
| **访问控制** | 基于角色的功能权限（普通/高级/管理员） | 接口层中间件 |
| **资源限制** | 单用户 QPS 限制、单次研究最大 Token 消耗、最大信息源数量 | 工作流编排层 |
| **审计日志** | 记录所有搜索、提取、生成操作，包含操作者、时间戳、资源消耗 | 各节点内置日志 |

### 人工审核触发边界

以下情况强制进入人工审核节点：

- 信息源可信度平均评分低于阈值。
- 高优先级信息冲突且无法自动裁决。
- 用户请求超出常规研究边界（如要求访问受限领域）。
- 首次使用特定高风险搜索源。

### 错误处理边界

- **可恢复错误**（如单次搜索超时）：自动重试或切换备选搜索源。
- **不可恢复错误**（如 LLM 服务不可用）：终止执行，向主图返回错误状态与友好提示。
- **部分成功**：即使部分子任务失败，仍返回已完成的部分结果（如已提取的信息片段）。

---

## 🛠️ 工具集成

### 工具集概览

| 工具集 | 功能 | 外部依赖 |
|:-------|:-----|:---------|
| **搜索工具集** | 通用网页搜索、学术论文检索、专业知识库查询、新闻资讯获取 | 搜索 API 网关 |
| **信息提取工具集** | 实体识别、数据提取、术语标注、关系抽取、摘要生成 | LLM 服务 |
| **信息验证工具集** | 多源交叉验证、可信度评分、时效性检查、一致性检查 | 域名信誉库、LLM |
| **报告生成工具集** | 内容生成、引用插入、图表生成、格式转换 | LLM、图表服务 |
| **记忆检索工具集** | 历史研究语义检索、项目检索、时间范围检索 | Qdrant / pgvector |

### 工具调用规范

所有工具遵循统一接口规范：

- **输入**：标准字典参数。
- **输出**：标准字典结果，包含 `status`、`data`、`error` 字段。
- **元数据**：每次调用记录调用时间、耗时、资源标识。

### 工具扩展方式

新增工具仅需三步：

1. 在对应工具集中实现标准接口的适配器。
2. 在工具注册表中声明工具元数据（名称、描述、参数模式）。
3. 在相关节点中通过工具名称调用，无需修改节点核心逻辑。

---

## 📑 快速开始（概念级）

研究分析子图作为主图的一个子图节点被调用，典型集成方式如下：

1. **主图路由**：当主图识别到用户意图为“研究分析”时，路由至 `research_subgraph` 节点。
2. **状态映射**：主状态中的 `user_input`、`user_id` 等字段映射到子图状态输入部分。
3. **子图执行**：子图按照上述工作流自主执行，可能在人工干预点挂起。
4. **结果回传**：子图执行完毕后，将 `final_report`、`executive_summary` 等字段回写到主状态。

子图内部配置项（如默认搜索源、重试次数、审核超时）通过环境变量或配置文件管理。

---

## ⚙️ 配置项参考

| 配置项 | 说明 | 默认值 |
|:-------|:-----|:-------|
| `RESEARCH_LLM_MODEL` | 意图理解与生成使用的 LLM 模型 | `deepseek-chat` |
| `SEARCH_API_GATEWAY_URL` | 统一搜索网关地址 | `http://localhost:8080` |
| `SEARCH_DEFAULT_SOURCES` | 默认启用的搜索源列表 | `["web", "news"]` |
| `MAX_SEARCH_ROUNDS` | 最大搜索轮次 | `3` |
| `RERANK_TOP_N` | 信息源筛选保留数量 | `20` |
| `CONFLICT_SEVERITY_THRESHOLD` | 触发人工审核的冲突等级 | `high` |
| `HUMAN_LOOP_TIMEOUT_SEC` | 人工审核超时自动确认时间 | `3600` |
| `VECTOR_DB_URL` | 记忆检索向量库地址 | `http://localhost:6333` |
| `CHART_SERVICE_URL` | 图表生成服务地址 | `http://localhost:3000` |

---

## 🤝 与主系统集成

研究分析子图通过 LangGraph 子图机制与主系统解耦集成：

- **状态隔离**：子图状态字段使用前缀 `research_` 避免与主状态冲突。
- **错误传播**：子图内部异常捕获后转换为标准错误结构向上传递，主图可选择重试或降级。
- **检查点共享**：子图与主图共用同一检查点器后端，确保整体流程的断点续作能力。

子图对外暴露的唯一接口是编译后的 `StateGraph` 实例，主图通过 `builder.add_node("research", research_subgraph)` 将其作为一个节点加入。

---

## 📈 性能考量

- **并行搜索**：多源搜索与多关键词检索采用异步并行，典型场景下搜索阶段耗时控制在 3 秒内。
- **流式报告生成**：报告生成节点支持流式输出，用户在报告结构确认后可实时看到内容逐段生成。
- **结果缓存**：对于相同搜索词在短时间内的重复请求，搜索网关层提供 TTL 缓存。
- **状态压缩**：持久化前对大型字段（如原始搜索结果全文）进行摘要化处理，减少存储开销。

---

## 🔮 未来演进方向

参见需求文档中的详细规划，技术实现层面重点关注：

- **LLM 工具调用标准化**：向 OpenAI Function Calling 风格对齐。
- **多模态管道**：集成图像描述生成与视觉问答模型。
- **插件市场**：提供标准工具接口 SDK，支持第三方搜索源接入。
- **协同研究**：支持多用户对同一研究项目的评论与版本分支管理。