precommit-setup

Pre-commit 设置技能

配置一个三层 pre-commit 质量系统，在每次 提交前执行 lint、类型检查和测试。

适用场景

• 为新项目设置代码质量检查
• 为现有项目添加 pre-commit 钩子
• 从基础 lint 升级到完整的质量系统
• 为 monorepo 或插件架构设置按组件执行的质量检查
• 更新 pre-commit 钩子版本

不适用场景

• pre-commit 钩子已配置且运行良好
• 项目不使用 git 版本控制
• 团队因工作流原因明确不使用 pre-commit 钩子

理念：三层防护

该系统分为三层，每层在成本与覆盖范围之间进行不同的权衡：

• 第 1 层：标准钩子：快速的全局检查 （总计 50-200 毫秒）。对每个暂存文件执行 lint 和类型检查。
• 第 2 层：组件专属检查：按组件执行 lint、类型检查和测试（总计 10-30 秒）。只运行受暂存文件影响的组件。
• 第 3 层：验证钩子：针对项目的 结构和模式检查（耗时不定）。捕获通用 lint 工具无法发现的违规情况。

这种分层既能保持快速反馈循环，又能在问题提交前发现耗时较长的检查以及针对项目的错误。

模块加载

详细的配置模式位于各模块中；只加载所需模块：

• modules/standard-hooks.md：适用于 Python、Rust 和 TypeScript 的第 1 层模式（配置基础 lint 工具时加载）。
• modules/component-level-hooks.md：第 2 层 monorepo 脚本和 pre-commit 配置（项目包含多个组件或插件时加载）。
• modules/validation-hooks.md：第 3 层自定义钩子 和 SKIP 模式（需要强制执行 lint 之外的项目约定时加载）。
• modules/ci-integration.md：GitHub Actions 工作流 以及完整的 .pre-commit-config.yaml 示例（需要让 CI 执行与本地检查一致的操作时加载）。
• modules/troubleshooting.md：耗时表、缓存 清理和钩子失败后的恢复方法（钩子运行缓慢或失败时加载）。

工作流

1. 创建配置文件

```bash

Create .pre-commit-config.yaml

python3 plugins/attune/scripts/attune_init.py \ --lang python \ --name my-project \ --path .

Create quality check scripts (for monorepos)

mkdir -p scripts chmod +x scripts/run-component-*.sh ```

2. 配置 Python 类型检查

创建 pyproject.toml 并启用严格类型检查：

```toml [tool.mypy] python_version = "3.12" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true strict = true

Per-component configuration

[[tool.mypy.overrides]] module = "plugins.*" strict = true ```

3. 配置测试

```toml [tool.pytest.ini_options] testpaths = ["tests"] pythonpath = ["src"] addopts = [ "-v", # Verbose output "--strict-markers", # Strict marker enforcement "--cov=src", # Coverage for src/ "--cov-report=term", # Terminal coverage report ]

markers = [ "slow: marks tests as slow (deselect with '-m \"not slow\"')", "integration: marks tests as integration tests", ] ```

4. 安装并测试钩子

```bash

Install pre-commit tool

uv sync --extra dev

Install git hooks

uv run pre-commit install

Test on all files (first time)

uv run pre-commit run --all-files

Normal usage - test on staged files

git add . git commit -m "feat: add feature"

Hooks run automatically

```

5. 创建手动质量检查脚本

用于完整的质量检查（CI/CD、每月审计）：

```bash #!/bin/bash

scripts/check-all-quality.sh: full quality check for all components

set -e

echo "=== Running Full Quality Checks ==="

./scripts/run-component-lint.sh --all ./scripts/run-component-typecheck.sh --all ./scripts/run-component-tests.sh --all

echo "=== All Quality Checks Passed ===" ```

Hook 执行顺序

Pre-commit hook 按以下固定顺序运行；全部通过后，提交才能成功：

1. 文件验证（空白字符、文件末尾、YAML/TOML/JSON 语法）
2. 安全扫描（bandit）
3. 全局 lint（ruff，所有文件）
4. 全局类型检查（mypy，所有文件）
5. 组件 lint（仅检查已更改的组件）
6. 组件类型检查（仅检查已更改的组件）
7. 组件测试（仅测试已更改的组件）
8. 自定义验证（结构、模式等）

最佳实践

对于新项目

从一开始就采用严格设置：长期维护起来更轻松。在 pyproject.toml 中使用 strict = true 配置类型检查，尽早设置测试（在 pre-commit 中加入 pytest），如果必须跳过某个 hook，请记录原因。

对于现有项目

采用渐进式引入策略。先启用全局检查（第 1 层），然后在解决遗留问题后，再添加组件专属检查（第 2 层）。只有真正的紧急情况才使用 --no-verify，并记录原因。

对于单体仓库和插件架构

统一各组件的 Makefile，为 lint、typecheck 和 test 目标制定标准。将通用设置集中放在根目录的 pyproject.toml 中，同时允许各组件覆盖设置。自动检测变更，以加快提交速度，并采用渐进式展示（先显示摘要，失败时再显示详情）。

相关技能

• Skill(attune:project-init)：完整的项目初始化
• Skill(attune:workflow-setup)：GitHub Actions 设置
• Skill(attune:makefile-generation)：生成组件 Makefile
• Skill(pensive:shell-review)：审查 shell 脚本中的退出代码和安全问题

另请参阅

• 质量门禁：三层验证：pre-commit hook（格式化、lint）、CI 检查（测试、覆盖率）以及 PR 审查门禁（代码质量、安全性）。

退出标准

• 项目根目录存在 .pre-commit-config.yaml，其中的 hook 至少涵盖第 1 层（空白字符、YAML/TOML/JSON 语法、全局 lint）。
• 安装配置后，uv run pre-commit run --all-files 以 0 退出，确认所有 hook 均通过当前代码库的检查。
• 对暂存更改执行 git commit 时会自动触发 pre-commit hook（通过 uv run pre-commit install 的退出代码为 0 且 .git/hooks/pre-commit 存在来验证）。
• 项目文档化的工作流中不得使用任何 --no-verify 绕过方式；如果在现有脚本中发现该参数，应将其标记为违规，而不是默认接受。