更新各类文档
This commit is contained in:
375
README.md
375
README.md
@@ -1,121 +1,318 @@
|
||||
# Interactive Mindmap
|
||||
|
||||
基于 Next.js、FastAPI 和 SQLite 的交互式思维导图应用，支持通过腾讯云 AI Agent 对话生成思维导图。
|
||||
基于 `Next.js 14`、`FastAPI` 和 `SQLite` 的思维导图项目。
|
||||
|
||||
当前项目的实际使用方式是：
|
||||
|
||||
- 腾讯云智能体工作流生成思维导图 JSON
|
||||
- 后端 `POST /api/mindmaps` 保存脑图并返回访问链接
|
||||
- 前端通过 `/mindmap/[id]` 展示脑图
|
||||
- 在脑图详情页中，双击节点可打开右侧聊天面板，继续通过腾讯云智能体进行对话
|
||||
|
||||
## 当前功能
|
||||
|
||||
- 保存思维导图 JSON，并生成可访问链接
|
||||
- 展示思维导图详情页
|
||||
- 支持节点展开/收缩
|
||||
- 支持在详情页中对节点发起对话
|
||||
- 后端代理腾讯云智能体 SSE 接口
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
```text
|
||||
mindmap/
|
||||
├── backend/ # FastAPI 后端
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # 应用入口
|
||||
│ │ ├── config.py # 配置
|
||||
│ │ ├── database.py # 数据库
|
||||
│ │ ├── models.py # 数据模型
|
||||
│ │ ├── schemas.py # Pydantic schemas
|
||||
│ │ ├── main.py
|
||||
│ │ ├── config.py
|
||||
│ │ ├── database.py
|
||||
│ │ ├── models.py
|
||||
│ │ ├── schemas.py
|
||||
│ │ └── routers/
|
||||
│ │ ├── mindmaps.py # 思维导图 CRUD API
|
||||
│ │ └── chat.py # AI 对话代理 (SSE)
|
||||
│ ├── data/ # SQLite 数据库文件
|
||||
│ │ ├── chat.py
|
||||
│ │ └── mindmaps.py
|
||||
│ ├── data/
|
||||
│ ├── requirements.txt
|
||||
│ └── .env.example
|
||||
├── frontend/ # Next.js 前端
|
||||
├── frontend/
|
||||
│ ├── app/
|
||||
│ │ ├── page.tsx # 首页
|
||||
│ │ ├── page.tsx
|
||||
│ │ └── mindmap/
|
||||
│ │ ├── [id]/page.tsx # 思维导图详情页
|
||||
│ │ └── chat/page.tsx # AI 对话 + 思维导图页
|
||||
│ │ └── [id]/page.tsx
|
||||
│ ├── components/
|
||||
│ │ ├── MindmapCanvas.tsx # 思维导图画布
|
||||
│ │ ├── MindmapNodeCard.tsx # 节点卡片
|
||||
│ │ ├── ChatPanel.tsx # 聊天面板
|
||||
│ │ └── CreateMindmapForm.tsx # 创建表单
|
||||
│ │ ├── ChatPanel.tsx
|
||||
│ │ ├── MarkdownMessage.tsx
|
||||
│ │ ├── MindmapCanvas.tsx
|
||||
│ │ └── MindmapNodeCard.tsx
|
||||
│ ├── lib/
|
||||
│ │ ├── api.ts # API 调用
|
||||
│ │ └── treeToGraph.ts # 树转图布局
|
||||
│ └── types/
|
||||
│ └── mindmap.ts # TypeScript 类型
|
||||
└── mind_prompt.md # AI Agent 系统提示词
|
||||
```
|
||||
|
||||
## 环境配置
|
||||
|
||||
### 后端
|
||||
|
||||
1. 安装依赖:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
2. 配置环境变量:
|
||||
|
||||
```bash
|
||||
# 复制示例配置
|
||||
cp .env.example .env
|
||||
|
||||
# 编辑 .env，填入腾讯云 AI Agent 的 bot_app_key
|
||||
TENCENT_BOT_APP_KEY=your-key-here
|
||||
```
|
||||
|
||||
3. 启动后端:
|
||||
|
||||
```bash
|
||||
TENCENT_BOT_APP_KEY=your-key-here uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
### 前端
|
||||
|
||||
1. 安装依赖:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
2. 启动开发服务器:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
│ │ ├── api.ts
|
||||
│ │ ├── tencentSse.ts
|
||||
│ │ └── treeToGraph.ts
|
||||
│ ├── types/
|
||||
│ │ └── mindmap.ts
|
||||
│ └── package.json
|
||||
├── mind_prompt.md
|
||||
├── 宝塔面板部署指南.md
|
||||
└── 腾讯云工作流说明.md
|
||||
```
|
||||
|
||||
## 页面说明
|
||||
|
||||
### 首页 `/`
|
||||
|
||||
输入主题创建思维导图（使用 mock 数据）。
|
||||
当前首页是项目说明页，不负责直接创建脑图。
|
||||
|
||||
### 思维导图详情 `/mindmap/[id]`
|
||||
### 思维导图详情页 `/mindmap/[id]`
|
||||
|
||||
查看已保存的思维导图，支持节点展开/收缩。
|
||||
该页面会：
|
||||
|
||||
### AI 对话生成 `/mindmap/chat?sessionId=xxx`
|
||||
- 从后端读取指定 `unique_id` 的脑图数据
|
||||
- 渲染交互式脑图
|
||||
- 双击节点后打开右侧聊天面板
|
||||
- 聊天面板通过 `/api/chat` 与腾讯云智能体交互
|
||||
|
||||
通过与腾讯云 AI Agent 对话生成思维导图：
|
||||
## 后端接口
|
||||
|
||||
- **左侧**: 思维导图画布，初始为空，AI 返回有效数据后自动渲染
|
||||
- **右侧**: 聊天面板，支持实时 SSE 流式响应
|
||||
### `GET /`
|
||||
|
||||
URL 参数:
|
||||
- `sessionId` (必填): 会话 ID，用于标识对话会话
|
||||
健康检查接口。
|
||||
|
||||
## 数据流
|
||||
返回：
|
||||
|
||||
```
|
||||
用户输入 → ChatPanel → POST /api/chat → 后端代理 → 腾讯云 SSE API
|
||||
↓
|
||||
画布更新 ← onMindmapUpdate ← JSON 解析 ← SSE 流式响应 ←─┘
|
||||
```json
|
||||
{"message":"Interactive Mindmap API is running"}
|
||||
```
|
||||
|
||||
1. 用户在聊天面板输入消息
|
||||
2. 前端发送 POST 请求到后端 `/api/chat`
|
||||
3. 后端将请求代理到腾讯云 AI Agent SSE 接口
|
||||
4. SSE 流式响应逐步返回到前端
|
||||
5. 前端解析 SSE 事件，逐步显示 AI 回复
|
||||
6. 当 AI 回复完成后，尝试从回复中提取思维导图 JSON
|
||||
7. 如果提取成功，更新左侧画布
|
||||
### `POST /api/mindmaps`
|
||||
|
||||
## AI Agent 配置
|
||||
创建并保存思维导图。
|
||||
|
||||
参见 [mind_prompt.md](./mind_prompt.md) 获取 AI Agent 的系统提示词配置。
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "session_001",
|
||||
"mindmap_json": {
|
||||
"id": "node_0",
|
||||
"label": "主题",
|
||||
"parent_id": null,
|
||||
"level": 0,
|
||||
"is_leaf": false,
|
||||
"children": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
返回中会包含：
|
||||
|
||||
- `unique_id`
|
||||
- `title`
|
||||
- `url`
|
||||
- `tree`
|
||||
|
||||
### `GET /api/mindmaps/{unique_id}`
|
||||
|
||||
读取指定脑图详情。
|
||||
|
||||
### `POST /api/chat`
|
||||
|
||||
后端代理腾讯云智能体 SSE 接口。
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "session_001",
|
||||
"content": "帮我解释一下这个节点",
|
||||
"visitor_biz_id": "default_visitor"
|
||||
}
|
||||
```
|
||||
|
||||
返回：
|
||||
|
||||
- `text/event-stream`
|
||||
|
||||
## 环境变量
|
||||
|
||||
## 后端 `backend/.env`
|
||||
|
||||
复制：
|
||||
|
||||
```bash
|
||||
cp backend/.env.example backend/.env
|
||||
```
|
||||
|
||||
实际使用的变量名是：
|
||||
|
||||
```env
|
||||
BOT_APP_KEY=your-app-key
|
||||
FRONTEND_BASE_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `BOT_APP_KEY`：腾讯云智能体平台 AppKey
|
||||
- `FRONTEND_BASE_URL`：后端返回脑图链接时使用的前端基地址
|
||||
|
||||
注意：当前代码读取的是 `BOT_APP_KEY`，不是 `TENCENT_BOT_APP_KEY`。
|
||||
|
||||
## 前端 `frontend/.env.production`
|
||||
|
||||
如果前后端分端口直连，推荐写成：
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
|
||||
```
|
||||
|
||||
如果后面切到统一入口反向代理，可以改成：
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_BASE_URL=
|
||||
```
|
||||
|
||||
## 本地开发
|
||||
|
||||
## 启动后端
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
默认地址：
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8000
|
||||
```
|
||||
|
||||
## 启动前端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
默认地址：
|
||||
|
||||
```text
|
||||
http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
## 生产构建
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm ci
|
||||
rm -rf .next
|
||||
npm run build
|
||||
npm run start -- -p 3000
|
||||
```
|
||||
|
||||
## 测试一条脑图创建链路
|
||||
|
||||
后端启动后，可以直接调用：
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/api/mindmaps \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"session_id": "test-session",
|
||||
"mindmap_json": {
|
||||
"id": "node_0",
|
||||
"label": "测试主题",
|
||||
"parent_id": null,
|
||||
"level": 0,
|
||||
"is_leaf": false,
|
||||
"children": [
|
||||
{
|
||||
"id": "node_1",
|
||||
"label": "测试子节点",
|
||||
"parent_id": "node_0",
|
||||
"level": 1,
|
||||
"is_leaf": true,
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
成功后会返回一个 `url`，打开即可查看脑图详情页。
|
||||
|
||||
## 腾讯云智能体接入说明
|
||||
|
||||
当前项目更适合由腾讯云工作流或插件来创建脑图，而不是由前端首页直接生成。
|
||||
|
||||
建议查看：
|
||||
|
||||
- [mind_prompt.md](E:/code/mindmap/mind_prompt.md)
|
||||
- [腾讯云工作流说明.md](E:/code/mindmap/腾讯云工作流说明.md)
|
||||
|
||||
如果你走当前工作流方案，关键链路是：
|
||||
|
||||
```text
|
||||
开始
|
||||
-> 大模型生成内容
|
||||
-> 大模型整理 JSON
|
||||
-> 大模型检查 JSON
|
||||
-> 变量转换(JSON 反序列化)
|
||||
-> 插件调用 /api/mindmaps
|
||||
-> 回复脑图链接
|
||||
```
|
||||
|
||||
## 部署说明
|
||||
|
||||
当前实际部署文档见：
|
||||
|
||||
- [宝塔面板部署指南.md](E:/code/mindmap/宝塔面板部署指南.md)
|
||||
|
||||
当前推荐部署方式与实际落地一致：
|
||||
|
||||
- 前端放在宝塔 `Node 项目`
|
||||
- 后端放在宝塔 `Python 项目`
|
||||
- 通过公网 IP + `3000/8000` 直接访问
|
||||
|
||||
## 已知注意事项
|
||||
|
||||
### 1. `frontend/lib` 不能被 `.gitignore` 误伤
|
||||
|
||||
根目录 `.gitignore` 如果写成：
|
||||
|
||||
```gitignore
|
||||
lib/
|
||||
```
|
||||
|
||||
会把 `frontend/lib/` 一起忽略掉，导致服务器缺少：
|
||||
|
||||
- `frontend/lib/api.ts`
|
||||
- `frontend/lib/tencentSse.ts`
|
||||
- `frontend/lib/treeToGraph.ts`
|
||||
|
||||
正确写法应该是：
|
||||
|
||||
```gitignore
|
||||
/lib/
|
||||
/lib64/
|
||||
```
|
||||
|
||||
### 2. 前端接口地址改动后必须重建
|
||||
|
||||
只要改了：
|
||||
|
||||
- `NEXT_PUBLIC_API_BASE_URL`
|
||||
|
||||
就必须重新执行：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
rm -rf .next
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 3. 后端返回链接依赖 `FRONTEND_BASE_URL`
|
||||
|
||||
如果这个值不对，后端返回的 `url` 就会不对。
|
||||
|
||||
Reference in New Issue
Block a user