git-commit-push-pr

Git 提交、推送和 PR

从完成更改到发起拉取请求，或重写现有 PR 描述。

询问用户： 当此技能要求“询问用户”时，请使用平台的阻塞式提问工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。如果不可用，请提出问题并等待回复。

模式检测

如果用户要求更新、刷新或重写现有 PR 描述（且没有提到提交或推送），这属于仅更新描述。用户也可以指定重点（例如，“更新 PR 描述并加入基准测试结果”）。记录重点，以便在 DU-3 中使用。

对于仅更新描述的请求，请遵循下方的“描述更新工作流”。否则，请遵循完整工作流。

上下文

如果你不是 Claude Code，请跳转到下方的“上下文回退”部分，并运行其中的命令来收集上下文。

如果你是 Claude Code，下方六个带标签的部分已包含预先收集的数据。直接使用这些数据——不要重新运行这些命令。

Git 状态： !git status

工作树差异： !git diff HEAD

当前分支： !git branch --show-current

最近的提交： !git log --oneline -10

远程默认分支： !git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'

现有 PR 检查： !gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'

上下文回退

如果你是 Claude Code，请跳过此部分——上方已提供数据。

运行这条命令来收集所有上下文：

printf '=== STATUS ===\n'; git status; printf '\n=== DIFF ===\n'; git diff HEAD; printf '\n=== BRANCH ===\n'; git branch --show-current; printf '\n=== LOG ===\n'; git log --oneline -10; printf '\n=== DEFAULT_BRANCH ===\n'; git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'; printf '\n=== PR_CHECK ===\n'; gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'

---

描述更新工作流

DU-1：确认意图

询问用户：“要更新此分支的 PR 描述吗？”如果用户拒绝，请停止。

DU-2：查找 PR

使用上下文中的当前分支和现有 PR 检查结果。如果当前分支为空（处于 detached HEAD 状态），请报告没有分支并停止。如果 PR 检查结果为 state: OPEN，请记录上下文块中的 PR url——这是传递给后续步骤的明确引用——然后继续 DU-3。否则，请报告没有打开的 PR 并停止。

DU-3：撰写并应用更新后的描述

读取当前 PR 描述，以便之后进行比较并确认：

gh pr view --json body --jq '.body'

生成更新后的标题和正文——使用 DU-2 中的 PR URL（例如，https://github.com/owner/repo/pull/123）加载 ce-pr-description 技能。即使从工作树或当前仓库不明确的子目录中调用，该 URL 也能保留仓库和 PR 的身份信息。如果用户指定了重点（例如，“加入基准测试结果”），请在 URL 后追加该内容作为自由文本引导。此技能会返回 {title, body_file} 块（正文位于 OS 临时文件中），不会应用更改或提示用户。

如果 ce-pr-description 返回“未打开”或其他正常退出消息，而不是 {title, body_file} 对，请报告该消息并停止。

证据决策： 默认情况下，ce-pr-description 会保留当前正文中已有的 ## Demo 或 ## Screenshots 区块。如果用户的重点要求刷新或移除证据，请将该意图作为引导文本传入——此技能会按要求处理。如果不存在证据区块，且添加证据有助于读者理解，请单独调用 ce-demo-reel 进行采集，然后重新调用 ce-pr-description，并在更新后的引导文本中引用所采集的证据。

比较并确认——简要说明新描述与旧描述相比涵盖了哪些不同内容。这有助于用户决定是否应用；描述本身不应叙述这些差异。根据上下文中已有的正文进行总结（即写入 body_file 的 bash 调用中的内容）；不要 cat 临时文件，以免再次输出正文。

• 如果用户指定了重点，请确认已涵盖该重点。
• 应用前请征求用户确认。

如果用户确认，请使用返回的标题和正文文件进行应用：

gh pr edit --title "<returned title>" --body "$(cat "<returned body_file>")"

报告 PR URL。

---

完整工作流

步骤 1：收集上下文

使用上述上下文。此步骤和步骤 3 所需的所有数据均已提供——不要重新运行这些命令。

远程默认分支的值类似于 origin/main。去掉 origin/ 前缀。如果返回 DEFAULT_BRANCH_UNRESOLVED 或裸 HEAD，请尝试：

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

如果两者都失败，则回退到 main。

如果当前分支为空（分离 HEAD），请说明需要一个分支。询问现在是否要创建功能分支。

• 如果是，根据变更内容派生分支名称，使用 git checkout -b <branch-name> 创建分支，并在后续工作流中使用该分支。
• 如果否，则停止。

如果工作树干净（没有暂存、已修改或未跟踪文件），确定下一步操作：

1. 运行 git rev-parse --abbrev-ref --symbolic-full-name @{u} 检查上游分支。
2. 如果存在上游分支，运行 git log <upstream>..HEAD --oneline 查看尚未推送的提交。

决策树：

• 位于默认分支，有未推送的提交或没有上游分支——询问是否创建功能分支（不支持直接推送默认分支）。如果是，创建分支并从步骤 5 继续。如果否，则停止。
• 位于默认分支，所有提交均已推送，没有未关闭的 PR——报告没有功能分支工作。停止。
• 功能分支，没有上游分支——跳过步骤 4，从步骤 5 继续。
• 功能分支，有未推送的提交——跳过步骤 4，从步骤 5 继续。
• 功能分支，所有提交均已推送，没有未关闭的 PR——跳过步骤 4–5，从步骤 6 继续。
• 功能分支，所有提交均已推送，有未关闭的 PR——报告已是最新状态。停止。

步骤 2：确定约定

提交消息和 PR 标题的优先顺序：

1. 上下文中的仓库约定——如果项目说明指定了约定，请遵循。不要重新读取；这些说明会在会话开始时加载。
2. 近期提交历史——遵循最近 10 个提交中的模式。
3. 默认格式——type(scope): description（约定式提交）。

步骤 3：检查是否已有 PR

使用当前分支和上下文中已有的 PR 检查结果。如果分支为空，请报告分离 HEAD 并停止。

如果 PR 检查返回 state: OPEN，请记下 URL——这是已有 PR 流程。继续执行步骤 4 和 5（提交任何待处理工作并推送），然后前往步骤 7，询问是否要重写描述。只有在用户确认重写后，才运行步骤 6（通过 ce-pr-description 生成新描述）；步骤 7 中处理已有 PR 的分支会使用步骤 6 生成的 {title, body_file}。否则（没有未关闭的 PR），按顺序继续执行步骤 6、7 和 8。

步骤 4：创建分支、暂存并提交

1. 如果位于默认分支，先使用 git checkout -b <branch-name> 创建功能分支。
2. 扫描已更改文件，找出自然区分的事项。如果文件明显分成不同的逻辑变更，则分别创建提交（最多 2–3 个）。仅按文件分组（不要使用 git add -p）。如果难以区分，一个提交即可。
3. 在单次调用中暂存并提交每个分组。避免使用 git add -A 或 git add .。遵循步骤 2 中的约定：

   git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
   commit message here
   EOF
   )"
   

步骤 5：推送

git push -u origin HEAD

步骤 6：生成 PR 标题和正文

步骤 1 中的工作树差异仅显示调用时未提交的变更。PR 描述必须涵盖 PR 中的所有提交。

**检测基分支和远程仓库。**解析基分支和远程仓库（基于 fork 的 PR 可能使用 origin 以外的远程仓库）。按以下顺序尝试，首个成功项即停止：

1. PR 元数据（如果步骤 3 中找到已有 PR）：

   gh pr view --json baseRefName,url
   

   提取 baseRefName。将 PR URL 中的 owner/repo 与 git remote -v 的 fetch URL 匹配，以查找基远程仓库。若未找到，则回退到 origin。
2. 上下文中的远程默认分支——如果已解析，则去掉 origin/ 前缀。使用 origin。
3. GitHub 元数据：

   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
   

   使用 origin。
4. 常见名称——按顺序检查 main、master、develop、trunk：

   git rev-parse --verify origin/<candidate>
   

   使用 origin。

如果均未解析出结果，请询问用户指定目标分支。 收集完整的分支差异（在决定证据之前）。 第 1 步的工作区差异仅反映调用时尚未提交的更改——在常见的“功能分支已全部推送，且已创建 PR”场景中，第 1 步会跳过提交和推送步骤，因此工作区差异为空。下面的证据决策需要真实的分支差异来判断行为是否可观察，因此请针对上文解析的基准分支显式计算差异。仅当本地引用不可用时才获取——如果 <base-remote>/<base-branch> 已可在本地解析，请根据本地状态运行差异比较，以免在离线、网络受限或身份验证过期的环境中失败：

git rev-parse --verify <base-remote>/<base-branch> >/dev/null 2>&1 \
  || git fetch --no-tags <base-remote> <base-branch>
git diff <base-remote>/<base-branch>...HEAD

请在证据决策中使用此分支差异（而非工作区差异）。如果分支差异为空（例如，HEAD 已合并到基准分支，或该分支没有独有提交），则跳过证据提示并继续委派。

证据决策（委派之前）。 如果分支差异改变了可观察行为（UI、CLI 输出、可运行代码的 API 行为、生成的产物、工作流输出），且证据未受到其他因素阻碍（凭据不可用、付费服务、仅可通过部署使用的基础设施、硬件），请询问：“此 PR 具有可观察行为。要为 PR 描述捕获证据吗？”

• 立即捕获——加载 ce-demo-reel 技能，并根据分支差异推断目标描述。ce-demo-reel 会返回 Tier、Description 和 URL。记录已捕获的证据，以便将其作为自由文本引导传递给 ce-pr-description（例如，“在 ## Demo 部分中包含已捕获的演示：”），或在应用之前将其插入返回的正文中。如果捕获结果为 Tier: skipped 或 URL: "none"，则不附带证据继续。
• 使用现有证据——询问 URL 或 Markdown 嵌入内容，然后将其作为自由文本引导传递给 ce-pr-description，或在应用之前插入。
• 跳过——不附带证据部分继续。

如果无法提供证据（仅限文档、仅限 Markdown、仅限变更日志、发布元数据、仅限 CI/配置、仅限测试或纯内部重构），则直接跳过，无需询问。

委派 ce-pr-description 生成标题和正文。 加载 ce-pr-description 技能：

• 新建 PR（第 3 步中未找到现有 PR）：使用此前在本步骤中已解析的基准分支，通过 base:<base-remote>/<base-branch> 调用，这样即使分支的目标不是默认基准分支（例如 develop、release/*），ce-pr-description 也能描述正确的提交范围。将任何已捕获证据的上下文或用户关注点作为自由文本引导附加（例如，“在 ## Demo 部分中包含已捕获的演示：”）。
• 现有 PR（第 3 步中找到）：使用第 3 步上下文中的完整 PR URL 调用（例如，https://github.com/owner/repo/pull/123）。即使从工作树或子目录中调用，该 URL 也能保留仓库和 PR 标识；技能会读取该 PR 自身的 baseRefName，因此无需覆盖 base:。将任何关注点引导作为自由文本附加在 URL 之后。

ce-pr-description 会返回一个 {title, body_file} 块（正文位于操作系统临时文件中）。它会在内部应用价值优先的写作原则、提交分类、篇幅控制、叙事框架、写作风格、视觉沟通、编号规则以及 Compound Engineering 徽章页脚。请在第 7 步中原样使用返回值；除非需要针对性调整，否则不要手动修改（例如，将本步骤捕获但未作为引导文本传入的证据内容插入正文——这种情况下，请直接编辑正文文件，然后再应用）。

如果 ce-pr-description 返回的是正常退出消息，而非 {title, body_file}（例如，PR 已关闭、没有可描述的提交、基准分支引用无法解析），请报告该消息并停止——不要创建或编辑 PR。

第 7 步：创建或更新 PR

新建 PR（第 3 步未找到现有 PR）

使用 ce-pr-description 返回的 {title, body_file}：

gh pr create --title "<returned title>" --body "$(cat "<returned body_file>")"

标题控制在 72 个字符以内；ce-pr-description 已生成符合约定式提交规范且长度在此范围内的标题。

现有 PR（第 3 步已找到）

新提交已在第 5 步对应的 PR 中。报告 PR URL，然后询问是否要重写描述。

• 如果回答是，现在运行第 6 步，通过 ce-pr-description 生成 {title, body_file}（将现有 PR URL 作为 pr: 传入），然后应用返回的标题和正文文件：

  gh pr edit --title "<returned title>" --body "$(cat "<returned body_file>")"
  

• 如果回答否——完全跳过第 6 步并结束。用户拒绝重写后，不要运行委派或证据收集。

第 8 步：报告

输出 PR URL。