md-review 是 Markdown 转 HTML 之前运行的质量门禁。转换器会照常渲染含多个 H1、死链、无 alt 图片和超长句子的文档，本技能在修复成本还低时捕获这些缺陷，并在阻断性问题出现时让构建失败。它按设计零网络调用：相对链接与锚点在磁盘上解析，外部 URL 只登记上报而不抓取。
用途包括：发布文档、指南或文章前审查；把文档 CI 门禁接入合并流程，只对真实缺陷阻断而不因风格阻断；审计存量 Markdown 语料，估算无障碍与链接腐烂债务；统一术语（如 front-end 与 frontend、GitHub 与 Github）；按 WCAG 中可经受转换的准则检查源内容；按读者校准文风（凌晨读的运行手册与 API 参考需要不同区间）。
使用前需明确：目标读者，它决定 Flesch 区间与年级上限；必需的前置元数据字段；阻断级别与警告预算，决定是审计还是门禁；语料是新建还是继承，继承语料应先只报告。配置来自样例 JSON，包含必需 frontmatter、结构与无障碍阈值、术语表和门禁设置。项目根目录在使用根相对链接时需提供。
工作流有三种：工作流一在发布前跑结构与 frontmatter/无障碍门禁、离线链接检查、可读性与术语评分三道脚本，任一非零退出即阻断；工作流二用 --fail-on never 与 JSON 输出审计语料，按规则频次排序后再启用门禁；工作流三按读者校准文风，先改写超长句，确认长句占比低于 10%。默认命令示例以仓库根目录为基准，使用 python3 运行三个脚本，并指定 --input、--config、--format、--root 等参数。
严重级别判定：读者可见、无歧义、可机械修复三者同时满足才算 error；断链、缺 alt、标题层级跳跃、表头缺失、必需 frontmatter 缺失为 error；过长段落、术语漂移、标题大小写、可读性区间为 warning；被动语态为 info。a11y.missing-alt 永不降级。可读性分读者给出 Flesch 区间与最大长句占比，仅下限阻断。句子长度：46 词以上为 error，31-45 为 warning，目标均值不超过 20 词且超 30 词句占比不超过 10%。WCAG 覆盖方面，源级检查可覆盖 1.1.1、1.3.1、2.4.4、2.4.9，2.4.6 为部分覆盖，1.4.3、2.1.1、4.1.2 需转换后 HTML 检查。退出码约定：0 通过，1 工具错误，2 门禁失败。
既有语料上线建议分四阶段：观察、仅变更文件、逐步收紧、稳态。文件包含 md_review_gate.py、link_checker.py、readability_scorer.py 三个脚本，以及规则手册、可读性与无障碍参考、样例配置、样例文章（含缺陷与干净版）和报告模板。反模式包括把网络链接检查放进合并门禁、对可读性上限阻断、术语表只增不减、首日要求零警告、使用内联抑制注释。离线检查不能证明完全符合 WCAG，对比度、键盘与无障碍树需另行验证；其他未在资料中说明的功能或限制暂未提供。