code-quality

代码质量技能

激活时机

在以下情况下激活此技能：

• 格式化 Python 代码
• 运行代码检查工具
• 添加类型注解
• 修复代码风格问题
• 配置质量工具

快速命令

# Format with Black
uv run black .
uv run black --check .  # Dry run

# Lint with Ruff
uv run ruff check .
uv run ruff check --fix .  # Auto-fix

# Type check with mypy
uv run mypy .

# All checks
uv run black . && uv run ruff check . && uv run mypy .

工具概览

工具	用途	速度	自动修复
Black	代码格式化	快	是
Ruff	代码检查和导入管理	非常快	大多数规则
mypy	类型检查	中等	否

安装

uv add --dev black ruff mypy

Black - 代码格式化

无需配置即可实现风格一致的格式化。

uv run black .                # Format all
uv run black --check .        # Dry run
uv run black --diff .         # Show changes

配置

[tool.black]
line-length = 88
target-version = ['py311']

Ruff - 快速代码检查

基于 Rust 的代码检查工具，可替代 flake8、isort、pylint 和 50 多种工具。

uv run ruff check .               # Check
uv run ruff check --fix .         # Auto-fix
uv run ruff check --show-source . # Show context

配置

[tool.ruff]
line-length = 88
target-version = "py311"
select = ["E", "W", "F", "I", "B", "SIM"]
ignore = ["E501"]  # Black handles line length

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]
"tests/*" = ["S101"]

常见问题

• F401：未使用的导入（可自动修复）
• F841：未使用的变量
• I001：导入排序问题（可自动修复）
• B008：可变默认参数

mypy - 类型检查

用于 Python 的静态类型检查器。

def greet(name: str) -> str:
    return f"Hello, {name}"

greet(123)  # mypy error: incompatible type "int"

配置

[tool.mypy]
python_version = "3.11"
warn_return_any = true
disallow_untyped_defs = false  # Enable gradually
check_untyped_defs = true

常见类型提示

from typing import Optional, List, Dict

def find_user(user_id: int) -> Optional[Dict[str, str]]:
    return database.get(user_id)

def process_items(items: List[str]) -> int:
    return len(items)

统一配置

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py311']

[tool.ruff]
line-length = 88
target-version = "py311"
select = ["E", "W", "F", "I", "B", "SIM"]

[tool.mypy]
python_version = "3.11"
warn_return_any = true

跳过规则

import os  # noqa: F401       # Ignore Ruff rule

# fmt: off                     # Disable Black
matrix = [[1, 2, 3], [4, 5, 6]]
# fmt: on

工作流最佳实践

开发阶段（提交前）

uv run black . && uv run ruff check --fix . && uv run mypy .

CI/CD（严格模式，不自动修复）

uv run black --check . && uv run ruff check . && uv run mypy --strict .

渐进式采用

1. 从 Black 开始 - 无需配置，立即见效
2. 添加 Ruff - 先启用基本规则，再逐步扩展
3. 引入 mypy - 初期使用宽松设置，再逐步提高严格程度

代码风格原则

清晰胜过巧妙

# ❌ Clever but unclear
result = [x for x in range(10) if x % 2 == 0 if x > 5]

# ✅ Clear and readable
even_numbers = [x for x in range(10) if x % 2 == 0]
result = [x for x in even_numbers if x > 5]

使用有意义的名称

# ❌ Unclear
def proc(d, x):
    return d[x] if x in d else None

# ✅ Clear
def get_user_by_id(users_dict, user_id):
    return users_dict.get(user_id)

尽早返回

# ❌ Nested
def process(amount, user):
    if amount > 0:
        if user.has_payment():
            return charge(user, amount)

# ✅ Early returns
def process(amount, user):
    if amount <= 0:
        return "Invalid amount"
    if not user.has_payment():
        return "No payment method"
    return charge(user, amount)

相关资源

有关以下内容，请参阅 AgentUsage/code_quality.md 和 AgentUsage/code_style_guide.md：

• IDE 集成
• Pre-commit 钩子设置
• 全面的风格指南
• 错误处理模式