SuperAPI AI 工具集

contribution-review

编程与开发

查看项目

更新于 10-16 06:59

技能介绍

Contribution Review(worker skill)用于对 Drupal 贡献进行诚实的验证。构建者往往带有会话叙事——即每个选择为何作出的来龙去脉——因此难以客观审查自己的工作。该技能派出全新上下文的智能体,这些智能体不携带任何上述叙事。

用途

该技能为 /drupal-ai-contrib:review 提供支撑。知识层通过 dev-guides-navigator 加载:drupal/contributing-with-ai/ai-code-review-checklist、drupal/contributing-with-ai/human-review-requirements、drupal/contributing-with-ai/security-considerations、drupal/contributing-with-ai/issue-review-guidelines。

主要能力与使用方式

  1. 建立审查输入

在不添加主观评论的前提下收集:范围契约(目标/预期结果/成功标准/非目标);待审查的 diff,用 git diff <target-branch>...<issue-fork-branch> 显式生成(三点形式只显示该贡献自身的改动),审查智能体必须收到真实、非空的 diff,若 git diff 无输出则说明无可审查内容,报告并停止;issue 及其验收标准;verify-staleness 状态,运行 ${CLAUDE_PLUGIN_ROOT}/scripts/reverify-list.sh,若输出任何路径,则在报告中注明这些文件自上次 verify 通过后已变更,使审查者知道门禁证据可能未覆盖当前 diff。

  1. 派出全新上下文审查者

使用 Task 工具调用 drupal-ai-contrib:fresh-context-reviewer 智能体,向它传递 diff、范围契约和 issue,但不传构建叙事。该智能体从以下方面审查:范围(改动是否恰好交付契约内容、无超出;过度交付也是一项发现,因为这是维护者没有要求的审查负担);标准(Drupal 编码规范、Drupal + PHP 最佳实践);安全(AI 特有的风险,见 security-considerations 开发指南);AI 政策(AI 使用是否超过“significant portion”阈值并已披露)。对于大型改动,可派出多个审查智能体以获得视角多样性。对于安全关键改动,§3 的安全子审查是强制性的——必须是显式的 Task 调用并将其输出记录到产物中,而非可选的附带项。

互补的安全层:security-guidance 插件与本技能覆盖不同范围,二者并不竞争。security-guidance 在 Claude 自身的会话内编辑上自动运行——确定性的逐次编辑字符串匹配(不涉及模型),加上在回合结束和提交时对 diff 进行全新上下文、聚焦安全的审查。本处的 fresh-context-reviewer 智能体是按贡献触发、显式派出的,依据范围、标准、安全与 AI 政策审查整个贡献 diff。两者都应运行:会话内指导在 Claude 编写时捕获漏洞,贡献审查捕获残留在 diff 中的问题;二者互不替代,也都不阻断,均以指令形式呈现发现。会话内层可用 /plugin install security-guidance@claude-plugins-official 安装。

  1. 安全关键贡献——强制的 Task 调用

当 issue 带安全标签,或 diff 触及以下任一项时,视为安全关键贡献:权限/访问回调、实体或字段访问、#access 表单键、用户输入清理或输出转义、基于输入构建的 SQL/数据库查询、文件或路径处理,或其他与 XSS/注入相邻的代码。以上均不适用时跳过此步骤。适用时,安全子审查不是建议性的——用 Task 工具显式派出(子智能体的隔离上下文是证据,而非本技能的叙述):对 diff 运行 /code-quality-tools:security,和/或 code-paper-test 的 paper-test 技能,传入 diff 以及 security-considerations 开发指南中的安全检查清单。在本技能返回结论前,将该 Task 返回的发现追加到审查产物(§6)。安全关键审查只有在该子审查输出被记录到产物中时才算完成——绝不能仅凭声称“已运行”。

  1. 委托理念审查

将 SOLID/DRY/架构审查交给 code-quality-tools。本技能负责诚实验证关注点;code-quality-tools 负责理念审查。不要在此重复实现。

  1. 综合——只给出诚实结论

收集各智能体的结论。按严重程度(blocker/should-fix/suggestion)报告发现,每项都关联到 file:line 和具体修复建议。结论以智能体的为准——绝不因为构建者解释了意图就软化它。若审查者之间存在分歧,应呈现分歧,不要掩盖。

  1. 报告

输出发现报告:每项发现的严重程度、位置、修复建议。对于安全关键贡献,§3 的子审查发现必须已出现在此处。明确说明该贡献是准备好提交,还是需要再进行一轮开发。当工作尚未就绪时,诚实的“未就绪”就是正确输出。

生成报告后,记录一次针对当前代码树的审查已运行:${CLAUDE_PLUGIN_ROOT}/scripts/review-mark.sh --set。submit 读取该标记以检测本次审查后被编辑的贡献文件(review-staleness 门禁,与 verify 的 reverify 台账平行)。修复后重新运行 review 会重新打标记。

示例

示例 1:捕获过度交付。触发:/drupal-ai-contrib:review。操作:fresh-context-reviewer 智能体将 diff 与范围契约比较,发现对无关类的一次重构——超出契约的非目标。结果:记录为 blocker——维护者没有要求的审查负担。

示例 2:安全关键改动。触发:对触及访问控制(#access、实体访问回调)的 diff 运行 /drupal-ai-contrib:review。操作:标记为安全关键;派出 fresh-context 审查者,并对 diff 执行 §3 的 Task 子审查(/code-quality-tools:security + code-paper-test)。将子审查发现追加到产物;用 review-mark.sh --set 打标记。结果:一份综合报告,其中记录了安全子审查(而不仅是声称已运行);审查者分歧被呈现而非隐藏。

适用场景与限制

适用于 Drupal 贡献在提交前的审查,尤其是需要判断范围、规范、安全与 AI 使用披露是否符合要求的场合。无 diff 可审查时应报告并停止;不存在范围契约时应指出缺口,说明范围审查需要契约,请求提供或标注为无法评估。构建者对某项发现提出异议时,智能体的结论仍然成立,不得因解释了意图而软化。审查者意见不一致时应在报告中呈现,不要掩盖。