Python uv 项目开发

适用于现代 Python 项目开发说明，适用于基于 Claude Sonnet 模型等 AI 指令生成助手。

英文

# Project Instructions: Python Development with `uv`

## 1. Project Intent
This project aims to develop a robust Python application designed for high efficiency and modern dependency management. The architecture leverages **`uv`** (a high-performance Python package and project manager) as the core tool for environment handling, dependency resolution, and script execution. The primary technical challenge involves strictly adhering to the `uv` ecosystem workflow, avoiding traditional `pip`/`venv`/`python` direct usage patterns to ensure reproducible, fast, and isolated environments.

## 2. Constraints
To ensure consistency and compatibility, all development and coding tasks must follow these rules:

- **Root Execution Rule:** All terminal commands, script executions, and tool invocations must be performed exclusively from the **project root directory**. Do not navigate into subdirectories to run scripts.
- **Dependency & Runtime Management (`uv`):**
    - **Do not** use the `python` or `pip` commands directly.
    - Use `uv run <script.py>` to execute Python scripts.
    - Use `uv add <package>` to install dependencies.
    - Use `uv sync` to update the environment based on lockfiles.
    - Use `uv venv` if explicit virtual environment creation is strictly necessary, though `uv run` handles ephemeral environments automatically.
- **File Structure:** Adhere to a standard Python layout (e.g., `src/`, `tests/`, `pyproject.toml`) compatible with modern PEP standards.
- **Configuration:** All project metadata and dependencies must be defined in `pyproject.toml`.
- **Typing:** Enforce strict type hinting using standard Python `typing` or modern syntax (Python 3.10+).

## 3. Summary & Attention Points
- **Strict `uv` Adherence:** The developer or AI agent must treat `uv` as the operating system for this Python project. If a command typically starts with `python -m`, convert it to the equivalent `uv run` syntax.
- **Reproducibility:** Rely heavily on `uv.lock` (generated automatically) to guarantee that the execution environment is identical across different machines.
- **User Requirement:** The user explicitly requested **no Markdown file output** for the instructions themselves; therefore, this response is presented directly in the chat interface for immediate adoption.

中文

# 项目指令：基于 `uv` 的 Python 开发指南

## 1. 项目意图 (Project Intent)
本项目旨在开发一个高效且现代化的 Python 应用程序。核心架构利用 **`uv`**（高性能 Python 包和项目管理器）作为环境处理、依赖解析和脚本执行的主要工具。主要的技术挑战在于严格遵守 `uv` 生态系统的工作流，坚决摒弃传统的 `pip`/`venv`/`python` 直接调用模式，以确保开发环境具备高度的可复现性、执行速度和隔离性。

## 2. 约束条件 (Constraints)
为了确保开发的一致性和兼容性，所有编码任务必须严格遵循以下规则：

- **根目录执行原则：** 所有终端命令、脚本执行和工具调用必须完全在 **项目根目录** 下进行。严禁进入子目录运行脚本。
- **依赖与运行时管理 (`uv`)：**
    - **禁止** 直接使用 `python` 或 `pip` 命令。
    - 使用 `uv run <script.py>` 来执行 Python 脚本。
    - 使用 `uv add <package>` 来安装新依赖。
    - 使用 `uv sync` 来根据锁定文件同步和更新环境。
    - 仅在严格需要显式创建虚拟环境时使用 `uv venv`，但在大多数情况下应依赖 `uv run` 的自动环境管理。
- **文件结构：** 必须遵守与现代 PEP 标准兼容的标准 Python 项目布局（例如包含 `src/`, `tests/`, `pyproject.toml`）。
- **配置管理：** 所有项目元数据和依赖项必须统一在 `pyproject.toml` 文件中定义。
- **类型标注：** 强制使用标准 Python `typing` 模块或现代语法（Python 3.10+）进行严格的类型提示。

## 3. 总结与注意点 (Summary & Attention Points)
- **严格遵守 `uv` 规范：** 开发人员或 AI 智能体必须将 `uv` 视为本项目的唯一运行时入口。遇到通常使用 `python -m` 的场景，必须转换为等效的 `uv run` 语法。
- **环境可复现性：** 严格依赖自动生成的 `uv.lock` 文件，确保执行环境在不同机器上完全一致。
- **用户特定要求：** 用户明确要求 **不要将说明输出为 Markdown 文件**，因此本指令直接在当前对话界面中呈现，供立即采纳和执行。