create-pr

推送当前分支并创建 GitHub 拉取请求。如果分支名称中包含 JIRA ID，且能够加载对应工单，则 PR 标题和描述应以该工单为准。如果没有 JIRA ID，或者无法获取工单，仍需推送分支，向开发者提供多个 PR 标题选项供其选择（也可自定义标题），然后创建 PR。PR 描述始终只引用此 PR 实际解决的所有问题（例如 JIRA 工单、GitHub issue 等），绝不引用相关但未解决的问题。

用法：

• /create-pr - 推送并创建草稿 PR
• /create-pr --no-draft - 推送并创建可供审核的 PR

说明：

1. 检查前置条件（GitHub — 始终检查）：

   • GitHub CLI（gh）： 运行 gh --version。如果找不到该命令，显示以下消息并停止：

     ## 缺少前置条件：GitHub CLI
     
     未安装 `gh` 命令。此技能需要 GitHub CLI 来执行仓库操作。
     
     从此处安装：https://cli.github.com/
     

   • GitHub CLI 身份验证： 运行 gh auth status。如果尚未通过身份验证，显示以下消息并停止：

     ## 缺少前置条件：GitHub CLI 身份验证
     
     GitHub CLI 尚未通过身份验证。请运行 `gh auth login` 完成身份验证，然后再使用此技能。
     

2. 解析选项：

   • 如果 $1 是 --no-draft，则创建可供审核的 PR
   • 否则（默认，即未提供参数时），创建草稿 PR

3. 获取当前分支并提取 JIRA ID：

   • 运行 git branch --show-current 获取当前分支名称
   • 通过匹配模式 [A-Z][A-Z0-9]+-[0-9]+ 提取 JIRA ID（例如：PROJ-123、AB-1、MYAPP-4567）
   • JIRA ID 可以出现在分支名称的任意位置（例如：fix/proj-123、feat/PROJ-123、PROJ-123-some-description）
   • 匹配时应忽略大小写；将提取的 ID 转换为大写，以便通过 JIRA API 查询
   • 如果未找到 JIRA ID，请继续执行，不要停止；推送后将采用无 JIRA 工单流程（见步骤 8）

4. 获取 JIRA 工单详情（仅当在步骤 3 中找到 JIRA ID 时）：

   • Atlassian CLI（acli）： 运行 acli auth status，检查 CLI 是否已安装并完成身份验证。
     • 如果找不到该命令，显示以下消息并停止：

       ## 缺少前置条件：Atlassian CLI
       
       未安装 `acli` 命令。分支名称中找到了 JIRA ID；请安装 CLI 以加载工单，或者重命名分支并移除 JIRA ID，以便在不关联 JIRA 的情况下创建 PR。
       
       使用以下命令安装：brew tap atlassian/acli && brew install acli
       

     • 如果命令因身份验证错误而失败，显示以下消息并停止：

       ## 缺少前置条件：Atlassian CLI 身份验证
       
       Atlassian CLI 尚未通过身份验证。请运行 `acli auth login` 完成身份验证，或修复分支／工单访问权限后再继续。
       

   • 使用 Atlassian CLI 根据 JIRA ID 检索 issue：

     acli jira workitem view <JIRA-ID> --fields summary,description,issuetype --json
     

   • 如果命令成功，则提取摘要、描述和issue 类型（Bug、Story、Task 等）；步骤 8 中将使用这些 JIRA 上下文
   • 如果命令失败（工单不存在、权限不足、网络错误等），请简要告知开发者，然后继续采用步骤 8 中的无 JIRA 工单流程（不要停止）。如果可以构造正确的浏览 URL，仍可在描述中选择性地使用原始 JIRA-ID 字符串创建链接；否则请省略

5. 确定基础分支：

   • 检查当前目录中是否存在 .agent 文件
   • 如果存在，请读取该文件，并查找 baseBranch=<value> 行以提取基础分支
   • 使用 AskUserQuestion 让开发者选择基础分支：
     • 如果在 .agent 中找到了基础分支：第一个选项为该分支，后缀为“（来自 .agent）”；如果 main 不同，则将 main 设为第二个选项
     • 如果不存在 .agent 文件，或没有 baseBranch 键：第一个选项为 main
     • 如果 PR 的目标基础分支不同，开发者可以通过“Other”选项输入其他分支名称

6. 推送分支：

   推送策略取决于 PR 是草稿还是已准备好供审查：

   如果创建草稿 PR（未使用 --no-draft 选项）：

   • 运行 git push -u origin <branch-name> --no-verify
   • 由于这是草稿 PR，可以跳过推送前检查；这些检查会在 CI 中运行，开发者会在将 PR 标记为已准备好供审查之前处理任何问题
   • 如果推送失败，显示错误并停止

   如果创建已准备好供审查的 PR（已传入 --no-draft）：

   • 运行 git push -u origin <branch-name>

   • 如果远程分支已是最新状态，则无需处理，继续下一步

   • 如果推送因推送前钩子失败（请查看错误输出中是否有 husky、pre-push、钩子脚本输出或交互式提示等迹象）：

     a) 提议使用 --no-verify 跳过钩子：

     • 使用 AskUserQuestion 询问开发者：

       推送被推送前钩子阻止。是否要使用 --no-verify 跳过该钩子？

     • 选项：是 — 使用 --no-verify 推送和否 — 解决推送前钩子问题

     b) 如果开发者选择使用 --no-verify：

     • 运行 git push -u origin <branch-name> --no-verify
     • 重要：无论是否传入 --no-draft，都必须将 PR 创建为草稿。由于跳过了推送前检查，PR 不应标记为已准备好供审查。
     • 如果这次推送也失败，显示错误并停止

     c) 如果开发者选择解决钩子问题：

     • 向开发者显示完整的推送前钩子输出，以便他们了解钩子要求执行什么操作或发生了什么错误
     • 如果钩子输出中包含提示或问题（例如“是否要继续？[y/n]”），使用 AskUserQuestion 向开发者提供选项，并根据他们的回答与钩子交互
     • 解决问题后，重新运行 git push -u origin <branch-name>
     • 如果推送仍然失败，显示错误并停止

   • 如果推送因其他原因（非推送前钩子）失败，显示错误并停止

7. 确定此 PR 修复或处理的问题：

   目标是列出仅由此 PR 实际修复或处理的事项，绝不能列出相关事项、依赖项或仅被顺带提及的事项。

   a) 从所有可用来源收集候选引用：

   • **分支名称：**步骤 3 中的任何 JIRA ID，以及任何 GitHub 问题编号线索——例如 issue-123、gh-123、以数字开头的部分（如 123-some-description）或 #123。
   • **此分支上的提交消息：**运行 git log <base-branch>..HEAD --pretty=%B，并扫描输出中的以下内容：
     • GitHub 问题引用：#NNN、GH-NNN 或跨仓库引用 owner/repo#NNN
     • 关闭关键词引用：Fixes #NNN、Closes #NNN、Resolves #NNN（不区分大小写）
     • 符合 [A-Z][A-Z0-9]+-[0-9]+ 格式的其他 JIRA 键
   • **PR 标题（如果来自 JIRA）：**JIRA 键已是候选项。 b）筛选此 PR 实际修复或处理的条目：
   • 仅在 PR 的更改解决或实现了某个条目时才纳入该引用。参考以下信号：
     • 分支名称中的主要 JIRA ID（来自步骤 3）以及分支名称中包含的任何 GitHub issue 编号 → 几乎总是由此 PR 处理；请纳入。
     • 此分支上的某条提交中，引用前带有关闭关键词（Fixes、Closes、Resolves）→ 请纳入。
     • 提交消息中单独出现的 #NNN → 仅当提交正文明确表明 PR 解决了该 issue 时才纳入；否则视为相关内容并排除。
     • 提交中提及但未明确表达“修复／处理”意图的其他 JIRA 键 → 作为相关背景排除。
   • 如果不确定某候选项是正在修复，还是仅仅相关，请使用 AskUserQuestion 询问开发者，并列出有歧义的候选项，每项提供 “此 PR 会修复它 — 纳入” 和 “仅相关 — 排除” 两个选项。如果没有有歧义的候选项，则完全跳过询问。
   • 对最终列表去重。

   c）为 PR 正文格式化引用：

   • JIRA 工单： [PROJ-123](https://<site>.atlassian.net/browse/PROJ-123)，后接工单摘要（如已知）（例如， — 添加批量导出）。使用在 acli 查询期间确认的同一 <site> 主机名。
   • GitHub issue（同一仓库）： 使用关闭关键词，以便 GitHub 在合并时自动关闭 — Fixes #123（bug 优先使用 Fixes，其他情况优先使用 Closes；两者都能自动关闭）。
   • GitHub issue（跨仓库）： Fixes owner/repo#123。

   将结果留给步骤 8 使用。如果筛选后的列表为空，则不会有 ## Fixes 部分。

8. 创建拉取请求：

   如果步骤 4 获取到了 JIRA 上下文（成功获取）：

   • 根据 issue 类型，使用提交前缀规范构建 PR 标题，后接从 JIRA 工单摘要中提炼的简洁说明：
     • Bug → fix: <summary>（例如，fix: resolve null pointer in user lookup）
     • 其他所有类型 → feat: <summary>（例如，feat: add bulk export for reports）
     • 摘要部分应使用小写、祈使语气，并保持简洁
   • 构建 PR 描述：
     • ## Summary — 根据 JIRA 工单描述撰写简短说明。
     • ## Fixes — 列出步骤 7 中所有已确认的引用，每行一条，以项目符号开头。始终将分支对应的 JIRA 工单作为第一条列出。仅当步骤 7 生成的列表为空时才完全省略该部分（有 JIRA 上下文时这种情况应很少见）。
   • 使用上述标题和正文运行 gh pr create（共享标志见下文） 如果没有 JIRA 上下文（分支中没有 JIRA ID，或第 4 步获取失败）：
   • 收集线索：分支名称（不含远程前缀）和最新提交主题（例如 git log -1 --pretty=%s）；也可以附上提交正文的第一行
   • 使用 AskUserQuestion，让开发者在运行 gh pr create 之前选择 PR 标题。至少提供三个不同的选项，例如：
     • 根据分支名称生成符合约定的标题（在 feat:、fix: 或 chore: 后使用祈使语气的小写短语——如果分支表明是修复 bug，则选择 fix:；否则优先选择 feat:，除非更改明确仅涉及杂项或文档，此时选择 chore:）
     • 根据最新提交主题拟定的标题（必要时调整为符合约定的格式）
     • 更短或措辞不同的标题
     • 另提供一个让开发者输入自定义标题的选项（如果工具支持）
   • 开发者选定标题后，编写 PR 描述：
     • ## Summary — 根据分支名称和近期提交消息简要说明。如果已知 JIRA ID，但无法加载工单，可以添加一句说明预期的工单 key。
     • ## Fixes — 将第 7 步确认的每个引用各列一行，以项目符号标出。如果第 7 步得到的列表为空，则完全省略此部分。
   • 使用选定的标题和正文运行 gh pr create

   通用的 gh pr create 行为：

   • 除非传入了 --no-draft，否则使用 --draft 标志。**例外：**如果第 6 步的推送使用了 --no-verify，则无论是否传入 --no-draft，都始终使用 --draft，并告知开发者：

     ⚠️ 由于跳过了推送前检查（--no-verify），PR 已创建为草稿。
     确认所有检查均已通过后，再将其标记为可供审查。
     

   • 使用第 5 步确定的分支，通过 --base <base-branch> 指定目标分支
   • 使用 HEREDOC 传入正文
   • 如果创建 PR 失败，显示错误并停止

9. 显示成功消息：

   显示包含所有相关信息的摘要。列出 ## Fixes 部分中的每个引用；如果省略了该部分，则注明“无”：

   ## PR Created
   
   - Fixes: PROJ-123, #45 (or "none")
   - Branch: my-branch → main
   - PR: https://github.com/org/repo/pull/42 (draft)
   - Title: <chosen title>