Auto-Finance/.agents/docs/guides/工程实践指南.md

last_reviewed

last_reviewed
2026-06-09

工程实践指南

创建或修改任何 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 必填字段模板

[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 中配置：

[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（静态类型检查）

[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_configs = true
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "tests.*"
ignore_errors = true

• 启用严格模式，测试文件豁免。
• 运行方式：uv run python -m mypy src（整个 src 都在 strict 下；uv run mypy 偶尔报 trampoline 错，用 python -m 形式）

3.3 Deptry（依赖审计）

[tool.deptry]
ignore_notebooks = true

• 检测未使用、缺失、重复的依赖。
• 运行方式：uv run deptry .

---

4. 测试规范

4.1 Pytest 配置

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["."]

4.2 测试要求

• 测试文件命名：test_*.py，放在 tests/ 目录。
• 测试函数/类命名：以 test_ 或 Test 开头。
• 使用 pytest.fixture 管理测试资源。
• 必须使用 pytest-cov 生成覆盖率报告。
• 运行方式：

  uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
  

---

5. Pre-commit Hooks

.pre-commit-config.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）

.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 python -m mypy src
	@uv run deptry .

test:
	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing

run:
	@uv run python -m src.mcp.server   # 唯一入口是 MCP stdio，没有 CLI 产品入口

clean:
	@rm -rf .venv __pycache__ .pytest_cache .mypy_cache .ruff_cache

6.2 tasks.py（跨平台）

提供 tasks.py 作为 Windows 兼容的任务运行器，任务名与 Makefile 一致：install、check、test、 mcp、mcp-smoke、mcp-docs、docs-check、upload、skill-install、skill-check、clean。 任务必须透传退出码（本项目就栽过：os.system 的返回值被丢掉，门禁失败调用方仍看到 0）。

---

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 全部通过且覆盖率合理
• 改了 MCP 工具：make mcp-smoke 再 make mcp-docs，并确认 make docs-check 为 0
• 不承诺未完成的能力：INSTRUCTIONS 只列已注册工具；提交类动作永远不进工具层
• 所有命令使用 uv run 前缀，无全局 pip 操作