GitHubxsy 让代码差异适合人类检视
把原始 diff 转化为 reviewer 能快速理解、逐层核验并作出决定的材料。报告不是 diff 的自然语言复述，也不替人自动批准代码。
目标
报告应同时满足两种阅读深度：
- reviewer 在第一屏内理解修改目的、可观察行为变化、最高风险、待确认决定和验证状态；
- reviewer 可以沿证据链接继续检查相关文件、符号、调用方、测试和原始 diff。
报告深度应与改动风险和复杂度相称。小改动不要强行生成完整架构分析；大改动不要用一句摘要掩盖跨模块影响。
确定范围与证据
- 准确解析用户指定的目标：单个提交、提交范围、分支比较、PR/MR、暂存区、工作区或指定文件。
- 如果目标不明确，使用对话中最近讨论的一组改动，并在报告中标明该假设。
- 检查 diff、修改前的代码、相关调用方、测试、配置和文档。按需查看提交历史，理解难以从代码本身确认的原因。
- 区分代码中可以确认的事实、提交或需求中声明的意图，以及检视者作出的推断。明确标注不确定结论。
- 除非用户要求修复，否则只检视，不修改产品代码，也不改写 PR。
优先使用仓库原生命令，例如：
git show --stat --oneline <commit>
git diff <base>...<head>
git show <commit> -- <path>
rg "<symbol>" <relevant-paths>
先建立变更地图
在设计报告前，先回答五个问题：
- 为什么要改？
- 用户、调用方或运维会观察到什么不同？
- 哪条运行时路径、数据流或职责边界发生了变化？
- 最大风险和真正需要人决定的取舍是什么？
- 现有验证证明了什么，还没有证明什么？
据此给出建议的 Review 顺序。按行为和因果链组织，不要按文件名逐个复述。
选择最小有效视图
视觉表达用于降低理解成本，不用于装饰。只保留回答当前 Review 问题所需的调用、文件、状态和边界。通常使用一到三个视图，不需要覆盖所有形式。
- 局部逻辑或算法：使用短小伪代码。
- 运行时调用关系：使用调用树。
- UI 结构与状态归属：使用组件树，并标出关键文件或模块。
- 文件职责或大范围重构：使用浅层文件树，每个目录只写一句职责。
- 组件交互、控制流或数据流：使用紧凑流程图；HTML 中优先使用带标签的 CSS 图示或内联 SVG。
- 已有形状中的局部变化：优先使用
diff形式，在调用树、文件树、组件树或伪代码上直接标出增删。 - 大部分内容都是新的，或省略上下文会隐藏归属和顺序：展示一个完整但最短的目标结构。
每个视图紧邻它所解释的简短文字，并注明它是代码事实、根据代码简化的模型，还是建议方案。不要把概念图伪装成真实调用链。
生成自包含报告
除非用户指定其他位置，否则将 UTF-8 HTML5 文件写入本 Skill 目录下的 reports/explain-diff-<target>.html。运行时确定当前 Skill 所在目录；如果 reports 不存在则创建。不要假设固定安装路径。
报告必须可以直接打开：
- 内嵌全部 CSS，不使用远程字体、脚本、样式表、图片或分析服务；
- 使用语义化 HTML、响应式布局、清晰的键盘焦点和足够的文字对比度；
- 对代码、路径、提交信息和用户文本进行 HTML 转义；
- 使用
<details>折叠长代码、原始 diff、验证命令和次要证据； - 提供打印样式，确保导出 PDF 后仍然可读。
报告结构
只保留适用于本次改动的章节，不要为了模板完整而制造空内容。
第一屏：Review 摘要
显示仓库、检视范围、基准版本、改动规模，以及：
- 一句话说明为什么改、改了什么；
- 最小的“修改前 → 修改后”行为视图；
- 最高优先级风险；
- reviewer 必须确认的决定；
- 已执行验证的真实状态；
- 建议从哪里开始 Review。
风险等级使用：严重、高、中、低、提示。总体结论仅限：可以合入、可以合入但需要后续处理、需要修改。结论必须由证据支持，并明确最终决定属于人类 reviewer。
改动导览
按行为或职责组织改动。每组说明修改目的、关键实现选择、涉及的文件和符号、输入输出、状态、失败行为及兼容性影响。展示最小有效视图，原始细节放入折叠区域。
检视发现
将可执行发现按严重程度排序。每项包括：
- 严重程度和简短标题；
- 文件、符号和代码行证据；
- 可能的失败场景或需要确认的问题；
- 建议的处理决定或后续工作。
区分已确认缺陷、设计决定、残余风险和提示。没有明确缺陷时直接说明，不要为了显得全面而虚构问题。
系统形状与影响
仅当关系本身是 Review 难点时展示修改前后的架构、控制流、数据流或状态变化。适用时用紧凑矩阵覆盖配置、API/协议、运行时、并发、安全、可观测性、部署、兼容性和测试。“未受影响”只有在能消除合理疑问时才列出。
验证证据
严格分为：
- 本次检视实际执行的测试及观察结果；
- diff 中存在但本次没有执行的测试；
- 建议补充的验证。
只有命令输出或可靠证据能够证明时，才能标记为通过。适用时提供可复现的人工验证步骤。
深入证据与待确认事项
按需提供永久链接、关键代码片段、替代方案和简短确认清单。只有存在实质不同的实现路径时才讨论替代方案。知识传递确有价值时，可以添加不超过五个理解问题，并将答案折叠；小型修复省略。
证据链接
- 先读取仓库 remote，仅在能可靠识别托管平台及 URL 规则时生成网页链接；支持 GitHub、CodeHub、GitLab、Gitee 和其他类似平台，不绑定厂商。
- 优先链接固定到提交哈希的提交、文件和代码行，不使用会随分支漂移的地址。
- 无法可靠生成网页链接时，显示仓库相对路径、符号、提交哈希和行号，不猜测 URL。
视觉规范
使用安静、清晰的工程报告风格：中性背景、白色内容区、深色正文；蓝色用于导航，绿色用于已验证证据，琥珀色用于待确认决定，红色用于缺陷。内容最大宽度约 1180px，圆角不超过 8px，代码和路径使用等宽字体。
宽屏提供固定目录，移动端使用顶部索引。卡片仅用于独立发现、验证证据和重复的行为分组，不嵌套卡片。第一屏优先呈现信号，不用装饰性大标题挤占空间。
校验与返回
完成前：
- 确认文件存在且非空，所有适用章节都有真实内容；
- 确认没有外部运行时资源或托管文档服务依赖；
- 如果浏览器工具可用，本地打开或渲染 HTML，检查桌面和移动端的溢出、重叠、锚点和代码可读性；
- 对照检视版本核对仓库链接、提交哈希和引用行号；
- 返回报告的绝对路径链接，并用简短 Markdown 概述修改目的、行为变化、最高风险、验证状态和建议 Review 顺序。除非用户明确要求，不要自动发布或修改 PR 描述。