用途
该技能用于把目标仓库配置成支持本地 GitHub Actions 验证的环境，使 Jules（或任意智能体）能够借助 act 在推送代码或创建 PR 之前，先在本地运行 CI 工作流，确认改动能通过 CI。
主要能力
配置完成后，仓库将包含两个脚本和一段 AGENTS.md 说明：
- install-act.sh：在 act 缺失时安装 act，脚本感知平台，并带有 sudo 回退。
- run-act.sh：在后台运行 act，并通过轮询日志的方式避免智能体超时。
- AGENTS.md 中的说明段落：Jules 读取该段落以了解如何使用这些脚本。
使用方式
第 1 步：将脚本复制到仓库
把该技能中的 scripts/ 目录复制到目标仓库的 scripts/act/ 下，目标结构为：
scripts/act/
├── install-act.sh
└── run-act.sh
确保脚本可执行：
chmod +x scripts/act/install-act.sh scripts/act/run-act.sh
第 2 步：向 AGENTS.md 添加说明
将以下段落追加到仓库的 AGENTS.md 文件（若不存在则创建）。这是 Jules 发现本地验证能力的方式：
## Local CI Verification
Before pushing code or opening a PR, verify changes pass CI locally using `act`.
### Prerequisites
- Docker must be running
- If `act` is not installed, run: `bash scripts/act/install-act.sh`
### How to Verify
1. Read `.github/workflows/` to find the CI workflow and identify the job ID
2. Run the verification script:
```bash
bash scripts/act/run-act.sh "push -j <JOB_ID>"
With matrix: bash scripts/act/run-act.sh "push -j <JOB_ID> --matrix <KEY>:<VALUE>" 3. If the run fails, read the log output, fix the code, and re-run 4. After verification, clean up:
rm -f act_output.log git checkout <any unintended file changes>
### 配置
- 超时：`ACT_TIMEOUT=900 bash scripts/act/run-act.sh "..."`（默认：600 秒）
- 轮询间隔：`ACT_POLL=15 bash scripts/act/run-act.sh "..."`（默认：10 秒）
- 自定义镜像：在参数中传入 `-P ubuntu-latest=node:20-bookworm` 以加快拉取
### 第 3 步：更新 .gitignore
若以下条目尚不存在，将其追加到 .gitignore：
act artifacts
act_output.log .secrets
### 第 4 步：向用户打印后续步骤
告知用户：
1. 在运行验证的任何机器（或 Jules VM）上，Docker 必须已安装并正在运行。
2. act 将在首次使用时通过 `scripts/act/install-act.sh` 自动安装。
3. 若工作流需要密钥，创建 `.secrets` 文件（KEY=VALUE 格式）——切勿提交该文件。
4. 提交所有生成的文件。
## 适用场景
适用于需要在推送前本地验证 GitHub Actions CI 的仓库，尤其是由 Jules 或其他智能体自动修改代码、并希望在推送前确认 CI 通过的工作流。
## 限制与故障排查
- Docker 未运行：act 需要 Docker，请确保 Docker 守护进程已启动。
- 镜像拉取缓慢：首次运行会下载约 2GB 以上，可使用 `-P ubuntu-latest=node:20-bookworm` 加快拉取。
- ARM64 问题：在 Apple Silicon 上，向 act 参数添加 `--container-architecture linux/amd64`。
- 需要密钥：创建 `.secrets` 文件，并在 act 参数中传入 `--secret-file .secrets`。
- 超时：使用 `ACT_TIMEOUT=1200 bash scripts/act/run-act.sh "..."` 增加超时。
## 资源参考
- 故障排查指南（resources/troubleshooting.md）——常见问题的详细解决方案。