CONTRIBUTING.md

# 贡献指南

欢迎参与本项目的开发！为确保代码风格统一并提升协作效率，本项目使用 [pre-commit](https://pre-commit.com/) 框架在每次提交前自动执行代码格式化与检查。

## 环境准备

### 1. 安装 pre-commit

确保系统已安装 Python 3.9+ 和 pip3，然后安装 `pre-commit`：

```bash
pip3 install pre-commit==4.5.1
```

或者使用 `uv` 安装：

```bash
uv tool install pre-commit==4.5.1 --python python3.11
```

### 2. 激活 Git Hooks

在项目根目录执行以下命令，将 pre-commit 钩子安装到本地 `.git/hooks` 中：

```bash
pre-commit install
```

## 工作流程

完成上述步骤后，每次执行 `git commit` 时，pre-commit 会自动运行以下检查：

| Hook | 说明 |
|------|------|
| `check-merge-conflict` | 检测未解决的合并冲突 |
| `trailing-whitespace` | 移除行尾空格 |
| `end-of-file-fixer` | 确保文件以换行符结尾 |
| `check-added-large-files` | 阻止提交大于 10MB 的文件 |
| `check-yaml` / `check-json` / `check-toml` | 校验配置文件语法 |
| `check-symlinks` | 检查无效符号链接 |


### 提交代码

```bash
git add .
git commit -m "feat: your message"
```

如果检查失败：
- **自动修复的问题**：重新 `git add` 修改后的文件，再次提交
- **需手动修复的问题**：根据终端提示修复后再提交

### （可选）手动运行检查

```bash
# 检查所有文件
pre-commit run --all-files

# 检查指定文件
pre-commit run --files path/to/file.py
```

## 常见问题

**Q: 如何跳过 pre-commit 检查？**

紧急情况下可使用 `--no-verify`，但不推荐：

```bash
git commit --no-verify -m "your message"
```