# 完整 PyPI 发布流程指南

## 📋 目录
1. [准备工作](#准备工作)
2. [项目配置](#项目配置)
3. [本地开发和测试](#本地开发和测试)
4. [构建包](#构建包)
5. [发布到 PyPI](#发布到-pypi)
6. [后续版本更新](#后续版本更新)

---

## 🚀 准备工作

### 步骤 1: 注册 PyPI 账户

1. 访问 https://pypi.org/account/register/
2. 填写用户名、邮箱、密码注册账户
3. 验证邮箱激活账户

### 步骤 2: 创建 API Token（推荐）

PyPI 不再支持用户名/密码认证，必须使用 API Token：

1. 登录 https://pypi.org/
2. 点击右上角用户名 → **Account settings**
3. 左侧菜单选择 **API tokens**
4. 点击 **Add API token**
5. 填写信息：
   - **Name**: `hinaagent-core`（随意命名）
   - **Scope**: 
     - **Entire account**（整个账户，可以发布所有包）
     - 或选择特定项目（更安全）
6. 点击 **Add token**
7. **重要**：复制生成的 token（以 `pypi-` 开头），**只显示一次**，妥善保存！

### 步骤 3: 安装必要工具

```bash
# 安装 uv（如果还没安装）
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

---

## 📦 项目配置

### 步骤 1: 检查项目结构

确保项目结构如下：

```
hinaagent_core/
├── pyproject.toml          # 包配置文件（必需）
├── README.md               # 项目说明（推荐）
├── LICENSE                 # 许可证文件（推荐）
├── .gitignore             # Git 忽略规则
└── hinaagent_core/        # 包源代码目录
    ├── __init__.py        # 包含 __version__
    ├── cli.py
    ├── core/
    │   └── __init__.py
    └── api/
        └── __init__.py
```

### 步骤 2: 配置 pyproject.toml

确保 `pyproject.toml` 包含所有必要信息：

```toml
[project]
name = "hinaagent-core"  # PyPI 上的包名（使用连字符）
version = "1.0.0"       # 版本号
description = "HinaAgent核心依赖包，包含核心功能和API服务器相关依赖"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "你的名字", email = "你的邮箱"},
]
keywords = ["ai", "agent", "llm", ...]
dependencies = [
    "mcp>=1.0.0",
    "openai>=1.0.0",
    # ... 其他依赖
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["hinaagent_core"]
```

### 步骤 3: 同步版本号

确保版本号在以下文件中一致：

1. **pyproject.toml**:
   ```toml
   [project]
   version = "1.0.0"
   ```

2. **hinaagent_core/__init__.py**:
   ```python
   __version__ = "1.0.0"
   ```

---

## 💻 本地开发和测试

### 步骤 1: 安装开发环境

```bash
# 进入项目目录
cd hinaagent_core

# 以可编辑模式安装（自动安装依赖）
uv pip install -e .

# 或使用 pip（也可以）
pip install -e .
```

### 步骤 2: 测试导入

```bash
# 测试包是否能正常导入
python -c "import hinaagent_core; print(hinaagent_core.__version__)"

# 测试 CLI 工具
hinaagent-core --info
```

### 步骤 3: 运行测试（如果有）

```bash
# 运行单元测试
uv run pytest

# 或
pytest
```

---

## 🔨 构建包

### 步骤 1: 清理旧构建文件

```bash
# 删除之前的构建产物
rm -rf dist/ build/ *.egg-info

# Windows PowerShell
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
```

### 步骤 2: 构建包

```bash
# 使用 uv 构建（推荐）
uv build

# 或使用传统工具
pip install build
python -m build
```

构建成功后，会在 `dist/` 目录生成：
- `hinaagent-core-1.0.0-py3-none-any.whl` (wheel 包)
- `hinaagent-core-1.0.0.tar.gz` (源码包)

### 步骤 3: 检查构建产物

```bash
# 安装检查工具
uv pip install twine

# 检查包
uv run twine check dist/*
```

应该看到：
```
Checking dist/hinaagent-core-1.0.0-py3-none-any.whl: PASSED
Checking dist/hinaagent-core-1.0.0.tar.gz: PASSED
```

### 步骤 4: 本地测试安装（可选）

```bash
# 创建一个临时虚拟环境测试
python -m venv test_env

# Windows
test_env\Scripts\activate
# macOS/Linux
source test_env/bin/activate

# 安装构建的包
pip install dist/hinaagent-core-1.0.0-py3-none-any.whl

# 测试导入
python -c "import hinaagent_core; print('成功！')"

# 退出测试环境
deactivate
```

---

## 📤 发布到 PyPI

### 方式一：使用 uv publish（推荐，最简单）

```bash
# 设置环境变量（PowerShell）
$env:UV_PUBLISH_TOKEN="pypi-你的token内容"

# 发布到正式 PyPI
uv publish

# 或者使用命令行参数（Windows CMD）
set UV_PUBLISH_TOKEN=pypi-你的token内容 && uv publish
```

### 方式二：交互式输入

```bash
# 运行发布命令
uv publish

# 提示输入时：
# Enter username ('__token__' if using a token): __token__
# Enter password: pypi-你的token内容
```

### 方式三：使用 twine（传统方式）

```bash
# 安装 twine
uv pip install twine

# 发布到正式 PyPI
twine upload dist/*

# 输入凭证：
# Username: __token__
# Password: pypi-你的token内容
```

### 发布成功标志

看到以下输出表示成功：
```
Uploading hinaagent-core-1.0.0-py3-none-any.whl (XX KiB)... ✓
Uploading hinaagent-core-1.0.0.tar.gz (XX KiB)... ✓
```

### 验证发布

1. **浏览器访问**：
   - https://pypi.org/project/hinaagent-core/
   - 等待几分钟让 PyPI 索引更新

2. **测试安装**：
   ```bash
   pip install hinaagent-core
   ```

3. **验证功能**：
   ```bash
   python -c "import hinaagent_core; print(hinaagent_core.__version__)"
   ```

---

## 🔄 后续版本更新

当需要发布新版本时：

### 步骤 1: 更新版本号

**同步更新两个地方：**

1. **pyproject.toml**:
   ```toml
   [project]
   version = "1.0.1"  # 升级版本号
   ```

2. **hinaagent_core/__init__.py**:
   ```python
   __version__ = "1.0.1"
   ```

### 步骤 2: 提交代码（可选）

```bash
git add .
git commit -m "Bump version to 1.0.1"
git tag v1.0.1
git push
git push --tags
```

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

```bash
# 清理
rm -rf dist/ build/ *.egg-info

# 构建
uv build

# 发布
uv publish
```

---

## 📝 快速参考命令

### 完整发布流程（一键命令）

```bash
# 1. 清理
rm -rf dist/ build/ *.egg-info

# 2. 构建
uv build

# 3. 检查
uv run twine check dist/*

# 4. 发布（设置 token）
$env:UV_PUBLISH_TOKEN="pypi-你的token"
uv publish
```

### 常用命令速查

| 任务 | 命令 |
|------|------|
| 安装开发环境 | `uv pip install -e .` |
| 构建包 | `uv build` |
| 检查包 | `uv run twine check dist/*` |
| 发布到 PyPI | `uv publish` |
| 测试安装 | `pip install hinaagent-core` |

---

## ⚠️ 常见问题处理

### 1. 403 Forbidden 错误

**错误信息**：
```
403 Username/Password authentication is no longer supported
```

**解决方案**：
- 必须使用 API Token，不能使用用户名/密码
- 用户名填 `__token__`，密码填 API token

### 2. 包名已被占用

**错误信息**：
```
HTTP Error 403: The user 'xxx' isn't allowed to upload to project 'xxx'
```

**解决方案**：
- 检查 PyPI 上是否已有同名包
- 修改 `pyproject.toml` 中的 `name` 字段
- 更新包代码中所有引用包名的地方

### 3. 版本号冲突

**错误信息**：
```
HTTP Error 400: File already exists
```

**解决方案**：
- 同一版本号不能重复发布
- 升级 `pyproject.toml` 中的版本号
- 重新构建和发布

### 4. 依赖安装失败

**检查项**：
- `requires-python` 版本是否合理
- 依赖包名是否正确
- 版本号范围是否有效

### 5. 编码错误（Windows）

如果看到编码警告：
```bash
# 设置环境变量
$env:UV_LINK_MODE="copy"
uv pip install -e .
```

---

## 🔒 安全建议

1. **保护 API Token**
   - 不要提交 token 到 Git
   - 使用环境变量存储
   - 如果泄露，立即删除旧 token 并创建新的

2. **使用项目范围的 Token**
   - 只给必要的权限
   - 定期轮换 token

3. **不要在公开场合分享 token**
   - 包括截图、日志等

---

## 📚 相关资源

- [PyPI 官方文档](https://packaging.python.org/)
- [uv 官方文档](https://docs.astral.sh/uv/)
- [PEP 621 - 项目元数据](https://peps.python.org/pep-0621/)
- [语义化版本控制](https://semver.org/)

---

## ✅ 发布检查清单

发布前确认：

- [ ] PyPI 账户已注册并验证邮箱
- [ ] API Token 已创建并保存
- [ ] `pyproject.toml` 配置完整正确
- [ ] 版本号已同步（`pyproject.toml` 和 `__init__.py`）
- [ ] README.md 信息准确
- [ ] LICENSE 文件存在
- [ ] 本地测试通过（`uv pip install -e .`）
- [ ] 构建成功（`uv build`）
- [ ] 检查通过（`twine check`）
- [ ] API Token 已准备好

---

**祝你发布顺利！🎉**

