init

Signed-off-by: liuzhen19 <liuzhen19@xiaomi.com>

Author: liuzhen19

.github/copilot-instructions.md

@@ -0,0 +1,75 @@
+# Copilot Instructions for Python Development
+
+This project uses a modern, high-performance Python toolchain. Please adhere to the following guidelines and tool usages when generating code or commands.
+
+## Toolchain & Workflow
+
+### Dependency & Project Management: `uv`
+- **Primary Tool**: Use `uv` for all project management tasks.
+- **Overview**: `uv` is an extremely fast Python package and project manager written in Rust. It effectively replaces `pip`, `poetry`, and `pip-tools`.
+- **Commands**:
+    - Add dependencies: `uv add <package>`
+    - Add dev dependencies: `uv add --dev <package>`
+    - Run scripts: `uv run <script.py>` or `uv run -m <module>`
+    - Sync environment: `uv sync` (creates/updates `.venv`)
+    - Lock dependencies: `uv lock`
+- **Configuration**: Managed in `pyproject.toml`.
+
+### Linting & Formatting: `ruff`
+- **Linter & Formatter**: Use `ruff` for all linting and formatting.
+- **Overview**: `ruff` is an extremely fast Python linter and code formatter written in Rust. It replaces tools like Black, Flake8, and isort.
+- **Commands**:
+    - Check: `uvx ruff check` (fix with `--fix`)
+    - Format: `uvx ruff format`
+- **Style**: Code should be compliant with `ruff`'s default rules and any overrides in `pyproject.toml` or `ruff.toml`.
+
+### Type Checking: `ty`
+- **Type Checker**: Use `ty` for static type checking.
+- **Overview**: `ty` is a fast Python type checker and language server found in the Astral ecosystem.
+- **Commands**:
+    - Check: `uvx ty check`
+- **Typing**: Ensure all code is fully typed. Use modern Python type hinting features.
+
+### Task Management: `just`
+- **Task Runner**: Uses `just` to run project-specific tasks.
+- **Overview**: `just` is a handy command runner that saves and runs project-specific commands (recipes) stored in a `Justfile`.
+- **Usage**: Check the `Justfile` (if present) for available recipes.
+- **Recommendation**: If users ask to run common tasks (build, test, lint), check if a `just` recipe exists.
+- **installation**: `just` can be installed via package managers like `brew`, `apt`, or using uv:
+    ```bash
+    uv tool install rust-just
+    ```
+
+### Git Hooks: `pre-commit`
+- **Automation**: `pre-commit` ensures code quality before committing.
+- **Overview**: Framework for managing and maintaining multi-language pre-commit hooks.
+- **Commands**:
+    - Run manually: `uvx pre-commit run --all-files`
+- **installation**:
+    ```bash
+    uv tool install pre-commit
+    pre-commit install
+    ```
+
+### Build System: `hatchling`
+- **Backend**: The project uses `hatchling` as the build backend.
+- **Overview**: `hatchling` is a modern, extensible build backend for Python projects.
+- **Configuration**: Build settings are defined in the `[build-system]` section of `pyproject.toml`.
+
+### Testing: `pytest`
+- **Framework**: Use `pytest` for testing.
+- **Overview**: The pytest framework makes it easy to write small, readable tests, and can scale to support complex functional testing.
+- **Commands**:
+    - Run tests: `uv run pytest`
+- **Practices**: Write unit tests for new functionality in the `tests/` directory.
+
+## Commit Messages
+
+- **Strict Requirement**: You **MUST** reference and follow the commit message conventions defined in `.copilot-commit-message-instructions.md` located in the project root.
+- All generated commit messages should adhere to the format and rules specified in that file.
+
+## General Development Guidelines
+
+- **Modern Python**: Use modern Python features (3.10+).
+- **Type Safety**: Prioritize type safety and clarity.
+- **Performance**: Leverage the speed of the provided Rust-based tools (`uv`, `ruff`, `ty`).

README.md

@@ -5,26 +5,42 @@ A minimal, practical project template for small Python projects and experiments.
 ## Requirements
 
 - Python 3.8+
-- pip
+- [uv](https://github.com/astral-sh/uv)
 
-## Installation
+## Usage
 
-1. Clone the repository:
-   git clone <repo-url>
-2. Install dependencies (if any):
-   pip install -r requirements.txt
+### Using this Template
 
-## Usage
+1.  **Fork or Copy**: Fork this repository or copy the files to a new directory.
+2.  **Rename Directory**: Rename the directory to your desired project name.
+3.  **Initialize Project**: Run the following command to initialize the project with `uv`, which will generate a `pyproject.toml` based on your directory name:
+    ```bash
+    uv init --lib --build-backend hatchling .
+    ```
+    *Note: If you want to specify a project name different from the directory name, you can pass the `--name` argument (if supported by your uv version) or simply rename the directory first.*
+
+### Installation
+
+1.  **Install dependencies**:
+    ```bash
+    uv sync
+    ```
+
+### Running
 
 - Run the main script or module:
-  python -m your_package
+  ```bash
+  uv run -m your_package
+  ```
 
-Replace `your_package` with the actual package or script name.
+  Replace `your_package` with the actual package or script name.
 
 ## Testing
 
-- Add tests under a `tests/` directory and run with your preferred test runner (pytest recommended):
-  pytest
+- Run tests using `pytest`:
+  ```bash
+  uv run pytest
+  ```
 
 ## Contributing