SuperAPI AI 工具集

pr

编程与开发

查看项目

更新于 10-23 16:18

技能介绍

PR 技能定义了 Pull Request 正文的写作格式,目标是让改动便于快速进行人工审查。它适用于撰写或重写 PR 正文的场景。

用途:为 PR 正文提供统一模板。撰写时跳过前言,保持文字简短;若项目存在 GLOSSARY.md,应使用其中的领域语言。

正文结构:

一、Summary(摘要)。选择能清楚表达关键点的最小可视化形式,通常只用一种,不要全部使用。可选形式包括:以伪代码描述逻辑或算法;以调用树描述运行时控制流;以浅层文件树描述文件职责或大范围重构;以 Mermaid 图描述交互或数据流;当要点是既有结构中发生的变化时使用 diff 草图,并让图形形态与主题匹配(调用树、文件树、状态流)。仅当大部分代码是新增,或省略上下文会隐藏归属关系或顺序时,才给出完整代码块。每个可视化图形应紧邻其所支撑的简短文字,只保留审查者需要的调用、文件、状态和边界。

二、Evidence(证据)。以改动前后的对比提供改动有效的具体证明。改动是视觉性的且环境允许截图时,截图最佳;其次是执行输出,即原先失败、现在通过的具体测试(写明测试名并以伪代码勾勒步骤),或改动前后的命令输出。没有证据时应说明未验证的内容及原因,而不是留空。添加截图时,应放入本次会话中针对该 PR 所构建内容拍摄的所有截图(来自 verify、浏览器测试运行目录或临时保存);排除其他工作及后来已修复失败的截图。上传前须检查每张截图,不得上传包含真实客户或员工个人身份信息(姓名、邮箱、电话)或本地数据库导出中密钥的截图;应改用伪造或种子数据重新截图,或先做脱敏。若没有截图,则跳过该部分,也不要仅为 PR 而补拍,Evidence 改用执行输出。GitHub 无法将本地文件附加到 PR 正文,因此需先上传。在仓库内运行该技能的脚本:bash <this skill's directory>/scripts/upload-screenshots.sh <pr-branch> <image>...。该脚本会把图片提交到孤立的 pr-assets 分支(保持 PR diff 干净)、推送,并为每张图打印一行 ,并固定到该提交。将这些行粘贴到 After: 下;旧行为截图粘贴到 Before: 下,每张配一行说明其内容。若推送失败,保留正文,在 Evidence 下列出本地路径并说明上传失败。

三、Merge Danger(合并风险)。说明门类型:双向门指回退并重新部署成本低;单向门则不是,例如破坏性迁移、数据回填、公共 API 或契约变更、已发送邮件、仍在处理中的任务所携带的队列负载结构。然后说明影响范围,即改动若出错可能触及的内容,需考虑所有消费方:其他模块、队列任务、API 客户端、布局、移动端、定时命令。

调用方需要的行(fixes #NNN,每个关闭工单一行)放在 Merge Danger 之后,保持原样。

适用场景:团队希望 PR 正文简洁、以证据为核心并明确合并风险时。限制:资料未提供该技能的安装方式、依赖环境、自动化程度、支持平台及收费信息,这些暂未提供。