1

2026-03-20 23:09:51 +08:00
commit 8400fb6127
41 changed files with 9348 additions and 0 deletions
--- a/help.md
+++ b/help.md
@@ -0,0 +1,176 @@
+# 思维导图工具使用说明
+
+## 概述
+
+本工具用于对接腾讯云智能体平台，实现思维导图的可视化展示和交互式对话。
+
+## 工作流程
+
+```
+腾讯云智能体平台 → 发送sessionID和思维导图JSON → 本系统存储并返回URL → 用户访问URL查看思维导图 → 点击节点触发AI对话
+```
+
+## API 接口
+
+### 1. 创建思维导图
+
+**请求**
+
+```
+POST /api/mindmaps
+Content-Type: application/json
+
+{
+  "session_id": "腾讯云对话sessionID",
+  "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": false,
+        "children": []
+      }
+    ]
+  }
+}
+```
+
+**响应**
+
+```json
+{
+  "id": 1,
+  "unique_id": "abc123xyz",
+  "session_id": "腾讯云对话sessionID",
+  "title": "机器学习",
+  "raw_json": "{...}",
+  "tree": {...},
+  "url": "http://localhost:3000/mindmap/abc123xyz",
+  "created_at": "2026-03-20T12:00:00",
+  "updated_at": "2026-03-20T12:00:00"
+}
+```
+
+**说明**
+- `session_id`: 腾讯云智能体平台的对话sessionID，用于后续节点点击时的对话
+- `mindmap_json`: 思维导图的JSON数据，标题从根节点的`label`字段自动提取
+- `url`: 返回的唯一访问链接，可直接发送给用户
+
+### 2. 获取思维导图
+
+**请求**
+
+```
+GET /api/mindmaps/{unique_id}
+```
+
+**响应**
+
+与创建接口返回格式相同
+
+### 3. 对话接口
+
+**请求**
+
+```
+POST /api/chat
+Content-Type: application/json
+
+{
+  "session_id": "腾讯云对话sessionID",
+  "content": "帮我解释一下监督学习"
+}
+```
+
+**响应**
+
+SSE流式响应，转发腾讯云智能体平台的对话结果
+
+## 思维导图JSON格式
+
+```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": []
+    }
+  ]
+}
+```
+
+**字段说明**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 节点唯一标识 |
+| `label` | string | 节点显示文本 |
+| `parent_id` | string \| null | 父节点ID，根节点为null |
+| `level` | number | 节点层级，根节点为0 |
+| `is_leaf` | boolean | 是否为叶子节点 |
+| `children` | array | 子节点数组 |
+
+## 前端交互
+
+1. **查看思维导图**: 用户访问返回的URL即可查看思维导图
+2. **展开/折叠节点**: 点击有子节点的节点可展开或折叠
+3. **触发AI对话**: 点击任意节点，右侧聊天面板会自动显示并发送"帮我解释一下{节点内容}"到腾讯云智能体平台
+4. **继续对话**: 用户可在聊天面板中继续与AI对话
+
+## 环境变量配置
+
+后端 `.env` 文件：
+
+```env
+# 腾讯云智能体平台 AppKey
+# 获取方式：应用管理 → 找到运行中的应用 → 点击"调用" → 复制AppKey
+BOT_APP_KEY=your-app-key-here
+
+# 前端基础URL（用于生成思维导图链接）
+FRONTEND_BASE_URL=http://localhost:3000
+```
+
+前端 `.env.local` 文件：
+
+```env
+# 后端API地址
+NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
+```
+
+## 启动方式
+
+### 后端
+
+```bash
+cd backend
+pip install -r requirements.txt
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 前端
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+## 腾讯云智能体平台配置
+
+在腾讯云智能体平台的系统提示词中，指导AI返回符合上述格式的思维导图JSON。参考 `mind_prompt.md` 文件中的示例提示词。