SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场md-review

md-review

编程与开发

查看项目

更新于 10-16 03:22

技能介绍

用途

md-review 是一个代码评审 Markdown 转 HTML 的转换器，属于 Shihipar 文章（"Code Review and PR Writeups"）中的 Tier 2 用例。它读取带有 diff 块和严重级别标注的 Markdown PR 说明，生成单文件 HTML 评审页面，包含跳转导航、双栏的 diff 与批注布局，以及署名的评审人页脚。

主要能力

工具由三个标准库脚本串联成流水线：

diff_parser.py → annotation_extractor.py → review_html_renderer.py （md → diff hunks） （md → 带严重级别的批注，附加到最近的 hunk） （hunks + 批注 + tokens → 双栏 HTML）

渲染内容包含：

  • 顶部跳转导航：每条批注带严重级别徽章、80 字符预览和跳转链接；标题中显示各严重级别计数（如 "3 BLOCKER · 2 MAJOR · 1 NIT"）。
  • 双栏 hunk 行：左侧为 unified diff（逐行旧/新行号、+/− 标记、来自设计系统 token 的增删背景色），右侧为批注卡片（颜色 + 图标 + aria-label，符合 WCAG 1.4.1）。
  • 审批条：若存在 LGTM 标记且没有严重级别批注，显示成功色调的 "LGTM — no findings flagged" 条。
  • 一般评论：未附加到任何 hunk 的批注在底部单独区域渲染。
  • 评审人页脚：强制要求，没有 --reviewer 则拒绝渲染。
  • 响应式：视口小于 900px 时双栏折叠为堆叠布局。

何时调用

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

使用方式

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

# 2. 提取带严重级别的批注，附加到最近的先前 hunk
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

硬性规则

  • --reviewer 必填。代码评审必须指定人类评审人，否则以退出码 3 拒绝。
  • 没有 hunk 时拒绝。缺少 --- a/file + @@ ... @@ 块意味着这不是代码评审，以退出码 4 拒绝并建议改用 md-document。
  • 输入少于 100 行时拒绝。低于该阈值时 Markdown 更优（Shihipar）。
  • 未接入设计系统时拒绝，与所有转换器同一门槛。
  • 严重级别不只靠颜色区分。每个徽章同时带颜色、图标、aria-label 和文本，在渲染器层面强制执行 WCAG 1.4.1。
  • 单文件输出。所有 CSS 内联，唯一外部资源是 Google Fonts CSS。md-review 中不使用 Prism（diff 着色与语法高亮冲突）。
  • 可自定义严重级别约定。--severity-convention "critical,important,suggestion,nit" 可替换层级名称，位置 0 为最严重。默认是 BLOCKER / MAJOR / MINOR / NIT（Google Code Review Developer Guide）。

强制问题库（Matt Pocock 质询方法）

  • 具名评审人是谁？推荐：为评审签字的人。依据：research-ops 的具名负责人模式；SWE at Google 第 9 章。
  • 适用哪种严重级别约定——默认（BLOCKER/MAJOR/MINOR/NIT）还是自定义？推荐：除非团队有书面替代方案，否则用默认。依据：Google Code Review Developer Guide。
  • 批注是锚定到具体 hunk，还是有些是一般性的？推荐：尽量全部锚定；一般性的归入未锚定区域。依据：SWE at Google 第 9 章——"评论必须引用具体行"。
  • <title> 和页眉用的 PR 标题是什么？推荐：实际的 PR/commit 标题。依据：docs-as-context-for-readers。
  • LGTM 标记是否应作为审批条输出？推荐：如果没有严重级别批注则输出；否则以发现的问题优先。

与其他工具的区别

  • md-document：那个转换器渲染散文 + 表格 + 代码 + callout；本工具渲染 diff hunk + 边距批注。
  • md-slides：那个转换器按 --- 边界切分；本工具是单页产物。
  • GitHub PR 评论：那是讨论线程；本工具是单一作者的快照产物。

输出产物

{default_output_dir}/review-{slug}.html（路径由 orchestrator 的 output_path_resolver.py 解析；默认冲突后缀为 -2、-3……）。

适用场景与限制

适用：把带 diff 块和严重级别标注的代码评审 Markdown 转成便于阅读的单页 HTML。

限制：输入过短（少于 100 行）、没有 diff hunk、缺 --reviewer、或设计系统未接入时会被拒绝；输入类型不符时应改用 md-document 或 md-slides。