llm-wiki-builder
@user_7ffd653a/llm-wiki-builder
# LLM Wiki Builder
Karpathy 风格的 LLM Wiki 知识库构建系统。Wiki 是一个**持久的、复合增长的制品**：交叉引用已经存在，矛盾已经被标记，综合分析已经反映了你读过的一切。每次摄入和查询都让它变得更好。
> *"Wiki is a persistent, compounding artifact. Cross-references are already there. Contradictions are already flagged. The synthesis already reflects everything you've read."* — Andrej Karpathy
---
## 核心差异：Wiki vs 传统 RAG
| 维度 | 传统 RAG | LLM Wiki |
|------|---------|----------|
| 知识积累 | 无，每次从零检索 | 有，每次摄入都更新现有页面 |
| 交叉引用 | 查询时动态拼接 | 已写入页面，随时存在 |
| 矛盾处理 | 依赖 LLM 即时判断 | 显式标记在 Contradictions 节 |
| 维护成本 | 人工负担随规模增长 | LLM 自动维护，成本趋近于零 |
| 溯源能力 | 片段引用 | 精确到 `wiki/sources/.md` |
| 查询效率 | 需重新检索所有文档 | 直接读取已编译的 wiki 页面 |
---
## 系统架构：三层所有权
```
raw/ → 人类拥有，LLM 只读（来源真理）
wiki/ → LLM 完全读写（知识层）
CLAUDE.md → 行为契约，共同维护（规范层）
```
**铁律**：
- LLM **绝不自动执行**不可逆操作（merge、删除、confidence 升 high）——必须等人类确认
- 人类**绝不手动编辑** `wiki/` 目录下的内容页——所有编辑通过 LLM 完成
- 人类**只负责** `raw/` 目录的文件管理
- 模板文件有 `graph-excluded: true`——**根据模板创建的新页面必须删除此字段**
---
## 快速开始
### 1. 初始化（Agent 执行）
**前置：Agent 必须先询问用户知识库名称。**
```bash
python scripts/init.py <项目目录> --name "<知识库名称>"
```
脚本自动完成 10 步：
| 步骤 | 内容 |
|------|------|
| 1 | 创建目录结构（raw/、wiki/、outputs/、scripts/、.qmd/） |
| 2 | 生成系统文件（index.md、log.md、overview.md、QUESTIONS.md） |
| 3 | 生成 5 个页面模板 |
| 4 | 复制 schema.md |
| 5 | 生成 CLAUDE.md + AGENTS.md（行为契约） |
| 6 | 复制 lint.py（14 项健康检查） |
| 7 | 复制 registry.py（知识库注册管理） |
| 8 | 复制 list-wikis.py（全局知识库列表） |
| 9 | 生成 .gitignore |
| 10 | 注册到全局注册表 `~/.llm-wiki/registry.json` |
### 2. qmd 检测（可选，Agent 交互式）
qmd 提供语义搜索（BM25 + 向量嵌入 + LLM 重排序），**不安装不影响核心功能**。
```bash
qmd --version # 检测是否已安装
npm install -g @tobilu/qmd # 安装（需 Node.js >= 22）
qmd init && qmd collection add wiki wiki/
qmd embed # 首次下载约 2GB 模型
```
**模型明细**：
- embeddinggemma-300M ~300MB（向量嵌入）
- Qwen3-Reranker-0.6B ~640MB（结果重排）
- qmd-query-expansion-1.7B ~1.1GB（查询扩展）
**qmd 不可用时**：核心功能（ingest、query、lint）仍可运行，只是搜索降级为读取 `wiki/index.md`。详见 `references/setup-guide.md` §降级策略。
### 3. 安装依赖
```bash
pip install pyyaml
```
### 4. 运行审计
```bash
python scripts/lint.py
```
---
## 用户操作
| 触发词 | 操作 | 说明 |
|--------|------|------|
| `ingest` / `摄入` / `处理这个` | **摄入** | 读取 raw 文件，提取概念，创建/更新页面 |
| `batch ingest` | **批量摄入** | 多 subagent 并行处理 |
| 直接提问 / `根据我的知识库` | **查询** | 搜索 + 综合 + 溯源到 source 页 |
| `lint` / `检查` | **健康检查** | 14 项检查 + 报告 |
| `reflect` / `综合分析` | **深度分析** | 4 阶段：反向检验→模式扫描→合成→缺口分析 |
| `merge` / `去重` | **合并** | 页面去重，需确认 |
| `我想搞清楚` | **添加问题** | 追踪到 QUESTIONS.md |
| `audit` | **系统核查** | 全系统验证 |
| `切换知识库` / `list wiki` | **切换/查看** | 从注册表选择 |
### 查看所有知识库
```bash
python scripts/list-wikis.py # 文本格式
python scripts/list-wikis.py --json # JSON 供 Agent 解析
python scripts/list-wikis.py --path <名> # 获取指定知识库路径
```
---
## 页面类型
| 类型 | 路径 | 用途 |
|------|------|------|
| **source** | `wiki/sources/.md` | 来源摘要，记录 SHA-256、提取的概念/实体 |
| **concept** | `wiki/concepts/.md` | 概念页，含定义、置信度、来源计数、演化日志 |
| **entity** | `wiki/entities/.md` | 实体页（人/工具/机构/论文），含贡献和关联 |
| **synthesis** | `wiki/synthesis/-synthesis.md` | 综合分析，含论点、证据、反证、局限 |
| **personal-writing** | `raw/personal/` | 个人写作，不创建 source 页，不参与 source_count |
### 置信度分级
| 级别 | 标准 | 设置方式 |
|------|------|----------|
| **low** | 1-2 个来源，或来源间有矛盾 | 自动（1 来源） |
| **medium** | 3+ 个来源，信息一致 | 自动（3+ 来源） |
| **high** | 多元来源 + 无矛盾 | **候选，用户确认后设置**（铁律） |
### 时效分级
| 级别 | 领域 | Stale 阈值 |
|------|------|-----------|
| high | AI、加密货币、科技新闻 | 90 天 |
| medium | 法律、商业、政策 | 180 天 |
| low | 数学、哲学、历史 | 365 天 |
---
## 注册表管理
全局注册表位置：`~/.llm-wiki/registry.json`
```bash
python scripts/registry.py list # 列出所有知识库
python scripts/registry.py add <路径> [名称] # 注册新知识库
python scripts/registry.py use <名称> # 获取知识库路径
python scripts/registry.py remove <名称> # 取消注册（不删文件）
python scripts/registry.py rename <旧名> <新名> # 重命名
python scripts/registry.py get-last # 获取最近访问的知识库
```
---
## 14 项 Lint 检查
```bash
python scripts/lint.py # 只检测
python scripts/lint.py --fix # 交互修复
python scripts/lint.py --fix --auto # 自动修复安全项
```
| # | 检查项 | 说明 | 可修复 |
|---|--------|------|--------|
| 1 | YAML Frontmatter | 合法性、type/date 字段 | ❌ |
| 2 | Broken Wikilinks | 引用不存在的页面 | ❌ |
| 3 | Index 一致性 | index.md 引用 vs 实际页面 | ✅ safe |
| 4 | Stub 页面 | 正文 < 100 字 | ❌ |
| 5 | 近重复概念 | Jaccard 相似度 > 0.7 | ❌ |
| 6 | SHA-256 完整性 | 原始文件是否被篡改 | ❌ |
| 7 | Stale 页面 | 超时效阈值 | ❌ |
| 8 | 跨语言重复 | aliases 与 title 冲突 | ❌ |
| 9 | Wikilink 格式 | 禁止驼峰/下划线/空格 | ❌ |
| 10 | 孤立页 | 无入站链接 | ❌ |
| 11 | 缺失交叉引用 | concept 未反向引用 source | ❌ |
| 12 | 隐性盲区 | Related Concepts 引用不存在页 | ❌ |
| 13 | source_count 不一致 | 声明 vs 实际统计 | ✅ safe |
| 14 | Dashboard 不一致 | overview.md 数字 vs 实际 | ✅ safe |
---
## 目录结构
```
project/
├── raw/
│ ├── articles/ # 文章（转换后的 markdown）
│ ├── clippings/ # 网页剪藏
│ ├── images/ # 提取的图片
│ ├── notes/ # 笔记
│ ├── personal/ # 个人写作
│ └── originals/
│ ├── articles/ # 原始 PDF/DOCX
│ ├── clippings/ # 原始剪藏
│ ├── notes/ # 原始笔记
│ └── personal/ # 原始个人写作
├── wiki/
│ ├── sources/ # 来源摘要页
│ ├── concepts/ # 概念页
│ ├── entities/ # 实体页
│ ├── synthesis/ # 综合分析页
│ ├── templates/ # 页面模板
│ ├── index.md # 内容目录
│ ├── log.md # 时间线日志
│ ├── overview.md # 全局视图（含 Health Dashboard）
│ ├── QUESTIONS.md # 开放问题追踪
│ └── schema.md # 数据结构规范
├── outputs/ # 报告输出
├── scripts/
│ ├── lint.py # 健康检查
│ ├── registry.py # 注册表管理
│ └── list-wikis.py # 全局知识库列表
├── CLAUDE.md # 行为契约（Claude）
├── AGENTS.md # 行为契约（通用）
├── .gitignore
└── .qmd/ # 向量索引（qmd）
## 参考文件
| 文件 | 内容 |
|------|------|
| `references/Karpathy-mapping.md` | 与 Karpathy 方法论的对应关系 |
| `references/schema.md` | 数据模型、字段规范、关系规则 |
| `references/CLAUDE.md` | LLM 行为契约（INGEST/QUERY/LINT/REFLECT） |
| `references/setup-guide.md` | qmd 安装与降级策略 |
| `references/audit-checklist.md` | 系统审计清单（27 项规则 + 14 项检查） |
| `references/wikilink-rules.md` | Wikilink 语法速查 |
---
## 灵感来源
> *"The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. The part he couldn't solve was who does the maintenance. The LLM handles that."* — Andrej Karpathy
---
## 许可证
本 skill 为自托管知识库构建工具，遵循 Karpathy 的 LLM Wiki 模式。所有代码和模板可自由修改以适配你的领域。
下载 Zip 包安装
