SuperAPI AI 工具集

review-code

编程与开发

查看项目

更新于 10-20 12:34

技能介绍

用途

review-code 是一个代码审查技能,针对单个 diff、分支或 PR 提供正确性与安全性门禁。它只报告问题并给出建议性结论,不修改文件、不创建 PR、不执行任何变更或部署,因此无需确认即可运行。

两个审查维度

技能并行运行两条轴:

  • Standards(标准)轴:检查正确性、安全性与仓库卫生。
  • Spec(规格)轴:检查改动是否符合原始需求,防止“通过全部规范但实现了错误功能”或“满足需求但破坏项目约定”的情况被掩盖。两条轴的发现分别列在 ## Standards 和 ## Spec 下,不合并、不重新排序。

规格轴步骤

  1. 确定固定基准点:用户指定的提交 SHA、分支、标签、main 或 HEAD~5;未指定时需询问。确认基准可解析且 git diff <fixed-point>...HEAD 非空。
  2. 按顺序识别规格来源:提交信息中的 issue 引用(如 #123、Closes #45,通过 gh 获取);用户作为参数传入的路径;docs/、specs/ 下或与分支匹配的 issue 正文中的规格文件。找不到时需询问;若确无规格,则跳过规格轴并报告“no spec available”。
  3. 报告规格发现:规格要求但缺失或部分实现的需求;未被要求的行为(范围蔓延);看似实现但实际错误的需求。每条发现需引用规格原文。遗漏必需行为属 Block Merge;范围蔓延属 Request Changes(用户已接受者除外)。

标准轴关键检查项

  • 安全与数据隔离:多租户时所有查询按租户/组织过滤;过滤软删除记录;无跨租户访问;受保护路由有鉴权守卫;每个路由的鉴权姿态是有意为之;输入经 DTO/schema 校验;不提交或记录密钥、令牌与凭据。
  • TypeScript:禁止 any 类型,应定义接口或命名类型;禁止无类型守卫的裸 unknown;禁止无解释注释的 as X 断言;接口/props 放在专用文件而非组件或服务文件内;所有函数标注返回类型;禁止 console.log,应使用项目日志器;@ts-ignore/@ts-expect-error 需配解释注释。
  • 模式一致性:遵循现有代码库模式(标记前需核实 3 个以上真实示例);优先使用路径别名而非相对导入。
  • 数据库:适用时所有查询带租户/组织过滤与软删除过滤;大文档使用投影;为查询模式建立索引;diff 中无可见的 N+1 查询;失败时可能留下半写状态的连续 await db.update() 调用须包裹事务或合并为单次原子写入。
  • 错误处理:存在 try/catch;使用框架专用异常而非通用 Error;错误经日志服务记录;返回客户端的消息保持通用,不暴露内部细节。
  • 测试:单元测试存在且通过;覆盖所有公共方法;覆盖错误场景;断言行为而非仅断言代码可运行(无空洞快照测试)。
  • 前端:useEffect 中异步调用需清理(AbortController);处理加载与错误状态;交互元素使用语义化 HTML 并带 ARIA 标签。
  • API:使用恰当的 HTTP 状态码;请求/响应使用 DTO;项目采用时添加 API 文档装饰器(如 @ApiOperation / @ApiResponse);不向 API 消费者泄漏内部堆栈信息。
  • 开发体验回归:环境变量重命名或新增是否更新 .env.example / .env.template 并加以说明;密钥读取路径变更是否更新运行手册;端口或网络映射变更是否更新 README/安装文档及依赖配置;新增强制性安装脚本(迁移、种子、一次性引导)是否在 PR 描述或安装指南中记录;构建流程变更(新增必需构建步骤、输出目录改变、pre/post 脚本)是否有明确迁移说明。未提前声明的开发体验回归属 Block Merge;已记录但文档位置不当属 Request Changes。
  • 功能开关泄漏:明确泄漏(PR 描述称功能位于开关后,但检查缺失或只应用于 UI 而未覆盖 API 处理程序);隐蔽泄漏(正常路径有检查,但错误处理器、后台任务或管理员路径缺失);始终为真的常量(如 const ENABLE_NEW_CHECKOUT = true)代替真实开关评估;引入开关但无清理计划(缺关联 issue 或 TODO,命名应体现预期生命周期);开关已定义但发布比例/定向规则缺失或默认 100%。暴露未发布功能给所有用户的开关泄漏属合并阻断项;缺少清理工单属 Request Changes。

批准标准

  • Block Merge:存在安全问题;缺少必需的多租户过滤;无类型守卫的 any 或裸 unknown;测试失败或新公共方法完全无测试;构建失败;功能开关泄漏暴露未发布功能;未声明的开发体验回归;无事务的非原子多步数据库变更。
  • Request Changes:环境变量新增或安装脚本需求缺文档;diff 中明显可见的性能问题(N+1、缺索引);模式违规(已引入 UI 库的文件中出现原始 HTML);引入功能开关但无清理 issue/TODO;仅断言执行而非行为的空洞测试。
  • Approve:全部安全检查通过;测试通过且断言真实行为;遵循代码库模式;开发体验影响已记录;功能开关有清理计划;规格轴通过或因无规格而跳过。

边界与限制

仅适用于单个 diff 或 PR,不重复讨论结构性维度(模块内聚、抽象层级、循环依赖、死代码引入、API 表面膨胀、架构契合度),这些问题应交给结构性审查。可指出 diff 中明显的安全问题,但不做完整安全审计(OWASP 清单、依赖 CVE、时序攻击、提权路径),应交给专门的安全审计。若发现涉及模块深度或接缝位置,建议进行代码库设计审查。不得从审查请求推断合并或清空队列等操作。此外,若仓库已有针对技术栈规则(包管理器、CSS 框架、框架版本、UI 库)的自动化合规检查,不重复标记其已覆盖的问题。

输入与输出

  • 输入:一个待审查的 diff、分支或 PR;通过只读 git/gh 命令收集范围。
  • 输出:按 Block Merge / Request Changes / Approve 分桶的发现列表,每条含文件、行号与一句话理由;另附独立的规格报告(缺失需求、范围蔓延、实现错误)。同时建议在发现超出本门禁范围时进行结构性审查、安全审查或代码库设计审查(如已安装上游 pstack 工作流)。
  • 外部副作用:仅只读的 git 与 gh 调用,无变更、无部署。