# 开发与系统模块说明

> 本文档由原《开发文档》与《模块说明》合并而成，涵盖开发环境配置、技术栈、架构以及细粒度模块说明。

## 第一部分：开发文档体系

# RAG 知识库问答系统 - 开发文档

> **项目版本**: v7.0.0
> **更新日期**: 2026-04-18
> **文档用途**: 架构说明、技术栈、部署指南

> **API 接口文档**: 详见 [后端对接规范.md](./后端对接规范.md)

---

## 一、项目概述

### 1.1 项目定位

本项目是智能出题系统的**核心知识服务层**，为上层 Dify 工作流提供知识检索能力。系统通过 RAG（检索增强生成）技术，实现基于企业制度文档的智能问答，支持：

- **知识库问答**：基于向量检索 + BM25 + Rerank 的混合检索
- **Agentic RAG**：智能问答流程（Query Rewriting、Context Compression、Answer Grounding）
- **多轮对话**：会话历史管理、代词消解
- **图谱推理**：基于 Neo4j 的多跳关系查询（可选）
- **网络搜索**：实时信息获取（可选，需配置 Serper API）

### 1.2 系统架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                          前端应用层                                  │
│                    (chat-ui/ 开发测试界面)                           │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ HTTP API / SSE
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       API 服务层 (api/)                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   /chat     │  │    /rag     │  │ /sessions   │  │  /search   │ │
│  │ 智能聊天    │  │ SSE 流式问答│  │ 会话管理    │  │ 混合检索   │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘ │
└─────────┼────────────────┼────────────────┼───────────────┼────────┘
          │                │                │               │
          ▼                ▼                ▼               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       核心能力层 (core/)                             │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                     Agentic RAG (agentic.py)                 │   │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────────┐ │   │
│  │  │  Query    │  │  检索层   │  │  Context  │  │  Answer  │ │   │
│  │  │ Rewriting │  │向量+BM25  │  │Compression│  │ Grounding│ │   │
│  │  │ 统一入口  │  │ +Rerank   │  │ Token控制 │  │ 幻觉闭环 │ │   │
│  │  └───────────┘  └───────────┘  └───────────┘  └──────────┘ │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       数据存储层                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │  ChromaDB   │  │   .data/    │  │  SQLite     │  │ documents/ │ │
│  │  向量数据库  │  │  图片存储   │  │  会话数据   │  │  文档源    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```

### 1.3 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| API 服务 | Flask + Flask-CORS | RESTful API，SSE 流式返回 |
| 文档解析 | MinerU 3.0+ | PDF/DOCX/PPTX/图片统一解析 |
| 向量检索 | ChromaDB + BGE-base-zh | 本地向量数据库 + 嵌入模型 |
| 关键词检索 | BM25 + jieba | 中文分词 + 倒排索引 |
| 重排序 | BGE-reranker-base | CrossEncoder 精排 |
| 大模型 | Qwen (通义千问) | 问答生成、实体提取 |
| 数据库 | SQLite | 会话管理、审计日志 |

---

## 二、项目结构

```
├── main.py                  # 统一启动入口
├── config.py                # API 配置（需自行创建）
├── requirements.txt         # 依赖列表
│
├── api/                     # API 路由层（Flask Blueprint）
│   ├── __init__.py          #   create_app() 应用工厂
│   ├── chat_routes.py       #   /chat, /rag (SSE), /search
│   ├── session_routes.py    #   /sessions, /history
│   ├── auth_routes.py       #   /health, /auth/me
│   ├── kb_routes.py         #   /collections
│   ├── document_routes.py   #   /documents/upload
│   ├── sync_routes.py       #   /sync
│   ├── image_routes.py      #   /images/<id>
│   └── feedback_routes.py   #   /feedback
│
├── core/                    # RAG 核心引擎
│   ├── agentic.py           #   AgenticRAG 智能问答
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 索引
│   ├── chunker.py           #   文本分块
│   ├── query_classifier.py  #   查询分类器
│   ├── confidence_gate.py   #   置信度门控
│   ├── quality_assessor.py  #   质量评估器
│   ├── loop_guard.py        #   循环防护
│   └── reasoning_reflector.py # 推理反思器
│
├── parsers/                 # 文档解析器
│   ├── mineru_parser.py     #   MinerU 统一解析 (PDF/DOCX/PPTX/图片)
│   ├── excel_parser.py      #   Excel 专属管道
│   └── image_extractor.py   #   图片噪音过滤
│
├── knowledge/               # 知识库管理
│   ├── manager.py           #   多向量库管理器
│   ├── router.py            #   知识库路由器
│   └── sync.py              #   同步服务
│
├── services/                # 业务服务
│   ├── session.py           #   会话管理 (SQLite)
│   ├── audit.py             #   审计日志
│   └── feedback.py          #   反馈系统
│
├── auth/                    # 认证与安全
│   ├── gateway.py           #   网关认证 (DEV_MODE mock token)
│   └── security.py          #   安全防护
│
├── data/                    # SQLite 数据库
│   ├── db.py                #   统一数据访问层
│   ├── rag_core.db          #   会话/审计数据
│   └── knowledge.db         #   知识管理数据
│
├── .data/                   # 运行时数据
│   ├── files/images/        #   提取的图片
│   └── mineru_output/       #   MinerU 解析输出
│
├── chat-ui/                 # 前端测试界面
│   ├── index.html           #   主页面
│   ├── app.js               #   主逻辑
│   └── api-test.js          #   API 测试面板
│
├── docs/                    # 文档
│   ├── 后端对接规范.md       #   API 接口规范 (主要)
│   ├── 开发文档.md           #   本文档
│   └── ...
│
├── scripts/                 # 工具脚本
│   └── analyze_chunks.py    #   切片分析
│
├── tools/                   # 开发工具
│   └── export_chunks.py     #   导出切片
│
└── exam_pkg/                # 出题系统（可选）
    ├── manager.py           #   出题与批卷
    └── api.py               #   Flask Blueprint
```

---

## 三、Agentic RAG 流程

### 3.1 完整流程图

```
用户问题 (query)
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  1. Query Rewriting（统一入口）                              │
│     - 有历史对话 → 强制改写（消歧）                           │
│     - 短查询 (<10字符) → 强制改写（扩展）                     │
│     - 其他 → LLM 判断是否需要改写                            │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  2. 查询分类 (QueryClassifier)                              │
│     - FACT: 事实查询 → 直接检索                              │
│     - COMPARISON: 比较查询 → 分解检索                        │
│     - META: 元问题 → 直接回答                                │
│     - REALTIME: 实时信息 → 网络搜索（可选）                   │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  3. 检索流程                                                 │
│     - 向量检索 + BM25 + Rerank                               │
│     - 置信度门控检查 (threshold=0.3)                         │
│     - 多维质量评估 (相关性/完整性/准确性/覆盖率)              │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Context Compression                                      │
│     - Rerank 过滤 (score < 0.3 丢弃)                         │
│     - 去重 (相同来源+页码只保留一个)                          │
│     - Token 控制 (max=3500 tokens, max=20 条)               │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  5. 答案生成                                                 │
│     - 多源融合 (知识库 + 网络 + 图谱)                        │
│     - 来源标注                                               │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  6. Answer Grounding（幻觉闭环）                             │
│     - 幻觉检测 (推理反思器)                                  │
│     - 发现幻觉 → 补充检索 → 重新生成                         │
│     - 最多重试 1 次                                          │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│  7. 输出                                                     │
│     - answer: 回答内容                                       │
│     - sources: 来源列表（已去重，含页码范围）                 │
│     - images/tables: 富媒体信息                              │
│     - session_id: 会话ID（用于多轮对话）                      │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 关键配置参数

| 参数 | 值 | 说明 |
|------|-----|------|
| `MAX_CONTEXT_TOKENS` | 3500 | 上下文最大 token 数 |
| `MAX_CONTEXT_COUNT` | 20 | 上下文最大条数 |
| `RERANK_THRESHOLD` | 0.3 | Rerank 过滤阈值 |
| `MAX_GROUNDING_RETRY` | 1 | 幻觉修正最多重试次数 |
| `max_iterations` | 3 | 最大迭代检索次数 |

---

## 四、API 接口

> **详细 API 文档**: 详见 [后端对接规范.md](./后端对接规范.md)

### 核心接口概览

| 接口 | 方法 | 说明 |
|------|------|------|
| `/chat` | POST | 智能聊天 |
| `/rag` | POST | 知识库问答（SSE 流式） |
| `/search` | POST | 混合检索（供 Dify 调用） |
| `/sessions` | GET | 会话列表 |
| `/history/<id>` | GET | 会话历史 |
| `/collections` | GET | 向量库列表 |
| `/images/<id>` | GET | 获取图片 |
| `/sync` | POST | 触发同步 |
| `/health` | GET | 健康检查 |

---

## 五、开发环境配置

### 5.1 环境准备

```powershell
# 创建虚拟环境
python -m venv venv
.\venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt
```

### 5.2 配置文件

复制 `config.example.py` 为 `config.py`：

```python
# config.py - 必需配置

# 通义千问 API（必需）
DASHSCOPE_API_KEY = "your-api-key"
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
DASHSCOPE_MODEL = "qwen-flash"           # 文本模型
DASHSCOPE_VL_MODEL = "qwen-vl-plus"      # 视觉模型（图片描述）

# 兼容变量
API_KEY = DASHSCOPE_API_KEY
BASE_URL = DASHSCOPE_BASE_URL
MODEL = DASHSCOPE_MODEL

# 文档路径
DOCUMENTS_PATH = "./documents"

# 开发模式（支持 mock 用户）
DEV_MODE = True
```

### 5.3 开发模式特性

| 特性 | 说明 |
|------|------|
| Mock 用户 | 支持 `mock-token-admin` 等模拟 token |
| 本地登录 | `/auth/login` 接口支持用户名密码登录 |
| 会话存储 | SQLite 本地存储，无需外部数据库 |
| 前端界面 | `http://localhost:5001` 直接访问测试 |

**模拟用户列表**：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | admin |
| manager | manager123 | manager |
| user | test123 | user |

---

## 六、运行命令

### 6.1 启动服务

```powershell
# 激活虚拟环境
.\venv\Scripts\Activate.ps1

# 启动服务
python main.py                  # 端口 5001
python main.py --port 8080      # 指定端口
```

### 6.2 同步知识库

```powershell
# 通过 API 触发同步
curl -X POST http://localhost:5001/sync

# 或通过前端界面操作
```

---

## 七、会话管理

### 7.1 多轮对话流程

```
首次对话:
POST /rag { "message": "出差补助标准", "collections": ["public_kb"] }
    ↓
finish 事件返回 session_id
    ↓
前端保存 session_id

后续对话:
POST /rag { "message": "它有什么限制", "session_id": "xxx", "collections": ["public_kb"] }
    ↓
RAG 服务自动从 SQLite 加载历史
    ↓
Query Rewriting: "它" → "出差补助"
    ↓
生成带上下文的回答
```

### 7.2 会话相关 API

| 接口 | 说明 |
|------|------|
| `GET /sessions` | 获取用户会话列表 |
| `GET /history/<session_id>` | 获取会话历史 |
| `DELETE /session/<session_id>` | 删除会话 |

---

## 八、部署指南

### 8.1 生产环境建议

| 项目 | 建议 |
|------|------|
| DEV_MODE | 设置为 `false` |
| WSGI 服务器 | gunicorn 或 uWSGI |
| 反向代理 | Nginx |
| HTTPS | 配置 SSL 证书 |

### 8.2 职责边界

| 后端负责 | RAG 服务负责 |
|----------|--------------|
| 用户认证 | 知识库问答 |
| 权限判断 | 向量检索 |
| 会话管理（生产） | 返回溯源 |
| 消息存储 | 文档处理 |

---

## 九、错误码说明

| 状态码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查请求体格式 |
| 401 | 未认证 | 检查 Header 认证信息 |
| 403 | 权限不足 | 检查用户角色权限 |
| 404 | 资源不存在 | 检查 session_id 或资源路径 |
| 500 | 服务器内部错误 | 查看服务日志 |

---

## 十、相关文档

- [后端对接规范.md](./后端对接规范.md) - API 接口规范（主要）
- [数据库设计文档.md](./数据库设计文档.md) - 数据库结构
- [模块说明.md](./模块说明.md) - 模块详细说明
- [Agentic_RAG完整指南.md](./Agentic_RAG完整指南.md) - Agentic RAG 详解


---

## 第二部分：模块规范体系

# 项目模块说明文档 (v6.1.0)

> **注**：本项目经过大规模重构，采用模块化架构。当前版本已包含细粒度多向量库权限控制、文档生命周期跟踪、本地化自动出题系统及FAQ问答闭环反馈收集。

## 项目架构概览

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              API 服务层                                      │
│                            main.py (入口)                                   │
│    (Flask 应用工厂，整合所有 Blueprint，提供 REST API)                        │
└─────────────────────────────────────────────────────────────────────────────┘
         │         │         │         │         │         │         │
         ▼         ▼         ▼         ▼         ▼         ▼         ▼
┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
│ RAG 核心 ││  图谱模块 ││ 出题系统 ││ 安全模块 ││ 同步服务 ││ 反馈闭环 ││ 纲要生成 │
│core/     ││graph/    ││exam_pkg/ ││auth/     ││knowledge/││services/ ││services/ │
│agentic.py││graph_    ││manager.py││gateway.py││sync.py   ││feedback.py││outline.py│
│engine.py ││manager.py││api.py    ││security.py││          ││          ││          │
│bm25_     ││entity_   ││local_db.py││          ││          ││          ││          │
│index.py  ││extractor ││analysis.py││          ││          ││          ││          │
│chunker.py││graph_rag ││question_ ││          ││          ││          ││          │
│          ││graph_    ││hook.py   ││          ││          ││          ││          │
│          ││build.py  ││          ││          ││          ││          ││          │
└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘
     │                                                    │
     ▼                                                    │
┌──────────────────────────┐                              │
│   多向量库管理            │                              │
│ knowledge/manager.py     │                              │
│ knowledge/router.py      │                              │
└──────────────────────────┘                              │
                              ┌─────────────────────┼─────────────────────┐
                              │                     │                     │
                              ▼                     ▼                     ▼
                       ┌──────────┐          ┌──────────┐          ┌──────────┐
                       │会话管理  │          │题库分析  │          │ 审计日志 │
                       │services/ │          │exam_pkg/ │          │services/ │
                       │session.py│          │analysis.py│         │audit.py  │
                       └──────────┘          └──────────┘          └──────────┘
```

---

## 目录结构

```
项目根目录/
├── main.py                  # ✨ 统一启动入口（推荐）
├── config.py                # API 配置（不提交）
├── config.example.py        # API 配置模板
├── requirements.txt         # 依赖列表
│
├── api/                     # API 路由层（Flask Blueprint）
│   ├── __init__.py          #   create_app() 应用工厂
│   ├── chat_routes.py       #   /chat, /rag, /rag/stream, /search
│   ├── session_routes.py    #   /sessions, /history, /session, /clear
│   ├── auth_routes.py       #   /stats, /health, /auth/me
│   ├── audit_routes.py      #   /audit/logs
│   ├── kb_routes.py         #   /collections, /documents/sync, /kb/route
│   ├── document_routes.py   #   /documents/upload, /documents/list, 版本管理
│   ├── sync_routes.py       #   /sync, /subscribe, /notifications
│   ├── graph_routes.py      #   /graph/search, /graph/build, /graph/stats
│   ├── question_routes.py   #   /questions/*, /knowledge-points
│   ├── outline_routes.py    #   /outline/*, /recommend/*
│   ├── feedback_routes.py   #   /feedback/*, /reports/*, /faq/*
│   └── image_routes.py      #   图片相关接口
│
├── core/                    # RAG 核心引擎
│   ├── __init__.py
│   ├── agentic.py           #   AgenticRAG 智能问答
│   ├── engine.py            #   检索引擎封装
│   ├── bm25_index.py        #   BM25 关键词索引
│   ├── chunker.py           #   语义分块器
│   ├── query_classifier.py  #   查询分类器
│   ├── confidence_gate.py   #   置信度门控
│   ├── quality_assessor.py  #   质量评估器
│   ├── reasoning_reflector.py # 推理反思器
│   └── loop_guard.py        #   循环防护
│
├── parsers/                 # 文档解析器
│   ├── __init__.py
│   ├── mineru_parser.py      #   MinerU 统一解析（PDF/DOCX/PPTX/图片）
│   ├── pdf_mineru.py         #   MinerU PDF 兼容别名
│   ├── excel_parser.py       #   Excel 解析（Pandas 管道）
│   ├── txt_parser.py         #   TXT 解析
│   └── image_extractor.py   #   图片提取器
│
├── knowledge/               # 知识库管理模块
│   ├── __init__.py
│   ├── manager.py           #   多向量库管理器
│   ├── router.py            #   知识库路由器
│   ├── sync.py              #   同步服务
│   ├── lifecycle.py         #   文档生命周期
│   ├── diff.py              #   文档差异分析
│   └── vector_store/        #   向量数据库与BM25索引
│       ├── chroma/          #   ChromaDB存储
│       └── bm25/            #   BM25索引存储
│
├── exam_pkg/                # 考试系统
│   ├── __init__.py
│   ├── manager.py           #   出题与批卷
│   ├── api.py               #   Flask Blueprint (exam_bp)
│   ├── analysis.py          #   考试分析
│   ├── local_db.py          #   本地题库
│   └── question_hook.py     #   题目维护钩子
│
├── services/                # 业务服务
│   ├── __init__.py
│   ├── session.py           #   会话管理
│   ├── audit.py             #   审计日志
│   ├── feedback.py          #   反馈质量闭环
│   ├── outline.py           #   纲要生成与推荐
│   └── user_info.py         #   用户信息服务
│
├── auth/                    # 认证与安全
│   ├── __init__.py
│   ├── gateway.py           #   网关认证
│   └── security.py          #   输入/输出安全
│
├── data/                    # SQLite 数据库
│   ├── __init__.py
│   ├── db.py                #   统一数据访问层
│   ├── rag_core.db          #   核心数据（会话、审计、反馈）
│   ├── knowledge.db         #   知识管理（同步、大纲、版本）
│   └── exam.db              #   出题系统（题目、试卷、批卷）
│
├── graph/                   # 知识图谱
│   ├── __init__.py
│   ├── graph_manager.py     #   Neo4j 图谱管理
│   ├── entity_extractor.py  #   实体提取器
│   ├── graph_rag.py         #   图谱增强检索
│   └── graph_build.py       #   图谱构建工具
│
├── documents/               # 知识库文档目录
├── models/                  # 本地模型目录
├── scripts/                 # 工具脚本
│   ├── migrate_version_status.py  # 版本状态迁移
│   ├── rebuild_multi_kb.py        # 重建多向量库
│   ├── run_exam.py                # 运行考试
│   └── test_rag_questions.py      # RAG问题测试
├── tests/                   # 测试
├── chat-ui/                 # 前端界面
├── venv/                    # 虚拟环境
│
```

> **注意**: 根目录下的 `.py` 文件大多已迁移至子包，保留仅为向后兼容。
> 新代码请使用子包路径导入，如 `from auth.gateway import require_gateway_auth`。

---

## 模块详细说明

### 一、API 路由层 (api/)

#### 1. `api/__init__.py` - 应用工厂

**职责**：创建并配置 Flask 应用，注册所有 Blueprint

**主要功能**：
- 初始化共享服务（SessionManager、AuditLogger、AgenticRAG）
- 注册所有 API Blueprint
- 可选模块按需加载

**使用方式**：
```python
from api import create_app

app = create_app()
app.run(host='0.0.0.0', port=5001)
```

#### 2. API Blueprint 分组

| Blueprint | 文件 | 端点前缀 | 主要功能 |
|-----------|------|----------|----------|
| `auth_bp` | auth_routes.py | - | /stats, /health, /auth/me |
| `session_bp` | session_routes.py | - | /sessions, /history, /session, /clear |
| `audit_bp` | audit_routes.py | - | /audit/logs |
| `chat_bp` | chat_routes.py | - | /chat, /rag, /rag/stream, /search |
| `kb_bp` | kb_routes.py | - | /collections, /documents/sync, /kb/route |
| `document_bp` | document_routes.py | - | /documents/upload, /documents/list |
| `sync_bp` | sync_routes.py | - | /sync, /subscribe, /notifications |
| `graph_bp` | graph_routes.py | - | /graph/search, /graph/build, /graph/stats |
| `question_bp` | question_routes.py | - | /questions/*, /knowledge-points |
| `outline_bp` | outline_routes.py | - | /outline/*, /recommend/* |
| `feedback_bp` | feedback_routes.py | - | /feedback/*, /reports/*, /faq/* |
| `image_bp` | image_routes.py | - | 图片上传、处理相关接口 |
| `exam_bp` | exam_pkg/api.py | /exam | 出题系统相关接口 |

---

### 二、核心 RAG 模块 (core/)

#### 3. `core/agentic.py` - Agentic RAG 核心

**职责**：智能问答的 Agent 决策引擎

**主要功能**：
- Agent 决策循环（检索、改写、分解、回答）
- 网络搜索集成（Serper API）
- 图谱检索集成
- 多源结果融合
- SSE 流式输出

**关键类/函数**：
| 类/函数 | 说明 |
|---------|------|
| `AgenticRAG` | 主类，封装所有 Agent 功能 |
| `process()` | 处理用户查询 |
| `chat_search()` | 聊天搜索（支持网络搜索） |
| `simple_query()` | 简化调用接口 |

**使用方式**：
```python
from core.agentic import AgenticRAG, simple_query

# 完整模式
rag = AgenticRAG()
result = rag.process("出差补助标准是什么？")

# 简化模式
result = simple_query("出差补助标准")
```

#### 4. `core/engine.py` - 检索引擎封装

**职责**：统一的检索引擎接口

**主要功能**：
- 向量检索
- BM25 关键词检索
- 混合检索 + Rerank

#### 5. `core/bm25_index.py` - BM25 索引管理

**职责**：BM25 关键词索引的构建和查询

#### 6. `core/query_classifier.py` - 查询分类器

**职责**：对用户查询进行意图分类，辅助选择合适的检索策略

#### 7. `core/confidence_gate.py` - 置信度门控

**职责**：基于置信度判断是否需要额外的检索或改写

#### 8. `core/quality_assessor.py` - 质量评估器

**职责**：评估检索结果和生成回答的质量

#### 9. `core/reasoning_reflector.py` - 推理反思器

**职责**：对推理过程进行反思和优化

#### 10. `core/loop_guard.py` - 循环防护

**职责**：防止 Agent 陷入无限循环，控制最大迭代次数

---

### 三、知识库管理模块 (knowledge/)

#### 11. `knowledge/manager.py` - 多向量库管理器

**职责**：多向量库的创建、管理和检索

**主要功能**：
- 多向量库创建与管理（public_kb + dept_xxx）
- 每个向量库独立的 BM25 索引
- 并行检索多个向量库
- RRF 融合结果

**使用方式**：
```python
from knowledge.manager import get_kb_manager

kb_manager = get_kb_manager()

# 创建向量库
kb_manager.create_collection('dept_finance', display_name='财务部知识库')

# 检索
results = kb_manager.search_multiple(['public_kb', 'dept_finance'], query_vector)
```

#### 12. `knowledge/router.py` - 知识库路由器

**职责**：根据查询意图和用户权限智能选择目标向量库

**主要功能**：
- 规则匹配（关键词识别部门）
- LLM 意图分析（复杂查询）
- 权限过滤

#### 13. `knowledge/sync.py` - 知识库同步服务

**职责**：自动检测文档变更并触发增量更新

---

### 四、数据库模块 (data/)

#### 14. `data/db.py` - 统一数据访问层

**职责**：集中管理所有数据库连接

**主要功能**：
- 统一数据库路径配置
- 连接池管理（上下文管理器）
- WAL 模式 + 外键约束
- 自动事务管理

**数据库架构**：
| 数据库 | 主要功能 |
|--------|----------|
| `rag_core.db` | 会话、审计、反馈、FAQ |
| `knowledge.db` | 同步、大纲、文档版本 |
| `exam.db` | 题目、试卷、批卷、分析 |

**使用方式**：
```python
from data.db import get_connection, init_databases

# 初始化数据库
init_databases()

# 使用连接
with get_connection("core") as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM sessions WHERE user_id = ?", (user_id,))
    rows = cursor.fetchall()
```

---

### 五、出题系统模块 (exam_pkg/)

#### 15. `exam_pkg/manager.py` - 出题核心逻辑

**职责**：试卷生成、保存、批阅的核心业务逻辑

**主要功能**：
- 调用 Dify 工作流生成试卷
- 试卷 CRUD 操作
- 审核流程管理
- 自动批阅与报告生成

#### 16. `exam_pkg/api.py` - 出题系统 API

**职责**：出题系统的 Flask Blueprint

**API 端点**：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/exam/generate-by-file` | POST | 按文件生成题目（带溯源） |
| `/exam/generate` | POST | 生成试卷 |
| `/exam/list` | GET | 获取试卷列表 |
| `/exam/<id>` | GET/PUT/DELETE | 试卷 CRUD |
| `/exam/grade-from-mysql` | POST | 基于 MySQL 数据批卷 |

#### 17. `exam_pkg/analysis.py` - 题库分析模块

**职责**：题目与制度文档关联、知识点分析

---

### 六、服务模块 (services/)

#### 18. `services/session.py` - 会话管理

**职责**：多用户对话历史管理

**主要功能**：
- 会话创建与管理
- 消息历史存储
- 上下文压缩
- 会话过期清理

**使用方式**：
```python
from services.session import SessionManager

sm = SessionManager()
session_id = sm.create_session("user_123")
sm.add_message(session_id, "user", "出差补助标准是什么？")
history = sm.get_history(session_id)
```

#### 19. `services/audit.py` - 审计日志

**职责**：用户操作审计

**主要功能**：
- 记录查询日志
- 记录检索结果
- 日志查询

#### 20. `services/feedback.py` - 反馈服务

**职责**：用户反馈收集与 FAQ 自动沉淀

#### 21. `services/outline.py` - 纲要生成器

**职责**：自动生成文档结构纲要

---

### 七、认证与安全模块 (auth/)

#### 22. `auth/gateway.py` - 网关认证

**职责**：网关注入的 Header 认证与多向量库权限控制

**主要功能**：
- 从 Header 读取用户信息（X-User-ID、X-User-Role、X-User-Department）
- 角色映射
- 多向量库权限控制
- `@require_gateway_auth` 装饰器

**网关注入的 Header**：
| Header | 说明 |
|--------|------|
| `X-User-ID` | 用户唯一标识 |
| `X-User-Name` | 用户名 |
| `X-User-Role` | 用户角色 |
| `X-User-Department` | 部门 |

#### 23. `auth/security.py` - 安全防护

**职责**：Prompt 注入防护

---

### 八、图谱模块 (graph/)

> **注意**：图谱模块为可选功能，需在 `config.py` 中配置 `USE_GRAPH_RAG=True` 和 Neo4j 连接。

#### 24. `graph/graph_manager.py` - 图谱管理器

**职责**：Neo4j 图数据库管理

#### 25. `graph/entity_extractor.py` - 实体提取器

**职责**：使用 LLM 从文本提取实体和关系

#### 26. `graph/graph_rag.py` - 图谱 RAG

**职责**：图谱增强检索

#### 27. `graph/graph_build.py` - 图谱构建工具

**使用方式**：
```bash
python -m graph.graph_build --stats
python -m graph.graph_build --file documents/xxx.pdf
```

---

## 数据库文件说明

| 文件名 | 主要功能 | 详细文档 |
|--------|----------|----------|
| `data/rag_core.db` | 会话管理、审计日志、用户反馈、FAQ | [数据库设计文档.md](./数据库设计文档.md) |
| `data/knowledge.db` | 知识库同步、文档哈希、纲要缓存、版本管理 | [数据库设计文档.md](./数据库设计文档.md) |
| `data/exam.db` | 题目存储、试卷管理、批阅记录、分析报告 | [数据库设计文档.md](./数据库设计文档.md) |
| `knowledge/vector_store/` | 多向量库存储（ChromaDB） | [多向量库实现权限划分.md](./多向量库实现权限划分.md) |

---

## 运行命令

```powershell
# ✨ 推荐方式 - 新入口
python main.py                  # 启动 API 服务（端口 5001）
python main.py --port 8080      # 指定端口

# 旧入口（仍可用）
python main.py                  # 启动统一网关与大模型 API 服务
python scripts/test_rag_questions.py  # 自动化问答自评估测试
python scripts/rebuild_multi_kb.py    # 强制重建各个部门/集合维度的知识库
```

---

## 相关文档

- [API接口文档.md](./API接口文档.md) - REST API 详细说明
- [数据库设计文档.md](./数据库设计文档.md) - 所有数据库结构
- [认证与权限配置指南.md](./认证与权限配置指南.md) - 网关认证说明
- [多向量库实现权限划分.md](./多向量库实现权限划分.md) - 权限架构说明

---

## 最后更新

- 文档版本：v6.1.0
- 更新时间：2026-04-16
- 主要更新：
  - 补充 core/ 目录新增模块（query_classifier、confidence_gate、quality_assessor、reasoning_reflector、loop_guard）
  - 补充 api/ 目录新增的 image_routes.py
  - 补充 parsers/ 目录新增的 image_extractor.py
  - 修正 knowledge/ 目录重复描述，合并 vector_store 子目录说明
  - 补充 scripts/ 目录实际存在的脚本文件
  - 重新编号所有模块说明章节