Fu-Jie_openwebui-extensions/plugins/actions/smart-mind-map/README_CN.md

思维导图 - 思维导图生成插件

作者: Fu-Jie | 版本: 0.7.2 | 许可证: MIT

重要提示：为了确保所有插件的可维护性和易用性，每个插件都应附带清晰、完整的文档，以确保其功能、配置和使用方法得到充分说明。

思维导图是一个强大的 OpenWebUI 动作插件，能够智能分析长篇文本内容，自动生成交互式思维导图，帮助用户结构化和可视化知识。

---

核心特性

• ✅ 智能文本分析: 自动识别文本的核心主题、关键概念和层次结构
• ✅ 交互式可视化: 基于 Markmap.js 生成美观的交互式思维导图
• ✅ 多语言支持: 根据用户语言自动调整输出
• ✅ 实时渲染: 在聊天界面中直接渲染思维导图，无需跳转
• ✅ 导出功能: 支持复制 SVG 代码和 Markdown 源码
• ✅ 自定义配置: 可配置 LLM 模型、最小文本长度等参数

---

工作原理

1. 文本提取: 从用户消息中提取文本内容（自动过滤 HTML 代码块）
2. 智能分析: 使用配置的 LLM 模型分析文本结构
3. Markdown 生成: 将分析结果转换为 Markmap 兼容的 Markdown 格式
4. 可视化渲染: 在 HTML 模板中使用 Markmap.js 渲染思维导图
5. 交互展示: 在聊天界面中以可交互的形式展示给用户

---

安装与配置

1. 插件安装

1. 下载 思维导图.py 文件到本地
2. 在 OpenWebUI 管理员设置中找到"插件"（Plugins）部分
3. 选择"动作"（Actions）类型
4. 上传下载的文件
5. 刷新页面，插件即可使用

2. 模型配置

插件需要访问 LLM 模型来分析文本。请确保：

• 您的 OpenWebUI 实例中配置了至少一个可用的 LLM 模型
• 推荐使用快速、经济的模型（如 gemini-2.5-flash）来获得最佳体验
• 在插件设置中配置 LLM_MODEL_ID 参数

3. 插件启用

在聊天设置中选择"思维导图"动作插件即可启用。

4. 主题颜色风格一致性（可选）

为了使思维导图与 OpenWebUI 主题颜色风格保持一致，需要在 OpenWebUI 中启用 artifact 的同源访问：

• 配置位置：在 OpenWebUI 用户设置中找到"界面"→"产物"部分（Settings → Interface → Products/Artifacts）
• 启用选项：勾选 "iframe 沙盒允许同源访问"（Allow same-origin access for artifacts / iframe sandbox allow-same-origin）
• 沙箱属性：确保 iframe 的 sandbox 属性包含 allow-same-origin 和 allow-scripts

启用后，思维导图会自动检测并应用 OpenWebUI 的当前主题（亮色/暗色），无需手动配置。

---

配置参数

您可以在插件的设置（Valves）中调整以下参数：

参数	默认值	描述
show_status	true	是否在聊天界面显示操作状态更新（如"正在分析..."）。
LLM_MODEL_ID	gemini-2.5-flash	用于文本分析的 LLM 模型 ID。推荐使用快速且经济的模型。
MIN_TEXT_LENGTH	100	进行思维导图分析所需的最小文本长度（字符数）。文本过短将无法生成有效的导图。

---

使用方法

基本使用

1. 在聊天设置中启用"思维导图"动作
2. 在对话中输入或粘贴长篇文本内容（至少 100 字符）
3. 发送消息后，插件会自动分析并生成思维导图
4. 思维导图将在聊天界面中直接渲染显示

使用示例

输入文本：

人工智能（AI）是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统。
主要应用领域包括：
1. 机器学习 - 使计算机能够从数据中学习
2. 自然语言处理 - 理解和生成人类语言
3. 计算机视觉 - 识别和处理图像
4. 机器人技术 - 创建能够与物理世界交互的智能系统

生成结果： 插件会生成一个以"人工智能"为中心主题的交互式思维导图，包含主要应用领域及其子概念。

导出功能

生成的思维导图支持两种导出方式：

1. 复制 SVG 代码: 点击"复制 SVG 代码"按钮，可将思维导图的 SVG 格式复制到剪贴板
2. 复制 Markdown: 点击"复制 Markdown"按钮，可将原始 Markdown 格式复制到剪贴板

---

技术架构

前端渲染

• Markmap.js: 开源的思维导图渲染引擎
• D3.js: 数据可视化基础库
• 响应式设计: 适配不同屏幕尺寸

后端处理

• LLM 集成: 通过 generate_chat_completion 调用配置的模型
• 文本预处理: 自动过滤 HTML 代码块，提取纯文本内容
• 格式转换: 将 LLM 输出转换为 Markmap 兼容的 Markdown 格式

安全性

• XSS 防护: 自动转义 </script> 标签，防止脚本注入
• 输入验证: 检查文本长度，避免无效请求

---

故障排除

问题：插件无法启动

解决方案：

• 检查 OpenWebUI 日志，查看是否有错误信息
• 确认插件已正确上传并启用
• 验证 OpenWebUI 版本是否支持动作插件

问题：文本内容过短

现象： 提示"文本内容过短，无法进行有效分析"

解决方案：

• 确保输入的文本至少包含 100 个字符（默认配置）
• 可以在插件设置中降低 MIN_TEXT_LENGTH 参数值
• 提供更详细、结构化的文本内容

问题：思维导图未生成

解决方案：

• 检查 LLM_MODEL_ID 是否配置正确
• 确认配置的模型在 OpenWebUI 中可用
• 查看后端日志，检查是否有 LLM 调用失败的错误
• 验证用户是否有足够的权限访问配置的模型

问题：思维导图显示错误

现象： 显示"⚠️ 思维导图渲染失败"

解决方案：

• 检查浏览器控制台的错误信息
• 确认 Markmap.js 和 D3.js 库是否正确加载
• 验证生成的 Markdown 格式是否符合 Markmap 规范
• 尝试刷新页面重新渲染

问题：导出功能不工作

解决方案：

• 确认浏览器支持剪贴板 API
• 检查浏览器是否阻止了剪贴板访问权限
• 使用现代浏览器（Chrome、Firefox、Edge 等）

---

最佳实践

1. 文本准备

   • 提供结构清晰、层次分明的文本内容
   • 使用段落、列表等格式帮助 LLM 理解文本结构
   • 避免过于冗长或无结构的文本

2. 模型选择

   • 对于日常使用，推荐 gemini-2.5-flash 等快速模型
   • 对于复杂文本分析，可以使用更强大的模型（如 GPT-4）
   • 根据需求平衡速度和分析质量

3. 性能优化

   • 合理设置 MIN_TEXT_LENGTH，避免处理过短的文本
   • 对于特别长的文本，考虑先进行摘要再生成思维导图
   • 在生产环境中关闭 show_status 以减少界面更新

---

更新日志

v0.7.2 (当前版本)

• 优化文本提取逻辑，自动过滤 HTML 代码块
• 改进错误处理和用户反馈
• 增强导出功能的兼容性
• 优化 UI 样式和交互体验

---

许可证

本插件采用 MIT 许可证发布。

贡献

欢迎提交问题报告和改进建议！请访问项目仓库：awesome-openwebui

---

相关资源

• Markmap 官方网站
• OpenWebUI 文档
• D3.js 官方网站