用途:在本地复现 GitHub Actions 会运行的检查,适用于 Actions 不可用或配额耗尽时。工作流 YAML 即规范,按文件内容执行,不猜测 lint、test 等步骤的含义。
范围:仅支持 GitHub Actions(.github/workflows/*.yml)。若仓库使用 GitLab CI、CircleCI 或 Jenkins,应说明并停止,目前没有对应转换层。
主要能力与用法:
- 定位合并门禁作业。可用 [workflow-file] 和/或 --job name 限定;否则 Glob 查找 .github/workflows/*.yml 与 .yaml。无文件则提示无工作流可镜像并停止。仅关注在 pull_request 或受保护分支 push 上触发的作业,忽略仅 schedule、workflow_dispatch 或 release 触发的作业(除非用户明确要求)。多文件或多作业时可用 Explore 子代理并行读取,返回作业名、触发条件、runs-on、步骤(uses/run/env/working-directory)、services、strategy.matrix 及 secrets 引用等结构化摘要。
- 将步骤翻译为本地命令。按顺序逐条翻译,不发明通用的 lint && test && build。actions/checkout 视为空操作;setup-node 用 fnm use X 或 nvm use X;setup-python 用 uv python pin X 或 uv run --python X;带 working-directory 或 env 的 run 步骤在对应目录与环境下执行;cache 步骤为空操作;本地不可能成立的条件步骤跳过并说明。工作流未固定版本时,先查 .nvmrc、package.json#engines.node、.python-version 或 pyproject.toml#requires-python,再回退到 PATH。
- 无法复现的项要标记而非伪造:services(如 Postgres、Redis)仅在 Docker 可用且用户同意时尝试,否则标记依赖步骤为跳过;secrets 检查本地 .env 是否有同名变量,缺失则标记跳过并写明缺失名称,绝不填假值;matrix 只运行匹配本机的一条组合,其余标记未覆盖。
- 顺序执行并报告。通过 Bash 按工作流声明顺序运行,某步失败立即停止并清晰报告,不静默继续。最后输出对照表,列出每步的本地结果与备注,版本回退警告须作为注意事项或 NOT REPLICABLE 呈现,不得并入 PASS。所有结果必须来自本次实际运行的命令,不得编造 PASS、FAIL 或测试数量。结尾说明分支能否通过真实 CI 门禁,以及哪些因无法本地运行而未验证。
限制:对 git 只读,不提交、不推送、不修改工作流文件;安装依赖(如 npm ci、uv sync)属于步骤的一部分,是允许的。若同一仓库反复请求,应提示修复实际 CI 配额或故障,而非长期依赖本地替代。