# EZAI PyPI发布指南

本指南将帮助你将EZAI库发布到PyPI平台。

## 📋 发布前检查清单

### 1. 环境准备
- [ ] 安装Python 3.7+
- [ ] 安装发布工具: `pip install build twine`
- [ ] 注册PyPI账号: https://pypi.org/account/register/

### 2. 项目检查
- [ ] 版本号更新 (`setup.py` 和 `pyproject.toml`)
- [ ] README.md文档完整
- [ ] LICENSE文件存在
- [ ] 所有依赖项正确列出
- [ ] 测试通过

## 🚀 发布步骤

### 第一步：清理之前的构建
```bash
# 删除旧的构建文件
rm -rf build/ dist/ *.egg-info/
```

### 第二步：运行测试
```bash
# 运行单元测试
python -m pytest tests/

# 或者运行快速测试
python quick_test.py
```

### 第三步：构建包
```bash
# 使用现代构建工具
python -m build
```

这将在 `dist/` 目录下生成两个文件：
- `ezai-1.0.0-py3-none-any.whl` (wheel包)
- `ezai-1.0.0.tar.gz` (源码包)

### 第四步：检查包
```bash
# 检查包的完整性
twine check dist/*
```

### 第五步：上传到PyPI
```bash
# 上传到正式PyPI
twine upload dist/*

# 或者先上传到测试PyPI
twine upload --repository testpypi dist/*
```

## 🧪 测试安装

### 从测试PyPI安装
```bash
pip install --index-url https://test.pypi.org/simple/ ezai
```

### 从正式PyPI安装
```bash
pip install ezai
```

## 📝 版本管理

### 更新版本号
1. 修改 `setup.py` 中的 `version="1.0.0"`
2. 修改 `pyproject.toml` 中的 `version = "1.0.0"`
3. 修改 `ezai/__init__.py` 中的 `__version__ = "1.0.0"`

### 版本号规范
- `1.0.0` - 主版本.次版本.修订版本
- 主版本：不兼容的API修改
- 次版本：向下兼容的功能性新增
- 修订版本：向下兼容的问题修正

## 🔧 常见问题

### 1. 上传失败：文件名已存在
- 解决方案：更新版本号后重新构建

### 2. 依赖项问题
- 确保所有依赖在 `requirements.txt` 中正确列出
- 可选依赖放在 `extras_require` 中

### 3. 测试失败
- 检查导入路径是否正确
- 确保所有必需的文件都包含在包中

### 4. 文档格式问题
- README.md必须是有效的Markdown格式
- 使用UTF-8编码

## 📊 发布后维护

### 监控下载量
访问PyPI项目页面查看下载统计

### 处理用户反馈
- GitHub Issues
- PyPI评论
- 邮件反馈

### 持续改进
- 修复bug
- 添加新功能
- 更新文档

## 🎯 最佳实践

1. **语义化版本控制**：遵循SemVer规范
2. **自动化测试**：在CI/CD中运行测试
3. **文档同步**：保持README和代码文档同步
4. **变更日志**：维护CHANGELOG.md记录变更
5. **标签管理**：在Git中为每个发布版本打标签

## 📞 获取帮助

- PyPI文档：https://packaging.python.org/
- Twine文档：https://twine.readthedocs.io/
- 构建工具文档：https://build.pypa.io/

---

祝发布顺利！🎉