review-walkthrough

评审讲解

为当前分支生成一份独立的 HTML 讲解，其中将最终差异拆分为逻辑步骤，并附上说明和关键评审发现。根据理解需要决定分组方式和阅读顺序；不必遵循提交顺序。在 Claude Code 中使用 /review-walkthrough:review-walkthrough 调用，在 Codex 中使用 $review-walkthrough 调用。

获取分支差异

尊重用户指定的基准分支。否则，如果有 PR 元数据，则使用当前打开的 PR 的基准分支。没有 PR 时，通过 git symbolic-ref --quiet --short refs/remotes/origin/HEAD 或已配置远程仓库的等效命令，查找仓库的默认分支。不要假定默认分支是 main。如果选定的基准分支不存在或不明确，请询问用户，不要悄悄改选其他分支。

使用 git rev-parse --verify --end-of-options "${ref}^{commit}" 将基准分支和 HEAD 解析为提交 ID，然后用 git merge-base 计算它们的合并基点。使用 git diff --no-ext-diff --no-textconv --no-color --src-prefix=a/ --dst-prefix=b/ "$merge_base" "$head_sha" -- 获取完整补丁。在同一次 shell 调用中初始化变量并运行使用这些变量的命令；shell 变量不会在工具调用之间保留。将补丁保存到检出目录之外的临时文件，并保留其实际路径。如果遇到 Git 错误或补丁为空，请停止并说明结果。

此范围包括截至所捕获的 HEAD 的已提交更改。说明任何未纳入的未提交工作。不要切换分支、重置检出状态或修改源文件来准备评审。除非用户指定了输出位置，否则将生成的数据和 HTML 保存在检出目录之外；生成的评审产物绝不能包含在所获取的补丁中。

对于 GitHub PR，从其元数据中收集 owner、repo、pr_number 和 head_sha。只有在 PR 的 head 与所捕获的 HEAD 相符，且所选基准分支与 PR 的基准分支相符时，才填写这些信息。否则使用 null，并说明无法导出评论。身份验证失败或网络请求失败并不意味着 PR 不存在；如果无法确定基准分支，请报告失败并询问用户。如果用户已提供基准分支或确认不存在 PR，则可选用 GitHub 访问功能。

组织评审内容

阅读已更改的文件，以及判断这些更改所需的相关源码、测试、配置和依赖元数据。评审应保持只读；不要仅为构建讲解而运行项目测试或安装其依赖项。

将相关文件分组为若干步骤，每个步骤只涵盖一个概念。先放定义，再放使用它们的内容；先放组件，再放连接这些组件的配置；测试放在其对应内容之后或旁边。将捕获的补丁中每个文件的完整差异原样复制到且仅复制到一个步骤中。可以在步骤之间调整文件顺序，但不得拆分、改写、省略或凭空编造补丁。即使重命名、二进制和模式更改条目没有文本差异块，也要保留。二进制摘要用于标识已更改的文件；其载荷不属于本次评审范围。

每个步骤撰写一段说明，通常为 50–150 个词，涵盖更改目的、设计选择、权衡，以及与其他步骤的关联。引用实际标识符。每个步骤撰写一份评审列表，涵盖代码所支持的错误、安全性、验证、API 设计或性能问题。按严重程度报告问题，不要压下轻微问题。没有问题的步骤使用空列表。

说明和评审正文均为 HTML 片段。使用 <p>、<strong>、<em>、<code>、<pre> 和 <ul>/<li> 组织内容。在正文或代码片段中出现字面量 < 和 > 时，分别写为 < 和 >。反引号和 Markdown 围栏在此处均为字面文本。支持的行内标签还包括 <sup>、<sub>、<kbd>、<del> 和 <a href="https://…">。页面会清理这些片段，并在准备 PR 评论时将其转换为 Markdown。仅保留安全的链接目标；不保留任意属性、脚本和图片。表格会导出为单元格之间以分隔符隔开的文本行；保留表格标题和行顺序。结构足够时，优先使用段落、列表和代码块。

将问题锚定到同一步骤中的文件，以及该文件显示差异中的某一行。新增内容或新文件上下文使用 side: "RIGHT"，删除内容或旧文件上下文使用 side: "LEFT"。对于范围，line 和 end_line 必须使用同一侧，且位于同一个差异块内。跨越多个步骤的问题应归入其所涉及的文件，或不设锚点。无锚点的问题仍会显示，但无法成为行内 PR 评论。

渲染产物

使用文件写入工具创建一个包含以下字段的 JSON 对象。将字面补丁保留为 JSON 字符串数据，不进行 shell 展开。

字段	值
title	功能或评审标题
steps	对象数组，包含 sha（步骤 ID，例如 step-1）、message（步骤标题）、files（按补丁顺序排列的路径）和 diff（每个文件的完整补丁）
explanations	HTML 字符串，每个步骤一个
reviews	每个步骤一个发现项数组；每个发现项包含 severity（high、medium 或 low）、title 和 HTML 格式的 body
pr_meta	包含 owner、repo、pr_number 和 head_sha 的对象，或 null

带锚点的发现项还包含 file、line 和 side，以及可选的 end_line。三个数组的长度相同，且对应项一一对应。文件路径须与 diff 标头中的路径一致，但不带 a/ 或 b/ 前缀；重命名文件使用新路径。请明确设置 side，以区分同时出现在两侧的行。

使用本次评审实际创建的路径运行捆绑的渲染器：

uv run --no-project {baseDir}/scripts/render_walkthrough.py \
  --input /tmp/data.json \
  --diff /tmp/captured.patch \
  --output /tmp/walkthrough.html

渲染器会验证数据，将每个步骤的补丁与完整捕获的 diff 进行比较，检查锚点，并将结果安全地嵌入捆绑的模板中。请修复报告的输入错误，不要绕过渲染器或生成替代页面。

当浏览器可用时，在 macOS 上使用 open，或在 Linux 上使用 xdg-open 打开输出，并告知用户文件路径。在无头运行中，报告文件路径即可。存在 PR 元数据时，页面会允许用户为所选评论复制 gh api 命令。它不会执行该命令，也不会向 GitHub 发布任何内容。复制命令前，Comment 和 Request Changes 都需要填写评审摘要；Approve 的摘要则为可选。