知识库健康扫描

解决什么问题

当笔记库随着时间不断膨胀，很容易积累看不见的结构问题：某次重命名或移动笔记后留下的 [[wikilink]] 变成了死链；一篇刚写完的想法因为没人引用，慢慢变成孤页；真正被反复查阅的核心笔记藏在几十层目录里找不到；还有一些已经超过 90 天没有更新过的页面，早就完成了生命周期却还留在活跃目录中。知识体检——知识库健康扫描 就是为这些痛点设计的只读扫描工具，让知识库维护像定期体检一样简单。

如何工作

health.py 会递归扫描目标目录下的所有 .md 文件，通过解析双链语法构建整张知识图谱。它会检查四个关键维度：

• 死链检测：识别指向不存在页面的 [[wikilink]]，支持 [[link|alias]] 形式的别名提取；
• 孤页发现：找出没有任何其他页面引用的孤立节点，这些往往是被遗忘的灵感碎片；
• 枢纽页分析：按被引用次数排序，帮你找到知识库里真正的核心页面；
• 陈旧页标记：找出超过设定天数（默认 90 天）未更新的页面，辅助归档决策。

除了默认参数，还可以通过 --stale 调整陈旧阈值，用 --exclude 或 --include 指定扫描范围，甚至加上 --json 参数输出结构化报告。你可以直接说“帮我做个知识库体检”，也可以在每月整理前跑一次，或者新人接手笔记库时用它快速摸清整体结构。

注意点与边界

工具是纯只读的，不会修改任何文件。它只关注内部 wiki 链接网络，不统计外部 HTTP 链接。如果扫描报告显示 0 页，请确认目录下确实有非空的 .md 文件，且没有被 --include 参数意外过滤。同名文件在不同目录下会被优先按文件名 slug 匹配，如果 slug 冲突则改用相对路径去重，确保死链判断和入链统计的准确性。对于文件明明存在却被报为死链的情况，可能是 pipe 前的文件路径有误或存在编码问题，可以结合排障 FAQ 逐一排查。

它是手动扫描工具，适合每月一次的定期维护，与自动化系统 灵台 的 24/7 巡更互补。和 quality-check 搭配使用效果更好——先用它看全局结构，再用 quality-check 逐页检查质量，形成完整的知识库管理闭环。