publish-knowledge-health-checker
by @xb19960921
知识库健康检查器 - 超越市面上水平的知识库质量诊断工具。检测空壳文件、断链、内容密度、知识网络完整性，生成可视化健康报告卡片，提供自动修复建议。支持Obsidian/Notion/Logseq/Markdown多格式。触发词：知识库检查、wiki健康、断链检测、空壳文件、知识库质量、lint wiki、know...
clawhub install publish-knowledge-health-checker📖 About This Skill
name: knowledge-health-checker description: 知识库健康检查器 - 超越市面上水平的知识库质量诊断工具。检测空壳文件、断链、内容密度、知识网络完整性，生成可视化健康报告卡片，提供自动修复建议。支持Obsidian/Notion/Logseq/Markdown多格式。触发词：知识库检查、wiki健康、断链检测、空壳文件、知识库质量、lint wiki、knowledge health、check knowledge。
知识库健康检查器
> 你的知识库是活的，不是死的。让它呼吸。
核心理念
市面上的检查工具只做一件事：检测有没有坏东西。
我们做三件事： 1. 检测问题（空壳、断链、孤立） 2. 分析健康度（内容密度、网络连接、主题分布） 3. 给出生机（可视化报告 + 修复建议 + 自动修复脚本）
不只是"告诉你哪里坏了"，而是"帮你让它变好"。
适用场景
执行流程
Phase 0: 扫描确认（用户检查点）
先确认知识库路径和预期：
扫描目录：~/.openclaw/workspace/memory/ [默认]
文件总数：预计 ~600-800个
预估时间：640个文件约20秒确认：开始扫描？(y/n)
扫描策略：
进度展示：
扫描中：[████████████░░░░░░░░] 240/640 (37.5%) | 预计剩余12s
Phase 1: 空壳文件检测
定义：文件存在但内容低于阈值，或内容只有"TODO占位"。
检测标准： 1. 内容长度：< 200字符 = 空壳 2. 结构完整度：缺少标题（#开头的行） 3. 占位符检测：内容中包含"待补充"、"TODO"、"占位" 4. 图片文件数：>3个且文字<100字符 = 纯图片笔记
输出格式：
空壳文件清单：
┌─────────────────────────┬──────────┬─────────────────────────┐
│ 文件名 │ 类型 │ 建议 │
├─────────────────────────┼──────────┼─────────────────────────┤
│ theory-gap.md │ 内容过短 │ 补充定义/方法/案例 │
│ 待研究.md │ 占位符 │ 删除或开始撰写 │
│ product-sketch.png.md │ 纯图片 │ 添加图片说明文字 │
└─────────────────────────┴──────────┴─────────────────────────┘
Phase 2: 断链检测
定义：Wiki链接指向不存在的文件或锚点。
链接类型检测：
1. 文件链接：[[filename]] → 检查文件是否存在
2. 锚点链接：[[filename#heading]] → 检查文件和锚点是否存在
3. 外部链接：text → 可选检查HTTP 200（需用户确认，耗时）
4. 相对路径：../path/to/file → 检查路径有效性
检测策略：
输出格式：
断链清单：
┌─────────────────────────┬──────────┬─────────────────────────┐
│ 源文件 │ 链接类型 │ 目标（不存在） │
├─────────────────────────┼──────────┼─────────────────────────┤
│ quantum-mechanics.md │ 文件链接 │ [[wave-function]] │
│ design-system.md │ 锚点链接 │ [[#best-practices]] │
│ research-links.md │ 外部链接 │ https://broken-url │
└─────────────────────────┴──────────┴─────────────────────────┘
Phase 3: 内容密度分析
定义：分析文件的内容质量，不是简单看字数。
分析维度： 1. 字数分布： - 过短（<300字）：内容单薄 - 适中（300-3000字）：健康 - 过长（>3000字）：建议拆分
2. 结构质量： - 标题层级（H1/H2/H3分布） - 列表密度（有序/无序列表占比） - 代码块数量（技术类文档） - 表格数量（数据类文档）
3. 链接密度： - 内链数：链接到知识库内部的其他文件 - 外链数：外部引用 - 无内链 = 孤岛文件
4. 更新时间： - 最近修改时间（mtime） - 长期未更新（>90天）：标注为"待回顾"
输出格式：
内容密度分析：
┌─────────────────────────┬────────┬────────┬────────┬────────┐
│ 文件名 │ 字数 │ 结构分 │ 内链数 │ 状态 │
├─────────────────────────┼────────┼────────┼────────┼────────┤
│ machine-learning.md │ 2800 │ 85 │ 12 │ ✅健康 │
│ quick-note.md │ 120 │ 30 │ 0 │ ⚠️孤岛 │
│ legacy-theory.md │ 5400 │ 70 │ 3 │ ⚠️过长 │
└─────────────────────────┴────────┴────────┴────────┴────────┘
Phase 4: 知识网络完整性
定义：分析知识库的连接结构，发现孤岛和中心节点。
构建知识图谱：
分析指标： 1. 孤立节点：没有入边也没有出边的文件 2. 中心节点：度数>10的文件（被广泛引用） 3. 弱连接：单向链接（A→B但B不回链A） 4. 环路检测：是否存在循环引用 5. 连通分量：知识库是否是一个连通图，还是分裂成多个孤岛
输出格式：
知识网络分析：
总节点数：347
连通分量：3个（主图322节点，孤岛A 18节点，孤岛B 7节点）
孤立节点：5个（完全未连接）
中心节点：8个（被引用>10次）
弱连接：42对（单向链接） 孤立节点建议：
┌─────────────────────────┬─────────────────────────┐
│ 孤岛文件 │ 连接建议 │
├─────────────────────────┼─────────────────────────┤
│ draft-idea.md │ 链接到[[thinking]]或删除 │
│ temp-research.md │ 整合到主话题或归档 │
└─────────────────────────┴─────────────────────────┘
Phase 5: 可视化健康报告卡片（用户检查点）
生成前展示摘要：
检测完成！发现以下问题：
空壳文件：12个
断链：8个
孤立节点：15个
健康分：78分 是否生成完整报告？(y/n)
生成机制：使用Python脚本生成HTML报告，包含：
报告模板：
78
健康分
空壳文件
12个
↑3
输出：health-report-YYYYMMDD-HHMM.html，自动在浏览器打开。
Phase 6: 自动修复建议
修复策略： 1. 空壳文件： - 原则：删除无意义占位，补充有价值的框架 - 生成：批量删除脚本或补充模板
2. 断链： - 策略：搜索相似文件名，推荐替换目标 - 生成：sed替换脚本或交互式修复工具
3. 孤岛文件： - 判断：有内容但无链接 = 建议连接；无内容 = 建议删除 - 生成：批量添加链接脚本
4. 过长文件： - 策略：按H2标题拆分 - 生成：拆分脚本和索引生成
输出格式：
#!/bin/bash
auto-fix-20260418-1055.sh
知识库自动修复脚本（需人工审查后执行）
1. 删除空壳文件
rm "memory/drafts/待研究.md"
rm "memory/temp/quick-note.md"2. 修复断链（搜索相似文件名）
sed -i '' 's/\[\[wave-function\]\]/[[wave-function-theory]]/g' "memory/physics/quantum-mechanics.md"3. 拆分过长文件
python3 scripts/split_long_file.py "memory/legacy/theory.md" --by-h2echo "修复完成，请review更改后commit"
使用方式
快速体检（默认）
用户："检查一下我的知识库健康度"
→ Phase 0-5，生成HTML报告，浏览器打开
→ 展示：健康分、问题分布、修复建议
深度分析（含网络）
用户："深度分析我的知识库网络结构"
→ Phase 0-4 + Phase 6
→ 额外输出：连通分量图、中心节点列表、弱连接清单
只检测不修复
用户："只检测问题，不要生成修复脚本"
→ Phase 0-4，跳过Phase 5-6
→ 输出：纯文本诊断报告
生成修复脚本
用户："生成修复脚本"
→ 基于之前的检测结果，执行Phase 6
→ 输出：auto-fix-YYYYMMDD-HHMM.sh
→ 提示用户审查后执行
定期检查（Cron集成）
用户："每周日自动检查知识库"
→ 生成cron任务：每周日09:00执行
→ 输出：发送到飞书/邮件/控制台
工具脚本
scripts/health_check.py
核心检测引擎：scripts/report_generator.py
可视化报告生成：scripts/auto_fix.py
修复脚本生成：评分标准
| 维度 | 权重 | 满分标准 | |------|------|----------| | 空壳文件率 | 25% | 0个空壳 | | 断链接率 | 30% | 0个断链 | | 内容密度 | 25% | 80%文件健康 | | 网络完整性 | 20% | 孤岛<5% |
健康分 = Σ(维度得分 × 权重)
错误处理与边界条件
超时保护
skipped_files.json内存保护
progress.json恢复上次扫描位置编码处理
encoding_errors.json排除规则
与竞品差异
| 功能 | Obsidian Linter | Logseq Linter | 我们 | |------|----------------|---------------|----------| | 空壳检测 | ❌ | ❌ | ✅ | | 断链检测 | ✅ | ✅ | ✅ | | 内容密度 | ❌ | ❌ | ✅ | | 知识网络 | ❌ | ❌ | ✅ | | 可视化报告 | ❌ | ❌ | ✅ | | 自动修复 | ❌ | ❌ | ✅ | | 多平台支持 | 只Obsidian | 只Logseq | ✅全平台 |
性能预期
| 文件数量 | 预估时间 | 内存占用 | |---------|---------|---------| | < 100 | < 3秒 | < 50MB | | 500 | < 10秒 | < 200MB | | 1000 | < 20秒 | < 500MB | | > 5000 | 建议分段扫描 | 按需分配 |
实战案例
案例1：知识库全面体检
用户："检查一下我的知识库健康度"
→ 执行：health_check.py ~/.openclaw/workspace/memory
→ 结果：640个文件，健康分56.4
→ 发现：12个空壳文件、8个断链、15个孤立节点
→ 生成：health-report-20260418.html
→ 动作：浏览器自动打开报告
案例2：修复断链
用户："我的知识库有很多断链，帮我修复"
→ 执行：report_generator.py → auto_fix.py
→ 生成：auto-fix-20260418.sh（包含8个sed命令）
→ 动作：用户审查后执行bash auto-fix-20260418.sh
→ 结果：8个断链已修复
案例3：定期检查（Cron集成）
用户："每周日自动检查知识库"
→ 配置cron：0 9 * * 0 /path/to/health_check.py
→ 输出：发送到飞书或邮件
→ 效果：知识库质量持续监控
常见问题FAQ
Q: 扫描很慢怎么办？ A: 可能原因：1) 文件数量太多（>5000），建议分段扫描；2) 文件很大（>5MB），建议单独处理；3) 磁盘IO瓶颈，建议用SSD。
Q: 报告打不开怎么办？ A: 1) 检查浏览器是否支持HTML5；2) 检查文件路径是否正确；3) 检查是否有权限问题；4) 尝试其他浏览器。
Q: 修复脚本执行失败怎么办？ A: 1) 检查是否在正确目录执行；2) 检查文件是否存在；3) 检查是否有权限；4) 手动review脚本内容后再执行。
Q: 如何排除某些目录？ A: 在SKILL.md的"错误处理与边界条件"章节有详细说明，可以在命令行传入exclude_dirs参数。
Q: 如何自定义空壳文件阈值？ A: 默认200字符，可以通过min_chars参数调整。例如：min_chars=100（更宽松）或min_chars=500（更严格）。
最后
你的知识库像花园。 不只是除草，还要修剪、施肥、规划新的花坛。
检查是手段，健康是目的。