文档评审

md-review
分类编程
作者Alireza Rezvani
许可MIT
评分4.80/5
使用3.8K

md-review — 代码审查 Markdown $\rightarrow$ 双栏 HTML

该工具源自 Shihipar 论文（"Code Review and PR Writeups"）的第二层级代码审查转换器。它接收包含 diff 代码块和严重程度标注的 Markdown PR 描述，并生成一个包含跳转导航、双栏 diff + 标注布局以及具名审查者页脚的单文件 HTML 报告。

三个标准库工具通过流水线协作：

code
diff_parser.py  →  annotation_extractor.py  →  review_html_renderer.py
   (md → diff 块)   (md → 将带有严重程度标签的    (块 + 标注
                        标注关联至最近的块)        + token → 双栏 HTML)

调用时机

| 现象 | 操作 |
|---|---|
| markdown-html-orchestrator 将输入路由为 REVIEW | 调用此技能 |
| 用户直接运行 /cs:md-review <path>.md | 调用此技能 |
| 输入包含 `diff 代码块 + > [!MAJOR]/> [!BLOCKER]/等标注 | 调用此技能 |
| 输入为长篇规范/报告（无 diff 块） | 路由至 md-document |
| 输入为幻灯片 | 路由至 md-slides |
| 输入少于 100 行 | 拒绝（Shihipar 阈值） |
| 设计系统（Design-system）未配置 | 拒绝；提示使用 /cs:design-system |

流水线

bash
# 1. 解析 markdown → diff 块 JSON
python3 markdown-html/skills/md-review/scripts/diff_parser.py \
    --input <path>.md --output hunks.json

2. 提取带有严重程度标签的标注，并关联至其前方的最近代码块

python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
    --input <path>.md --diff-blocks hunks.json --output annotations.json

3. 渲染双栏 HTML（--reviewer 为必填项，否则拒绝执行）

python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
    --diff-blocks hunks.json --annotations annotations.json \
    --reviewer "Jane Doe" --title "PR #123: Add retry logic" \
    --output review.html

渲染内容

  • 顶部跳转导航 — 列出所有标注，包含严重程度徽章 + 80 字符预览 + 跳转链接；标题中显示严重程度统计（如 "3 BLOCKER · 2 MAJOR · 1 NIT"）
  • 双栏代码块行 — 左侧为统一差分（每行显示旧/新行号，+/- 标记，基于设计系统 token 的增删背景色），右侧为标注卡片（根据 WCAG 1.4.1 提供颜色 + 图标 + aria-label）
  • 批准栏 — 若存在 LGTM 标记且无严重程度标注，则显示绿色调的 "LGTM — no findings flagged" 栏
  • 通用评论 — 未关联至任何代码块的标注将渲染在
底部位于独立区域
  • 评审员页脚 (Reviewer footer) — 强制要求；若无 --reviewer 参数则拒绝渲染
  • 响应式 — 在视口 < 900px 时，两列布局将折叠为堆叠布局

硬性规则

1. --reviewer 为强制项。 代码评审必须指定一名人类评审员，否则以退出码 3 拒绝。此举旨在镜像 research-ops 的“指定所有者 (named owner)”纪律。
2. 若无 hunk 则拒绝。 如果没有 --- a/file + @@ ... @@ 代码块，则认为这不是代码评审 —— 以退出码 4 拒绝，并建议使用 md-document。
3. 输入少于 100 行则拒绝。 低于此阈值时，Markdown 优先（参考 Shihipar）。
4. 未完成 onboarding 则拒绝。 与所有转换器的准入机制一致。
5. 严重程度绝不能仅靠颜色区分。 每个徽章必须包含：颜色 + 图标 + aria-label + 文本。在渲染层强制执行 WCAG 1.4.1 标准。
6. 单文件输出。 所有 CSS 均内联。唯一允许的外部资源是 Google Fonts CSS。md-review 中不使用 Prism（diff 着色与语法高亮存在冲突）。
7. 自定义严重程度约定。 使用 --severity-convention "critical,important,suggestion,nit" 可更换等级名称；索引 0 为最严重。默认值为 BLOCKER / MAJOR / MINOR / NIT（参考 Google 代码评审开发者指南）。

强制性问题库 (Matt Pocock 质询纪律)

1. 指定的评审员是谁？ 建议：签署评审的用户。规范：research-ops 的 named-owner 模式；《Google 软件工程》第 9 章。
2. 适用哪种严重程度约定 —— 默认 (BLOCKER/MAJOR/MINOR/NIT) 还是自定义？ 建议：除非团队有记录在案的替代方案，否则使用默认值。规范：《Google 代码评审开发者指南》。
3. 批注是锚定在特定 hunk 上，还是部分为通用批注？ 建议：尽可能全部锚定；通用批注放入未锚定区域。规范：《Google 软件工程》第 9 章 —— “评论必须引用具体行号”。
4. <title> 和页眉使用的 PR 标题是什么？ 建议：实际的 PR / commit 标题。规范：将文档作为读者的上下文。
5. LGTM 标记是否应作为批准栏显示？ 建议：如果没有严重程度批注，则显示；否则以评审结果为准。

区别于

  • md-document — 该转换器渲染正文 + 表格 + 代码 + 标注。本转换器渲染 diff hunk + 边距批注。
  • md-slides — 该转换器在 --- 边界处进行分割。本转换器生成单页产物。
  • GitHub PR 评论 — 那些是对话线程。本产物是单作者的快照。

输出产物

{default_output_dir}/review-{slug}.html（路径由编排器的 output_path_resolver.py 解析；冲突时默认添加后缀 -2, -3 ...）。

参考资料

  • Shihipar — *Claude Code HTML output* (Medium, 2026), Tier 2 用例
  • *Software Engineering at Google* (Manshreck & Wright, O'Reilly 2020), 第 9 章 "Code Review"
  • Google *Code Review Developer Guide* — 严重程度约定来源
  • WCAG 2.2 §1.4.1 — 颜色非唯一信号强制执行
  • 完整引用请参阅 references/ (diff_rendering_canon, severity_coding, pr_annotation_ux)