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

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

**作者:** [Fu-Jie](https://github.com/Fu-Jie) | **版本:** 0.9.1 | **许可证:** MIT

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

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

---

## 🔥 v0.9.1 更新亮点

**新功能：图片输出模式**

- **静态图片支持**：新增 `OUTPUT_MODE` 配置参数。
  - `html`（默认）：交互式 HTML 思维导图。
  - `image`：静态 SVG 图片直接嵌入 Markdown。
- **高效存储**：图片模式将 SVG 上传至 `/api/v1/files`，避免聊天记录中出现超长 Base64 字符串。
- **智能特性**：生成的图片支持自动响应式宽度和自动主题检测（亮色/暗色）。

---

## 核心特性

- ✅ **智能文本分析**：自动识别文本的核心主题、关键概念和层次结构
- ✅ **交互式可视化**：基于 Markmap.js 生成美观的交互式思维导图
- ✅ **高分辨率 PNG 导出**：导出高质量的 PNG 图片（9 倍分辨率，约 1-2MB 文件大小）
- ✅ **完整控制面板**：缩放控制（+/-/重置）、展开层级选择（全部/2级/3级）、全屏模式
- ✅ **主题切换**：手动主题切换按钮（亮色/暗色）与自动主题检测
- ✅ **深色模式支持**：完整的深色模式支持，自动检测与手动覆盖
- ✅ **多语言支持**：根据用户语言自动调整输出
- ✅ **实时渲染**：在聊天界面中直接渲染思维导图，无需跳转
- ✅ **导出功能**：支持 PNG、SVG 代码和 Markdown 源码导出
- ✅ **自定义配置**：可配置 LLM 模型、最小文本长度等参数
- ✅ **图片输出模式**：生成静态 SVG 图片直接嵌入 Markdown（无交互式 HTML）

---

## 工作原理

1. **文本提取**：从用户消息中提取文本内容（自动过滤 HTML 代码块）
2. **智能分析**：使用配置的 LLM 模型分析文本结构
3. **Markdown 生成**：将分析结果转换为 Markmap 兼容的 Markdown 格式
4. **可视化渲染**：在 HTML 模板中使用 Markmap.js 渲染思维导图，并优化字体层级（H1：22px 粗体，H2：18px 粗体）
5. **交互展示**：以可交互的形式展示给用户，并提供完整的控制面板
6. **主题检测**：自动检测并应用当前 OpenWebUI 的主题（亮色/暗色模式）
7. **导出选项**：提供 PNG（高分辨率）、SVG 和 Markdown 导出功能

---

## 安装与配置

### 1. 插件安装

1. 下载 `smart_mind_map_cn.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` | 进行思维导图分析所需的最小文本长度（字符数）。文本过短将无法生成有效的导图。 |
| `CLEAR_PREVIOUS_HTML` | `false` | 在生成新的思维导图时，是否清除之前由插件生成的 HTML 内容。 |
| `MESSAGE_COUNT` | `1` | 用于生成思维导图的最近消息数量（1-5）。 |
| `OUTPUT_MODE` | `html` | 输出模式：`html` 为交互式 HTML（默认），`image` 为嵌入静态 Markdown 图片。 |

---

## 使用方法

### 基本使用

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

### 使用示例

**输入文本：**

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

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

### 导出功能

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

1. **下载 PNG**：点击“📥 下载 PNG”按钮，可将思维导图导出为高分辨率 PNG 图片（9 倍分辨率，约 1-2MB 文件大小）
2. **复制 SVG 代码**：点击“复制 SVG 代码”按钮，可将思维导图的 SVG 格式复制到剪贴板
3. **复制 Markdown**：点击“复制 Markdown”按钮，可将原始 Markdown 格式复制到剪贴板

### 控制面板

交互式思维导图包含完整的控制面板：

- **缩放控制**：`+`（放大）、`-`（缩小）、`↻`（重置视图）
- **展开层级**：在“全部”、“2 级”、“3 级”之间切换，控制节点展开深度
- **全屏模式**：进入全屏模式，获得更好的查看体验
- **主题切换**：手动在亮色和暗色主题之间切换

---

## 技术架构

### 前端渲染

- **Markmap.js**：开源的思维导图渲染引擎
- **D3.js**：数据可视化基础库
- **响应式设计**：适配不同屏幕尺寸
- **字体层级**：优化的字体排版，H1（22px 粗体）和 H2（18px 粗体），提供更好的可读性

### PNG 导出技术

- **SVG 转 Canvas**：将思维导图 SVG 转换为 Canvas 以导出 PNG
- **ForeignObject 处理**：正确处理 SVG 元素中的 HTML 内容
- **高分辨率**：9 倍缩放因子，输出打印级质量（约 1-2MB 文件大小）
- **主题保持**：在导出的 PNG 中保持当前主题（亮色/暗色）

### 主题检测机制

自动检测并应用主题，具有 4 级优先级：

1. **显式切换**：用户手动点击主题切换按钮（最高优先级）
2. **Meta 标签**：从父文档读取 `<meta name="theme-color">`
3. **Class/Data-Theme**：检查父文档 HTML/body 的 `class` 或 `data-theme` 属性
4. **系统偏好**：回退到 `prefers-color-scheme` 媒体查询

### 后端处理

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

### 安全性增强

- **XSS 防护**：自动转义 `</script>` 标签，防止脚本注入
- **输入验证**：检查文本长度，避免无效请求
- **非冒泡事件**：按钮点击使用 `stopPropagation()` 防止导航拦截

---

## 故障排除

### 问题：插件无法启动

**解决方案：**

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

### 问题：文本内容过短

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

**解决方案：**

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

### 问题：思维导图未生成

**解决方案：**

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

### 问题：思维导图显示错误

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

**解决方案：**

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

### 问题：PNG 导出不工作

**现象：**PNG 下载按钮不工作或生成空白/损坏的图片

**解决方案：**

- 确保浏览器支持 HTML5 Canvas API（所有现代浏览器都支持）
- 检查浏览器控制台是否有与 `toDataURL()` 或 Canvas 渲染相关的错误
- 确保思维导图在点击导出前已完全渲染
- 尝试刷新页面并重新生成思维导图
- 使用 Chrome 或 Firefox，获得最佳 PNG 导出兼容性

### 问题：主题未自动检测

**现象：**思维导图不匹配 OpenWebUI 主题颜色

**解决方案：**

- 在 OpenWebUI 设置 → 界面 → 产物中，启用“iframe 沙盒允许同源访问”
- 验证 iframe 的 sandbox 属性包含 `allow-same-origin` 和 `allow-scripts`
- 确保父文档有 `<meta name="theme-color">` 标签或主题 class/属性
- 使用手动主题切换按钮覆盖自动检测
- 检查浏览器控制台是否有跨域错误

### 问题：导出功能不工作

**解决方案：**

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

---

## 最佳实践

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

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

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

4. **导出质量**
   - **PNG 导出**：最适合演示、文档和分享（9 倍分辨率适合打印）
   - **SVG 导出**：最适合在矢量图形工具中进一步编辑（无限缩放）
   - **Markdown 导出**：最适合版本控制、协作和重新生成

5. **主题一致性**
   - 启用同源访问以实现自动主题检测
   - 如果自动检测失败，使用手动主题切换
   - 在切换到所需主题后导出 PNG，以保持视觉一致性

---

## 依赖要求

本插件仅使用 OpenWebUI 的内置依赖，**无需安装额外的软件包。**

---

## 更新日志

### v0.9.1

**新功能：图片输出模式**

- 新增 `OUTPUT_MODE` 配置参数，支持两种模式：
  - `html`（默认）：交互式 HTML 思维导图，带完整控制面板
  - `image`：静态 SVG 图片直接嵌入 Markdown（上传至 `/api/v1/files`）
- 图片模式特性：
  - 自动响应式宽度（适应聊天容器）
  - 自动主题检测（亮色/暗色）
  - 通过 Chat API 持久化存储（刷新页面后保留）
  - 高效文件存储（聊天记录中无超长 Base64 字符串）

**改进项：**

- 实现健壮的 Chat API 更新机制，带重试逻辑
- 修复消息持久化，同时更新 `messages[]` 和 `history.messages`
- 添加 Event API 实现即时前端更新
- 移除不必要的 `SVG_WIDTH` 和 `SVG_HEIGHT` 参数（现已自动计算）

**技术细节：**

- 图片模式使用 `__event_call__` 在浏览器中执行 JavaScript
- SVG 离屏渲染，转换为 Blob，并上传至 OpenWebUI Files API
- 通过 OpenWebUI Backend-Controlled API 流程更新聊天消息为 `/api/v1/files/{id}/content` URL

### v0.8.2

- 移除输出中的调试信息

### v0.8.0 (Previous Version)

**主要功能：**

- 添加高分辨率 PNG 导出（9 倍分辨率，约 1-2MB 文件大小）
- 实现完整的控制面板，包含缩放控制（+/-/重置）
- 添加展开层级选择（全部/2级/3级）
- 集成全屏模式，自动适应
- 添加手动主题切换按钮（亮色/暗色）
- 实现 4 级优先级的自动主题检测

**改进项：**

- 优化字体层级（H1：22px 粗体，H2：18px 粗体）
- 增强深色模式，完整的主题支持
- 改进 PNG 导出技术（SVG 转 Canvas，处理 foreignObject）
- 在导出的 PNG 图片中保持主题
- 增强安全性，按钮事件使用非冒泡机制

**Bug 修复：**

- 修复跨域 iframe 中的主题检测问题
- 解决 SVG 中 HTML 内容的 PNG 导出问题
- 改进与 OpenWebUI 主题系统的兼容性

### v0.7.2

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

---

## 许可证

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

## 贡献

欢迎提交问题报告和改进建议！请访问项目仓库：[awesome-openwebui](https://github.com/Fu-Jie/awesome-openwebui)

---

## 相关资源

- [Markmap 官方网站](https://markmap.js.org/)
- [OpenWebUI 文档](https://docs.openwebui.com/)
- [D3.js 官方网站](https://d3js.org/)