前言¶

做个人知识库的人大多会遇到同一个问题：存了一堆 Markdown，检索靠全文搜索，越积越乱。传统 RAG 每次从零检索，交叉引用靠 LLM 临时拼接，矛盾点没有留痕，人工维护成本随规模上涨。llm-wiki-builder 走的是另一条路：维护一个持久的、复合增长的 wiki，交叉引用已经写进页面，矛盾显式标在 Contradictions 节，综合分析反映你读过的一切。

下面介绍这个 skill。它由社区开发者 user_7ffd653a 发布在 SkillHub，分类 knowledge-management，定位是 Karpathy 风格的 LLM Wiki 构建系统。

这是什么¶

llm-wiki-builder 是一个自托管的知识库构建工具，通过 init.py 一键生成目录结构、系统文件、页面模板、行为契约和健康检查脚本，并把知识库注册到全局注册表。知识分三层归属：raw/ 人类拥有、LLM 只读；wiki/ LLM 完全读写；CLAUDE.md 是双方共同维护的行为契约。

它解决的是「知识库的骨架和纪律」问题：目录怎么分、页面怎么命名、链接怎么写、哪些操作必须人工确认，都由脚本和契约预先定好，而不是每次让 LLM 临场发挥。

初始化：init.py 一键建库¶

先做初始化，再做后续操作。Agent 必须先询问用户知识库名称，然后执行：

python scripts/init.py <项目目录> --name "<知识库名称>"

脚本自动完成 10 步：创建 raw/、wiki/、outputs/、scripts/、.qmd/ 目录；生成 index.md、log.md、overview.md、QUESTIONS.md；生成 5 个页面模板；复制 schema.md；生成 CLAUDE.md 与 AGENTS.md；复制 lint.py（14 项检查）、registry.py、list-wikis.py；生成 .gitignore；最后注册到 ~/.llm-wiki/registry.json。

可选的语义搜索：qmd¶

qmd 提供 BM25 + 向量嵌入 + LLM 重排序的语义搜索，不安装不影响核心功能。先检测：

qmd --version

未安装则执行：

npm install -g @tobilu/qmd
qmd init && qmd collection add wiki wiki/
qmd embed

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 的降级策略一节。

安装依赖与首次审计¶

依赖只有 PyYAML：

pip install pyyaml

初始化完成后跑一次审计，确认骨架可用：

python scripts/lint.py

日常操作：摄入、查询、检查¶

资料写进 raw/，剩下的交给 Agent。常用触发词如下：

健康检查支持三种模式：

python scripts/lint.py              # 只检测
python scripts/lint.py --fix        # 交互修复
python scripts/lint.py --fix --auto # 自动修复安全项

14 项检查覆盖 YAML frontmatter、失效 wikilink、index 一致性、stub 页面、近重复概念、SHA-256 完整性、stale 页面、跨语言重复、wikilink 格式、孤立页、缺失反向引用、隐性盲区、source_count 一致性、dashboard 一致性。其中 index 一致性、source_count、dashboard 三类标为 safe，可用 --auto 自动修复，其余需要人工判断。

页面类型与置信度¶

页面分五类：wiki/sources/<slug>.md 记录来源摘要与 SHA-256；wiki/concepts/<slug>.md 是概念页，含定义、置信度、来源计数、演化日志；wiki/entities/<slug>.md 是人物、工具、机构、论文页；wiki/synthesis/<topic>-synthesis.md 是综合分析；raw/personal/ 放个人写作，不创建 source 页，不计入 source_count。

置信度分三级：low 是 1-2 个来源或有矛盾；medium 是 3 个以上来源且信息一致；high 需要多元来源且无矛盾，属于候选值，必须经用户确认后才能设置。时效分三级：AI、加密货币、科技新闻 90 天判 stale，法律、商业、政策 180 天，数学、哲学、历史 365 天。

注册表与多知识库管理¶

全局注册表在 ~/.llm-wiki/registry.json，一个机器上可以有多个知识库：

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               # 获取最近访问的知识库

配合列表脚本使用：

python scripts/list-wikis.py            # 文本格式
python scripts/list-wikis.py --json     # JSON 供 Agent 解析
python scripts/list-wikis.py --path <名> # 获取指定知识库路径

铁律与注意事项¶

三层所有权的边界是这套系统的关键，四条铁律：LLM 绝不自动执行不可逆操作（merge、删除、把 confidence 升到 high），必须等人类确认；人类绝不手动编辑 wiki/ 下的内容页，所有编辑通过 LLM 完成；人类只负责 raw/ 的文件管理；模板文件带 graph-excluded: true，按模板新建的页面必须删掉这个字段。

实际使用中要注意几点：知识库的质量取决于 raw/ 的整理，原文乱则页面跟着乱；qmd 的 2GB 模型下载是一次性开销，网络受限时可以先跳过；wiki/ 一旦交给 LLM 维护，就不要再用编辑器直接改，否则 lint 的一致性检查会反复报警；模板里的 graph-excluded: true 忘了删，页面会从图谱里消失。

适合想把阅读笔记、剪藏、论文整理成长期可检索资产的人，尤其是希望 LLM 承担维护而非只做检索的团队。不适合需要严格版本控制或多人并发写入的场景，那部分要靠 raw/ 走 git 管理。

结尾¶

llm-wiki-builder 的价值不在检索速度，而在把「知识库如何组织」这件事固化成脚本和契约，让 LLM 去维护一个持续生长的制品。官方地址：https://api.skillhub.cn/user_7ffd653a/llm-wiki-builder