SuperAPI AI 工具集

pull-requests

编程与开发

查看项目

更新于 10-16 22:15

技能介绍

用途

本技能提供在代码仓库中创建和管理 Pull Request(PR)的规范与操作指南,适用于使用 coder/xum 工作流的开发场景。其目标是统一 PR 的署名、生命周期、审查与验证流程,减少协作摩擦。

主要能力

  • 署名页脚规范:公开工作(issue/PR/commit)必须在标题中使用 🤖,并在正文中包含指定页脚。AI 生成的 PR 需通过 bash 检查 $XUM_MODEL_STRING、$XUM_THINKING_LEVEL、$XUM_COSTS_USD 并填入页脚;GitHub Actions 工作流产生的非 AI 提交和 PR 使用另一套页脚格式。
  • 生命周期规则:提交 PR 前确保分支名反映工作内容且基础分支正确;PR 始终以 squash 方式合并到 main;复用已有 PR,未经指示不得关闭或重建;小幅更新可强制推送,否则新增提交以保留时间线;保持 PR 与最新提交同步;更新 PR 时标题和正文需描述针对基础分支的完整 diff;禁止自行启用自动合并或合并到 main,必须由用户显式合并。
  • CI 与验证:优先本地验证(如 make static-check 或针对性测试子集),因为 CI 等待可能超过 10 分钟;默认最后一步使用 ./scripts/wait_pr_ready.sh <pr_number>,它会同时轮询 Codex、CI 检查以及(按需)coder-agents-review 门禁,并在首个终态失败时快速失败;调试特定门禁时可直接使用 ./scripts/wait_pr_checks.sh <pr_number> 和 ./scripts/wait_pr_codex.sh <pr_number>;修复 CI 问题时先在本地复现并通过,再使用 wait_pr_ready.sh。
  • 状态解码:提供 mergeable 与 mergeStateStatus 字段的取值含义表,例如 MERGEABLE 表示无冲突,CONFLICTING 表示需解决冲突,CLEAN 表示可合并,BLOCKED 表示等待 CI,BEHIND 表示需 rebase,DIRTY 表示有冲突。若落后,执行 git fetch origin && git rebase origin/main && git push --force-with-lease。
  • Codex 审查工作流:使用 gh 发布多行评论时,不要依赖 --body 字符串中的 \n 转义,应使用 --body-file - 配合 heredoc 保留真实换行。提供脚本:./scripts/check_codex_comments.sh <pr_number> 列出未解决的 Codex 评论及线程 ID;./scripts/resolve_pr_comment.sh <thread_id> 解决审查线程;./scripts/wait_pr_codex.sh <pr_number> 等待 Codex 状态;./scripts/wait_pr_ready.sh <pr_number> 统一轮询 Codex 与 CI。PR 就绪定义、审查循环及提前停止情形见 AGENTS.md 的 PR Workflow 部分。
  • Coder Agents 审查工作流:当使用 /coder-agents-review 或该机器人参与时,需逐条处理实质性发现,在解决线程前回复机器人(可内联或通过 PR 评论列出发现 ID 与回应),解决已处理的审查线程,重新请求审查,并运行 ./scripts/wait_pr_ready.sh <pr_number>。不得静默解决 coder-agents-review 线程,否则机器人会将已解决但未回复的发现视为阻塞审查轮次。
  • PR 标题约定:标题前缀包括 perf|refactor|fix|feat|ci|tests|bench,示例为 🤖 fix: handle workspace rename edge cases;仅测试变更使用 tests:,CI 配置变更使用 ci:。
  • PR 正文结构:推荐包含摘要(单段执行摘要)、背景(变更原因、解决的问题、相关提交/issue/PR)、实现(新颖或不清晰的实现方式,保持高层与架构视角)、验证(证明变更有效的步骤,避免样板化描述,仅包含新颖且针对变更的步骤)、风险(涉及复杂逻辑的 PR 必须评估回归风险,说明严重程度与受影响产品区域)、痛点(仅用于经历多轮迭代的非平凡变更,说明拖慢规划、实现或验证的代码库或环境问题)。
  • PR 正文编辑:始终使用 mktemp 创建唯一临时文件,例如 PR_BODY=$(mktemp /tmp/pr-XXXXXX.md),用文件编辑工具构建正文后执行 gh pr edit <num> --body-file "$PR_BODY" 并删除临时文件;更新正文时可考虑将不再重要的信息折叠。
  • 日常维护:代码推送到远程后(即使尚未创建 PR),在响应前提交并推送所有变更以便用户可见;工作分支上的提交供自己理解变更,不必遵循仓库约定,因为 PR 正文和标题会成为提交主题和正文;生成压缩摘要时需包含是否已打开 PR 以及远程的一般状态(如 CI 检查、已知审查、分叉情况)。

使用方式

该技能以指南文档形式提供,通过阅读并遵循其中的规则与脚本命令来管理 PR。涉及的具体脚本包括 wait_pr_ready.sh、wait_pr_checks.sh、wait_pr_codex.sh、check_codex_comments.sh、resolve_pr_comment.sh 等,均以命令行方式调用。

适用场景

适用于使用 coder/xum 工作流的代码仓库中,由 AI 或自动化流程创建、更新、审查和合并 PR 的场景,尤其涉及 Codex 审查与 Coder Agents 审查的协作流程。

限制

本技能为仓库特定的 PR 管理规范,不涉及具体编程语言或框架的功能实现。部分流程依赖仓库中存在的脚本和 AGENTS.md 文件,若缺失则相关步骤无法执行。关于收费、价格、平台支持范围等信息,资料中暂未提供。