# 个人知识库

**Repository Path**: yertqyang/personal-knowledge-base

## Basic Information

- **Project Name**: 个人知识库
- **Description**: 存放个人常用的组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-13
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Personal Knowledge Base

Vue 3 + TypeScript + FastAPI 个人知识库应用，集成 ReAct 多步推理 Agent、RAG 语义搜索、JWT 认证。

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | Vue 3 + TypeScript + Vite |
| 路由 | Vue Router 4（History 模式） |
| 可视化 | ECharts 6 |
| 物理动画 | Matter.js（登录页背景） |
| 后端 | FastAPI + Uvicorn |
| 数据库 | SQLite（用户/文章/对话） |
| 向量搜索 | ChromaDB + all-MiniLM-L6-v2 |
| 认证 | JWT（PyJWT + passlib bcrypt） |
| LLM | OpenAI 兼容接口（可切换 OpenAI / Gemini / DeepSeek / MiniMax） |
| 部署 | Docker + nginx 反向代理 |

## 功能模块

### 知识库
- 结构化知识卡片（文本/列表/代码段落）
- 标签分类筛选，支持展开收起
- 全文搜索（标题/摘要/标签）
- RAG 语义搜索（基于 ChromaDB 向量相似度）

### 智能对话
- 多轮对话 + ReAct 多步推理
- 实时展示思考过程（思考 → 工具调用 → 观察 → 回答）
- 内置工具：计算器、网页搜索、知识库语义查找
- LLM 失败时自动降级为知识库搜索
- 对话历史保存与管理

### 管理后台
- 知识文章 CRUD（新增/编辑/删除）
- 弹框式文章编辑器，支持文本/列表/代码段落
- Markdown 文件导入
- 文章变更自动同步 ChromaDB 索引

### 认证系统
- 用户注册/登录（JWT Token）
- 路由守卫：需登录页面自动跳转登录页
- 仅登录页/注册页对未认证用户可见

### 组件示例
- ECharts 图表（柱状图、地图下钻）
- 表单校验（数字输入拦截、联动校验）
- 可复用 Demo 卡片与代码展示

## 项目结构

```
src/
├── pages/
│   ├── LoginPage/              # 登录页（/ 路径，未登录可见）
│   ├── RegisterPage/           # 注册页（/register）
│   ├── HomePage/               # 首页（/home，需登录）
│   ├── KnowledgeListPage/      # 知识库列表（/kb，公开）
│   ├── KnowledgeArticlePage/   # 知识文章详情（/kb/:id）
│   ├── AgentPage/              # 智能推理对话（/chat）
│   ├── AdminPage/              # 知识管理后台（/admin，需登录）
│   └── ComponentsPage/         # 组件示例（/components）
├── agent/                      # Agent SSE 客户端 + 对话历史 API
├── auth/                       # JWT 认证（login/register/logout）
├── knowledge/                  # 知识库 API 服务 + 类型定义
├── router/                     # 路由配置 + 导航守卫
├── components/                 # 公共组件（AppNav、CodeBlock 等）
└── styles.css                  # 全局样式 + 响应式适配

agent-server/                   # Python 后端
├── main.py                     # FastAPI 入口（CORS、中间件、路由注册）
├── app/
│   ├── config.py               # 环境变量配置
│   ├── database.py             # SQLite 数据库（users/articles/conversations）
│   ├── auth.py                 # JWT 认证中间件
│   ├── agent_engine.py         # ReAct Agent（LLM 推理 + 规则引擎降级）
│   ├── rag.py                  # RAG 语义搜索（ChromaDB）
│   ├── routers/
│   │   ├── auth_router.py      # POST /api/auth/register, /api/auth/login
│   │   ├── articles_router.py  # CRUD /api/articles + 语义搜索
│   │   ├── conversations_router.py  # 对话历史 CRUD
│   │   └── agent_router.py     # GET /agent/status, POST /agent/chat (SSE)
│   └── tools/
│       ├── calculator.py       # 安全数学表达式计算
│       └── search.py           # 知识库搜索（语义优先 + 关键词降级）
├── seed_db.py                  # 数据库种子（28 篇知识文章）
├── requirements.txt            # Python 依赖
├── .env                        # API 配置（不提交 git）
├── start.sh                    # 启动脚本
└── stop.sh                     # 停止脚本
```

## 路由说明

| 路径 | 页面 | 权限 |
|---|---|---|
| `/` | 登录 | 仅未登录 |
| `/register` | 注册 | 仅未登录 |
| `/home` | 首页 | 需登录 |
| `/kb` | 知识库列表 | 公开 |
| `/kb/:id` | 知识文章详情 | 公开 |
| `/chat` | 智能对话 | 公开 |
| `/components` | 组件示例 | 公开 |
| `/admin` | 知识管理 | 需登录 |

## 快速开始

### 1. 前端

```bash
npm install
npm run dev
```

访问 http://localhost:5173

### 2. Agent 后端

```bash
cd agent-server
./start.sh       # 启动（自动创建虚拟环境并安装依赖）
./stop.sh        # 停止
```

访问 http://localhost:8000/docs 查看 API 文档

### 3. 配置 LLM（可选）

编辑 `agent-server/.env`：

```env
# OpenAI
LLM_API_KEY=你的key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini

# 或 Google Gemini
# LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
# LLM_MODEL=gemini-2.0-flash

# 或 DeepSeek
# LLM_BASE_URL=https://api.deepseek.com/v1
# LLM_MODEL=deepseek-chat

# JWT 密钥（生产环境请修改）
JWT_SECRET=pkb-dev-secret-change-in-prod
```

不配置 API Key 时自动使用内置规则引擎 + 知识库搜索，无需网络。

### 4. 局域网访问（手机调试）

前端已配置 `host: 0.0.0.0`，启动后终端会显示 Network 地址：

```
Local:   http://localhost:5173/
Network: http://192.168.x.x:5173/
```

手机连接同一 WiFi，浏览器打开 Network 地址即可。所有页面已适配移动端。

### 5. Docker 部署

```bash
docker-compose up -d
```

- 前端：http://localhost:3000（nginx 反向代理，API 请求自动转发后端）
- 后端：http://localhost:8000

## 脚本

```bash
npm run dev        # 开发服务器
npm run build      # 构建
npm run preview    # 预览构建产物
npm run typecheck  # 类型检查
npm run lint       # ESLint 检查
```

## 默认账号

首次启动后端会自动创建种子数据：

- 用户名：`admin`
- 密码：`admin123`