Explain Diff For Human Review

生成人工代码检视报告

> 修改说明：本文件从 GitHubxsy/agent-skills 引入，并由 amazing-fish/agent-skills 修改了报告输出位置、规模控制、GitHub 固定链接证据策略和可选独立子 Agent 审查。来源与上游版本见仓库根目录 sources.lock.json。

生成一份自包含的 HTML 报告，将原始代码差异转化为供人类检视的上下文、证据和待确认事项。帮助检视者作出判断，不要替检视者自动批准改动，也不要只复述增加或删除了哪些代码行。

确定检视范围

1. 准确解析用户指定的目标：单个提交、提交范围、分支比较、代码评审请求（PR 或 MR）、暂存区、工作区或指定文件。
2. 如果目标不明确，使用对话中最近讨论的一组改动，并在报告中明确说明该假设。
3. 检查 diff、改动前的代码、相关调用方、测试、配置和文档。
4. 区分代码中可以确认的事实和对修改意图的推断；对不确定的结论加以标注。
5. 除非用户另行要求修复，否则在解释 diff 时不要修改产品代码。

优先使用仓库原生命令，例如：

git show --stat --oneline 
git diff ...
git show  -- 
rg "" 

生成报告

不要将运行生成物默认写入 Skill 安装目录。按以下优先级确定一个 UTF-8 HTML5 输出文件：

1. 用户显式指定的文件或目录。
2. 当前仓库根目录下的 reports/explain-diff-.html。
3. 当前可写工作区下的 reports/explain-diff-.html。
4. 无仓库和工作区时，系统临时目录下的 reports/explain-diff-.html。

如果本 Skill 包含 scripts/resolve_report_path.py，优先用它确定路径并创建父目录。显式路径以 .html 结尾时视为文件，否则视为目录。始终在最终响应中返回实际绝对路径。Skill 安装目录只有在用户明确指定时才可作为输出位置。

报告必须能够通过直接打开文件使用：

• 将全部 CSS 内嵌到 HTML。
• 不使用远程字体、脚本、样式表、图片、分析服务或其他托管资源。
• 使用语义化 HTML、响应式布局、清晰的键盘焦点和足够的文字对比度。
• 将代码、路径、提交信息以及用户提供的文本写入 HTML 前进行转义。
• 优先使用 CSS 图示和带标签的流程图；仅在确实有助于理解关系时使用内联 SVG。
• 使用 `` 折叠较长的代码片段、验证命令和问答答案。
• 如果代码托管平台提供稳定的网页地址，链接到具体提交、文件和代码行；支持 GitHub、CodeHub、GitLab、Gitee 及其他类似平台，不绑定任何特定厂商。
• 优先使用固定到提交哈希的永久链接，不使用可能随分支变化而失效的链接。
• 先读取仓库 remote，并仅在能够可靠识别托管平台及其 URL 规则时生成网页链接。不要根据猜测拼接地址。
• 如果托管平台未知、没有网页访问地址或无法确定链接格式，则显示仓库相对路径、符号、提交哈希和行号，不降低报告的可读性。
• 提供打印样式，确保报告导出为 PDF 后仍然可读。

控制报告规模

生成 HTML 前统计 changed files、增加/删除行数、可获得的 patch 字节数，以及缺失 patch 的文件数。如果本 Skill 包含 scripts/classify_diff_size.py，使用它选择模式；默认阈值为：

• small：文件数不超过 20、改动行数不超过 800、patch 不超过 128 KiB。
• standard：文件数不超过 80、改动行数不超过 4,000、patch 不超过 1 MiB。
• large：超过任一 standard 阈值。

阈值判断使用“全部满足才进入该档”的规则。报告页头必须显示所选模式、统计值、缺失 patch 数量和未纳入正文的材料。

按模式控制细节：

• small：可内嵌全部可用 diff，但仍只在正文展示关键短片段。
• standard：正文只内嵌关键 hunks；其余按文件折叠、拆入附录或使用稳定链接。
• large：主报告只保留结论、架构、影响矩阵、发现和验证证据；原始细节进入有大小上限的附录，或明确说明省略原因。

GitHub 仓库采用以下特例：

• 对 small、standard 和 large 一律不在 HTML 中复制 raw diff、patch 或 diff hunk。详细代码证据只使用固定版本链接。
• 提供固定到 base_sha...head_sha 的 compare 链接，以及固定到 head_sha 的文件和代码行永久链接。链接文字应说明目标文件、符号或证据用途。
• 报告中保留对行为变化、架构、风险、验证结果和待确认事项的人工解释，但不要把 GitHub 源码重新复制为 diff 证据。
• 对私有仓库，不要把受访问控制的源码镜像进报告；永久链接仍由仓库权限控制访问。
• 不要只链接随分支变化的页面。PR 的 Files changed 页面可作为导航，但必须同时显示已检视的 head SHA，并优先提供固定 SHA 链接。

对 rename、binary、generated/vendor、lockfile、submodule、LFS、超长单文件和缺失/截断 patch，只展示可确认的元数据、风险和稳定链接；不要伪装成已检查完整内容。非 GitHub 平台在无法生成可靠链接时使用有界附录，并明确证据缺口。

可选独立子 Agent 审查

独立审查是降低作者视角偏差的可选阶段，不是报告生成、批准或修改代码的替代者。

1. 先解析并记录不可变 base_sha、head_sha、仓库和检视范围；不要只向子 Agent 提供活动分支名。独立审查结束后重新核对 SHA，漂移时丢弃结果。
2. 检查运行环境是否提供子 Agent 能力。仅在用户要求、风险值得额外审查或需要验证本 Skill 时启用；能力不可用、超时、失败或输出无效时执行现有单 Agent 回退，不阻断报告生成。
3. 启用时读取 [independent-review-contract.md](references/independent-review-contract.md)。按规模准备输入：small 提供完整的相关改动集；standard 优先高风险和代表性文件并列出省略项；large 只在确有价值时提供有界的高风险切片，不声称完整覆盖。
4. 只提供固定版本证据、patch 元数据、相关测试和约束；不要提供主 Agent 的预期结论、怀疑点、拟议修复或报告草稿。
5. 明确要求子 Agent 只读：不修改产品代码、不提交 Review、不批准合入、不作最终判断。其输出只能是约定的 JSON 发现。
6. 如果包含 scripts/validate_independent_review.py，使用预期 base SHA、head SHA、规模模式、实际提供给子 Agent 的 included 路径集合和明确 withheld 的 omitted 路径集合校验输出。completed 时两组必须分别精确匹配；非完成状态必须返回空 included，并把整个计划范围归入 omitted。丢弃无效或非 completed 状态的发现，并执行单 Agent 回退。
7. 主 Agent 逐项在固定 head_sha 上复核证据、去重并负责最终 HTML。无法复核的内容只能标记为推断或证据缺口，不能升级为已确认缺陷。
8. 报告披露是否请求独立审查、执行状态、固定 SHA、规模模式、覆盖和省略路径、单 Agent 回退及证据缺口。子 Agent 不可用不是报告失败。

报告结构

页头

显示仓库、检视目标、基准版本、作者和日期（如果可知）、改动规模、报告模式、缺失或省略材料，以及一句话结论。提供简洁的风险等级说明：严重、高、中、低、提示。

如果请求了独立审查，同时显示其状态、覆盖范围、回退状态和证据缺口；未请求时无需增加空占位。

结论摘要

说明：

• 修改了什么。
• 为什么需要这项修改。
• 用户或运维人员会观察到哪些行为变化。
• 是否向后兼容。
• 总体检视结论：可以合入、可以合入但需要后续处理，或需要修改。

架构与数据流

解释相关系统在修改前和修改后的模型。如果涉及三个及以上组件或处理步骤，提供简洁的可视化关系图。

改动导览

按行为或职责组织改动，不要简单按照文件顺序罗列。每组改动说明：

• 修改目的。
• 关键实现选择。
• 涉及的文件和符号。
• 输入、输出、状态和失败行为。
• 兼容性影响。

只展示短小且关键的代码片段。原始 diff 细节按报告规模策略折叠、拆入有界附录、明确省略，或用固定版本链接代替。GitHub 目标不得内嵌 diff、patch 或 hunk，只提供固定版本证据链接。

影响矩阵

使用表格覆盖适用的影响面：配置、API 或协议、运行时行为、并发、安全、指标与可观测性、部署、兼容性和测试。如果“未受影响”本身对检视有价值，也要明确标出。

检视发现

先列出可执行的发现，并按严重程度排序。每项发现包括：

• 严重程度和简短标题。
• 文件、符号和代码行证据。
• 可能的失败场景或需要确认的问题。
• 建议的处理决定或后续工作。

明确区分已确认缺陷、设计决策和残余风险。如果没有发现明确缺陷，应直接说明，不要为了填充报告而虚构问题。

验证

将验证证据分为三类：

1. 本次检视实际执行的测试及观察到的结果。
2. diff 中存在但本次检视没有执行的测试。
3. 建议补充的验证。

只有在命令输出或可靠的已有证据能够证明时，才可将命令标记为通过。适用时提供可复现的人工验证步骤。

替代方案

只有在能够识别出实质不同的实现方式时，才列出一到两个替代方案。比较其收益、成本，以及当前实现为何被选择或更合适。

检视清单与理解问答

提供一份简短清单，列出检视者需要明确确认的决定。如果报告还用于知识传递，增加不超过五个中等难度的问题，并将答案放在 `` 中；对于范围很小的缺陷修复，可以省略问答。

视觉规范

采用安静、清晰的工程报告风格：

• 使用中性页面背景、白色内容区域和深色正文。
• 使用克制的蓝色表示导航与链接，绿色表示已验证证据，琥珀色表示待确认决定，红色表示缺陷。
• 内容最大宽度约为 1180px。
• 宽屏使用固定目录，移动端使用简洁的顶部索引。
• 卡片仅用于单项发现、验证证据和重复的改动分组，不要嵌套卡片。
• 圆角不超过 8px。
• 代码、命令、提交哈希、指标和文件路径使用等宽字体。

校验产物

完成前执行以下检查：

1. 确认文件存在且内容非空。
2. 确认报告包含标题和所有适用的必需章节，并且不包含托管文档服务引用或外部资源地址。
3. 如果浏览器工具可用，在本地打开或渲染 HTML；分别检查桌面和移动端宽度下是否存在溢出、重叠、失效锚点或不可读代码。
4. 对照检视版本核对所有仓库链接和引用行号。
5. 核对报告模式、规模统计、缺失 patch 和省略声明；所有规模的 GitHub 报告均不得包含 raw diff、patch 或 diff hunk，并必须提供固定版本证据链接。
6. 如果请求了独立审查，核对其结构化输出已绑定预期 base/head、通过校验，并在 HTML 中披露执行状态、覆盖范围、回退和证据缺口。
7. 返回 HTML 文件的绝对路径可点击链接，并概述优先级最高的检视结论。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: amazing-fish
• Source: amazing-fish/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.