用途
PR Review Canvas 用于为 GitHub Pull Request 生成一份交互式 HTML 审查走查页面,目标是让审查者像有一位同事陪同一样,清楚地理解 PR 中真正重要的内容。它把 PR 数据整理成可折叠、带注解的页面,帮助审查者快速区分核心变更与机械性变更。
主要能力
- 通过 gh API 只读获取 PR 数据,包括 PR 元信息(标题、正文、作者、状态、增删行数、变更文件数、base/head 分支)、变更文件列表(文件名、状态、增删行数、patch)以及 PR 评论(用户、正文、路径、行号)。
- 将文件区分为核心变更与机械性/样板变更:核心文件默认展开并附审查注解,机械文件默认折叠。
- 生成可折叠的文件卡片,支持粘性文件头与粘性注解,滚动时保持可见。
- 渲染统一 diff,并自动过滤仅 import 的行、将纯空白变更折叠为上下文行、检测被移动的代码块(连续 3 行以上在一处删除并在另一处相同添加),以蓝色/紫色而非红/绿色显示;移动加小幅编辑的近似匹配使用另一种紫色。
- 支持伪代码摘要:对冗长代码用通俗英文或短伪代码概括算法,真实 diff 折叠在下方。
- 支持内联 SVG、通过 CDN 的 mermaid、
<pre>中的 ASCII 图、前后控制流流程图、新旧行为对比表格、警告/问题/陷阱提示框,以及有助于审查的交互式组件。 - 提供预置的深色主题 CSS 类与 JS 工具函数,包括
toggle、toggleBP、renderDiff、esc。
使用方式
- 并行运行 gh api 调用获取 PR 元数据、变更文件与评论。
- 阅读 diff,理解 PR,并直接以 HTML 编写
<body>内容。典型结构包括:带标题、PR 编号、作者、统计信息的头部;用平实语言说明 PR 作用的摘要框;带注解与 diff 的核心文件区块;默认折叠的机械/样板文件;底部的审查清单。也可按需添加伪代码摘要、图表、流程图、对比表格、提示框等。 - 使用技能目录中的
styles.css与renderer.js,将其原样注入template.html。diff 通过<div data-diff="KEY"></div>占位符与pr-diffs-json脚本元素自动发现并填充。 - 安全嵌入 patch:先用 jq 将 patch 保存为 JSON 文件,再用 Python 脚本将 JSON 安全注入
template.html,对<、>、&做转义,避免</script>提前终止 HTML 脚本标签。 - 将 body HTML 写入临时文件,保存 patch JSON,运行 Python 组装脚本,生成最终 HTML。
- 在固定端口启动本地服务器:
cd /tmp && python3 -m http.server 8432 --bind 127.0.0.1,后台运行后在应用内浏览器访问http://127.0.0.1:8432/pr-review-{number}.html。若端口被占用可尝试 8433、8434 等。
适用场景
- 需要向审查者清晰解释一个 GitHub PR 的内容与重点。
- PR 中包含大量机械性/样板变更,需要突出核心变更。
- 希望用伪代码、图表、对比表格等方式辅助理解复杂逻辑。
- 在本地以只读方式查看 PR 审查页面。
限制
- 仅用于本地只读渲染,不会评论、批准、合并或发布 PR。
- 需要 GitHub gh CLI(只读),可选地支持本地 fixture;缺少 gh 时回退到本地 diff,并标记 PR 元数据不可用。
- 需要本地 HTML 产物与 node 语法检查能力。
- 资料明确说明:PR 检索、分类、浏览器呈现、注解与发布等路径尚未被验证。
- 固定端口与
cd /tmp的做法是因为后台 shell 没有 TTY,Python 会无限缓冲启动消息,使用端口 0 无法读取所选端口。