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/<slug>.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/<slug>.md` | 来源摘要，记录 SHA-256、提取的概念/实体 | | **concept** | `wiki/concepts/<slug>.md` | 概念页，含定义、置信度、来源计数、演化日志 | | **entity** | `wiki/entities/<slug>.md` | 实体页（人/工具/机构/论文），含贡献和关联 | | **synthesis** | `wiki/synthesis/<topic>-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 模式。所有代码和模板可自由修改以适配你的领域。