Interactive Mindmap

基于 Next.js 14、FastAPI 和 SQLite 的思维导图项目。

当前项目的实际使用方式是：

• 腾讯云智能体工作流生成思维导图 JSON
• 后端 POST /api/mindmaps 保存脑图并返回访问链接
• 前端通过 /mindmap/[id] 展示脑图
• 在脑图详情页中，双击节点可打开右侧聊天面板，继续通过腾讯云智能体进行对话

当前功能

• 保存思维导图 JSON，并生成可访问链接
• 展示思维导图详情页
• 支持节点展开/收缩
• 支持在详情页中对节点发起对话
• 后端代理腾讯云智能体 SSE 接口

项目结构

mindmap/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── models.py
│   │   ├── schemas.py
│   │   └── routers/
│   │       ├── chat.py
│   │       └── mindmaps.py
│   ├── data/
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── app/
│   │   ├── page.tsx
│   │   └── mindmap/
│   │       └── [id]/page.tsx
│   ├── components/
│   │   ├── ChatPanel.tsx
│   │   ├── MarkdownMessage.tsx
│   │   ├── MindmapCanvas.tsx
│   │   └── MindmapNodeCard.tsx
│   ├── lib/
│   │   ├── api.ts
│   │   ├── tencentSse.ts
│   │   └── treeToGraph.ts
│   ├── types/
│   │   └── mindmap.ts
│   └── package.json
├── mind_prompt.md
├── 宝塔面板部署指南.md
└── 腾讯云工作流说明.md

页面说明

首页 /

当前首页是项目说明页，不负责直接创建脑图。

思维导图详情页 /mindmap/[id]

该页面会：

• 从后端读取指定 unique_id 的脑图数据
• 渲染交互式脑图
• 双击节点后打开右侧聊天面板
• 聊天面板通过 /api/chat 与腾讯云智能体交互

后端接口

GET /

健康检查接口。

返回：

{"message":"Interactive Mindmap API is running"}

POST /api/mindmaps

创建并保存思维导图。

请求体：

{
  "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 接口。

请求体：

{
  "session_id": "session_001",
  "content": "帮我解释一下这个节点",
  "visitor_biz_id": "default_visitor"
}

返回：

• text/event-stream

环境变量

后端 backend/.env

复制：

cp backend/.env.example backend/.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

如果前后端分端口直连，推荐写成：

NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000

如果后面切到统一入口反向代理，可以改成：

NEXT_PUBLIC_API_BASE_URL=

本地开发

启动后端

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

默认地址：

http://127.0.0.1:8000

启动前端

cd frontend
npm install
npm run dev

默认地址：

http://127.0.0.1:3000

生产构建

cd frontend
npm ci
rm -rf .next
npm run build
npm run start -- -p 3000

测试一条脑图创建链路

后端启动后，可以直接调用：

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
• 腾讯云工作流说明.md

如果你走当前工作流方案，关键链路是：

开始
-> 大模型生成内容
-> 大模型整理 JSON
-> 大模型检查 JSON
-> 变量转换(JSON 反序列化)
-> 插件调用 /api/mindmaps
-> 回复脑图链接

部署说明

当前实际部署文档见：

• 宝塔面板部署指南.md

当前推荐部署方式与实际落地一致：

• 前端放在宝塔 Node 项目
• 后端放在宝塔 Python 项目
• 通过公网 IP + 3000/8000 直接访问

已知注意事项

1. frontend/lib 不能被 .gitignore 误伤

根目录 .gitignore 如果写成：

lib/

会把 frontend/lib/ 一起忽略掉，导致服务器缺少：

• frontend/lib/api.ts
• frontend/lib/tencentSse.ts
• frontend/lib/treeToGraph.ts

正确写法应该是：

/lib/
/lib64/

2. 前端接口地址改动后必须重建

只要改了：

• NEXT_PUBLIC_API_BASE_URL

就必须重新执行：

cd frontend
rm -rf .next
npm run build

3. 后端返回链接依赖 FRONTEND_BASE_URL

如果这个值不对，后端返回的 url 就会不对。