---
name: kb-index
tags: [knowledge-base, indexing, navigation, routing]
creator: 传鹏
description: |-
  知识库索引与导航维护。维护三层索引体系（业务地图 → 目录索引 → 页面摘要），处理页面合并/拆分后的索引修复、别名补充、业务地图重组。

  触发词：索引、找不到页面、知识库导航、重建索引、业务地图、合并页面、拆分页面、别名
---

# 索引维护

## 三层索引，各司其职

| 层 | 文件 | 谁写 | 回答什么问题 |
|---|---|---|---|
| L1 业务地图 | `10-知识库/index.md` | **人 + LLM** | "我该从哪个方向找" |
| L2 目录索引 | `*/_index.md` | **`kb.py graph` 自动生成** | "这个方向下有哪些页" |
| L3 页面摘要 | 每页 frontmatter 的 `summary` | **写页时顺手写** | "这页具体讲什么" |

**关键认知**：L2 已经是自动的，所以索引腐化的真正来源只有两处 ——
① L1 业务地图没人维护；② L3 的 `summary` 写得敷衍（写成"本文介绍了 XX"）。

---

## L1 业务地图怎么维护

`index.md` 的业务地图**按业务问题分区，不按文件类型分区**。

当前四个分区对应本公司的做课业务链：
- **A 市场与行业认知** —— 判断"卖什么课给谁"
- **B 客户与需求画像** —— 判断"这门课要解决什么问题"
- **C 课程内容与方法论** —— 课里装什么
- **D 交付与运营** —— 怎么落地、怎么复购

### 什么时候动它

| 触发 | 动作 |
|---|---|
| 新建了一个 topic 页 | 在对应分区挂一行 |
| 某个 topic 页被归档 | 删掉那一行 |
| 分区长期为空（>1 个月） | 要么它是真需求（去补料），要么删掉这个分区 |
| 出现新的业务线 | 加分区 |
| 用户说"我找不到 XX" | 说明地图的组织方式和用户的思维方式不一致 → 调整分区命名，别让用户适应系统 |

### 行怎么写

```md
| 客户决策链 | [topics/客户决策链.md](topics/客户决策链.md) | 2026-11-04 | 中（2 源） |
```

「可信度」列用源的数量和时效粗判：1 源 = 低，2–3 源 = 中，≥4 源且最近更新 = 高。

---

## 别名：解决"用户说的话和页面标题不一样"

在页面 frontmatter 加：

```yaml
aliases:
  - "企业内训"
  - "B端培训"
  - "公司培训"
```

`kb-query` 的 Level 2 会检索 aliases。**没有任何技术门槛，但这是检索命中率提升最明显的一招。**

给哪些页加：
- 客户/机构（全称、简称、英文名、项目代号）
- 方法论（正式名、俗称）
- 术语（中英文对照）

---

## 合并页面（拆多了的情况）

症状：两个页面的 `summary` 几乎一样，或者互相大量交叉引用。

步骤：
1. 选主体页（更新更频繁、入链更多的那个）
2. 把另一页的有效内容搬过去，**保留所有 `[^脚注]` 溯源**
3. 合并 `sources` 两个列表（去重）
4. 合并 `tags`、`related`
5. 被吞并的页 → 文件内容改成一行 `已合并至 [[主体页]]`，或者直接移入 `_archive/`
6. 全库替换 `[[被吞并页]]` → `[[主体页]]`
7. `kb.py graph` + `lint`

---

## 拆分页面（装太满的情况）

症状：一个 topic 页超过 1500 字，且明显有 2 个以上独立主题。

不要急着拆。先问：**读者会不会只想看其中一部分？** 会才拆。

拆完必须：
- 两个新页都要保留原 `sources` 中相关的部分
- 建一个 index 型页或让 `index.md` 业务地图同时指向两页
- 检查所有指向原页的反链，分派到两个新页

---

## 反链的价值

`[[X]]` 的指向关系会被 `kb.py graph` 解析成 `_meta/derivations.jsonl` 里的 `links` 边。

这个图有两个用途：
1. `kb-lint` 找孤儿页（零入链）
2. `kb.py retract` 做级联失效（删一页，找出所有依赖它的页）

**所以：正文里该链的地方不链，等于放弃了自动保鲜能力。** 一个页面如果被删了但没人链它，系统就不知道哪些内容受影响。

---

## 索引重建

任何时候索引看起来不对：

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

它做两件事：重建 `derivations.jsonl`（全部关系边）+ 重写四个 `_index.md`。
**不会动 `index.md` 和任何页面内容。**

如果你改了 `index.md` 的业务地图但发现行链接指向不存在的页面 → 那是页面被删了，跑 `lint` 找 `DEAD_LINK`。