SuperAPI AI 工具集

diff-explainer

编程与开发

查看项目

更新于 11-08 05:20

技能介绍

Diff Explainer 是一个面向代码评审的讲解文档生成技能,来源为 thoughtbot/rails-consultant。它的目标不是复述改了什么,而是回答“为什么这样改”:为什么选这个方案而不是更显而易见的那个、试过什么失败了、作者担心什么、刻意没做什么。读者被设定为时间有限、可能不熟悉该技术栈的资深开发者。

用途与定位 技能用于把当前分支的变更整理成一份可分享的 HTML 走查页。它强调 diff 只能显示接缝,讲不清动机和取舍,因此写作者需要补充决策、风险、权衡与放弃的备选方案。

主要能力

  1. 定位比较基线:默认将当前分支与其基线比较,从合并基点开始 diff,避免混入他人提交。基线查找顺序为上游分支、refs/remotes/origin/HEAD、refs/heads/main、refs/heads/master。
  2. 判断改动规模:先运行 git diff --stat 和 git log --oneline,再看完整 diff,避免一次性把过大的 diff 拉入上下文。
  3. 支持多种输入:无参数时比较当前分支;传入参数时先按修订解析,否则按路径处理;纯数字视为 PR 编号,可用 gh pr diff 获取差异和 PR 描述。
  4. 识别可跳过的情况:版本号升级、拼写修正等显而易见的改动,可直接说明并跳过生成文档。
  5. 按读者背景调整表达:若已知读者来自其他技术栈,在注释处就地用类比翻译陌生概念,不建术语表。
  6. 收集“为什么”:优先使用本次会话中产生的上下文,否则从提交信息、PR 描述、关联 issue 和周边代码重建,必要时向作者提问;无法确认理由时不得编造。
  7. 选择性注释:展示完整 diff,只在有决策、风险、权衡或放弃方案处加注;生成文件只用一行说明并在代码块内用省略行代替其 diff。
  8. 控制注释数量与顺序:注释按论证顺序排列而非字母顺序,先放改动真正所在的文件;发布前删除资深评审者已知或无助于改变评审判断的注释。
  9. 开头交代问题与类比:Start here 部分先用平实语言说明用户看到的问题或需求,再用一个日常类比帮助理解,类比只出现一次。
  10. 画前后对比图:用 ASCII 画一张 before/after 图展示机制变化,保持两侧方框位置一致,仅用 <del> 和 <ins> 标记差异,图不超过十行、每侧不超过 44 字符。
  11. 使用固定模板:assets/walkthrough-template.html 提供页面结构与样式,元素按内容语义选择,不改动 style 块。
  12. 发布交付:将填写后的页面写入 walkthrough.html,用 Artifact 工具发布并提供链接。

使用方式 该技能以提示词工作流形式提供,依赖 git 与可选的 gh 命令行工具。使用时在具备仓库环境的情况下触发,技能会按步骤执行基线定位、规模判断、差异阅读、动机收集、注释撰写、模板填充与发布。输出为单个 HTML 页面,页面在 diff 结束时结束,不包含结论、推荐、预批准清单等引导评审结论的内容。

适用场景 适合需要向不熟悉该代码库或技术栈的评审者解释一次变更的场合,尤其是包含设计取舍、风险、失败尝试或刻意不做之事的改动。也适合把分支改动整理成便于分享的走查文档。

限制 无法确认变更理由时,技能要求留白或明确说明未记录,不得虚构。若仓库没有可用基线(如尚无提交),需要询问对比分支。纯数字参数在无 gh 时按分支处理。页面不提供评审结论或推荐。模板样式固定,不提供布局类选择。