SuperAPI AI 工具集

issue-to-merge

编程与开发

查看项目

更新于 11-12 23:16

技能介绍

issue-to-merge 是一个面向 AI 编码代理的开发流程技能,用于把一件具体工作从 Issue 阶段持续推进到合并后的拉取请求(PR),避免在各阶段之间反复停顿。它的重点是定义阶段的先后顺序、阶段之间交接的产物以及中断后的恢复方式;每个阶段的具体操作由相应专用技能承担。除“项目检查命令”外,流程只依赖 git 与 gh,不绑定特定语言或技术栈。

用途

该技能适用于需要按固定流程完成一项开发任务、并希望减少人工确认和重复询问的场景。它规定从 Issue 到合并的完整阶段链,并明确在什么情况下才允许停下来。流程本身不负责具体实现细节,而是协调若干技能:issue-create、goal-prompt-crafter、worktree-workflow、pr-autoloop、pr-maintainer,以及 git-workflow 规则。

主要流程

流程共分七个阶段。第一阶段创建 Issue 或选择已有 Issue,产出 Issue 编号与完成条件。第二阶段把完成条件转成带停止条件的目标提示,使用 goal-prompt-crafter,产出包含检查命令与上限的完成条件文。第三阶段创建专用 worktree 与分支,使用 worktree-workflow,产出 worktree 路径与分支名。第四阶段进行实现并通过检查命令,依据项目 rules,产出检查输出与 commit。第五阶段推送并创建 ready 状态的 PR,使用 worktree-workflow 的 Phase 5,产出 PR 编号。第六阶段应对 CI 与评审,在安全时执行 squash merge,使用 pr-autoloop 或 pr-maintainer,产出 merged、escalated 或 timeout。第七阶段清理 worktree 与分支,使用 worktree-workflow 的 Phase 6,产出最终报告。

停顿条件

阶段之间不会询问“继续吗”。只在以下情况停止:完成条件无法确定,涉及用户意图、范围或价值判断;因认证、权限或网络问题无法推进,需附真实错误报告;pr-maintainer 达到 escalate 或 timeout;用户明确要求“停在 PR 之前”或“保持 draft”。此外,对于仓库规定不需要 worktree 与 PR 的变更,例如仅文档变更或开发工具的 chore(git-workflow 的例外条款),不使用该流程。

检查命令的确定

“通过测试、lint 与类型检查”的具体内容因项目而异。技能要求按顺序查找并采用第一个找到的命令:AGENTS.md、CLAUDE.md 或 README 中写明的检查命令;CI 实际执行的命令(.github/workflows/*.yml 中的 run:);任务运行器定义,如 package.json 的 scripts(check、test、lint、typecheck)、Makefile 或 justfile 的 target、pyproject.toml 的工具配置。若都不存在,则在报告中注明没有检查,并自行构造最小可运行示例验证改动行为并保留输出;增加检查机制应另开 Issue。检查不通过时不得创建 PR,也不得通过放宽配置、skip 或抑制注释来让检查通过。

各阶段要点

从已有 Issue 开始时,需确认正文包含完成条件,缺失则先在 Issue 中补充评论再继续。单次执行即可完成的小任务可直接使用 Issue 完成条件;交给多轮自主执行时,需用 goal-prompt-crafter 增加上限(轮数、时间)与不变量(不可触碰范围)。分支名应包含 Issue 编号,如 fix/issue-<n> 或 feat/issue-<n>。commit 消息或 PR 正文中写 Closes #<n>,使合并时自动关闭 Issue。PR 不设为 draft,正文需写明改动内容、检查命令及结果、尚未验证的事项。无评审机器人或无 CI 的仓库处理方式由 pr-maintainer 的 Review gate 决定。清理前先确认已合并,并确认 Issue 已关闭。

中断与恢复

若会话中断或由另一代理接手,不应依赖记忆或上次报告,而应根据残留产物判断所处阶段,避免重做已完成阶段。可使用 gh issue view 检查 Issue 是否存在且未关闭;git worktree list --porcelain 检查 worktree;git -C "$WORKTREE" status --short 与 git log 检查未提交或已提交改动;git ls-remote --heads origin "$BRANCH" 检查是否已推送;gh pr list --head "$BRANCH" --state all --json number,state,isDraft,mergedAt,url 检查 PR 状态。根据观察结果决定回到第 1、3、4、5、6 或 7 阶段;若 Issue 与 PR 均已完成且 worktree 已清理,则只输出最终报告。对外操作如 push、创建 PR、merge、评论,在重试前须确认是否已执行,避免重复创建 PR 或评论。

最终报告

报告应包含 Issue 与 PR 的 URL、最后观察到的状态(merged、escalated、timeout 或停下的阶段与原因)、执行的检查命令及结果,以及尚未验证的事项。

适用场景与限制

适用于需要以 Issue 为起点、经 worktree 隔离开发、创建 PR、处理 CI 与评审并最终合并的单件开发工作。它不适用于仓库规定无需 worktree 与 PR 的变更,不负责替代各阶段专用技能的具体操作,也不应绕过检查命令。资料未提供更多关于依赖环境、支持平台或具体实现语言的限制说明。