# docMind_coding

**Repository Path**: polen910/docmind_coding

## Basic Information

- **Project Name**: docMind_coding
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocMind

> 一款集文档编辑与 AI 智能问答于一体的知识管理平台

## 拉取更新后必做：升级数据库

**已有开发环境也需要执行，不能只拉取代码或重启服务。** 拉取最新 `master` 后，先确认 MySQL 已启动、仓库根目录 `.env` 配置正确，并激活后端 Python 虚拟环境，然后在 `backend` 目录执行：

```bash
python -m alembic upgrade head
python -m alembic current
```

第二条命令应显示 `0007_document_import_jobs (head)`。本次新增 PDF/Word 解析任务表，支持上传状态、刷新恢复和失败重试；保留已有文档和消息。升级后再启动后端。

**每位使用独立本地数据库的成员都要执行一次；共用同一个数据库时，由一人完成升级并告知其他人。** 以后拉取包含新迁移的代码，也按以上步骤升级，再启动后端。

## 资料导入与手动更新

登录后点击“导入资料”，支持 UTF-8 Markdown/TXT，单篇不超过 1 MiB。
也支持 PDF、Word（DOC/DOCX）：原文件≤10 MB、轻量解析≤20 页，经 MinerU 云端解析，
无需额外密钥。侧栏显示进度，刷新后继续查看；失败可点击“重试解析”。
解析正文需≤1 MiB，成功后才创建文档。图片附件不导入，表格尽量转为 Markdown。
原文件临时保存，成功后清理，失败保留 24 小时以便重试。复杂版式建议导入后核对正文。
上传、编辑保存、保存检查点及恢复版本都只保留内容，不自动更新知识库。
需要 AI 使用当前内容时，点击“立即更新知识库”；后台处理已提交的任务，界面单独显示
检查点与索引状态。不启用静默五分钟或其他定时扫描触发入库。

## 真实 AI 问答

后端已接入 DeepSeek 流式对话和通义千问向量化。两家密钥配置在仓库根目录
`.env` 的 `DEEPSEEK_API_KEY`、`QWEN_API_KEY` 中；修改后重启后端。
配置文件按项目绝对路径查找，不依赖启动目录。对话默认使用 `deepseek-flash`，
向量模型固定为 `text-embedding-v3`、1024 维，不能混用其他模型的索引。
前端 `VITE_F3_MOCK`、`VITE_F4_MOCK` 均应为 `0` 或不设置，修改后重启前端。

使用时导入资料，PDF/Word 等待解析完成，再点击“立即更新知识库”，等待更新成功；
在 AI 助手中新建会话前选择“文档问答”和资料范围，再发送问题。
“通用对话”直接调用模型，不检索个人文档。资料编辑后仍需手动更新，
已有会话的模式与范围保持固定。

阅读模式复用编辑器的 Markdown 格式解析，支持表格、列表、加粗、链接和代码块；
没有编辑或保存操作，解析失败会保留原文供查看。历史引用仍按快照原文字符偏移定位。

后台每小时执行保留期清理：删除超过 24 小时且没有检查点引用的快照；
清理已删除超过 30 天的文档正文、检查点、索引任务、分块、向量及引用摘录。
保留文档删除标记和聊天历史；活动来源保护或正在入库的任务会延后清理。
外部存储删除失败时保留数据库记录供下次重试。清理任务不创建检查点、不触发入库，
不会恢复静默更新知识库。

需要再次验证真实链路时，在仓库根目录使用后端虚拟环境执行以下 PowerShell 命令：

```powershell
$env:DOCMIND_TEST_MYSQL='1'
$env:DOCMIND_TEST_REAL_AI='1'
python -m pytest backend/tests/integration/test_real_ai_document_flow.py -q -s --tb=short
Remove-Item Env:DOCMIND_TEST_MYSQL, Env:DOCMIND_TEST_REAL_AI
```

该检查会产生少量模型调用费用，使用示例配置中的本机 MySQL 创建并删除独立临时数据库，
在已配置的 S3 和 Qdrant 中使用并清理本次合成快照及临时集合。
它检查手动入库、随机资料事实回答、引用保存和跨用户访问拒绝；不生成验收报告。

## 第一次准备项目（新人必读）

首次搭建开发环境（环境变量、Docker 中间件、前后端启动步骤、常见问题），请先阅读：

**[skills/docmind-tech-stack/SKILL.md](skills/docmind-tech-stack/SKILL.md)**

该 skill 是项目技术栈与部署的唯一真相源，包含：

- 技术选型与设计基线（主题色、字体规范）
- Docker 中间件配置说明与健康检查
- 环境变量清单（`.env.example` 各字段含义）
- 新人从零跑起项目的完整步骤

其他 skill：JWT 鉴权使用指南见 [skills/docmind-jwt-auth/SKILL.md](skills/docmind-jwt-auth/SKILL.md)，团队 Git 协作流程见 [skills/git-team-workflow/SKILL.md](skills/git-team-workflow/SKILL.md)，接口契约见 [docs/API.md](docs/API.md)。

DocMind 是一个类似 Notion 的在线知识管理与协作平台。用户可以在线创建和编辑富文本文档,并通过内置的 AI 助手进行通用对话问答,或基于自己的文档内容进行检索增强问答(RAG),让知识"存得下、找得到、用得上"。

##  功能特性

### 文档编辑
- 所见即所得的富文本编辑器,支持标题、列表、代码块、表格等常用格式
- 多级文档树组织,支持页面新建、编辑、删除
- 文档实时保存,历史版本可追溯

###  AI 问答
- **通用对话助手**:支持多轮对话,随时提问
- **文档问答**:基于用户自己的文档库进行问答,AI 结合文档内容给出有依据的回答,并支持引用来源定位

###  RAG 系统
- 用户手动更新后将文档向量化入库,构建个人知识库
- 检索增强生成(Retrieval-Augmented Generation)流程:语义检索 → 上下文重排 → 生成回答
- 基于 LangGraph 编排的问答工作流,支持检索、重写、生成等节点的灵活组合

###  登录注册
- 用户注册、登录、会话管理
- JWT 身份认证,支持接口级别的权限控制

## 🛠 技术栈

| 层次 | 技术 |
| ---- | ---- |
| 前端 | React |
| 后端 | Python / FastAPI |
| 关系数据库 | MySQL(用户、文档等业务数据) |
| 向量数据库 | Qdrant(文档向量存储与语义检索) |
| AI 编排 | LangGraph(问答工作流编排) |
| 大模型 | 国内大模型 API |

## 系统架构

```
┌─────────────┐     HTTP/WS      ┌──────────────────┐
│   React 前端  │ ◄──────────────► │  FastAPI 后端服务  │
└─────────────┘                   └────────┬─────────┘
                                           │
                 ┌─────────────┬───────────┼─────────────┐
                 ▼             ▼           ▼             ▼
             ┌───────┐   ┌─────────┐ ┌─────────┐  ┌──────────┐
             │ MySQL │   │ Qdrant  │ │LangGraph│  │  LLM API │
             └───────┘   └─────────┘ └─────────┘  └──────────┘
```

- **MySQL**:存储用户账号、文档内容、对话历史等结构化数据
- **Qdrant**:存储文档切片的向量表示,提供高效的语义检索
- **LangGraph**:编排 RAG 问答工作流(检索 → 重排 → 生成),支持流式输出

## 核心流程:文档问答(RAG)

1. **文档入库**:用户点击“立即更新知识库”后,后端将对应检查点切分为语义片段
2. **向量化**:调用 Embedding 模型将片段转为向量,写入 Qdrant
3. **语义检索**:用户提问时,先将问题向量化,在 Qdrant 中检索最相关的文档片段
4. **生成回答**:LangGraph 工作流将检索结果与问题一起交给大模型,生成有据可依的回答

## 项目截图

> 待补充:文档编辑器界面、AI 问答界面、知识库检索效果等截图

## 项目状态

本项目为课程实践项目，主要用于功能演示与技术验证。

## 0 License

MIT