AIclinicalresearch/docs/03-业务模块/PKB-个人知识库/00-模块当前状态与开发指南.md

# PKB个人知识库模块 - 当前状态与开发指南

> **文档版本：** v2.3  
> **创建日期：** 2026-01-07  
> **维护者：** PKB模块开发团队  
> **最后更新：** 2026-01-21  
> **🎉 重大里程碑：** **成功替换 Dify！完全使用自研 pgvector RAG 引擎！**  
> **技术架构：** ✅ PostgreSQL + pgvector 0.8.1 + DeepSeek V3 查询理解 + qwen3-rerank  
> **架构变更：** 知识库引擎完全迁移至 `common/rag/`，移除 Dify 依赖  
> **文档目的：** 反映模块真实状态，记录开发历程

---

## 📋 文档说明

本文档是PKB个人知识库模块的**真实状态快照**，如实记录当前开发状态、技术架构和已知问题。

**与其他文档的关系**：
- **本文档（00-模块当前状态）**：What is（真实状态，包括问题）
- **需求分析文档**：What to do（产品需求）
- **开发记录文档**：What done（开发历程）
- **技术设计文档**：How to do（设计方案）

---

## 🎯 模块概述

### 核心功能

PKB（Personal Knowledge Base）个人知识库模块提供：
- 🗂️ **知识库管理**：创建、编辑、删除个人知识库
- 📄 **文档管理**：上传、处理、组织文档（PDF/Word/TXT/MD）
- 🤖 **AI问答**：基于知识库内容的智能问答
- 📊 **批处理**：批量提取文档信息，生成结构化数据

### 当前状态

| 组件 | 状态 | 完成度 | 说明 |
|------|------|--------|------|
| **后端API** | ✅ 已完成 | 100% | v1 + v2双路由运行 |
| **前端Dashboard** | ✅ 已完成 | 95% | 基于V5原型实现 |
| **前端Workspace** | ✅ 已完成 | 95% | 基于V3原型实现 |
| **全文阅读模式** | ✅ 已完成 | 95% | Chat组件集成完成 |
| **逐篇精读模式** | ✅ 已完成 | 95% | 文档选择+对话 |
| **批处理模式** | ✅ 已完成 | 95% | 完整流程+结果导出 |
| **文档上传** | ✅ 已完成 | 100% | 拖拽+进度显示+pgvector入库 |
| **RAG检索模式** | ✅ 已完成 | 100% | 🎉 **2026-01-21 完成！替换 Dify** |

**整体完成度：约95%** 🎉

---

## 🏗️ 技术架构

### 前端技术栈

```
框架: React 19 + TypeScript 5
路由: React Router DOM v7
状态管理: Zustand
UI组件: Ant Design v6 + Ant Design X
样式: TailwindCSS v3
构建工具: Vite 7
```

### 后端技术栈

```
框架: Fastify v4 (Node.js 22)
数据库: PostgreSQL 15 + Prisma 6 + pgvector 0.8.1
Schema: pkb_schema (业务数据) + ekb_schema (向量数据)
向量存储: pgvector (PostgreSQL原生向量扩展) ✅ 2026-01-19 已集成
Embedding: 阿里云 text-embedding-v4 (1024维) ✅
查询理解: DeepSeek V3 (中英双语翻译) ✅
重排序: 阿里云 qwen3-rerank ✅
LLM: DeepSeek-V3, Qwen-Max (通过LLMFactory)
RAG: 自研 pgvector 引擎 (common/rag/) ✅ 2026-01-21 完成
存储: OSS对象存储 (待完善)
```

### 依赖的通用能力层

| 通用能力 | 用途 | 状态 |
|----------|------|------|
| **RAG 引擎** | 文档入库、向量检索、Rerank | ✅ **2026-01-21 完成** |
| **文档处理引擎** | PDF/Word/Excel → Markdown | ✅ 已就绪 |
| **LLM 网关** | 大模型调用 | ✅ 已接入 |
| **存储服务** | 文档存储到 OSS | 🔧 待完善 |

> 📍 **架构说明**：2026-01-21 **成功替换 Dify**，完全使用自研 pgvector RAG 引擎。  
> PKB 模块调用 `common/rag/` 中的服务（EmbeddingService、VectorSearchService、DocumentIngestService）。  
> 详见 [RAG 引擎使用指南](../../02-通用能力层/03-RAG引擎/05-RAG引擎使用指南.md)

### API路由

```
# 新架构 (v2)
/api/v2/pkb/knowledge         # 知识库CRUD
/api/v2/pkb/knowledge/:id     # 知识库详情
/api/v2/pkb/documents         # 文档管理

# 旧架构 (v1，保持兼容)
/api/v1/knowledge             # 知识库管理
/api/v1/documents             # 文档管理
/api/v1/batch-tasks           # 批处理任务
/api/v1/chat/stream           # AI对话流
```

---

## 📂 代码结构

### 后端代码结构

```
backend/src/modules/pkb/
├── controllers/
│   ├── knowledgeBaseController.ts    # 知识库控制器
│   ├── documentController.ts         # 文档控制器
│   └── batchController.ts            # 批处理控制器
├── services/
│   ├── knowledgeBaseService.ts       # 知识库服务 (~350行)
│   ├── documentService.ts            # 文档服务 (~400行)
│   └── batchService.ts               # 批处理服务 (~300行)
├── routes/
│   └── index.ts                      # 路由配置
└── index.ts                          # 模块入口

总计: ~1500行后端代码
```

### 前端代码结构

```
frontend-v2/src/modules/pkb/
├── api/
│   └── knowledgeBaseApi.ts           # API客户端 (~200行)
├── stores/
│   └── useKnowledgeBaseStore.ts      # Zustand状态 (~150行)
├── pages/
│   ├── DashboardPage.tsx             # 仪表盘 (~450行)
│   └── WorkspacePage.tsx             # 工作台 (~513行)
├── components/
│   └── Workspace/
│       ├── WorkModeSelector.tsx      # 模式选择 (~200行)
│       ├── FullTextMode.tsx          # 全文阅读 (~150行)
│       ├── DeepReadMode.tsx          # 逐篇精读 (~150行)
│       ├── BatchMode.tsx             # 批处理入口
│       └── BatchModeComplete.tsx     # 批处理完整 (~511行)
├── hooks/
│   └── useWorkMode.ts                # 工作模式Hook
├── types/
│   └── index.ts                      # 类型定义
└── styles/
    └── workspace.css                 # 自定义样式

总计: ~2300行前端代码
```

---

## 🎨 UI设计

### 原型文件

- **Dashboard**: `docs/03-业务模块/PKB-个人知识库/01-需求分析/知识库仪表盘V5.html`
- **Workspace**: `docs/03-业务模块/PKB-个人知识库/01-需求分析/工作台V3.html`

### Workspace布局

```
┌─────────────────────────────────────────────────┐
│ [返回] │ 知识库名  │ [问答][资产] │ 设置 头像 │ Header 56px
├─────────────────────────────────────────────────┤
│ [工作模式▼] [文档▼]              已加载 x/y 篇 │ 工作模式栏 40px
├─────────────────────────────────────────────────┤
│                                                 │
│              聊天区域（最大化）                 │
│                                                 │
└─────────────────────────────────────────────────┘
```

### 设计特点

- **单层Header**: 整合导航和Tab切换（智能问答/知识资产）
- **紧凑工作模式栏**: 下拉选择，节省空间
- **最大化聊天区域**: 全屏模式，沉浸式对话体验
- **响应式布局**: 支持不同屏幕尺寸

---

## 🔌 工作模式

### 1. 全文阅读模式（Full Text）

**功能说明**：
- 加载知识库全部文档
- AI具备全知视角
- 适合文献综述、跨文献分析

**技术实现**：
- 调用 `/api/v1/chat/stream` 接口
- 传入所有文档ID
- 使用SSE流式响应

### 2. 逐篇精读模式（Deep Read）

**功能说明**：
- 选择1-5篇文档
- 深度解读单篇文献
- 适合精读、批注、理解

**技术实现**：
- 下拉选择文档（最多5篇）
- 调用相同Chat接口
- 仅传入选中文档ID

### 3. 批处理模式（Batch）

**功能说明**：
- 选择批处理模板
- 批量提取文档信息
- 生成结构化表格

**技术实现**：
- 调用 `/api/v1/batch-tasks` 接口
- 支持进度查询
- 结果导出Excel

**当前状态**：🔧 API执行待调试

### 4. RAG检索模式 ✅ **已完成（2026-01-21）**

**功能说明**：
- 基于向量检索 + 关键词检索的混合模式
- 精准定位相关段落
- 适合快速查找
- 支持中英文跨语言检索

**当前状态**：✅ **完全可用** - 成功替换 Dify！

**技术实现**（2026-01-21 完成）：
- ✅ pgvector 扩展（版本 0.8.1）+ HNSW 索引
- ✅ EmbeddingService（阿里云 text-embedding-v4，1024维）
- ✅ VectorSearchService（向量检索 + 关键词检索 + RRF 融合）
- ✅ QueryRewriter（DeepSeek V3 中英双语翻译）
- ✅ RerankService（阿里云 qwen3-rerank 重排序）
- ✅ DocumentIngestService（文档分块 + 向量化入库）
- ✅ ragService.ts 适配器（PKB → EKB 知识库映射）

**性能指标**：
- 单次检索延迟：~2.5秒
- 单次检索成本：¥0.0025
- 跨语言准确率提升：+20.5%

---

## ⚠️ 已知问题

### 1. ~~RAG检索模式业务逻辑未实现~~ ✅ 已解决（2026-01-21）

**已完成**：
- ✅ 完全替换 Dify，使用自研 pgvector RAG 引擎
- ✅ 向量表设计完成（ekb_schema: knowledge_bases, documents, chunks）
- ✅ Embedding 服务集成（阿里云 text-embedding-v4）
- ✅ 相似度检索 API 实现（混合检索 + Rerank）

### 2. OSS 存储集成待完善 🟡 中优先级

**问题描述**：
- 当前文档上传直接入库，未存储到 OSS
- 需要集成 `common/storage` 存储抽象层

**影响**：文档无法持久化存储到云端

**解决方案**：
- 使用 StorageFactory 选择存储适配器
- 开发环境使用 LocalAdapter
- 生产环境使用 OSSAdapter

### 3. pg_bigm 扩展待安装 🟢 低优先级

**问题描述**：
- 当前关键词检索使用基础 LIKE 查询
- pg_bigm 可提升中文关键词检索性能

**影响**：中文关键词检索可能较慢

**解决方案**：
- 安装 pg_bigm 扩展
- 创建 GIN 索引优化中文检索

### 4. 批处理模板有限 🟢 低优先级

**问题描述**：
- 当前只支持1个模板（临床研究信息提取）
- 需要更多预设模板和自定义能力

**影响**：批处理应用场景有限

**解决方案**：
- v2.2版本增加药物安全性、患者基线等模板
- 支持用户自定义模板

### 3. 文档预览功能缺失 🟢 低优先级

**问题描述**：
- 暂不支持文档在线预览
- 需下载后查看原文

**影响**：用户体验

**解决方案**：
- v3.0版本集成PDF预览功能
- 支持文档标注和批注

---

## 📝 下一步开发计划

### v2.3 版本（短期）✅ 已完成

1. **RAG检索模式** ✅ **已完成（2026-01-21）**
   - ✅ pgvector 0.8.1 已安装
   - ✅ 向量表设计完成（ekb_schema）
   - ✅ Embedding 服务集成（阿里云 text-embedding-v4）
   - ✅ 相似度检索 API 实现
   - ✅ 替换 Dify，完全使用自研引擎
   - ✅ 中英双语跨语言检索

### v2.4 版本（短期）

2. **OSS 存储集成** 🟡
   - 集成 common/storage 抽象层
   - 文档持久化存储到 OSS
   - 支持大文件上传

3. **性能优化** 🟡
   - 批处理并发优化
   - 文档加载缓存
   - API响应时间优化

### v2.5 版本（中期）

4. **批处理增强** 🟢
   - 增加药物安全性模板
   - 增加患者基线特征模板
   - 支持自定义模板

5. **用户体验优化** 🟢
   - 文档筛选和排序
   - 批量操作
   - 快捷键支持

### 中期任务（2周内）

6. **PDF预览增强**
   - 集成PDF查看器
   - 支持标注

---

## 📚 相关文档

### 需求文档
- [PRD V5.0](./01-需求分析/AI%20临床医生与医院知识库%20-%20MVP%20阶段产品需求文档%20(PRD)%20V5.0.md)
- [知识库仪表盘V5原型](./01-需求分析/知识库仪表盘V5.html)
- [工作台V3原型](./01-需求分析/工作台V3.html)

### 技术文档
- [数据库设计](./02-技术设计/01-数据库设计.md)

### 开发记录
- [2026-01-07 前端V3设计实现](./06-开发记录/2026-01-07_PKB模块前端V3设计实现.md)

### 测试文档
- [与原型图的差距](./05-测试文档/与原型图的差距.md)

---

## 🎓 给新开发者的提示

### 快速上手

1. **了解模块结构**
   - 阅读本文档了解当前状态
   - 查看原型HTML了解UI设计

2. **运行项目**
   ```bash
   # 后端
   cd backend && npm run dev
   
   # 前端
   cd frontend-v2 && npm run dev
   ```

3. **查看关键代码**
   - `WorkspacePage.tsx` - 工作台主逻辑
   - `knowledgeBaseApi.ts` - API调用
   - `useKnowledgeBaseStore.ts` - 状态管理

### 注意事项

✅ **应该这样做**：
1. 使用Zustand管理状态
2. 复用shared/components中的Chat组件
3. 遵循TailwindCSS样式规范
4. 使用Ant Design组件

❌ **不要这样做**：
1. 创建新的Chat实现
2. 直接操作DOM
3. 使用行内样式
4. 忽略TypeScript类型

---

## 📊 模块统计

### 代码量统计
```
后端代码：约1,500行
前端代码：约2,300行
总计：约3,800行
```

### 开发进度
```
整体进度：约95% 🎉

- 后端API：100% ✅
- Dashboard页面：95% ✅
- Workspace页面：95% ✅
- 全文阅读模式：95% ✅
- 逐篇精读模式：95% ✅
- 批处理模式：95% ✅
- RAG检索模式：100% ✅ (2026-01-21 完成)
- OSS存储集成：50% 🔧
```

---

## 🔗 Git提交记录

**最新提交**：
```
5a17d09 feat(pkb): Complete PKB module frontend migration with V3 design
```

**提交内容**：
- 后端模块迁移到 /modules/pkb
- 前端V3设计实现
- 3种工作模式框架
- Chat组件集成

---

---

## 📝 更新日志

### 2026-01-21 🎉 成功替换 Dify！完全使用自研 RAG 引擎

**重大里程碑**：
- ✅ **彻底移除 Dify 依赖**：删除 DifyClient.ts，重构所有相关服务
- ✅ **自研 RAG 引擎上线**：基于 PostgreSQL + pgvector 的完整 RAG 链路
- ✅ **跨语言检索支持**：DeepSeek V3 查询理解 + 中英双语检索
- ✅ **端到端测试通过**：文档入库 → 向量检索 → Rerank 全流程验证

**技术架构**：
```
Brain-Hand 模型：
  业务层 (Brain) → DeepSeek V3 查询理解 → 生成检索词
  引擎层 (Hand) → 向量+关键词 → RRF → Rerank → 结果

完整链路：
  PDF → Markdown → 分块 → 向量化 → 存储(pgvector)
  用户查询 → DeepSeek翻译 → 向量检索 → Rerank → Top K
```

**修改文件**：
- `backend/src/modules/pkb/services/ragService.ts` - 移除双轨模式，只保留 pgvector
- `backend/src/modules/pkb/services/knowledgeBaseService.ts` - 移除 Dify 创建逻辑
- `backend/src/modules/pkb/services/documentService.ts` - 移除 Dify 上传逻辑
- `backend/src/common/rag/DifyClient.ts` - 改为废弃桩文件（兼容 Legacy）
- `backend/src/common/rag/index.ts` - 更新导出
- `backend/src/common/rag/types.ts` - 移除 Dify 类型
- `backend/src/config/env.ts` - 移除 Dify 配置

**性能指标**：
- 单次检索延迟：~2.5秒
- 单次检索成本：¥0.0025
- 跨语言准确率提升：+20.5%

**遗留问题**：
- OSS 存储集成待完善
- pg_bigm 扩展待安装（优化中文关键词检索）

---

### 2026-01-19 pgvector 向量数据库集成

**重大变更**：
- ✅ **pgvector 0.8.1 安装成功**：Docker 环境已迁移到 `pgvector/pgvector:pg15` 镜像
- ✅ **兼容性验证**：与阿里云 RDS pgvector 0.8.0 完全兼容
- ✅ **功能验证**：前后端服务重启后功能正常
- ✅ **数据完整性**：用户数据、知识库数据、pg-boss 队列函数全部正常

**技术细节**：
- 镜像：`pgvector/pgvector:pg15`
- 扩展版本：0.8.1
- 支持索引类型：HNSW、IVFFlat
- 向量维度：最高支持 16000 维

---

**最后更新：** 2026-01-21  
**文档维护：** PKB模块开发团队  
**联系方式：** 项目Issues