gh-create-pr

GitHub PR 创建

堆叠分支工具

此仓库将 .agents/skills/gh-stack/SKILL.md 作为公开项目技能提供；开发者无需单独安装此 Agent 技能。在操作堆叠分支或 PR 前，请先阅读该文件。使用 .agents/skills/ 的 Agent 会直接发现此技能。如果 Claude 检出中缺少 .claude/skills/gh-stack，请运行 pnpm skills:sync，然后运行 pnpm skills:check；不要下载单独的全局副本。

在任务中首次运行 gh stack 命令前，请检查 GitHub CLI，并在缺少官方扩展时安装它：

command -v gh >/dev/null 2>&1 || {
  echo "GitHub CLI is required: https://cli.github.com/" >&2
  exit 1
}
gh auth status
if ! gh stack --help >/dev/null 2>&1; then
  gh extension install github/gh-stack
fi
gh stack --help >/dev/null

如果身份验证、安装或最终验证失败，请停止。不要使用临时的 Git 命令推断堆叠关系。对于人工编写的 Cherry PR，请使用 gh stack push，从底部到顶部通过此技能创建每个符合要求的 PR，然后使用 gh stack link 关联已有 PR；gh stack submit --auto 会绕过符合模板要求的正文流程创建 PR，不得用它绕过此工作流。

工作流

1. 起草 PR 正文前，先阅读 .github/pull_request_template.md。
2. 从当前分支收集 PR 上下文（base/head、范围、关联 issue、测试状态、破坏性变更、发布说明内容）。确认实际 base，并运行 pnpm change:scope --base <verified-base-ref>；不要只根据最近一次提交推断范围。
3. 阅读 .agents/notes/README.md 并对变更进行分类：
   • 在 Agent Note 中填写仓库路径；如果是本地或机械性变更，则填写 N/A — <reason>。
   • 对于 Spec PR，填写 Spec PR: This PR 并列出所有 AC。
   • 对于实现层，链接 Spec PR，并仅列出本层覆盖的 AC ID。确认存在一条 commit_id 与当前 Spec head 相同的 APPROVED 审核；过期的批准不能授权实现。
   • 对于有持久理由说明的直接 bug 修复，链接已实现的 bug-fix note，并填写 Spec PR: N/A。
   • 由自动化撰写的 PR（仓库工作流和 Dependabot）无需填写这些元数据字段。不要让它们的正文模仿人工撰写的 PR。
4. 对于实现 PR，先完成堆栈工具预检，然后运行 gh stack view --json。如果退出码为 2，请遵循 gh-stack 技能中的远程发现流程；缺少本地元数据并不能证明 PR 是独立的。检查每个下游实现 PR，并仅汇总有实际验证支持的 AC。中间层应保留 proposed 状态的 note。如果当前 PR 是最后一层，且累积证据覆盖完整的已批准 Spec，则将双语三元组移至 implemented/，并在发布前运行 pnpm agent-notes:check-transition --base <verified-spec-ref>。
5. 在 Verification 中填写实际运行过的命令和场景。绝不能将计划中、待处理、跳过或仅 CI 执行的检查标记为通过。
6. 检查当前分支是否已推送到远程。如果尚未推送，请先推送：
   • 默认远程为 origin，但如果想使用其他远程，请询问用户。

   git push -u <remote> <head-branch>
   

7. 确定 base 分支：
   • 应用任何默认值前，先检查 head 分支。如果 head 是 release/v<version>，请停止：绝不要从发布分支创建 pull request，尤其不要创建到 main 的 PR。应将独立修复放在主题分支上并以发布分支为目标，或者让 Post Release 创建元数据同步分支。
   • 将任意主题分支默认设为 main 前，先检查其合并基点和上游。若产品代码修复始于 release/v<version>，必须停止并从 main 重新创建为 hotfix；只有发布专属修复或明确的 backport 恢复主题分支可以指向对应的发布分支。
   • backport/v<version>/pr-<number> head 必须以匹配的 release/v<version> 为 base，且正文必须在单独一行包含用于指向确切源 hotfix PR 的 ``。release-sync/v<version> head 必须以 main 为目标，使用确切标题 chore(release): sync v<version> metadata，保留正文标记 release-metadata-boundary: v<version>，并使用 squash 合并。
   • 对于将 CherryHQ/cherry-studio 作为 origin 的官方仓库：默认 base 为 origin 上的 main，但允许用户明确指定 base 分支。
   • main 是当前活跃的开发线，包括 hotfix PR。除非用户明确要求，否则不要以旧维护分支为目标。
   • 只有当用户明确表示必须将 PR 纳入当前草稿发布版本时，才将 PR 归类为发布 hotfix。标题使用 hotfix: <description> 或 hotfix(<kebab-case-scope>): <description>，scope 必须是小写字母数字 kebab-case，冒号后恰好一个空格，且 description 不得为空。标题语法会自动同步 hotfix 标签。只有在恰好一个草稿语义化版本发布有匹配的活跃 release/v<version> 分支时，合并才会创建单独的 backport PR；否则自动化会停止，不会猜测目标。
   • 如果 hotfix 会影响用户，请分别提供一条各语言的发布说明，以便自动化更新当前草稿发布版本和稳定版发布历史。将以下确切结构放在模板现有的 release-note 围栏内；不要添加项目符号前缀：

     
     [组件] 英文说明。
     
     [组件] 中文说明。
     
     

   • 如果此热修复没有面向用户的发布说明，请在模板的 release-note 代码围栏中保留 NONE。代码仍会回移，但发布元数据不变。提供的双语内容块必须严格符合上述结构。
   • 如果将 fork 仓库设为 origin：使用 git remote -v 检查可用的远程仓库；默认基准分支可能是 upstream/main 或其他远程仓库。始终假定用户希望将 head 合并到 CherryHQ/cherry-studio/main，除非用户明确指定了基准分支。
   • 如果基准分支不是默认分支，请让用户确认。
8. 创建临时文件，并使用单个 Bash heredoc 写入 PR 正文 （避免在 Windows 上使用 mktemp 和 Write 工具时出现路径不匹配）：

   pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
   cat > "$pr_body_file" <<'EOF'
   ...filled template body...
   EOF
   

   严格按照模板结构填写内容（保留章节顺序、 标题和复选框格式）。如不适用，请填写 N/A 或 None。
9. 使用 Bash cat "$pr_body_file" 检查临时文件内容（在 Windows 上，Read 工具可能无法读取 /tmp/... 路径）。如果用户要求预览或确认，请展示完整正文并按其要求操作；否则，继续创建已获授权的 PR。
10. 创建 PR；如果用户要求创建草稿，请添加 --draft：

gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"

对于发布热修复，请使用可被分类器准确识别的标题，以便工作流同步标签，并单独验证提供的双语说明：

gh pr create --base main --head <head> --title "hotfix: <description>" --body-file "$pr_body_file"

创建后，确认分类器是否添加了 hotfix；如果没有，请修改标题，而不是手动添加标签。还要修正工作流报告的任何格式错误的可选发布说明块。 11. 清理临时文件：rm -f "$pr_body_file" 12. 报告已创建 PR 的 URL，并概述标题、基准分支/head、Agent Note/Spec、AC 覆盖情况、实际验证内容以及任何所需的后续操作。

约束

• 不得跳过模板中的任何章节。

• 不得改写模板格式。

• 内容应简洁明确，并针对当前变更集。

• PR 标题和正文必须使用英文。

• 普通 bug 修复不得使用 hotfix 标题或标签。该标签会在合并后、存在一个匹配的草稿版本发布时，触发自动创建回移 PR。

• 发布热修复在没有面向用户的发布说明时可以使用 NONE。不得提供不完整、仅单语或格式错误的双语说明；回移工作流会对格式错误的内容采取失败关闭处理。

• 绝不能默认将 release/v<version> 分支设为 main 的 head；发布分支不能作为 PR 源分支。

• 当前 Spec head 尚未获得精确匹配的 Approval 时，绝不能将实现 PR 发布为就绪状态。Spec 可以保持未合并，并作为堆叠分支的基准。

• 每个由人编写的 PR 都必须填写 Agent Note、Spec PR 和 Acceptance criteria；若填写 N/A，必须简要说明原因。自动化创建的 PR（仓库工作流和 Dependabot）不受此元数据要求限制。

• 发布说明与文档复选框——两者都取决于变更是否面向用户。请使用下表：

  变更类型	发布说明	文档 [x]
  面向用户的新功能／设置／UI	描述变更	✅
  用户可见的 bug 修复	描述修复内容	如果行为发生变化则勾选 ✅
  行为变更／默认值变更	描述变更 + action required	✅
  面向用户的依赖项安全修复	描述修复内容	如果用法发生变化则勾选 ✅
  CI／GitHub Actions 变更	NONE	❌
  内部重构（用户无法察觉）	NONE	❌
  开发／构建工具变更	NONE	❌
  仅用于开发的依赖项升级	NONE	❌
  仅测试／代码风格变更	NONE	❌

命令模式

# read template
cat .github/pull_request_template.md

# prepare and inspect the PR body
pr_body_file="/tmp/gh-pr-body-$(date +%s).md"
cat > "$pr_body_file" <<'EOF'
...filled template body...
EOF
cat "$pr_body_file"

# create the authorized PR; add --draft when requested
gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
rm -f "$pr_body_file"