# LLM Wiki 知识库 v2 — 知识管理三步流程 + 持续生长

> 基于 Karpathy LLM Wiki 模式，v2 实现完整的 Ingest → Query → Lint 三步流程，
> 新增交叉引用、过期检测、自动修复和主动生长机制。

## 1. 核心理念

### RAG 的问题

常见 RAG 流程：文档 → 切块 → 塞向量库 → 查的时候捞出来 → 让模型现编。
每次提问都像一个昨晚没睡好的实习生：重新读材料、重新组织语言、重新犯差不多的错。

### Wiki 的解法

LLM Wiki 不是检索，而是**知识编译**：
- Ingest 时 LLM 阅读理解，将知识写入结构化的 wiki 页面
- Query 时直接查已编译的 wiki 页面，不需要从碎片重搜
- Wiki 越用越丰富——持续生长

## 2. 三步流程 (v2)

### 第一步: Ingest (资料导入)

```
新资料 → 抽取要点 → 补充交叉引用 → 更新相关页面 10+
```

**v2 新增能力**:

| 能力 | v1 | v2 |
|------|----|----|
| LLM 提取结构化信息 | ✅ | ✅ |
| 创建 source/entity/topic 页面 | ✅ | ✅ |
| **补充交叉引用** | ❌ | ✅ 扫描已有页面，自动补 `[[链接]]` |
| **反向更新相关页面** | ❌ | ✅ 已有实体页追加新来源引用 + 更新时间戳 |

**实现函数**:
- `_cross_reference_new_pages()` — 扫描已有页面，找提到新实体但没有 `[[链接]]` 的，自动补上
- `_update_related_pages()` — 让已有实体/主题页反向引用新源文件

**效果**: 一个源文件触及 10-15 个 wiki 页面，不仅创建新页面，还主动链接和更新已有页面。

### 第二步: Query (信息查询)

```
直接查 Wiki 页面 → 综合多页信息 → 生成回答
```

**v2 新增能力**:

| 能力 | v1 | v2 |
|------|----|----|
| 关键词搜索 | ✅ | ✅ |
| **实体页优先** | ❌ | ✅ entities/ 权重 ×3，topics/ ×2 |
| **标签路由** | ❌ | ✅ 匹配 front matter tags |
| **[[链接]]跟踪** | ❌ | ✅ 读 top 页面的 `[[链接]]`，补充相关页面 |

**实现函数**:
- `_find_relevant_pages_v2()` — 替代 v1 的简单关键词匹配

**效果**: 查询 "JWT" 时，不仅找到 `entities/jwt.md`，还自动跟踪其中的 `[[OAuth]]`、`[[认证系统]]` 等链接，综合多页信息回答。

### 第三步: Lint (知识库检查)

```
知识库检查 → 查矛盾 → 查孤岛页 → 查过期引用 → 揪出问题 → 自动修复
```

**v2 新增能力**:

| 能力 | v1 | v2 |
|------|----|----|
| 孤页检测 | ✅ | ✅ |
| 断链检测 | ✅ | ✅ |
| LLM 深度分析 | ✅ | ✅ |
| **过期检测** | ❌ | ✅ 检测 >90 天未更新的页面 |
| **自动修复** | ❌ | ✅ `auto_fix=true` 创建断链占位页 + 重建索引 |

**用法**:
```json
{"action": "WikiLint", "input": {"auto_fix": true}}
```

## 3. 持续生长: WikiGrow (v2 新增)

```
发现知识空白 → 自动创建占位页 → 补充交叉引用
```

**功能**:
1. 发现被 2+ 页面 `[[引用]]` 但无独立页面的概念 → 自动创建实体占位页
2. 发现被 3+ 源文件引用的实体 → 标记为"可综合"
3. 支持 `dry_run=true` 预览不执行

**用法**:
```json
{"action": "WikiGrow", "input": {"wiki_root": "./wiki"}}
{"action": "WikiGrow", "input": {"wiki_root": "./wiki", "dry_run": true}}
```

**效果**: Wiki 像有机体一样不断生长，主动发现和填补知识空白。

## 4. 生长指标: WikiStatus (v2 增强)

v2 的 `WikiStatus` 新增生长指标和健康评分：

```
📊 Wiki 状态 (v2)

  源文件页:    508
  实体页:      1410
  主题页:      1085
  总页数:      3004
  总大小:      13204 KB

  📈 生长指标
  交叉引用:    4521 个 (1.5/页)
  实体/源文件: 2.8
  主题/源文件: 2.1
  健康评分:    85/100
```

**健康评分**:
- 交叉引用 < 1.0/页 → -20 分
- 没有主题页 → -15 分
- 实体/源文件 < 1.0 → -10 分

## 5. 三层架构

```
╔═══════════════════════════════════════╗
║           用户交互层                    ║
║  Query (查询)      Lint (维护)          ║
╠═══════════════════════════════════════╣
║           LLM 处理层                    ║
║  Ingest      Query       Lint           ║
║  ├ 抽取要点   ├ 综合多页   ├ 查矛盾       ║
║  ├ 交叉引用   ├ 标签路由   ├ 查孤岛页     ║
║  └ 更新相关   └ 链接跟踪   ├ 查过期       ║
║                           └ 自动修复     ║
║                                         ║
║           WikiGrow (持续生长)            ║
║  发现缺失概念 → 创建占位页               ║
╠═══════════════════════════════════════╣
║         持久化知识层                    ║
║  Markdown Wiki 知识库 (持续生长)        ║
║  ├ index.md     (导航索引)              ║
║  ├ sources/     (源文件摘要)            ║
║  ├ entities/    (实体页面)              ║
║  ├ topics/      (主题综合)              ║
║  ├ analyses/    (查询结果)              ║
║  └ log.md       (操作日志)              ║
║                                         ║
║  核心概念: Obsidian + Markdown          ║
║  [[双括号]] 交叉引用 → 知识网络          ║
╚═══════════════════════════════════════╝
```

## 6. 工具清单

| 工具 | 功能 | v2 新增 |
|------|------|---------|
| `WikiIngest` | 喂文件 → 知识编译 → 交叉引用 → 更新相关 | ✅ 交叉引用 + 反向更新 |
| `WikiQuery` | 查询 → 综合多页 → 回答 | ✅ 实体优先 + 链接跟踪 |
| `WikiLint` | 健康检查 → 自动修复 | ✅ 过期检测 + auto_fix |
| `WikiSearch` | 关键词搜索 | - |
| `WikiStatus` | 统计 + 生长指标 + 健康评分 | ✅ 全部新增 |
| `WikiGrow` | 主动生长 → 创建缺失页面 | ✅ 全新工具 |

## 7. 受影响的文件

| 文件 | 改动 |
|------|------|
| `lambdagent/builtin_tools/wiki_tools.py` | 核心升级: Ingest 交叉引用 + Query v2 搜索 + Lint 过期/修复 + WikiGrow + WikiStatus 指标 |
| `lambdagent/builtin_tools/registry.py` | 注册 WikiGrow + 更新工具描述 |
| `agentexample/qaagent67wiki/agent-config.yml` | 更新 system prompt (三步流程) + 加入 WikiGrow |

## 8. 适用场景

| 场景 | 使用的 agent | 说明 |
|------|-------------|------|
| 海事法规问答 | qaagent67wiki | 1326 文档 → 3000+ wiki 页面 |
| 通用领域知识库 | qaagent67lambda | Wiki 作为 4 路检索之一 |
| 个人研究笔记 | agent67/agent67v2 | 通过 ResearchWorkflow 写入 wiki |
| Obsidian 知识管理 | 任意 agent | `[[双括号]]` 兼容 Obsidian 图谱 |