LLM Wiki 实战：用 MCP 构建会自我维护的个人知识库

LLM Wiki 实战：用 MCP 构建会自我维护的个人知识库

摘要

资料越存越多，真正难的是持续整理、建立主题关联，并在之后找到来源。LLM Wiki 是一个开源的个人知识库项目：把 PDF、Office 文件、网页摘录和 Markdown 放进工作区，由 AI 通过 MCP 搜索资料、创建带来源引用的 Wiki 页面；本地模式把页面保存为普通 Markdown，索引保存在本机。

你可以从 Windows 本地安装开始，初始化自己的资料目录，再通过 MCP 连接 AI 助手，让它先检索来源、再尝试维护 Wiki 页面。操作时尤其要分清本地模式与托管模式的数据边界。

一、背景与问题

笔记、论文、网页剪藏和工作文档通常分散在不同文件夹。传统全文搜索可以找到关键词，却很难回答"哪些资料共同支持这个结论""哪些主题页需要因为新来源而更新"。手工维护 Wiki 又需要持续投入，常常在搭好目录后就停止更新。

LLM Wiki 把"来源资料"和"整理后的知识页面"分开：原始文件留在你指定的工作区；AI 通过 MCP 读取来源、搜索现有页面，并创建或更新带引用关系的 Markdown 页面。浏览器应用用于查看和管理知识库，Chrome 扩展可以剪藏网页与 PDF。

不要把自动生成的页面当成事实本身。模型可能遗漏来源、错误归纳或产生不准确引用；用它加速整理与检索时，重要结论仍要回到原始资料核对。

二、核心概念

1. 项目定位与许可证

先确认仓库：下面使用的是 lucasastorian/llmwiki，不是搜索结果中的其他同名或近名项目。项目 README 说明它受到 Andrej Karpathy 的 LLM Wiki 概念启发，并通过 MCP 让 Claude、Codex 等兼容客户端操作知识库。

仓库使用 Apache License 2.0。许可证允许在满足许可证条件的情况下使用、修改和分发；它不自动授予项目名称、标识等商标权。部署和再分发时应保留相应版权与许可证信息，并分别检查依赖和第三方内容的许可。

截至 2026-10-28，GitHub API 显示仓库默认分支为 master、近期仍有提交，GitHub Releases 页面没有可用的 latest release。因此下面从默认分支演示安装；如果用于生产或团队环境，先锁定经过验证的提交，不要把 master 当作稳定版本承诺。

2. 本地模式与托管模式

模式	主要存储	你会怎样使用	需要留意
本地	本机文件系统、SQLite 索引	在自己的电脑上管理来源文件	本地 API 仅绑定 127.0.0.1，不支持局域网或远程绑定
托管	项目架构说明中的 Postgres 与对象存储	通过远程服务访问知识库	需要按实际托管配置处理数据库、对象存储、凭据和网络边界

本地模式中，知识页面位于工作区的 wiki/，.llmwiki/ 保存索引数据库和缓存。README 说明原始来源文件不会被移动、修改或上传；但如果你把资料上传到托管服务，数据边界自然不同，必须按托管部署配置和隐私要求评估，不能把本地模式的承诺套用到云端。

3. MCP 在这里负责什么

MCP 是 AI 客户端访问知识库能力的接口。LLM Wiki 提供 guide、search、read、create、edit、append、delete、lint 等工具。读取、搜索用于查找知识；创建、编辑、追加和删除会改变知识库内容。连接 MCP 不只是"增加一个搜索框"，而是把受配置约束的读写能力交给客户端，因此要按工具权限和工作区范围审慎授权。

三、工作原理

本地模式的关键数据流可以概括为：

PDF / Office / Markdown / 网页剪藏
                 ↓
       工作区文件与内容抽取
                 ↓
      SQLite 索引与缓存 (.llmwiki)
                 ↓
AI 客户端 ── MCP ── search / read / create / edit / lint
                 ↓
       Wiki 页面写回工作区 wiki/
                 ↓
        文件监听器同步索引

README 描述的架构包含三类访问入口：MCP Server 服务 AI 客户端，API 服务 Web 应用和 Chrome 扩展，转换服务处理较重的 PDF/Office 内容抽取。底层 VaultFS 抽象让本地与托管模式使用相同的知识库操作，但持久化后端不同：本地使用 SQLite 与文件系统，托管模式使用 Postgres 与对象存储。

文件系统是本地模式的知识页面事实来源，搜索索引是为了快速检索而生成的数据。重建索引时要区分"可重建的索引"与"不能随意丢失的用户状态"：README 特别指出，高亮、评论、AI 回复、课程进度和剪藏元数据保存在 SQLite 索引库中。不要直接删除 .llmwiki/；先备份，再按项目提供的命令重建。

四、实战示例

打开 Windows PowerShell，先检查 Python、Node.js 与 Git。项目 README 要求 Python 3.11+、Node.js 20+；如果需要转换 Office 文件，还要安装 LibreOffice。

python --version
node --version
git --version

1. 获取项目并安装依赖

git clone https://github.com/lucasastorian/llmwiki.git
Set-Location .\llmwiki
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r api/requirements.txt -r mcp/requirements.txt
Set-Location .\web
npm install
Set-Location ..

如果 PowerShell 阻止虚拟环境激活，可以不改变执行策略，直接使用虚拟环境解释器运行 Python 命令：.\.venv\Scripts\python.exe。如果安装依赖失败，先根据错误确认 Python、Node 版本和网络依赖，不要直接使用管理员权限执行来源不明的脚本。

2. 初始化本地资料工作区

工作区应与源码仓库分开。例如建立一个只放个人资料的目录：

New-Item -ItemType Directory -Force -Path 'C:\Users\you\Documents\research-vault' | Out-Null
python .\llmwiki open 'C:\Users\you\Documents\research-vault'

按照 README，本地 CLI 会初始化该资料目录、建立索引、启动 API 和 Web 应用，并打开 http://localhost:3000。本地服务只绑定回环地址，不应通过端口转发或反向代理直接暴露到公网。资料目录里的原始文件保持原位置；项目创建 wiki/ 与隐藏的 .llmwiki/ 目录。

如果只需要测试 Web onboarding 页面，而不连接真实 API，可以在 web 目录使用项目提供的开发预览开关：

Set-Location .\web
$env:NEXT_PUBLIC_ONBOARDING_PREVIEW = 'true'
npm run dev

这是开发预览，不会创建真实知识库或写入 API 数据；改变开关后需要重新启动开发服务器。

3. 连接 MCP 客户端

在仓库根目录为该工作区生成 MCP 配置：

python .\llmwiki mcp-config 'C:\Users\you\Documents\research-vault'

命令会输出配置 JSON。按项目 README，把输出内容加入 Claude Desktop 的 claude_desktop_config.json，或 Claude Code 的 .claude/settings.json；每个工作区配置一个 MCP Server 条目。配置格式可能随项目和客户端版本变化，应以命令实际输出为准，不要照抄过期示例。连接后先让客户端调用 guide 了解工作区结构，再用 search、read 做只读验证，最后才授权 create 或 edit。

连接成功后，先发出一条只读验证任务：

先读取知识库 guide，列出可用知识库和资料目录。
只搜索"机器学习"，返回匹配来源的文件名与相关片段；
不要创建、修改或删除任何页面。回答时区分来源原文和你的归纳。

确认搜索结果能回到正确来源后，再试着创建一页小型概念总结，并通过页面引用检查确认引用目标存在。将删除工具留到明确需要且有备份的操作中。

4. 试用剪藏和定时维护

项目提供 Chrome 扩展用于剪藏网页和 PDF，并保存高亮与个人批注。README 描述扩展默认连接托管应用；本地使用时需要在扩展中切换到 Local，并连接运行中的本地工作区。安装扩展时只从项目 README 链接的 Chrome Web Store 页面或已审查的官方仓库构建物获取，不要安装来历不明的同名扩展。

项目 README 还展示了用 Claude Routine 定时读取新增来源并更新 Wiki 的工作流。定时任务运行在云端还是本机，取决于所选 Claude 产品能力。若使用云端定时任务，不能假设它能直接访问只存在于个人电脑的本地文件；应确认实际连接模式与数据访问路径，不要为绕过限制而开放本地 API 到公网。

五、常见问题与实践建议

1. 页面能打开，但 AI 客户端找不到 Wiki

确认 CLI 初始化和 MCP 配置使用的是同一个资料目录；检查 MCP 子进程命令、参数和工作目录是否可用。重新运行 mcp-config 生成当前配置，并从客户端的 MCP 诊断界面查看连接错误。避免同时配置多个指向不同目录的同名 Server。

2. PDF 或 Office 内容提取不完整

先检查文件是否为扫描件、是否含复杂表格或图片。项目 README 提到可设置 MISTRAL_API_KEY 提升部分复杂 PDF 的 OCR 效果；这是可选的外部服务凭据，会改变资料处理的数据边界。确认组织政策和服务条款后再使用。Office 文件转换需要本机 LibreOffice；没有安装时不要假设 Word/PPT 一定能完整提取。

3. 搜索索引与页面不同步

本地文件监听器会跟踪外部编辑并更新索引；如果索引异常，可使用项目 CLI 的 reindex 重建。重建前备份 .llmwiki/，因为其中不只有缓存，还包含剪藏批注等状态。不要把"重新生成索引"误认为"重置所有本地数据没有损失"。

4. AI 生成的知识页面引用不可靠

要求客户端在摘要中保留来源链接或引用标记，抽查引用是否确实支持结论；对日期、数字、医疗、法律和财务信息回到原始文档核实。lint 可以检查失效引用、悬空链接、孤立页等结构问题，但结构检查通过不等于事实正确。

5. 担心模型误删或覆盖页面

MCP 工具包含编辑和删除能力。将日常验证限制在只读搜索与读取；确需写入时先备份工作区并检查生成差异。把 wiki/ 纳入 Git 可以追踪 Markdown 页面变化，但 SQLite 中的剪藏状态仍应另行备份。避免把未经审查、带删除权限的 MCP Server 接入高价值资料库。

六、进阶思考

LLM Wiki 的设计价值不只是"用模型总结 PDF"，而是把来源、Wiki 页面、搜索索引和 AI 工具连接成可持续更新的知识循环。Markdown 文件降低了知识库的迁移成本；引用关系和 lint 则为知识维护提供了一些可检查结构。

团队落地时，首先要确定哪些资料允许进入知识库、哪些用户可以读写、生成页面由谁审批，以及托管模式的访问与备份策略。把 MCP 的读写能力按最小权限拆分、保留来源引用、定期备份原文件与索引状态，再用一组固定问题评估召回和引用质量，会比单纯追求"自动生成更多页面"更可靠。

结论

LLM Wiki 将你的资料目录、AI 助手和可编辑的 Markdown Wiki 串联起来：资料留在来源工作区，MCP 提供搜索与维护工具，索引帮助快速检索。如果你改用团队或托管部署，要重新审视存储、凭据、访问权限与自动化任务的数据路径。

先用少量非敏感资料建立本地工作区，完成只读 MCP 验证，再逐步启用页面写入和定时维护。把原始来源、生成内容与模型归纳区分开，才能让这座 Wiki 真正可追溯、可维护。

参考资料

• LLM Wiki GitHub 仓库
• LLM Wiki README
• LLM Wiki Apache-2.0 许可证
• Karpathy：LLM Wiki 概念说明
• Model Context Protocol：官方文档