# 发布快速入门 🚀

5分钟快速了解如何发布 Python 包到 PyPI。

## 📋 前提条件

1. **PyPI 账号**
   - 注册: https://pypi.org/account/register/
   - TestPyPI (测试): https://test.pypi.org/account/register/

2. **API Token**
   - 获取: https://pypi.org/manage/account/token/
   - 保存到环境变量或 `~/.pypirc`

3. **开发依赖已安装**
   ```bash
   uv sync --group dev
   ```

---

## ⚡ 快速发布（3 步）

### 方法 1: 使用自动化脚本（推荐）

```bash
# 一键发布
./scripts/release.sh 0.1.0
```

脚本会自动完成：
- ✅ 运行测试
- ✅ 代码质量检查
- ✅ 更新版本号
- ✅ 创建 Git 标签
- ✅ 构建包
- ✅ 上传到 PyPI

### 方法 2: 手动发布（3 个命令）

```bash
# 1. 构建
uv build

# 2. 测试发布（可选但推荐）
uv run twine upload --repository testpypi dist/*

# 3. 正式发布
uv run twine upload dist/*
```

---

## 📝 第一次发布详细步骤

### 步骤 1: 配置 PyPI 凭证

创建 `~/.pypirc`:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-YOUR-TOKEN-HERE

[testpypi]
username = __token__
password = pypi-YOUR-TESTPYPI-TOKEN-HERE
```

或设置环境变量：

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-YOUR-TOKEN-HERE
```

### 步骤 2: 准备发布

```bash
# 1. 确保测试通过
uv run pytest --cov=agentcenter --cov-fail-under=80

# 2. 格式化代码
uv run black src/ tests/
uv run ruff check src/ tests/ --fix

# 3. 更新版本号 (编辑 pyproject.toml)
# version = "0.1.0"

# 4. 更新 CHANGELOG.md
# 添加本版本的更新内容

# 5. 提交并打标签
git add .
git commit -m "Release version 0.1.0"
git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin main --tags
```

### 步骤 3: 构建和发布

```bash
# 1. 清理旧构建
rm -rf dist/

# 2. 构建包
uv build

# 3. 检查构建产物
ls -lh dist/
# 应该看到:
# agentcenter-0.1.0.tar.gz
# agentcenter-0.1.0-py3-none-any.whl

# 4. 上传到 TestPyPI（测试）
uv run twine upload --repository testpypi dist/*

# 5. 测试安装
pip install --index-url https://test.pypi.org/simple/ agentcenter==0.1.0

# 6. 上传到 PyPI（正式）
uv run twine upload dist/*
```

### 步骤 4: 验证

```bash
# 等待几分钟让 PyPI 更新索引

# 安装
pip install agentcenter

# 测试
python -c "from agentcenter import AgentCenter; print('Success!')"

# 查看 PyPI 页面
# https://pypi.org/project/agentcenter/
```

---

## 🔧 常用命令

```bash
# 查看当前版本
grep version pyproject.toml

# 构建包
uv build

# 检查包内容
tar -tzf dist/agentcenter-0.1.0.tar.gz

# 上传到 TestPyPI
uv run twine upload --repository testpypi dist/*

# 上传到 PyPI
uv run twine upload dist/*

# 从 TestPyPI 安装
pip install --index-url https://test.pypi.org/simple/ agentcenter

# 从 PyPI 安装
pip install agentcenter

# 使用 uv 安装
uv add agentcenter
```

---

## 📦 版本号规则

遵循语义化版本 (MAJOR.MINOR.PATCH):

```
0.1.0  →  0.1.1   Bug 修复
0.1.1  →  0.2.0   新功能（兼容）
0.2.0  →  1.0.0   第一个稳定版本
1.0.0  →  2.0.0   破坏性变更
```

---

## ⚠️ 重要提醒

1. **PyPI 发布是永久的** - 无法删除已发布的版本
2. **先测试再发布** - 使用 TestPyPI 测试
3. **版本号唯一** - 同一版本号只能发布一次
4. **包名唯一** - 确保包名未被占用

---

## 🔍 故障排除

### 问题 1: 403 Forbidden

**原因**: Token 无效或权限不足

**解决**:
```bash
# 检查 token
echo $TWINE_PASSWORD

# 重新设置 token
export TWINE_PASSWORD=pypi-YOUR-NEW-TOKEN
```

### 问题 2: 包名已存在

**原因**: PyPI 上已有同名包

**解决**:
- 在 PyPI 搜索确认包名
- 修改 `pyproject.toml` 中的包名
- 或联系现有包的所有者

### 问题 3: 版本号已存在

**原因**: 该版本已发布

**解决**:
- 更新版本号 (例如 0.1.0 → 0.1.1)
- 清理 dist/ 目录
- 重新构建

---

## 📚 更多资源

- **完整文档**: `docs/publishing.md`
- **发布检查清单**: `RELEASE_CHECKLIST.md`
- **自动化脚本**: `scripts/release.sh`

---

## 🎯 一键复制命令

### 完整发布流程

```bash
# 测试、构建、发布一气呵成
uv run pytest --cov=agentcenter --cov-fail-under=80 && \
uv run black src/ tests/ && \
uv run ruff check src/ tests/ && \
rm -rf dist/ && \
uv build && \
echo "上传到 TestPyPI..." && \
uv run twine upload --repository testpypi dist/* && \
echo "测试安装: pip install --index-url https://test.pypi.org/simple/ agentcenter" && \
read -p "确认上传到 PyPI? (y/n) " -n 1 -r && echo && \
[[ $REPLY =~ ^[Yy]$ ]] && uv run twine upload dist/*
```

---

## ✅ 发布成功！

发布成功后，你的包将在以下位置可见：

- PyPI: https://pypi.org/project/agentcenter/
- 安装: `pip install agentcenter`
- 导入: `from agentcenter import AgentCenter`

🎉 恭喜！你已经成功发布了 Python 包！
