GitHub PR 创建流程
智能体如何在 GitHub 上创建、更新和链接 pull request — AACWorkflow 自动化 PR 工作流。
智能体可以在执行任务时在 GitHub 上创建和更新 pull request。GitHub PR 创建流程处理：
- 使用标题、描述和分支创建新 PR
- 将 PR 链接到 AACWorkflow issue（通过 issue ID 自动检测）
- 更新 PR 描述和状态
- 处理 merge 冲突和 CI 检查
工作原理
创建 PR
当智能体完成功能工作时，它可以：
- 将包含功能代码的分支推送到 GitHub
- 使用描述性标题和正文打开 PR
- 标题或正文应包含 AACWorkflow issue ID（如
AAC-42） - AACWorkflow 检测 ID 并自动链接 PR
示例 PR 标题：
AAC-42: Add OAuth 2.1 authorization to MCP endpoint示例 PR 正文：
## Description
Implements OAuth 2.1 authorization server for MCP clients per spec.
## Changes
- Add /oauth/authorize, /oauth/token endpoints
- Implement PKCE + refresh-token rotation
- Add RFC 8414 metadata discovery
## Issue
Closes AAC-42
## Testing
- [x] Unit tests for OAuth flows
- [x] Integration test for PKCE verification自动链接
创建 PR 时：
- AACWorkflow 扫描标题和正文查找 issue 标识符（不区分大小写：
AAC-42、aac-42等） - 如果找到且 issue 存在于工作区，PR 被自动链接
- Issue 页面在 Pull requests 部分显示 PR
PR 必须在标题或正文中引用 issue ID。分支名是可选的（但最佳实践）。
更新 PR 描述
PR 创建后，智能体可以更新描述以：
- 添加测试结果或截图
- 链接依赖的 PR
- 更新状态（「准备审查」、「WIP」等）
更新通过 webhook 同步回 AACWorkflow。
PR 生命周期
| 阶段 | 事件 | AACWorkflow 行为 |
|---|---|---|
| 已创建 | PR 打开 | 若找到 ID → 自动链接; UI 在 issue sidebar 显示 PR |
| 已更新 | 标题/正文改变 | 若找到新 ID → 重新链接; 若 ID 移除 → 取消链接 |
| Draft | PR 标记为 draft | UI 在 sidebar 显示 Draft 徽章 |
| 准备 | Draft → 准备转换 | UI 更新徽章 |
| 有评论 | 审查评论发表 | 评论同步（若启用，见 PR 评论同步） |
| 已批准 | PR 被审查者批准 | 记录在审计日志 |
| 已合并 | PR 合并到 main | Issue 自动移到 已完成 状态 |
| 已关闭 | PR 关闭但未合并 | Issue 保留当前状态; PR 链接保留 |
合并时自动移动
当 PR 合并时，每个关联的 issue（若不已是已完成或已取消）自动移到工作区的已完成状态。
示例：
- PR
#123 (Closes AAC-42, AAC-43)被合并 - Issue AAC-42 → 移到已完成
- Issue AAC-43 → 移到已完成
- Issue AAC-99 → 保留当前状态（未链接）
这通过 GitHub webhook 自动发生。
分支策略
推荐的分支命名
在分支名中使用 issue ID 以清晰：
feature/aac-42-oauth-mcp
fix/aac-99-login-timeout
refactor/aac-55-query-optimizationAACWorkflow 不要求此，但它：
- 使 GitHub 历史更容易导航
- 帮助开发者记住他们正在处理的 issue
- 明显显示哪个分支关闭哪个 issue
分支保护
你 GitHub 仓库的分支保护规则适用（如「merge 前需要 PR 审查」）。AACWorkflow 尊重这些。
如果智能体代码不符合要求：
- PR 不会合并
- Issue 保留当前状态
- 智能体可重试或请求人工帮助
PR 状态指示符
在 issue 页面，Pull requests 部分显示：
| 状态徽章 | 含义 | 下一步 |
|---|---|---|
| 🟢 开放 | PR 开放等待审查 | 审查代码 |
| 📋 Draft | PR 处于 draft 模式 | 等待或请求准备 |
| ✅ 已合并 | PR 被合并 | Issue 应移到已完成 |
| ❌ 已关闭 | PR 关闭但未合并 | 调查为什么 |
点击 PR 行跳转到 GitHub。
冲突解决
Merge 冲突
如果智能体分支与 main 冲突：
- 智能体在 push 时检测冲突
- 智能体可以：
- Rebase 分支并重试
- 请求人工帮助（在 issue 上发表评论）
- 关闭 PR 并重新开始
选择取决于智能体指令和自主权级别。
CI 检查失败
若 GitHub CI 检查失败（测试、lint、安全扫描）：
- PR 显示 ❌ 检查状态
- 智能体可以：
- 修复问题并推送新提交
- 请求人工审查失败的检查
- 关闭 PR 若问题阻挡
Issue 页面显示 CI 检查状态。管理员可配置策略在检查通过前阻止合并。
API
获取 issue 的关联 PR
GET /api/issues/{issue_id}响应包括：
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Add OAuth to MCP",
"status": "in_progress",
"pull_requests": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"pr_number": 123,
"repo": "org/repo",
"title": "AAC-42: Add OAuth 2.1 authorization",
"url": "https://github.com/org/repo/pull/123",
"state": "merged",
"merged_at": "2025-06-22T16:00:00Z"
}
]
}列出工作区的 PR
GET /api/workspaces/{ws}/github/pull-requests返回此工作区中智能体创建的所有 PR，分页。
安全
智能体绝不可向 PR 提交密钥（令牌、API 密钥、凭证）。使用环境变量或密钥管理。
- 分支权限： 智能体推送到功能分支; 管理员控制谁可合并到 main
- 提交归属： 智能体提交归属于 GitHub App 的 bot 用户（在设置 → GitHub 中配置）
- PR 描述编辑： PR 正文中的密钥在存储于 AACWorkflow 前编辑
- 审计轨迹： 每个 PR 动作（创建、更新、合并）被记录
故障排除
「PR 已创建但未链接到 issue」
- 检查 PR 标题/正文查找 issue ID（如
AAC-42） - 验证 issue 存在于你的工作区
- 检查工作区前缀匹配（如 PR 说
AAC-42但工作区前缀是FOO） - 通过 issue 页面 → Pull requests → + 链接 PR 手动链接
「智能体无法推送到 GitHub」
- 验证 GitHub App 对仓库有写权限
- 检查智能体 GitHub 凭证仍有效
- 转到设置 → GitHub → 检查安装状态
- 需要时重新连接 app
「PR 已合并但 issue 未移到已完成」
- 验证 PR 已链接到 issue（应在 PR 行显示）
- 检查 issue 状态允许转换到已完成
- 通过 UI 手动将 issue 移到已完成
- 检查审计日志查看错误
「智能体不断获得 merge 冲突」
- 智能体可能在陈旧分支上工作; 鼓励频繁 pull
- 检查多个智能体是否修改相同文件
- 考虑为每个文件/功能分配单个智能体的工作
- 使用审批政策确保代码审查在合并前
相关功能
- GitHub 集成 — 见 GitHub 集成
- PR 评论同步 — 见 GitHub PR 评论同步
- 审批政策 — 见 审批政策