html-review

html-review Skill

何时使用本 Skill

在 doc-formatter 的路线 A 和路线 B 流水线中，每次 HTML 输出后调用本 skill 执行质量门禁：

• 路线 A：每次 doc-typeset 输出 HTML 后调用
• 路线 B：每次 doc-edit 输出 HTML 后调用

若检测不通过，将修正反馈返回对应 skill（路线 A → doc-typeset；路线 B → doc-edit）做一次定向修正，修正后直接输出，不再复检、不循环。

职责

执行 6 维度 HTML 质量门禁检测，输出结构化 HtmlReviewReport。安全性维度（SC-01~SC-06）为一票否决维度；其余 5 维度参与综合分计算。检测不通过时，生成可操作的修正建议返回给上游 skill。

执行方式（脚本化，0 次 LLM 往返）

6 个维度的检测项全部为确定性规则（正则匹配、标签计数、结构解析、class/属性存在性判断），已由 scripts/review_html.py 完整实现（纯 Python 3 标准库，零第三方依赖）。本 skill 直接运行脚本并解析其 JSON 输出作为 HtmlReviewReport，无需读取 references/ 逐条人工检测，无需任何 LLM 推理往返。

python3 scripts/review_html.py --html <html_path> --genre <genre>
# 或从 stdin 读取：
cat <html_path> | python3 scripts/review_html.py --stdin --genre <genre>

• stdout 输出即为完整 HtmlReviewReport（JSON）。
• 退出码：0 = 通过（passed=true）；1 = 不通过（passed=false）；2 = 运行错误（输入缺失/为空）。
• 脚本失败（退出码 2 或异常）→ 视为 review_skill_failed，由 doc-formatter 输出当前最佳 HTML（见 doc-formatter §7）。

references/ 目录下的规则文件是脚本实现的规则来源与说明，仅供维护脚本时对照，运行时无需加载。

输入契约

interface HtmlReviewInput {
  html: string;           // doc-typeset 输出的完整 HTML 字符串
  design_tokens: object;  // 与排版时相同的 design token 对象
  genre: string;          // 文档类型（government-doc / legal-contract / academic-paper 等）
}

输出契约

interface HtmlReviewReport {
  passed: boolean;          // 整体是否通过（score ≥ 80 且所有维度 passed）
  score: number;            // 综合质量分 0-100（安全性维度不参与计算）
  dimensions: {
    design_token_compliance: DimensionResult;
    structural_integrity:    DimensionResult;
    typographic_quality:     DimensionResult;
    genre_fit:               DimensionResult;
    decoration_usage:        DimensionResult;
    security:                DimensionResult;  // 一票否决维度
  };
  actionable_feedback: string[];  // 可操作的修正建议列表（优先级排序）
}

interface DimensionResult {
  passed: boolean;
  score: number;    // 该维度得分 0-100
  issues: string[]; // 发现的问题列表
}