# noteagent

**Repository Path**: homeless20/noteagent

## Basic Information

- **Project Name**: noteagent
- **Description**: 一个笔记智能体，它可以 对你的笔记建立知识库，以后得内容都根据你的知识库给你专业的回答
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 笔记智能体

一个私人知识库助手，让你在线写入笔记信息，当你查询时以你的笔记为知识库源，给你专业的回答和建议。

## 技术栈

- **后端**: Python + FastAPI
- **前端**: Vue 3 + TailwindCSS
- **AI**: DeepSeek API
- **存储**: 本地文件系统 (JSON)

## 项目结构

```
noteagent/
├── backend/                    # 后端服务
│   ├── .env                   # 环境变量配置
│   ├── .env.example           # 环境变量示例
│   ├── requirements.txt       # Python 依赖
│   ├── main.py                # FastAPI 主入口
│   ├── config.py              # 配置管理
│   ├── models.py              # 数据模型
│   ├── storage.py             # 笔记存储服务
│   └── ai_service.py          # DeepSeek AI 服务
│
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── api/              # API 服务
│   │   ├── router/           # 路由配置
│   │   ├── views/            # 页面组件
│   │   │   ├── Notes.vue     # 笔记管理页面
│   │   │   └── Chat.vue      # AI 对话页面
│   │   ├── App.vue           # 根组件
│   │   ├── main.js           # 入口文件
│   │   └── style.css         # 全局样式
│   ├── index.html
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   └── postcss.config.js
│
└── README.md
```

## 快速开始

### 1. 准备工作

1. 注册 DeepSeek 账号并获取 API Key: https://platform.deepseek.com/
2. 安装 Python 3.8+ 和 Node.js 18+

### 2. 后端安装

```bash
cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

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

# 配置 API Key
# 编辑 .env 文件，将 DEEPSEEK_API_KEY 替换为你的实际 API Key
```

### 3. 前端安装

```bash
cd frontend

# 安装依赖
npm install
```

### 4. 启动服务

**启动后端 (端口 8000)**:
```bash
cd backend
venv\Scripts\activate  # Windows
python main.py
```

**启动前端 (端口 3000)**:
```bash
cd frontend
npm run dev
```

### 5. 访问应用

打开浏览器访问: http://localhost:3000

## 功能特性

### 笔记管理
- ✅ 创建新笔记
- ✅ 编辑现有笔记
- ✅ 删除笔记
- ✅ 搜索笔记（标题、内容、标签）
- ✅ 标签管理
- ✅ 笔记列表展示（按更新时间排序）

### AI 对话
- ✅ 基于知识库回答问题
- ✅ 显示参考来源（相关笔记标题）
- ✅ Markdown 格式渲染
- ✅ 可选择是否使用知识库
- ✅ 快捷提问建议
- ✅ 清空对话功能

## API 接口

后端运行在 http://localhost:8000，API 文档地址：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 主要接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /notes/ | 获取笔记列表 |
| POST | /notes/ | 创建笔记 |
| GET | /notes/{id} | 获取单个笔记 |
| PUT | /notes/{id} | 更新笔记 |
| DELETE | /notes/{id} | 删除笔记 |
| GET | /search/ | 搜索笔记 |
| POST | /chat/ | AI 对话 |

## 配置说明

### 后端环境变量 (.env)

```env
# DeepSeek API 配置
DEEPSEEK_API_KEY=sk-your-api-key-here      # 你的 API Key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat                # 可选: deepseek-chat, deepseek-coder

# 存储配置
STORAGE_PATH=./data/notes                    # 笔记存储路径
```

### 前端代理配置

前端通过 Vite 代理将 `/api` 请求转发到后端:
- 前端请求: `http://localhost:3000/api/notes/`
- 实际转发: `http://localhost:8000/notes/`

## RAG 检索机制

系统使用简单但有效的 RAG (检索增强生成) 策略：

1. **关键词匹配**: 将用户问题与笔记内容进行关键词匹配
2. **相关度评分**: 基于匹配到的关键词数量进行评分
3. **上下文构建**: 将相关笔记内容整合到系统提示词中
4. **来源标注**: 回答中显示参考了哪些笔记

## 开发说明

### 后端开发

添加新的 API 端点请编辑 `main.py`，数据模型定义在 `models.py`。

### 前端开发

- 页面组件位于 `src/views/`
- 路由配置在 `src/router/index.js`
- API 调用在 `src/api/index.js`

## 注意事项

1. **API Key 安全**: 不要将包含真实 API Key 的 `.env` 文件提交到代码仓库
2. **存储限制**: 目前使用本地文件存储，笔记数量较多时可能影响性能
3. **网络要求**: 需要能够访问 DeepSeek API
4. **并发限制**: 免费版 DeepSeek API 有请求频率限制

## 后续优化建议

- [ ] 添加向量数据库 (如 Chroma) 提升检索效果
- [ ] 支持笔记分类和文件夹
- [ ] 添加用户认证
- [ ] 支持笔记导入导出
- [ ] 添加对话历史保存
- [ ] 支持流式 AI 响应

## 许可证

MIT License