SuperAPI AI 工具集

synthesis-code-audit

编程与开发

查看项目

更新于 10-22 16:14

技能介绍

Synthesis Code Audit 是一个代码审计技能,用于对一次代码差异(diff)做系统性的质量度量。它明确区分“审计”和“评审”:审计输出跨十个正交维度的评分报告,指出质量问题所在;是否合并由评审者决定(相关评审工作见 synthesis-pr-review)。

绑定规则

  • 只度量,不决策:审计给 diff 打分,合并由评审者决定。当其他工作流(preflight、PR review)调用审计时,把发现返回给该工作流。
  • 始终对比新的基线引用,而不是过期的本地基线:过期基线会同时造成误报和漏报。
  • 完整阅读每个变更文件,而不仅是 diff 片段;文件上下文能说明改动是否合理。
  • 向评审者提供完整需求(冻结的产物范围、用户结果、验收标准、排除项、决策),但不预设结论;对有误的前提用证据质疑,修订意见交给决策负责人。
  • 评定变更行为及其受影响的消费方。即使阻塞性缺陷的代码行早于本次 diff,它仍是阻塞项;无关发现单独记录,绝不把未审查代码称为干净。
  • 显式应用项目规范,包括更强的“顺手修复”规则;不对本次 diff 未改动的代码挑风格小毛病。
  • 部分覆盖记为 Incomplete,绝不为 Clean。跟踪已审查与未审查路径;UNKNOWN 维度或未审查路径不能满足就绪门槛。
  • 复用既有发现时,须绑定到实际 diff、所需消费方与证据输入;材料变化会重新打开相关判断。

参考文件

  • references/dimensions.md:十个维度各自检查什么,评分任一维度前先阅读。
  • references/principles-and-rules.md:本技能与 pr-review、codebase-review 的关系定位,以及四条原则和规则的完整文本。规则适用范围不清或在技能间选择时阅读。
  • references/coverage-map.md:1.1.0 版文本各部分现所在位置。

Diff 范围检测

确定审计对象:

  • 存在未提交改动:对照 HEAD 审计已暂存和未暂存的改动。
  • 分支有领先基线的提交:审计从基线到 HEAD 的范围。
  • 无可比较内容:报告并停止。

大型 diff(40 个以上文件):按后果优先调查,包括影响执行或供应链完整性的配置、生成资源和锁文件;把冻结范围划分为有界评审任务,设一名集成负责人;显式跟踪已审查与未审查路径。部分覆盖产生不完整审计,绝不给出无条件的 Clean 结论;须在打包通过前完成必要覆盖。

十维框架

对每个维度评估变更代码,并给出以下之一:

  • PASS:无问题,或仅有琐碎风格偏好
  • WARNING:值得关注但不阻塞发布(缺少边界测试、轻微不一致、可改进的模式)
  • FAIL:具体缺陷、安全漏洞、规范违规或缺失覆盖,应在合并前修复
  • UNKNOWN:无法从现有证据或已完成的评审覆盖中建立所需判断

十个维度(详见 references/dimensions.md):

  1. 项目规范合规
  2. 代码复用——优先使用现有实现
  3. 与现有模式的一致性
  4. 安全
  5. 可扩展性与企业就绪
  6. 未来适应性(不过度工程)
  7. 代码质量
  8. 测试覆盖
  9. 文档与注释
  10. 清理

报告方式

以表格呈现发现,列为 #、维度、结果、备注,逐行列出十个维度及结果与细节。表格下方给出一行结论:

  • “Clean”:完整声明范围内所有适用维度 PASS,并附带精确的源码/基线绑定
  • “Has warnings”:存在一个或多个 WARNING,无 FAIL
  • “Has blockers”:存在一个或多个 FAIL
  • “Incomplete”:任一必需维度或声明范围的一部分为 UNKNOWN 或未审查;不能满足就绪门槛

随后列出可执行的发现,附文件与行号引用;对每个问题说明错在哪里以及如何修复。

PR 评审模式(交叉比对)

作为 PR 评审工作流的一部分被调用时,可获得既有评审评论作为上下文(包含评审者、文件路径、行号、评论内容的条目列表)。完成全部十个维度后,逐条交叉比对:

  • 文件+行号匹配:同一文件 ±10 行内是否有既有评论?
  • 语义匹配:既有评论是否提出同一类问题(例如都在指出缺少鉴权、都在指出重复)?

为每条发现标注:

  • [Already noted by @reviewer]:同一位置存在相同或非常相似的关注
  • [Related to @reviewer's comment on file:line]:相似关注,位置不同
  • [New finding]:未被任何既有评审者覆盖

最后给出交叉比对摘要:新发现与已被覆盖发现的数量统计。该模式不改变检查哪些维度或如何评估问题,只增加重叠标注,让评审者知道自己的评审在何处增加新价值、在何处确认已有反馈。