chore: project initialization - Day 4 environment setup

2025-10-10 15:14:54 +08:00
commit bdc7de8043
22 changed files with 12276 additions and 0 deletions
--- a/docs/00-项目概述/技术架构总览.md
+++ b/docs/00-项目概述/技术架构总览.md
@@ -0,0 +1,419 @@
+# AI科研助手 - 技术架构总览
+
+> **最后更新：2025-10-10**  
+> **方案版本：v2.0（最终优化版）**  
+> **文档说明：** 本文档是技术架构的快速参考指南，适合新人快速了解整体技术方案
+
+---
+
+## 📊 核心数据一览
+
+| 指标 | 数值 |
+|------|------|
+| **开发周期** | 2.5个月（10周） |
+| **开发成本** | ¥49,300 |
+| **技术难度** | ⭐⭐⭐（中等） |
+| **月度成本** | ¥16,520（1000用户） |
+| **团队规模** | 2人（1全栈 + 1前端） |
+
+---
+
+## 🎯 关键需求澄清
+
+### 知识库规模（重要变更）
+
+| 项目 | 限制 |
+|------|------|
+| 知识库数量 | 3个/用户 |
+| 文件数量 | 50个/知识库 |
+| 文件格式 | PDF、DOCX |
+| 单用户最大 | 150个文件 |
+
+**影响：** 技术难度从⭐⭐⭐⭐⭐降至⭐⭐⭐，Dify完全满足需求！
+
+---
+
+## 🏗️ 技术架构（一图看懂）
+
+```
+┌─────────────────────────────────────────┐
+│         前端（React + Vite）             │
+│  - 项目管理（自研）                      │
+│  - 智能体选择（自研）                    │
+│  - 聊天界面（参考LobeChat）⭐            │
+│  - 知识库管理（自研）                    │
+└─────────────────────────────────────────┘
+                    ↓ REST API
+┌─────────────────────────────────────────┐
+│      业务层 (Node.js/TypeScript)        │
+│  - 对话逻辑（自研）⭐                    │
+│  - 项目/课题管理                         │
+│  - 智能体路由（配置化）⭐                │
+│  - 简化运营后台⭐                        │
+└─────────────────────────────────────────┘
+          ↓                    ↓
+┌──────────────────┐  ┌─────────────────┐
+│   Dify           │  │  LLM API        │
+│  （仅RAG）⭐      │  │  - DeepSeek-V3⭐│
+│  - 知识库检索     │  │  - Qwen3 ⭐     │
+│  - Qdrant(内置)⭐ │  │                 │
+└──────────────────┘  └─────────────────┘
+```
+
+---
+
+## 🔑 核心决策
+
+### 1. 聊天功能实现方式
+
+| 方案 | 选择 | 原因 |
+|------|------|------|
+| **前端UI** | 参考LobeChat组件 ✅ | 成熟稳定，节省9.5天 |
+| **对话逻辑** | 自研（调用LLM API）✅ | 业务可控，核心只要4步 |
+| Dify对话功能 | ❌ 不用 | 不适合12个智能体管理 |
+| LobeChat整体 | ❌ 不用 | 缺少项目管理功能 |
+
+### 2. RAG系统
+
+| 功能 | 方案 |
+|------|------|
+| **知识库管理** | Dify ✅ |
+| **文档解析** | Dify内置 ✅ |
+| **向量数据库** | Dify内置Qdrant ✅ |
+| **检索** | Dify API ✅ |
+| 自建RAG | ❌ 不需要 |
+
+### 3. 运营后台
+
+| 功能 | 状态 | 实现方式 |
+|------|------|---------|
+| 用户管理 | ✅ 保留 | 简化版 |
+| 数据统计 | ✅ 保留 | 基础仪表盘 |
+| 模型管理 | ❌ 删除 | `config/models.yaml` |
+| 智能体管理 | ❌ 删除 | `config/agents.yaml` |
+| Prompt配置 | ❌ 删除 | `prompts/*.txt` |
+
+### 4. 大模型选择
+
+| 优先级 | 模型 | 价格 | 用途 |
+|--------|------|------|------|
+| **主力** | DeepSeek-V3 | ¥1/百万tokens | 90%的请求 |
+| **备用** | Qwen3-72B | ¥4/百万tokens | 需要更强中文理解时 |
+| 可选 | Gemini 2.0 | ¥2.7/百万tokens | 国际用户 |
+
+---
+
+## 💰 成本明细
+
+### 开发成本
+
+| 项目 | 金额 |
+|------|------|
+| 人力（4人月） | ¥48,000 |
+| 服务器（开发环境） | ¥1,250 |
+| LLM API（测试） | ¥50 |
+| **总计** | **¥49,300** |
+
+### 月度运营成本（1000用户）
+
+| 项目 | 金额 |
+|------|------|
+| 基础设施（服务器） | ¥1,200 |
+| LLM API（DeepSeek-V3） | ¥180 |
+| 对象存储（知识库） | ¥140 |
+| 人力（1人运维） | ¥15,000 |
+| **总计** | **¥16,520/月** |
+
+### 知识库存储详情
+
+```
+单用户：150个文件 × 5MB = 750MB
+1000用户：750GB总存储
+
+对象存储（阿里云OSS）：
+- 存储费：¥90/月
+- 流量费：¥50/月
+- 总计：¥140/月
+```
+
+---
+
+## 📅 开发计划（10周）
+
+| 阶段 | 时间 | 主要任务 |
+|------|------|---------|
+| **阶段1** | 1.5周 | 基础搭建 + 复用LobeChat组件 |
+| **阶段2** | 3.5周 | 核心功能（12个智能体 + 对话） |
+| **阶段3** | 2周 | 高级功能（RAG + 文档生成） |
+| **阶段4** | 1周 | 简化运营后台 |
+| **阶段5** | 2周 | 测试优化 |
+
+### 阶段1：基础搭建（1.5周）
+- [ ] 前端框架（React + Vite + TailwindCSS）
+- [ ] **复用LobeChat聊天UI组件** ⭐
+- [ ] 后端框架（Fastify + Prisma + PostgreSQL）
+- [ ] Dify部署（Docker）
+- [ ] DeepSeek-V3 + Qwen3接入
+
+### 阶段2：核心功能（3.5周）
+- [ ] 用户认证（JWT）
+- [ ] 项目/课题CRUD
+- [ ] 12个智能体配置（`agents.yaml`）
+- [ ] 对话系统（上下文组装 + 流式输出）
+- [ ] 知识库集成（Dify API）
+
+### 阶段3：高级功能（2周）
+- [ ] 多模型切换（DeepSeek/Qwen）
+- [ ] 历史记录管理
+- [ ] 固定到项目背景功能
+- [ ] 文档生成（CRF、研究方案）
+
+### 阶段4：简化运营后台（1周）
+- [ ] 用户列表与管理
+- [ ] 基础数据统计
+- [ ] 对话记录查看
+
+### 阶段5：测试优化（2周）
+- [ ] 功能测试
+- [ ] 性能优化
+- [ ] DeepSeek-V3效果调优
+
+---
+
+## 🛠️ 技术栈
+
+### 前端
+```
+- React 18 + TypeScript
+- Vite（构建工具）
+- TailwindCSS（UI框架）
+- Zustand（状态管理）
+- LobeChat组件（聊天UI）⭐
+- react-markdown（Markdown渲染）
+```
+
+### 后端
+```
+- Node.js + Fastify + TypeScript
+- Prisma（ORM）
+- PostgreSQL（数据库）
+- Redis（缓存）
+```
+
+### 第三方服务
+```
+- Dify（RAG知识库）⭐
+- DeepSeek-V3（主力LLM）⭐
+- Qwen3（备用LLM）⭐
+- 阿里云OSS（对象存储）
+```
+
+---
+
+## ✅ 核心优势
+
+### 1. 开发效率高
+- ✅ 复用LobeChat聊天UI：节省9.5天
+- ✅ 使用Dify RAG：节省40天
+- ✅ 配置化智能体：节省5天
+- ✅ 总节省：**约54.5天**
+
+### 2. 成本可控
+- ✅ 开发成本：¥49,300（vs 纯手写¥80k+）
+- ✅ 月度LLM成本：¥180（vs GPT-4 ¥2,500）
+- ✅ 知识库存储：¥140/月（适度规模）
+
+### 3. 技术风险低
+- ✅ Dify：50k+ Stars，生产级稳定
+- ✅ LobeChat：40k+ Stars，成熟方案
+- ✅ DeepSeek-V3：性价比极高
+
+### 4. 架构灵活
+- ✅ 业务逻辑完全可控
+- ✅ 可随时替换RAG引擎
+- ✅ 可随时增减LLM模型
+
+---
+
+## 📋 核心文件结构
+
+```
+项目根目录/
+├── frontend/                    # 前端
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── chat/           # 聊天组件（参考LobeChat）⭐
+│   │   │   │   ├── ChatMessage.tsx
+│   │   │   │   ├── ChatInput.tsx
+│   │   │   │   └── StreamRenderer.tsx
+│   │   │   ├── project/        # 项目管理
+│   │   │   └── kb/             # 知识库管理
+│   │   ├── pages/
+│   │   └── services/
+│   └── package.json
+│
+├── backend/                     # 后端
+│   ├── src/
+│   │   ├── services/
+│   │   │   ├── chat.service.ts        # 对话服务 ⭐
+│   │   │   ├── kb.service.ts          # 知识库服务
+│   │   │   └── project.service.ts
+│   │   ├── adapters/
+│   │   │   └── llm-factory.ts         # LLM适配器 ⭐
+│   │   ├── clients/
+│   │   │   └── dify.ts                # Dify客户端
+│   │   └── config/
+│   │       └── agent-loader.ts        # 智能体配置加载 ⭐
+│   ├── config/
+│   │   ├── agents.yaml                # 智能体配置 ⭐
+│   │   └── models.yaml                # 模型配置 ⭐
+│   ├── prompts/                       # Prompt文件 ⭐
+│   │   ├── picos_system.txt
+│   │   ├── topic_evaluation_system.txt
+│   │   └── ...（共12个智能体）
+│   └── package.json
+│
+└── docker-compose.yml           # Dify部署
+```
+
+---
+
+## 🚀 快速启动
+
+### 1. 准备工作
+
+**申请API Key：**
+- [ ] DeepSeek API Key (https://platform.deepseek.com)
+- [ ] 阿里云DashScope Key (https://dashscope.aliyun.com)
+- [ ] 阿里云OSS (https://oss.console.aliyun.com)
+
+**准备服务器：**
+- [ ] 云服务器 4核8G（开发环境）
+- [ ] PostgreSQL 数据库
+- [ ] Redis 缓存
+
+### 2. 部署Dify
+
+```bash
+# 克隆Dify
+git clone https://github.com/langgenius/dify.git
+cd dify/docker
+
+# 启动
+docker-compose up -d
+
+# 访问 http://localhost:3000
+# 创建账号并获取API Key
+```
+
+### 3. 后端开发
+
+```bash
+cd backend
+npm install
+
+# 配置环境变量
+cp .env.example .env
+# 填入：
+# - DATABASE_URL
+# - REDIS_URL
+# - DEEPSEEK_API_KEY
+# - DASHSCOPE_API_KEY
+# - DIFY_API_KEY
+
+# 运行数据库迁移
+npx prisma migrate dev
+
+# 启动开发服务器
+npm run dev
+```
+
+### 4. 前端开发
+
+```bash
+cd frontend
+npm install
+
+# 配置API地址
+# .env.local
+VITE_API_URL=http://localhost:3001
+
+# 启动开发服务器
+npm run dev
+```
+
+---
+
+## 📚 相关文档
+
+### 设计文档
+- [产品需求文档(PRD)](./产品需求文档(PRD).md) - 完整的产品需求
+- [数据库设计文档](../01-设计文档/数据库设计文档.md) - 数据库表结构
+- [API设计规范](../01-设计文档/API设计规范.md) - 所有API定义
+- [代码规范](../02-开发规范/代码规范.md) - 代码风格规范
+- [核心业务规则](../03-业务规则/核心业务规则总览.md) - 业务逻辑规则
+
+### 开发计划
+- [开发里程碑](../04-开发计划/开发里程碑.md) - 详细的10周开发计划
+
+### 参考文档
+- **技术架构选型对比方案.md** - 完整技术方案（在项目根目录）
+- **对话系统实现方案对比.md** - 对话功能详细说明（在项目根目录）
+- **知识库需求调整说明.md** - 知识库实现方案（在项目根目录）
+
+---
+
+## 🎯 关键决策清单
+
+**在开始开发前，请确认：**
+
+- [ ] **聊天实现方式：** 参考LobeChat + 自研对话逻辑 ✅
+- [ ] **RAG系统：** 使用Dify（无需自建）✅
+- [ ] **向量数据库：** Dify内置Qdrant（无需关心）✅
+- [ ] **运营后台：** 简化版（配置文件管理）✅
+- [ ] **主力LLM：** DeepSeek-V3 ✅
+- [ ] **备用LLM：** Qwen3 ✅
+- [ ] **知识库限制：** 3个/用户，50个文件/库 ✅
+- [ ] **开发周期：** 2.5个月 ✅
+- [ ] **团队规模：** 2人 ✅
+
+---
+
+## 💡 常见问题 FAQ
+
+### Q1: 为什么不直接用Dify的对话功能？
+**A:** Dify对话功能需要为每个智能体创建独立应用，12个智能体管理复杂，且缺少项目管理功能。我们只用Dify做RAG检索。
+
+### Q2: 对话功能自己实现会很复杂吗？
+**A:** 不复杂！核心只要4步：接收消息 → 组装上下文 → 调用LLM → 返回流式结果。参考LobeChat的实现，约需4天。
+
+### Q3: 150个文件/用户，Dify够用吗？
+**A:** 完全够用！Dify单个知识库支持上万个文档片段，我们的需求远低于上限。
+
+### Q4: 为什么选择DeepSeek-V3？
+**A:** 性价比极高（¥1/百万tokens），性能接近GPT-4，年度可节省¥27,840。
+
+### Q5: 2.5个月真的能完成吗？
+**A:** 可以！通过复用LobeChat组件、使用Dify RAG、配置化智能体，我们节省了约54天开发时间。
+
+---
+
+## 🎉 总结
+
+**这是一个经过充分优化、成本可控、技术可行的方案：**
+
+✅ **开发周期：** 2.5个月  
+✅ **开发成本：** ¥49,300  
+✅ **月度成本：** ¥16,520（1000用户）  
+✅ **技术难度：** ⭐⭐⭐（中等）  
+✅ **风险等级：** 低（使用成熟组件和服务）  
+
+**立即可以开始！** 🚀
+
+---
+
+**文档版本：v2.0**  
+**最后更新：2025-10-10**  
+**文档位置：** `docs/00-项目概述/技术架构总览.md`  
+**作者：** AI技术顾问
+