configure-pre-commit

/configure:pre-commit

根据项目标准检查并配置 pre-commit 钩子。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方法……
设置或验证 pre-commit 钩子	项目未使用 pre-commit 框架（直接使用 git 钩子）
检查是否符合项目标准	只是手动运行钩子（使用 pre-commit run 命令）
安装特定项目类型的钩子	钩子已正确配置
迁移到 pre-commit 框架	无需质量检查的简单项目
更新针对已检测工具的钩子配置	需要完全禁用 pre-commit

上下文

• Pre-commit 配置： !find . -maxdepth 1 -name \'.pre-commit-config.yaml\'
• 项目标准： !find . -maxdepth 1 -name \'.project-standards.yaml\'
• 标准中的项目类型： !find . -maxdepth 1 -name '.project-standards.yaml' -exec grep -m1 "^project_type:" {} +
• 是否包含 terraform： !find . -maxdepth 2 \( -name '*.tf' -o -type d -name 'terraform' \) -print -quit
• 是否包含 helm： !find . -maxdepth 2 -type d -name 'helm' -print -quit
• 是否包含 package.json： !find . -maxdepth 1 -name \'package.json\'
• 是否包含 pyproject.toml： !find . -maxdepth 1 -name \'pyproject.toml\'

参数

从 $ARGUMENTS 解析：

• --check-only：仅报告状态，不提供修复选项
• --fix：无需提示，自动应用所有修复
• --type <type>：覆盖项目类型检测（frontend、infrastructure、python）

执行

执行此 pre-commit 合规性检查：

步骤 1：检测项目类型

1. 如果 .project-standards.yaml 存在，读取其中的 project_type 字段
2. 如果未找到，则自动检测：
   • infrastructure：包含 terraform/、helm/、argocd/ 或 *.tf 文件
   • frontend：包含带有 vue/react 依赖项的 package.json
   • python：包含 pyproject.toml 或 requirements.txt
3. 如果提供了 --type 标志，则应用其覆盖设置

步骤 2：检查配置文件

1. 如果缺少 .pre-commit-config.yaml：报告 FAIL，并提出根据模板创建
2. 如果文件存在：读取并解析配置

步骤 3：根据最新发布版本验证钩子版本

重要：标记钩子版本过时时，必须先使用 WebSearch 或 WebFetch 验证最新发布版本：

1. pre-commit-hooks：GitHub 发布页
2. conventional-pre-commit：GitHub 发布页
3. biome：GitHub 发布页
4. ruff-pre-commit：GitHub 发布页
5. gitleaks：GitHub 发布页

步骤 4：分析合规性

将现有配置与 REFERENCE.md 中的项目标准进行比较：

所有项目的必需基础钩子：

• pre-commit-hooks v5.0.0+，包含：trailing-whitespace、end-of-file-fixer、check-yaml、check-json、check-merge-conflict、check-added-large-files
• conventional-pre-commit v4.3.0+，使用 commit-msg 阶段

前端特定要求：

• biome（pre-commit）v0.4.0+
• helmlint（如果存在 helm/ 目录）

基础设施特定要求：

• tflint、helmlint（gruntwork v0.1.29+）
• actionlint v1.7.7+
• helm-docs v1.14.2+
• gitleaks v8.22.1+

Python 特定要求：

• ruff-pre-commit v0.8.4+（ruff、ruff-format）
• gitleaks v8.22.1+

步骤 5：生成合规性报告

按以下格式打印报告：

Pre-commit Compliance Report
================================
Project Type: [type] ([detected|override])
Config File: .pre-commit-config.yaml ([found|missing])

Hook Status:
  [hook-name]     [version]   [PASS|WARN|FAIL] ([details])

Outdated Hooks:
  - [hook]: [current] -> [standard]

Overall: [N] issues found

步骤 6：应用修复（如有请求）

如果设置了 --fix 标志或用户确认：

1. 缺少配置文件：根据检测到的项目类型，从标准模板创建
2. 缺少钩子：使用标准版本添加必需的钩子
3. 版本过时：将 rev: 值更新为标准版本
4. 缺少钩子类型：添加 default_install_hook_types，包含 pre-commit 和 commit-msg

修改后，运行 pre-commit install --install-hooks 以安装钩子。

步骤 7：更新标准跟踪

更新或创建 .project-standards.yaml：

standards_version: "2025.1"
project_type: "[detected]"
last_configured: "[timestamp]"
components:
  pre-commit: "2025.1"

面向 Agent 的优化

上下文	命令
检查是否已安装 pre-commit	command -v pre-commit >/dev/null 2>&1 && echo "installed" || echo "missing"
验证配置语法	pre-commit validate-config .pre-commit-config.yaml 2>&1
列出已配置的钩子	grep -E '^\s+- id:' .pre-commit-config.yaml 2>/dev/null | sed 's/.*id:[[:space:]]*//'
检查钩子版本	pre-commit autoupdate --freeze 2>&1
快速合规性检查	/configure:pre-commit --check-only
自动修复配置	/configure:pre-commit --fix

标志

标志	说明
--check-only	报告状态，但不提供修复方案
--fix	无需提示，自动应用所有修复
--type <type>	覆盖项目类型检测（frontend、infrastructure、python）

错误处理

• 没有 Git 仓库：发出警告，但继续（pre-commit 仍然有用）
• 无效的 YAML：报告解析错误，并提供用模板替换的选项
• 未知的钩子仓库：跳过（不删除自定义钩子）
• 权限错误：报告错误并建议手动修复

另请参阅

• /configure:all - 运行所有合规性检查
• /configure:status - 快速查看合规性概况
• REFERENCE.md - 权威钩子列表、固定版本及按项目类型划分的配置