lambdagent/docs/wiki-v2.md

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 创建断链占位页 + 重建索引

用法:

{"action": "WikiLint", "input": {"auto_fix": true}}

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

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

功能:

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

用法:

{"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 图谱