# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## 关键命令

### 测试命令
```bash
# 运行所有测试（必须达到90%覆盖率）
pytest --cov=uvm --cov-report=term-missing --cov-fail-under=90

# 运行特定测试类型
pytest tests/unit/              # 单元测试
pytest tests/integration/       # 集成测试
pytest -m "not slow"            # 跳过慢测试

# 运行单个测试文件
pytest tests/unit/test_models.py -v
```

### 代码质量检查
```bash
# 代码检查和格式化
ruff check --fix .
ruff format .

# 类型检查（严格模式）
mypy uvm/

# 预提交检查
pre-commit run --all-files
```

## 项目特定约定

### 配置文件操作
- 必须使用 `tomlkit` 而非标准 `toml` 库，以保留格式和注释
- 所有配置写入操作前必须调用 `create_backup()` 创建备份
- 配置路径使用 `platformdirs` 跨平台处理，注意 API 兼容性

### 镜像源验证
- 所有镜像源 URL 必须以 `/simple` 结尾（在 Mirror 模型中强制验证）
- 镜像源名称只能包含字母、数字、连字符和下划线
- 内置镜像源不可删除，只能操作自定义镜像源

### 异步并发模式
- 速度测试使用 `asyncio.Semaphore` 控制并发数（默认5个）
- 缓存有效期为24小时，存储在 `~/.cache/uv-mirror/.uvm-cache.json`
- 下载固定100KB的 `requests-2.31.0-py3-none-any.whl` 进行速度测试

### CLI 输出约定
- 使用 Rich 库美化输出，包括表格、颜色和表情符号
- 危险操作（删除、重置）必须使用 `typer.confirm()` 获取用户确认
- 使用特定退出码：EXIT_SUCCESS(0), EXIT_ERROR(1), EXIT_INVALID_ARGS(2)

### 测试隔离要求
- 单元测试必须禁用网络调用（使用 `pytest-socket`）
- 使用 `temp_uv_home` fixture 隔离配置文件，避免污染开发者机器
- Mock platformdirs API 路径确保测试隔离

### Pydantic 模型约定
- 使用 `field_validator` 而非已弃用的 `validator`（Pydantic v2）
- 模型比较基于名称（不区分大小写）
- URL 使用 `HttpUrl` 类型确保格式正确

### 已知问题
- `platformdirs` API 兼容性问题：`user_config_path()` 是属性而非方法
- 位置：`uvm/core/config.py:31` 和 `uvm/core/config.py:41`
- 当前状态：所有配置相关功能因此问题阻塞