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