agent-pr-creator

Agent PR 创建器

分析 git 差异和提交历史，智能填写 PR 模板，并通过 gh CLI 创建拉取请求。本技能将介绍如何检测基分支、分析更改、读取项目的 PR 模板、根据提交和差异填充模板上下文，以及创建 PR。

工作流

阶段 1：检测基分支并检查是否已有 PR

确定此 PR 的目标基分支：

# Check if develop exists; fall back to main
git rev-parse --verify develop 2>/dev/null && echo "develop" || echo "main"

# Current branch
git branch --show-current

检查当前分支是否已有 PR：

gh pr list --head $(git branch --show-current) --json number,url,title

如果已有 PR，请停止并告知用户。询问他们是否想改用 gh pr edit 更新描述。

检查点： 如果有未提交的更改，或当前分支落后于远程分支，请警告用户并停止：

# Check for uncommitted changes
git status --porcelain

# Check if branch is behind remote
git rev-parse @{u} 2>/dev/null && git log --oneline @..@{u}

如果分支没有远程跟踪分支，请在创建 PR 前使用 -u 推送：

git push -u origin $(git branch --show-current)

阶段 2：分析更改

收集自基分支以来更改的完整上下文：

# Get the base branch
BASE=$(git rev-parse --verify develop 2>/dev/null && echo "develop" || echo "main")

# Changed files
git diff ${BASE}...HEAD --name-only

# Commit log with oneline format
git log --oneline ${BASE}..HEAD

# Diff stats (file-level changes)
git diff ${BASE}...HEAD --stat

# Full diff for review (optional, context-dependent)
git diff ${BASE}...HEAD

分析更改，以了解：

• 修改了哪些文件，以及涉及哪些领域（前端、后端、测试、文档、配置）
• 有多少次提交
• 出现了哪些常规提交类型（feat、fix、refactor、test、docs、chore）
• 是否有破坏性更改（API 更改、架构迁移、配置格式更改）
• 这是重构、新功能、错误修复，还是几者的组合

阶段 3：读取 PR 模板

定位并读取项目的 PR 模板：

# Standard locations
ls -la .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md PULL_REQUEST_TEMPLATE.md pull_request_template.md 2>/dev/null | head -1

如果找到模板，请通读全文以了解：

• 所有必填部分（描述、变更类型、破坏性更改、屏幕截图、备注、检查清单）
• 准确的复选框标签和选项
• 项目采用的任何特定说明或约定

如果没有找到模板，则创建仅包含标题和描述的简版 PR。

阶段 4：填写 PR 模板

根据更改内容填写模板的各个部分：

标题： 使用 Conventional Commits 格式

• 前缀：根据大多数提交使用 feat:、fix:、refactor:、docs:、test: 或 chore:
• 格式：<type>: <short description>
• 不超过 70 个字符
• 使用祈使语气（“add”“fix”“update”，而不是“added”“fixed”“updates”）
• 示例：feat: add authentication service integration

描述：

• 分析差异和提交，写出 2–3 句话，概述更改了什么以及为什么
• 聚焦业务价值，而非实现细节
• 如果修改了多个方面，请按逻辑分组（例如：“数据库层更改以提升查询性能。前端更改以显示新指标。向仪表板添加了新的监控查询。”）
• 如果分支名称或提交中包含 Linear/问题 ID，请引用它们（例如 PUL3-34、#123）
• 示例：“新增 OAuth 2.0 身份验证流程，以支持第三方集成。采用标准 OIDC 提供商模式，以支持多个身份服务。关闭 PUL3-42。”

更改类型：

• 分析提交前缀：feat → 新功能，fix → 错误修复，refactor → 代码重构，test → 测试，docs → 文档，chore/build → 构建/配置
• 勾选符合项：选中使用 [x]，未选中使用 [ ]
• 使用模板中的确切复选框标签，不要改写或转述
• 可以勾选多个选项（例如，功能 PR 也可能包含测试）

破坏性更改：

• 分析是否修改了以下任何内容：
  • 公共 API 契约（函数签名、端点、导出类型）
  • 数据库架构（新增必填字段、删除列、类型更改）
  • 环境变量（新增必需变量、删除变量、更改格式）
  • 配置文件格式（结构、必需键、已弃用选项）
  • 删除导出项或公共方法
• 如果有：勾选“Yes”，并说明会造成什么影响以及所需的迁移步骤
• 如果没有：勾选“No”
• 示例：“是 — POST /api/auth/login 现在要求提供 oauth_provider 字段。缺少此字段的现有调用将返回 400。请更新客户端身份验证代码以指定提供商。”

截图 / 视频：

• 如果更改涉及 UI 文件（src/components/、pages/、app/ 或 .jsx、.tsx、.vue 等扩展名的文件）：添加占位符 ``
• 否则：填写 N/A — No UI changes

附加说明 / 检查清单：

• 如果需要非标准部署步骤，请注明（数据库迁移、环境设置、服务重启）
• 注明对其他 PR 或服务的依赖
• 如果更改需要特定测试路径或边缘情况，请添加审阅者说明
• 如果没有特别事项：填写 N/A，或根据模板风格留空

阶段 5：创建 PR

使用 gh pr create，并填写模板和标题：

gh pr create \
  --base ${BASE} \
  --title "<type>: <short description>" \
  --body "<filled template body as HEREDOC or string>"

示例：

gh pr create --base develop \
  --title "feat: add authentication service integration" \
  --body $'## Description\nAdds OAuth 2.0 support for third-party integrations.\n\n## Type of Change\n- [x] New Feature\n- [ ] Bug Fix\n\n## Breaking Changes\n- [ ] Yes\n- [x] No\n\n## Screenshots\nN/A'

**重要：**保留模板中的 Markdown 格式。使用 Shell HEREDOC（$'...'）或多行字符串，以保留章节分隔符和格式。

阶段 6：确认并报告

gh pr create 成功后，输出：

1. PR URL（例如 https://github.com/owner/repo/pull/456）
2. PR 编号
3. 简要说明所包含的内容（更改类型、受影响的关键部分）
4. 说明是否自动分配了审阅者，或是否有特殊状态（草稿、准备审阅）

示例输出：

PR created: https://github.com/ravn/ai-toolkit/pull/123
Type: feat (New Feature)
Changes: 3 files, 156 additions
Affected areas: Authentication service, OAuth integration tests
Ready for review.

示例

正向触发

用户：“填写 PR 模板，并为我的分支创建一个拉取请求”

预期行为：使用 agent-pr-creator 工作流分析 git 历史记录，读取 PR 模板，根据更改智能填写所有部分，并通过 gh pr create 创建 PR。

---

用户：“我需要创建一个描述完善的拉取请求”

预期行为：使用 agent-pr-creator 从提交和差异中收集上下文，分析更改类型（feat/fix/refactor）、检测是否存在破坏性更改，并按照约定创建标题和正文得当、内容全面的 PR。

---

用户：“向 main 创建一个 PR”

预期行为：使用 agent-pr-creator 检测基分支，分析自分支以来的所有更改，按照项目约定填写模板，并创建 PR。

非触发

用户：“审查这个拉取请求：https://github.com/org/repo/pull/123”

预期行为：不要使用 agent-pr-creator。用户想审查现有 PR，而不是创建 PR。改用 gh pr view 或审查技能。

---

用户：“我的分支有哪些更改？”

预期行为：不要使用 agent-pr-creator。用户想查看更改，而不是创建 PR。直接使用 git diff 或 git log。

故障排除

技能未触发

• 错误：用户要求创建 PR 时，未选择此技能。
• 原因：请求措辞与触发短语不匹配。请求使用了“review”或“commit”等泛泛的词语，而不是“create PR”“open PR”或“make PR”。
• 解决方案：使用明确的 PR 创建关键词重新表述，例如“create a pull request”“make a PR”或“open a PR”，然后重试。

未找到 PR 模板

• 错误：找不到 .github/PULL_REQUEST_TEMPLATE.md 或类似文件。
• 原因：项目没有 PR 模板，或者模板位于非标准位置。
• 解决方案：在 .github/ 和常见的根目录位置中搜索模板文件。如果没有找到，则使用约定式提交格式，仅包含标题和描述，创建一个最简 PR。

此分支已存在 PR

• 错误：由于此分支已存在 PR，gh pr create 失败。
• 原因：此分支已有一个开放的 PR。
• 解决方案：告知用户现有 PR 的 URL，并询问他们是否想使用 gh pr edit <PR> 更新描述，而不是创建新的 PR。

存在未提交的更改，或分支落后于远程

• 错误：由于存在未提交的更改，或分支落后于远程，无法创建 PR。
• 原因：工作目录中有尚未暂存或提交的更改，或者本地分支落后于上游分支。
• 解决方案：对于未提交的更改：提醒用户，并建议先使用 /commit 提交或暂存更改。对于落后的分支：先拉取并变基，然后再创建 PR。

缺少远程跟踪分支

• 错误：由于分支没有上游跟踪分支，gh pr create 失败。
• 原因：本地分支从未推送到远程。
• 解决方案：先使用 git push -u origin <branch-name> 推送分支，然后创建 PR。

gh CLI 身份验证失败

• 错误：gh 命令失败，并显示“not authenticated”或“token expired”错误。
• 原因：GitHub CLI 尚未登录，或身份验证令牌已过期。
• 解决方案：运行 gh auth login 重新进行身份验证，然后重试此技能。