minimap/腾讯云工作流说明.md

腾讯云思维导图工作流说明

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 代码块
• 不要输出前后缀说明

建议要求它输出的格式为：

{
  "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

节点类型：

• 回复节点

作用：

• 将生成后的脑图链接返回给用户

当前文案可以写成：

思维导图已生成！请打开以下链接查看：{{url}}

如果你在插件节点里直接暴露的是完整路径变量，也可以写成：

思维导图已生成！请打开以下链接查看：{{生成前端页面.Output.Body.url}}

如果还想带标题，可以改成：

思维导图已生成！
标题：{{生成前端页面.Output.Body.title}}
链接：{{生成前端页面.Output.Body.url}}

3.8 结束

作用：

• 标记工作流结束

4. 当前工作流的数据流

可以理解为：

开始
  -> 生成思维导图内容
  -> 生成思维导图内容json
  -> 检查json
  -> 变量转换1(JSON反序列化)
  -> 生成前端页面(插件/API落库)
  -> 回复1
  -> 结束

其中最关键的一段是：

检查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. 当前工作流与项目接口的对应关系

当前插件节点 生成前端页面 对应后端接口：

• mindmaps.py

接口实际请求体结构为：

{
  "session_id": "string",
  "mindmap_json": {
    "id": "node_0",
    "label": "主题",
    "parent_id": null,
    "level": 0,
    "is_leaf": false,
    "children": []
  }
}

接口实际返回中至少会包含：

{
  "unique_id": "string",
  "title": "string",
  "url": "string"
}