publish-knowledge-health-checker

SKILL.md

---
name: knowledge-health-checker
description: 知识库健康检查器 - 超越市面上水平的知识库质量诊断工具。检测空壳文件、断链、内容密度、知识网络完整性，生成可视化健康报告卡片，提供自动修复建议。支持Obsidian/Notion/Logseq/Markdown多格式。触发词：知识库检查、wiki健康、断链检测、空壳文件、知识库质量、lint wiki、knowledge health、check knowledge。
---

# 知识库健康检查器

> 你的知识库是活的，不是死的。让它呼吸。

## 核心理念

市面上的检查工具只做一件事：检测有没有坏东西。

**我们做三件事：**
1. 检测问题（空壳、断链、孤立）
2. 分析健康度（内容密度、网络连接、主题分布）
3. 给出生机（可视化报告 + 修复建议 + 自动修复脚本）

不只是"告诉你哪里坏了"，而是"帮你让它变好"。

---

## 适用场景

- Obsidian用户：检测断链、未连接的笔记
- Notion导出用户：检查格式一致性、空页面
- Logseq用户：分析graph密度、孤立block
- Markdown知识库：内容质量综合评估
- 知识库重构前：做一次全面体检，避免搬砖式迁移

---

## 执行流程

### Phase 0: 扫描确认（用户检查点）

**先确认知识库路径和预期**：
```
扫描目录：~/.openclaw/workspace/memory/ [默认]
文件总数：预计 ~600-800个
预估时间：640个文件约20秒

确认：开始扫描？(y/n)
```

**扫描策略**：
- 递归扫描所有.md文件
- 排除隐藏文件（.开头）和系统文件（node_modules/、.git/）
- 实时进度展示：每扫描100个文件更新一次
- 支持中断恢复：从进度文件恢复上次扫描位置

**进度展示**：
```
扫描中：[████████████░░░░░░░░] 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](url)` → 可选检查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: 知识网络完整性

**定义**：分析知识库的连接结构，发现孤岛和中心节点。

**构建知识图谱**：
- 节点 = 文件
- 边 = 内链关系（A→B表示A链接到B）

**分析指标**：
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报告，包含：
- 总体健康评分（0-100分）
- 各维度得分（空壳、断链、密度、网络）
- 问题分布饼图
- 修复建议清单
- 一键修复按钮（生成脚本）

**报告模板**：
```html
<!-- assets/report_templates/health_report.html -->
<div class="health-card">
  <div class="score-circle">
    <div class="score">78</div>
    <div class="label">健康分</div>
  </div>
  <div class="metrics">
    <div class="metric">
      <span class="name">空壳文件</span>
      <span class="value">12个</span>
      <span class="trend">↑3</span>
    </div>
    <!-- ... 更多指标 -->
  </div>
  <div class="actions">
    <button onclick="generateFixScript()">生成修复脚本</button>
    <button onclick="exportReport()">导出PDF</button>
  </div>
</div>
```

**输出**：`health-report-YYYYMMDD-HHMM.html`，自动在浏览器打开。

### Phase 6: 自动修复建议

**修复策略**：
1. **空壳文件**：
   - 原则：删除无意义占位，补充有价值的框架
   - 生成：批量删除脚本或补充模板

2. **断链**：
   - 策略：搜索相似文件名，推荐替换目标
   - 生成：sed替换脚本或交互式修复工具

3. **孤岛文件**：
   - 判断：有内容但无链接 = 建议连接；无内容 = 建议删除
   - 生成：批量添加链接脚本

4. **过长文件**：
   - 策略：按H2标题拆分
   - 生成：拆分脚本和索引生成

**输出格式**：
```bash
#!/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-h2

echo "修复完成，请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
可视化报告生成：
- HTML模板渲染
- 评分计算
- 图表生成（可选Chart.js）

### scripts/auto_fix.py
修复脚本生成：
- 批量删除建议
- 断链修复建议
- 拆分建议

---

## 评分标准

| 维度 | 权重 | 满分标准 |
|------|------|----------|
| 空壳文件率 | 25% | 0个空壳 |
| 断链接率 | 30% | 0个断链 |
| 内容密度 | 25% | 80%文件健康 |
| 网络完整性 | 20% | 孤岛<5% |

**健康分 = Σ(维度得分 × 权重)**

---

## 错误处理与边界条件

### 超时保护
- 单个文件处理超时：跳过并记录到`skipped_files.json`
- 整体扫描超时：每100个文件保存一次进度，支持中断恢复
- 大文件处理：>5MB的文件单独标记，建议手动检查

### 内存保护
- 流式处理：不一次性加载所有文件到内存
- 进度保存：每100个文件保存一次中间结果
- 恢复机制：从`progress.json`恢复上次扫描位置

### 编码处理
- 优先UTF-8，失败后尝试GBK、GB2312
- 无法解码的文件记录到`encoding_errors.json`

### 排除规则
- 隐藏文件（.开头）
- 系统目录（node_modules/、.git/、__pycache__/、.obsidian/）
- 用户自定义排除（支持正则表达式）

---

## 与竞品差异

| 功能 | 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（更严格）。

---

## 最后

你的知识库像花园。
不只是除草，还要修剪、施肥、规划新的花坛。

检查是手段，健康是目的。