M5 详细设计：站点治理页与校验流程设计

这份详细设计文档用于描述 M5 的核心设计：如何在不改变站点“生成优先”主架构的前提下，为知识库增加质量巡检、治理总览和 CI 校验能力。

设计目标

M5 的设计目标有三点：

• 质量问题可被自动发现
• 质量问题可在站内被看见
• 构建与巡检可被本地和 CI 复用

一、质量巡检数据设计

1.1 巡检对象

巡检对象仍然是仓库中的原始 Markdown 文件，而不是 docs-site 生成结果。

原因：

• 原始文件才是真正需要治理的内容源
• 生成目录会被反复覆盖，不适合作为质量来源
• 标题、资源链接、空文件等问题都应在源文件层识别

1.2 巡检维度

本轮巡检聚焦下面几类高价值问题：

• Markdown 总量
• 强制占位页与空文件数量
• 缺少一级标题的文档
• 本地资源缺失链接
• 重复标题
• 文件名尾部空格

1.3 数据产物

巡检结果输出为两份：

• docs-site/.vitepress/generated/quality-report.json
• 站点治理/index.md

前者用于程序校验与脚本复用，后者用于站内展示。

二、站点治理页设计

2.1 页面定位

站点治理页是一个面向维护者的站内总览页，不强调读者浏览深度，而强调：

• 现在有哪些质量问题
• 问题数量大概多少
• 从哪里开始治理更划算

2.2 页面结构

页面结构分为：

1. 巡检概览统计
2. 重复标题关注项
3. 缺少一级标题文档
4. 缺失资源引用
5. 治理建议

2.3 展示方式

继续复用 M4 已引入的：

• SiteStatGrid
• SiteDataGrid

不新增新的复杂组件，避免治理页单独演化出一套 UI 体系。

三、本地校验命令设计

3.1 命令职责

docs:check 负责：

1. 执行构建
2. 确认关键产物存在
3. 确认治理报告生成
4. 输出巡检摘要

3.2 校验范围

至少校验：

• index.html
• robots.txt
• sitemap.xml
• quality-report.json
• 内容导航/ 页面
• 专题导航/ 页面
• 站点治理/ 页面
• 示例专题详情页

四、CI 设计

4.1 新工作流定位

新增 docs-check.yml，仅负责构建与校验，不负责部署。

这样可以把：

• 质量校验
• 发布部署

拆成两条职责明确的工作流。

4.2 触发策略

本轮先采用保守策略：

• PR 到 master
• push 到 dev-vitepress
• push 到 master
• 手工触发

五、自测设计

本轮至少执行：

• npm run docs:sync
• npm run build
• npm run docs:check
• npm run preview -- --port 4173
• 校验首页、内容导航、专题导航、站点治理页访问状态