md-review

md-review — 代码审查 Markdown → 双栏 HTML

Shihipar 的文章《Code Review and PR Writeups》中 Tier 2 的代码审查转换器。输入包含差异块和严重性标注的 Markdown PR 说明，生成单文件 HTML 审查页面，包含跳转导航、双栏差异与注释布局，以及带审查者姓名的页脚。

三个标准库工具组成流水线：

diff_parser.py  →  annotation_extractor.py  →  review_html_renderer.py
   (md → diff hunks)   (md → severity-tagged    (hunks + annotations
                        annotations attached     + tokens → 2-col HTML)
                        to nearest hunk)

何时调用

情况	操作
markdown-html-orchestrator 将输入路由为 REVIEW	调用此技能
用户直接运行 /cs-md-review <path>.md	调用此技能
输入包含 ```diff 围栏代码块和 > [!MAJOR]/> [!BLOCKER]/等标注	调用此技能
输入是长篇规格说明 / 报告（没有差异块）	改为路由到 md-document
输入是幻灯片	改为路由到 md-slides
输入少于 100 行	拒绝（Shihipar 阈值）
尚未接入设计系统	拒绝；提示使用 /cs-design-system

流水线

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

# 2. Extract severity-tagged annotations, attach to nearest preceding hunk
python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
    --input <path>.md --diff-blocks hunks.json --output annotations.json

# 3. Render 2-col HTML (--reviewer is mandatory — refuses without)
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”）
• 双栏差异块行 — 左侧为统一差异（逐行显示旧行 / 新行编号、+ / − 标记，以及使用设计系统令牌的新增 / 删除背景色调），右侧为注释卡片（根据 WCAG 1.4.1 提供颜色、图标和 aria-label）
• 批准栏 — 如果存在 LGTM 标记且没有严重性注释，则显示成功色调的“LGTM — 未标记问题”栏
• 一般评论 — 未关联任何差异块的注释会在底部自己的版块中渲染
• 审查者页脚 — 必须提供；缺少 --reviewer 时拒绝渲染
• 响应式布局 — 视口宽度 < 900px 时，双栏布局折叠为纵向堆叠

硬性规则

1. 必须提供 --reviewer。 代码审查必须注明人工审查者。否则以退出码 3 拒绝。遵循 research-ops 的“指定负责人”原则。
2. 没有差异块时拒绝。 没有 --- a/file + @@ ... @@ 块就不是代码审查——以退出码 4 拒绝，并建议使用 md-document。
3. 输入少于 100 行时拒绝。 低于此阈值时应使用 Markdown（Shihipar）。
4. 未完成接入时拒绝。 与每个转换器采用相同的门槛。
5. 严重性绝不只用颜色表示。 每个徽标都包含颜色、图标、aria-label 和文本。在渲染器层强制执行 WCAG 1.4.1。
6. 单文件输出。 所有 CSS 均内联。唯一的外部资源是 Google Fonts CSS。md-review 不使用 Prism（差异着色会与语法高亮冲突）。
7. 自定义严重性约定。 --severity-convention "critical,important,suggestion,nit" 可替换各级名称；位置 0 表示最严重。默认值为 BLOCKER / MAJOR / MINOR / NIT（Google Code Review Developer Guide）。

强制提问库（Matt Pocock 式追问原则）

1. 指定的审查者是谁？ 建议：负责批准审查的用户。依据：research-ops 的指定负责人模式；SWE at Google 第 9 章。
2. 采用哪种严重性约定——默认值（BLOCKER/MAJOR/MINOR/NIT）还是自定义值？ 建议：除非团队有记录在案的替代方案，否则使用默认值。依据：Google Code Review Developer Guide。
3. 注释是锚定到具体差异块，还是有些属于一般评论？ 建议：尽可能将所有注释锚定到具体位置；一般评论放在未锚定版块。依据：SWE at Google 第 9 章——“评论必须指向具体行”。
4. <title> 和页眉中使用什么 PR 标题？ 建议：使用实际的 PR / 提交标题。依据：docs-as-context-for-readers。
5. 是否应将 LGTM 标记显示为批准栏？ 建议：如果没有严重性注释，则显示；否则优先展示问题。

与以下内容的区别

• md-document — 该转换器渲染正文、表格、代码和标注；此转换器渲染差异块和边栏注释。
• 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 章“代码审查”
• Google Code Review Developer Guide — 严重程度约定来源
• WCAG 2.2 §1.4.1 — 强制要求颜色不能作为唯一信号
• 完整引文请参见 references/（diff_rendering_canon、severity_coding、pr_annotation_ux）