llm-wiki-agent

你有没有过这样的经历？读了一堆论文、博客、会议纪要，当时觉得记住了，过几天再用时——脑子一片空白。不是你不努力，而是人类大脑根本不适合存储碎片化信息。

LLM Wiki Agent 解决的正是这个痛点：它不是一个聊天机器人，而是一个由 AI 驱动的个人知识库引擎。你把各种文档丢进去，它自动阅读、提取知识、构建起一张互相联通的 Wiki 网。你只管往里扔资料，Wiki 自己会长出来。

图1：SamurAIGPT 个人主页

这个项目的设计灵感可以追溯到 1945 年 Vannevar Bush 提出的 Memex 概念——一种「扩展记忆」的机器。70 多年后，大语言模型终于让这个愿景变得可以落地。

---

项目背景与作者

LLM Wiki Agent 由独立开发者 SamurAIGPT 创建和维护，目前在 GitHub 上拥有约 2,800+ Stars，已被超过 100 个项目引用。项目采用 MIT 开源许可证，代码质量在同类工具中处于较高水准。

作者的核心观点是：大多数知识管理工具让你「搜索自己的笔记」，而 Wiki Agent 的逻辑完全不同——它不是在你的笔记里找答案，而是让 AI 代替你整理和写作。每新摄入一份资料，整个知识网络就会自动更新、补充和修正。

项目的技术实现上完全不依赖服务器和数据库，所有数据以纯 Markdown 文件存储在本地目录中，这意味着零锁定风险、数据完全可控、可以用 Git 做版本管理，与 Obsidian 等本地笔记工具无缝集成。

---

核心功能：知识摄入与 Wiki 生成

多格式自动摄入

用户只需把文件丢进 raw/ 目录，然后告诉 Agent 去「消化」它们。支持的格式非常广泛：文档类包括 Markdown、PDF、DOCX、PPTX、XLSX、HTML、TXT、CSV、JSON、XML、RST、EPUB、IPynb；媒体类支持 WAV、MP3 用于音频笔记转录。

非 Markdown 文件会在摄入时自动通过 markitdown 转换为 Markdown，整个过程对用户透明，无需手动操作。特别值得一提的是，项目针对 arXiv 学术论文 提供了专门的增强转换工具 tools/pdf2md.py，对于复杂排版（双栏 PDF）的学术文献，使用 Marker 后端可以获得更准确的转换效果。

自动生成的 Wiki 结构

摄入完成后，Agent 会在 wiki/ 目录下构建以下层级：sources/ 存放每个原始文档的摘要页，记录关键要点；entities/ 自动提取人名、公司名、项目名等实体页；concepts/ 存放提取的核心概念、框架、方法论；syntheses/ 保存用户查询结果的存档页面；overview.md 是全局概览页，每次摄入后自动更新；index.md 是全部 Wiki 页面的目录索引；log.md 是追加日志，记录每次操作。

每个 Wiki 页面使用 [[双括号链接]]（WikiLinks）互相引用，形成一个可导航的知识图谱，而非孤立的文档堆。这种结构设计让知识的发现从「主动搜索」变成了「顺藤摸瓜」。

---

知识图谱：超越 RAG 的关键差异

传统 RAG（检索增强生成）每次查询都要重新从原始文档中「捞」相关段落，LLM Wiki Agent 的设计哲学完全不同：

对比维度	传统 RAG	LLM Wiki Agent
知识表示	原始文档块	结构化 Wiki 页面
交叉引用	查询时动态发现	摄入时自动建立
矛盾检测	查询时可能发现	摄入时实时标记
知识积累	每次重新推导	持续沉淀和更新
隐含关系	依赖 LLM 即时推理	通过图谱边显式存储

项目内置的 Knowledge Graph 功能使用 NetworkX 构建图数据，利用 Louvain 社区检测算法将相关节点聚类，并生成一个完全自包含的 graph.html——无需任何服务器，在浏览器中打开即可看到交互式知识图谱可视化。图的构建采用双通道策略：确定性通道解析所有 Wiki 页面中的 [[wikilinks]] 生成 EXTRACTED 类型的边；语义推理通道由 Agent 推断 WikiLinks 未捕获的隐含关系，标记为 INFERRED 或 AMBIGUOUS，并附带置信度评分。

---

使用方式与上手门槛

Agent 模式（核心体验）

项目被设计为 AI 编码代理的「技能」使用。项目为不同的 Agent 提供了对应的 schema 文件：Claude Code 使用 CLAUDE.md，Codex / OpenCode 使用 AGENTS.md，Gemini CLI 使用 GEMINI.md。这些 schema 文件本质上是一套标准化的指令模板，告诉 AI Agent 如何维护 Wiki 的结构和流程。

打开项目后，直接用自然语言与 Agent 对话即可，例如输入 ingest raw/papers/attention-is-all-you-need.md 摄入论文，然后用 /wiki-query "主要的主题有哪些？" 查询，用 /wiki-lint 检查 Wiki 健康度，用 /wiki-graph 查看知识图谱。Claude Code 用户还可以使用内置的斜杠命令，如 /wiki-ingest、/wiki-query、/wiki-lint、/wiki-graph，进一步降低操作摩擦。

独立脚本模式（无 Agent 环境）

如果不想用编码 Agent，项目在 tools/ 目录下提供了独立的 Python 脚本（需要设置 ANTHROPIC_API_KEY）：tools/ingest.py 用于单文件摄入，tools/query.py 用于查询，tools/lint.py 用于 Wiki 健康检查，tools/build_graph.py 用于构建知识图谱，tools/health.py 提供轻量级结构检查（无需 LLM 调用）。

与 Obsidian 深度集成

项目专为 Obsidian 笔记软件优化，支持保险库符号链接模式：将 wiki/ 目录符号链接到 Obsidian 保险库，用户的 Wiki 内容会直接出现在 Obsidian 的图形视图中，获得原生图谱探索体验。建议在 Obsidian 中过滤掉 index.md 和 log.md 避免它们成为图谱重心。

---

技术架构

核心依赖： networkx 用于图结构构建与社区检测，markitdown 用于多格式文档转 Markdown，litellm 用于统一 LLM API 调用接口（已锁定 1.83.10+ 版本，规避 2026 年 3 月供应链攻击风险）。可选依赖包括 tqdm（批处理进度条）、marker-pdf（复杂 PDF 高保真转换）、arxiv2markdown（arXiv 论文结构化转换）。

项目采用 Python 3.10-3.13，通过 pyproject.toml 管理依赖。文件结构设计非常清晰：raw/ 存放原始资料（只读不修改），wiki/ 是 Agent 全权维护的 Wiki 层，graph/ 存放自动生成的知识图谱数据，tools/ 包含独立 Python 脚本，.claude/ 定义 Claude Code 斜杠命令。整个系统架构遵循「数据层 / 推理层 / 输出层」三层分离原则，扩展性良好。

---

局限与争议

1. 依赖 Agent 质量：Wiki 页面的质量直接取决于使用的 LLM 能力，不同模型生成的实体页和概念页质量差异较大，专业领域的术语提取有时不够准确。
2. 摄入成本：每次新文档摄入都需要 LLM 处理，长文档或大量资料时成本和时间消耗不可忽视，一个 50 页的 PDF 可能需要几分钟才能完成处理。
3. 没有原生 Web 界面：纯命令行工具，对非技术用户有一定门槛，需要熟悉终端操作。
4. 图谱规模敏感：当 Wiki 页面超过数百个时，图谱构建时间会显著增加，虽然 SHA256 缓存可以缓解，但首次构建仍较慢。
5. 与 Notion 等工具相比：缺少协作功能，更适合个人知识管理而非团队共享场景。

---

行业意义

在 RAG 大行其道的当下，LLM Wiki Agent 代表了一种不同的思路——不是用 RAG 做「检索」，而是用 Agent 做「整理和写作」。它的增长曲线与 AI Coding Agent 的普及高度相关：Agent 越强，Wiki 质量就越高。随着 Claude Code、Codex 等工具越来越强大，这个项目的价值天花板也在持续抬高。

如果把知识管理工具分为三代——第一代手动整理（Evernote/Notion）、第二代 RAG 检索（各种向量数据库）、第三代 AI 主动整理（Wiki Agent）——这个项目正处于第三代的开创性位置。

图2：项目 Star 历史增长曲线