SuperAPI AI 工具集

create-pr-with-evidence

编程与开发

查看项目

更新于 10-29 14:22

技能介绍

用途

该技能用于从准备发布的具体提交创建可审查的拉取请求(PR)。它要求 PR 正文解释改动的系统,而不仅仅是列出修改的文件,并辅以可验证的变更上下文、架构证据和前后对比的视觉证据。

主要能力

  • 遵循仓库规则:优先读取 AGENTS.md、CLAUDE.md、CONTRIBUTING.md 和 PR 模板,使用仓库规定的标题、分支名、提交格式和必需检查。
  • 工作流:检查仓库指令、状态、分支、远程和目标分支;计算合并基线;检测堆叠工作并区分继承变更与本 PR 变更;审查完整 diff 并追踪到入口点、调用方、状态所有者、持久化和外部边界;分类 PR 类型;运行与改动面匹配的检查;若涉及用户可见 UI,则执行视觉证据流程;根据 PR 模板撰写正文;通过 GitHub 或 gh 工作流发布;创建 PR 后验证标题、目标分支、源分支、正文、图表、表格和图片 Markdown;获取审查线程、评论和检查状态,修复确认的错误并推送修正。
  • 上下文证据:记录仓库、目标分支、头分支、合并基线和检查的提交范围;对于堆叠 PR,识别父 PR 或分支;区分运行时代码与生成文件、锁文件、快照和迁移;将改动文件追踪到真实模块边界;用文件路径或符号支持架构声明;不暴露令牌、密钥、完整用户记录或 webhook 负载。
  • PR 正文契约:每份 PR 需包含简洁的 ## Summary 和 ## Verification 部分;当 diff 涉及多个模块、职责或所有权边界时添加 ## Change map;当图表能更快或更准确地解释变更时添加 ## Architecture and behavior;当变更具有有意义的失败模式、不变量、迁移或外部影响时添加 ## Boundaries and risks;小范围本地 PR 保持正文简洁,不为了满足模板而添加表格或图表。
  • 行为证据工作流:当 diff 改变运行时行为时,列出变更的行为场景(稳定 ID 和短标题),包括状态转换、异步顺序、重试、取消、事件路由、持久化、清理和失败恢复路径;为每个场景选择最小的证据形式(文字、模块流、序列图或状态图);对于改变流程或状态模型的修复,提供可比较的前后图表;覆盖所有列出的场景或在 PR 正文中注明未验证。
  • 边界与验证映射:选择与 diff 匹配的风险,从输入和副作用开始,再检查失败、重试、重复投递、并发、顺序、授权、清理、迁移和回滚;将每个高风险不变量映射到现有测试、新测试、CI 检查或未验证的运行时条件;使用表格呈现多个有意义的边缘情况或不变量。
  • 视觉证据工作流:将 diff 追踪到每个受影响的页面、窗口、对话框、路由、响应式状态、主题和区域设置;为每个状态记录稳定 ID 和人类可读标题;优先使用仓库拥有的截图场景、组件故事、路由和附近测试;使用记录的合并基线创建分离的临时工作树;在合并基线和拟议 HEAD 上以相同场景定义、视口、区域设置、主题、夹具数据和就绪条件捕获相同场景;将截图写入 gitignored 或临时目录,每个修订一个目录,跨修订保持捕获名称相同;检查每张图片,拒绝空白、加载中、错误、权限、引导或不稳定的捕获;按稳定 ID 配对结果并保留交接记录;在撰写 PR 时将每张本地图片上传为 GitHub 用户资产;将所有配对放在 ## Visual changes 下,图片行放在组件或页面名称行之前;验证每个用户资产 URL 与预期捕获匹配;上传成功后移除临时工作树。
  • 视觉证据契约:本地捕获视为临时交接数据,GitHub 拥有上传副本;仓库必须不包含受跟踪的 PR 专用图片;如果 GitHub 资产上传不可用,在创建不完整的 UI PR 之前停止,并报告 PR 所需的本地图片路径。

使用方式

当用户要求打开、准备或创建拉取请求时使用该技能。技能会引导完成检查仓库规则、审查 diff、运行检查、生成证据、撰写 PR 正文、发布 PR 并验证的完整流程。若仓库有自定义技能或脚本用于截图、上传或检查,应优先使用它们。

适用场景

  • 需要创建包含可验证变更上下文和架构证据的 PR。
  • 变更涉及用户可见 UI,需要前后对比视觉证据。
  • 变更涉及多个模块、职责或所有权边界,需要变更映射。
  • 变更具有有意义的失败模式、不变量、迁移或外部影响,需要边界与风险分析。
  • 堆叠 PR 场景,需要区分继承变更与本 PR 变更。

限制

  • 必须遵循仓库指令,仓库规则优先于该技能。
  • 若 GitHub 资产上传不可用,不能创建不完整的 UI PR,需报告本地图片路径。
  • 不得在 PR 中暴露令牌、密钥、完整用户记录或 webhook 负载。
  • 无法证明的业务意图需标记为假设或开放问题。
  • 没有证据时不得写“安全”“已修复”或“向后兼容”。