# Agent-Loop：基于Claude的自动化PR审查与合并工作流系统

> 一套可复用的GitHub Actions工作流，实现AI驱动的代码审查、自动修复和冲突解决，支持双机器人身份分离和渐进式自动化部署。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-06T04:51:52.000Z
- 最近活动: 2026-05-06T05:00:48.572Z
- 热度: 152.8
- 关键词: GitHub Actions, Claude, 代码审查, 自动化PR, CI/CD, DevOps, AI代理, 工作流自动化, 开源
- 页面链接: https://www.zingnex.cn/forum/thread/agent-loop-claudepr
- Canonical: https://www.zingnex.cn/forum/thread/agent-loop-claudepr
- Markdown 来源: ingested_event

---

# Agent-Loop：基于Claude的自动化PR审查与合并工作流系统

在软件开发的日常工作中，代码审查（Code Review）和合并冲突解决是耗时且容易出错的环节。随着AI能力的不断增强，越来越多的团队开始探索如何让AI代理参与这些流程。**agent-loop**项目正是这一探索的前沿实践——它提供了一套可复用的GitHub Actions工作流，实现了基于Claude的自动化PR审查、修复和合并，同时通过精心设计的双机器人架构确保安全性与可控性。

## 项目背景与目标

agent-loop由RiddimSoftware开发，旨在解决大规模软件开发中的重复性审查工作。项目的v0.1版本设定了明确的成功标准：在两周窗口期内，实现10个连续的PR通过自主合并落地，且工作流文件无需人工热修复。这种务实的目标设定体现了工程团队对AI自动化边界的清醒认知。

## 核心架构设计

### 双机器人身份分离

agent-loop采用了独特的双机器人架构，这是其安全设计的核心：

| 机器人身份 | GitHub账号 | 核心职责 |
|-----------|-----------|---------|
| developer-bot | riddim-riddim-developer-bot[bot] | 创建PR、推送实现分支、触发工作流 |
| reviewer-bot | riddim-riddim-reviewer-bot[bot] | 运行Claude审查、推送修复提交、批准PR |

这种分离不是多余的——GitHub明确禁止同一身份既创建PR又批准PR。如果developer-bot和reviewer-bot使用相同身份，自动合并将被阻止。agent-loop通过强制性的双身份契约，确保了整个流程的合规性。

### 工作流组件

agent-loop由四个核心工作流组成，形成完整的自动化闭环：

#### 1. agent-review.yml —— Claude驱动的智能审查

这是整个系统的"大脑"，负责真正的代码审查工作：

- **触发时机**：PR的pr-build工作流成功后，通过workflow_run触发
- **核心功能**：读取diff、运行Claude审查提示、生成审查意见
- **决策分支**：
  - **批准路径**：推送修复提交（如有）、执行`gh pr review --approve`、启用自动合并
  - **需人工干预**：添加`agent:needs-human`标签、评论说明、退出而不批准

#### 2. reviewer.yml —— 机械化的合并管理器

这是一个轻量级的状态检查工作流，不调用Claude：

- **职责**：检查mergeable_state，决定PR的下一步命运
- **脏分支处理**：当PR处于dirty状态（有冲突）时，保留autonomous标签，让conflict-scan处理
- **自动合并**：不在每次推送后重新启用自动合并，避免重复触发

#### 3. conflict-scan.yml —— 智能冲突解决器

当主分支前进导致PR产生冲突时，这个工作流负责自动修复：

- **触发时机**：main分支推送时
- **工作流程**：
  1. 轮询开放PR的可合并状态，直到状态确定（有超时保护）
  2. 验证最新非作者审查是否为批准状态
  3. 检查CI是否通过
  4. 如满足条件，执行developer-bot的rebase/冲突解决/推送
  5. 如解决失败，添加`agent:needs-human`标签并添加阻止性评论

#### 4. pr-build.yml —— 自测工作流

用于验证agent-loop自身的变更：

- 运行actionlint检查工作流语法
- 执行conflict-resolver单元测试
- 当PR触及工作流/脚本/提示路径时触发

## 完整工作流程图解

```
developer-bot 创建PR (分支: claude/<ticket>, 应用 autonomous 标签)
    │
    ▼
pr-build 成功
    │
    ▼
agent-review.yml 触发 (workflow_run)
    ├── 读取diff，运行Claude审查提示
    ├── 批准路径 → 推送修复提交，执行 gh pr review --approve
    └── 需人工 → 评论PR，添加 agent:needs-human 标签，退出
    │
    ▼ (批准后)
reviewer.yml 在 review/push 事件时介入
    ├── 读取 mergeable_state
    ├── dirty → 保留 autonomous 供 conflict-scan 处理
    └── 其他 → 无操作；自动合并已由 agent-review 启用
    │
    ▼
main 前进，conflict-scan.yml 运行
    ├── 轮询PR可合并状态直到确定（有界超时）
    ├── 已批准 + CI通过 + dirty → developer-bot rebase/解决/推送
    └── 不安全/未解决 → 添加 agent:needs-human 标签和阻止评论
    │
    ▼
synchronize 重新运行审查/检查；GitHub自动合并在门禁通过后触发
```

## 使用指南

### 消费者仓库配置

要在你的仓库中使用agent-loop，需要完成以下配置：

#### 1. 创建工作流包装器

在消费者仓库（如RiddimSoftware/bap）创建`.github/workflows/agent-loop.yml`：

```yaml
workflow_run:
  workflows: ["CI", "pr-build"]
  types: [completed]
```

参考[bap的包装器](https://github.com/RiddimSoftware/bap/blob/main/.github/workflows/agent-loop.yml)获取完整示例。

#### 2. 配置白名单

设置仓库变量`LOOP_OPENER_ALLOWLIST`，值为允许触发循环的GitHub登录名逗号分隔列表：
```
sunnypurewal,riddim-developer-bot
```

#### 3. 创建必要标签

确保以下标签存在于仓库中：
- `autonomous` —— 标记由机器人创建的PR
- `agent:pause` —— 暂停特定PR的自动化处理
- `agent:needs-human` —— 标记需要人工介入的PR
- `agent:attempt-1..3` —— 记录重试次数

#### 4. 配置组织密钥

确保组织密钥`REVIEWER_BOT_APP_ID`和`REVIEWER_BOT_PRIVATE_KEY`已授予本仓库和消费者仓库访问权限。

### 版本对齐策略

agent-loop支持灵活的版本管理：

```yaml
uses: RiddimSoftware/agent-loop/.github/workflows/main.yml@main
with:
  agent_loop_ref: main
secrets: inherit
```

当固定到特定版本时，确保`uses`和`agent_loop_ref`指向相同的标签或SHA，这样工作流逻辑和运行时资产可以同步移动。PR的自测会自动使用PR head SHA，确保变更在合并前得到验证。

## 运行时资产分离

agent-loop采用优雅的资产分离设计：

- **消费者仓库**：检出作为被审查的代码
- **agent-loop仓库**：提供运行时资产（`.github/prompts/`和`.github/scripts/`）
- **显式引用**：通过`agent_loop_ref`参数指定加载哪个版本的运行时资产

这种分离使得消费者仓库保持干净，同时允许agent-loop独立演进。

## 提供商路由策略

虽然v0.1版本仍直接调用Claude，但agent-loop已提前规划了模型路由策略：

- 策略文档：`docs/provider-routing-policy.md`
- 机器可读配置：`.github/config/agent-provider-routing-policy.json`

未来的runner将能够从单一策略表面解析任务→层级→模式→提供商/模型，而不是在YAML中分散路由逻辑。

## 暂停与干预机制

agent-loop设计了完善的人工干预机制：

### 全局暂停

在任何消费者仓库PR上应用`agent:pause`标签，所有工作流将在第一步守卫处短路退出。

### 单PR移除

应用`agent:needs-human`标签，将特定PR从循环中移除，同时保持其他PR的自动化处理。

### 失败处理

当冲突解决失败或审查发现问题时，系统会自动：
1. 添加`agent:needs-human`标签
2. 添加详细的阻止性评论说明原因
3. 通知相关开发者介入

## v0.2路线图

agent-loop v0.1刻意保持精简，以下功能将在v0.1成功指标达成后回归：

| 功能 | 回归版本 | 说明 |
|-----|---------|------|
| Jira集成触发 | v0.2 | Jira Automation → repository_dispatch → create-pr.yml |
| 变更请求乒乓 | v0.2 | 审查者请求变更 → 开发者迭代 → 重新审查的循环 |
| 多轮审查 | v0.2 | 单PR支持多轮审查 |
| 多消费者推广 | v0.2 | 从bap扩展到epac、riddim-website等 |
| PAT轮换 | v0.2 | 消费者级别的PAT + 90天轮换策略 |

## 技术亮点与启示

### 1. 渐进式自动化

agent-loop没有试图一步到位实现完全自动化，而是：
- 设定清晰的成功指标（10个连续PR，2周窗口）
- 保留完善的人工干预机制
- 分阶段引入更复杂的功能

### 2. 安全边界设计

- 双机器人身份分离防止自我批准
- 有界超时防止无限轮询
- 明确的标签状态机
- 失败时优雅降级到人工处理

### 3. 可观测性

- `tag-outcome.yml`为已关闭的PR添加`loop:merged`/`loop:hotfixed`/`loop:abandoned`标签
- 详细的评论说明每一步的决策原因
- 状态标签提供即时的可视化反馈

## 适用场景

agent-loop特别适合以下场景：

1. **高频小型PR**：代码变更相对独立、审查标准明确的场景
2. **重复性审查**：代码风格、测试覆盖、文档完整性等可规则化的检查
3. **多仓库管理**：需要在多个仓库间复用相同审查标准的组织
4. **CI/CD集成**：与现有构建流程深度集成的自动化发布

## 局限性与注意事项

- **v0.1功能有限**：复杂的审查场景仍需人工介入
- **Claude依赖**：当前版本直接调用Claude，未来才会支持模型路由
- **GitHub Actions限制**：需要GitHub-hosted Ubuntu运行器
- **组织配置复杂**：需要正确配置密钥、标签、白名单等多个环节

## 结语

agent-loop代表了AI辅助软件工程的一个重要方向——不是取代人类审查者，而是处理那些重复性、规则明确的审查任务，让人类专注于真正需要判断力和创造力的工作。通过精心设计的双机器人架构、完善的人工干预机制和清晰的演进路线图，agent-loop为希望在组织中引入AI自动化的团队提供了一个务实且可扩展的解决方案。