# 发布到 PyPI 教程（使用 uv）

## 前置准备

### 1. 注册 PyPI 账号

- 正式环境：https://pypi.org/account/register/
- 测试环境（建议先试）：https://test.pypi.org/account/register/

### 2. 创建 API Token

1. 登录 PyPI → 点击右上角用户名 → **Account settings**
2. 滚动到 **API tokens** → **Add API token**
3. Scope 选择 **Entire account**（首次发布）或指定项目
4. 复制生成的 Token（以 `pypi-` 开头），**只显示一次**

### 3. 确认已安装 uv

```bash
uv --version
```

如果没有安装：
```bash
pip install uv
# 或 Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

---

## 发布流程

### 第一步：检查 pyproject.toml

确认以下字段正确：

```toml
[project]
name = "ai2-Abridge"       # ← PyPI 上的包名，必须全局唯一
version = "1.0.0"           # ← 每次发布必须递增
```

> ⚠️ **包名一旦发布无法更改**，请确认 `name` 是你想要的。

### 第二步：构建包

```bash
cd d:\PersonalArchive\Person\Tools\aib_project

uv build
```

构建成功后会在 `dist/` 目录生成：

```
dist/
├── ai2_abridge-1.0.0-py3-none-any.whl    # wheel 包
└── ai2_abridge-1.0.0.tar.gz              # 源码包
```

### 第三步：上传到 TestPyPI（首次建议先测试）

```bash
uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-你的TestPyPI-Token
```

测试安装：

```bash
pip install --index-url https://test.pypi.org/simple/ ai2-Abridge
```

### 第四步：上传到正式 PyPI

```bash
uv publish --token pypi-你的PyPI-Token
```

发布成功后即可：

```bash
pip install ai2-Abridge
```

---

## 免 Token 参数上传

### 方式一：环境变量

```bash
# PowerShell
$env:UV_PUBLISH_TOKEN = "pypi-你的Token"
uv publish

# Linux / macOS
export UV_PUBLISH_TOKEN="pypi-你的Token"
uv publish
```

### 方式二：使用 keyring

```bash
pip install keyring
uv publish --keyring-provider subprocess
```

---

## 在其他项目中使用

```bash
pip install ai2-Abridge
# 或用 uv
uv add ai2-Abridge
```

```python
from aib import AIBridge

bridge = AIBridge(vendor="gemini", api_key="your-key")
response = bridge.chat("Hello!")
print(response.content)
```

---

## 版本更新发布

```bash
# 1. 修改版本号（两处同步修改）
#    pyproject.toml  → version = "1.0.1"
#    src/aib/__init__.py → __version__ = "1.0.1"

# 2. 清理旧构建 + 重新构建 + 上传
rmdir /s /q dist
uv build
uv publish --token pypi-你的Token
```

---

## 常见问题

| 问题 | 解决方案 |
|------|----------|
| `File already exists` | 版本号未递增，修改 `version` 后重新构建 |
| `Invalid or non-existent authentication` | Token 错误或过期，重新生成 |
| `The name is too similar to an existing project` | 包名被占用，修改 `pyproject.toml` 中的 `name` |
| 安装后 `import aib` 报错 | 检查 `[tool.hatch.build.targets.wheel]` 中 `packages` 路径是否正确 |

---

## 快速命令速查

```bash
uv build && uv publish --token pypi-你的Token
```
