# UV 镜像源管理工具 —— 技术方案（v2.0）

## 1. 项目定位
- 面向 Python 开发者，一键管理 `uv` 的 PyPI 镜像源
- 不侵入 `uv` 源码，仅通过修改 `uv.toml` 实现切换
- 独立命令行工具，未来可横向扩展支持 `pip`、`pdm`、`rye` 等

---

## 2. 需求清单（MVP）
| 需求 | 命令 | 输出示例 |
|----|------|-----------|
| 列出内置镜像 | `uvm list` | 带 * 为当前源 |
| 切换镜像 | `uvm use <name>` | `✅ Switched to tsinghua` |
| 测速并排序 | `uvm test` | 表格+推荐 |
| 查看当前源 | `uvm current` | `tsinghua (https://...)` |
| 恢复官方源 | `uvm reset` | 删除自定义配置 |
| 增删自定义源 | `uvm add <name> <url>` / `uvm remove <name>` | 持久化到用户配置 |
| 版本信息 | `uvm --version` | `uvm 0.1.0` |

---

## 3. 技术选型
| 层级 | 方案 | 理由 |
|----|------|------|
| 语言 | Python ≥3.8 | 与 `uv` 社区一致 |
| CLI 框架 | Typer 0.12+ | 自动生成帮助、shell 补全 |
| 配置解析 | tomlkit | 保留注释、格式化友好 |
| 路径管理 | platformdirs | 跨平台用户配置目录 |
| 测速 | aiohttp + asyncio | 并发下载 100 kB 文件，精准耗时 |
| 打包 | build + twine | 标准 PyPI 发布链路 |
| 测试 | pytest + pytest-asyncio + coverage | ≥90% 单测覆盖 |
| 代码质量 | ruff + mypy + pre-commit | 强制 CI 检查 |

---

## 4. 架构设计

```
uvm/
├── uvm/
│   ├── __init__.py
│   ├── __main__.py        # python -m uvm 入口
│   ├── cli.py             # Typer 命令树
│   ├── core/
│   │   ├── config.py      # uv.toml 读写
│   │   ├── mirror.py      # 内置源+用户源合并
│   │   └── speedtest.py   # 异步测速
│   ├── models/
│   │   └── mirror.py      # pydantic 数据模型
│   └── constants.py       # 内置国内镜像表
├── tests/
├── pyproject.toml
└── README.md
```

---

## 5. 数据模型
```python
class Mirror(BaseModel):
    name: str               # 唯一标识
    url: HttpUrl            # 必须以 /simple 结尾
    region: str = "CN"      # 后续可做 Geo 推荐
    builtin: bool = True    # 区分内置/用户自定义
```

---

## 6. 配置存储
| 平台 | 路径 |
|------|------|
| Linux/macOS | `~/.config/uv-mirror/config.toml` |
| Windows | `%APPDATA%\uv-mirror\config.toml` |

文件内容：
```toml
[meta]
version = 1

[mirrors.custom]
company = "https://internal/simple"

[uv]
index_url = "https://pypi.tuna.tsinghua.edu.cn/simple"
```

> 程序只修改 `uv.index_url`，其余字段保持原样；`uv.toml` 不存在时自动创建。

---

## 7. 测速算法
1. 并发 5 线程，下载 `requests-2.31.0-py3-none-any.whl` 前 100 kB
2. 取最小往返时间 (RTT) 而非平均，降低抖动
3. 失败（>5 s 或 404）自动剔除
4. 输出推荐 Top3，写入 `.uvm-cache.json` 供后续快速排序

---

## 8. 发布与安装
```bash
pip install uvm
uvm --version
```

- PyPI 包名已预留 `uvm`（占位项目已上传空包，可联系管理员 transfer）
- 后续提供 Homebrew、AUR、Scoop 等分发

---

## 9. 迭代 Roadmap
| 版本 | 功能 |
|------|------|
| 0.1.0 | MVP 全部子命令，单测 ≥90 % |
| 0.2.0 | 交互式 TUI（textual）选择镜像 |
| 0.3.0 | 系统代理自动识别、镜像站健康检查定时任务 |
| 0.4.0 | 支持 `pip`、`pdm`、`rye` 一键切换 |
| 1.0.0 | 插件化，支持公司内部源认证、LDAP 集成 |

---

## 10. 风险与合规
- 不修改 `uv` 源码，仅操作其公开配置文件，协议兼容
- 镜像站 URL 均来自高校/云厂商官方公告，定期校验
- 开源协议：MIT，允许二次商用

---
