M6 详细设计：治理热点排序与质量基线设计

这份详细设计文档用于描述 M6 的核心设计：如何把已有的站点治理总览，继续推进成具备优先级判断和回归校验能力的治理闭环。

设计目标

M6 要解决两个问题：

• 治理工作应该优先做哪一块
• 新改动是否让已知问题变得更糟

一、热点模块设计

1.1 模块维度统计

在原始 Markdown 巡检过程中，按顶层模块累计下面几类数据：

• Markdown 数量
• 缺少一级标题数
• 空文件数
• 资源缺失数
• 文件名尾部空格数
• 重复标题影响数

1.2 治理得分

为了形成简单可用的优先级排序，本轮采用权重分数：

• 缺少一级标题 × 3
• 资源缺失 × 4
• 空文件 × 5
• 重复标题 × 2
• 文件名尾部空格 × 1

该得分不是绝对正确的质量评分，而是用于帮助当前阶段快速排治理优先级。

1.3 站点治理页展示

治理页新增：

• 热点模块卡片
• 建议治理路径

这样维护者进入治理页后，可以直接看到“先治理哪个模块更划算”。

二、质量基线设计

2.1 基线文件职责

基线文件用于固化一组已知质量指标，作为后续回归比较参照。

本轮采用独立 JSON 文件：

• scripts/docs-quality-baseline.json

2.2 当前纳入基线的指标

• placeholderCount
• missingTitleCount
• missingAssetCount
• duplicateTitleCount

这些指标都具有：

• 能被稳定计算
• 能体现质量回升或回退
• 不依赖页面访问环境

三、docs:check 回归比较设计

3.1 比较策略

docs:check 在读取最新巡检报告后，会与基线进行比较。

若下面任一指标高于基线，则判定为回归：

• 占位/空文件数量
• 缺少一级标题数量
• 缺失资源数量
• 重复标题数量

3.2 输出策略

本轮比较结果同时输出到：

• CLI 日志
• GitHub Actions step summary

如果发生回归，则命令失败。

四、CI 归档设计

在 docs-check.yml 中追加质量报告产物上传：

• 产物名：docs-quality-report
• 文件：docs-site/.vitepress/generated/quality-report.json

这样可以让每次检查的巡检结果都能在 CI 中被保留。