# freemind AI

**Repository Path**: zyxi/freemind-ai

## Basic Information

- **Project Name**: freemind AI
- **Description**: 基于freemind1.0.1源码进行深度改造，加入AI能力，将文件一键分析，自动转为思维导图，测试人员友好，一键生成测试用例，对外提供MCP服务，自动编写思维导图
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 3
- **Created**: 2026-04-11
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeMind AI

<div align="center">

[![License](https://img.shields.io/badge/license-GPL%20v2-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17%2B-orange.svg)](https://www.oracle.com/java/)
[![Gradle](https://img.shields.io/badge/Gradle-8.5-green.svg)](https://gradle.org/)
[![Version](https://img.shields.io/badge/version-1.0.1--ai-brightgreen.svg)](https://gitee.com/zyxi/freemind-ai)

**基于 FreeMind 1.0.1 深度改造，集成 AI 能力的智能思维导图工具**

[English](README.en.md) | 简体中文

</div>

---

## 📖 目录

- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [构建项目](#构建项目)
- [运行项目](#运行项目)
- [项目结构](#项目结构)
- [配置说明](#配置说明)
- [适用场景](#适用场景)
- [文档导航](#文档导航)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

---

## 项目简介

FreeMind AI 是在经典开源思维导图工具 FreeMind 1.0.1 基础上，深度集成大语言模型（LLM）能力的智能思维导图工具。通过 AI 技术，实现了文档智能解析、自动生成思维导图、测试用例生成等创新功能，同时保留了 FreeMind 轻量、稳定、跨平台的优点。

---

## 🆕 最新更新 (2026-05-24)

### 版本 1.0.1-ai 重要改造

本次更新进行了深度功能增强和缺陷修复，主要包含以下五大核心改造：

#### 1. 🤖 AI关键字智能提取
- 需求分析和用例生成查询知识库时，通过AI大模型智能分析生成关键字
- 提高知识库检索准确性，实现语义级别的关键字提取
- 支持多种提取策略：基于语义、基于词频、基于领域知识

#### 2. 📝 提示词外置化
- 提示词文件支持外置到JAR同级目录（`./prompts/`）
- 采用"外部优先、内部降级"策略，方便用户调整提示词内容
- **无需重新打包**即可修改和优化提示词

#### 3. 🔄 用例生成提示词优化
- 合并详细版和简洁版提示词为单套，减少维护成本
- 实现动态模板注入，支持运行时切换输出格式
- 提供标准版、详细版、简洁版等多种模板格式

#### 4. ✨ 提示词内容优化
- 优化提示词避免AI伪造预期结果
- 需求分析时增加澄清指令，提高分析准确性
- 明确约束"预期结果必须基于需求文档推导"

#### 5. 📦 打包和启动脚本完善
- 新增自动化打包脚本 `build-dist.sh`
- 完善跨平台启动脚本（Linux/Mac/Windows）
- 简化部署流程，一键构建分发包

### 技术改进

- ✅ 解决Gradle循环依赖问题（延迟配置解析）
- ✅ 修复freemind-plugins模块编译错误（补充缺失依赖）
- ✅ 优化正则表达式处理（Unicode转义）
- ✅ 完善Shadow JAR打包流程

### 详细说明

完整的改造说明请参考：[改造总结文档](docs/REFACTORING_SUMMARY.md)

---

## 核心功能

### 🤖 AI 深度增强
- 原生集成大模型能力，支持多个主流 AI 提供商
- 支持的 AI 服务商：
  - OpenAI (GPT-3.5/GPT-4)
  - Anthropic (Claude)
  - Google AI (Gemini)
  - DeepSeek
  - 通义千问 (Qwen)
  - 文心一言 (Wenxin)
  - 智谱 AI (Zhipu)
  - 本地模型部署

### 📄 文件一键分析 → 自动思维导图
- 支持 Word / PDF / Markdown / TXT 智能解析
- 自动识别文档结构，生成层次化思维导图
- 智能提取关键信息，自动组织内容

### 🧪 测试人员友好 · 一键生成测试用例
- 从需求/PRD 自动生成标准测试用例
- 支持多种测试用例格式导出
- 测试场景智能识别与覆盖

### 🚀 自然语言生成思维导图
- 输入一句话，AI 自动生成完整脑图结构
- 支持多轮对话式思维导图优化
- 智能补全和扩展节点

### 🌐 对外提供 MCP 服务
- 标准化接口开放
- 支持与 IDE、自动化平台、CI/CD 集成
- RESTful API 和 WebSocket 支持

---

## 技术架构

### 技术栈

| 类别 | 技术 |
|------|------|
| **核心语言** | Java 17 |
| **构建工具** | Gradle 8.5 |
| **HTTP 客户端** | OkHttp 4.12.0 |
| **JSON 处理** | Jackson 2.16.0 |
| **响应式编程** | RxJava 3.1.8 |
| **文档解析** | Apache PDFBox 3.0.1, Apache POI 5.2.5 |
| **测试框架** | JUnit 5.10.1, Mockito 5.8.0 |
| **代码覆盖率** | JaCoCo 0.8.11 |

### 模块架构

```
freemind-ai/
├── freemind-core/          # 核心模块 - FreeMind 基础功能
├── modules/
│   ├── ai-service/         # AI 服务模块 - 多提供商 AI 集成
│   ├── file-parser/        # 文件解析模块 - 文档智能解析
│   ├── config/             # 配置模块 - 多环境配置管理
│   └── freemind-plugins/   # 插件模块 - 扩展功能
└── accessories/            # 附件资源 - 导出模板等
```

---

## 快速开始

### 环境要求

- **Java**: JDK 17 或更高版本
- **Gradle**: 8.5+ (项目包含 Gradle Wrapper，无需单独安装)
- **操作系统**: Windows / macOS / Linux

### 安装步骤

1. **克隆项目**
```bash
git clone https://gitee.com/zyxi/freemind-ai.git
cd freemind-ai
```

2. **构建项目**
```bash
# 使用 Gradle Wrapper 构建
./gradlew buildAll

# 或者在 Windows 上
gradlew.bat buildAll
```

3. **运行应用**
```bash
# 运行应用
./gradlew :freemind-core:run

# 或运行调试模式
./gradlew :freemind-core:runDebug
```

---

## 构建项目

### 常用构建命令

```bash
# 清理构建产物
./gradlew cleanAll

# 构建所有模块
./gradlew buildAll

# 运行所有测试
./gradlew testAll

# 生成测试覆盖率报告
./gradlew jacocoRootReport
```

### 打包分发

```bash
# 创建分发包（推荐）
# 输出目录：build/dist/
# 包含：freemind.jar（包含所有依赖的可执行 JAR）、启动脚本、依赖库、插件等
./gradlew dist

# 创建所有发布包（ZIP、TAR.GZ）
# 输出目录：build/post/
./gradlew post

# 只构建 Shadow JAR（包含所有依赖的可执行 JAR）
# 输出：modules/freemind-core/build/libs/freemind-core-1.0.1-ai.jar
./gradlew :freemind-core:shadowJar
```

### 模块化构建

```bash
# 只构建核心模块
./gradlew :freemind-core:build

# 只构建 AI 服务模块
./gradlew :ai-service:build

# 只构建文件解析模块
./gradlew :file-parser:build
```

### 创建平台安装包

```bash
# 创建 Mac OS X DMG (仅 macOS)
./gradlew createMacDmg

# 创建 Windows 安装程序脚本 (需要 Inno Setup)
./gradlew createWindowsInstaller

# 创建 Linux 分发包
./gradlew createLinuxPackage

# 创建所有平台包
./gradlew packageAll
```

---

## 运行项目

### 开发模式运行

```bash
# 标准运行
./gradlew :freemind-core:run

# 调试模式 (监听 5005 端口)
./gradlew :freemind-core:runDebug

# 使用 Shadow JAR 运行
./gradlew :freemind-core:runShadow
```

### 从分发包运行（推荐）

```bash
# 1. 构建分发包
./gradlew dist

# 2. 进入分发目录
cd build/dist

# 3. 运行（macOS/Linux）
./freemind.sh

# 或直接运行 JAR（需要 Java 17+）
java -Xms64m -Xmx512m -jar freemind.jar
```

### 直接运行 JAR

```bash
# 构建后直接运行（需要 Java 17+）
java -Xms64m -Xmx512m -Xss8M -jar build/dist/freemind.jar
```

### Windows 用户

```bash
# 构建
gradlew.bat dist

# 运行（命令行版本，显示控制台窗口）
cd build\dist
freemind.bat

# 或运行（GUI版本，不显示控制台窗口）
freemindw.bat

# 或直接运行 JAR
java -Xms64m -Xmx512m -Xss8M -jar freemind.jar
```

---

## 项目结构

```
freemind-ai/
├── build.gradle              # 根项目构建配置
├── gradle.properties         # Gradle 配置属性
├── settings.gradle           # 项目设置
│
├── freemind/                 # 原始 FreeMind 源码
│   ├── common/              # 通用工具类
│   ├── controller/          # 控制器层
│   ├── extensions/          # 扩展功能
│   ├── main/                # 主程序入口
│   ├── modes/               # 模式管理
│   └── view/                # 视图层
│
├── modules/                  # 新增模块
│   ├── ai-service/          # AI 服务模块
│   │   ├── src/main/java/org/freemind/ai/
│   │   │   ├── config/      # AI 配置
│   │   │   ├── exception/   # 异常处理
│   │   │   ├── factory/     # 服务工厂
│   │   │   ├── fallback/    # 降级熔断
│   │   │   ├── model/       # 数据模型
│   │   │   ├── provider/    # AI 提供商实现
│   │   │   └── service/     # 服务接口
│   │   └── build.gradle
│   │
│   ├── file-parser/         # 文件解析模块
│   │   └── build.gradle
│   │
│   ├── config/              # 配置模块
│   │   └── build.gradle
│   │
│   └── freemind-plugins/    # 插件模块
│       └── build.gradle
│
├── lib/                      # 依赖库
│   ├── SimplyHTML/          # HTML 编辑器
│   └── jibx/                # XML 绑定
│
├── accessories/              # 附件资源
│   └── plugins/             # 插件资源
│
├── images/                   # 图标资源
├── doc/                      # 文档
└── build/                    # 构建输出
    ├── dist/                # 分发包
    └── post/                # 发布包
```

---

## 配置说明

### AI 服务配置

在 `modules/config/src/main/resources/` 目录下配置 AI 服务：

```properties
# application.properties

# AI 提供商配置
ai.provider=openai

# OpenAI 配置
ai.openai.api-key=your-api-key
ai.openai.model=gpt-4
ai.openai.base-url=https://api.openai.com/v1

# 其他提供商配置...
```

### 环境配置

项目支持多环境配置：

- `application.properties` - 默认配置
- `application-dev.properties` - 开发环境
- `application-prod.properties` - 生产环境

切换环境：

```bash
# 使用开发环境
./gradlew run -Dspring.profiles.active=dev

# 使用生产环境
./gradlew run -Dspring.profiles.active=prod
```

---

## 适用场景

- ✅ 需求文档自动结构化梳理
- ✅ 测试用例快速批量生成
- ✅ 思路/笔记一键转为思维导图
- ✅ 企业/团队系统集成脑图与 AI 能力
- ✅ 知识管理和内容整理
- ✅ 项目规划和任务分解

---

## 文档导航

### 视频教程

- 🎥 [FreemindAI使用教程](https://www.bilibili.com/video/BV1chRiBgEqh/?share_source=copy_web&vd_source=aaa3ec1f3c687cc2288f78e5958df0d2) - B站视频教程

### 用户文档

- 📚 [用户使用手册](docs/USER_GUIDE.md) - 详细的功能使用说明
- 🤖 [AI 配置指南](docs/AI_CONFIGURATION.md) - AI 服务配置教程
- 🔄 [AI 工作流程指南](docs/AI_WORKFLOW_GUIDE.md) - 从需求分析到测试用例编写全流程
- 🧪 [测试用例导出指南](docs/TESTCASE_EXPORT_GUIDE.md) - 测试用例导出功能说明

### 开发者文档

- 👨‍💻 [开发者指南](docs/DEVELOPER_GUIDE.md) - 开发环境搭建和代码规范
- 🚀 [部署指南](docs/DEPLOYMENT_GUIDE.md) - 生产环境部署方案
- 🔌 [API 文档](docs/API_REFERENCE.md) - MCP 服务接口文档
- 📝 [思维导图标准格式](docs/mindmap-standard-format.md) - Markdown 格式规范
- 📖 [知识库管理](docs/KNOWLEDGE_BASE.md) - 知识库配置和使用

---

## 贡献指南

我们欢迎所有形式的贡献！

### 如何贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 开发规范

- 遵循 Java 代码规范
- 编写单元测试
- 更新相关文档
- 确保所有测试通过

```bash
# 运行测试
./gradlew testAll

# 检查代码覆盖率
./gradlew jacocoRootReport
```

---

## 常见问题

### Q: 构建失败怎么办？
A: 确保使用 JDK 17 或更高版本，并检查网络连接（首次构建需要下载依赖）。

### Q: 运行时提示 "UnsupportedClassVersionError" 怎么办？
A: 项目需要 Java 17+，请检查当前 Java 版本：`java -version`，确保是 17 或更高版本。

### Q: 如何配置 AI 服务？
A: 参考 [配置说明](#配置说明) 章节，在配置文件中设置 API Key。

### Q: 支持哪些操作系统？
A: 支持 Windows、macOS、Linux 三大平台。

### Q: 如何报告 Bug？
A: 请在 [Issues](https://gitee.com/zyxi/freemind-ai/issues) 页面提交问题。

---

## 许可证

本项目基于 GPL v2 许可证开源，详见 [LICENSE](LICENSE) 文件。

---

## 致谢

- 感谢 [FreeMind](https://freemind.sourceforge.io/) 原项目团队的开源贡献
- 感谢所有贡献者的付出

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️ Star！**

Made with ❤️ by 张同学

</div>