安装参考
本文是安装方式的完整参考（pip / uv / Docker / 故障排查）。 如果你只想快速跑起来，5 分钟快速开始 已经覆盖了最简流程。
系统要求
- Python 3.10 或更高版本
- pip 或 uv（推荐）
- 足够的磁盘空间（至少 100MB）
安装方式
方式一：使用 pip 安装
# 安装 ErisPulse
pip install ErisPulse
# 升级到最新版本
pip install ErisPulse --upgrade
方式二：使用 uv 安装（推荐）
uv 是一个更快的 Python 工具链，推荐用于开发环境。
安装 uv
# 使用 pip 安装 uv
pip install uv
# 验证安装
uv --version
创建虚拟环境
# 创建项目目录
mkdir my_bot && cd my_bot
# 安装 Python 3.12
uv python install 3.12
# 创建虚拟环境
uv venv
激活虚拟环境
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
安装 ErisPulse
# 安装 ErisPulse
uv pip install ErisPulse --upgrade
方式三：使用 uv tool 安装（全局 CLI，推荐）
只想把 epsdk 当全局命令行工具使用时，uv tool install 是最干净的方式——
epsdk 运行在独立的工具环境中，不污染任何项目环境：
# 安装（epsdk 立即可用，无需激活任何虚拟环境）
uv tool install ErisPulse
# 升级（或直接使用 epsdk self-update，会自动走此通道）
uv tool upgrade ErisPulse
Note
工具环境里的 epsdk 在项目目录内运行时会自动感知项目 .venv：
epsdk install 将组件安装进项目环境、epsdk run 使用项目环境运行机器人，
框架本体仍由工具环境提供，两边互不干扰。
项目初始化与模块安装
安装完成后，项目初始化、模块安装、运行的完整流程见 5 分钟快速开始。
方式三：使用 ErisPulse-App 客户端（免终端）
不想装 Python 环境？ErisPulse-App 是官方全平台客户端 （Android / Windows / Linux / macOS），手机直接运行，桌面版支持最小化到 系统托盘后台常驻；内置 Python 运行时与 ErisPulse SDK，无需终端与手动配置：
- 从 GitHub Releases 按平台选择下载
（Android
online/offlineAPK、Windowssetup.exe/zip、Linuxtar.gz、macOSzip） - 在 App 内创建并启动实例，通过原生界面管理适配器与模块、浏览模块商店
完整说明见 ErisPulse-App 安装与使用。
验证安装
检查安装
# 检查 ErisPulse 版本
epsdk --version
运行测试
# 运行项目
epsdk run main.py
如果看到类似的输出说明安装成功：
[INFO] 正在初始化 ErisPulse...
[INFO] 适配器已加载: Yunhu
[INFO] 模块已加载: MyModule
[INFO] ErisPulse 初始化完成
常见问题
安装失败
- 检查 Python 版本是否 >= 3.10（推荐 3.10 - 3.14；3.14t free-threaded 无 GIL 构建暂未列入正式支持，框架以实验性 CI 冒烟持续监测）
- 尝试使用
uv pip install ErisPulse替代pip install - 如果提示权限错误，尝试
pip install --user ErisPulse或使用虚拟环境 - 如果在企业代理环境下遇到 SSL 证书错误，尝试
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ErisPulse - 确保网络连接正常，pip 源可访问
配置错误
- 检查
config.toml语法是否正确（TOML 格式对缩进和引号敏感） - 确认所有必需的配置项都已填写
- 查看终端日志获取详细错误信息
- 使用
epsdk init重新生成配置文件
模块安装失败
- 确认模块名称拼写正确（大小写敏感）
- 检查网络连接
- 使用
epsdk list-remote查看可用模块列表 - 确认模块与你当前 SDK 版本兼容
Windows PowerShell 执行策略
如果 PowerShell 提示"无法加载文件...因为在此系统上禁止运行脚本"：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Debian/Ubuntu 虚拟环境创建失败
如果安装脚本提示「虚拟环境创建失败」，且错误信息包含 ensurepip is not available，是因为 Debian/Ubuntu 默认未安装 python3-venv（系统 Python 的 ensurepip 被禁用）：
sudo apt install python3.13-venv # 按实际 Python 版本安装对应包
# 或安装通用元包：
sudo apt install python3-venv
安装后重新运行安装脚本即可。新版安装脚本在检测到该问题时会主动询问并尝试自动安装对应系统包；也可以改用 uv（uv venv 不依赖 ensurepip）。