用途：在用户 Python 仓库中搭建与维护 pre-commit 框架，输出仓库根目录的 .pre-commit-config.yaml。核心价值不在写 YAML，而在避免让钩子配置静默失效的陷阱：钩子版本未固定或与 CI 不一致、ruff 自动修复后提交仍放行、mypy 在空环境运行、归档的 Prettier 镜像、以及过慢钩子让人习惯加 --no-verify。
主要能力：卫生类检查（trailing-whitespace、end-of-file-fixer、check-yaml/toml/json、check-added-large-files、check-merge-conflict、detect-private-key）；ruff-check（--fix）与 ruff-format；非 Python 文件的格式化与校验（Prettier 维护分支或 mdformat/taplo/yamllint 无 Node 方案，validate-pyproject、check-jsonschema）；conventional commits 的 commit-msg 钩子；把 mypy、pytest 等慢检查放到 pre-push 或 CI。原则是钩子只是便利、CI 才是强制，提交阶段保持数秒内，所有钩子固定 rev。
使用方式：先勘察仓库现有配置、ruff/mypy 版本、CI 工作流与是否已有 Node，写配置后运行 uv add --dev pre-commit、uv run pre-commit install（需覆盖 commit-msg、pre-push 等阶段）、uv run pre-commit run --all-files，首次运行较慢且会因修复文件而失败，需重跑到干净。CI 镜像同一配置，并用 Dependabot、pre-commit.ci 或定期 autoupdate 保持版本同步。
适用场景：需要统一本地与 CI 提交门禁的 Python 仓库。限制：git commit --no-verify 可静默绕过；钩子按克隆安装、不被 git 跟踪；首跑会下载环境；提交阶段不应放覆盖率或完整测试；不少细节（如 Prettier 与 yamllint 冲突、prek 替代、agent 频繁编辑是否让 pre-commit 失效）仍有争议，资料建议呈现选项而非断言。