环境配置

本文档介绍如何配置 Mindra 开源版本的开发环境。

系统要求

安装 Python

Windows

1. 访问 Python 官网
2. 下载 Python 3.8+ 安装包
3. 运行安装程序，勾选 "Add Python to PATH"
4. 点击 "Install Now" 完成安装

验证安装：

python --version
pip --version

macOS

使用 Homebrew 安装：

brew install python@3.11

或使用 pyenv 管理多版本：

pyenv install 3.11.0
pyenv global 3.11.0

Linux

Ubuntu/Debian：

sudo apt update
sudo apt install python3.11 python3-pip

CentOS/RHEL：

sudo dnf install python3.11 python3-pip

创建虚拟环境（推荐）

使用虚拟环境可以隔离项目依赖：

使用 venv

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

使用 conda

# 创建环境
conda create -n mindra python=3.11

# 激活环境
conda activate mindra

安装 Python 依赖

激活虚拟环境后，安装所需依赖：

pip install PySide6 openai pymysql PyYAML

依赖说明

安装指定版本

pip install PySide6==6.6.1 openai==1.10.0 pymysql==1.1.0 PyYAML==6.0.1

安装 MySQL（可选）

如果需要用户管理功能，需要安装 MySQL。

Windows

1. 访问 MySQL 官网
2. 下载 MySQL Installer
3. 选择 "Server only" 或 "Full" 安装
4. 设置 root 密码，记住该密码

macOS

brew install mysql
brew services start mysql

Linux

Ubuntu/Debian：

sudo apt install mysql-server
sudo mysql_secure_installation

验证安装

创建测试脚本 test_env.py：

import sys
print(f"Python 版本: {sys.version}")

try:
    import PySide6
    print(f"PySide6 版本: {PySide6.__version__}")
except ImportError as e:
    print(f"PySide6 导入失败: {e}")

try:
    import openai
    print("openai 已安装")
except ImportError as e:
    print(f"openai 导入失败: {e}")

try:
    import pymysql
    print(f"pymysql 版本: {pymysql.__version__}")
except ImportError as e:
    print(f"pymysql 导入失败: {e}")

try:
    import yaml
    print(f"PyYAML 已安装")
except ImportError as e:
    print(f"PyYAML 导入失败: {e}")

运行测试：

python test_env.py

开发工具推荐

IDE/编辑器

• PyCharm: 专业的 Python IDE，提供强大的调试和代码补全
• VS Code: 轻量级编辑器，安装 Python 扩展后功能强大
• Sublime Text: 快速轻量的编辑器

VS Code 推荐扩展

• Python (Microsoft)
• Pylance (Microsoft)
• Qt for Python (Sean Wu)

常见问题

PySide6 安装失败

问题: pip 安装 PySide6 时失败

解决方案:

# 使用国内镜像
pip install PySide6 -i https://pypi.tuna.tsinghua.edu.cn/simple

MySQL 连接失败

问题: 无法连接到 MySQL 服务器

解决方案:

1. 检查 MySQL 服务是否启动
2. 验证用户名和密码是否正确
3. 检查防火墙设置

缺少 Qt 依赖

问题: 运行时提示缺少 Qt 库

解决方案: PySide6 应包含所需的 Qt 库，尝试重新安装：

pip uninstall PySide6
pip install PySide6