# AGENTS.md

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

## Project Debug Rules (Non-Obvious Only)

- Configuration operations fail silently due to `platformdirs` API compatibility issue
- Check `uvm/core/config.py:31` and `uvm/core/config.py:41` for `user_config_path()` property vs method
- Speed test cache stored in `~/.cache/uv-mirror/.uvm-cache.json` with 24-hour expiration
- Network timeout errors are caught and converted to `MirrorTestResult` with success=False
- Async speed testing uses semaphore with max 5 concurrent requests - check for deadlock
- Configuration backup files created as `uv.toml.bak` in same directory as main config
- Mock `platformdirs.PlatformDirs.user_config_path` in tests using `temp_uv_home` fixture
- Unit tests have network calls disabled via `pytest-socket` - look for "Network calls disabled" errors
- Speed test failures return specific error messages: "Timeout", "HTTP {status}", "Network error: {e}"
- Mirror URL validation happens at Pydantic model level - check for "镜像源URL必须以/simple结尾" errors
- CLI exit codes: 0=success, 1=error, 2=invalid args, 3=network error, 4=config error
- Rich console output may mask underlying errors - check raw exception messages
- Async test failures may not show full stack trace - use `pytest -v -s` for detailed output
- Configuration file parsing uses `tomlkit` - preserves comments but may have different error handling than standard toml
- Cache loading filters by timestamp - check for stale cache entries if speed tests seem inconsistent
- Mirror comparison is case-insensitive - check for unexpected matches when debugging duplicate name issues