文档知识库健康度评分体系设计 + Python 采集脚本（覆盖 6 个核心维度）

背景

我负责一个技术产品文档站（约 1200 篇文档、4 个产品版本线）的持续维护。目前团队对"文档质量好不好"只能靠主观感受：用户反馈零散、编辑排期拍脑袋、管理层要数据时拿不出来。我需要一套可量化、可复现的文档知识库健康度评分体系，把"文档到底健不健康"变成一组可追踪的数字。

最终要什么

一份评分体系设计文档 + 一套可落地的 Python 采集/计算脚本，让团队每周跑一次就能出分，并能按产品线、文档类型、时间趋势做切片分析。

6 个核心维度（评分体系需覆盖）

1. 覆盖度：API / 功能点 vs 已有文档的映射完整率（需定义"功能点清单"的采集方式）
2. 新鲜度：文档最后更新时间 vs 对应代码/产品版本的发布时间的偏差分布
3. 可发现性：站内搜索词 → 文档命中率的代理指标（基于站内搜索日志或 sitemap 关键词覆盖）
4. 一致性：跨文档术语冲突率、交叉引用断链率
5. 用户满意度代理：文档页平均停留时长 / 跳出率 / 反馈按钮正负比（用模拟数据说明计算口径即可）
6. 结构健康度：文档树深度分布、单篇长度异常值（过长/过短）、无标签/无分类文档占比

每个维度给出：定义、计算公式（含边界处理）、权重建议、数据来源、采集频率、评分区间（0–100）。

输入与上下文

• 文档站技术栈：MkDocs Material + Git 仓库管理（约 1200 个 .md 文件）
• 搜索日志：JSON Lines 格式，字段含 query, clicked_doc_id, timestamp, user_id（可脱敏）
• 产品版本发布记录：CSV，字段含 version, release_date, features[]
• 现有术语表：YAML，约 300 条
• 不需要对接真实系统，脚本用模拟数据跑通即可，但接口层要留好真实数据源切换的 hook

交付格式

1. 设计文档（Markdown，≥2000 字）：6 个维度的定义、公式、权重、边界条件、评分区间，附 1 个完整的加权总分计算示例
2. Python 脚本（单文件或小型 package，Python 3.10+）：
   • collect.py：从 6 类数据源采集原始指标（用内置 mock 数据，接口可切换）
   • score.py：按权重计算各维度分 + 总分，输出 JSON + 人可读的 Markdown 报告
   • report.py：生成趋势图（matplotlib，至少 4 周模拟数据）
   • main.py：一键入口 python main.py --period 4w
3. 模拟数据集（JSON/CSV/YAML）：让脚本开箱即跑
4. README.md：安装依赖、运行命令、预期输出示例

不需要做的

• 不需要部署到生产环境
• 不需要前端 dashboard（Markdown 报告 + 图片即可）
• 不需要对接 CI/CD