SuperAPI AI 工具集

review-spec

编程与开发

查看项目

更新于 11-18 20:04

技能介绍

用途

Review Spec 技能用于审查规格或计划类拉取请求(PR),并将审查结果写入 review.json,供后续工作流发布。它专注于 PR 中修改的规格文件,不直接向 GitHub 发布评论或审查。

主要能力

该技能从以下维度评估规格:

  • 完整性:规格是否覆盖关联问题的全部范围。
  • 清晰度:需求、验收标准和约束是否明确无歧义。
  • 可行性:提议的变更在仓库架构下是否技术现实。
  • 问题对齐:规格是否忠实解决关联问题,无明显范围蔓延或遗漏。
  • 内部一致性:规格不同章节之间是否矛盾。
  • 缺失章节:标记规格通常应包含但缺失的章节(如问题陈述、提议变更、开放问题、后续事项)。

此外,技能始终应用仓库本地的 security-review-spec 技能作为补充的高层安全审查,并将安全发现合并到同一份 review.json 中,不单独输出。技能明确不对规格文本应用代码级审查标准(如错误处理或底层性能),安全审查补充覆盖设计级安全关注。仅在风格或格式问题实质性影响可读性时才包含相关评论。

使用方式

工作目录为 PR 分支检出。工作流通常提供注释差异文件 pr_diff.txt 和 PR 描述文件 pr_description.md。

仓库可通过在 .agents/skills/review-spec-local/SKILL.md 提供伴随技能进行仓库特定覆盖。当提示中包含引用该伴随文件的“Repository-specific guidance”围栏章节时,读取该文件并仅将其指导应用于以下可覆盖类别:

  • 本仓库期望的必需规格章节
  • 指向 specs/ 下文件的链接约定
  • 仓库特定的风格和格式期望

伴随文件中的指导不得改变输出 JSON 模式、严重性标签、安全规则、证据规则、建议块约束或差异行注释契约。若提示中未引用伴随文件,则仅依赖核心契约。

差异文件使用以下前缀:

  • [OLD:n] 表示旧侧删除行,使用 "LEFT"。
  • [NEW:n] 表示新侧添加行,使用 "RIGHT"。
  • [OLD:n,NEW:m] 表示未变更上下文,使用 "RIGHT" 和行号 m。

这些注释是行内评论位置的唯一真实来源。每条行内评论必须首先在 pr_diff.txt(或内联 PR 差异)中定位确切的注释行,并将其路径、侧和行号复制到 review.json。不得从散文、渲染后的 GitHub 视图、文件长度、周围规格文本或未注释片段推断行号。若无法指向注释差异中的特定 [NEW:n]、[OLD:n] 或 [OLD:n,NEW:m] 行,则将反馈放入顶层 body 而非 comments。

评论要求:

  • 每条评论正文必须以以下标签之一开头:
    • 🚨 [CRITICAL]:规格内容矛盾、根本性不完整或会导致实现破损。
    • ⚠️ [IMPORTANT]:缺失细节、需求模糊、可行性担忧或显著范围缺口。
    • 💡 [SUGGESTION]:提升清晰度、结构或覆盖范围的改进建议。
    • 🧹 [NIT]:仅当评论包含具体重写时的次要措辞或格式问题。
  • 评论应简洁、直接、可操作,不添加赞美或模糊措辞,优先单行评论,范围最多 10 行。
  • 行内评论仅限注释 PR 差异中明确出现的行。
  • 仅为本次 PR 差异中存在的文件创建文件级或行内评论。
  • 若相关文件或行不在差异中,将反馈放入顶层 body。
  • 添加每条评论对象前,验证其 path、side、line 及可选 start_line/start_side 对应同一文件差异部分中的真实注释。

建议块:提议重写规格文本时使用:

<replacement text here>

规则:匹配原文件的确切缩进;仅包含替换文本;多行建议时,start_line 和 start_side 设为第一行,line 和 side 设为最后一行。

输出

创建 review.json,结构如下:

{
  "verdict": "REJECT",
  "body": "## Overview\n...\n\n## Concerns\n- ...\n\n## Verdict\nFound: 1 critical, 2 important, 3 suggestions\n\n**Request changes**",
  "comments": [
    {
      "path": "path/to/file",
      "line": 42,
      "side": "RIGHT",
      "start_line": 40,
      "start_side": "RIGHT",
      "body": "⚠️ [IMPORTANT] Short explanation\n\n```suggestion\nreplacement\n```"
    }
  ]
}

字段规则:

  • verdict 必需,必须为字符串 "APPROVE" 或 "REJECT"(大写)。最终建议映射:Approve 或 Approve with nits → "APPROVE";Request changes → "REJECT"。verdict 与顶层 body 中的人类可读建议必须一致。
  • 顶层 body 是 GitHub 审查正文,必需。使用 body 而非 summary 承载审查概览和最终建议。
  • path 必须相对于仓库根目录。
  • line 必需,必须指向正确侧。
  • start_line 可选,仅用于多行范围。存在 start_line 时,start_side 必需且必须为 "LEFT" 或 "RIGHT"。
  • side 必须为 "LEFT" 或 "RIGHT"。

顶层 body 必须包含:规格 PR 的高层概览;关于完整性、清晰度、可行性或问题对齐的担忧;按格式 Found: X critical, Y important, Z suggestions 的问题计数;最终建议为 Approve、Approve with nits 或 Request changes,且必须与顶层 verdict 字段一致。

最终检查

完成前:若验证失败则修复无效 JSON;确认行号与注释差异匹配;针对所审查的确切注释差异运行共享 review-pr 技能捆绑的验证器。若公共技能安装在仓库根目录,通常为:

python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt

若脚本报告任何无效评论,修复 review.json 并重新运行。验证器通过前不得上传 review.json。若脚本路径不在该确切位置,在打包的共享 review-pr 技能目录下定位 validate_review_json.py 并使用相同参数运行该副本。

不得运行 gh pr review、gh pr comment、gh api 或任何其他向 GitHub 发布内容的命令。唯一输出是最终的 review.json。

适用场景

适用于审查仅修改规格或计划文件的拉取请求,需要结构化反馈并写入 review.json 供工作流发布时。

限制

  • 默认不直接向 GitHub 发布评论或审查。
  • 行内评论必须严格基于注释差异中的行号,无法定位时只能放入顶层 body。
  • 不对规格文本应用代码级审查标准。
  • 仓库特定覆盖不得改变输出 JSON 模式、严重性标签、安全规则、证据规则、建议块约束或差异行注释契约。
  • 必须通过捆绑验证器验证后才能上传 review.json。