AutoGPT open-pr Skill 全解析：从预检、模板化 PR 到评审闭环的自动化提交流程

本篇基于 AutoGPT 仓库中的 open-pr Skill 定义 展开，完整还原该 Skill 的六步工作流（预检、测试覆盖、模板化创建 PR、评审触发、反馈处理、收尾），并结合仓库中的 PR 模板、配套 Skill（pr-test / pr-review / pr-address / pr-polish）与 贡献规范 的源码级证据，说明它如何约束 Agent 提交一个“不破坏现有行为、新行为有测试、评审可闭环”的 Pull Request。读完后你可以掌握：如何把一套 PR 流程沉淀为可复用的 Agent Skill，以及该流程中每个 gh 命令、模板规则与轮询机制的设计意图。

1. open-pr 是一个什么机制：Claude Agent Skill

open-pr 位于 .claude/skills/open-pr/SKILL.md，采用 YAML frontmatter + Markdown 正文的结构，是典型的 Claude Agent Skill 定义文件。其 frontmatter 声明了四个关键字段：

name: open-pr
description: Open a pull request with proper PR template, test coverage, and
  review workflow. ... TRIGGER when user asks to "open a PR", "create a PR",
  "make a PR", "submit a PR", ...
user-invocable: true
args: "[base-branch] — optional target branch (defaults to dev)."

• description 中除了功能描述，还明确列出了触发语（"open a PR"、"push and create PR" 等任意变体），用于让 Agent 在用户表达“提 PR”意图时自动命中该 Skill；
• user-invocable: true 表示用户可以以 /open-pr 形式直接调用；
• args 声明了唯一可选参数 [base-branch]，即目标分支，默认指向 dev——这与 AutoGPT 以 dev 为主开发分支的惯例一致。

该 Skill 的元数据为 author: autogpt-team、version: 1.0.0。它并非孤立存在，而是 .claude/skills/ 目录下一个 PR 技能族的核心入口，同族技能还包括：

Skill	文件	职责
/pr-test	.claude/skills/pr-test/SKILL.md	用 docker compose、agent-browser 与 API 调用做 E2E 手动测试
/pr-review	.claude/skills/pr-review/SKILL.md	按正确性、安全、代码质量、测试缺口做自评审
/pr-address	.claude/skills/pr-address/SKILL.md	处理评审意见，循环直到 CI 绿、评论清零
/pr-polish	.claude/skills/pr-polish/SKILL.md	交替执行 review + address，直到 PR 达到可合并状态

下文按 Skill 正文的六个 Step 依次展开。

2. Step 1：预检（Pre-flight checks）

在创建 PR 之前，open-pr 要求完成三件硬性事项：

1. 所有变更已提交——不允许带着未提交的工作区状态创建 PR；
2. 分支已推送到远端——使用 git push -u origin <branch>，-u 保证建立上游跟踪，后续 gh 命令和 CI 才能正确定位 head 分支；
3. 对整个仓库运行 linter/formatter，并提交产生的修复——注意这里的强调是 “across the whole repo (not just changed files)”：只检查改动文件可能放过历史遗留的格式问题，而 CI 通常按仓库整体校验，提前修复可避免 PR 打开后首轮 CI 红屏。

这一步与 AGENTS.md 中 “Rely on the pre-commit checks for linting and formatting” 的约定互为补充：pre-commit 钩子负责增量拦截，open-pr 的全仓 lint 负责提交前的最终兜底。

3. Step 2：测试覆盖（Test coverage）——Skill 中标注 “This is critical” 的一步

open-pr 把测试覆盖拆成两个正交问题，二者缺一都不允许开 PR：

3.1 现有行为不能被破坏

• 先识别本次改动触碰了哪些模块/组件；
• 运行这些区域的既有测试套件；
• 如果有测试失败，必须先修复再开 PR——“do not open a PR with known regressions”。

3.2 新行为必须有测试覆盖

Skill 给出按改动类型对号入座的规则：

• 新增功能、端点或行为变更都需要对应测试；
• 新增了一个 block，就要为该 block 加测试；
• 改了 API 行为，就要新增或更新 API 测试；
• 改了前端行为，要验证没有破坏既有用户流。

对于 AutoGPT 这种 block/agent 架构的平台仓库，这条规则意味着 autogpt_platform/backend/blocks/ 下新增的每个 block 都自带测试义务。测试命令则遵循 AGENTS.md 的分层约定：

• 后端：poetry run test（pytest，基于 docker 的 postgres + prisma）；
• 前端集成测试（默认手段，Vitest + RTL + MSW）：pnpm test:unit；
• 前端 E2E（Playwright）：pnpm test 或 pnpm test-ui。

最后一条兜底规则值得注意：如果本地无法跑完整测试套件，必须在 test plan 中如实注明“跑了哪些、没跑哪些”。这一要求会直接落到 PR 模板的 Checklist 中（见第 4 节），把“部分验证”从隐瞒项变成显式披露项。

4. Step 3：用仓库模板创建 PR（Step 3 的模板规则 + 完整模板内容）

open-pr 明确要求：读取规范模板 .github/PULL_REQUEST_TEMPLATE.md，并逐字（verbatim）使用它作为 PR 正文。具体规则有五条：

1. 用 cat .github/PULL_REQUEST_TEMPLATE.md 读取模板；
2. 精确保留章节标题与格式，包括 ### Why / What / How、### Changes 🏗️、### Checklist 📋；
3. 把 HTML 注释提示（<!-- ... -->）替换为真实内容，不允许把注释留在最终正文里；
4. 不要预先勾选任何复选框——所有 checkbox 保持 - [ ]，直到对应步骤真实完成；
5. 不得改动模板结构、不得重命名章节、不得删减 checklist 条目。

4.1 模板本身的结构

为方便直接对照填写，以下是该模板的完整结构（内容与 .github/PULL_REQUEST_TEMPLATE.md 一致）：

• ### Why / What / How：三个 HTML 注释分别提示——Why（这个 PR 为什么存在，解决什么问题，缺了它会怎样）、What（高层概述改了什么）、How（实现方式、关键细节或架构决策）。
• ### Changes 🏗️：以高于 diff 的粒度列出关键变更，但具体到“新/改了什么”。
• ### Checklist 📋 分为两组：
  • For code changes：变更已在描述中清晰列出；已制定 test plan；已按 test plan 完成测试（测试计划写在注释占位下，模板提供了一个示例计划，包含“从零创建并运行一个至少 3 个 block 的 agent”“从文件导入 agent 并确认可运行”“上传 agent 到 marketplace”“从 marketplace 导入并确认可运行”“从 monitor 编辑 agent 并确认可运行”等条目）；
  • For configuration changes：.env.default 已更新或兼容、docker-compose.yml 已更新或兼容、配置变更清单已写入 Changes 段（模板示例列举了改端口、新增需互联的服务、密钥/环境变量变更、数据库等基础设施变更）。

4.2 PR 标题：conventional commit 格式

Skill 规定标题必须采用 conventional commit 形式，并给出三个示例：feat(backend): add new block、fix(frontend): resolve routing bug、dx(skills): update PR workflow，同时指向 AGENTS.md 获取完整 scope 列表。仓库规范中实际定义的是：

• Types：feat / fix / refactor / ci / dx（developer experience）；
• Scopes：platform、platform/library、platform/marketplace、backend、backend/executor、frontend、frontend/library、frontend/marketplace、blocks。

4.3 创建命令：用 --body-file 规避 shell 转义

Skill 给出的标准创建命令是：

BASE_BRANCH="${BASE_BRANCH:-dev}"
PR_BODY=$(mktemp)
cat > "$PR_BODY" << 'PREOF'
<filled-in template from .github/PULL_REQUEST_TEMPLATE.md>
PREOF
gh pr create --base "$BASE_BRANCH" --title "<type>(scope): short description" --body-file "$PR_BODY"
rm "$PR_BODY"

几个细节体现了工程化考虑：

• BASE_BRANCH="${BASE_BRANCH:-dev}" 实现了 frontmatter 中 args 声明的默认值语义：未提供 [base-branch] 时回落到 dev；
• 正文先写入临时文件再用 --body-file 传入，目的是避免正文中的反引号、特殊字符被 shell 二次解释——PR 描述里常含代码块，直接内联 --body "..." 极易踩坑；
• heredoc 使用带引号的分隔符（'PREOF'），进一步保证内容原样落盘。

5. Step 4：评审工作流——按“能否本地测试”分两条路径

这是 open-pr 最核心的分支设计：Agent 所处的环境可能是一个能跑全栈的 workspace，也可能只是一个没有 docker 环境的 git worktree。Skill 据此给出两条路径。

5.1 路径 A：有可测试的 workspace（docker、运行中的 backend 等）

1. 运行 /pr-test：使用 docker compose、agent-browser 和 API 调用对 PR 做 E2E 手动测试——这是评审前最彻底的验证方式；
2. 测试完成后运行 /pr-review：在请求人工评审前，先针对正确性、安全性、代码质量、测试缺口做一轮自评审。

/pr-test 的实际规格相当严格（见 pr-test Skill）：每个状态变更操作都要记录 before/after 的 API 值、每个场景至少各一张前后截图、每个特性至少一个负向用例、截图必须推送到 test-screenshots/pr-{N} 临时分支并以内联图片形式贴回 PR 评论，最后还要基于“覆盖度、全部通过、负向测试、前后证据、无回归”等标准发出正式的 approve / request-changes 评审。

5.2 路径 B：没有可测试的 workspace（Agent 在 worktree 中很常见）

Skill 给出的五步操作规程：

1. 先本地跑 /pr-review，在 push 前抓住明显问题；
2. 创建 PR 后评论 /review 触发评审机器人；
3. 轮询而不是干等——每 30 秒用 gh api repos/<owner>/<repo>/pulls/{N}/reviews --paginate 及 GraphQL inline threads 查询检查新评审。Skill 说明机器人通常在 30 分钟内响应，轮询让 Agent 在评审到达的瞬间就能反应；
4. 在评审返回之前禁止推进或合并；
5. 处理机器人提出的问题——交由 /pr-address，它内置完整的“CI + 评论跟踪”轮询循环。

配套命令示例：

# 创建 PR 之后
PR_NUMBER=$(gh pr view --json number -q .number)
gh pr comment "$PR_NUMBER" --body "/review"
# 然后使用 /pr-address 轮询并在评审到达时处理

5.3 两条路径背后的评审检查项

/pr-review 自评审的检查维度（见 pr-review Skill）包括：描述质量（Why/What/How 是否齐备）、正确性（逻辑错误、off-by-one、竞态、异步缺失 await 等）、安全（边界输入校验、注入、密钥不落日志）、代码质量（按前后端 CLAUDE.md 规则）、架构（DRY、FastAPI 鉴权用 Security() 而非 Depends()、SSE 事件用 data: 等）、测试（同目录 *_test.py / __tests__/ 约定）。所有评审意见须以 🤖 加严重级徽章输出并以 inline 评论形式直接贴到 PR，严重级分四级：🔴 Blocker（合并前必须修）、🟠 Should Fix、🟡 Nice to Have、🔵 Nit。

6. Step 5：处理评审反馈——/pr-address 的闭环纪律

评审机器人或人工评审留下评论后，open-pr 的处理原则是：

• 运行 /pr-address，它会循环处理直到 CI 全绿且所有评论被解决；
• 没有人工批准不得合并。

/pr-address（见 pr-address Skill）是该闭环中最厚重的部分，几条纪律值得单独强调：

• 唯一合法的处置序列是 fix → commit → push → reply → resolve。直接调用 resolveReviewThread 而没有真实提交，是文档中反复警告的“最常见失败模式”——未解决计数降了，但代码什么都没变，产生虚假的“完成”信号。
• 分页陷阱：GraphQL 的 reviewThreads(first: 100) 每页最多 100 条且按最旧优先返回；文档给出真实案例（142 个 thread 的第一页过滤后 0 条未解决，而第 2–3 页有 111 条），因此规则是必须翻到 hasNextPage == false 为止，绝不允许因为某页未解决数为 0 就提前停止。
• 轮询而非阻塞：每 30 秒检查一次 CI 状态（gh pr checks {N} --json bucket,name,link）、mergeable 状态与三类评论来源；且明确禁用 gh pr checks --watch，因为它会阻塞整个工具调用、无法在 CI 运行期间响应新评论。
• 退出条件：CI 全绿 + 评论清零 + CI 稳定后连续两轮（约 60 秒）无新评论，才允许结束循环。
• 另有 GitHub 三类速率限制（REST 403 abuse、REST 429、GraphQL 独立限额）的检测与 REST 降级方案，以及“按文件分组批量 commit”的并行处理策略。

7. Step 6：创建后的收尾动作

PR 创建并触发评审之后，open-pr 规定三个收尾动作：

1. 把 PR URL 分享给用户；
2. 若在等待评审机器人，告知用户预期等待时间（约 30 分钟）；
3. 没有人工批准不得合并——这条红线在 Step 5 与 Step 6 中被重复强调。

8. 仓库层面的配套约定与运行前提

open-pr 的可执行性依赖仓库中另外几处事实性约定，理解它们才能完整复现该流程：

• PR 模板是契约：.github/PULL_REQUEST_TEMPLATE.md 定义了 Why/What/How、Changes、Checklist 三段结构，pr-review 与 pr-test 均以“PR 描述是否覆盖 Why/What/How”作为评审/测试的起点——模板质量直接决定下游自动化质量。
• 提交规范：AGENTS.md 要求 conventional commit（feat/fix/refactor/ci/dx + 上述 scope）、提交前跑相应 linter 与测试、PR 中范围外变更占比控制在 20% 以内、改动 data/*.py 时需说明 user ID 校验、新增受保护前端路由时需同步更新 frontend/lib/supabase/middleware.ts——这些都会以评审意见的形式回到 /pr-address 循环中。
• 格式化工具链：后端 poetry run format，前端 pnpm format && pnpm lint && pnpm types（pr-address 中明确“format 不过会是永不自愈的 CI failure”）。
• 权限面：.claude/settings.json 为 Agent 预置了 Read/Grep/Glob 与白名单 Bash 命令（git status/diff/log/worktree 等）的工具权限，open-pr 这类 Skill 在其上调用 gh、git 命令完成整个流程。
• 运行前提：该流程假设本机已安装并认证 GitHub CLI（gh），有对 AutoGPT 仓库的 push 权限，目标分支默认 dev；路径 B（无 workspace）下 Agent 无法做 E2E 验证，因此把验证责任前移到 /review 机器人与 /pr-address 轮询。

9. 小结：这套流程沉淀了什么经验

把 open-pr 与同族 Skill 合起来看，AutoGPT 仓库实际上把“一个人提 PR 的正确姿势”固化成了 Agent 可执行的状态机：

1. 预检先行（全仓 lint + 推送）保证 PR 出生即干净；
2. 测试双覆盖（不破坏旧行为 + 新行为有测试）把回归风险挡在创建前；
3. 模板逐字复用 + 不预勾选 checkbox 保证 PR 描述的可评审性与真实性；
4. 按环境分叉的评审路径（有 workspace 走 /pr-test E2E，无 workspace 走 /review 机器人 + 30 秒轮询）让同一流程适配本地全栈与纯 worktree 两种形态；
5. fix → commit → push → reply → resolve 的严格序列与“两轮干净轮询才退出”的收敛条件，消除“假性完成”；
6. 合并权始终保留给人类，Agent 只负责把 PR 推到 merge-ready。

对想要在自己仓库中沉淀类似 Skill 的团队而言，.claude/skills/ 目录下的这五个 SKILL.md（open-pr、pr-test、pr-review、pr-address、pr-polish）加上 PR 模板 与 AGENTS.md 中的提交规范，构成了一套可直接参考的“PR 工作流即代码”范式。