384 lines
7.7 KiB
Markdown
384 lines
7.7 KiB
Markdown
# 腾讯云思维导图工作流说明
|
||
|
||
## 1. 工作流目标
|
||
|
||
当前工作流的目标是：
|
||
|
||
1. 接收用户主题与会话 ID
|
||
2. 通过大模型生成思维导图内容
|
||
3. 将内容整理为合法 JSON 字符串
|
||
4. 对 JSON 做校验和修复
|
||
5. 将 JSON 字符串反序列化为对象
|
||
6. 调用后端工具保存脑图
|
||
7. 将生成后的访问链接回复给用户
|
||
|
||
这条链路的关键点是：
|
||
|
||
- 大模型节点输出保持为 `string`
|
||
- 插件节点接收的 `mindmap_json` 必须是 `object`
|
||
- 所以中间必须经过一次 `变量转换节点 -> JSON 反序列化`
|
||
|
||
## 2. 当前工作流节点
|
||
|
||
根据当前画布，节点顺序为：
|
||
|
||
1. `开始`
|
||
2. `生成思维导图内容`
|
||
3. `生成思维导图内容json`
|
||
4. `检查json`
|
||
5. `变量转换1`
|
||
6. `生成前端页面`
|
||
7. `回复1`
|
||
8. `结束`
|
||
|
||
## 3. 节点职责说明
|
||
|
||
## 3.1 开始
|
||
|
||
作用：
|
||
|
||
- 接收工作流启动输入
|
||
|
||
建议输入变量：
|
||
|
||
- `topic`
|
||
- `session_id`
|
||
|
||
说明：
|
||
|
||
- `topic` 用于告诉大模型本次脑图主题
|
||
- `session_id` 用于插件调用时传给后端接口
|
||
|
||
## 3.2 生成思维导图内容
|
||
|
||
节点类型：
|
||
|
||
- 大模型节点
|
||
|
||
作用：
|
||
|
||
- 根据用户主题先生成一版结构化脑图内容
|
||
|
||
建议输出：
|
||
|
||
- `Output.Content`：文本内容
|
||
|
||
建议：
|
||
|
||
- 这一层可以先输出脑图提纲或中间描述
|
||
- 不要求它直接输出最终可落库的 JSON
|
||
|
||
## 3.3 生成思维导图内容json
|
||
|
||
节点类型：
|
||
|
||
- 大模型节点
|
||
|
||
作用：
|
||
|
||
- 将上一节点的内容转换成思维导图 JSON 字符串
|
||
|
||
建议输出：
|
||
|
||
- `Output.Content`：JSON 字符串
|
||
|
||
这一节点必须满足：
|
||
|
||
- 只输出纯 JSON
|
||
- 不要输出解释文字
|
||
- 不要输出 markdown 代码块
|
||
- 不要输出前后缀说明
|
||
|
||
建议要求它输出的格式为：
|
||
|
||
```json
|
||
{
|
||
"id": "node_0",
|
||
"label": "主题",
|
||
"parent_id": null,
|
||
"level": 0,
|
||
"is_leaf": false,
|
||
"children": []
|
||
}
|
||
```
|
||
|
||
## 3.4 检查json
|
||
|
||
节点类型：
|
||
|
||
- 大模型节点
|
||
|
||
作用：
|
||
|
||
- 对上一节点生成的 JSON 字符串做检查和修复
|
||
|
||
建议输出：
|
||
|
||
- `Output.Content`：修复后的 JSON 字符串
|
||
|
||
建议规则：
|
||
|
||
1. 如果 JSON 合法且结构正确，原样返回
|
||
2. 如果不合法，修复后返回
|
||
3. 始终只输出 JSON 字符串
|
||
4. 不输出解释文字
|
||
|
||
这一节点输出仍然应该是 `string`，不要直接改成 `JSON` 类型输出。
|
||
|
||
## 3.5 变量转换1
|
||
|
||
节点类型：
|
||
|
||
- 变量转换节点
|
||
|
||
当前建议配置：
|
||
|
||
- 转换类型：`JSON`
|
||
- 转换方式：`JSON 反序列化`
|
||
- 转换变量：`检查json.Output.Content`
|
||
|
||
作用：
|
||
|
||
- 将 `检查json` 节点输出的 JSON 字符串反序列化为对象
|
||
|
||
为什么必须有这一步：
|
||
|
||
- 大模型节点输出的是字符串
|
||
- 插件节点里的 `mindmap_json` 入参需要的是 `object`
|
||
|
||
该节点默认输出：
|
||
|
||
- `Output`
|
||
- `Error`
|
||
|
||
后续插件节点应引用：
|
||
|
||
- `变量转换1.Output`
|
||
|
||
不要引用：
|
||
|
||
- `变量转换1.Error`
|
||
|
||
## 3.6 生成前端页面
|
||
|
||
节点类型：
|
||
|
||
- 插件节点
|
||
|
||
作用：
|
||
|
||
- 调用后端 API 创建并保存思维导图
|
||
- 返回脑图访问链接
|
||
|
||
当前插件接口建议：
|
||
|
||
- 调用地址：`http://公网IP:8000/api/mindmaps`
|
||
- 请求方式：`POST`
|
||
- Content-Type：`application/json`
|
||
|
||
插件输入参数应配置为：
|
||
|
||
- `session_id`
|
||
- `mindmap_json`
|
||
|
||
工作流内的输入映射建议如下：
|
||
|
||
### 输入参数 `session_id`
|
||
|
||
来源建议：
|
||
|
||
- `开始.session_id`
|
||
|
||
如果你是通过应用 API 调工作流，也可以使用：
|
||
|
||
- `API.session_id`
|
||
|
||
### 输入参数 `mindmap_json`
|
||
|
||
来源必须是：
|
||
|
||
- `变量转换1.Output`
|
||
|
||
也就是反序列化后的对象，而不是大模型输出的字符串。
|
||
|
||
## 3.7 回复1
|
||
|
||
节点类型：
|
||
|
||
- 回复节点
|
||
|
||
作用：
|
||
|
||
- 将生成后的脑图链接返回给用户
|
||
|
||
当前文案可以写成：
|
||
|
||
```text
|
||
思维导图已生成！请打开以下链接查看：{{url}}
|
||
```
|
||
|
||
如果你在插件节点里直接暴露的是完整路径变量，也可以写成：
|
||
|
||
```text
|
||
思维导图已生成！请打开以下链接查看：{{生成前端页面.Output.Body.url}}
|
||
```
|
||
|
||
如果还想带标题，可以改成：
|
||
|
||
```text
|
||
思维导图已生成！
|
||
标题：{{生成前端页面.Output.Body.title}}
|
||
链接：{{生成前端页面.Output.Body.url}}
|
||
```
|
||
|
||
## 3.8 结束
|
||
|
||
作用：
|
||
|
||
- 标记工作流结束
|
||
|
||
## 4. 当前工作流的数据流
|
||
|
||
可以理解为：
|
||
|
||
```text
|
||
开始
|
||
-> 生成思维导图内容
|
||
-> 生成思维导图内容json
|
||
-> 检查json
|
||
-> 变量转换1(JSON反序列化)
|
||
-> 生成前端页面(插件/API落库)
|
||
-> 回复1
|
||
-> 结束
|
||
```
|
||
|
||
其中最关键的一段是：
|
||
|
||
```text
|
||
检查json.Output.Content (string)
|
||
-> 变量转换1.Output (object)
|
||
-> 生成前端页面.mindmap_json
|
||
```
|
||
|
||
## 5. 插件节点推荐配置
|
||
|
||
如果你使用当前项目现有后端接口，插件建议如下：
|
||
|
||
### 工具基础信息
|
||
|
||
- 工具名称：`create_mindmap`
|
||
- 调用地址：`http://公网IP:8000/api/mindmaps`
|
||
- 请求方法：`POST`
|
||
- 请求体格式：`JSON`
|
||
|
||
### 输入参数
|
||
|
||
- `body.session_id`：`string`
|
||
- `body.mindmap_json`：`object`
|
||
|
||
### 输出参数
|
||
|
||
- `url`：`string`
|
||
- `title`：`string`
|
||
- `unique_id`：`string`
|
||
|
||
如果平台输出变量是以返回体路径显示，也可以直接使用：
|
||
|
||
- `Output.Body.url`
|
||
- `Output.Body.title`
|
||
- `Output.Body.unique_id`
|
||
|
||
## 6. 当前工作流下各节点变量关系
|
||
|
||
| 节点 | 关键输入 | 关键输出 | 备注 |
|
||
|---|---|---|---|
|
||
| 开始 | `topic`、`session_id` | 输入变量本身 | 作为整条链路源头 |
|
||
| 生成思维导图内容 | `topic` | `Output.Content` | 生成脑图内容 |
|
||
| 生成思维导图内容json | 上一节点内容 | `Output.Content` | 输出 JSON 字符串 |
|
||
| 检查json | 上一节点 JSON 字符串 | `Output.Content` | 修复后的 JSON 字符串 |
|
||
| 变量转换1 | `检查json.Output.Content` | `Output`、`Error` | `Output` 为 object |
|
||
| 生成前端页面 | `session_id`、`mindmap_json` | `Output.Body.url` 等 | 调用插件/API |
|
||
| 回复1 | `url` | 文本回复 | 回复用户链接 |
|
||
|
||
## 7. 当前工作流的关键注意点
|
||
|
||
## 7.1 不要让大模型节点直接输出 object 给插件
|
||
|
||
当前这条链里，最稳的方式仍然是：
|
||
|
||
- 大模型输出 `string`
|
||
- 变量转换节点做 `JSON 反序列化`
|
||
- 插件节点接收 `object`
|
||
|
||
## 7.2 插件节点的 `mindmap_json` 必须吃反序列化后的结果
|
||
|
||
正确：
|
||
|
||
- `变量转换1.Output`
|
||
|
||
错误：
|
||
|
||
- `检查json.Output.Content`
|
||
- `生成思维导图内容json.Output.Content`
|
||
|
||
因为这两者还是字符串。
|
||
|
||
## 7.3 插件节点的 `session_id` 不要写死
|
||
|
||
建议引用：
|
||
|
||
- `开始.session_id`
|
||
- 或 `API.session_id`
|
||
|
||
这样才能保证每次生成的脑图都能和对应会话关联。
|
||
|
||
## 7.4 当前工作流还缺少显式异常分支
|
||
|
||
建议后续补一个条件判断：
|
||
|
||
1. 如果 `变量转换1.Error` 不为空，直接回复“JSON 解析失败”
|
||
2. 如果 `生成前端页面.Error` 不为空，直接回复“脑图保存失败”
|
||
|
||
当前不加也能跑，但可维护性会差一些。
|
||
|
||
## 8. 建议的后续优化
|
||
|
||
如果你后面想继续提升稳定性，优先做这几件事：
|
||
|
||
1. 在 `检查json` 节点里进一步收紧输出约束，只允许返回纯 JSON 字符串
|
||
2. 在工作流里增加错误分支，处理反序列化失败和插件调用失败
|
||
3. 插件输出中除了 `url` 外，再将 `title` 一并回复给用户
|
||
4. 如果后面模型经常输出不稳定，可以增加代码节点做 schema 校验
|
||
|
||
## 9. 当前工作流与项目接口的对应关系
|
||
|
||
当前插件节点 `生成前端页面` 对应后端接口：
|
||
|
||
- [backend/app/routers/mindmaps.py](./backend/app/routers/mindmaps.py)
|
||
|
||
接口实际请求体结构为：
|
||
|
||
```json
|
||
{
|
||
"session_id": "string",
|
||
"mindmap_json": {
|
||
"id": "node_0",
|
||
"label": "主题",
|
||
"parent_id": null,
|
||
"level": 0,
|
||
"is_leaf": false,
|
||
"children": []
|
||
}
|
||
}
|
||
```
|
||
|
||
接口实际返回中至少会包含：
|
||
|
||
```json
|
||
{
|
||
"unique_id": "string",
|
||
"title": "string",
|
||
"url": "string"
|
||
}
|
||
```
|