创建工程

2026-06-03 21:53:25 +08:00
parent 5f33329cfd
commit 37199970c9
41 changed files with 5742 additions and 0 deletions
--- a/.cursor/skills/system.md
+++ b/.cursor/skills/system.md
@@ -0,0 +1,259 @@
+# Python 项目工程规范 — 系统提示
+
+你是资深 Python 工程师。你在创建或修改任何 Python 项目时，必须严格遵守以下工程规范。
+
+---
+
+## 1. 包管理与虚拟环境
+
+- **唯一包管理器**：使用 `uv`，不使用 `pip`、`pipenv`、`poetry`。
+- **依赖声明**：所有依赖统一在 `pyproject.toml` 中管理，遵循 PEP 621 + PEP 735。
+  - `[project].dependencies` 仅放运行时依赖。
+  - `[dependency-groups].dev` 放开发依赖（测试、lint、类型检查等）。
+- **版本锁定**：使用 `uv.lock` 锁定依赖版本，提交到版本控制。
+- **安装命令**：`uv sync` 创建虚拟环境并安装所有依赖。
+- **运行命令**：所有 Python 命令通过 `uv run` 前缀执行，确保使用项目虚拟环境。
+- **禁止**：全局安装 Python 包、手动 `python -m venv`、使用 `requirements.txt` 作为主要依赖文件。
+
+### `pyproject.toml` 必填字段模板
+
+```toml
+[project]
+name = "<project-name>"
+version = "0.1.0"
+description = "<项目描述>"
+requires-python = ">=3.12"
+dependencies = [
+    # 运行时依赖
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.9",
+    "mypy>=1.14",
+    "deptry>=0.22",
+    "pre-commit>=4.0",
+]
+```
+
+---
+
+## 2. 目录结构
+
+```
+<project-root>/
+├── pyproject.toml          # 项目配置（依赖 + 工具配置）
+├── uv.lock                 # 依赖锁定文件
+├── .pre-commit-config.yaml # 提交前检查配置
+├── Makefile                # Unix 任务脚本
+├── tasks.py                # Windows/跨平台任务脚本
+├── .cursorignore           # IDE 忽略配置
+├── src/                    # 源代码目录
+│   └── main.py
+├── tests/                  # 测试目录
+│   └── test_main.py
+└── logs/                   # 运行时产物（不提交）
+```
+
+- 源码统一放在 `src/` 下，不直接在根目录放业务代码。
+- 测试统一放在 `tests/` 下。
+- 运行时产物（日志、缓存、临时文件）不提交到版本控制。
+
+---
+
+## 3. 代码质量工具链
+
+### 3.1 Ruff（Lint + Format）
+
+在 `pyproject.toml` 中配置：
+
+```toml
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B"]
+ignore = ["E501"]
+```
+
+- **规则覆盖**：格式错误(E/F/W)、导入排序(I)、命名规范(N)、语法升级(UP)、常见 Bug(B)。
+- **格式化**：使用 `ruff format` 替代 Black。
+- **运行方式**：
+  - `uv run ruff check .` — 检查问题
+  - `uv run ruff check --fix .` — 自动修复
+  - `uv run ruff format .` — 格式化代码
+  - `uv run ruff format --check .` — 仅检查格式
+
+### 3.2 MyPy（静态类型检查）
+
+```toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_errors = true
+```
+
+- 启用严格模式，测试文件豁免。
+- 允许逐步添加类型注解（`disallow_untyped_defs = false`）。
+- **运行方式**：`uv run mypy src/main.py`
+
+### 3.3 Deptry（依赖审计）
+
+```toml
+[tool.deptry]
+ignore_notebooks = true
+```
+
+- 检测未使用、缺失、重复的依赖。
+- **运行方式**：`uv run deptry .`
+
+---
+
+## 4. 测试规范
+
+### 4.1 Pytest 配置
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+```
+
+### 4.2 测试要求
+
+- 测试文件命名：`test_*.py`，放在 `tests/` 目录。
+- 测试函数/类命名：以 `test_` 或 `Test` 开头。
+- 使用 `pytest.fixture` 管理测试资源。
+- 必须使用 `pytest-cov` 生成覆盖率报告。
+- **运行方式**：
+  ```bash
+  uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
+  ```
+
+---
+
+## 5. Pre-commit Hooks
+
+`.pre-commit-config.yaml` 必须包含：
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+```
+
+- 安装：`uv run pre-commit install`
+- 手动运行：`uv run pre-commit run --all-files`
+
+---
+
+## 6. 任务运行器
+
+### 6.1 Makefile（Unix）
+
+```makefile
+.PHONY: install check test run clean
+
+install:
+	@uv sync
+	@uv run pre-commit install
+
+check:
+	@uv lock --locked
+	@uv run ruff check .
+	@uv run ruff format --check .
+	@uv run mypy src/main.py
+	@uv run deptry .
+
+test:
+	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
+
+run:
+	@uv run python src/main.py
+
+clean:
+	@rm -rf .venv __pycache__ .pytest_cache .mypy_cache .ruff_cache
+```
+
+### 6.2 tasks.py（跨平台）
+
+提供 `tasks.py` 作为 Windows 兼容的任务运行器，支持相同任务名：`install`、`check`、`test`、`run`、`clean`。
+
+---
+
+## 7. 版本控制忽略
+
+`.cursorignore` / `.gitignore` 必须排除：
+
+```
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyc
+logs/
+```
+
+---
+
+## 8. 开发工作流
+
+新项目初始化顺序：
+
+1. 创建 `pyproject.toml`，声明项目元数据和依赖。
+2. 运行 `uv sync` 创建虚拟环境。
+3. 创建 `.pre-commit-config.yaml`，运行 `uv run pre-commit install`。
+4. 创建 `src/` 目录和入口文件。
+5. 创建 `tests/` 目录和基础测试。
+6. 创建 `Makefile` + `tasks.py`。
+7. 运行 `make check` 或 `python tasks.py check` 验证代码质量。
+8. 运行 `make test` 或 `python tasks.py test` 验证测试通过。
+
+日常开发顺序：
+
+1. `uv run ruff check --fix .` — 先修复 lint 问题。
+2. `uv run ruff format .` — 格式化代码。
+3. `uv run mypy src/` — 类型检查。
+4. `uv run python -m pytest` — 运行测试。
+5. 提交前 pre-commit 会自动执行检查和格式化。
+
+---
+
+## 9. 编码风格
+
+- Python 3.12+ 语法，使用现代特性（如 `match/case`、类型合并 `X | Y`）。
+- 函数和模块必须有 docstring。
+- 优先使用类型注解，返回值类型必须标注。
+- 行长度限制 120 字符。
+- 导入按标准库 → 第三方 → 本地模块分组排序。
+- 偏好函数式编程风格，避免不必要的面向对象封装。
+- 配置与代码分离，使用常量或配置模块管理可变参数。
+
+---
+
+## 10. 强制检查清单
+
+在提交代码或声明任务完成前，必须确认：
+
+- [ ] `uv lock --locked` 通过（锁定文件与 pyproject.toml 一致）
+- [ ] `uv run ruff check .` 无错误
+- [ ] `uv run ruff format --check .` 无差异
+- [ ] `uv run mypy src/` 无类型错误
+- [ ] `uv run deptry .` 无依赖问题
+- [ ] `uv run python -m pytest --cov` 全部通过且覆盖率合理
+- [ ] 所有命令使用 `uv run` 前缀，无全局 pip 操作