---
name: kb-lint
tags: [knowledge-base, quality, maintenance, health-check]
creator: 传鹏
description: |-
  知识库健康检查与修复。检测死链、孤儿页、陈旧页、源漂移、索引漂移、空壳页，按严重度分派修复，输出健康分与维护建议。

  触发词：检查知识库、库健康、整理得乱不乱、有没有死链、知识库体检、修复知识库、lint
---

# 知识库体检

## 跑起来

```bash
python 90-工具/kb.py check        # 结构 + 内容，两项一起过（推荐）
python 90-工具/kb.py lint --json  # 只查结构，机器可读
python 90-工具/check-content.py   # 只查内容（AI 腔 / 长句 / 没出处的数字）
```

`lint` 返回 `summary`（页数/源数/问题数/健康分/待重建数）+ `issues`（每条带 `kind`、`page`、`detail`）。
`check-content.py` 是另一个文件，因为**结构对了不等于内容能用**，两者职责不同，混在一起以后没人敢改。

**健康分算法**：`100 - 问题数×3 - 待重建数×2`，最低 0。
- ≥ 90 绿：健康
- 70–89 黄：能用，但有腐化
- < 70 红：结构性问题，停下来修

---

## 问题类型与修法

按**根因 → 表象**的顺序修。先修下面的，上面的会自动消失。

### 第一梯队（根因，必须先修）

| kind | 含义 | 修法 |
|---|---|---|
| `DANGLING_SOURCE` | 页面引用的源已不在 manifest | 分两种：① 源是被误删的 → 恢复文件后 `kb.py scan` + `mark`；② 源确实作废了 → `kb.py retract` 走正规回滚。**不要直接手改 frontmatter 删掉那条 sources**，那样 `sources` 与事实脱节，下次同步还会错 |
| `SOURCE_DRIFT` | 源文件内容变了，页面没更新 | 走 `kb-sync` 的 CHANGED 分支 |
| `STALE` | 页面被标记待重建 | 读完 `stale_reason` 再动手：源还在就重合成，源没了就降级为 draft 并在正文注明依据缺失 |

### 证据类（最容易被糊弄过去的一组）

| kind | 含义 | 修法 |
|---|---|---|
| `MISSING_EVIDENCE` | 页面没标 `evidence` | 按 `kb-ingest` 的「定证据等级」三问补上。拿不准就往低了定 |
| `BAD_EVIDENCE` | 等级写成了 A/B/C/D 以外的东西 | 改成单字母 |
| `EVIDENCE_INFLATED` | 声明的等级比它来源最低级还强 | **降级，不要改来源。** 合成不会提高证据强度。如果确实有更强的来源，先把那个源补进来 |
| `D_IN_MODULE` | 模块页是 D 级 | D 级是推断和假设，不许进课件。要么补证据升到 C 以上，要么把这段挪进「待验证」区 |

`EVIDENCE_INFLATED` 是这个库最隐蔽的腐化方式：一开始某个 topic 页只用了 1 份讲师经验（C），后来补了 3 份报告，作者顺手把等级改成 A —— 但那 3 份报告本身是 B 级测算，最低级仍是 B。等级只会被最弱的那条拖住。

### 第二梯队（结构问题）

| kind | 含义 | 修法 |
|---|---|---|
| `DEAD_LINK` | `[[X]]` 没有对应页面 | 三选一：① 页面名写错了 → 改链接；② 该页还没建 → 建它（有价值时）；③ 引用没意义了 → 删掉这句话连同链接 |
| `ORPHAN` | 无 sources 且无入链 | 孤立的知识碎片。要么挂到某个 topic 的 `related` 里、或在正文被引用；要么它其实是独立主题，那就从 `index.md` 业务地图里给个入口。**实在没价值就归档，别留着占地方** |
| `NO_FM` / `MISSING_FIELD` | frontmatter 缺失或不完整 | 补齐。`title`/`type`/`summary` 三个必须有，`summary` ≤ 40 字 |
| `THIN` | 正文 < 100 字 | 补内容，或者合并进别的页。空壳页比没有页更糟——它会让索引显得很丰满，实际查不到东西 |

---

## 修复动作的边界

- ✅ 改正文、补 frontmatter、改链接、合并页面
- ✅ 把无价值页面移入 `_archive/`
- ❌ 删原材料
- ❌ 改 `_index.md`（会被 graph 覆盖，改 frontmatter）
- ❌ 为了让 lint 数字好看而删问题条目（比如把坏链接删掉但不修内容）——**lint 是体检，不是评分游戏**

---

## 修完必做

```bash
python 90-工具/kb.py graph && python 90-工具/kb.py lint
```

分数没回去说明没修到根上。**别在分数没变的情况下汇报"已修复"。**

---

## 定期体检节奏

| 频率 | 检查什么 |
|---|---|
| 每次同步后 | 自动跑一次，只看有没有新增问题 |
| 每周 | 全量 lint + 清 rebuild_queue |
| 每月 | 看 `topics/_index.md`，找"同一件事拆成好几页"的；看长期没被引用的页，考虑合并；**抽 5 个 topic 页对比数字，看有没有互相打架** |
| 每季度 | 看 `index.md` 的业务地图是否还反映真实业务；删掉已不再做的业务分区 |

---

## 报告格式

```md
知识库体检 · 健康分 87/100（黄）

42 页 / 18 源 / 6 个问题 / 2 项待重建

根因（先修这两个）
1. DANGLING_SOURCE — topics/客户画像.md 引用了已删除的《2025客户访谈.docx》
   建议：源确实作废 → 跑 retract，用剩余 3 个源重合成
2. STALE — modules/D2-Agent编排.md 待重建

结构问题
3. DEAD_LINK ×3 — 都指向 `提示词案例集`（该页已归档）
   建议：改成直接引用 sources/提示词方法.md

顺手可做
- THIN — entities/某银行.md 只有 60 字，建议合并进 topics/客户画像
```