pr-review-html

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR review HTML

PR审查HTML

Build a single self-contained HTML file that lets a reviewer (or the author) work through a PR's diff with severity-coded inline annotations, check off the findings they want fixed, and one-click generate a paste-ready follow-up prompt for the next agent.

构建一个独立的HTML文件，让审查者（或代码作者）能够在PR的diff中查看带有严重程度编码的内联注释，勾选需要修复的发现项，并一键生成可直接粘贴给下一个Agent的后续提示。

When this skill helps

此技能适用场景

The artifact is most useful when:

The PR has multiple files and at least a few findings worth tagging
You want a portable review you can share, archive, or revisit
You want to round-trip selected findings back to an LLM as a clean prompt

For very small PRs (1-2 line changes) the artifact is overkill — just leave inline comments via

gh pr review

该工件在以下场景中最为实用：

PR包含多个文件，且至少有一些值得标记的发现项
你需要一份可分享、存档或重新查看的便携审查文件
你希望将选中的发现项整理为清晰的提示，反馈给大语言模型（LLM）

对于极小的PR（仅1-2行变更），使用该工件就有些大材小用了——直接通过

gh pr review

留下内联评论即可。

Workflow

工作流程

The skill bundles a Python build script and an HTML template. Your job is to produce a good

findings.json

and run the script.

此技能包含一个Python构建脚本和一个HTML模板。你的任务是生成一份合格的

findings.json

并运行该脚本。

Step 1 — Gather the diff and PR metadata

步骤1 — 收集diff和PR元数据

bash

gh pr diff <N> > /tmp/pr-<N>.diff
gh pr view <N> --json title,headRefName,additions,deletions,files

Read the whole diff before you start reviewing. Note the PR number, branch name, file count, additions, and deletions — you'll need them for the findings JSON.

bash

gh pr diff <N> > /tmp/pr-<N>.diff
gh pr view <N> --json title,headRefName,additions,deletions,files

在开始审查前通读整个diff。记录PR编号、分支名称、文件数量、新增行数和删除行数——这些信息会用到

findings.json

中。

Step 2 — Do an honest, critical self-review

步骤2 — 进行诚实、严格的自审查

For each substantive observation, assign one severity:

critical — blocks merge; correctness, security, or data-loss bug
major — should fix before merge; UX, partial-failure, or design concern
minor — worth fixing but won't block; clarity, hard-coded values, missing edge tests
nit — style, comment, or preference; take or leave
praise — specifically good; call out so we keep doing it

Be honest. If you wrote the code, push back on yourself the same way you would on a colleague. If every finding lands at "praise" you're not reviewing — aim for a mix that includes at least a few genuine concerns when they exist. Skip formatting nits unless they're load-bearing.

Findings can be tied to a specific file + line (rendered next to the diff) or

general

(rendered in a "General notes" section at the bottom).

对于每个实质性的观察结果，分配一个严重程度：

critical（严重） —— 阻碍合并；涉及正确性、安全或数据丢失的bug
major（主要） —— 合并前应修复；涉及用户体验（UX）、部分功能失效或设计问题
minor（次要） —— 值得修复但不阻碍合并；涉及代码清晰度、硬编码值、缺失边缘测试
nit（细微） —— 风格、注释或偏好问题；可修复也可不修复
praise（表扬） —— 特别优秀的部分；指出来以便后续保持

务必诚实。如果你是代码作者，要像对待同事的代码一样严格要求自己。如果所有发现项都是「表扬」，那说明你没有认真审查——当存在真实问题时，应确保发现项包含至少一些切实的关注点。除非格式问题影响重大，否则可以忽略细微的格式问题。

发现项可以关联到特定文件+行（渲染在diff旁），或是标记为

general

（渲染在底部的「通用说明」部分）。

Step 3 — Write findings.json

步骤3 — 编写findings.json

The full schema and a worked example live in

references/findings-schema.md

. The shape at a glance:

json

{
  "pr_number": 54,
  "title": "feat(scripts): pnpm onboard:dev + onboarding docs (#48 phase 1)",
  "branch": "48-onboard-dev-phase-1",
  "github_url": "https://github.com/<owner>/<repo>/pull/54",
  "files_stat": "10 files, +750 / −1",
  "verdict": "One-sentence summary of the overall take.",
  "test_commands": "pnpm test && pnpm typecheck",
  "files": [
    {
      "path": "scripts/onboard-dev.ts",
      "key": "orchestrator",
      "additions": 188,
      "deletions": 0,
      "is_new": true,
      "open_by_default": true,
      "diff": "@@ -0,0 +1,188 @@\n+import { ... }\n...",
      "annotations": [
        {
          "line": 165,
          "sev": "major",
          "title": "Manifest is mutated on `main` BEFORE the branch is created",
          "body": "If <code>openManifestPr</code> fails partway, the user is left with a dirty working tree on main.",
          "suggest": "Reorder so the branch is created first..."
        }
      ]
    }
  ],
  "general_annotations": [
    {
      "sev": "praise",
      "title": "Tests cover the surface area",
      "body": "85/85 passing; the safety-property tests are particularly nice."
    }
  ]
}

The

diff

field is the raw diff body for that file (everything after the

diff --git

and index header — start at the

@@

hunk). The build script parses

, and

@@

lines and renders line numbers from the new-file side.

Body text may use inline

<code>

(renders as backticks in the aggregated prompt) and

<em>

(renders as underscores). Keep bodies to 1-3 sentences.

test_commands

should match whatever the target project actually uses — the aggregated prompt tells the next agent to run them between commits.

完整的 schema 和示例可查看

references/findings-schema.md

。大致结构如下：

json

{
  "pr_number": 54,
  "title": "feat(scripts): pnpm onboard:dev + onboarding docs (#48 phase 1)",
  "branch": "48-onboard-dev-phase-1",
  "github_url": "https://github.com/<owner>/<repo>/pull/54",
  "files_stat": "10 files, +750 / −1",
  "verdict": "对整体情况的一句话总结。",
  "test_commands": "pnpm test && pnpm typecheck",
  "files": [
    {
      "path": "scripts/onboard-dev.ts",
      "key": "orchestrator",
      "additions": 188,
      "deletions": 0,
      "is_new": true,
      "open_by_default": true,
      "diff": "@@ -0,0 +1,188 @@\n+import { ... }\n...",
      "annotations": [
        {
          "line": 165,
          "sev": "major",
          "title": "Manifest is mutated on `main` BEFORE the branch is created",
          "body": "If <code>openManifestPr</code> fails partway, the user is left with a dirty working tree on main.",
          "suggest": "Reorder so the branch is created first..."
        }
      ]
    }
  ],
  "general_annotations": [
    {
      "sev": "praise",
      "title": "Tests cover the surface area",
      "body": "85/85 passing; the safety-property tests are particularly nice."
    }
  ]
}

diff

字段是该文件的原始diff内容（从

@@

块开始，即

diff --git

和索引头之后的所有内容）。构建脚本会解析

、

和

@@

行，并从新文件的一侧渲染行号。

正文文本可使用内联

<code>

（在汇总提示中渲染为反引号）和

<em>

（渲染为下划线）。正文内容控制在1-3句话。

test_commands

应与目标项目实际使用的命令一致——汇总提示会告知下一个Agent在提交之间运行这些命令。

Step 4 — Run the build script

步骤4 — 运行构建脚本

bash

python "<plugin-root>/skills/pr-review-html/scripts/build_review.py" \
  --findings /tmp/pr-<N>-findings.json \
  --output plans/<unix-ts>--<m-d-h:mmam/pm>--pr-<N>-review.html

Get the timestamp + date label from:

bash

date +%s
date "+%-m-%-d-%-I:%M%p" | tr 'A-Z' 'a-z'

The script is Python stdlib only (no pip install needed). On success it prints the output path on stdout. Open the file in a browser to verify.

bash

python "<plugin-root>/skills/pr-review-html/scripts/build_review.py" \
  --findings /tmp/pr-<N>-findings.json \
  --output plans/<unix-ts>--<m-d-h:mmam/pm>--pr-<N>-review.html

通过以下命令获取时间戳和日期标签：

bash

date +%s
date "+%-m-%-d-%-I:%M%p" | tr 'A-Z' 'a-z'

该脚本仅依赖Python标准库（无需pip安装）。运行成功后，会在标准输出中打印输出路径。在浏览器中打开该文件进行验证。

What the artifact does

工件功能

Sticky header with PR metadata, severity filter chips, and the "Create feedback prompt" button
Per-file
```
<details>
```
blocks (most substantive open by default, tests and wiring collapsed)
Two-column layout: diff on the left with
```
+
```
/
```
-
```
/
```
@@
```
coloring, line numbers, and a severity-colored gutter bar on annotated lines; cards on the right with severity badge, title, body, optional suggested-fix block
Click annotated line → scroll its card into view (and vice versa)
Filter chips toggle visibility per severity
Each card has a checkbox; "Create feedback prompt" aggregates checked items into a markdown prompt in a modal
```
<textarea>
```
with copy-to-clipboard

固定头部，包含PR元数据、严重程度筛选芯片和「创建反馈提示」按钮
每个文件对应一个
```
<details>
```
块（内容最丰富的文件默认展开，测试和连接类文件默认折叠）
双栏布局：左侧为带有
```
+
```
/
```
-
```
/
```
@@
```
颜色标记的diff、行号，以及带注释行的严重程度颜色侧边栏；右侧为带有严重程度徽章、标题、正文和可选建议修复块的卡片
点击带注释的行 → 滚动到对应的卡片（反之亦然）
筛选芯片可按严重程度切换显示内容
每个卡片都有一个复选框；「创建反馈提示」会将选中的项汇总为markdown提示，显示在模态框的
```
<textarea>
```
中，并支持一键复制到剪贴板

Reporting back

反馈结果

When done, print the output path and a one-sentence verdict on the PR. Don't proactively suggest follow-ups — the reviewer drives next steps from the artifact.

完成后，打印输出路径和对PR的一句话总结。不要主动建议后续步骤——审查者会通过该工件主导后续操作。