Orchestrates multi-linter chec…

# 在 GitHub Actions 中接入 Lint Orchestrator（flake8 + black）

一、准备工作

• 确认仓库根目录或子目录共 45 个 Python 文件，无需单独列举，工具会自动扫描（可用 find . -name "*.py" | wc -l 核实）。
• 在仓库中添加两个配置文件（可选但推荐）：
• .flake8：设置 max-line-length（与 black 保持一致，通常设为与 black 兼容的值）以及 extend-ignore 忽略与 black 冲突的规则（如 E203、W503）。
• pyproject.toml 中写 [tool.black] 配置（如 line-length），确保两者风格统一。
• 在 requirements-dev.txt 或直接在 workflow 中固定版本安装 flake8 和 black。

二、编写 Workflow 文件

创建 .github/workflows/lint.yml，核心结构：

• 触发条件：on: pull_request（可限定 branches: [main]）。
• 运行环境：runs-on: ubuntu-latest。
• 步骤：

1. actions/checkout 检出代码；

2. actions/setup-python 指定 Python 版本（与项目实际版本一致）；

3. pip install flake8 black；

4. 执行 flake8 .；

5. 执行 black . --check --diff。

三、拦截合并的关键点

• 失败即拦截：任何一步以非零码退出，整个 job 标记为失败，PR 无法合并。
• 分支保护规则（必须配置，否则只是“红灯”不拦截）：
• 进入仓库 Settings → Branches → Add rule；
• 勾选 Require status checks to pass before merging；
• 将 lint job 的名称（如 lint）加入必过检查项。

四、orchestrator 层面的整合

如果你有一个统一的 lint orchestrator 脚本/入口（如 make lint 或 scripts/lint.sh）：

• 在 workflow 中只调用这一个入口：make lint 或 bash scripts/lint.sh；
• 脚本内部顺序执行 flake8 和 black，任一失败则 exit 1；
• 好处：本地与 CI 跑完全同一套检查，避免“本地过、CI 挂”。

五、实践建议

• 先自动修复再拦截：可在 PR 描述中提示开发者本地先跑 black .，或单独加一个自动格式化提交的 workflow。
• 加缓存：用 actions/setup-python 的 pip 缓存功能，加速依赖安装。
• 限定检查范围：如需只检查变更文件，可配合 paths-filter 或 orchestrator 支持 diff 模式，缩短 CI 时长。

按以上配置，任何 flake8 报错或 black 格式不一致的 PR 都会无法合并。