用途
act 是一个可移植技能(skill),用于在 PR/MR 上自动处理审查意见。其核心理念是“修复 PR,而不是隐藏审查评论”——所有在 PR 上被标记的问题(包括 SonarQube、Codacy、CodeQL、Semgrep、Trivy 等工具的报告)都视为需要修复的问题。
主要能力
- 拉取 PR 状态:HEAD SHA、检查运行状态、未解决线程、SAST 标注。
- 分析每条发现:阅读标注、线程,理解变更内容。
- 确认或拒绝:判断是否为真实问题,对误报给出书面理由后拒绝。
- 修复:修改产品代码,每个逻辑修复对应一次提交。
- 回复并解决:在对应线程中回复并指向修复提交,然后解决该线程。
- 验证干净:通过 pr-state.ts 确认 SAST_FINDINGS_PENDING=0、CI_REQUIRED_PENDING=0。
- 推送并等待 CI:使用 gh run watch 阻塞等待 CI 完成,再重新拉取。
- 循环执行:重新拉取,CI 可能暴露新发现,重复直到干净。
使用方式
通过 /act 命令触发,支持以下上下文:
- pr(默认):/act、/act 42、/act <url>,处理单个 PR 的未解决线程。
- stack:/act stack,处理堆叠分支系列中的所有 PR。
- plan:/act plan,来源为 .agents/plans/*.md。
- backlog:/act backlog,来源为 .agents/backlog/*.md。
- harvest:/act harvest,来源为 .agents/review-debt/harvests/*.jsonl。
也支持 @claude /act、@codex /act、@copilot /act 等调用方式。
启动时会:在审查上添加 👀 反应;将 PR 移至草稿状态(set-review-state.ts --draft);验证环境(gh auth status 或 GITLAB_TOKEN/glab auth status,以及 jq、git、curl、bun);解析 PR/MR 上下文;若仓库是 fork 则运行 shadow-fork-check.sh;获取 HEAD SHA;清点线程并制定线程计划。
工作顺序为强制序列:P0a(CI/合并阻塞项)、P0b(失败检查上的 SAST 错误标注)、P1(阻塞性审查)、P2(小问题、提问、风格)、P3(内联建议)、P4(解决阶段)、P5(评分,可选)。解决是 P4 步骤,不是第一步。
每个线程的循环:阅读完整线程 → 回复并添加 👀 → 实质性处理(修复/回答/应用或解释)→ 提交产品变更 → 在线程中回复并指向提交或决定 → 然后解决该线程。先解决后回复是严重违规。
解决阶段(P4)使用脚本:
npx --yes tsx@4 scripts/run.ts .agents/skills/act/scripts/review-resolve.ts --file tmp/open_ids.txt
GitHub 专用旧版:
npx --yes tsx@4 scripts/run.ts .agents/skills/act/scripts/resolve-open-threads.ts [--dry-run] OWNER REPO NUMBER
等待 CI 的示例:
RUN_ID=$(gh run list --repo <owner>/<repo> --branch <branch> \
--limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID" --repo <owner>/<repo> --exit-status --compact
适用场景
- 在 GitHub PR 或 GitLab MR 上自动处理审查意见和 SAST 发现。
- 处理堆叠分支系列中的多个 PR。
- 处理计划、待办和审查债务上下文。
- 需要迭代式修复直到 CI 和 SAST 全部干净的场景。
限制
- 不适用于已合并到 main 的工作;/act 操作的是现有 PR/MR。若需对已合并工作自动审查,可使用 fork(shadow-fork)加 fork→upstream PR、直接在 main 上运行审查工具,或临时空分支。
- 不使用 Playwright 操作 GitHub PR UI。
- 需要 bun 运行辅助脚本(runner 回退为纯 Node.js)。
- 需要 gh(GitHub)或 glab(GitLab)认证,以及 jq、git、curl、bun。
- 若 gh run watch 不可用(GitLab、无 runs:read 权限),回退到 pr-state.ts 以 30 秒间隔轮询,硬上限 10 分钟,然后交还用户。
- 退出条件要求同一 HEAD 上满足:open_threads == 0;CI_REQUIRED_PENDING == 0、SAST_FINDINGS_PENDING == 0、SAST_FINDINGS_UNKNOWN == 0 且 CI 已实际完成;自上次推送后无新机器人评论/标注;无循环保护信号(线程重新打开、同一规则出现 2 次以上、空 /act 循环)。
- 干净退出通常需要 3-5 次迭代,而非 1 次。
- 上下文不足时需规划交接。
- 范围外:.agents/skills/、resolve-open-threads.ts(除非脚本确实无法运行)。
- 提交前对触及的 tools/**/*.ts 运行 bunx nx format:write。
- 不要用 sleep 循环轮询。
- 不要发明自定义基础分支(review/<name>)。
其他说明
可移植技能布局(agentskills.io):scripts/(辅助脚本)、references/(详细流程)。复制 .agents/skills/act/ 即可迁移。
相关参考文档:references/sast-source-priority.md、references/loop-convergence.md、references/debt-context.md、references/wrong-vs-right.md、references/footguns.md、references/script-index.md、references/script-gotchas.md、references/runner-fallback.md、references/RATING_FLOW.md、references/stack-mode.md、references/shadow-fork/SKILL.md。
运行时附加:Copilot SWE 使用 .github/copilot-instructions.md;Codex / Claude 使用 AGENTS.md § Cloud agents on GitHub。
P5 评分(可选):对每条发现评分 0-5,仅在 --record / ACT_RECORD_SCORES=1 / 配置启用时记录。
合并就绪条件:审查反馈已在代码中完成(或明确拒绝并说明理由);当前 HEAD 上 CI 必需检查成功(CI_REQUIRED_PENDING=0),通过 gh run watch 返回验证;SAST 干净(SAST_FINDINGS_PENDING=0 且 SAST_FINDINGS_UNKNOWN=0);open_threads=0;摘要按主题/文件列出变更;P5 完成(若启用);移出草稿(set-review-state.ts --ready)。
PR 关闭摘要包含:状态、HEAD SHA、审查修复(按主题/文件)、已解决线程、HEAD 上的 CI、SAST 干净、P5(若启用)。
堆叠模式:/act stack 或 PR 属于堆叠分支系列时,自底向上处理,两个效率杠杆——PR 之间不等待 CI(推送后继续,在轮询重扫时检查 CI),以及预先分析所有 PR 以批量处理相似修复。收敛为 2-3 轮轮询,而非 N 次串行迭代。
幂等性:若反馈已在 HEAD 上修复且线程已关闭,简短回复“已完成”,不重新运行仅解决操作。